R: approach snippets in a more conventional VS Code way

[jennybc]

Currently ark provides, unconditionally, a fixed set of R snippets:

https://github.com/posit-dev/ark/blob/main/crates/ark/resources/snippets/r.code-snippets

Thoughts about how to improve this area:

• The existing snippets were ported from RStudio and, to some of us, contain a rather peculiar set of snippets. It feels like we might be on autopilot, maintaining something created a long time ago, without re-examining and curating it? I don't think these would be the top snippets we'd create if we were starting from scratch. Also the completion landscape has changed dramatically since these snippets were created, now that we've got a true LSP and also given code completion from LLMs.
• There's no way to turn the built-in ark snippets off. So there's no recourse if you find them to be a net negative to your completion life. And they do tend to show up near the top of the list, conceivably squatting on the coveted top spot.
• In RStudio, you either get the default snippets or your custom snippets. There is no combining of them. If you want custom snippets AND you like some of the default snippets, you copy those defaults into your custom snippets. We should at least consider this design for Positron as well. What I mostly mean is: maybe we should get out of the snippet business entirely, but we help people to develop their own custom snippets. For example, by providing some great example content when the user first start their own snippet file.
  • Personally, I never use any of the snippets that ark is currently providing and anecdotally this is also true for various colleagues I consulted. Instead, those of us who use snippets use custom ones we've created for ourselves.
• Currently, it is possible to augment the built-in snippets by using a VS Code mechanism. The entry point is Snippets: Configure Snippets in the command palette. That allows snippet customization at the user or workspace level, via a dedicated .code-snippets file (more below). These snippets appear to be combined with the snippet completions coming from the LSP. I can confirm that if you use "r" as the scope, these snippets are thrown into the mix along with those coming from ark.

Here is the initial content of a snippet file initiated with VS Code / Positron:

{
	// Place your r_testing workspace snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and 
	// description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope 
	// is left empty or omitted, the snippet gets applied to all languages. The prefix is what is 
	// used to trigger the snippet and the body will be expanded and inserted. Possible variables are: 
	// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. 
	// Placeholders with the same ids are connected.
	// Example:
	// "Print to console": {
	// 	"scope": "javascript,typescript",
	// 	"prefix": "log",
	// 	"body": [
	// 		"console.log('$1');",
	// 		"$2"
	// 	],
	// 	"description": "Log output to console"
	// }
}

Issue inspired by #7101 and general work on R completions.

[jennybc]

The official docs for snippets clarify the r.json file mentioned in #7101, vis-à-vis a .code-snippets file: https://code.visualstudio.com/docs/editing/userdefinedsnippets#_language-snippet-scope

Single-language user-defined snippets are defined in a specific language's snippet file (for example javascript.json), which you can access by language identifier through Snippets: Configure Snippets. A snippet is only accessible when editing the language for which it is defined.

Multi-language and global user-defined snippets are all defined in "global" snippet files (JSON with the file suffix .code-snippets), which is also accessible through Snippets: Configure Snippets. In a global snippets file, a snippet definition may have an additional scope property that takes one or more language identifiers, which makes the snippet available only for those specified languages. If no scope property is given, then the global snippet is available in all languages.

Most user-defined snippets are scoped to a single language, and so are defined in a language-specific snippet file.

[jennybc]

The Python extension contributes only 2 snippets, which is consistent with my hunch that perhaps positron-r / ark should provide no snippets (or almost none?):

positron/extensions/positron-python/snippets/python.code-snippets

Lines 1 to 12 in 6e40bda

	{
	"import <module>": {
	"prefix": "im",
	"body": "import ${1:module}$0",
	"description": "Import a package or module"
	},
	"from <module> import <names>": {
	"prefix": "from",
	"body": "from ${1:module} import ${2:names}$0",
	"description": "Import names from a package or module"
	}
	}

[dkaschek]

It would be great to see support for snippets with executable R code similar to RStudio. As an example, snippets in RStudio allow expressions like `r date()` to insert the current date into the output from the snippet. There are many more cases where R code in snippets helps creating more dynamic snippets.

[jennybc]

Since I'm advocating for the removal of built-in R snippets, that doesn't bode well for a feature request for even more capable R snippets.

I just want to note that VS Code and, therefore, Positron offer another snippet-y way of doing things like "insert the current date", e.g.:

https://mattferderer.com/create-a-snippet-or-shortcut-in-vs-code-to-insert-the-current-date-time

I think this is a great example of the benefits of building on VS Code: we get a lot of features "for free" and this could be one of them.

[jennybc]

If we remove built-in snippets from ark, we could still shape the user's experience of configuring R snippets by providing some examples. Here's where the content of a bare language-specific snippet file lives:

positron/src/vs/workbench/contrib/snippets/browser/commands/configureSnippets.ts

Lines 202 to 224 in 6af5bd8

	async function createLanguageSnippetFile(pick: ISnippetPick, fileService: IFileService, textFileService: ITextFileService) {
	if (await fileService.exists(pick.filepath)) {
	return;
	}
	const contents = [
	'{',
	'\t// Place your snippets for ' + pick.label + ' here. Each snippet is defined under a snippet name and has a prefix, body and ',
	'\t// description. The prefix is what is used to trigger the snippet and the body will be expanded and inserted. Possible variables are:',
	'\t// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. Placeholders with the ',
	'\t// same ids are connected.',
	'\t// Example:',
	'\t// "Print to console": {',
	'\t// \t"prefix": "log",',
	'\t// \t"body": [',
	'\t// \t\t"console.log(\'$1\');",',
	'\t// \t\t"$2"',
	'\t// \t],',
	'\t// \t"description": "Log output to console"',
	'\t// }',
	'}'
	].join('\n');
	await textFileService.write(pick.filepath, contents);
	}

Currently, the selected language just gets inserted for the pick.label placeholder, but you could imagine going beyond that. This initial content is not truly a configuration point, but Positron could feature 1 R and 1 Python example, instead of a javascript example.

[jennybc]

This appears to be the landscape for user-defined snippet files:

• A language-specific snippet file that is user-level. The language is conveyed by the file name via a language identifier.
  • Example path: ~/Library/Application Support/Positron/User/snippets/r.json
• A global snippet file, where "global" means "not scoped to a specific language", at the user-level. Language scope(s) can be optionally specified in the snippets themselves.
  • Example path: ~/Library/Application Support/Positron/User/snippets/jenny.code-snippets
• A global snippet file for a workspace.
  • Example path: PATH/TO/THE/WORKSPACE/ROOT/.vscode/SOMETHING.code-snippets