Expose API for variable substitution in contributed configuration

[rozzzly]

So now we have a bunch of variable substitutions we can use in .vscode/tasks.json

${workspaceFolder} - the path of the folder opened in VS Code
${workspaceFolderBasename} - the name of the folder opened in VS Code without any slashes (/)
${file} - the current opened file
${relativeFile} - the current opened file relative to workspaceFolder
${fileBasename} - the current opened file's basename
${fileBasenameNoExtension} - the current opened file's basename with no file extension
${fileDirname} - the current opened file's dirname
${fileExtname} - the current opened file's extension
${cwd} - the task runner's current working directory on startup
${lineNumber} - the current selected line number in the active file
${env:Name} - the `Name` variable from the environment
${config:Name} - example: ${config:editor.fontSize}
${command:CommandID} - example: ${command:explorer.newFolder}

But what if an extension wants to give the user the ability to use substitution for the configuration points it contributes, the extension developer has to implement that all themselves. While it is totally possible to support all of these substitutions, even inlined commands, from an extension the developer has to reinvent the wheel and maintain compatibility with future/past versions of VSCode.

It would be great if there was a way for an extension to make use of the existing variable substitution logic. Unfortunately, this is pretty deeply embedded into vscode and not something made readily accessible to extension developers.

I'm sure that there will be demand for custom substitutions and for limiting what kind of substitutions are allowed.

Really rough, but this is how something like this could look.

./package.json

"contributes": {
  "substitutions": {
    "prompt-debug.colorOfSky": {
      "description": "..."
    }
    "prompt-debug.binaryPath": {
      "description": "..."
    }
  },
  "configuration": {
    "properties": {
      "prompt-debug.autoResolveScript": {
        "description": "A javascript or typescript file which is exports a function named 'autoResolve' that resolves a file path to run.",
        "title": "Auto Resolve Script",
        "type": "string",
        "required": false,
		"substitutions": false, // substitutions disabled (default)
        "substitutions": "*", // allow all registered substitutions
		"substitutions": [
		  "*", // allow all registered substitutions
		  "-command:*" // exclude commands from substitutions
		  "command:explorer.newFolder" // with the exception of the newFolder command
		],
        "substitutions": [
    	  "substitution:prompt-debug.*" // allow all of the substitutions prompt-debug contributes
		  "-substitution:prompt-debug.binaryPath" // with the exception of binaryPath 
		]
	}
}

./src/extension.ts

export function activate(context: vscode.ExtensionContext) {
  vscode.substitutions.registerSubstitution('prompt-debug.colorOfSky', () => (Math.random() > 0.5) ? 'blue' : 'grey');
  vscode.substitutions.registerSubstitution('prompt-debug.binaryPath', async () => {
    const binaryPath = await someAsycStuff();
	if (binaryPath) return binaryPath;
    else return '/usr/bin/derp';
  });
}

Obviously vscode.workspace.getConfiguration().get('prompt-debug.autoResolveScript'); would have to be async because substitutions with commands can take a while to evaluate.. I have a few good ideas, but I'm tired of typing so we can bikeshed later if anyone is actually interested in this.. lol

[vscodebot]

(Experimental duplicate detection)
Thanks for submitting this issue. Please also check if it is already covered by an existing one, like:

• Suggest substitution variables when editing launch.json ans tasks.json (#41057)

[rozzzly]

Sorry bot, not quite.

[cheshirekow]

Hopping in here just to create a link to #23738 which was higher up in google search results, but was closed as a duplicate of an irrelevant bug. Hopefully this will save someone else some time in finding this issue.

[Trass3r]

How is this different from #2809?

[alexr00]

I'm looking at adding a variable resolving API that you would also be able to use in debug: #81007 (comment)
If that API happens, then this issue would also be resolved by it. Please give feedback on the API proposal if you have any!

Note that this API proposal doesn't open the door for contributing new substitutions, only for resolving ones that VS Code already supports in other places.

[hannah23280]

What is the current status for the suggestion to expose API for variable substitution? Eagerly hoping for such API to be exposed, so that in future the developer using vscode-java extension might be able to use variable expansion when declaring the java home path in the workspace setting rather than having to hardcode the actual path.

[DominicVonk]

Hi, I created a package to use predefined variables within your settings:

https://www.npmjs.com/package/vscode-variables

I will add other options later

[hannah23280]

Hi, I created a package to use predefined variables within your settings:

https://www.npmjs.com/package/vscode-variables

I will add other options later

Wau. Thanks a lot. Now many custom extensions could finally use this support variables in settings

[DominicVonk]

I added ${config:} as well, and recursive resolving.

[andyleejordan]

Just because I haven't commented here yet, throwing my vote out here for just how incredibly helpful this would be. Even just the basics of allowing us to opt in from configuration.get() to have the predefined variables resolved by VS Code for its own setting configurations!

I have at least five different issues in the PowerShell extension for VS Code stemming from the fact that users expect extension contributed settings to support the same variable expansions as built-in settings.

I'm sure that there will be demand for custom substitutions and for limiting what kind of substitutions are allowed.

As an extension author, I don't need this. Maybe others will, but I don't think we should stall getting basic support in for this possibility.

Obviously vscode.workspace.getConfiguration().get('prompt-debug.autoResolveScript'); would have to be async because substitutions with commands can take a while to evaluate.. I have a few good ideas, but I'm tired of typing so we can bikeshed later if anyone is actually interested in this.. lol

I also think it would be quite reasonable to omit ${command:CommandID} in order to keep get() synchronous. Again, that could be done later, but it's not even one of the predefined variables. Simply supporting that list would satisfy the vast majority of the use cases.

[tristan957]

I am trying to understand the best course of action here. Are extensions supposed to copy https://github.com/microsoft/vscode-python/blob/b68facc42f684f26c5f83f3cfe895e7aa4bb2bee/src/client/common/variables/systemVariables.ts and friends into their source tree?

[ramilmsh]

is there any update on this?

It's blocking bazel-contrib/vscode-bazel#132 , which i am quite anxious to see resolved

[ssbarnea]

As this bug is 6+ years old and I do not see any signs of being addressed... do we have that anyone managed to write some code that is flexible enough to be published as an npm package so extension authors can reuse it?

Apparently https://github.com/DominicVonk/vscode-variables by @DominicVonk is the best bet but considering that it was not touched in 4 years, it would require forking it to ensure it stays maintained.

[DominicVonk]

As this bug is 6+ years old and I do not see any signs of being addressed... do we have that anyone managed to write some code that is flexible enough to be published as an npm package so extension authors can reuse it?

Apparently DominicVonk/vscode-variables by @DominicVonk is the best bet but considering that it was not touched in 4 years, it would require forking it to ensure it stays maintained.

Hi @ssbarnea, I updated the package and added the long-awaited feature: ${command:...}. The variables method has become awaitable because of this. Please ask for support when needed!