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
233 changes: 2 additions & 231 deletions packages/app-web-docs/src/docs/user/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <TARGET>"`: Selects the given target.
- `"pre <TARGET>"`: Places the cursor before the given target.
- `"post <TARGET>"`: Places the cursor after the given target.
- `"append <TARGET>"`: Selects the given target, while preserving your existing selections.
- `"append pre <TARGET>"`: Adds a new cursor before the given target, while preserving your existing selections.
- `"append post <TARGET>"`: Adds a new cursor after the given target, while preserving your existing selections.
- `"give <TARGET>"`: 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 <TARGET>"`
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 <TARGET>"`
- `"clone up <TARGET>"`

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 <TARGET>"`: cut
- `"copy <TARGET>"`: 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 `<Target 1>` and `<Target 2>` each consist of multiple targets, they will be zipped together.

- `"swap <TARGET 1> with <TARGET 2>"`
- `"swap with <TARGET>"`
- `"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 <TARGET>"` decreases the indentation level of `<TARGET>`
- `"indent <TARGET>"` increases the indentation level of `<TARGET>`

For example:

- `"indent air"`
- `"dedent funk bat"`

### Increment / decrement

- `"increment <TARGET>"`: increment number target. eg change `1` to `2`.
- `"decrement <TARGET>"`: decrement number target. eg change `2` to `1`.

### Insert empty lines

- `"drink <TARGET>"`: Inserts a new line above the target line, and moves the cursor to the newly created line
- `"pour <TARGET>"`: Inserts a new line below the target line, and moves the cursor to the newly created line
- `"drop <TARGET>"`: Inserts an empty line above the target line (without moving the cursor)
- `"float <TARGET>"`: Inserts an empty line below the target line (without moving the cursor)
- `"puff <TARGET>"`: 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 <TARGET>"`

eg:

- `"phones air"`
- `"phones first word air"`

### Rename

Executes vscode rename action on the specified target

- `"rename <TARGET>"`

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 <TARGET>"`: top
- `"center <TARGET>"`: center
- `"bottom <TARGET>"`: 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 <TARGET>"`: Inserts the given target at the cursor position
- `"bring <TARGET 1> to <TARGET 2>"`

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 <TARGET>"`: Moves the given target to the cursor position
- `"move <TARGET 1> to <TARGET 2>"`: 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 <TARGET>"`
- `"sort every item <TARGET>"`
- `"reverse every item <TARGET>"`
- `"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 <TARGET>"`: wraps the target with parentheses
- `"box wrap <TARGET>"`: 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 <TARGET>"`: 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 <TARGET>"` navigate to the definition of the target
- `"reference <TARGET>"` search the workspace for all references to the target
- `"hover <TARGET>"` displays the tooltip that would appear if you hovered the mouse over the target
- `"quick fix <TARGET>"` displays quick fixes and refactors suggested by the vscode
- `"scout <TARGET>"` search the document for the target
- `"scout all <TARGET>"` 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 <TARGET>"`
- `"unfold <TARGET>"`

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 <TARGET>"`

eg:
`extract call air`

Extracts the function call containing the decorated 'a' into its own variable.

### Join

Join multiple lines together.

- `"join <TARGET>"`

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 <TARGET>"`

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

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

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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ sidebar_label: Extract

# Extract (Extract variable)

Uses the editor's extract-variable refactoring.

Cursorless ID: `extractVariable`

## Spoken form
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions packages/app-web-docs/src/docs/user/actions/joinLines.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
2 changes: 2 additions & 0 deletions packages/app-web-docs/src/docs/user/actions/rename.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ sidebar_label: Rename

# Rename

Uses the editor's rename operation.

Cursorless ID: `rename`

## Spoken form
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading