Master Keybindings

This defines version 2.1 of the master keybinding file format. All changes (including breaking) are described below

Master keybindings are TOML files that begin with a line containing #:master-keybindings and include the following top-level fields:

• header: top-level properties of the binding file
• mode: array describing behavior of keybinding modes
• bind: an actual keybinding; extends the schema used by VSCode's keybindings.json
• define: object of arbitrary fields which can be used in computed arguments.

In addition, any comments prefixed with ## will show up in the documentation displayed by Master Key: Show Text Documentation. Any key bindings that fall between paragraphs of the literate documentation are combined and presented as a table of keybindings.

Example

Here's a minimal example, demonstrating the most basic use of each field

#:master-keybindings

## # My Key Bindings
##
## The binding file is a literate document. This text will show up in
## `Master Key: Show Text Documentation`

[header]
# this denotes the file-format version, it must be semver compatible with 2.0
version = "2.0.0"
name = "My Bindings"

[[mode]]
name = "insert"
# this comment will not show up in the documentation because it is prefixed
# with `#` instead of `##`.
whenNoBinding = 'insertCharacters'

[[mode]]
name = "normal"
default = true

[[kind]]
name = "motion"
description = "Commands that move your cursor"

[[kind]]
name = "mode"
description = "Commands that change the keybinding mode"

[[bind]]
key = "i"
doc.name = "insert"
mode = "normal"
command = "master-key.enterInsert"
doc.kind = "mode"

[[bind]]
key = "escape"
doc.name = "normal"
mode = "insert"
command = "master-key.enterNormal"
doc.kind = "mode"

[[define.bind]]
id = "basic_motion"
mode = "normal"
doc.kind = "motion"
command = "cursorMove"

[[bind]]
default = '{{bind.basic_motion}}'
doc.name = "right"
key = "l"
args.to = "right"

[[bind]]
doc.name = "left"
default = '{{bind.basic_motion}}'
key = "h"
args.to = "left"

[[define.val]]
foo = 1

[[bind]]
doc.name = "double right"
key = "g l"
default = '{{bind.basic_motion}}'
args.to = "right"
args.value = "{{foo+1}}"

Breaking Changes

2.1

The following, non-breaking changes were introduced in this version

• define.bind.before/after: Default binding definitions can now include a sequence of commands to execute before or after the command or commands executed with bind.command.

2.0

The following changes were made from version 1.0 of the file format.

• header.version is now 2.0
• [[define]] now has several sub fields. Definitions previously under [[define]] should usually go under [[define.val]], but also see [[define.command]].
• Comments prefixed with ## show up in literate documentation and all other comments are ignored. (Previously # showed up as literate documentation and #- was ignored).
• generalized expressions. This changed or replaced several other features:
  • bind.computedArgs no longer exists: instead, place expressions inside of args
  • bind.foreach has changed
    • {key: [regex]} is now {{keys(`[regex]`)}}
    • foreach variables are interpolated as expressions ({{symbol}} instead of {symbol}).
  • bind.path and [[path]]: A similar, but more explicit approach is possible using default and define.bind
  • replaced mode = [] with mode = '{{all_modes()}}'
  • replaced mode = ["!normal", "!visual"] with mode = '{{not_modes(["normal", "visual"])}}'
• revised several fields:
  • replaced prefixes = ["a", "b", ...] with prefixes.anyOf = ["a", "b", ...]
  • replaced prefixes = "<all-prefixes>" with prefixes.any = true
  • name, description, hideInPalette and hideInDocs moved to doc.name, doc.description, doc.hideInPalette and doc.hideInDocs
  • combinedName, combinedDescription and combinedKey moved to doc.combined.name, doc.combined.description and doc.combined.key.
  • resetTransient is now finalKey
  • bind.if replaced with bind.skipWhen
  • removed (re)storeNamed commands
  • replay-related command fields have changed their semantics, see examples under replayFromHistory

1.0

THis was the original file format version