All Topics

Compound Commands

In CodeRunner, you can create commands with advanced behaviors by using compound commands. A compound command is a procedural-style collection of commands written in JSON format.

Command Lists

A series of commands are supplied in a JSON list [], referred to as a command list. Command lists may be nested. Commands are supplied in quotes (as JSON strings) within the list. If the command name contains a colon :, the next element in the command list is an argument to this command, rather than a new command. If two colons appear in the command name, there are two arguments expected, etc. Example:

["moveLeft", "insertText:", "hello", "surroundSelectionWithString:endString:", "(", ")"]

In this example, the editor command moveLeft has no arguments, so the next element is interpreted as a new command. insertText: takes one argument, so the next element, "hello", is an argument to this command (i.e. the text to be inserted). surroundSelectionWithString:endString: takes two arguments. Note that all commands are quoted so as to be valid JSON. The most important commands are listed below, and you can discover all available commands by using the code completion facility when writing compound commands.

Tests

Some commands, referred to as tests, have a positive/negative return value associated with them. Tests typically begin with the words test or find. When a test appears in a command list and the test fails, the execution of the command list containing the test is aborted. No further commands are executed in this command list and the state of the document is restored to the state it was in before entering the failed command list. This means that any changes made to the state of the document (text content, selection, etc.) within the failed command list are discarded. If this behavior is undesired, for example when using find commands, use nested command lists.

If a test appears in the top-most command list of a compound command, and the test fails, the keystrokes that triggered the compound command are routed to other compound commands, if applicable, and if these fail, the default behaviors of the keystrokes are performed. If the top-most command list does not contain any tests or the tests are positive, the keystrokes are consumed by this compound command and further behaviors are suppressed.

Typically, a compound command begins with a few tests to check whether the command is applicable in the current context. This prevents it from being triggered in undesirable situations. A useful command for this purpose is testActiveSyntax:, which allows you to quickly check the syntax language at the current selection location. The test will fail if the current selection is inside of a string or comment. The argument should be a top level scope selector beginning with source or text. You can discover which scopes are active at the current selection in a document by using Text ‣ Show Color Scopes (⌃⌘P).

Objects

JSON objects {} may appear alongside command lists. If the root element of the JSON is an object rather than a command list, the compound command has multiple entry points of execution depending on what keystrokes are pressed. The object's keys refer to key equivalents as defined below, or alternatively, they are custom names which may be invoked manually by calls to callCompoundCommand: or includeCompoundCommand:. The associated values of the objects are always command lists. If an object appears inside of a command list, execution is paused at this point awaiting keystrokes from the user. The pressed keystrokes are checked against the object's keys and the associated command list is executed.

Key Equivalents

A key equivalent is a technical string that denotes a key combination. The string may be prefixed by a series of special characters representing modifier keys, followed by a single letter or symbol representing the pressed key. The following characters are used to represent modifier keys:

Examples of key equivalents:

For arrow keys, function keys, etc, use the appropriate Unicode escape sequence, such as "\uF700". These can be found here.

Some Important Commands

Discover all available commands by using the code completion facility when writing compound commands.

Control Flow

Interacting With the Document

Test Modifiers

Other

Multiple Selections

If a compound command is invoked when multiple selections are set, the compound command is executed separately for each selection.

The "Load" and "Unload" compound commands

A key binding set may optionally define compound commands titled "Load" and "Unload". The "Load" command is executed when a new document is instantiated or this key binding set is made active. This allows for any initialization operations that may be required by the key binding set. "Unload" is executed to reverse any setup done in "Load", for example when a different key binding set is chosen.

Examples

For examples, take a look at the numerous compound commands included in CodeRunner by default. View these under Preferences ‣ Key Bindings > (Global) Compound Commands. The "Vim" key binding set implements the majority of its functionality using compound commands.