Configuration

A Configuration is a key-value storage that can be persistently saved on disk. Configurations are provided by the extension API for the user’s global preferences (see Environment) and Workspace preferences.

Keys in a configuration can optionally have a default value set by either the application or an extension. In this case, calls to get for a configuration that does not have an explicit value set will return the default value.

Methods

onDidChange(key, callback, [thisValue])

Adds an event listener that invokes the provided callback when a specific configuration key is changed. The callback will receive the new and old values of the key. Returns a Disposable object that can be used to cancel the event listener.

The optional thisValue argument may be used to set what this is bound to when the callable is invoked. If omitted, this will be undefined.

This method returns a Disposable that can be used to unregister the listener.

observe(key, callback, [thisValue])

Adds an event listener that invokes the provided callback when a specific configuration key is changed. The callback will receive the new and old values of the key. Similar to onDidChange(), except that this method immediate invokes the callback with the current value of the key. Returns a Disposable object that can be used to cancel the event listener.

The optional thisValue argument may be used to set what this is bound to when the callable is invoked. If omitted, this will be undefined.

This method returns a Disposable that can be used to unregister the listener.

get(key, [coerce])

Gets the current value of a key in the configuration. Returns null if no value and no default is set.

If the optional coerce argument is provided, the value can be automatically coerced to ensure a specific type. The following coercion types are supported:

• “string”: ensures that the value is a String, otherwise returning null
• “number”: ensures that the value is a Number, otherwise returning null
• “array”: ensures that the value is an Array of String, otherwise returning null
• “boolean”: ensures that the value is a Boolean, otherwise returning null

set(key, value)

Sets the value of the provided key in the configuration. If value is undefined, this will effectively remove the key from the configuration, returning it to its default value (if any).

This method will throw an Error if the provided value is not a String, Number, Boolean, Array of String, null, or undefined.

remove(key)

Removes the value for the provided key in the configuration, returning it to its default value (if any). This is effectively the same as passing undefined to the .set() method.