Binding Field bind

Example

[[bind]]
doc.name = "←"
key = "h"
mode = "normal"
command = "cursorLeft"

In the below field descriptions note that:

• ❗ denotes a required field.
• ⚡ denotes that a field can include runtime expressions

Fields

• ❗key: the keybinding that triggers command.

• ❗command: A string denoting the command to execute. This is a command defined by VSCode or an extension thereof. See finding commands. This field has special behavior when set torunCommands (see running multiple commands).

• ⚡ args: The arguments to directly pass to command. Args may include runtime evaluated expressions.

• when: A when clause context under which the binding will be active. Also see Master Key's available contexts

• mode: The key mode (or modes) for which the binding is active. Can be a string or an array of strings. The default mode is used when this field is not specified. When using an expression there are two available functions of use here: all_modes and not_modes

• priority: (default=0) The ordering of the keybinding relative to others when inserted into keybinding.json; determines which bindings trigger for a given key press. Higher priorities trigger over lower priorities because they are occur later in keybindings.json. Bindings with same priority are follow the same order as provided in the master key TOML file.

• default: the default values to use for fields, specified as a string of the form {{bind.[name]}}. See define for more details.

• foreach: Allows parametric definition of multiple keybindings, see foreach clauses.

• prefixes: (default prefixes.any=false) expresses the allowed key sequences that can occur before this keybinding. Explicit prefixes listed here should be define elsewhere with a master-key.prefix command or they will raise an error. The value is an object with only one of the following three keys:

  • any: when true any prefix defined elsewhere in the file is allowed before the binding. This includes the implicit prefixes of any other keybinding. false means no other key sequence can occur prior to this binding (this is the default behavior).
  • anyOf: A single string or an array of strings, each an allowed prefix
  • allBut: A single string or an array of strings; all prefixes except those specified here are valid

• finalKey: (default=true, unless master-key.prefix is one of the commands being run). Whether this key should clear any transient state associated with the pending keybinding prefix. See master-key.prefix for details.

• ⚡ repeat (default=0): The number of times to repeat the command; this can be a runtime expression. This defaults to zero: one repeat means the command is run twice. The most common use case here is to set this to '{{(max(key.count, 1))-1}}' for a command that does not accept a count value as an argument.

• tags: An array of strings used to characterize the behavior of the binding. They have no inherent meaning but are often used when filtering which commands in a call to master-key.replayFromHistory can be replayed.

• doc: Documentation for this keybinding. None of the fields of this object impact the behavior of the keybinding, only the interactive documentation features describing keybindings.

Documentation

The documentation object bind.doc is composed of the following fields

• name: (default='' unless binding is a prefix) A very brief description for the command; this must fit in the visual documentation of keybindings so it shouldn't be much longer than five characters for most keys. Favor unicode symbols such as →/← over text like left/right. For bindings that include master-key.prefix name defaults to prefix. This ensures that all key prefixes show up in documentation, thereby maintaining visibility of the suffixes' documentation.

• description: (default='') A sentence or two about the command. Save more detailed descriptions for the comments around your keybindings: the keybinding file is a literate document and all users can see these comments when reviewing the textual documentation.

• hideInPalette/hideInDocs: (default=false) whether to show the keys in the sidebar suggestions and the documentation. Note that if the name of a key is not defined it does not show up in the palette or documentation.

• combined.name/combined.key/combined.description: in the suggestion palette and textual documentation, keys that have the same combined.name will be represented as a single entry, using the combined.key and combined.description instead of key and description. The combined.key for a multi-key sequence should only include the suffix key. You need only define combined.key and combined.description once across keys that share the same combined.name entry.

• kind: The broad cagegory of commands this binding falls under. There should be no more than 4-5 of these. Each kind here should have a corresponding entry in the top-level kind array.

Running Multiple Commands

When bind.command is set to runCommands, you can run multiple commands with a single key press. Thebind.args.commands list is an array that can contain the following types:

• string: the name of the command to run
• object: describes the command to run
• an expression referencing a command {{command.[commandId]}}; this is a command defined in the [[define]] section.

The object fields are defined as follows:

• ❗command: as per the top level command field, this is the command you wish to run.

• ⚡ args: as per the top level args field. Can include runtime expressions.

• ⚡ skipWhen: (default=false) an expression evaluated at run-time. When true the command will not be run.

Finding Commands

You can find commands in a few ways:

• Find commands you want to use from the command palette, and click on the gear symbol (⚙︎) to copy the command string to your clipboard
• Review the list of built-in commands
• Run the command Preferences: Open Default Keyboard Shortcuts (JSON) to get a list of built-in commands and extension commands already associated with a keybinding

Furthermore, you can also use:

• Master Key Commands
• Selection Utility Commands

Selection Utilities is a complimentary extension used extensively by the Larkin preset.

Available when Contexts

Each keybinding can make use of any context defined in VSCode across any extension. Master Key adds the follow contexts:

• master-key.mode: the current keybinding mode
• master-key.count: The current count, as defined by master-key.updateCount
• master-key.captured: The text currently captured by the most recent call to master-key.captureKeys.
• master-key.prefix: The currently active keybinding prefix
• master-key.record: a boolean flag used to indicate when keys are marked for recording
• master-key.val.[name]: the current value of a defined variable.

foreach Clauses

The bind.foreach field of a keybinding can be used to generate many bindings from one entry. Each field under foreach should be an array. They are looped through exhaustively, creating a binding for each combination of values of the fields. For example, the following creates 9 bindings, for all possible combinations of the three values of a and b.

[[bind]]
foreach.a = [1,2,3]
foreach.b = [1,2,3]
key = "ctrl+; {{a}} {{b}}"
command = "type"
args.text = "{{a-b}}"

Furthermore, if an element of this array is a nested array, it is spliced into the array of values. This is commonly used to leverage the keys function available from expressions. For example, the following definition is used in Larkin to allow the numeric keys to be used as a count prefix for motions.

[[bind]]
foreach.num = ['{{keys(`[0-9]`)}}'] # matches all numeric keybindings
name = "count {{num}}"
key = "{{num}}"
command = "master-key.updateCount"
description = "Add digit {{num}} to the count argument of a command"
args.value = "{{num}}"
# etc...

Implementation detail for advanced readers

All expressions can include foreach variables, including expressions evaluated at run-time. Each instance of a foreach repeated binding has a local scope that resolves its foreach variables. The expression itself is then evaluated within this scope at read-time or run-time, depending on the field the expression is located in.