Here we provide definitions for several commonly used Cursorless terms.
The action being performed on a target, such as
"chuck" (to delete),
"post" (to place your cursor after a target), etc.
The range containing the content of a target. This is the range that will be used when selecting a target, copying a target, as the source of a
"bring" command, etc.
The range within which a scope is valid/active. For example, the scope type
"key" is valid anywhere inside its containing key/value pair, and
"funk name" is valid anywhere inside its containing function.
A canonical range for a given scope type that defines a list of sibling scopes. For example, the iteration scope for
"arg" is an argument list. The iteration scope is used for things like
"every", to select all sibling scopes. This allows us to say things like
"take every arg",
"pre every line", etc.
The delimiter to be inserted before / after targets when inserting a new target. For example, for list items, the insertion delimiter is
Leading / trailing delimiter range
The leading delimiter range, if it exists, contains the delimiter before a target; the trailing delimiter range contains the delimiter after a target. For example, for a token with a hat over it, the trailing delimiter will be any whitespace after the token. For a function argument, it will be the trailing comma and any whitespace after the comma. Leading and trailing delimiters are used when constructing the removal range, and can also be targeted directly using the
A single position in a text document, consisting of
character numbers/indices. A position is equivalent to a zero-length range or zero-length selection. Examples of positions include a cursor position, the start of your selection, the end of a function, etc.
A single range in a text document. Consists of
end positions. Ranges have no direction, and
start is always before, or, in the case of an empty range, equal to
end. Examples of ranges include the range of a function, the whole document, a token with a hat over it, etc.
The range used when removing a target. This is generally the content range plus one of the leading or trailing delimiter ranges, if they exist for the given target. For example, for a function call argument, the removal range will include a leading or trailing comma and whitespace, so that saying
"chuck arg" or
"move arg" will clean up the comma.
A predefined pattern/structure that can appear in a text document. This could be textual, like
paragraph, or syntactic, like
class. Each scope type represents a way to view a text document in a structured manner, for example as a sequence of lines, or a hierarchy of statements (ie an
if statement containing series of variable declarations). Scope types allow us to say things like
"take funk" to select the function containing your cursor.
A concrete instance of a given scope type. For example, a particular function, line, or token in a text document.
The thing being operated on by a Cursorless command, such as a function, a line, a function parameter, etc. For example, in the command
"chuck funk", the target will be the function containing your cursor.