Represents the configuration. It is a merged view of
- Default Settings
- Global (User) Settings
- Workspace settings
- Workspace Folder settings - From one of the {@link workspace.workspaceFolders Workspace Folders} under which requested resource belongs to.
- Language settings - Settings defined under requested language.
The effective value (returned by {@linkcode WorkspaceConfiguration.get get}) is computed by overriding or merging the values in the following order.
`defaultValue` (if defined in `package.json` otherwise derived from the value's type)
`globalValue` (if defined)
`workspaceValue` (if defined)
`workspaceFolderValue` (if defined)
`defaultLanguageValue` (if defined)
`globalLanguageValue` (if defined)
`workspaceLanguageValue` (if defined)
`workspaceFolderLanguageValue` (if defined)
Note: Only object
value types are merged and all other value types are overridden.
Example 1: Overriding
defaultValue = 'on';
globalValue = 'relative'
workspaceFolderValue = 'off'
value = 'off'
Example 2: Language Values
defaultValue = 'on';
globalValue = 'relative'
workspaceFolderValue = 'off'
globalLanguageValue = 'on'
value = 'on'
Example 3: Object Values
defaultValue = { "a": 1, "b": 2 };
globalValue = { "b": 3, "c": 4 };
value = { "a": 1, "b": 3, "c": 4 };
Note: Workspace and Workspace Folder configurations contains launch
and tasks
settings. Their basename will be
part of the section identifier. The following snippets shows how to retrieve all configurations
from launch.json
:
// launch.json configuration
const config = workspace.getConfiguration('launch', vscode.workspace.workspaceFolders[0].uri);
// retrieve values
const values = config.get('configurations');
Refer to Settings for more information.
Fields
update(section:String, value:Any, ?configurationTarget:EitherType<ConfigurationTarget, Bool>, ?overrideInLanguage:Bool):Thenable<Void>
Update a configuration value. The updated configuration values are persisted.
A value can be changed in
- {@link ConfigurationTarget.Global Global settings}: Changes the value for all instances of the editor.
- {@link ConfigurationTarget.Workspace Workspace settings}: Changes the value for current workspace, if available.
- {@link ConfigurationTarget.WorkspaceFolder Workspace folder settings}: Changes the value for settings from one of the {@link workspace.workspaceFolders Workspace Folders} under which the requested resource belongs to.
- Language settings: Changes the value for the requested languageId.
Note: To remove a configuration value use undefined
, like so: config.update('somekey', undefined)
@link ConfigurationTarget configuration target} or a boolean value.
- If `true` updates {@link ConfigurationTarget.Global Global settings}.
- If `false` updates {@link ConfigurationTarget.Workspace Workspace settings}.
- If `undefined` or `null` updates to {@link ConfigurationTarget.WorkspaceFolder Workspace folder settings} if configuration is resource specific,
otherwise to {@link ConfigurationTarget.Workspace Workspace settings}.
@link WorkspaceConfiguration} is not scoped to a resource.
Parameters:
section | Configuration name, supports dotted names. |
---|---|
value | The new value. |
configurationTarget | The { |
overrideInLanguage | Whether to update the value in the scope of requested languageId or not.
- If |
Throws:
error | while updating - configuration which is not registered. - window configuration to workspace folder - configuration to workspace or workspace folder when no workspace is opened. - configuration to workspace folder when there is no workspace folder settings. - configuration to workspace folder when { |
---|
inspect<T>(section:String):Null<{workspaceValue:Null<T>, workspaceLanguageValue:Null<T>, workspaceFolderValue:Null<T>, workspaceFolderLanguageValue:Null<T>, languageIds:Null<Array<String>>, key:String, globalValue:Null<T>, globalLanguageValue:Null<T>, defaultValue:Null<T>, defaultLanguageValue:Null<T>}>
Retrieve all information about a configuration setting. A configuration value often consists of a default value, a global or installation-wide value, a workspace-specific value, folder-specific value and language-specific values (if {@link WorkspaceConfiguration} is scoped to a language).
Also provides all language ids under which the given configuration setting is defined.
Note: The configuration name must denote a leaf in the configuration tree
(editor.fontSize
vs editor
) otherwise no result is returned.
Parameters:
section | Configuration name, supports dotted names. |
---|
Returns:
Information about a configuration setting or undefined
.
has(section:String):Bool
Check if this configuration has a certain value.
Parameters:
section | Configuration name, supports dotted names. |
---|
Returns:
true
if the section doesn't resolve to undefined
.