Let openTextDocument create an untitled file with a specific file extension

[mjbvz]

Problem

Custom editors support untitled resources. However it is currently not easy to open these untitled resources with our existing APIs because the untitled resources need to have a specific file extension. Here's what I have to do today:

// Create untitled file
const newFileUri = vscode.Uri.file(path.join(vscode.workspace?.rootPath!, 'newFile.cscratch')).with({ scheme: 'untitled' });
await vscode.workspace.openTextDocument(newFileUri);

// Fill in initial content
const edit = new vscode.WorkspaceEdit();
edit.insert(newFileUri, new vscode.Position(0, 0), "{}");
await vscode.workspace.applyEdit(edit);

// Actually show the editor
vscode.commands.executeCommand('vscode.open', newFileUri);

This code works but is complex and fragile. For example, it breaks if a file called newFile.csratch already exists in the workspace

Proposal

In the version of openTextDocument that support untitled files, add a new optional parameter for the file extension:

export function openTextDocument(options?: { language?: string; content?: string; fileExtension?: string }): Thenable<TextDocument>;

This would be used when creating the new file name so that custom editors can correctly enable themselves for it

[bpasero]

@mjbvz currently the only way that an untitled file allows to configure the file extension to use is either by:

• providing the full associated path (as you already found out)
• setting a language mode from which we then offer the extension

As such, this change also needs to include a way for untitled files to configure a file extension. And I would think that we should then also determine the language mode from such extension if it is not otherwise provided.

I can review a PR, I cannot work on this in April though given sandbox duties.

[jrieken]

@mjbvz Did you try setTextDocumentLanguage? That should work with untitled documents...

[mjbvz]

Custom editors are enabled/disabled based on file names instead of language

[bpasero]

@mjbvz isn't it weird though to call openTextDocument and get a non-text-based custom editor potentially?

[mjbvz]

@bpasero openTextDocument would be used for CustomTextEditor since they are also based on TextDocument

This does bring up to how to handle custom binary editors however since they do not have a TextDocument. Some possible options on how to open an untitled CustomEditor:

• Leave this up to extensions. They would need to make sure they create a unique untitled file each time

• Add an api that creates a unique uri for an untitled files (with a file extension)

[jrieken]

Custom editors are enabled/disabled based on file names instead of language

You should be able to use the overload that takes an URI then, this:

vscode/src/vs/vscode.d.ts

Lines 8748 to 8766 in d778f85

	/**
	* Opens a document. Will return early if this document is already open. Otherwise
	* the document is loaded and the [didOpen](#workspace.onDidOpenTextDocument)-event fires.
	*
	* The document is denoted by an [uri](#Uri). Depending on the [scheme](#Uri.scheme) the
	* following rules apply:
	* * `file`-scheme: Open a file on disk, will be rejected if the file does not exist or cannot be loaded.
	* * `untitled`-scheme: A new file that should be saved on disk, e.g. `untitled:c:\frodo\new.js`. The language
	* will be derived from the file name.
	* * For all other schemes contributed [text document content providers](#TextDocumentContentProvider) and
	* [file system providers](#FileSystemProvider) are consulted.
	*
	* *Note* that the lifecycle of the returned document is owned by the editor and not by the extension. That means an
	* [`onDidClose`](#workspace.onDidCloseTextDocument)-event can occur at any time after opening it.
	*
	* @param uri Identifies the resource to open.
	* @return A promise that resolves to a [document](#TextDocument).
	*/
	export function openTextDocument(uri: Uri): Thenable<TextDocument>;

According to the doc, you call it like so: openTextDocument(vscode.Uri.parse('untitled:/foo/bazz.json')) and I would assume that it creates a JSON file

[bpasero]

Passing in vscode.Uri.parse('untitled:/foo/bazz.json') works fine but note that this assumes you want to save the file at /foo/bazz.json, that is, you will not be asked to provide a path when saving, it will just go there.

This maps to the concept of "associated file path" for untitled, e.g. starting code <some file that does not exist> from the command line.

[jrieken]

Slowly understanding what this is about... The proposal has potential for conflict, e.g what should win when language and extension are present. What has come up often, and that might be helpful for this, is to have utilities that map from an extension to a language id (and maybe also the other way around).

[kieferrm]

@mjbvz @eamodio is looking into adding a view type parameter vscode.open. Does that suffice?

[DonJayamanne]

@rebornix we have a similar situation in Notebooks.
Today we need the ability to create untitled notebooks with some default content.

Our solution:

• Generate a name for the untitled file as follows

const fileName = 'untitled-1.ipynb';
const newUri = Uri.file(fileName).with({ scheme: 'untitled', path: fileName });

• Next, we invoke openWith as follows:

commands.executeCommands('vscode.openWith', newUri, viewType);

• At this point, VS Code invokes our NotebookContentProvider.openNotebook, passing in the Uri we generated earlier for untitled file.
• Now we return the contents of this new untitled file to VSC.

Also, I'm not using the new command workbench.action.files.newUntitledFile for the following two reasons:

• We cannot pass default content
• Also the file extension is missing and at this point, there's no icon on the editor that's associated with the langauage (e.g. *.ipynb).

Please note, this isn't a blocker for us, I'm happy with our current solution, however @mjbvz solution does seem better if we could do the same for Notebooks.

[jrieken]

Adding @bpasero as the owner of untitled land

[bpasero]

@mjbvz this issue seems to get snow plowed for a while and I do not see it on the plan. My previous comment still holds true:

I can review a PR, I cannot work on this in April though given sandbox duties.

Let me know if you want to open a PR for me to review, otherwise I suggest to move this to Backlog.

[bpasero]

Thinking more about this, I feel having this on openTextDocument is actually the wrong layer, because you want to control which editor to open for the document, but nothing about the text document itself changes.

I would enrich the options you can pass into vscode.open to allow to specify the identifier of an editor to use, i.e. somewhat exposing the overrideId option to extensions when opening editors.

[mjbvz]

This issue is now outdated. Instead, we now allow extension to the contribute to the New File... menu to create a file of a specific type