Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
339 changes: 2 additions & 337 deletions packages/app-web-docs/src/docs/user/README.md

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand All @@ -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.
3 changes: 3 additions & 0 deletions packages/app-web-docs/src/docs/user/modifiers/ancestor.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Original file line number Diff line number Diff line change
@@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
10 changes: 10 additions & 0 deletions packages/app-web-docs/src/docs/user/modifiers/ordinalScope.mdx
Original file line number Diff line number Diff line change
@@ -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.

<div className="dark-mode-invert">

![Relative and ordinal modifier diagram](../images/relative_ordinal.png)

</div>

Cursorless ID: `ordinalScope`

## Syntax
Expand Down
Original file line number Diff line number Diff line change
@@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
3 changes: 3 additions & 0 deletions packages/app-web-docs/src/docs/user/modifiers/visible.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
2 changes: 1 addition & 1 deletion packages/app-web-docs/src/docs/user/scopes/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions packages/app-web-docs/src/docs/user/scopes/document.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions packages/app-web-docs/src/docs/user/scopes/identifier.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 7 additions & 0 deletions packages/app-web-docs/src/docs/user/scopes/instance.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

<Scopes scopeTypeType="instance" />
2 changes: 1 addition & 1 deletion packages/app-web-docs/src/docs/user/scopes/line.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Default: `line`

## Syntax

- line - Line, without indentation.
- line - Line, excluding indentation.

## Examples

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions packages/app-web-docs/src/docs/user/scopes/paragraph.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions packages/app-web-docs/src/docs/user/scopes/token.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions packages/app-web-docs/src/docs/user/scopes/word.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

<Scopes scopeTypeType="word" />
10 changes: 8 additions & 2 deletions packages/lib-common/src/references/actionReferences.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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,
Expand All @@ -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}.`,
},
],
},

Expand Down
Loading
Loading