$bindctl(FUNCTION <function> <action> [<args]>)
$bindctl(SEQUENCE <sequence> <action> [<args]>)
$bindctl(MAP [<sequence>] [<action>])

The bindctl function is a low level interface to the keybinding system. A FUNCTION is a thing that can be run when you press a key. A SEQUENCE is one or more unicode code points (“characters”) that you can type sequentially, which cause a FUNCTION to be executed when you type them. A MAP is a collection of SEQUENCES that begin with a common sub-sequence. The client comes with a variety of built-in FUNCTIONs, and you can create your own.

In each case, the first argument is the name of your function (“keybinding”) and the second argument is what you want to do with that keybinding. All operations return 1 for success and 0 or the empty string for failure, unless they say otherwise.

Create a new keybinding that will run the statement when it is invoked.

  $bindctl(FUNCTION name CREATE statement)

Destroy a keybinding you created with $bindctl(). You cannot destroy built-in keybindings.

  $bindctl(FUNCTION name DESTROY)

Test whether a keybinding exists – returns 1 for yes, 0 for no.

  $bindctl(FUNCTION name EXISTS)

Return the keybinding's action. If you created it with $bindctl(), it will return the statement you originally provided. If it is a built-in keybinding, it will return something like “Internal <address>”

  $bindctl(FUNCTION name GET)

Return the names of all keybindings whose names begin with string (ie, command-completion)

  $bindctl(FUNCTION string MATCH)

Return the names of all keybindings that match the pattern (which can contain wildcards)

  $bindctl(FUNCTION pattern PMATCH)

Return the package associated with the keybinding

  $bindctl(FUNCTION name GETPACKAGE)

Set the package associated with the keybinding

  $bindctl(FUNCTION name SETPACKAGE)

Bind the sequence “chars” to the given FUNCTION. Naturally, the FUNCTION must exist before you can bind anything to it. The args will be passed into the FUNCTION as $*. This is the same operation as /BIND chars function args. Most functions don't take an arg. The special function “NOTHING” will remove the binding.

  $bindctl(SEQUENCE chars SET function args)

Return the FUNCTION that is bound to the sequence chars. If the chars are not bound to a sequence, it will return the empty string (which means “nothing”)

  $bindctl(SEQUENCE chars GET)

Set the package associated with the sequence chars.

  $bindctl(SEQUENCE chars SETPACKAGE)

Get the package associated with the sequence chars.

  $bindctl(SEQUENCE chars GETPACKAGE)

Delete all keybindings that begin with chars. Be careful!

  $bindctl(MAP chars CLEAR)

Create a keybinding named “GREETINGS” that outputs “Hi there!”

  $bindctl(FUNCTION GREETINGS {echo Hi there!})

Bind Escape-g so it runs your new keybinding

  $bindctl(SEQUENCE ^[g GREETINGS)

Stop all this silliness

  $bindctl(SEQUENCE ^[g NOTHING)