diff --git a/packages/app-web-docs/src/docs/user/README.md b/packages/app-web-docs/src/docs/user/README.md index 78950f943c..b84262e1b6 100644 --- a/packages/app-web-docs/src/docs/user/README.md +++ b/packages/app-web-docs/src/docs/user/README.md @@ -535,238 +535,9 @@ Selects both the token containing letter 'a' with a blue hat AND the token conta ## Actions -In any cursorless command, the action defines what happens to the specified target. Every command must have a target. For example, deleting the target (`"chuck"`, as in `"chuck air"`) or moving the cursor to select the target (`"take"`, as in `"take air"`). +Every Cursorless command combines an action with a target. The action determines what happens to the target. For example, `"chuck air"` removes the target, while `"take air"` selects it. -### Cursor movement - -Despite the name cursorless, some of the most basic commands in cursorless are for moving the cursor. - -Note that when combined with list targets, `take`/`pre`/`post` commands will result in multiple cursors. - -- `"take "`: Selects the given target. -- `"pre "`: Places the cursor before the given target. -- `"post "`: Places the cursor after the given target. -- `"append "`: Selects the given target, while preserving your existing selections. -- `"append pre "`: Adds a new cursor before the given target, while preserving your existing selections. -- `"append post "`: Adds a new cursor after the given target, while preserving your existing selections. -- `"give "`: Deselects the given target. - -eg: -`pre blue air` -Moves the cursor to before the token containing letter 'a' with a blue hat. - -### Changing a target - -This command will delete a target and leave the cursor where the target used to be, making it easy to change a target - -- `"change "` - eg: - `change blue air` - Deletes the token containing letter 'a' with a blue hat then places your cursor where the token had been. - -### `"clone"` / `"clone up"` - -These commands insert a copy of the target either before or after the target itself, leaving your cursor(s) in the newly created clone. - -- `"clone "` -- `"clone up "` - -For example: - -- `"clone funk"` inserts a copy of the function containing your cursor just below the function -- `"clone up funk"` inserts a copy of the function containing your cursor just above the function -- `"clone state air"` inserts a copy of the statement containing `a` with a gray hat below the given statement itself - -### Cut / copy - -- `"carve "`: cut -- `"copy "`: copy - -eg: -`copy blue air` -Copies the token containing letter 'a' with a blue hat. - -### Swap - -Swaps two targets. If the first target is omitted, it will target the current selection. If `` and `` each consist of multiple targets, they will be zipped together. - -- `"swap with "` -- `"swap with "` -- `"swap air and bat with cap and drum"` is equivalent to `"swap air with cap"` and `"swap bat with drum"` - -eg: -`swap blue air with green bat` - -Swaps the given tokens. - -### Indent / dedent - -- `"dedent "` decreases the indentation level of `` -- `"indent "` increases the indentation level of `` - -For example: - -- `"indent air"` -- `"dedent funk bat"` - -### Increment / decrement - -- `"increment "`: increment number target. eg change `1` to `2`. -- `"decrement "`: decrement number target. eg change `2` to `1`. - -### Insert empty lines - -- `"drink "`: Inserts a new line above the target line, and moves the cursor to the newly created line -- `"pour "`: Inserts a new line below the target line, and moves the cursor to the newly created line -- `"drop "`: Inserts an empty line above the target line (without moving the cursor) -- `"float "`: Inserts an empty line below the target line (without moving the cursor) -- `"puff "`: Inserts empty lines/spaces around the target (without moving the cursor) - -eg: `pour blue air` will insert empty line below the token containing letter 'a' with a blue hat and moves the cursor to the new line. - -Note: `"drink"`, `"pour"`, `"drop"`, `"float"`, and `"puff"` are actually more versatile than just handling lines. -If you use a [syntactic scope](#syntactic-scopes) modifier on the target, they will do the -appropriate insertions to prepare the text for a new instance of that scope. - -eg: `pour item air` will insert a comma and space after the air item, and place the cursor after the inserted characters. -eg: `puff token air` will insert spaces around the token with a hat over the letter 'a'. -eg: `float item air` will insert a comma after the item containing letter 'a' with a hat. - -### Homophones - -The `"phones"` command can be used to cycle through homophones for a given target. For example, if there were a hat on the `h` in `where`, you could say `"phones harp"` to change it to `wear`. - -- `"phones "` - -eg: - -- `"phones air"` -- `"phones first word air"` - -### Rename - -Executes vscode rename action on the specified target - -- `"rename "` - -eg: -`rename blue air` -Rename the token containing letter 'a' with a blue hat. - -### Scroll - -Scrolls a given target to the top, center or bottom of the screen. - -- `"crown "`: top -- `"center "`: center -- `"bottom "`: bottom - -eg `crown blue air` scrolls the line containing the letter 'a' with a blue hat to the top of the screen. - -### Insert/Use/Repeat - -The `"bring"` command can be used to replace one target with another, or to use a target at the current cursor position. - -- `"bring "`: Inserts the given target at the cursor position -- `"bring to "` - -eg: -`bring blue air to green bat` -Replaces the token containing letter 'b' with a green hat using the token containing letter 'a' with a blue hat. - -### Move/Replace - -The `"move"` command can be used to move a target. - -- `"move "`: Moves the given target to the cursor position -- `"move to "`: Replaces `TARGET 2` with `TARGET 1` and deletes `TARGET 1` - -eg: -`move blue air to green bat` -Replaces the token containing letter 'b' with a green hat using the token containing letter 'a' with a blue hat, and the delete the latter token. - -### Reverse/Shuffle/Sort - -These commands accept multiple selections, and change their order. For example: - -- `"shuffle every item "` -- `"sort every item "` -- `"reverse every item "` -- `"sort line air slice bat"`: sort lines within the selection. -- `"sort this"`: Sort the multiple selections. - -### Wrap/Rewrap - -The wrap command can be used to wrap a given target with a pair of symbols - -- `"round wrap "`: wraps the target with parentheses -- `"box wrap "`: wraps the target with square brackets - -eg: -`box wrap blue air` -Wraps the token containing letter 'a' with a blue hat in square brackets. - -The rewrap command, mapped to `"repack"` by default, can be used to swap a given pair of symbols with another - -- `"curly repack "`: wraps the target with curly brackets, replacing the previous paired delimiter - -See [paired delimiters](#paired-delimiters) for a list of possible wrappers. - -### Show definition/reference/quick fix - -Each of these commands performs a vscode action of the same or a similar name on the target. - -- `"define "` navigate to the definition of the target -- `"reference "` search the workspace for all references to the target -- `"hover "` displays the tooltip that would appear if you hovered the mouse over the target -- `"quick fix "` displays quick fixes and refactors suggested by the vscode -- `"scout "` search the document for the target -- `"scout all "` search the workspace for the target - -eg: -`define blue air` -Shows definition for the token containing letter 'a' with a blue hat. - -### Fold/unfold - -- `"fold "` -- `"unfold "` - -eg: -`fold funk blue air` -Fold the function with the token containing letter 'a' with a blue hat. - -### Extract - -Extracts a target as a variable using the VSCode refactor action - -- `"extract "` - -eg: -`extract call air` - -Extracts the function call containing the decorated 'a' into its own variable. - -### Join - -Join multiple lines together. - -- `"join "` - -eg: - -- `join air`: Join the line with the token containing the letter 'a' with its next line. -- `join block air`: Joins all lines in the paragraph with the token containing the letter 'a' together into a single line. - -### Break - -Break line in two. - -- `"break "` - -eg: - -- `break air`: Break the line with the token containing the letter 'a'. 'a' is now the first token on the new line. +See the [action reference](./actions/README.md) for the complete list of actions, syntax, behavior, and examples. ## Paired delimiters diff --git a/packages/app-web-docs/src/docs/user/actions/editNewLineAfter.mdx b/packages/app-web-docs/src/docs/user/actions/editNewLineAfter.mdx index 8b6f79b1b0..6e60085a1d 100644 --- a/packages/app-web-docs/src/docs/user/actions/editNewLineAfter.mdx +++ b/packages/app-web-docs/src/docs/user/actions/editNewLineAfter.mdx @@ -4,7 +4,7 @@ sidebar_label: Pour # Pour (Edit new line/scope after) -Scope defaults to line. +Scope defaults to line. When used with a provided scope target, this action inserts the delimiters or spacing required for a new instance of that scope. Cursorless ID: `editNewLineAfter` diff --git a/packages/app-web-docs/src/docs/user/actions/editNewLineBefore.mdx b/packages/app-web-docs/src/docs/user/actions/editNewLineBefore.mdx index 3cec16d316..97a15a112d 100644 --- a/packages/app-web-docs/src/docs/user/actions/editNewLineBefore.mdx +++ b/packages/app-web-docs/src/docs/user/actions/editNewLineBefore.mdx @@ -4,7 +4,7 @@ sidebar_label: Drink # Drink (Edit new line/scope before) -Scope defaults to line. +Scope defaults to line. When used with a provided scope target, this action inserts the delimiters or spacing required for a new instance of that scope. Cursorless ID: `editNewLineBefore` diff --git a/packages/app-web-docs/src/docs/user/actions/extractVariable.mdx b/packages/app-web-docs/src/docs/user/actions/extractVariable.mdx index 60ff001ac9..0854a96bcc 100644 --- a/packages/app-web-docs/src/docs/user/actions/extractVariable.mdx +++ b/packages/app-web-docs/src/docs/user/actions/extractVariable.mdx @@ -4,6 +4,8 @@ sidebar_label: Extract # Extract (Extract variable) +Uses the editor's extract-variable refactoring. + Cursorless ID: `extractVariable` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/insertCopyAfter.mdx b/packages/app-web-docs/src/docs/user/actions/insertCopyAfter.mdx index f2e9461c5f..fb7380cfe4 100644 --- a/packages/app-web-docs/src/docs/user/actions/insertCopyAfter.mdx +++ b/packages/app-web-docs/src/docs/user/actions/insertCopyAfter.mdx @@ -4,6 +4,8 @@ sidebar_label: Clone # Clone (Insert copy after) +After insertion, each selection moves to its newly created copy. + Cursorless ID: `insertCopyAfter` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/insertCopyBefore.mdx b/packages/app-web-docs/src/docs/user/actions/insertCopyBefore.mdx index d31e87bc4f..c6588fae19 100644 --- a/packages/app-web-docs/src/docs/user/actions/insertCopyBefore.mdx +++ b/packages/app-web-docs/src/docs/user/actions/insertCopyBefore.mdx @@ -4,6 +4,8 @@ sidebar_label: Clone up # Clone up (Insert copy before) +After insertion, each selection moves to its newly created copy. + Cursorless ID: `insertCopyBefore` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/insertEmptyLineAfter.mdx b/packages/app-web-docs/src/docs/user/actions/insertEmptyLineAfter.mdx index a61c053802..61e8af8c9b 100644 --- a/packages/app-web-docs/src/docs/user/actions/insertEmptyLineAfter.mdx +++ b/packages/app-web-docs/src/docs/user/actions/insertEmptyLineAfter.mdx @@ -4,6 +4,8 @@ sidebar_label: Float # Float (Insert empty line/scope after) +Scope defaults to line. When used with a provided scope target, this action inserts the delimiters or spacing required for a new instance of that scope. + Cursorless ID: `insertEmptyLineAfter` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/insertEmptyLineBefore.mdx b/packages/app-web-docs/src/docs/user/actions/insertEmptyLineBefore.mdx index 65f93fd787..5d82b68a80 100644 --- a/packages/app-web-docs/src/docs/user/actions/insertEmptyLineBefore.mdx +++ b/packages/app-web-docs/src/docs/user/actions/insertEmptyLineBefore.mdx @@ -4,6 +4,8 @@ sidebar_label: Drop # Drop (Insert empty line/scope before) +Scope defaults to line. When used with a provided scope target, this action inserts the delimiters or spacing required for a new instance of that scope. + Cursorless ID: `insertEmptyLineBefore` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/insertEmptyLinesAround.mdx b/packages/app-web-docs/src/docs/user/actions/insertEmptyLinesAround.mdx index 934094c4cc..180a126a83 100644 --- a/packages/app-web-docs/src/docs/user/actions/insertEmptyLinesAround.mdx +++ b/packages/app-web-docs/src/docs/user/actions/insertEmptyLinesAround.mdx @@ -4,6 +4,8 @@ sidebar_label: Puff # Puff (Insert empty lines/scopes around) +Scope defaults to line. When used with a provided scope target, this action inserts the delimiters or spacing required for a new instance of that scope. + Cursorless ID: `insertEmptyLinesAround` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/joinLines.mdx b/packages/app-web-docs/src/docs/user/actions/joinLines.mdx index 36557daba1..ed48d54eaa 100644 --- a/packages/app-web-docs/src/docs/user/actions/joinLines.mdx +++ b/packages/app-web-docs/src/docs/user/actions/joinLines.mdx @@ -4,6 +4,8 @@ sidebar_label: Join # Join (Join lines) +When the target spans multiple lines, joins all of those lines; otherwise joins the target's line with the following line. + Cursorless ID: `joinLines` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/moveToTarget.mdx b/packages/app-web-docs/src/docs/user/actions/moveToTarget.mdx index e56f6700dc..13ffc95adf 100644 --- a/packages/app-web-docs/src/docs/user/actions/moveToTarget.mdx +++ b/packages/app-web-docs/src/docs/user/actions/moveToTarget.mdx @@ -4,6 +4,8 @@ sidebar_label: Move # Move (Move to target) +A target destination is replaced, while a position destination such as `before` or `after` inserts there. The source is removed from its original location in either case. + Cursorless ID: `moveToTarget` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/nextHomophone.mdx b/packages/app-web-docs/src/docs/user/actions/nextHomophone.mdx index 824d26960d..13db382fc8 100644 --- a/packages/app-web-docs/src/docs/user/actions/nextHomophone.mdx +++ b/packages/app-web-docs/src/docs/user/actions/nextHomophone.mdx @@ -4,6 +4,8 @@ sidebar_label: Phones # Phones (Next homophone) +Cycles through words that sound alike, such as changing `where` to `wear`. + Cursorless ID: `nextHomophone` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/randomizeTargets.mdx b/packages/app-web-docs/src/docs/user/actions/randomizeTargets.mdx index b6dc79965f..355740cd5b 100644 --- a/packages/app-web-docs/src/docs/user/actions/randomizeTargets.mdx +++ b/packages/app-web-docs/src/docs/user/actions/randomizeTargets.mdx @@ -4,6 +4,8 @@ sidebar_label: Shuffle # Shuffle (Randomize targets) +This action changes the order of multiple target contents. The targets can come from a list or range target, or from existing multiple selections. + Cursorless ID: `randomizeTargets` ## Spoken form @@ -17,3 +19,5 @@ Default: `shuffle` ## Examples - `"shuffle every item blue air"` - Randomizes the collection items associated with the token containing letter 'a' with a blue hat. +- `"shuffle line blue air slice green bat"` - Randomizes the lines from the token containing letter 'a' with a blue hat through the token containing letter 'b' with a green hat. +- `"shuffle this"` - Randomizes the current selections. diff --git a/packages/app-web-docs/src/docs/user/actions/rename.mdx b/packages/app-web-docs/src/docs/user/actions/rename.mdx index 31ad4d2d34..0ecd8cdfad 100644 --- a/packages/app-web-docs/src/docs/user/actions/rename.mdx +++ b/packages/app-web-docs/src/docs/user/actions/rename.mdx @@ -4,6 +4,8 @@ sidebar_label: Rename # Rename +Uses the editor's rename operation. + Cursorless ID: `rename` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/reverseTargets.mdx b/packages/app-web-docs/src/docs/user/actions/reverseTargets.mdx index 9d69390c38..7273244197 100644 --- a/packages/app-web-docs/src/docs/user/actions/reverseTargets.mdx +++ b/packages/app-web-docs/src/docs/user/actions/reverseTargets.mdx @@ -4,6 +4,8 @@ sidebar_label: Reverse # Reverse (Reverse targets) +This action changes the order of multiple target contents. The targets can come from a list or range target, or from existing multiple selections. + Cursorless ID: `reverseTargets` ## Spoken form @@ -17,3 +19,5 @@ Default: `reverse` ## Examples - `"reverse every item blue air"` - Reverses the collection items associated with the token containing letter 'a' with a blue hat. +- `"reverse line blue air slice green bat"` - Reverses the lines from the token containing letter 'a' with a blue hat through the token containing letter 'b' with a green hat. +- `"reverse this"` - Reverses the current selections. diff --git a/packages/app-web-docs/src/docs/user/actions/rewrapWithPairedDelimiter.mdx b/packages/app-web-docs/src/docs/user/actions/rewrapWithPairedDelimiter.mdx index b4ae573496..8e4df7cef0 100644 --- a/packages/app-web-docs/src/docs/user/actions/rewrapWithPairedDelimiter.mdx +++ b/packages/app-web-docs/src/docs/user/actions/rewrapWithPairedDelimiter.mdx @@ -4,6 +4,8 @@ sidebar_label: Repack # Repack (Rewrap with paired delimiter) +See [paired delimiters](../README.md#paired-delimiters) for the available pairs. + Cursorless ID: `rewrapWithPairedDelimiter` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/setSelection.mdx b/packages/app-web-docs/src/docs/user/actions/setSelection.mdx index dbb0937076..0b5d7909b0 100644 --- a/packages/app-web-docs/src/docs/user/actions/setSelection.mdx +++ b/packages/app-web-docs/src/docs/user/actions/setSelection.mdx @@ -4,6 +4,8 @@ sidebar_label: Take # Take (Set selection) +When used with a list target, this action creates one cursor for each target. + Cursorless ID: `setSelection` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/setSelectionAfter.mdx b/packages/app-web-docs/src/docs/user/actions/setSelectionAfter.mdx index 7776897437..ddfd67335b 100644 --- a/packages/app-web-docs/src/docs/user/actions/setSelectionAfter.mdx +++ b/packages/app-web-docs/src/docs/user/actions/setSelectionAfter.mdx @@ -4,6 +4,8 @@ sidebar_label: Post # Post (Set selection after) +When used with a list target, this action creates one cursor for each target. + Cursorless ID: `setSelectionAfter` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/setSelectionBefore.mdx b/packages/app-web-docs/src/docs/user/actions/setSelectionBefore.mdx index 82ee070695..600eb32d13 100644 --- a/packages/app-web-docs/src/docs/user/actions/setSelectionBefore.mdx +++ b/packages/app-web-docs/src/docs/user/actions/setSelectionBefore.mdx @@ -4,6 +4,8 @@ sidebar_label: Pre # Pre (Set selection before) +When used with a list target, this action creates one cursor for each target. + Cursorless ID: `setSelectionBefore` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/showQuickFix.mdx b/packages/app-web-docs/src/docs/user/actions/showQuickFix.mdx index b61e10c4ab..581f3ca06f 100644 --- a/packages/app-web-docs/src/docs/user/actions/showQuickFix.mdx +++ b/packages/app-web-docs/src/docs/user/actions/showQuickFix.mdx @@ -4,6 +4,8 @@ sidebar_label: Quick fix # Quick fix (Show quick fix) +Shows the editor's quick fix menu. + Cursorless ID: `showQuickFix` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/sortTargets.mdx b/packages/app-web-docs/src/docs/user/actions/sortTargets.mdx index 00fecb165f..80f99d236f 100644 --- a/packages/app-web-docs/src/docs/user/actions/sortTargets.mdx +++ b/packages/app-web-docs/src/docs/user/actions/sortTargets.mdx @@ -4,6 +4,8 @@ sidebar_label: Sort # Sort (Sort targets) +This action changes the order of multiple target contents. The targets can come from a list or range target, or from existing multiple selections. + Cursorless ID: `sortTargets` ## Spoken form @@ -17,3 +19,5 @@ Default: `sort` ## Examples - `"sort every item blue air"` - Sorts the collection items associated with the token containing letter 'a' with a blue hat. +- `"sort line blue air slice green bat"` - Sorts the lines from the token containing letter 'a' with a blue hat through the token containing letter 'b' with a green hat. +- `"sort this"` - Sorts the current selections. diff --git a/packages/app-web-docs/src/docs/user/actions/swapTargets.mdx b/packages/app-web-docs/src/docs/user/actions/swapTargets.mdx index 50f2e317f0..b5556aff89 100644 --- a/packages/app-web-docs/src/docs/user/actions/swapTargets.mdx +++ b/packages/app-web-docs/src/docs/user/actions/swapTargets.mdx @@ -4,6 +4,8 @@ sidebar_label: Swap # Swap (Swap targets) +When both operands contain multiple targets, their targets are paired by position and swapped. + Cursorless ID: `swapTargets` ## Spoken form diff --git a/packages/app-web-docs/src/docs/user/actions/wrapWithPairedDelimiter.mdx b/packages/app-web-docs/src/docs/user/actions/wrapWithPairedDelimiter.mdx index f787e411a6..5fd7637479 100644 --- a/packages/app-web-docs/src/docs/user/actions/wrapWithPairedDelimiter.mdx +++ b/packages/app-web-docs/src/docs/user/actions/wrapWithPairedDelimiter.mdx @@ -4,6 +4,8 @@ sidebar_label: Wrap # Wrap (Wrap with paired delimiter/snippet) +See [paired delimiters](../README.md#paired-delimiters) for the available pairs. + Cursorless ID: `wrapWithPairedDelimiter` ## Spoken form 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 19e6b4ad48..96ed583c78 100644 --- a/packages/app-web-docs/src/docs/user/scopes/README.md +++ b/packages/app-web-docs/src/docs/user/scopes/README.md @@ -18,16 +18,6 @@ - [`""`](./surroundingPair.mdx) - Surrounding matching delimiter pair and its contents. - [`"glyph "`](./glyph.mdx) - Instance of single character ``. -## Sections - -- [`"section"`](./section.mdx) - Heading and its content through the next heading of the same or higher level. -- [`"one section"`](./sectionLevelOne.mdx) - Level-one heading and its content. -- [`"two section"`](./sectionLevelTwo.mdx) - Level-two heading and its content. -- [`"three section"`](./sectionLevelThree.mdx) - Level-three heading and its content. -- [`"four section"`](./sectionLevelFour.mdx) - Level-four heading and its content. -- [`"five section"`](./sectionLevelFive.mdx) - Level-five heading and its content. -- [`"six section"`](./sectionLevelSix.mdx) - Level-six heading and its content. - ## Document hierarchy - [`"part"`](./part.mdx) - Document part and its contents. @@ -84,6 +74,16 @@ - [`"selector"`](./selector.mdx) - CSS selector. - [`"unit"`](./unit.mdx) - Unit suffix in a measurement, such as `px` in `100px`. +## Sections + +- [`"section"`](./section.mdx) - Heading and its content through the next heading of the same or higher level. +- [`"one section"`](./sectionLevelOne.mdx) - Level-one heading and its content. (**Disabled by default**) +- [`"two section"`](./sectionLevelTwo.mdx) - Level-two heading and its content. (**Disabled by default**) +- [`"three section"`](./sectionLevelThree.mdx) - Level-three heading and its content. (**Disabled by default**) +- [`"four section"`](./sectionLevelFour.mdx) - Level-four heading and its content. (**Disabled by default**) +- [`"five section"`](./sectionLevelFive.mdx) - Level-five heading and its content. (**Disabled by default**) +- [`"six section"`](./sectionLevelSix.mdx) - Level-six heading and its content. (**Disabled by default**) + ## Notebook - [`"cell"`](./notebookCell.mdx) - Notebook cell or Markdown fenced code block. diff --git a/packages/lib-common/src/references/actionReferences.ts b/packages/lib-common/src/references/actionReferences.ts index 7a62f7f044..88940efbc4 100644 --- a/packages/lib-common/src/references/actionReferences.ts +++ b/packages/lib-common/src/references/actionReferences.ts @@ -2,6 +2,7 @@ import type { ActionType } from "../types/command/ActionDescriptor"; import type { ActionReferenceGroupId } from "./actionReferenceGroups"; import { FORMATTER_CAMEL, + LINE, REMOVE, SET_SELECTION, SNIPPET_IF, @@ -26,6 +27,7 @@ import { pairedDelimiterReferences } from "./pairedDelimiterReferences"; import type { ReferenceEntry } from "./ReferenceEntry"; import { scopeReferences } from "./scopeReferences"; import { connectiveDefaultSpokenForms } from "./spokenForms/connectiveDefaultSpokenForms"; +import { markDefaultSpokenForms } from "./spokenForms/markDefaultSpokenForms"; const DEFAULT_PATTERN = `${VAR_SPOKEN_FORM} ${VAR_TARGET}`; const DEFAULT_COMMAND = `${VAR_SPOKEN_FORM} ${TARGET}`; @@ -43,6 +45,19 @@ const CURLY = pairedDelimiterReferences.curlyBrackets.defaultSpokenForm; const SQUARE = pairedDelimiterReferences.squareBrackets.defaultSpokenForm; const AT = connectiveDefaultSpokenForms.at; const ON = connectiveDefaultSpokenForms.on; +const SLICE = connectiveDefaultSpokenForms.verticalRange; +const CURRENT_SELECTION = markDefaultSpokenForms.cursor; + +const MULTI_TARGET_CURSOR_DESCRIPTION = + "When used with a list target, this action creates one cursor for each target."; +const CLONE_SELECTION_DESCRIPTION = + "After insertion, each selection moves to its newly created copy."; +const SCOPE_INSERTION_DESCRIPTION = + "Scope defaults to line. When used with a provided scope target, this action inserts the delimiters or spacing required for a new instance of that scope."; +const REORDER_DESCRIPTION = + "This action changes the order of multiple target contents. The targets can come from a list or range target, or from existing multiple selections."; +const PAIRED_DELIMITER_DESCRIPTION = + "See [paired delimiters](../README.md#paired-delimiters) for the available pairs."; type TalonSideActionType = "applyFormatter" | "nextHomophone"; @@ -52,6 +67,7 @@ export const actionReferences = { name: "Set selection", defaultSpokenForm: SET_SELECTION, group: { id: "cursor", index: 0 }, + description: MULTI_TARGET_CURSOR_DESCRIPTION, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -70,6 +86,7 @@ export const actionReferences = { name: "Set selection before", defaultSpokenForm: "pre", group: { id: "cursor", index: 1 }, + description: MULTI_TARGET_CURSOR_DESCRIPTION, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -88,6 +105,7 @@ export const actionReferences = { name: "Set selection after", defaultSpokenForm: "post", group: { id: "cursor", index: 2 }, + description: MULTI_TARGET_CURSOR_DESCRIPTION, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -277,6 +295,7 @@ export const actionReferences = { name: "Insert copy after", defaultSpokenForm: "clone", group: { id: "insert", index: 0 }, + description: CLONE_SELECTION_DESCRIPTION, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -295,6 +314,7 @@ export const actionReferences = { name: "Insert copy before", defaultSpokenForm: "clone up", group: { id: "insert", index: 1 }, + description: CLONE_SELECTION_DESCRIPTION, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -369,6 +389,8 @@ export const actionReferences = { name: "Swap targets", defaultSpokenForm: "swap", group: { id: "swap", index: 0 }, + description: + "When both operands contain multiple targets, their targets are paired by position and swapped.", syntaxes: [ { pattern: `${VAR_SPOKEN_FORM} ${WITH} ${VAR_TARGET}`, @@ -398,6 +420,8 @@ export const actionReferences = { name: "Move to target", defaultSpokenForm: "move", group: { id: "move", index: 0 }, + description: + "A target destination is replaced, while a position destination such as `before` or `after` inserts there. The source is removed from its original location in either case.", syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -465,7 +489,7 @@ export const actionReferences = { name: "Edit new line/scope before", defaultSpokenForm: "drink", group: { id: "emptyLines", index: 0 }, - description: "Scope defaults to line.", + description: SCOPE_INSERTION_DESCRIPTION, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -493,7 +517,7 @@ export const actionReferences = { name: "Edit new line/scope after", defaultSpokenForm: "pour", group: { id: "emptyLines", index: 1 }, - description: "Scope defaults to line.", + description: SCOPE_INSERTION_DESCRIPTION, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -521,6 +545,7 @@ export const actionReferences = { name: "Insert empty line/scope before", defaultSpokenForm: "drop", group: { id: "emptyLines", index: 2 }, + description: SCOPE_INSERTION_DESCRIPTION, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -543,6 +568,7 @@ export const actionReferences = { name: "Insert empty line/scope after", defaultSpokenForm: "float", group: { id: "emptyLines", index: 3 }, + description: SCOPE_INSERTION_DESCRIPTION, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -565,6 +591,7 @@ export const actionReferences = { name: "Insert empty lines/scopes around", defaultSpokenForm: "puff", group: { id: "emptyLines", index: 4 }, + description: SCOPE_INSERTION_DESCRIPTION, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -589,6 +616,7 @@ export const actionReferences = { name: "Reverse targets", defaultSpokenForm: "reverse", group: { id: "reorder", index: 0 }, + description: REORDER_DESCRIPTION, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -601,12 +629,21 @@ export const actionReferences = { command: `${VAR_SPOKEN_FORM} ${EVERY} ${ITEM} ${TARGET}`, description: `Reverses the collection items associated with the ${TARGET_DESC}.`, }, + { + command: `${VAR_SPOKEN_FORM} ${LINE} ${TARGET} ${SLICE} ${TARGET_2}`, + description: `Reverses the lines from the ${TARGET_DESC} through the ${TARGET_2_DESC}.`, + }, + { + command: `${VAR_SPOKEN_FORM} ${CURRENT_SELECTION}`, + description: "Reverses the current selections.", + }, ], }, randomizeTargets: { name: "Randomize targets", defaultSpokenForm: "shuffle", group: { id: "reorder", index: 1 }, + description: REORDER_DESCRIPTION, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -619,12 +656,21 @@ export const actionReferences = { command: `${VAR_SPOKEN_FORM} ${EVERY} ${ITEM} ${TARGET}`, description: `Randomizes the collection items associated with the ${TARGET_DESC}.`, }, + { + command: `${VAR_SPOKEN_FORM} ${LINE} ${TARGET} ${SLICE} ${TARGET_2}`, + description: `Randomizes the lines from the ${TARGET_DESC} through the ${TARGET_2_DESC}.`, + }, + { + command: `${VAR_SPOKEN_FORM} ${CURRENT_SELECTION}`, + description: "Randomizes the current selections.", + }, ], }, sortTargets: { name: "Sort targets", defaultSpokenForm: "sort", group: { id: "reorder", index: 2 }, + description: REORDER_DESCRIPTION, syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -637,6 +683,14 @@ export const actionReferences = { command: `${VAR_SPOKEN_FORM} ${EVERY} ${ITEM} ${TARGET}`, description: `Sorts the collection items associated with the ${TARGET_DESC}.`, }, + { + command: `${VAR_SPOKEN_FORM} ${LINE} ${TARGET} ${SLICE} ${TARGET_2}`, + description: `Sorts the lines from the ${TARGET_DESC} through the ${TARGET_2_DESC}.`, + }, + { + command: `${VAR_SPOKEN_FORM} ${CURRENT_SELECTION}`, + description: "Sorts the current selections.", + }, ], }, @@ -645,6 +699,7 @@ export const actionReferences = { name: "Wrap with paired delimiter/snippet", defaultSpokenForm: "wrap", group: { id: "wrap", index: 0 }, + description: PAIRED_DELIMITER_DESCRIPTION, syntaxes: [ { pattern: `${VAR_PAIR} ${VAR_SPOKEN_FORM} ${VAR_TARGET}`, @@ -672,6 +727,7 @@ export const actionReferences = { name: "Rewrap with paired delimiter", defaultSpokenForm: "repack", group: { id: "wrap", index: 1 }, + description: PAIRED_DELIMITER_DESCRIPTION, syntaxes: [ { pattern: `${VAR_PAIR} ${VAR_SPOKEN_FORM} ${VAR_TARGET}`, @@ -730,6 +786,7 @@ export const actionReferences = { name: "Rename", defaultSpokenForm: "rename", group: { id: "refactor", index: 0 }, + description: "Uses the editor's rename operation.", syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -748,6 +805,7 @@ export const actionReferences = { name: "Extract variable", defaultSpokenForm: "extract", group: { id: "refactor", index: 1 }, + description: "Uses the editor's extract-variable refactoring.", syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -765,6 +823,7 @@ export const actionReferences = { showQuickFix: { name: "Show quick fix", defaultSpokenForm: "quick fix", + description: "Shows the editor's quick fix menu.", group: { id: "refactor", index: 2 }, syntaxes: [ { @@ -786,6 +845,8 @@ export const actionReferences = { name: "Join lines", defaultSpokenForm: "join", group: { id: "joinBreak", index: 0 }, + description: + "When the target spans multiple lines, joins all of those lines; otherwise joins the target's line with the following line.", syntaxes: [ { pattern: DEFAULT_PATTERN, @@ -957,6 +1018,8 @@ export const actionReferences = { name: "Next homophone", defaultSpokenForm: "phones", group: { id: "homophones", index: 0 }, + description: + "Cycles through words that sound alike, such as changing `where` to `wear`.", syntaxes: [ { pattern: DEFAULT_PATTERN, diff --git a/packages/lib-common/src/references/scopeReferenceGroups.ts b/packages/lib-common/src/references/scopeReferenceGroups.ts index 8092f37351..b70322cadf 100644 --- a/packages/lib-common/src/references/scopeReferenceGroups.ts +++ b/packages/lib-common/src/references/scopeReferenceGroups.ts @@ -2,14 +2,14 @@ import type { ReferenceGroup } from "./ReferenceEntry"; export type ScopeReferenceGroupId = | "text" - | "sections" | "documentHierarchy" - | "notebook" | "collections" | "functions" | "objects" | "statements" | "markup" + | "sections" + | "notebook" | "private"; export const scopeReferenceGroups: ReferenceGroup[] = [ @@ -17,10 +17,6 @@ export const scopeReferenceGroups: ReferenceGroup[] = [ id: "text", name: "Text-based scopes", }, - { - id: "sections", - name: "Sections", - }, { id: "documentHierarchy", name: "Document hierarchy", @@ -45,6 +41,10 @@ export const scopeReferenceGroups: ReferenceGroup[] = [ id: "markup", name: "Markup and styles", }, + { + id: "sections", + name: "Sections", + }, { id: "notebook", name: "Notebook", diff --git a/packages/lib-common/src/references/scopeReferences.ts b/packages/lib-common/src/references/scopeReferences.ts index 05cfcba8ff..a091e48c51 100644 --- a/packages/lib-common/src/references/scopeReferences.ts +++ b/packages/lib-common/src/references/scopeReferences.ts @@ -302,141 +302,6 @@ export const scopeReferences = { ], }, - // Group: sections - section: { - name: "Section", - group: { id: "sections", index: 0 }, - defaultSpokenForm: "section", - syntaxes: [ - { - pattern: DEFAULT_PATTERN, - description: - "Heading and its content through the next heading of the same or higher level.", - cheatsheet: "Section", - }, - ], - examples: [ - { - command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${TARGET}`, - description: `Selects the section containing the ${TARGET_DESC}.`, - }, - ], - }, - sectionLevelOne: { - name: "Section level one", - group: { id: "sections", index: 1 }, - defaultSpokenForm: "one section", - disabledByDefault: true, - syntaxes: [ - { - pattern: DEFAULT_PATTERN, - description: "Level-one heading and its content.", - cheatsheet: "Section level one", - }, - ], - examples: [ - { - command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${TARGET}`, - description: `Selects the section level one containing the ${TARGET_DESC}.`, - }, - ], - }, - sectionLevelTwo: { - name: "Section level two", - group: { id: "sections", index: 2 }, - defaultSpokenForm: "two section", - disabledByDefault: true, - syntaxes: [ - { - pattern: DEFAULT_PATTERN, - description: "Level-two heading and its content.", - cheatsheet: "Section level two", - }, - ], - examples: [ - { - command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${TARGET}`, - description: `Selects the section level two containing the ${TARGET_DESC}.`, - }, - ], - }, - sectionLevelThree: { - name: "Section level three", - group: { id: "sections", index: 3 }, - defaultSpokenForm: "three section", - disabledByDefault: true, - syntaxes: [ - { - pattern: DEFAULT_PATTERN, - description: "Level-three heading and its content.", - cheatsheet: "Section level three", - }, - ], - examples: [ - { - command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${TARGET}`, - description: `Selects the section level three containing the ${TARGET_DESC}.`, - }, - ], - }, - sectionLevelFour: { - name: "Section level four", - group: { id: "sections", index: 4 }, - defaultSpokenForm: "four section", - disabledByDefault: true, - syntaxes: [ - { - pattern: DEFAULT_PATTERN, - description: "Level-four heading and its content.", - cheatsheet: "Section level four", - }, - ], - examples: [ - { - command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${TARGET}`, - description: `Selects the section level four containing the ${TARGET_DESC}.`, - }, - ], - }, - sectionLevelFive: { - name: "Section level five", - group: { id: "sections", index: 5 }, - defaultSpokenForm: "five section", - disabledByDefault: true, - syntaxes: [ - { - pattern: DEFAULT_PATTERN, - description: "Level-five heading and its content.", - cheatsheet: "Section level five", - }, - ], - examples: [ - { - command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${TARGET}`, - description: `Selects the section level five containing the ${TARGET_DESC}.`, - }, - ], - }, - sectionLevelSix: { - name: "Section level six", - group: { id: "sections", index: 6 }, - defaultSpokenForm: "six section", - disabledByDefault: true, - syntaxes: [ - { - pattern: DEFAULT_PATTERN, - description: "Level-six heading and its content.", - cheatsheet: "Section level six", - }, - ], - examples: [ - { - command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${TARGET}`, - description: `Selects the section level six containing the ${TARGET_DESC}.`, - }, - ], - }, - // Group: documentHierarchy part: { name: "Part", @@ -1140,6 +1005,141 @@ export const scopeReferences = { ], }, + // Group: sections + section: { + name: "Section", + group: { id: "sections", index: 0 }, + defaultSpokenForm: "section", + syntaxes: [ + { + pattern: DEFAULT_PATTERN, + description: + "Heading and its content through the next heading of the same or higher level.", + cheatsheet: "Section", + }, + ], + examples: [ + { + command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${TARGET}`, + description: `Selects the section containing the ${TARGET_DESC}.`, + }, + ], + }, + sectionLevelOne: { + name: "Section level one", + group: { id: "sections", index: 1 }, + defaultSpokenForm: "one section", + disabledByDefault: true, + syntaxes: [ + { + pattern: DEFAULT_PATTERN, + description: "Level-one heading and its content.", + cheatsheet: "Section level one", + }, + ], + examples: [ + { + command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${TARGET}`, + description: `Selects the section level one containing the ${TARGET_DESC}.`, + }, + ], + }, + sectionLevelTwo: { + name: "Section level two", + group: { id: "sections", index: 2 }, + defaultSpokenForm: "two section", + disabledByDefault: true, + syntaxes: [ + { + pattern: DEFAULT_PATTERN, + description: "Level-two heading and its content.", + cheatsheet: "Section level two", + }, + ], + examples: [ + { + command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${TARGET}`, + description: `Selects the section level two containing the ${TARGET_DESC}.`, + }, + ], + }, + sectionLevelThree: { + name: "Section level three", + group: { id: "sections", index: 3 }, + defaultSpokenForm: "three section", + disabledByDefault: true, + syntaxes: [ + { + pattern: DEFAULT_PATTERN, + description: "Level-three heading and its content.", + cheatsheet: "Section level three", + }, + ], + examples: [ + { + command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${TARGET}`, + description: `Selects the section level three containing the ${TARGET_DESC}.`, + }, + ], + }, + sectionLevelFour: { + name: "Section level four", + group: { id: "sections", index: 4 }, + defaultSpokenForm: "four section", + disabledByDefault: true, + syntaxes: [ + { + pattern: DEFAULT_PATTERN, + description: "Level-four heading and its content.", + cheatsheet: "Section level four", + }, + ], + examples: [ + { + command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${TARGET}`, + description: `Selects the section level four containing the ${TARGET_DESC}.`, + }, + ], + }, + sectionLevelFive: { + name: "Section level five", + group: { id: "sections", index: 5 }, + defaultSpokenForm: "five section", + disabledByDefault: true, + syntaxes: [ + { + pattern: DEFAULT_PATTERN, + description: "Level-five heading and its content.", + cheatsheet: "Section level five", + }, + ], + examples: [ + { + command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${TARGET}`, + description: `Selects the section level five containing the ${TARGET_DESC}.`, + }, + ], + }, + sectionLevelSix: { + name: "Section level six", + group: { id: "sections", index: 6 }, + defaultSpokenForm: "six section", + disabledByDefault: true, + syntaxes: [ + { + pattern: DEFAULT_PATTERN, + description: "Level-six heading and its content.", + cheatsheet: "Section level six", + }, + ], + examples: [ + { + command: `${SET_SELECTION} ${VAR_SPOKEN_FORM} ${TARGET}`, + description: `Selects the section level six containing the ${TARGET_DESC}.`, + }, + ], + }, + // Group: notebook notebookCell: { name: "Notebook cell", diff --git a/packages/tool-meta-updater/src/updateReferenceMdx.ts b/packages/tool-meta-updater/src/updateReferenceMdx.ts index 826d2dc04a..44b89d7a73 100644 --- a/packages/tool-meta-updater/src/updateReferenceMdx.ts +++ b/packages/tool-meta-updater/src/updateReferenceMdx.ts @@ -1,6 +1,7 @@ import type { FormatPluginFnOptions } from "@pnpm/meta-updater"; import type { ReferenceEntry } from "@cursorless/lib-common"; import { capitalize } from "@cursorless/lib-common"; +import { DISABLED_BY_DEFAULT } from "./util/constants"; import { formatVariables } from "./util/formatVariables"; import { injectSpokenForm } from "./util/injectSpokenForm"; @@ -62,7 +63,7 @@ export function updateReferenceMdx( } if (entry.disabledByDefault) { - spokenFormLines.push(bold("Disabled by default")); + spokenFormLines.push(DISABLED_BY_DEFAULT); } if (spokenFormLines.length > 0) { @@ -104,10 +105,6 @@ function code(value: string) { return `\`${value}\``; } -function bold(value: string) { - return `**${value}**`; -} - function formatGroup(lines: string[]): string[] { return lines.map((line, index) => index < lines.length - 1 ? `${line}\\` : line, diff --git a/packages/tool-meta-updater/src/updateReferenceReadmeMd.ts b/packages/tool-meta-updater/src/updateReferenceReadmeMd.ts index 8be2374d56..2062977c15 100644 --- a/packages/tool-meta-updater/src/updateReferenceReadmeMd.ts +++ b/packages/tool-meta-updater/src/updateReferenceReadmeMd.ts @@ -1,6 +1,7 @@ import type { FormatPluginFnOptions } from "@pnpm/meta-updater"; import type { ReferenceEntry, ReferenceGroup } from "@cursorless/lib-common"; import { cleanId } from "./util/cleanId"; +import { DISABLED_BY_DEFAULT } from "./util/constants"; import { formatVariables } from "./util/formatVariables"; import { injectSpokenForm } from "./util/injectSpokenForm"; @@ -30,13 +31,18 @@ export function updateReferenceReadmeMd( for (const [rawId, entry] of groupEntries) { const id = cleanId(rawId); + const disabledByDefault = entry.disabledByDefault + ? ` (${DISABLED_BY_DEFAULT})` + : ""; for (const syntax of entry.syntaxes) { const pattern = injectSpokenForm( syntax.pattern, entry.defaultSpokenForm, ); const description = formatVariables(syntax.description); - expected.push(`- [\`"${pattern}"\`](./${id}.mdx) - ${description}`); + expected.push( + `- [\`"${pattern}"\`](./${id}.mdx) - ${description}${disabledByDefault}`, + ); } } diff --git a/packages/tool-meta-updater/src/util/constants.ts b/packages/tool-meta-updater/src/util/constants.ts new file mode 100644 index 0000000000..4eedfe3500 --- /dev/null +++ b/packages/tool-meta-updater/src/util/constants.ts @@ -0,0 +1 @@ +export const DISABLED_BY_DEFAULT = "**Disabled by default**";