Values - egodigital/vscode-powertools GitHub Wiki

Values (or placeholders) can be used to define dynamic settings, e.g.

Create a values section to the settings.json file in the .vscode sub folder of your workspace and add one or more entry as key/value pairs:

{
    "ego.power-tools": {
        "values": {
            "buttonText": "My Button",
            "buttonTooltip": "This is a button, click it!",
            "currentTime": {
                "code": "new Date()",
                "type": "code"
            }
        },

        "buttons": [
            {
                "text": "That button is called: '${buttonText}'",
                "tooltip": "${buttonTooltip}",
                "action": {
                    "type": "script",
                    "script": "my_button.js"
                }
            }
        ]
    }
}

Create a my_button.js file in your .vscode folder and use the following skeleton:

exports.execute = async (args) => {
    // args => https://egodigital.github.io/vscode-powertools/api/interfaces/_contracts_.buttonactionscriptarguments.html

    // s. https://code.visualstudio.com/api/references/vscode-api
    const vscode = args.require('vscode');

    vscode.window.showInformationMessage(
        // you also can use values / placeholders
        // in all kind of scripts
        args.replaceValues('Now it is: ${currentTime}')
    );
};

Global values

Name	Description
`activeFile`	The full path to the file of the active editor. If no editor is open, an empty string is returned.
`appDir`	The (possible) path of folder with the apps, inside the `.vscode-powertools` subfolder of the current user's home directory.
`cwd`	The working directory of the current editor's process.
`EOL`	System's End-Of-Line char sequence.
`extensionDir`	The (possible) path of the `.vscode-powertools` subfolder inside the current user's home directory.
`homeDir`	Current user's home directory.
`hostName`	The system's hostname.
`tempDir`	The path of the directory with temp files.
`userName`	The user's name.

Also all environment variables of the current process will be available as (global) values.

Workspace values

Name	Description
`workspaceId`	The ID of the workspace.
`workspaceIndex`	The zero based index of the workspace folder.
`workspaceName`	The name of the workspace folder.
`workspaceRoot`	The root path of the workspace.
`workspaceUri`	The URI of the workspace folder.

Settings

You can define the value directly or define an object that supports the following properties:

Name	Description	Required?
`if`	(JavaScript) Code that checks if value is available or not. s. Conditional Settings	no
`platforms`	A list of one or more platform IDs, where the value should be available on. s. process.platform	no
`type`	The type. Current supports: `code` and `static`. Default: `static`	no

Code

Executes (JavaScript) code and uses its result as value.

{
    "ego.power-tools": {
        "values": {
            "currentTime": {
                "code": "new Date()",
                "type": "code"
            }
        }
    }
}

Name	Description	Required?
`code`	The (JavaScript) code to execute.	yes

Files

Loads data from a file.

{
    "ego.power-tools": {
        "values": {
            "currentTime": {
                "file": "./my_value_from_file.txt",
                "type": "file"
            }
        }
    }
}

Name	Description	Required?
`file`	The path to the file from where to load the file from. Relative paths will be mapped to the `.vscode` sub folder of the workspace or the `.vscode-powertools` sub folder inside the current user's home directory.	yes
`format`	The target (data) format to use. Default: `string`	no

format

Name	Description
`b64`, `base64`	Base64
`bin`, `binary`, `blob`, `buffer`	Buffer
`json`	Handle as JSON string
`str`, `string`	No conversion (string)

Scripts

Defines a script, what provides a value.

{
    "ego.power-tools": {
        "values": {
            "currentTime": {
                "script": "./my_value.js",
                "type": "script"
            }
        }
    }
}

A script has the following skeleton:

exports.getValue = (args) => {
    // args => https://egodigital.github.io/vscode-powertools/api/interfaces/_contracts_.scriptvaluearguments.html

    return args.require('moment')()
        .format('YYYY-MM-DD HH:mm:ss');
};

Name	Description	Required?
`options`	Options for the script.	no
`script`¹	The path to the script to execute. Relative paths will be mapped to the `.vscode` sub folder of the workspace or the `.vscode-powertools` sub folder inside the current user's home directory.	yes

^{1 supports placeholders}

Keep in mind that getValue() has to run synchronous!

Shell commands

Provides a value by running a shell command.

{
    "ego.power-tools": {
        "values": {
            "mailOfCurrentGitUser": {
                "command": "git config user.email",
                "type": "shell"
            }
        }
    }
}

Name	Description	Required?
`command`¹	The command to execute.	yes
`cwd`¹	The custom working directory.	no
`trim`	Trim result or not. Default: `(true)`	no