From e44a224c70900ca0a9d52ca3ac57cc80145c83e4 Mon Sep 17 00:00:00 2001 From: Andreas Arvidsson Date: Sun, 30 Aug 2026 04:10:58 +0200 Subject: [PATCH] Move the modifiers docs from README.md into separate reference markdown files --- packages/app-web-docs/src/docs/user/README.md | 339 +----------------- .../user/actions/setInstanceReference.mdx | 5 +- .../src/docs/user/modifiers/ancestor.mdx | 3 + .../docs/user/modifiers/containingScope.mdx | 2 + .../src/docs/user/modifiers/everyScope.mdx | 2 + .../user/modifiers/extendThroughEndOf.mdx | 2 + .../user/modifiers/extendThroughStartOf.mdx | 2 + .../docs/user/modifiers/inferPreviousMark.mdx | 3 + .../src/docs/user/modifiers/ordinalScope.mdx | 10 + .../src/docs/user/modifiers/relativeScope.mdx | 4 + .../docs/user/modifiers/toRawSelection.mdx | 5 + .../src/docs/user/modifiers/visible.mdx | 3 + .../src/docs/user/scopes/README.md | 2 +- .../scopes/boundedNonWhitespaceSequence.mdx | 2 + .../src/docs/user/scopes/boundedParagraph.mdx | 2 + .../src/docs/user/scopes/document.mdx | 2 + .../src/docs/user/scopes/identifier.mdx | 2 + .../src/docs/user/scopes/instance.mdx | 7 + .../src/docs/user/scopes/line.mdx | 2 +- .../user/scopes/nonWhitespaceSequence.mdx | 2 + .../src/docs/user/scopes/paragraph.mdx | 2 + .../src/docs/user/scopes/surroundingPair.mdx | 4 + .../src/docs/user/scopes/token.mdx | 2 + .../src/docs/user/scopes/word.mdx | 3 + .../src/references/actionReferences.ts | 10 +- .../src/references/modifierReferences.ts | 63 ++++ .../src/references/scopeReferences.ts | 45 ++- .../src/util/injectSpokenForm.ts | 2 +- 28 files changed, 188 insertions(+), 344 deletions(-) diff --git a/packages/app-web-docs/src/docs/user/README.md b/packages/app-web-docs/src/docs/user/README.md index 268ac482c9..69d82dc40d 100644 --- a/packages/app-web-docs/src/docs/user/README.md +++ b/packages/app-web-docs/src/docs/user/README.md @@ -139,344 +139,9 @@ The word `"up"` or `"down"` followed by a number can be used to refer to the lin #### Modifiers -Modifiers can be applied to any mark to modify its extent. This is commonly used to refer to larger syntactic elements within a source code document. +Modifiers change a target's extent or interpretation. See the [modifier reference](./modifiers/README.md) for the available modifiers and their detailed behavior. -Note that if the mark is `"this"`, and you have multiple cursors, the modifiers will be applied to each cursor individually. - -##### Syntactic scopes - -For programming languages where Cursorless has rich parse tree support, we support modifiers that expand to the nearest containing function, class, etc. See [the source code](../../../../../packages/lib-common/src/scopeSupportFacets/languageScopeSupport.ts) for a list of supported languages. Below is a list of supported scope types, keeping in mind that this table can sometimes lag behind the actual list. Your cheatsheet (say `"cursorless cheatsheet"` with VSCode focused) will have the most up-to-date list. It can also be helpful to use the [scope visualizer](./scope-visualizer.md) to visualize the scope types on your own code, though keep in mind that the scope visualizer only works on language scopes that have been upgraded to our next-gen scope engine, so it may not work every time. - -| Term | Syntactic element | -| -------------- | --------------------------------------------------- | -| `"arg"` | function parameter or function call argument | -| `"attribute"` | attribute, eg on html element | -| `"branch"` | branch of a `switch` or `if` statement | -| `"call"` | function call, eg `foo(1, 2)` | -| `"callee"` | the function being called in a function call | -| `"class name"` | the name in a class declaration | -| `"class"` | class definition | -| `"comment"` | comment | -| `"condition"` | condition, eg in an if statement, while loop etc | -| `"element"` | xml element | -| `"end tag"` | xml end tag | -| `"funk name"` | the name in a function declaration | -| `"funk"` | name function declaration | -| `"if state"` | if statement | -| `"item"` | an entry in a map / object / list | -| `"key"` | key in a map / object | -| `"lambda"` | anonymous lambda function | -| `"list"` | list / array | -| `"map"` | map / object | -| `"name"` | the name in a declaration (eg function name) | -| `"regex"` | regular expression | -| `"start tag"` | xml start tag | -| `"state"` | a statement, eg `let foo;` | -| `"string"` | string | -| `"tags"` | xml both tags | -| `"type"` | a type annotation or declaration | -| `"unit"` | a unit, eg `px` in `100px` | -| `"value"` | a value eg in a map / object, return statement, etc | - -For example, `"take funk blue air"` selects the function containing the token with a blue hat over the letter `'a'`. - -##### `"previous"` / `"next"` / `` / `` - -We support several modifiers that allow you to refer to scopes relative to the input target, or relative to the canonical iteration scope of the scope type. For example, the iteration scope of functions is a class, of tokens is a line, of characters is a token, etc. - -Here is a diagram of the possible relative / ordinal modifiers using the `funk` scope as an example: - -
- ![Relative ordinal diagram](images/relative_ordinal.png) -
- -([Image source](https://github.com/cursorless-dev/cursorless/blob/main/docs/user/images/relative_ordinal.tex)) - -And here is a table of the spoken forms: - -| Spoken form | Description | Example | -| ------------------------------ | ------------------------------------------------------------------- | ----------------------------- | -| `"[number] [scope]s"` | `[number]` instances of `[scope]` including target, going forwards | `"take three funks"` | -| `"[number] [scope]s backward"` | `[number]` instances of `[scope]` including target, going backwards | `"take three funks backward"` | -| `"[nth] [scope]"` | `[nth]` instance of `[scope]` in iteration scope | `"take third funk"` | -| `"[nth] last [scope]"` | `[nth]`-to-last instance of `[scope]` in iteration scope | `"take third last funk"` | -| `"[nth] next [scope]"` | `[nth]` instance of `[scope]` after target | `"take third next funk"` | -| `"[nth] previous [scope]"` | `[nth]` instance of `[scope]` before target | `"take third previous funk"` | -| `"first [number] [scope]s"` | First `[number]` instances of `[scope]` in iteration scope | `"take first three funks"` | -| `"last [number] [scope]s"` | Last `[number]` instances of `[scope]` in iteration scope | `"take last three funks"` | -| `"next [number] [scope]s"` | next `[number]` instances of `[scope]` | `"take next three funks"` | -| `"next [scope]"` | Next instance of `[scope]` | `"take next funk"` | -| `"previous [number] [scope]s"` | previous `[number]` instances of `[scope]` | `"take previous three funks"` | -| `"previous [scope]"` | Previous instance of `[scope]` | `"take previous funk"` | - -You can prefix the modifier with `"every"` to yield multiple targets rather than a range. For example, `"take every two tokens"` selects two tokens as separate selections. - -##### `"every"` - -The modifier `"every"` can be used to select a syntactic element and all of its matching siblings. - -- `"take every key air"` -- `"take every funk air"` -- `"take every key"` (if cursor is currently within a key) - -For example, the command `"take every key [blue] air"` will select every key in the map/object/dict including the token with a blue hat over the letter 'a'. - -###### Use with relative / ordinal modifiers - -The modifier `every` can also be used to cause [relative / ordinal modifiers](#previous--next--ordinal--number) to yield multiple targets rather than a range: - -- `"take every two tokens"` selects two tokens as separate selections -- `"pre every first two lines"` puts a cursor before each of first two lines in block (results in multiple cursors) - -##### `"grand"` - -The modifier `"grand"` can be used to select the parent of the containing syntactic element. - -- `"take grand statement air"` -- `"take grand funk air"` - -For example, the command `"take grand statement [blue] air"` will select the parent statement of the statement containing the token with a blue hat over the letter 'a'. - -You can also repeat `"grand"` multiple times. - -For example, the command `"take grand grand statement [blue] air"` will select the parent statement of the parent statement of the statement containing the token with a blue hat over the letter 'a'. - -##### Sub-token modifiers - -###### `"sub"` - -If you need to refer to the individual words within a `camelCase`/`snake_case` token, you can use the `"sub"` modifier. For example, - -- `"second sub air"` -- `"second past fourth sub air"` -- `"last sub air"` - -For example, the following command: - - "take second past fourth sub blue air" - -Selects the second, third and fourth word in the token containing letter 'a' with a blue hat. - -###### `"char"` - -You can also refer to individual characters within a token: - -- `"second char air"` -- `"second past fourth char air"` -- `"last char air"` - -##### `"line"` - -The word `"line"` can be used to expand a target to refer to entire lines rather than individual tokens: - -eg: -`take line [blue] air` -Selects the line including the token containing letter 'a' with a blue hat. - -##### `"block"` - -The `"block"` modifier expands to above and below the target to select lines until an empty line is reached. - -- `"take block"` -- `"take block "` - -##### `"short block"` - -The `"short block"` scope is like `"block"`, but in addition to stopping at empty lines, it will also stop at the boundary of a [surrounding pair](#surrounding-pair). -For example, given the text... - -``` -{ - aaa - { - bbb - ccc - } -} -``` - -`"take short block bat"` would select the two lines with `bbb` and `ccc`. See [short paint](#short-paint) for a more detailed walkthrough of a scope not exiting surrounding pairs. - -##### `"file"` - -The word '`"file"` can be used to expand the target to refer to the entire file. - -- `"copy file"` -- `"take file"` -- `"take file blue air"` - -For example, `"take file [blue] air"` selects the file including the token containing letter 'a' with a blue hat. - -##### `"visible"` - -The word `"visible"` refers to the currently visible content in the editor viewport, excluding any folded/collapsed regions. - -- `"take visible"` -- `"chuck visible"` - -This is useful for limiting operations to what's on screen. For example, `"from visible take every instance air"` will only match visible instances of the token with an 'a' hat, skipping matches hidden in folded regions or scrolled out of view. - -##### `"head"` and `"tail"` - -The modifiers `"head"` and `"tail"` can be used to expand a target through the beginning or end of the line, respectively. - -- `"take head"`: select from the cursor the start of the line -- `"take tail"`: select from the cursor to the end of the line -- `"take head air"`: selects the mark through to start of the line -- `"take tail air"`: selects the mark through to the end of the line - -When inside a surrounding pair (eg parentheses, brackets, etc) the head/tail modifier will only expand to the interior of that pair instead of the whole line. You can explicitly say `"head line"` or `"tail line"` to get the line behavior. - -When followed by a modifier, they will expand their input to the start or end of the given modifier range. For example: - -- `"take head funk"`: select from the cursor the start of the containing function -- `"chuck tail class air"`: Delete from the token with a hat over the letter `a` through the end of its containing class - -##### `"token"` - -The `"token"` modifier expands its input to the nearest containing token. This modifier is often used without a mark, either to select the token adjacent to your cursor or to expand your selection to the nearest containing token range. For example: - -- `"copy token"` -- `"take token"` -- `"chuck token"` - -##### `"identifier"` - -The `"identifier"` modifier behaves like `"token"`, but only considers tokens that are viable identifiers. For example `"identifier"` could be used to select `foo`, `fooBar`, or `foo_bar`, but not `.`, `=`, `+=`, etc. For example: - -- `"copy identifier"` -- `"take identifier"` -- `"chuck identifier"` - -This scope type is useful with ordinals, allowing you to say eg `"last identifier"` to refer to the last identifier on the current line. - -##### `"paint"` - -Both of the commands below will expand from the mark forward and backward to include all adjacent non-whitespace characters. - -- `"take paint"` -- `"take paint "` - -For example, in the following text: - -``` -foo.bar baz|bongo -``` - -Saying `"every paint"` would select `foo.bar` and `baz|bongo`. - -##### `"short paint"` - -The `"short paint"` scope is like `"paint"`, but in addition to stopping at whitespace, it will also stop at the boundary of a [surrounding pair](#surrounding-pair). For example, given the text - -``` -(aaa[bbb]ccc ddd) -``` - -- `"take short paint air"` would select `aaa[bbb]ccc`. - - The target starts as `aaa`. - - Trying to expand to the left, we immediately hit a `(`, which is part of a paren pair that surrounds the original `aaa`, so that stops leftward expansion. - - Trying to expand to the right, we hit a `[`, and that pair of square brackets does not surround the original `aaa`, so rightward expansion continues. - - Rightward expansion continues over the `ccc`, then hits a space and stops. -- `"take short paint square"` would select `aaa[bbb]ccc`. - - The target starts as `[`. - - The expansion is not stopped by either the square brackets because they do not surround themselves. -- `"take short paint bat"` would select `bbb`. - - The target starts as `bbb`. - - The expansion is stopped by the square packets that surround `bbb`. - -##### `"instance"` - -The `"instance"` modifier searches for occurrences of the text of the target. For example: - -- `"take every instance air"`: selects all instances of the token with a hat over the letter `a` in the whole document -- `"take two instances air"`: selects the first two instances of the token with a hat over the letter `a`, starting from that token itself -- `"take next instance air"`: selects the next instance of the token with a hat over the letter `a`, starting from that token itself -- `"chuck every instance two tokens air"`: deletes all occurrences of the two tokens beginning from the token with a hat over the letter `a`. For example if there were a hat over the `a` in `aaa.bbb`, it would delete every occurrence of `aaa.` in the file. -- `"take every instance air past bat"`: if there were hats over the `a` and `b` in `aaa ccc bbb ddd`, it would selects all occurrences of `aaa ccc bbb` (which is the text corresponding to the range `"air past bat"`) - -Note in the final example how the `"instance"` modifier constructs the instance based on the range `"air past bat"`, rather than the individual tokens `"air"` and `"bat"`, as you might expect given the way other modifiers behave. Effectively `"instance"` applies to everything after the `"instance"` modifier, rather than just the next modifier. - -Note also that `"instance"` considers the type of target used to construct the instance. So for example, `"take every instance air"` will only select tokens that -are identical to the token with a hat over the letter `a`, skipping over bigger tokens that contain the token with a hat over the letter `a` as a substring. For example, if there were a hat over the `a` in `aaa`, it would select every occurrence of `aaa` in the file, but not `aaaaa`. If you want to avoid this behaviour, you can -use the `"just"` modifier, eg `"take every instance just air"`. - -If your cursor is touching a token, you can say `"take every instance"` to select all instances of the given token, (or `"chuck two instances"` to delete the token and its next occurrence, `"pre next instance"` to place your cursor before the next occurrence, etc). - -Pro tip: if you say eg `"take five instances air"`, and it turns out you need more, you can say eg `"take that and next two instances that"` to select the next two instances after the last instance you selected. - -###### `"from"` - -We have support for prefixing a command with `"from "` to narrow the range within which `"every instance"` searches, or to set the start point from which `"next instance"` searches. For example: - -- `"from funk take every instance air"`: selects all instances of the token with a hat over the letter `a` in the current function -- `"from air take next instance bat"`: selects the next instance of the token with a hat over the letter `b` starting from the token with a hat over the letter `a` - -Note that the `"from"` modifier was not enabled by default on older Cursorless installations; you must remove the `-` at the start of the line starting with `-from` in your `experimental/experimental_actions.csv` [settings csv](./customization.md). - -##### `"just"` - -The `"just"` modifier strips the target of any semantic information, treating it as just a raw range, with the following effects: - -- The new target has no leading or trailing delimiters. For example: - - `"chuck just air"` will delete just the air token, leaving adjacent spaces undisturbed, unlike the default behaviour of `"chuck air"` that deletes the air token _and_ cleans up adjacent whitespace as appropriate. Ie for - - ``` - bbb aaa ccc - ``` - - `"chuck just air"` would result in `bbb ccc` (note the double space in the middle), whereas `"chuck air"` would result in `bbb ccc`. - - - `"chuck just line"` will delete only the content of the current line, without removing the line ending, resulting in a blank line, unlike the default behaviour of `"chuck line"` that removes the line entirely, leaving no blank line. - -- A raw range does not have its own insertion delimiters. - - For example, `"paste after just air"` will paste directly after the air token, without inserting a space, as opposed to the way `"paste after air"` would insert a space before the pasted content. - - If you use `"just"` on the destination of a `"bring"` command, it will inherit its insertion delimiters from the source of the `"bring"` action. For example, in the command `"bring arg air and bat after just paren"`, the `"air"` and `"bat"` arguments will be joined by commas. In contrast, `"bring arg air and bat after token paren"` would join the arguments with spaces. -- In the case of [`"instance"`](#instance), by default `"every instance air"` will only consider instances of the air token that are themselves full tokens, but `"every instance just air"` doesn't have such a restriction, because we've stripped air of its semantic "token-ness". - -Some examples: - -- `"chuck just air"`: deletes just the air token, leaving spaces undisturbed. -- `"chuck just line"`: deletes just the content of the line, leaving a blank line. -- `"bring bat after just air"`: results in something like `aaabbb` where the bat token was copied after the air token with no delimiter between them. - -##### Surrounding pair - -Cursorless has support for expanding the selection to the nearest containing paired delimiter, eg the surrounding parentheses, curly brackets, etc. - -- `"take round"` expands selection to include containing parentheses `(` and `)` -- `"take curly"` expands selection to include containing braces `{` and `}` -- `"take box"` expands selection to include containing brackets `[` and `]`. See [paired delimiters](./paired-delimiters.md) for other possible surrounding pairs. -- `"take inside round"` is the same as `"take round"`, but excludes the parentheses themselves -- `"take bounds round"` selects only the parentheses -- `"take pair"` expands to include the nearest containing pair of any kind -- `"take bounds"` selects the nearest containing paired delimiters themselves of any kind -- `"take inside"` selects until the nearest containing paired delimiters of any kind, but doesn't include the delimiters themselves -- `"take round air"` selects the parentheses containing the token with a hat over the `a`. - -See [paired delimiters](./paired-delimiters.md) for a list of possible surrounding pairs. - -###### Ambiguous delimiters (`"`, `'`, `` ` ``, etc) - -For some delimiter pairs, the opening and closing delimiters are the same character, eg `"`, `'`, and `` ` ``. In this case, cursorless somehow needs to determine whether a given instance of the character is an opening or closing delimiter. When we have access to a parse tree, such as in typescript or python, this is not a problem, because we can reliably determine whether a quotation mark is an opening or closing delimiter based on its position in the parse tree. - -However, when we are in a language where we don't have access to a parse tree, such is in a plaintext or markdown file, or within a comment or string within a parsed language, it is not possible to reliably determine whether we are looking at an opening or closing delimiter. - -In this case, we resort to a simple heuristic to determine whether a character is an opening or closing delimiter: we consider the first instance of the given delimiter on a line to be an opening delimiter, and every subsequent delimiter alternates between being treated as an opening and closing delimiter. For example: - -``` -This is a "line with" a few "quotation marks" on it - ↑ ↑ ↑ ↑ - opening closing opening closing -``` - -##### `"its"` - -The the modifier `"its"` is intended to be used as part of a compound target, and will tell Cursorless to use the previously mentioned mark in the compound target. - -For example, `"take air past end of its line"` selects the range from the token containing letter `a` to the end of the line containing the same token. This is in contrast from `"take air past end of line"` which selects the range from the token containing letter `a` to the end of the line containing the current selection. - -Another example is `"bring air to its value"`, which would cause the token with a hat over `a` to replace the return value containing it. +Scopes expand a target to a containing text or syntax-tree structure. See the [scope reference](./scopes/README.md) for the available scopes, and use the [scope visualizer](./scope-visualizer.md) to explore the scopes supported in your code. ### Compound targets diff --git a/packages/app-web-docs/src/docs/user/actions/setInstanceReference.mdx b/packages/app-web-docs/src/docs/user/actions/setInstanceReference.mdx index de32ea7b79..cd2065722a 100644 --- a/packages/app-web-docs/src/docs/user/actions/setInstanceReference.mdx +++ b/packages/app-web-docs/src/docs/user/actions/setInstanceReference.mdx @@ -4,7 +4,9 @@ sidebar_label: From # From (Set instance reference) -Sets the instance reference for the next 'instance of' action. +Sets the instance reference. This restricts the next instance search to a target. With `"every instance"`, the target defines the region to search; with `"next instance"`, it defines the position where the search begins. + +Older Cursorless installations may have `"from"` disabled. Remove the leading `-` from its entry in `experimental/experimental_actions.csv` to enable it; see the [settings CSV documentation](../customization.md). Cursorless ID: `experimental.setInstanceReference` @@ -19,3 +21,4 @@ Default: `from` ## Examples - `"from funk blue air take every instance green bat"` - Selects every instance of the token containing letter 'b' with a green hat within the function containing the token containing letter 'a' with a blue hat. +- `"from blue air take next instance green bat"` - Selects the next instance of the token containing letter 'b' with a green hat, searching from the token containing letter 'a' with a blue hat. diff --git a/packages/app-web-docs/src/docs/user/modifiers/ancestor.mdx b/packages/app-web-docs/src/docs/user/modifiers/ancestor.mdx index 16274b1fca..93afbd4ea9 100644 --- a/packages/app-web-docs/src/docs/user/modifiers/ancestor.mdx +++ b/packages/app-web-docs/src/docs/user/modifiers/ancestor.mdx @@ -4,6 +4,8 @@ sidebar_label: Grand # Grand (Ancestor) +Selects the parent of a containing scope. Repeat `"grand"` to walk up more than one parent level. + Cursorless ID: `ancestor` ## Spoken form @@ -17,3 +19,4 @@ Default: `grand` ## Examples - `"take grand state blue air"` - Selects the parent statement of the statement containing the token containing letter 'a' with a blue hat. +- `"take grand grand state blue air"` - Selects the grandparent statement of the statement containing the token containing letter 'a' with a blue hat. diff --git a/packages/app-web-docs/src/docs/user/modifiers/containingScope.mdx b/packages/app-web-docs/src/docs/user/modifiers/containingScope.mdx index 7af3046aa1..4915374d70 100644 --- a/packages/app-web-docs/src/docs/user/modifiers/containingScope.mdx +++ b/packages/app-web-docs/src/docs/user/modifiers/containingScope.mdx @@ -1,5 +1,7 @@ # Containing scope +Expands a target to the containing instance of a scope. When the input is `"this"` with multiple selections, Cursorless expands each selection independently. + Cursorless ID: `containingScope` ## Syntax diff --git a/packages/app-web-docs/src/docs/user/modifiers/everyScope.mdx b/packages/app-web-docs/src/docs/user/modifiers/everyScope.mdx index 3bfe6380aa..9d895c79a8 100644 --- a/packages/app-web-docs/src/docs/user/modifiers/everyScope.mdx +++ b/packages/app-web-docs/src/docs/user/modifiers/everyScope.mdx @@ -4,6 +4,8 @@ sidebar_label: Every # Every (Every scope) +Selects all matching sibling scopes. It can also prefix an ordinal or relative modifier to return separate targets instead of one contiguous range. + Cursorless ID: `everyScope` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/modifiers/extendThroughEndOf.mdx b/packages/app-web-docs/src/docs/user/modifiers/extendThroughEndOf.mdx index 2a80d44fde..4f5a7b7b6d 100644 --- a/packages/app-web-docs/src/docs/user/modifiers/extendThroughEndOf.mdx +++ b/packages/app-web-docs/src/docs/user/modifiers/extendThroughEndOf.mdx @@ -4,6 +4,8 @@ sidebar_label: Tail # Tail (Extend through end of) +Extends a target through the end of its line. Inside a surrounding pair, it stops at the end of the pair's interior; use an explicit scope such as `"tail line"` to override that boundary. + Cursorless ID: `extendThroughEndOf` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/modifiers/extendThroughStartOf.mdx b/packages/app-web-docs/src/docs/user/modifiers/extendThroughStartOf.mdx index 7d6d9edc64..fa28f63176 100644 --- a/packages/app-web-docs/src/docs/user/modifiers/extendThroughStartOf.mdx +++ b/packages/app-web-docs/src/docs/user/modifiers/extendThroughStartOf.mdx @@ -4,6 +4,8 @@ sidebar_label: Head # Head (Extend through start of) +Extends a target through the start of its line. Inside a surrounding pair, it stops at the start of the pair's interior; use an explicit scope such as `"head line"` to override that boundary. + Cursorless ID: `extendThroughStartOf` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/modifiers/inferPreviousMark.mdx b/packages/app-web-docs/src/docs/user/modifiers/inferPreviousMark.mdx index 755de115d8..078e256c22 100644 --- a/packages/app-web-docs/src/docs/user/modifiers/inferPreviousMark.mdx +++ b/packages/app-web-docs/src/docs/user/modifiers/inferPreviousMark.mdx @@ -4,6 +4,8 @@ sidebar_label: Its # Its (Infer previous mark) +Within a compound target, applies the following modifier to the previously mentioned mark. Without `"its"`, an implicit target such as `"line"` is resolved relative to the current selection instead. + Cursorless ID: `inferPreviousMark` ## Spoken form @@ -17,3 +19,4 @@ Default: `its` ## Examples - `"take blue air past end of its line"` - Selects from the token containing letter 'a' with a blue hat through the end of the line containing that token. +- `"bring blue air to its value"` - Replaces the value containing the token containing letter 'a' with a blue hat with that token. diff --git a/packages/app-web-docs/src/docs/user/modifiers/ordinalScope.mdx b/packages/app-web-docs/src/docs/user/modifiers/ordinalScope.mdx index ad880f5771..38abda6d09 100644 --- a/packages/app-web-docs/src/docs/user/modifiers/ordinalScope.mdx +++ b/packages/app-web-docs/src/docs/user/modifiers/ordinalScope.mdx @@ -1,5 +1,15 @@ # Ordinal scope +The iteration scope depends on the scope type. For example, functions iterate within a class, tokens within a line, and characters within a token. + +Without `"every"`, plural ordinal forms produce one contiguous range. Prefix them with `"every"` to produce separate targets instead. + +
+ +![Relative and ordinal modifier diagram](../images/relative_ordinal.png) + +
+ Cursorless ID: `ordinalScope` ## Syntax diff --git a/packages/app-web-docs/src/docs/user/modifiers/relativeScope.mdx b/packages/app-web-docs/src/docs/user/modifiers/relativeScope.mdx index e1c4f0ffeb..609c92fb07 100644 --- a/packages/app-web-docs/src/docs/user/modifiers/relativeScope.mdx +++ b/packages/app-web-docs/src/docs/user/modifiers/relativeScope.mdx @@ -1,5 +1,9 @@ # Relative scope +The iteration scope depends on the scope type. For example, functions iterate within a class, tokens within a line, and characters within a token. + +Relative modifiers select scopes before or after the input target. Without `"every"`, plural forms produce one contiguous range; prefix them with `"every"` to produce separate targets instead. + Cursorless ID: `relativeScope` ## Syntax diff --git a/packages/app-web-docs/src/docs/user/modifiers/toRawSelection.mdx b/packages/app-web-docs/src/docs/user/modifiers/toRawSelection.mdx index 8981c64633..c3f3b2f9c7 100644 --- a/packages/app-web-docs/src/docs/user/modifiers/toRawSelection.mdx +++ b/packages/app-web-docs/src/docs/user/modifiers/toRawSelection.mdx @@ -4,6 +4,8 @@ sidebar_label: Just # Just (Raw selection) +Strips semantic information from a target and treats it as a raw range. Cursorless will not use the target's removal delimiters, insertion delimiters, or scope type. This means deletion leaves adjacent whitespace and line endings untouched, insertion adds no automatic separator, and instance matching is not restricted to targets of the original scope type. When a raw target is the destination of a `"bring"` command, it inherits insertion delimiters from the source. + Cursorless ID: `toRawSelection` ## Spoken form @@ -17,3 +19,6 @@ Default: `just` ## Examples - `"chuck just blue air"` - Deletes only the token containing letter 'a' with a blue hat, leaving adjacent whitespace unchanged. +- `"chuck just line"` - Deletes only the line content, leaving its line ending and therefore a blank line. +- `"paste after just blue air"` - Pastes directly after the token containing letter 'a' with a blue hat without inserting a separator. +- `"take every instance just blue air"` - Selects every matching text occurrence of the token containing letter 'a' with a blue hat, including occurrences that are not full tokens. diff --git a/packages/app-web-docs/src/docs/user/modifiers/visible.mdx b/packages/app-web-docs/src/docs/user/modifiers/visible.mdx index 87b4904bb6..86b4a22483 100644 --- a/packages/app-web-docs/src/docs/user/modifiers/visible.mdx +++ b/packages/app-web-docs/src/docs/user/modifiers/visible.mdx @@ -4,6 +4,8 @@ sidebar_label: Visible # Visible +Limits a target to content currently visible in the editor viewport, excluding folded regions and content scrolled off screen. This is especially useful with the `"from"` action when searching for instances. + Cursorless ID: `visible` ## Spoken form @@ -17,3 +19,4 @@ Default: `visible` ## Examples - `"take visible"` - Selects the content currently visible in the editor viewport. +- `"from visible take every instance blue air"` - Selects the visible instances of the token containing letter 'a' with a blue hat, excluding matches that are folded or outside the viewport. diff --git a/packages/app-web-docs/src/docs/user/scopes/README.md b/packages/app-web-docs/src/docs/user/scopes/README.md index 96ed583c78..ae43124999 100644 --- a/packages/app-web-docs/src/docs/user/scopes/README.md +++ b/packages/app-web-docs/src/docs/user/scopes/README.md @@ -7,7 +7,7 @@ - [`"token"`](./token.mdx) - Token such as a word, number, or operator. - [`"identifier"`](./identifier.mdx) - Identifier-style sequence, such as camelCase, snake_case, or kebab-case. - [`"sentence"`](./sentence.mdx) - Text ending at sentence punctuation or a paragraph boundary. -- [`"line"`](./line.mdx) - Line, without indentation. +- [`"line"`](./line.mdx) - Line, excluding indentation. - [`"full line"`](./fullLine.mdx) - Full line, including indentation. - [`"block"`](./paragraph.mdx) - Paragraph, contiguous non-empty lines around the target. - [`"short block"`](./boundedParagraph.mdx) - Paragraph bounded by surrounding pair delimiters. diff --git a/packages/app-web-docs/src/docs/user/scopes/boundedNonWhitespaceSequence.mdx b/packages/app-web-docs/src/docs/user/scopes/boundedNonWhitespaceSequence.mdx index 9f0c0da337..a65a0b2cd4 100644 --- a/packages/app-web-docs/src/docs/user/scopes/boundedNonWhitespaceSequence.mdx +++ b/packages/app-web-docs/src/docs/user/scopes/boundedNonWhitespaceSequence.mdx @@ -6,6 +6,8 @@ import { Scopes } from "@site/src/docs/components/Scopes"; # Short paint (Bounded non-whitespace sequence) +Like `"paint"`, but expansion also stops at a delimiter pair that surrounds the input target. Delimiter pairs that do not surround the original target do not stop expansion. + Cursorless ID: `boundedNonWhitespaceSequence` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/scopes/boundedParagraph.mdx b/packages/app-web-docs/src/docs/user/scopes/boundedParagraph.mdx index debee946d4..28148ab353 100644 --- a/packages/app-web-docs/src/docs/user/scopes/boundedParagraph.mdx +++ b/packages/app-web-docs/src/docs/user/scopes/boundedParagraph.mdx @@ -6,6 +6,8 @@ import { Scopes } from "@site/src/docs/components/Scopes"; # Short block (Bounded paragraph) +Like `"block"`, but also stops at the boundary of a surrounding delimiter pair, so the selection does not escape the pair containing the input target. + Cursorless ID: `boundedParagraph` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/scopes/document.mdx b/packages/app-web-docs/src/docs/user/scopes/document.mdx index e9c7309bbd..97d8e5b898 100644 --- a/packages/app-web-docs/src/docs/user/scopes/document.mdx +++ b/packages/app-web-docs/src/docs/user/scopes/document.mdx @@ -6,6 +6,8 @@ import { Scopes } from "@site/src/docs/components/Scopes"; # File (Document) +The entire document, from the first to the last character. + Cursorless ID: `document` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/scopes/identifier.mdx b/packages/app-web-docs/src/docs/user/scopes/identifier.mdx index 830ee6958f..f22193d14b 100644 --- a/packages/app-web-docs/src/docs/user/scopes/identifier.mdx +++ b/packages/app-web-docs/src/docs/user/scopes/identifier.mdx @@ -6,6 +6,8 @@ import { Scopes } from "@site/src/docs/components/Scopes"; # Identifier +Like a token, but limited to text that can act as an identifier, such as `foo`, `fooBar`, or `foo_bar`; operators such as `.`, `=`, and `+=` are excluded. This scope is useful with ordinals such as `last identifier`. + Cursorless ID: `identifier` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/scopes/instance.mdx b/packages/app-web-docs/src/docs/user/scopes/instance.mdx index 86aad769c3..792a97eeaf 100644 --- a/packages/app-web-docs/src/docs/user/scopes/instance.mdx +++ b/packages/app-web-docs/src/docs/user/scopes/instance.mdx @@ -6,6 +6,10 @@ import { Scopes } from "@site/src/docs/components/Scopes"; # Instance +Searches for occurrences of the input target's text. Instance matching preserves the target's scope type, so an instance of a token only matches complete tokens rather than substrings within larger tokens; apply [`"just"`](../modifiers/toRawSelection.mdx) to match the raw text instead. + +For a range target, the entire range becomes the search text. Without an explicit mark, Cursorless uses the token touching the cursor. Use [`"from"`](../actions/setInstanceReference.mdx) to restrict the search region or choose its starting point. + Cursorless ID: `instance` ## Spoken form @@ -19,5 +23,8 @@ Default: `instance` ## Examples - `"take every instance blue air"` - Selects every instance of the token containing letter 'a' with a blue hat. +- `"take every instance blue air past green bat"` - Selects every occurrence of the text spanning from the token containing letter 'a' with a blue hat through the token containing letter 'b' with a green hat. +- `"take next instance blue air"` - Selects the next instance of the token containing letter 'a' with a blue hat. +- `"take every instance"` - Selects every instance of the token touching the cursor. diff --git a/packages/app-web-docs/src/docs/user/scopes/line.mdx b/packages/app-web-docs/src/docs/user/scopes/line.mdx index ea6c1a6faa..40df716d2b 100644 --- a/packages/app-web-docs/src/docs/user/scopes/line.mdx +++ b/packages/app-web-docs/src/docs/user/scopes/line.mdx @@ -14,7 +14,7 @@ Default: `line` ## Syntax -- line - Line, without indentation. +- line - Line, excluding indentation. ## Examples diff --git a/packages/app-web-docs/src/docs/user/scopes/nonWhitespaceSequence.mdx b/packages/app-web-docs/src/docs/user/scopes/nonWhitespaceSequence.mdx index 062c8a5700..8f4ed905da 100644 --- a/packages/app-web-docs/src/docs/user/scopes/nonWhitespaceSequence.mdx +++ b/packages/app-web-docs/src/docs/user/scopes/nonWhitespaceSequence.mdx @@ -6,6 +6,8 @@ import { Scopes } from "@site/src/docs/components/Scopes"; # Paint (Non-whitespace sequence) +Expands forward and backward from the input through adjacent non-whitespace characters. + Cursorless ID: `nonWhitespaceSequence` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/scopes/paragraph.mdx b/packages/app-web-docs/src/docs/user/scopes/paragraph.mdx index 9f77c3e393..3b17a423a2 100644 --- a/packages/app-web-docs/src/docs/user/scopes/paragraph.mdx +++ b/packages/app-web-docs/src/docs/user/scopes/paragraph.mdx @@ -6,6 +6,8 @@ import { Scopes } from "@site/src/docs/components/Scopes"; # Block (Paragraph) +Expands above and below the input through contiguous nonempty lines, stopping at empty lines. + Cursorless ID: `paragraph` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/scopes/surroundingPair.mdx b/packages/app-web-docs/src/docs/user/scopes/surroundingPair.mdx index a7da0927b5..0b3b55c037 100644 --- a/packages/app-web-docs/src/docs/user/scopes/surroundingPair.mdx +++ b/packages/app-web-docs/src/docs/user/scopes/surroundingPair.mdx @@ -2,6 +2,10 @@ import { Scopes } from "@site/src/docs/components/Scopes"; # Surrounding pair +Expands the input to the nearest containing [paired delimiters](../paired-delimiters.md) and their contents. Use the [interior-only](../modifiers/interiorOnly.mdx) or [exclude-interior](../modifiers/excludeInterior.mdx) modifiers to select only the contents or only the delimiters. + +When an opening and closing delimiter use the same character and no parse-tree information is available, Cursorless treats the first occurrence on each line as an opening delimiter and alternates subsequent occurrences between closing and opening delimiters. + Cursorless ID: `surroundingPair` ## Syntax diff --git a/packages/app-web-docs/src/docs/user/scopes/token.mdx b/packages/app-web-docs/src/docs/user/scopes/token.mdx index 4d90f074ef..fc60454aef 100644 --- a/packages/app-web-docs/src/docs/user/scopes/token.mdx +++ b/packages/app-web-docs/src/docs/user/scopes/token.mdx @@ -6,6 +6,8 @@ import { Scopes } from "@site/src/docs/components/Scopes"; # Token +Expands the input to the nearest containing token. Without an explicit mark, it uses the token adjacent to the cursor or containing the current selection. + Cursorless ID: `token` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/scopes/word.mdx b/packages/app-web-docs/src/docs/user/scopes/word.mdx index da48599e05..b98365e9f4 100644 --- a/packages/app-web-docs/src/docs/user/scopes/word.mdx +++ b/packages/app-web-docs/src/docs/user/scopes/word.mdx @@ -6,6 +6,8 @@ import { Scopes } from "@site/src/docs/components/Scopes"; # Sub (Sub token word) +Selects an individual word-like component within a camelCase, snake_case, or similarly structured token. It can be combined with ordinal and range modifiers to select one or more components. + Cursorless ID: `word` ## Spoken form @@ -20,5 +22,6 @@ Legacy: `word` ## Examples - `"take first sub blue air"` - Selects the first sub token word in the token containing letter 'a' with a blue hat. +- `"take second past fourth sub blue air"` - Selects the second through fourth sub token words in the token containing letter 'a' with a blue hat. diff --git a/packages/lib-common/src/references/actionReferences.ts b/packages/lib-common/src/references/actionReferences.ts index 71cd05de7a..884568a41f 100644 --- a/packages/lib-common/src/references/actionReferences.ts +++ b/packages/lib-common/src/references/actionReferences.ts @@ -38,6 +38,7 @@ const INSTANCE = scopeReferences.instance.defaultSpokenForm; const FUNCTION = scopeReferences.namedFunction.defaultSpokenForm; const TOKEN = scopeReferences.token.defaultSpokenForm; const EVERY = modifierReferences.everyScope.defaultSpokenForm; +const NEXT = connectiveDefaultSpokenForms.next; const WITH = connectiveDefaultSpokenForms.swapConnective; const AFTER = connectiveDefaultSpokenForms.after; const TO = connectiveDefaultSpokenForms.sourceDestinationConnective; @@ -1060,8 +1061,9 @@ export const actionReferences = { name: "Set instance reference", defaultSpokenForm: "from", group: { id: "instanceReference", index: 0 }, - description: - "Sets the instance reference for the next 'instance of' action.", + description: `Sets the instance reference. This restricts the next instance search to a target. With \`"every instance"\`, the target defines the region to search; with \`"next instance"\`, it defines the position where the search begins. + +Older Cursorless installations may have \`"from"\` disabled. Remove the leading \`-\` from its entry in \`experimental/experimental_actions.csv\` to enable it; see the [settings CSV documentation](../customization.md).`, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -1074,6 +1076,10 @@ export const actionReferences = { command: `${VAR_SPOKEN_FORM} ${FUNCTION} ${TARGET} ${SET_SELECTION} ${EVERY} ${INSTANCE} ${TARGET_2}`, description: `Selects every instance of the ${TARGET_2_DESC} within the function containing the ${TARGET_DESC}.`, }, + { + command: `${VAR_SPOKEN_FORM} ${TARGET} ${SET_SELECTION} ${NEXT} ${INSTANCE} ${TARGET_2}`, + description: `Selects the next instance of the ${TARGET_2_DESC}, searching from the ${TARGET_DESC}.`, + }, ], }, diff --git a/packages/lib-common/src/references/modifierReferences.ts b/packages/lib-common/src/references/modifierReferences.ts index df63d75d9a..41e74cb2ee 100644 --- a/packages/lib-common/src/references/modifierReferences.ts +++ b/packages/lib-common/src/references/modifierReferences.ts @@ -32,6 +32,16 @@ const BACKWARD = connectiveDefaultSpokenForms.backward; const FORWARD = connectiveDefaultSpokenForms.forward; const FIRST = connectiveDefaultSpokenForms.first; const LAST = connectiveDefaultSpokenForms.last; +const PASTE = "paste"; +const BRING = "bring"; +const FROM = "from"; +const AFTER = connectiveDefaultSpokenForms.after; +const TO = connectiveDefaultSpokenForms.sourceDestinationConnective; +const INSTANCE = "instance"; +const VALUE = "value"; + +const ITERATION_SCOPE_DESCRIPTION = + "The iteration scope depends on the scope type. For example, functions iterate within a class, tokens within a line, and characters within a token."; type AdditionalModifierReferenceType = "ancestor"; @@ -40,6 +50,8 @@ export const modifierReferences = { containingScope: { name: "Containing scope", group: { id: "containing", index: 0 }, + description: + 'Expands a target to the containing instance of a scope. When the input is `"this"` with multiple selections, Cursorless expands each selection independently.', syntaxes: [ { pattern: VAR_SCOPE, @@ -58,6 +70,8 @@ export const modifierReferences = { name: "Every scope", defaultSpokenForm: EVERY, group: { id: "containing", index: 1 }, + description: + "Selects all matching sibling scopes. It can also prefix an ordinal or relative modifier to return separate targets instead of one contiguous range.", syntaxes: [ { pattern: `${VAR_SPOKEN_FORM} ${VAR_SCOPE}`, @@ -76,6 +90,8 @@ export const modifierReferences = { name: "Ancestor", defaultSpokenForm: "grand", group: { id: "containing", index: 2 }, + description: + 'Selects the parent of a containing scope. Repeat `"grand"` to walk up more than one parent level.', syntaxes: [ { pattern: `${VAR_SPOKEN_FORM} ${VAR_SCOPE}`, @@ -88,6 +104,10 @@ export const modifierReferences = { command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${STATEMENT} ${TARGET}`, description: `Selects the parent statement of the statement containing the ${TARGET_DESC}.`, }, + { + command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${VAR_SPOKEN_FORM} ${STATEMENT} ${TARGET}`, + description: `Selects the grandparent statement of the statement containing the ${TARGET_DESC}.`, + }, ], }, @@ -95,6 +115,15 @@ export const modifierReferences = { ordinalScope: { name: "Ordinal scope", group: { id: "ordinal", index: 0 }, + description: `${ITERATION_SCOPE_DESCRIPTION} + +Without \`"every"\`, plural ordinal forms produce one contiguous range. Prefix them with \`"every"\` to produce separate targets instead. + +
+ +![Relative and ordinal modifier diagram](../images/relative_ordinal.png) + +
`, syntaxes: [ { pattern: `${VAR_ORDINAL} ${VAR_SCOPE}`, @@ -164,6 +193,9 @@ export const modifierReferences = { relativeScope: { name: "Relative scope", group: { id: "relative", index: 0 }, + description: `${ITERATION_SCOPE_DESCRIPTION} + +Relative modifiers select scopes before or after the input target. Without \`"every"\`, plural forms produce one contiguous range; prefix them with \`"every"\` to produce separate targets instead.`, syntaxes: [ { pattern: `${PREVIOUS} ${VAR_SCOPE}`, @@ -375,6 +407,8 @@ export const modifierReferences = { name: "Extend through start of", defaultSpokenForm: "head", group: { id: "range", index: 0 }, + description: + 'Extends a target through the start of its line. Inside a surrounding pair, it stops at the start of the pair\'s interior; use an explicit scope such as `"head line"` to override that boundary.', syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -402,6 +436,8 @@ export const modifierReferences = { name: "Extend through end of", defaultSpokenForm: "tail", group: { id: "range", index: 1 }, + description: + 'Extends a target through the end of its line. Inside a surrounding pair, it stops at the end of the pair\'s interior; use an explicit scope such as `"tail line"` to override that boundary.', syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -469,6 +505,8 @@ export const modifierReferences = { name: "Visible", defaultSpokenForm: "visible", group: { id: "filters", index: 0 }, + description: + 'Limits a target to content currently visible in the editor viewport, excluding folded regions and content scrolled off screen. This is especially useful with the `"from"` action when searching for instances.', syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -482,6 +520,10 @@ export const modifierReferences = { description: "Selects the content currently visible in the editor viewport.", }, + { + command: `${FROM} ${VAR_SPOKEN_FORM} ${SET_SELECTION} ${EVERY} ${INSTANCE} ${TARGET}`, + description: `Selects the visible instances of the ${TARGET_DESC}, excluding matches that are folded or outside the viewport.`, + }, ], }, keepContentFilter: { @@ -528,6 +570,8 @@ export const modifierReferences = { name: "Raw selection", defaultSpokenForm: "just", group: { id: "inference", index: 0 }, + description: + 'Strips semantic information from a target and treats it as a raw range. Cursorless will not use the target\'s removal delimiters, insertion delimiters, or scope type. This means deletion leaves adjacent whitespace and line endings untouched, insertion adds no automatic separator, and instance matching is not restricted to targets of the original scope type. When a raw target is the destination of a `"bring"` command, it inherits insertion delimiters from the source.', syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -540,12 +584,27 @@ export const modifierReferences = { command: `${REMOVE} ${VAR_SPOKEN_FORM} ${TARGET}`, description: `Deletes only the ${TARGET_DESC}, leaving adjacent whitespace unchanged.`, }, + { + command: `${REMOVE} ${VAR_SPOKEN_FORM} ${LINE}`, + description: + "Deletes only the line content, leaving its line ending and therefore a blank line.", + }, + { + command: `${PASTE} ${AFTER} ${VAR_SPOKEN_FORM} ${TARGET}`, + description: `Pastes directly after the ${TARGET_DESC} without inserting a separator.`, + }, + { + command: `${SET_SELECTION} ${EVERY} ${INSTANCE} ${VAR_SPOKEN_FORM} ${TARGET}`, + description: `Selects every matching text occurrence of the ${TARGET_DESC}, including occurrences that are not full tokens.`, + }, ], }, inferPreviousMark: { name: "Infer previous mark", defaultSpokenForm: "its", group: { id: "inference", index: 1 }, + description: + 'Within a compound target, applies the following modifier to the previously mentioned mark. Without `"its"`, an implicit target such as `"line"` is resolved relative to the current selection instead.', syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -558,6 +617,10 @@ export const modifierReferences = { command: `${SET_SELECTION} ${TARGET} ${EXTEND_THROUGH_END_OF} ${VAR_SPOKEN_FORM} ${LINE}`, description: `Selects from the ${TARGET_DESC} through the end of the line containing that token.`, }, + { + command: `${BRING} ${TARGET} ${TO} ${VAR_SPOKEN_FORM} ${VALUE}`, + description: `Replaces the value containing the ${TARGET_DESC} with that token.`, + }, ], }, diff --git a/packages/lib-common/src/references/scopeReferences.ts b/packages/lib-common/src/references/scopeReferences.ts index a091e48c51..b545a80337 100644 --- a/packages/lib-common/src/references/scopeReferences.ts +++ b/packages/lib-common/src/references/scopeReferences.ts @@ -6,6 +6,8 @@ import { SET_SELECTION, STATEMENT, TARGET, + TARGET_2, + TARGET_2_DESC, TARGET_DESC, VAR_CHARACTER, VAR_PAIR, @@ -16,6 +18,7 @@ import type { ReferenceEntry } from "./ReferenceEntry"; import type { ScopeReferenceGroupId } from "./scopeReferenceGroups"; import { connectiveDefaultSpokenForms } from "./spokenForms/connectiveDefaultSpokenForms"; import { graphemeDefaultSpokenForms } from "./spokenForms/graphemeDefaultSpokenForms"; +import { ordinalDefaultSpokenForms } from "./spokenForms/numberDefaultSpokenForms"; const DEFAULT_PATTERN = VAR_SPOKEN_FORM; @@ -23,6 +26,10 @@ const AIR = graphemeDefaultSpokenForms.a; const PARENTHESIS = pairedDelimiterReferences.parentheses.defaultSpokenForm; const NEXT = connectiveDefaultSpokenForms.next; const FIRST = connectiveDefaultSpokenForms.first; +const LAST = connectiveDefaultSpokenForms.last; +const PAST = connectiveDefaultSpokenForms.rangeInclusive; +const SECOND = ordinalDefaultSpokenForms[2]; +const FOURTH = ordinalDefaultSpokenForms[4]; export const scopeReferences = { // Group: text @@ -49,6 +56,8 @@ export const scopeReferences = { group: { id: "text", index: 1 }, defaultSpokenForm: "sub", legacySpokenForms: ["word"], + description: + "Selects an individual word-like component within a camelCase, snake_case, or similarly structured token. It can be combined with ordinal and range modifiers to select one or more components.", syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -62,12 +71,18 @@ export const scopeReferences = { command: `${SET_SELECTION} ${FIRST} ${VAR_SPOKEN_FORM} ${TARGET}`, description: `Selects the first sub token word in the ${TARGET_DESC}.`, }, + { + command: `${SET_SELECTION} ${SECOND} ${PAST} ${FOURTH} ${VAR_SPOKEN_FORM} ${TARGET}`, + description: `Selects the second through fourth sub token words in the ${TARGET_DESC}.`, + }, ], }, token: { name: "Token", group: { id: "text", index: 2 }, defaultSpokenForm: "token", + description: + "Expands the input to the nearest containing token. Without an explicit mark, it uses the token adjacent to the cursor or containing the current selection.", syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -86,6 +101,7 @@ export const scopeReferences = { name: "Identifier", group: { id: "text", index: 3 }, defaultSpokenForm: "identifier", + description: `Like a token, but limited to text that can act as an identifier, such as \`foo\`, \`fooBar\`, or \`foo_bar\`; operators such as \`.\`, \`=\`, and \`+=\` are excluded. This scope is useful with ordinals such as \`${LAST} identifier\`.`, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -127,7 +143,7 @@ export const scopeReferences = { syntaxes: [ { pattern: DEFAULT_PATTERN, - description: "Line, without indentation.", + description: "Line, excluding indentation.", cheatsheet: "Line", }, ], @@ -160,6 +176,8 @@ export const scopeReferences = { name: "Paragraph", group: { id: "text", index: 7 }, defaultSpokenForm: "block", + description: + "Expands above and below the input through contiguous nonempty lines, stopping at empty lines.", syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -178,6 +196,8 @@ export const scopeReferences = { name: "Bounded paragraph", group: { id: "text", index: 8 }, defaultSpokenForm: "short block", + description: + 'Like `"block"`, but also stops at the boundary of a surrounding delimiter pair, so the selection does not escape the pair containing the input target.', syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -196,6 +216,7 @@ export const scopeReferences = { name: "Document", group: { id: "text", index: 9 }, defaultSpokenForm: "file", + description: "The entire document, from the first to the last character.", syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -214,6 +235,8 @@ export const scopeReferences = { name: "Non-whitespace sequence", group: { id: "text", index: 10 }, defaultSpokenForm: "paint", + description: + "Expands forward and backward from the input through adjacent non-whitespace characters.", syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -232,6 +255,8 @@ export const scopeReferences = { name: "Bounded non-whitespace sequence", group: { id: "text", index: 11 }, defaultSpokenForm: "short paint", + description: + 'Like `"paint"`, but expansion also stops at a delimiter pair that surrounds the input target. Delimiter pairs that do not surround the original target do not stop expansion.', syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -269,6 +294,9 @@ export const scopeReferences = { surroundingPair: { name: "Surrounding pair", group: { id: "text", index: 13 }, + description: `Expands the input to the nearest containing [paired delimiters](../paired-delimiters.md) and their contents. Use the [interior-only](../modifiers/interiorOnly.mdx) or [exclude-interior](../modifiers/excludeInterior.mdx) modifiers to select only the contents or only the delimiters. + +When an opening and closing delimiter use the same character and no parse-tree information is available, Cursorless treats the first occurrence on each line as an opening delimiter and alternates subsequent occurrences between closing and opening delimiters.`, syntaxes: [ { pattern: VAR_PAIR, @@ -673,6 +701,9 @@ export const scopeReferences = { name: "Instance", group: { id: "objects", index: 2 }, defaultSpokenForm: "instance", + description: `Searches for occurrences of the input target's text. Instance matching preserves the target's scope type, so an instance of a token only matches complete tokens rather than substrings within larger tokens; apply [\`"just"\`](../modifiers/toRawSelection.mdx) to match the raw text instead. + +For a range target, the entire range becomes the search text. Without an explicit mark, Cursorless uses the token touching the cursor. Use [\`"from"\`](../actions/setInstanceReference.mdx) to restrict the search region or choose its starting point.`, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -685,6 +716,18 @@ export const scopeReferences = { command: `${SET_SELECTION} ${EVERY} ${VAR_SPOKEN_FORM} ${TARGET}`, description: `Selects every instance of the ${TARGET_DESC}.`, }, + { + command: `${SET_SELECTION} ${EVERY} ${VAR_SPOKEN_FORM} ${TARGET} ${PAST} ${TARGET_2}`, + description: `Selects every occurrence of the text spanning from the ${TARGET_DESC} through the ${TARGET_2_DESC}.`, + }, + { + command: `${SET_SELECTION} ${NEXT} ${VAR_SPOKEN_FORM} ${TARGET}`, + description: `Selects the next instance of the ${TARGET_DESC}.`, + }, + { + command: `${SET_SELECTION} ${EVERY} ${VAR_SPOKEN_FORM}`, + description: "Selects every instance of the token touching the cursor.", + }, ], }, name: { diff --git a/packages/tool-meta-updater/src/util/injectSpokenForm.ts b/packages/tool-meta-updater/src/util/injectSpokenForm.ts index f3ff8ddd0e..b8a720f755 100644 --- a/packages/tool-meta-updater/src/util/injectSpokenForm.ts +++ b/packages/tool-meta-updater/src/util/injectSpokenForm.ts @@ -12,5 +12,5 @@ export function injectSpokenForm( } return pattern; } - return pattern.replace(VAR_SPOKEN_FORM, defaultSpokenForm); + return pattern.replaceAll(VAR_SPOKEN_FORM, defaultSpokenForm); }