From 606534d054768a1f1265f78d10ec5266013f0ea0 Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Sat, 17 Jun 2023 22:56:08 -0500 Subject: [PATCH 01/26] intro doc first draft with some concepts and no example walk throughs --- docs/user/intro.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/user/intro.md diff --git a/docs/user/intro.md b/docs/user/intro.md new file mode 100644 index 0000000000..b4c82b1cfc --- /dev/null +++ b/docs/user/intro.md @@ -0,0 +1,80 @@ +# Introduction + +This document will try to explicitly bring together a few concepts that underlie a lot of cursorless behavior, then walk through some example editing operations that are common but perhaps tricky to a beginner. + +## Some Important Concepts + +### Commands Have An Action And A Target Or Two + +Commands have an action and a target or two. `"chuck air"` has the action `"chuck"` and one target (the `"air"` token). +`"bring air to bat"` has the action `"bring"` and two targets (the `"air"` and `"bat"` tokens). + +A target can be more than a single token or line. A target can be a range, like `"air past bat"` that spans from the `"air"` token to the `"bat"` token, and that is still considered _one_ target. +A target can even be a vertical slice or list, like the list `"air and bat"`. +Doing `"take air and bat"` will result in multiple selections and multiple cursors, but it is still one target. + +Commands with two targets often require a separator word between the two targets, like the `"to"` in `"move air to bat"`. +The separator may seem trivial now, but it is easier to forget it when you start using fancy targets. + +### Targets Can Be Modified + +A target starts as a mark (`"this"`, `"row ten"`, `"green curve air"`, etc) and target modifiers can be applied to suit your needs. +A big part of feeling comfortable and productive with Cursorless is getting familiar with the most useful mark types and target modifiers. +All of the [mark types](README.md#Marks) are worth knowing. +There are a lot of target modifiers, in this document will try to help you learn the most important ones through examples. + +The big difference between a simple command `"bring air to bat"` and the intimidating `"bring next three tokens air to after just line bat"` is the addition of target modifiers. +Target modifiers are often chained. `"after just line"` is a chain of three modifiers and they are applied in reverse order (`"line"`, then `"just"`, then `"after"`). + +### Targets Sometimes Include Their Delimiter Depending On The Action And Modifiers + +Some actions will operate on the specified target, and some actions will additionally operate on a delimiter that leads/trails the target. + +The command `"take air"` will select a token. +The command `"chuck air"` will delete a token _and_ a leading/trailing space (if there is an appropriate one). +Likewise, `"chuck block air"` will delete a block _and_ a leading/trailing empty line (if appropriate). + +These default behaviors usually do what you want. +If you have the sentence `apple banana cherry` and run the command `"chuck bat"`, you usually don't want to end up with `apple cherry` (note the two spaces), so the command deletes a token and an appropriate token delimiter. + +Here are some target types and their delimiters... + +- Character or word within a token: nothing +- Token: space +- Argument and item: comma and space +- Line: line ending +- Block: empty line + +Whether a command operates on delimiters can be changed by a target modifier. +`"chuck just bat"` will not delete any spaces; the `"just"` causes the command to ignore delimiters. +`"take just just just bat"` does the same as `"take bat"`. + +Special positional target modifiers `"before"` and `"after"` try to work with delimiters. +`"bring line to after row ten"` will bring a copy of the current line content _with line delimiter_ to after line 10, meaning there will be an additional line (a new line 11). + +Special positional target modifiers `"start of"` and `"end of"` do not use delimiters. +`"bring line to end of row ten"` will bring a copy of the current line content _without line delimiter_ to the end of line 10, meaning line 10 will get content added to it. + +## Some Of The More Useful Actions + +Here are some of the most useful actions. +Parts in square braces (`[]`) are optional. +Targets are represented by `T` with a possible digit. + +- Core Changers + - `"bring T1 [to T2]"`: replace selection/T2 with T + - `"move T1 [to T2]"` + - `"chuck T"`: delete T + - `"change T"`: delete T and set cursor(s) to where T was + - `"drink/pour T"`: edit new line before/after T +- Selection Manipulation + - `"take T"`: set selection + - `"give T"`: deselect + - `"pre/post T"`: set selection before/after T +- Clipboard + - `"paste to T"` + - `"carve/copy T"`: cut/copy T + +## Examples With Walkthroughs + +TODO From 0bdd1a73ce8009ec9b895c15ffe721759fd144cd Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Sun, 18 Jun 2023 22:27:36 -0500 Subject: [PATCH 02/26] pokey suggestion for intro.md Co-authored-by: Pokey Rule <755842+pokey@users.noreply.github.com> --- docs/user/intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/intro.md b/docs/user/intro.md index b4c82b1cfc..6f0aef193b 100644 --- a/docs/user/intro.md +++ b/docs/user/intro.md @@ -21,7 +21,7 @@ The separator may seem trivial now, but it is easier to forget it when you start A target starts as a mark (`"this"`, `"row ten"`, `"green curve air"`, etc) and target modifiers can be applied to suit your needs. A big part of feeling comfortable and productive with Cursorless is getting familiar with the most useful mark types and target modifiers. All of the [mark types](README.md#Marks) are worth knowing. -There are a lot of target modifiers, in this document will try to help you learn the most important ones through examples. +While there are many target modifiers, this document will help you get started fast by focusing on the most important modifiers to learn first. The big difference between a simple command `"bring air to bat"` and the intimidating `"bring next three tokens air to after just line bat"` is the addition of target modifiers. Target modifiers are often chained. `"after just line"` is a chain of three modifiers and they are applied in reverse order (`"line"`, then `"just"`, then `"after"`). From a1ba7df290e377c50c805def91f0c426680c0566 Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Sun, 18 Jun 2023 22:58:17 -0500 Subject: [PATCH 03/26] intro.md, remove "to" from "to after" Co-authored-by: Pokey Rule <755842+pokey@users.noreply.github.com> --- docs/user/intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/intro.md b/docs/user/intro.md index 6f0aef193b..ee66453b43 100644 --- a/docs/user/intro.md +++ b/docs/user/intro.md @@ -50,7 +50,7 @@ Whether a command operates on delimiters can be changed by a target modifier. `"take just just just bat"` does the same as `"take bat"`. Special positional target modifiers `"before"` and `"after"` try to work with delimiters. -`"bring line to after row ten"` will bring a copy of the current line content _with line delimiter_ to after line 10, meaning there will be an additional line (a new line 11). +`"bring line after row ten"` will bring a copy of the current line content _with line delimiter_ after line 10, meaning there will be an additional line (a new line 11). Special positional target modifiers `"start of"` and `"end of"` do not use delimiters. `"bring line to end of row ten"` will bring a copy of the current line content _without line delimiter_ to the end of line 10, meaning line 10 will get content added to it. From b31db45dc290635986e737e4a8f5af0dd0e16cf1 Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Mon, 19 Jun 2023 16:44:17 -0500 Subject: [PATCH 04/26] refine concept sections --- docs/user/intro.md | 79 +++++++++++++++++++++++++++------------------- 1 file changed, 47 insertions(+), 32 deletions(-) diff --git a/docs/user/intro.md b/docs/user/intro.md index ee66453b43..634f240d01 100644 --- a/docs/user/intro.md +++ b/docs/user/intro.md @@ -1,61 +1,70 @@ -# Introduction +# Guide to intermediate level Cursorless This document will try to explicitly bring together a few concepts that underlie a lot of cursorless behavior, then walk through some example editing operations that are common but perhaps tricky to a beginner. +This document assumes that you understand the very basics of cursorless, like what commands `"take air"` and `"chuck line"` do. +If you don't have the basics down, please read some of [the main documentation page](README.md) and/or watch [the Cursorless tutorial videos](https://www.youtube.com/watch?v=5mAzHGM2M0k&list=PLXv2sppxeoQZz49evjy4T0QJRIgc_JPqs). -## Some Important Concepts +It is planned for this guide to be expanded to both basic and advanced levels. -### Commands Have An Action And A Target Or Two +## Some important concepts + +### Commands have an action and a target or two Commands have an action and a target or two. `"chuck air"` has the action `"chuck"` and one target (the `"air"` token). `"bring air to bat"` has the action `"bring"` and two targets (the `"air"` and `"bat"` tokens). -A target can be more than a single token or line. A target can be a range, like `"air past bat"` that spans from the `"air"` token to the `"bat"` token, and that is still considered _one_ target. +A target can be more than a single token or line. A target can be a [range](README.md#range-targets), like `"air past bat"` that spans from the `"air"` token to the `"bat"` token, and that is still considered _one_ target. A target can even be a vertical slice or list, like the list `"air and bat"`. Doing `"take air and bat"` will result in multiple selections and multiple cursors, but it is still one target. -Commands with two targets often require a separator word between the two targets, like the `"to"` in `"move air to bat"`. -The separator may seem trivial now, but it is easier to forget it when you start using fancy targets. - -### Targets Can Be Modified +### Targets can be modified -A target starts as a mark (`"this"`, `"row ten"`, `"green curve air"`, etc) and target modifiers can be applied to suit your needs. +A target contains a mark (ex: `"this"`, `"row ten"`, `"green curve air"`, etc) and target modifiers can be prefixed to suit your needs. A big part of feeling comfortable and productive with Cursorless is getting familiar with the most useful mark types and target modifiers. All of the [mark types](README.md#Marks) are worth knowing. While there are many target modifiers, this document will help you get started fast by focusing on the most important modifiers to learn first. -The big difference between a simple command `"bring air to bat"` and the intimidating `"bring next three tokens air to after just line bat"` is the addition of target modifiers. -Target modifiers are often chained. `"after just line"` is a chain of three modifiers and they are applied in reverse order (`"line"`, then `"just"`, then `"after"`). +The biggest difference between the simple `"bring air to bat"` and the intimidating `"bring next three lines air to tail block bat"` is the addition of target modifiers. +Target modifiers are often chained. `"tail block"` is a chain of two modifiers and they are applied in reverse order (`"block"`, then `"tail"`). + +Modifier chains can be applied to each [primitive target](README.md#primitive-targets) in a [compound target](README.md#compound-targets). +For instance, `"take tail line air and head block bat"` has chain `"tail line"` applied to `"air"` and chain `"head block"` applied to `"bat"`. + +### Some targets are destinations -### Targets Sometimes Include Their Delimiter Depending On The Action And Modifiers +Commands like `"paste"`, `"bring"`, and `"move"` have a target that is a destination. +Destinations are special. +Targets are converted into destinations using a destination converter (`"to"`, `"before"`, `"after"`); that is why you have to say commands like `"bring air to bat"` or `"bring air before bat"`. +The `"to"` might seem like cursorless is trying to resemble a sentence, but `"to"` actually serves a technical purpose of explicitly converting to a destination. + +Your destinations should start with a single destination converter before you add modifiers and/or a mark. + +### Targets sometimes include a delimiter Some actions will operate on the specified target, and some actions will additionally operate on a delimiter that leads/trails the target. The command `"take air"` will select a token. -The command `"chuck air"` will delete a token _and_ a leading/trailing space (if there is an appropriate one). -Likewise, `"chuck block air"` will delete a block _and_ a leading/trailing empty line (if appropriate). +The command `"chuck air"` will delete a token _and_ leading/trailing spaces (if appropriate ones exist). +Likewise, `"chuck block air"` will delete a block _and_ leading/trailing empty lines (if appropriate ones exist). These default behaviors usually do what you want. -If you have the sentence `apple banana cherry` and run the command `"chuck bat"`, you usually don't want to end up with `apple cherry` (note the two spaces), so the command deletes a token and an appropriate token delimiter. +If you have the sentence `apple banana cherry` and run the command `"chuck bat"`, you usually don't want to end up with `apple cherry` (note the two spaces), so the command deletes a token and appropriate token delimiter. Here are some target types and their delimiters... -- Character or word within a token: nothing -- Token: space -- Argument and item: comma and space -- Line: line ending -- Block: empty line +- Character or word within a token: nothing. +- Token: space. +- Argument and item: comma and space. +- Line: line ending. +- Block: empty line. -Whether a command operates on delimiters can be changed by a target modifier. -`"chuck just bat"` will not delete any spaces; the `"just"` causes the command to ignore delimiters. -`"take just just just bat"` does the same as `"take bat"`. - -Special positional target modifiers `"before"` and `"after"` try to work with delimiters. -`"bring line after row ten"` will bring a copy of the current line content _with line delimiter_ after line 10, meaning there will be an additional line (a new line 11). +Destination converters `"before"` and `"after"` try to work with delimiters. +`"bring air before bat"` will bring a copy of the `"air"` token _with token delimiter (space)_ before the `"bat"` token giving you something like `"aaa bbb"`. Special positional target modifiers `"start of"` and `"end of"` do not use delimiters. -`"bring line to end of row ten"` will bring a copy of the current line content _without line delimiter_ to the end of line 10, meaning line 10 will get content added to it. +`"bring air to start of bat"` will bring a copy of the `"air"` token _without token delimiter (space)_ before the `"bat"` token, giving you something like `"aaabbb"`. -## Some Of The More Useful Actions +## Some of the more useful actions Here are some of the most useful actions. Parts in square braces (`[]`) are optional. @@ -63,18 +72,24 @@ Targets are represented by `T` with a possible digit. - Core Changers - `"bring T1 [to T2]"`: replace selection/T2 with T + - `"bring T1 before/after T2"`: - `"move T1 [to T2]"` - - `"chuck T"`: delete T + - `"chuck T"`: delete T and appropriate delimiter - `"change T"`: delete T and set cursor(s) to where T was - `"drink/pour T"`: edit new line before/after T - Selection Manipulation - `"take T"`: set selection - - `"give T"`: deselect - `"pre/post T"`: set selection before/after T - Clipboard - - `"paste to T"` + - `"paste to/before/after T"` - `"carve/copy T"`: cut/copy T -## Examples With Walkthroughs +## Examples with walkthroughs TODO + +## Some reminders for the author about advanced level content + +Whether a command operates on delimiters can be changed by a target modifier. +`"chuck just bat"` will not delete any spaces; the `"just"` causes the command to ignore delimiters. +`"take just just just bat"` does the same as `"take bat"`. From 2a0950c9cec6ce3d89b81c0cd24d5957bf0c326b Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Fri, 23 Jun 2023 14:45:03 -0500 Subject: [PATCH 05/26] some line examples --- docs/user/intro.md | 50 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/docs/user/intro.md b/docs/user/intro.md index 634f240d01..a24f9b0705 100644 --- a/docs/user/intro.md +++ b/docs/user/intro.md @@ -86,7 +86,55 @@ Targets are represented by `T` with a possible digit. ## Examples with walkthroughs -TODO +### TO BE CATEGORIZED + +### Simple line operations + +Cursorless might feel token oriented at the beginning, but line operations and feel very natural, especially with use of `"before"` and `"after"`. + +#### Bringing a copy of a line to another line + +Here is a detailed example: + +- `"bring row 7 after line"` to bring a copy of [row](README.md#row-number) 7 to after the current line (or after the last selected line if you have a selection). + - The following will assume that before the command, nothing was selected and there was only one cursor. + - The command is using a [`"row"` mark](README.md#row-number) as a source. + `"row"` marks are especially useful for lines far away from your cursor. + - The destination has the mark `"line"`, which is more explicitly `"line this"`. + The [`"this"` mark](README.md#this) starts the target as the cursor (remember that we are assuming no selections). + The [`"line"` modifier](README.md#line) expands the target to the line containing the cursor. + The `"after"` converts the line-based target to a line-based destination that is after the target. + - Because the destination was an `"after"`, the `"bring"` command also inserts a delimiter that is appropriate for the destination when bringing a copy of the source to the destination. + +And some more examples: + +- `"bring row 7 to line"`, unlike the previous command, uses `"to"` instead of `"after"` for the destination converter. + The command will replace the current line (or line-expanded selection if you had a selection) with the contents of row 7. +- `"bring line air to line"` will replace the current line with the contents of the line that contains the `"air"` token. +- `"bring row 7"`. + If you have a selection, the selection is replaced with the contents of row 7. + If you don't have a selection, the contents of row 7 are inserted at your cursor. +- `"bring up 2"` is similar to the previous command, but uses the `"down "` and `"up "` [mark type](README.md#up-number--down-number). + +Copying a line to an adjacent line has some specialized command support: + +- `"clone row 7"` will put a copy of row 7 after the original row 7. +- `"clone line"` is very common and will move your cursor to the new line. +- `"clone up line"` puts the copy before the original. + - The useful difference from `"clone line"` is that your cursor moves up to the new line so that you are editing the "top" line rather than the "bottom" line. + - `"clone up row 7"` only differs from `"clone row 7"` if your cursor is on row 7. + +#### Operating on multiple lines + +You can operate on multiple lines at a time: + +- `"chuck 3 lines row 7"` will delete three lines starting at row 7. + - The command uses a [relative scope modifier](README.md#previous--next--ordinal--number) (`"3 lines"`) to expand the target to be three lines (proceeding forward). +- `"bring 3 lines row 7 to 2 lines row 12"` replaces the two lines starting at row 12 with the three lines starting at row 7. + Both destinations and sources can be multiple lines. +- `"chuck 3 lines air"` will delete three full lines starting at the line that contains the `"air"` token. + - This command shows that you should not think of these commands as having a length and a start point; think of them as a mark and zero or more modifiers that expand or shift the target. +- TODO MAYBE: lines backwards & next & previous & next lines ## Some reminders for the author about advanced level content From 8eafc233dcaa5cea6615a967077535a2f62c984d Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Mon, 24 Jul 2023 11:31:48 -0500 Subject: [PATCH 06/26] add more examples and highlight of more useful modifiers --- docs/user/intro.md | 174 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 162 insertions(+), 12 deletions(-) diff --git a/docs/user/intro.md b/docs/user/intro.md index a24f9b0705..8f7bf32264 100644 --- a/docs/user/intro.md +++ b/docs/user/intro.md @@ -71,9 +71,10 @@ Parts in square braces (`[]`) are optional. Targets are represented by `T` with a possible digit. - Core Changers - - `"bring T1 [to T2]"`: replace selection/T2 with T - - `"bring T1 before/after T2"`: - - `"move T1 [to T2]"` + - `"bring T"`: insert a copy of T at the cursor/selection. + - `"bring T1 to T2"`: replace T2 with T + - `"bring T1 before/after T2"`: insert a copy of T1 before/after T2, including appropriate delimiters. + - `"move T1 [to/before/after T2]"`: like `"bring"`, but moves instead of copies - `"chuck T"`: delete T and appropriate delimiter - `"change T"`: delete T and set cursor(s) to where T was - `"drink/pour T"`: edit new line before/after T @@ -84,13 +85,52 @@ Targets are represented by `T` with a possible digit. - `"paste to/before/after T"` - `"carve/copy T"`: cut/copy T -## Examples with walkthroughs +## Some of the more useful modifiers -### TO BE CATEGORIZED +Here are some very useful modifiers: -### Simple line operations +- Syntactic scopes ([reference](README.md#syntactic-scopes)) are great for expanding the target to what you want to operate on, like the containing function. + - `"arg"`, often used to involve commas, like `"chuck arg air"` or `"bring air after arg bat"` that take care of commas. + - `"funk"` for function. + - `"state"` for statement (which might span multiple lines or only part of a line). +- Other modifiers that are like syntactic scopes in that they expand the target. + - [`"file"`](README.md#file) for the whole file. + - [`"block"`](README.md#block) for a contiguous block of non-empty lines. + - [`"line"`](README.md#line), often used in commands like `"chuck line"`. + - [`"paint"`](README.md#paint) for contiguous sequence of non-white space characters. + - [`"token"`](README.md#token). + - [`"word"`](README.md#word) allows you to refer to words within a snake_case or camelCase token. + - [`"char"`](README.md#char) for individual characters. -Cursorless might feel token oriented at the beginning, but line operations and feel very natural, especially with use of `"before"` and `"after"`. +And you can reuse the above scopes when using [relative/ordinal modifiers](README.md#previous--next--ordinal--number). +Some examples: + +- `"[number] [scope]s"`, like `"chuck three lines row 12"` to delete rows 12-14. +- `"[number] [scope]s backward"`, like `"chuck three lines backward row 12"` to delete rows 10-12. +- `"[nth] [scope]"`, like `"chuck second word air"` to delete "Banana" from "appleBananaCherry". +- `"[nth] last [scope]"`, like `"chuck last char air"` to delete "s" from "apples". +- `"next/previous [scope]"`, like `"chuck until next token"` to delete everything from the cursor/selection to the next token. + +`"past"`, `"until"`, and `"and"` are good ways to build up targets. + +- `"chuck row 7 past row 9"` to delete rows 7 through 9. +- `"chuck air until bat"` to delete tokens starting at the air token ending just before the bat token. +- `"chuck row 7 and row 10"` to delete rows 7 and 10. + +There is also `"head"` and `"tail"` to expand a target through to the beginning or end of the line. +`"take head air"` selects the air token through to the beginning of air's line. +When followed by a modifier, they will expand their input to the start or end of the given modifier range. +`"take head funk"` will select from the cursor the start of the containing function. + +## Examples of some common operations + +The below examples are supposed to show you how to do some of the most common text editing operations, especially the +operations that might not be initially obvious how to do because of their use of multiple concepts in combination. + +### "Line operations + +Cursorless might feel token oriented at the beginning, but line operations can feel very natural, especially with use of `"before"` and `"after"`. +Also, a lot of the line-based examples can be adapted to tokens, blocks, and so on. #### Bringing a copy of a line to another line @@ -124,6 +164,9 @@ Copying a line to an adjacent line has some specialized command support: - The useful difference from `"clone line"` is that your cursor moves up to the new line so that you are editing the "top" line rather than the "bottom" line. - `"clone up row 7"` only differs from `"clone row 7"` if your cursor is on row 7. +`"clone"` commands on a line also bring the existing hats to the new line, so you can chain commands to operate on the new line without waiting for the clone to complete and see the new hats. +Sidenote: `"clone"` can operate on many types of targets, but lines, blocks, functions, and statements are the most common. + #### Operating on multiple lines You can operate on multiple lines at a time: @@ -134,10 +177,117 @@ You can operate on multiple lines at a time: Both destinations and sources can be multiple lines. - `"chuck 3 lines air"` will delete three full lines starting at the line that contains the `"air"` token. - This command shows that you should not think of these commands as having a length and a start point; think of them as a mark and zero or more modifiers that expand or shift the target. -- TODO MAYBE: lines backwards & next & previous & next lines +- `"chuck row 7 past row 9"` uses the `"past"` modifier to delete row 7 through row 9. + +#### Joining lines + +It is common to want to join lines. +For example, to go from... + +```markdown +apple +banana +``` + +to... + +```markdown +apple banana +``` + +There are a few ways to join lines. +Remember, not everything needs to be done in Cursorless. +Talon's community config repo [has](https://github.com/talonhub/community/blob/468fb16392e6a9907cb98e2526c1e5cbf3b5fc8d/apps/vscode/vscode.talon#L265) `join lines: user.vscode("editor.action.joinLines")`. +Using that command will join the current line with the line below it. +Or, if you have a multi-line selection, then it will join all the selected lines. + +Also, you can [customize Cursorless](customization.md##experimental-cursorless-custom-ide-actions) so you can invoke the vscode operation `editor.action.joinLines` with a Cursorless command and target. +In your Cursorless settings `experimental/actions_custom.csv` file, if you add `join, editor.action.joinLines`, then you can do Cursorless commands like `"join row 7"` to join row 7 and row 8 or `"join 5 lines row 7"` to join 5 lines starting at row 7. + +vscode's `editor.action.joinLines` puts a space between joined lines. +If you want to join lines without a space, `"move to end of "` or `"move to start of "` are an approach you could take. + +- `"move down 1 to end of line"` if your cursor is on the top line. +- `"move row 7 to start of row 8"` for any two lines regardless or cursor position. + +#### Splitting lines + +Sometimes you want to split a line into multiple lines. +For instance, for this... + +```typescript +someCode(); // some comment +``` + +to become this... + +```typescript +// some comment +someCode(); +``` + +`"move tail before its line"` will do the split starting at `""` (`"slash"` for the example above). +First, the `"tail "` expands the target from the mark to everything until the end of the line. +The `"its line"` makes Cursorless re-use the previous mark (from `"tail "`) and expand to the corresponding line. +The overall `"move ... before ..."` structure moves the tail portion to before the line. + +Or, you might want to do the other split, where the tail goes below. +Where this... + +```typescript +apple banana cherry date +``` + +becomes this... + +```typescript +apple banana +cherry date +``` + +`"move tail after its line"` will do the above split. + +### Subtoken changes + +Cursorless also has good support for operating on parts of a token. +Cursorless can recognize and operate on words within a snake_case, camelCase, or PascalCase token. + +- `"chuck third word air"` or `"chuck last word air"` to delete `"_cherry"` from `"apple_banana_cherry"`. +- `"change second word past third word air"` to delete `"BananaCherry"` from `"AppleBananaCherryDate"`. +- `"chuck last 2 words air"` to delete the last two words of the air token. +- `"chuck tail token third word air"` to delete from the third word to the last word of the air token. + It is probably easier to do `"chuck third word past last word air"`. +- `"bring 2 words third word air to last word bat"` will replace the last word of the bat token with some words from the air token. + +Similar things can be done on characters, like `"chuck last char air"` to delete `"s"` from `"apples"`. + +### Arg and item changes + +The `"arg"` (argument to a function call) and `"item"` (item in a list, map, or object) modifiers are often helpful because they are comma-aware. + +- `"chuck arg bat"` is a good way to go from `someFunction(apple, banana + otherStuff, cherry)` to `someFunction(apple, cherry)`. + The command deletes the argument and the appropriate delimiters (comma and a space). +- `"bring bat after arg air"` lets you go from `someFunction(apple, cherry)` to `someFunction(apple, banana, cherry)`, again taking care of commas and spaces. +- `"chuck item air"` can go from `someMap = { key1: "apple", key2: "banana" }` to `someMap = { key2: "banana" }`. + +### Delimeter-only changes + +You can use `"leading"` and `"trailing"` to target delimiters themselves. + +- `"chuck leading and trailing air"` to delete the spaces around the air token. +- `"chuck leading block` will delete the empty lines before the current block. + +But `"leading"` and `"trailing"` are not always needed to mess with delimiters. + +- `"chuck until next token"` will delete spaces from the cursor to the next token. + +## What's next -## Some reminders for the author about advanced level content +Eventually there will be more guide-like documentation on the more advanced concepts. +In the meantime, here are a few more useful concepts to look into. -Whether a command operates on delimiters can be changed by a target modifier. -`"chuck just bat"` will not delete any spaces; the `"just"` causes the command to ignore delimiters. -`"take just just just bat"` does the same as `"take bat"`. +- [pair operations](README.md#surrounding-pair), with [list of paired delimiters](README.md#paired-delimiters) +- [snippets](experimental/snippets.md) +- [every](README.md#every) +- [instance](README.md#instance) +- [just](README.md#just) From 26070d7af2f46cf1bd7adbfc7bff713003f32e58 Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Sat, 17 Jun 2023 22:56:08 -0500 Subject: [PATCH 07/26] intro doc first draft with some concepts and no example walk throughs --- docs/user/intro.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/user/intro.md diff --git a/docs/user/intro.md b/docs/user/intro.md new file mode 100644 index 0000000000..b4c82b1cfc --- /dev/null +++ b/docs/user/intro.md @@ -0,0 +1,80 @@ +# Introduction + +This document will try to explicitly bring together a few concepts that underlie a lot of cursorless behavior, then walk through some example editing operations that are common but perhaps tricky to a beginner. + +## Some Important Concepts + +### Commands Have An Action And A Target Or Two + +Commands have an action and a target or two. `"chuck air"` has the action `"chuck"` and one target (the `"air"` token). +`"bring air to bat"` has the action `"bring"` and two targets (the `"air"` and `"bat"` tokens). + +A target can be more than a single token or line. A target can be a range, like `"air past bat"` that spans from the `"air"` token to the `"bat"` token, and that is still considered _one_ target. +A target can even be a vertical slice or list, like the list `"air and bat"`. +Doing `"take air and bat"` will result in multiple selections and multiple cursors, but it is still one target. + +Commands with two targets often require a separator word between the two targets, like the `"to"` in `"move air to bat"`. +The separator may seem trivial now, but it is easier to forget it when you start using fancy targets. + +### Targets Can Be Modified + +A target starts as a mark (`"this"`, `"row ten"`, `"green curve air"`, etc) and target modifiers can be applied to suit your needs. +A big part of feeling comfortable and productive with Cursorless is getting familiar with the most useful mark types and target modifiers. +All of the [mark types](README.md#Marks) are worth knowing. +There are a lot of target modifiers, in this document will try to help you learn the most important ones through examples. + +The big difference between a simple command `"bring air to bat"` and the intimidating `"bring next three tokens air to after just line bat"` is the addition of target modifiers. +Target modifiers are often chained. `"after just line"` is a chain of three modifiers and they are applied in reverse order (`"line"`, then `"just"`, then `"after"`). + +### Targets Sometimes Include Their Delimiter Depending On The Action And Modifiers + +Some actions will operate on the specified target, and some actions will additionally operate on a delimiter that leads/trails the target. + +The command `"take air"` will select a token. +The command `"chuck air"` will delete a token _and_ a leading/trailing space (if there is an appropriate one). +Likewise, `"chuck block air"` will delete a block _and_ a leading/trailing empty line (if appropriate). + +These default behaviors usually do what you want. +If you have the sentence `apple banana cherry` and run the command `"chuck bat"`, you usually don't want to end up with `apple cherry` (note the two spaces), so the command deletes a token and an appropriate token delimiter. + +Here are some target types and their delimiters... + +- Character or word within a token: nothing +- Token: space +- Argument and item: comma and space +- Line: line ending +- Block: empty line + +Whether a command operates on delimiters can be changed by a target modifier. +`"chuck just bat"` will not delete any spaces; the `"just"` causes the command to ignore delimiters. +`"take just just just bat"` does the same as `"take bat"`. + +Special positional target modifiers `"before"` and `"after"` try to work with delimiters. +`"bring line to after row ten"` will bring a copy of the current line content _with line delimiter_ to after line 10, meaning there will be an additional line (a new line 11). + +Special positional target modifiers `"start of"` and `"end of"` do not use delimiters. +`"bring line to end of row ten"` will bring a copy of the current line content _without line delimiter_ to the end of line 10, meaning line 10 will get content added to it. + +## Some Of The More Useful Actions + +Here are some of the most useful actions. +Parts in square braces (`[]`) are optional. +Targets are represented by `T` with a possible digit. + +- Core Changers + - `"bring T1 [to T2]"`: replace selection/T2 with T + - `"move T1 [to T2]"` + - `"chuck T"`: delete T + - `"change T"`: delete T and set cursor(s) to where T was + - `"drink/pour T"`: edit new line before/after T +- Selection Manipulation + - `"take T"`: set selection + - `"give T"`: deselect + - `"pre/post T"`: set selection before/after T +- Clipboard + - `"paste to T"` + - `"carve/copy T"`: cut/copy T + +## Examples With Walkthroughs + +TODO From 368733bf3354830b4bb6834e1d61e8394b4156ad Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Sun, 18 Jun 2023 22:27:36 -0500 Subject: [PATCH 08/26] pokey suggestion for intro.md Co-authored-by: Pokey Rule <755842+pokey@users.noreply.github.com> --- docs/user/intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/intro.md b/docs/user/intro.md index b4c82b1cfc..6f0aef193b 100644 --- a/docs/user/intro.md +++ b/docs/user/intro.md @@ -21,7 +21,7 @@ The separator may seem trivial now, but it is easier to forget it when you start A target starts as a mark (`"this"`, `"row ten"`, `"green curve air"`, etc) and target modifiers can be applied to suit your needs. A big part of feeling comfortable and productive with Cursorless is getting familiar with the most useful mark types and target modifiers. All of the [mark types](README.md#Marks) are worth knowing. -There are a lot of target modifiers, in this document will try to help you learn the most important ones through examples. +While there are many target modifiers, this document will help you get started fast by focusing on the most important modifiers to learn first. The big difference between a simple command `"bring air to bat"` and the intimidating `"bring next three tokens air to after just line bat"` is the addition of target modifiers. Target modifiers are often chained. `"after just line"` is a chain of three modifiers and they are applied in reverse order (`"line"`, then `"just"`, then `"after"`). From 39efd7e1aa18fdbd21584c3a39a770d456438bd0 Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Sun, 18 Jun 2023 22:58:17 -0500 Subject: [PATCH 09/26] intro.md, remove "to" from "to after" Co-authored-by: Pokey Rule <755842+pokey@users.noreply.github.com> --- docs/user/intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/intro.md b/docs/user/intro.md index 6f0aef193b..ee66453b43 100644 --- a/docs/user/intro.md +++ b/docs/user/intro.md @@ -50,7 +50,7 @@ Whether a command operates on delimiters can be changed by a target modifier. `"take just just just bat"` does the same as `"take bat"`. Special positional target modifiers `"before"` and `"after"` try to work with delimiters. -`"bring line to after row ten"` will bring a copy of the current line content _with line delimiter_ to after line 10, meaning there will be an additional line (a new line 11). +`"bring line after row ten"` will bring a copy of the current line content _with line delimiter_ after line 10, meaning there will be an additional line (a new line 11). Special positional target modifiers `"start of"` and `"end of"` do not use delimiters. `"bring line to end of row ten"` will bring a copy of the current line content _without line delimiter_ to the end of line 10, meaning line 10 will get content added to it. From 66aa3a30b05c8688ea1c5b72d7d72c7041e454ea Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Mon, 19 Jun 2023 16:44:17 -0500 Subject: [PATCH 10/26] refine concept sections --- docs/user/intro.md | 79 +++++++++++++++++++++++++++------------------- 1 file changed, 47 insertions(+), 32 deletions(-) diff --git a/docs/user/intro.md b/docs/user/intro.md index ee66453b43..634f240d01 100644 --- a/docs/user/intro.md +++ b/docs/user/intro.md @@ -1,61 +1,70 @@ -# Introduction +# Guide to intermediate level Cursorless This document will try to explicitly bring together a few concepts that underlie a lot of cursorless behavior, then walk through some example editing operations that are common but perhaps tricky to a beginner. +This document assumes that you understand the very basics of cursorless, like what commands `"take air"` and `"chuck line"` do. +If you don't have the basics down, please read some of [the main documentation page](README.md) and/or watch [the Cursorless tutorial videos](https://www.youtube.com/watch?v=5mAzHGM2M0k&list=PLXv2sppxeoQZz49evjy4T0QJRIgc_JPqs). -## Some Important Concepts +It is planned for this guide to be expanded to both basic and advanced levels. -### Commands Have An Action And A Target Or Two +## Some important concepts + +### Commands have an action and a target or two Commands have an action and a target or two. `"chuck air"` has the action `"chuck"` and one target (the `"air"` token). `"bring air to bat"` has the action `"bring"` and two targets (the `"air"` and `"bat"` tokens). -A target can be more than a single token or line. A target can be a range, like `"air past bat"` that spans from the `"air"` token to the `"bat"` token, and that is still considered _one_ target. +A target can be more than a single token or line. A target can be a [range](README.md#range-targets), like `"air past bat"` that spans from the `"air"` token to the `"bat"` token, and that is still considered _one_ target. A target can even be a vertical slice or list, like the list `"air and bat"`. Doing `"take air and bat"` will result in multiple selections and multiple cursors, but it is still one target. -Commands with two targets often require a separator word between the two targets, like the `"to"` in `"move air to bat"`. -The separator may seem trivial now, but it is easier to forget it when you start using fancy targets. - -### Targets Can Be Modified +### Targets can be modified -A target starts as a mark (`"this"`, `"row ten"`, `"green curve air"`, etc) and target modifiers can be applied to suit your needs. +A target contains a mark (ex: `"this"`, `"row ten"`, `"green curve air"`, etc) and target modifiers can be prefixed to suit your needs. A big part of feeling comfortable and productive with Cursorless is getting familiar with the most useful mark types and target modifiers. All of the [mark types](README.md#Marks) are worth knowing. While there are many target modifiers, this document will help you get started fast by focusing on the most important modifiers to learn first. -The big difference between a simple command `"bring air to bat"` and the intimidating `"bring next three tokens air to after just line bat"` is the addition of target modifiers. -Target modifiers are often chained. `"after just line"` is a chain of three modifiers and they are applied in reverse order (`"line"`, then `"just"`, then `"after"`). +The biggest difference between the simple `"bring air to bat"` and the intimidating `"bring next three lines air to tail block bat"` is the addition of target modifiers. +Target modifiers are often chained. `"tail block"` is a chain of two modifiers and they are applied in reverse order (`"block"`, then `"tail"`). + +Modifier chains can be applied to each [primitive target](README.md#primitive-targets) in a [compound target](README.md#compound-targets). +For instance, `"take tail line air and head block bat"` has chain `"tail line"` applied to `"air"` and chain `"head block"` applied to `"bat"`. + +### Some targets are destinations -### Targets Sometimes Include Their Delimiter Depending On The Action And Modifiers +Commands like `"paste"`, `"bring"`, and `"move"` have a target that is a destination. +Destinations are special. +Targets are converted into destinations using a destination converter (`"to"`, `"before"`, `"after"`); that is why you have to say commands like `"bring air to bat"` or `"bring air before bat"`. +The `"to"` might seem like cursorless is trying to resemble a sentence, but `"to"` actually serves a technical purpose of explicitly converting to a destination. + +Your destinations should start with a single destination converter before you add modifiers and/or a mark. + +### Targets sometimes include a delimiter Some actions will operate on the specified target, and some actions will additionally operate on a delimiter that leads/trails the target. The command `"take air"` will select a token. -The command `"chuck air"` will delete a token _and_ a leading/trailing space (if there is an appropriate one). -Likewise, `"chuck block air"` will delete a block _and_ a leading/trailing empty line (if appropriate). +The command `"chuck air"` will delete a token _and_ leading/trailing spaces (if appropriate ones exist). +Likewise, `"chuck block air"` will delete a block _and_ leading/trailing empty lines (if appropriate ones exist). These default behaviors usually do what you want. -If you have the sentence `apple banana cherry` and run the command `"chuck bat"`, you usually don't want to end up with `apple cherry` (note the two spaces), so the command deletes a token and an appropriate token delimiter. +If you have the sentence `apple banana cherry` and run the command `"chuck bat"`, you usually don't want to end up with `apple cherry` (note the two spaces), so the command deletes a token and appropriate token delimiter. Here are some target types and their delimiters... -- Character or word within a token: nothing -- Token: space -- Argument and item: comma and space -- Line: line ending -- Block: empty line +- Character or word within a token: nothing. +- Token: space. +- Argument and item: comma and space. +- Line: line ending. +- Block: empty line. -Whether a command operates on delimiters can be changed by a target modifier. -`"chuck just bat"` will not delete any spaces; the `"just"` causes the command to ignore delimiters. -`"take just just just bat"` does the same as `"take bat"`. - -Special positional target modifiers `"before"` and `"after"` try to work with delimiters. -`"bring line after row ten"` will bring a copy of the current line content _with line delimiter_ after line 10, meaning there will be an additional line (a new line 11). +Destination converters `"before"` and `"after"` try to work with delimiters. +`"bring air before bat"` will bring a copy of the `"air"` token _with token delimiter (space)_ before the `"bat"` token giving you something like `"aaa bbb"`. Special positional target modifiers `"start of"` and `"end of"` do not use delimiters. -`"bring line to end of row ten"` will bring a copy of the current line content _without line delimiter_ to the end of line 10, meaning line 10 will get content added to it. +`"bring air to start of bat"` will bring a copy of the `"air"` token _without token delimiter (space)_ before the `"bat"` token, giving you something like `"aaabbb"`. -## Some Of The More Useful Actions +## Some of the more useful actions Here are some of the most useful actions. Parts in square braces (`[]`) are optional. @@ -63,18 +72,24 @@ Targets are represented by `T` with a possible digit. - Core Changers - `"bring T1 [to T2]"`: replace selection/T2 with T + - `"bring T1 before/after T2"`: - `"move T1 [to T2]"` - - `"chuck T"`: delete T + - `"chuck T"`: delete T and appropriate delimiter - `"change T"`: delete T and set cursor(s) to where T was - `"drink/pour T"`: edit new line before/after T - Selection Manipulation - `"take T"`: set selection - - `"give T"`: deselect - `"pre/post T"`: set selection before/after T - Clipboard - - `"paste to T"` + - `"paste to/before/after T"` - `"carve/copy T"`: cut/copy T -## Examples With Walkthroughs +## Examples with walkthroughs TODO + +## Some reminders for the author about advanced level content + +Whether a command operates on delimiters can be changed by a target modifier. +`"chuck just bat"` will not delete any spaces; the `"just"` causes the command to ignore delimiters. +`"take just just just bat"` does the same as `"take bat"`. From 3380085b29390e79151c9fb766e124656d25c145 Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Fri, 23 Jun 2023 14:45:03 -0500 Subject: [PATCH 11/26] some line examples --- docs/user/intro.md | 50 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/docs/user/intro.md b/docs/user/intro.md index 634f240d01..a24f9b0705 100644 --- a/docs/user/intro.md +++ b/docs/user/intro.md @@ -86,7 +86,55 @@ Targets are represented by `T` with a possible digit. ## Examples with walkthroughs -TODO +### TO BE CATEGORIZED + +### Simple line operations + +Cursorless might feel token oriented at the beginning, but line operations and feel very natural, especially with use of `"before"` and `"after"`. + +#### Bringing a copy of a line to another line + +Here is a detailed example: + +- `"bring row 7 after line"` to bring a copy of [row](README.md#row-number) 7 to after the current line (or after the last selected line if you have a selection). + - The following will assume that before the command, nothing was selected and there was only one cursor. + - The command is using a [`"row"` mark](README.md#row-number) as a source. + `"row"` marks are especially useful for lines far away from your cursor. + - The destination has the mark `"line"`, which is more explicitly `"line this"`. + The [`"this"` mark](README.md#this) starts the target as the cursor (remember that we are assuming no selections). + The [`"line"` modifier](README.md#line) expands the target to the line containing the cursor. + The `"after"` converts the line-based target to a line-based destination that is after the target. + - Because the destination was an `"after"`, the `"bring"` command also inserts a delimiter that is appropriate for the destination when bringing a copy of the source to the destination. + +And some more examples: + +- `"bring row 7 to line"`, unlike the previous command, uses `"to"` instead of `"after"` for the destination converter. + The command will replace the current line (or line-expanded selection if you had a selection) with the contents of row 7. +- `"bring line air to line"` will replace the current line with the contents of the line that contains the `"air"` token. +- `"bring row 7"`. + If you have a selection, the selection is replaced with the contents of row 7. + If you don't have a selection, the contents of row 7 are inserted at your cursor. +- `"bring up 2"` is similar to the previous command, but uses the `"down "` and `"up "` [mark type](README.md#up-number--down-number). + +Copying a line to an adjacent line has some specialized command support: + +- `"clone row 7"` will put a copy of row 7 after the original row 7. +- `"clone line"` is very common and will move your cursor to the new line. +- `"clone up line"` puts the copy before the original. + - The useful difference from `"clone line"` is that your cursor moves up to the new line so that you are editing the "top" line rather than the "bottom" line. + - `"clone up row 7"` only differs from `"clone row 7"` if your cursor is on row 7. + +#### Operating on multiple lines + +You can operate on multiple lines at a time: + +- `"chuck 3 lines row 7"` will delete three lines starting at row 7. + - The command uses a [relative scope modifier](README.md#previous--next--ordinal--number) (`"3 lines"`) to expand the target to be three lines (proceeding forward). +- `"bring 3 lines row 7 to 2 lines row 12"` replaces the two lines starting at row 12 with the three lines starting at row 7. + Both destinations and sources can be multiple lines. +- `"chuck 3 lines air"` will delete three full lines starting at the line that contains the `"air"` token. + - This command shows that you should not think of these commands as having a length and a start point; think of them as a mark and zero or more modifiers that expand or shift the target. +- TODO MAYBE: lines backwards & next & previous & next lines ## Some reminders for the author about advanced level content From bc84f3526a355064922f6fc714b1e6ae227bc841 Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Mon, 24 Jul 2023 11:31:48 -0500 Subject: [PATCH 12/26] add more examples and highlight of more useful modifiers --- docs/user/intro.md | 174 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 162 insertions(+), 12 deletions(-) diff --git a/docs/user/intro.md b/docs/user/intro.md index a24f9b0705..8f7bf32264 100644 --- a/docs/user/intro.md +++ b/docs/user/intro.md @@ -71,9 +71,10 @@ Parts in square braces (`[]`) are optional. Targets are represented by `T` with a possible digit. - Core Changers - - `"bring T1 [to T2]"`: replace selection/T2 with T - - `"bring T1 before/after T2"`: - - `"move T1 [to T2]"` + - `"bring T"`: insert a copy of T at the cursor/selection. + - `"bring T1 to T2"`: replace T2 with T + - `"bring T1 before/after T2"`: insert a copy of T1 before/after T2, including appropriate delimiters. + - `"move T1 [to/before/after T2]"`: like `"bring"`, but moves instead of copies - `"chuck T"`: delete T and appropriate delimiter - `"change T"`: delete T and set cursor(s) to where T was - `"drink/pour T"`: edit new line before/after T @@ -84,13 +85,52 @@ Targets are represented by `T` with a possible digit. - `"paste to/before/after T"` - `"carve/copy T"`: cut/copy T -## Examples with walkthroughs +## Some of the more useful modifiers -### TO BE CATEGORIZED +Here are some very useful modifiers: -### Simple line operations +- Syntactic scopes ([reference](README.md#syntactic-scopes)) are great for expanding the target to what you want to operate on, like the containing function. + - `"arg"`, often used to involve commas, like `"chuck arg air"` or `"bring air after arg bat"` that take care of commas. + - `"funk"` for function. + - `"state"` for statement (which might span multiple lines or only part of a line). +- Other modifiers that are like syntactic scopes in that they expand the target. + - [`"file"`](README.md#file) for the whole file. + - [`"block"`](README.md#block) for a contiguous block of non-empty lines. + - [`"line"`](README.md#line), often used in commands like `"chuck line"`. + - [`"paint"`](README.md#paint) for contiguous sequence of non-white space characters. + - [`"token"`](README.md#token). + - [`"word"`](README.md#word) allows you to refer to words within a snake_case or camelCase token. + - [`"char"`](README.md#char) for individual characters. -Cursorless might feel token oriented at the beginning, but line operations and feel very natural, especially with use of `"before"` and `"after"`. +And you can reuse the above scopes when using [relative/ordinal modifiers](README.md#previous--next--ordinal--number). +Some examples: + +- `"[number] [scope]s"`, like `"chuck three lines row 12"` to delete rows 12-14. +- `"[number] [scope]s backward"`, like `"chuck three lines backward row 12"` to delete rows 10-12. +- `"[nth] [scope]"`, like `"chuck second word air"` to delete "Banana" from "appleBananaCherry". +- `"[nth] last [scope]"`, like `"chuck last char air"` to delete "s" from "apples". +- `"next/previous [scope]"`, like `"chuck until next token"` to delete everything from the cursor/selection to the next token. + +`"past"`, `"until"`, and `"and"` are good ways to build up targets. + +- `"chuck row 7 past row 9"` to delete rows 7 through 9. +- `"chuck air until bat"` to delete tokens starting at the air token ending just before the bat token. +- `"chuck row 7 and row 10"` to delete rows 7 and 10. + +There is also `"head"` and `"tail"` to expand a target through to the beginning or end of the line. +`"take head air"` selects the air token through to the beginning of air's line. +When followed by a modifier, they will expand their input to the start or end of the given modifier range. +`"take head funk"` will select from the cursor the start of the containing function. + +## Examples of some common operations + +The below examples are supposed to show you how to do some of the most common text editing operations, especially the +operations that might not be initially obvious how to do because of their use of multiple concepts in combination. + +### "Line operations + +Cursorless might feel token oriented at the beginning, but line operations can feel very natural, especially with use of `"before"` and `"after"`. +Also, a lot of the line-based examples can be adapted to tokens, blocks, and so on. #### Bringing a copy of a line to another line @@ -124,6 +164,9 @@ Copying a line to an adjacent line has some specialized command support: - The useful difference from `"clone line"` is that your cursor moves up to the new line so that you are editing the "top" line rather than the "bottom" line. - `"clone up row 7"` only differs from `"clone row 7"` if your cursor is on row 7. +`"clone"` commands on a line also bring the existing hats to the new line, so you can chain commands to operate on the new line without waiting for the clone to complete and see the new hats. +Sidenote: `"clone"` can operate on many types of targets, but lines, blocks, functions, and statements are the most common. + #### Operating on multiple lines You can operate on multiple lines at a time: @@ -134,10 +177,117 @@ You can operate on multiple lines at a time: Both destinations and sources can be multiple lines. - `"chuck 3 lines air"` will delete three full lines starting at the line that contains the `"air"` token. - This command shows that you should not think of these commands as having a length and a start point; think of them as a mark and zero or more modifiers that expand or shift the target. -- TODO MAYBE: lines backwards & next & previous & next lines +- `"chuck row 7 past row 9"` uses the `"past"` modifier to delete row 7 through row 9. + +#### Joining lines + +It is common to want to join lines. +For example, to go from... + +```markdown +apple +banana +``` + +to... + +```markdown +apple banana +``` + +There are a few ways to join lines. +Remember, not everything needs to be done in Cursorless. +Talon's community config repo [has](https://github.com/talonhub/community/blob/468fb16392e6a9907cb98e2526c1e5cbf3b5fc8d/apps/vscode/vscode.talon#L265) `join lines: user.vscode("editor.action.joinLines")`. +Using that command will join the current line with the line below it. +Or, if you have a multi-line selection, then it will join all the selected lines. + +Also, you can [customize Cursorless](customization.md##experimental-cursorless-custom-ide-actions) so you can invoke the vscode operation `editor.action.joinLines` with a Cursorless command and target. +In your Cursorless settings `experimental/actions_custom.csv` file, if you add `join, editor.action.joinLines`, then you can do Cursorless commands like `"join row 7"` to join row 7 and row 8 or `"join 5 lines row 7"` to join 5 lines starting at row 7. + +vscode's `editor.action.joinLines` puts a space between joined lines. +If you want to join lines without a space, `"move to end of "` or `"move to start of "` are an approach you could take. + +- `"move down 1 to end of line"` if your cursor is on the top line. +- `"move row 7 to start of row 8"` for any two lines regardless or cursor position. + +#### Splitting lines + +Sometimes you want to split a line into multiple lines. +For instance, for this... + +```typescript +someCode(); // some comment +``` + +to become this... + +```typescript +// some comment +someCode(); +``` + +`"move tail before its line"` will do the split starting at `""` (`"slash"` for the example above). +First, the `"tail "` expands the target from the mark to everything until the end of the line. +The `"its line"` makes Cursorless re-use the previous mark (from `"tail "`) and expand to the corresponding line. +The overall `"move ... before ..."` structure moves the tail portion to before the line. + +Or, you might want to do the other split, where the tail goes below. +Where this... + +```typescript +apple banana cherry date +``` + +becomes this... + +```typescript +apple banana +cherry date +``` + +`"move tail after its line"` will do the above split. + +### Subtoken changes + +Cursorless also has good support for operating on parts of a token. +Cursorless can recognize and operate on words within a snake_case, camelCase, or PascalCase token. + +- `"chuck third word air"` or `"chuck last word air"` to delete `"_cherry"` from `"apple_banana_cherry"`. +- `"change second word past third word air"` to delete `"BananaCherry"` from `"AppleBananaCherryDate"`. +- `"chuck last 2 words air"` to delete the last two words of the air token. +- `"chuck tail token third word air"` to delete from the third word to the last word of the air token. + It is probably easier to do `"chuck third word past last word air"`. +- `"bring 2 words third word air to last word bat"` will replace the last word of the bat token with some words from the air token. + +Similar things can be done on characters, like `"chuck last char air"` to delete `"s"` from `"apples"`. + +### Arg and item changes + +The `"arg"` (argument to a function call) and `"item"` (item in a list, map, or object) modifiers are often helpful because they are comma-aware. + +- `"chuck arg bat"` is a good way to go from `someFunction(apple, banana + otherStuff, cherry)` to `someFunction(apple, cherry)`. + The command deletes the argument and the appropriate delimiters (comma and a space). +- `"bring bat after arg air"` lets you go from `someFunction(apple, cherry)` to `someFunction(apple, banana, cherry)`, again taking care of commas and spaces. +- `"chuck item air"` can go from `someMap = { key1: "apple", key2: "banana" }` to `someMap = { key2: "banana" }`. + +### Delimeter-only changes + +You can use `"leading"` and `"trailing"` to target delimiters themselves. + +- `"chuck leading and trailing air"` to delete the spaces around the air token. +- `"chuck leading block` will delete the empty lines before the current block. + +But `"leading"` and `"trailing"` are not always needed to mess with delimiters. + +- `"chuck until next token"` will delete spaces from the cursor to the next token. + +## What's next -## Some reminders for the author about advanced level content +Eventually there will be more guide-like documentation on the more advanced concepts. +In the meantime, here are a few more useful concepts to look into. -Whether a command operates on delimiters can be changed by a target modifier. -`"chuck just bat"` will not delete any spaces; the `"just"` causes the command to ignore delimiters. -`"take just just just bat"` does the same as `"take bat"`. +- [pair operations](README.md#surrounding-pair), with [list of paired delimiters](README.md#paired-delimiters) +- [snippets](experimental/snippets.md) +- [every](README.md#every) +- [instance](README.md#instance) +- [just](README.md#just) From 95e661607588e5d5077bf91bee36f45b8c5b92a5 Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Mon, 24 Jul 2023 13:41:42 -0500 Subject: [PATCH 13/26] act on some pokey suggestions --- docs/user/intro.md | 36 ++++++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/docs/user/intro.md b/docs/user/intro.md index 8f7bf32264..e86b334eff 100644 --- a/docs/user/intro.md +++ b/docs/user/intro.md @@ -24,20 +24,27 @@ A big part of feeling comfortable and productive with Cursorless is getting fami All of the [mark types](README.md#Marks) are worth knowing. While there are many target modifiers, this document will help you get started fast by focusing on the most important modifiers to learn first. -The biggest difference between the simple `"bring air to bat"` and the intimidating `"bring next three lines air to tail block bat"` is the addition of target modifiers. -Target modifiers are often chained. `"tail block"` is a chain of two modifiers and they are applied in reverse order (`"block"`, then `"tail"`). +The biggest difference between the simple `"bring air after bat"` and the intimidating `"bring next three lines air after block state bat"` is the addition of target modifiers. +Target modifiers are often chained. `"block state"` is a chain of two modifiers and they are applied in reverse order (`"state"`, then `"block"`). Modifier chains can be applied to each [primitive target](README.md#primitive-targets) in a [compound target](README.md#compound-targets). -For instance, `"take tail line air and head block bat"` has chain `"tail line"` applied to `"air"` and chain `"head block"` applied to `"bat"`. +For instance, `"take air and bat"` could be changed to have independent modifiers in front of `"air"` and/or `"bat"`. ### Some targets are destinations -Commands like `"paste"`, `"bring"`, and `"move"` have a target that is a destination. +The `"paste"` commands has a single target that is a destination. +The second targets of `"bring"` and `"move"` commands are destinations. Destinations are special. Targets are converted into destinations using a destination converter (`"to"`, `"before"`, `"after"`); that is why you have to say commands like `"bring air to bat"` or `"bring air before bat"`. The `"to"` might seem like cursorless is trying to resemble a sentence, but `"to"` actually serves a technical purpose of explicitly converting to a destination. -Your destinations should start with a single destination converter before you add modifiers and/or a mark. +`"to"` generally means you are replacing the destination. +Some targets are zero-width (ex: `"start of air"`), so nothing is actually deleted. + +`"before"` and `"after"` generally mean you are inserting before/after the destination with proper attention to delimiters. +More details in the next section. + +Your destinations should start with a single destination converter before you add modifiers and/or a mark, like in `"paste "`. ### Targets sometimes include a delimiter @@ -72,18 +79,19 @@ Targets are represented by `T` with a possible digit. - Core Changers - `"bring T"`: insert a copy of T at the cursor/selection. - - `"bring T1 to T2"`: replace T2 with T + - `"bring T1 to T2"`: replace T2 with T. - `"bring T1 before/after T2"`: insert a copy of T1 before/after T2, including appropriate delimiters. - - `"move T1 [to/before/after T2]"`: like `"bring"`, but moves instead of copies - - `"chuck T"`: delete T and appropriate delimiter - - `"change T"`: delete T and set cursor(s) to where T was - - `"drink/pour T"`: edit new line before/after T + - `"move T1 [to/before/after T2]"`: like `"bring"`, but moves instead of copies. + - `"swap T1 with T2"` + - `"chuck T"`: delete T and appropriate delimiter. + - `"change T"`: delete T and set cursor(s) to where T was; delimiters are unchanged. + - `"drink/pour T"`: edit new line before/after T. - Selection Manipulation - - `"take T"`: set selection - - `"pre/post T"`: set selection before/after T + - `"take T"`: set selection. + - `"pre/post T"`: set selection before/after T. - Clipboard - - `"paste to/before/after T"` - - `"carve/copy T"`: cut/copy T + - `"paste to/before/after T"`. + - `"carve/copy T"`: cut/copy T. ## Some of the more useful modifiers From 4802c1124e051f3ea46c6e9c2ea4ad1f85fe5acc Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Sat, 29 Jul 2023 09:31:41 -0500 Subject: [PATCH 14/26] add pokey's "break" command to "split lines" example --- docs/user/intro.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/user/intro.md b/docs/user/intro.md index e86b334eff..f463d8e433 100644 --- a/docs/user/intro.md +++ b/docs/user/intro.md @@ -255,6 +255,18 @@ cherry date `"move tail after its line"` will do the above split. +Pokey has streamlined the operation by [adding a Talon Voice command](https://github.com/pokey/pokey_talon/blob/3a7ccd407be7b97104b99c7288f9771ce0c0db4e/apps/vscode/vscode.talon#L613-L616): + +```talon +break : + user.cursorless_command("setSelectionBefore", cursorless_target) + user.vscode("hideSuggestWidget") + key("enter") +``` + +This is another example that not every text editing operation should be done with only the existing Cursorless system. +Customization and extension are very handy. + ### Subtoken changes Cursorless also has good support for operating on parts of a token. From 369430df78714abe0bacc9982c39ef59c448c687 Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Sat, 29 Jul 2023 13:55:02 -0500 Subject: [PATCH 15/26] change intro.md to guide-intermediate.md --- docs/user/{intro.md => guide-intermediate.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/user/{intro.md => guide-intermediate.md} (100%) diff --git a/docs/user/intro.md b/docs/user/guide-intermediate.md similarity index 100% rename from docs/user/intro.md rename to docs/user/guide-intermediate.md From 076a8338d5afcf4f93a549faa89b870e0de1dbe2 Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Sun, 30 Jul 2023 13:40:35 -0500 Subject: [PATCH 16/26] typo fixes --- docs/user/guide-intermediate.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user/guide-intermediate.md b/docs/user/guide-intermediate.md index f463d8e433..5c9ab18093 100644 --- a/docs/user/guide-intermediate.md +++ b/docs/user/guide-intermediate.md @@ -128,14 +128,14 @@ Some examples: There is also `"head"` and `"tail"` to expand a target through to the beginning or end of the line. `"take head air"` selects the air token through to the beginning of air's line. When followed by a modifier, they will expand their input to the start or end of the given modifier range. -`"take head funk"` will select from the cursor the start of the containing function. +`"take head funk"` will select from the cursor to the start of the containing function. ## Examples of some common operations The below examples are supposed to show you how to do some of the most common text editing operations, especially the operations that might not be initially obvious how to do because of their use of multiple concepts in combination. -### "Line operations +### Line operations Cursorless might feel token oriented at the beginning, but line operations can feel very natural, especially with use of `"before"` and `"after"`. Also, a lot of the line-based examples can be adapted to tokens, blocks, and so on. From d660024f7d57994b9b07476580959a70a259557a Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Thu, 10 Aug 2023 14:17:02 -0500 Subject: [PATCH 17/26] act on some @josharian feedback --- docs/user/guide-intermediate.md | 160 +++++++++++++++++--------------- 1 file changed, 85 insertions(+), 75 deletions(-) diff --git a/docs/user/guide-intermediate.md b/docs/user/guide-intermediate.md index 5c9ab18093..c435d4ef22 100644 --- a/docs/user/guide-intermediate.md +++ b/docs/user/guide-intermediate.md @@ -1,14 +1,82 @@ # Guide to intermediate level Cursorless -This document will try to explicitly bring together a few concepts that underlie a lot of cursorless behavior, then walk through some example editing operations that are common but perhaps tricky to a beginner. +This document will try to: + +- Highlight the most useful actions and modifiers in Cursorless so you know which ones to focus on learning first. +- Bring together a few important concepts that underlie a lot of Cursorless behavior. +- Walk through some example editing operations that are common but perhaps tricky to a beginner. + This document assumes that you understand the very basics of cursorless, like what commands `"take air"` and `"chuck line"` do. If you don't have the basics down, please read some of [the main documentation page](README.md) and/or watch [the Cursorless tutorial videos](https://www.youtube.com/watch?v=5mAzHGM2M0k&list=PLXv2sppxeoQZz49evjy4T0QJRIgc_JPqs). It is planned for this guide to be expanded to both basic and advanced levels. -## Some important concepts +## Important actions + +Here are some of the most useful actions. +Parts in square braces (`[]`) are optional. +Slashes (`/`) show alternatives. +Targets are represented by `T` with a possible digit. + +- Selection Manipulation + - `"take T"`: set selection. + - `"pre/post T"`: set selection before/after T. +- Clipboard + - `"paste to/before/after T"`. + - `"carve/copy T"`: cut/copy T. +- Core Changers + - `"bring T"`: insert a copy of T at the cursor/selection. + - `"bring T1 to T2"`: replace T2 with T. + - `"bring T1 before/after T2"`: insert a copy of T1 before/after T2, including appropriate delimiters. + - `"move T1 [to/before/after T2]"`: like `"bring"`, but moves instead of copies. + - `"chuck T"`: delete T and appropriate delimiter. + - `"change T"`: delete T and set cursor(s) to where T was; delimiters are unchanged. + - `"drink/pour T"`: edit new line before/after T. +- IDE-related + - `"follow T"`: open URL or go to definition of T. + - `"quick fix T"`: show quick fix for T. + - `"reference T"`: show references to T. + +## Important modifiers + +Here are some very useful modifiers: + +- Syntactic scopes ([reference](README.md#syntactic-scopes)) are great for expanding the target to what you want to operate on, like the containing function. + - `"arg"` and `"item"`: often used to involve commas, like `"chuck item air"` or `"bring air after arg bat"` that take care of commas. + - `"funk"` for function. + - `"state"` for statement (which might span multiple lines or only part of a line). +- Other modifiers that are like syntactic scopes in that they expand the target. + - [`"file"`](README.md#file) for the whole file. + - [`"block"`](README.md#block) for a contiguous block of non-empty lines. + - [`"line"`](README.md#line), often used in commands like `"chuck line"`. + - [`"paint"`](README.md#paint) for contiguous sequence of non-white space characters. + - [`"token"`](README.md#token). + - [`"word"`](README.md#word) allows you to refer to words within a snake_case or camelCase token. + - [`"char"`](README.md#char) for individual characters. + +And you can reuse the above scopes when using [relative/ordinal modifiers](README.md#previous--next--ordinal--number). +Some examples: -### Commands have an action and a target or two +- `"[number] [scope]s"`, like `"chuck three lines row 12"` to delete rows 12-14. +- `"[number] [scope]s backward"`, like `"chuck three lines backward row 12"` to delete rows 10-12. +- `"[nth] [scope]"`, like `"chuck second word air"` to delete "Banana" from "appleBananaCherry". +- `"[nth] last [scope]"`, like `"chuck last char air"` to delete "s" from "apples". +- `"next/previous [scope]"`, like `"chuck until next token"` to delete everything from the cursor/selection to the next token. + +`"past"`, `"until"`, and `"and"` are good ways to build up targets. + +- `"chuck row 7 past row 9"` to delete rows 7 through 9. +- `"chuck air until bat"` to delete tokens starting at the air token ending just before the bat token. +- `"chuck row 7 and row 10"` to delete rows 7 and 10. + +There is also `"head"` and `"tail"` to expand a target through to the beginning or end of the line. +`"take head air"` selects the air token through to the beginning of air's line. +When followed by a modifier, they will expand their input to the start or end of the given modifier range. +`"take head funk"` will select from the cursor to the start of the containing function. + +## Important concepts + +### Command structure Commands have an action and a target or two. `"chuck air"` has the action `"chuck"` and one target (the `"air"` token). `"bring air to bat"` has the action `"bring"` and two targets (the `"air"` and `"bat"` tokens). @@ -17,7 +85,7 @@ A target can be more than a single token or line. A target can be a [range](READ A target can even be a vertical slice or list, like the list `"air and bat"`. Doing `"take air and bat"` will result in multiple selections and multiple cursors, but it is still one target. -### Targets can be modified +### Marks and modifiers A target contains a mark (ex: `"this"`, `"row ten"`, `"green curve air"`, etc) and target modifiers can be prefixed to suit your needs. A big part of feeling comfortable and productive with Cursorless is getting familiar with the most useful mark types and target modifiers. @@ -28,25 +96,26 @@ The biggest difference between the simple `"bring air after bat"` and the intimi Target modifiers are often chained. `"block state"` is a chain of two modifiers and they are applied in reverse order (`"state"`, then `"block"`). Modifier chains can be applied to each [primitive target](README.md#primitive-targets) in a [compound target](README.md#compound-targets). -For instance, `"take air and bat"` could be changed to have independent modifiers in front of `"air"` and/or `"bat"`. +For instance, `"take air and bat"` could be changed to have independent modifiers in front of `"air"` and/or `"bat"`, such as `"take line air and block bat"` -### Some targets are destinations +### Destinations The `"paste"` commands has a single target that is a destination. The second targets of `"bring"` and `"move"` commands are destinations. -Destinations are special. -Targets are converted into destinations using a destination converter (`"to"`, `"before"`, `"after"`); that is why you have to say commands like `"bring air to bat"` or `"bring air before bat"`. + +In `"bring air before bat"`, `"air"` is the non-destination first target and `"before bat"` is a destination (and second target). + +Targets are converted into destinations using a destination converter (`"to"`, `"before"`, `"after"`); that is why you have to say commands like `"bring air to bat"` or `"bring air after bat"`. The `"to"` might seem like cursorless is trying to resemble a sentence, but `"to"` actually serves a technical purpose of explicitly converting to a destination. `"to"` generally means you are replacing the destination. -Some targets are zero-width (ex: `"start of air"`), so nothing is actually deleted. +Ex: `"paste to air"` will replace the air token. `"before"` and `"after"` generally mean you are inserting before/after the destination with proper attention to delimiters. +Ex: `"paste after air"` will insert a space followed by the clipboard contents after the air token. More details in the next section. -Your destinations should start with a single destination converter before you add modifiers and/or a mark, like in `"paste "`. - -### Targets sometimes include a delimiter +### Delimiters Some actions will operate on the specified target, and some actions will additionally operate on a delimiter that leads/trails the target. @@ -61,7 +130,7 @@ Here are some target types and their delimiters... - Character or word within a token: nothing. - Token: space. -- Argument and item: comma and space. +- Argument or item: comma and space. - Line: line ending. - Block: empty line. @@ -71,65 +140,6 @@ Destination converters `"before"` and `"after"` try to work with delimiters. Special positional target modifiers `"start of"` and `"end of"` do not use delimiters. `"bring air to start of bat"` will bring a copy of the `"air"` token _without token delimiter (space)_ before the `"bat"` token, giving you something like `"aaabbb"`. -## Some of the more useful actions - -Here are some of the most useful actions. -Parts in square braces (`[]`) are optional. -Targets are represented by `T` with a possible digit. - -- Core Changers - - `"bring T"`: insert a copy of T at the cursor/selection. - - `"bring T1 to T2"`: replace T2 with T. - - `"bring T1 before/after T2"`: insert a copy of T1 before/after T2, including appropriate delimiters. - - `"move T1 [to/before/after T2]"`: like `"bring"`, but moves instead of copies. - - `"swap T1 with T2"` - - `"chuck T"`: delete T and appropriate delimiter. - - `"change T"`: delete T and set cursor(s) to where T was; delimiters are unchanged. - - `"drink/pour T"`: edit new line before/after T. -- Selection Manipulation - - `"take T"`: set selection. - - `"pre/post T"`: set selection before/after T. -- Clipboard - - `"paste to/before/after T"`. - - `"carve/copy T"`: cut/copy T. - -## Some of the more useful modifiers - -Here are some very useful modifiers: - -- Syntactic scopes ([reference](README.md#syntactic-scopes)) are great for expanding the target to what you want to operate on, like the containing function. - - `"arg"`, often used to involve commas, like `"chuck arg air"` or `"bring air after arg bat"` that take care of commas. - - `"funk"` for function. - - `"state"` for statement (which might span multiple lines or only part of a line). -- Other modifiers that are like syntactic scopes in that they expand the target. - - [`"file"`](README.md#file) for the whole file. - - [`"block"`](README.md#block) for a contiguous block of non-empty lines. - - [`"line"`](README.md#line), often used in commands like `"chuck line"`. - - [`"paint"`](README.md#paint) for contiguous sequence of non-white space characters. - - [`"token"`](README.md#token). - - [`"word"`](README.md#word) allows you to refer to words within a snake_case or camelCase token. - - [`"char"`](README.md#char) for individual characters. - -And you can reuse the above scopes when using [relative/ordinal modifiers](README.md#previous--next--ordinal--number). -Some examples: - -- `"[number] [scope]s"`, like `"chuck three lines row 12"` to delete rows 12-14. -- `"[number] [scope]s backward"`, like `"chuck three lines backward row 12"` to delete rows 10-12. -- `"[nth] [scope]"`, like `"chuck second word air"` to delete "Banana" from "appleBananaCherry". -- `"[nth] last [scope]"`, like `"chuck last char air"` to delete "s" from "apples". -- `"next/previous [scope]"`, like `"chuck until next token"` to delete everything from the cursor/selection to the next token. - -`"past"`, `"until"`, and `"and"` are good ways to build up targets. - -- `"chuck row 7 past row 9"` to delete rows 7 through 9. -- `"chuck air until bat"` to delete tokens starting at the air token ending just before the bat token. -- `"chuck row 7 and row 10"` to delete rows 7 and 10. - -There is also `"head"` and `"tail"` to expand a target through to the beginning or end of the line. -`"take head air"` selects the air token through to the beginning of air's line. -When followed by a modifier, they will expand their input to the start or end of the given modifier range. -`"take head funk"` will select from the cursor to the start of the containing function. - ## Examples of some common operations The below examples are supposed to show you how to do some of the most common text editing operations, especially the @@ -308,6 +318,6 @@ In the meantime, here are a few more useful concepts to look into. - [pair operations](README.md#surrounding-pair), with [list of paired delimiters](README.md#paired-delimiters) - [snippets](experimental/snippets.md) -- [every](README.md#every) -- [instance](README.md#instance) -- [just](README.md#just) +- [`"every"`](README.md#every) +- [`"instance"`](README.md#instance) +- [`"just"`](README.md#just) From f3dcc0add86c9f7341618fb42ea2d5c0da6d8fc5 Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Sun, 13 Aug 2023 19:10:16 -0500 Subject: [PATCH 18/26] pokey suggestion for `move` Co-authored-by: Pokey Rule <755842+pokey@users.noreply.github.com> --- docs/user/guide-intermediate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/guide-intermediate.md b/docs/user/guide-intermediate.md index c435d4ef22..0ee66fcd46 100644 --- a/docs/user/guide-intermediate.md +++ b/docs/user/guide-intermediate.md @@ -28,7 +28,7 @@ Targets are represented by `T` with a possible digit. - `"bring T"`: insert a copy of T at the cursor/selection. - `"bring T1 to T2"`: replace T2 with T. - `"bring T1 before/after T2"`: insert a copy of T1 before/after T2, including appropriate delimiters. - - `"move T1 [to/before/after T2]"`: like `"bring"`, but moves instead of copies. + - `"move T1 [to/before/after T2]"`: like `"bring"`, but also deletes the source (ie it 'moves' T1 instead of copying it) - `"chuck T"`: delete T and appropriate delimiter. - `"change T"`: delete T and set cursor(s) to where T was; delimiters are unchanged. - `"drink/pour T"`: edit new line before/after T. From e2d020d448f76b4b61c76cbd7ba56dfc858ab918 Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Sun, 13 Aug 2023 19:11:56 -0500 Subject: [PATCH 19/26] pokey suggestion for quick fix Co-authored-by: Pokey Rule <755842+pokey@users.noreply.github.com> --- docs/user/guide-intermediate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/guide-intermediate.md b/docs/user/guide-intermediate.md index 0ee66fcd46..bb1c114a9b 100644 --- a/docs/user/guide-intermediate.md +++ b/docs/user/guide-intermediate.md @@ -34,7 +34,7 @@ Targets are represented by `T` with a possible digit. - `"drink/pour T"`: edit new line before/after T. - IDE-related - `"follow T"`: open URL or go to definition of T. - - `"quick fix T"`: show quick fix for T. + - `"quick fix T"`: show available quick fixes for T (eg rename, extract variable, etc). - `"reference T"`: show references to T. ## Important modifiers From 375ea0ca0e219931709b3fdb9396979c084c205c Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Sun, 13 Aug 2023 19:23:01 -0500 Subject: [PATCH 20/26] pokey suggestion for arg and item Co-authored-by: Pokey Rule <755842+pokey@users.noreply.github.com> --- docs/user/guide-intermediate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/guide-intermediate.md b/docs/user/guide-intermediate.md index bb1c114a9b..b531d77570 100644 --- a/docs/user/guide-intermediate.md +++ b/docs/user/guide-intermediate.md @@ -42,7 +42,7 @@ Targets are represented by `T` with a possible digit. Here are some very useful modifiers: - Syntactic scopes ([reference](README.md#syntactic-scopes)) are great for expanding the target to what you want to operate on, like the containing function. - - `"arg"` and `"item"`: often used to involve commas, like `"chuck item air"` or `"bring air after arg bat"` that take care of commas. + - `"arg"` and `"item"`: for items in a comma-separated list, like `"chuck item air"` or `"bring air after arg bat"`. Commas are inserted / removed as necessary to keep things syntactically valid. `"item"` works for all comma-separated items; `"arg"` only targets function arguments / parameters - `"funk"` for function. - `"state"` for statement (which might span multiple lines or only part of a line). - Other modifiers that are like syntactic scopes in that they expand the target. From f5c562a0f800bea3ed32f528b48c9bc3b68fc3a2 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci-lite[bot]" <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Date: Mon, 14 Aug 2023 00:25:02 +0000 Subject: [PATCH 21/26] [pre-commit.ci lite] apply automatic fixes --- docs/user/guide-intermediate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/guide-intermediate.md b/docs/user/guide-intermediate.md index b531d77570..e8b22ad08b 100644 --- a/docs/user/guide-intermediate.md +++ b/docs/user/guide-intermediate.md @@ -42,7 +42,7 @@ Targets are represented by `T` with a possible digit. Here are some very useful modifiers: - Syntactic scopes ([reference](README.md#syntactic-scopes)) are great for expanding the target to what you want to operate on, like the containing function. - - `"arg"` and `"item"`: for items in a comma-separated list, like `"chuck item air"` or `"bring air after arg bat"`. Commas are inserted / removed as necessary to keep things syntactically valid. `"item"` works for all comma-separated items; `"arg"` only targets function arguments / parameters + - `"arg"` and `"item"`: for items in a comma-separated list, like `"chuck item air"` or `"bring air after arg bat"`. Commas are inserted / removed as necessary to keep things syntactically valid. `"item"` works for all comma-separated items; `"arg"` only targets function arguments / parameters - `"funk"` for function. - `"state"` for statement (which might span multiple lines or only part of a line). - Other modifiers that are like syntactic scopes in that they expand the target. From 6b141d5c3f0717137451034d20c6dfa53808acd0 Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Sun, 13 Aug 2023 20:25:54 -0500 Subject: [PATCH 22/26] pokey suggestion for `next` example Co-authored-by: Pokey Rule <755842+pokey@users.noreply.github.com> --- docs/user/guide-intermediate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/guide-intermediate.md b/docs/user/guide-intermediate.md index e8b22ad08b..82853b37c5 100644 --- a/docs/user/guide-intermediate.md +++ b/docs/user/guide-intermediate.md @@ -61,7 +61,7 @@ Some examples: - `"[number] [scope]s backward"`, like `"chuck three lines backward row 12"` to delete rows 10-12. - `"[nth] [scope]"`, like `"chuck second word air"` to delete "Banana" from "appleBananaCherry". - `"[nth] last [scope]"`, like `"chuck last char air"` to delete "s" from "apples". -- `"next/previous [scope]"`, like `"chuck until next token"` to delete everything from the cursor/selection to the next token. +- `"next/previous [scope]"`, like `"chuck until next token"` to delete everything from the cursor/selection to the next token, or `"copy next funk"` to copy the next function after your cursor `"past"`, `"until"`, and `"and"` are good ways to build up targets. From 6b75e222980af3850f70eb9f526dd71830f9507a Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Tue, 15 Aug 2023 00:04:07 -0500 Subject: [PATCH 23/26] misc pokey suggestions --- docs/user/guide-intermediate.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/user/guide-intermediate.md b/docs/user/guide-intermediate.md index 82853b37c5..d44f96a495 100644 --- a/docs/user/guide-intermediate.md +++ b/docs/user/guide-intermediate.md @@ -22,15 +22,16 @@ Targets are represented by `T` with a possible digit. - `"take T"`: set selection. - `"pre/post T"`: set selection before/after T. - Clipboard - - `"paste to/before/after T"`. + - `"paste to T"`: replace T with clipboard contents. + - `"paste before/after T"`: insert clipboard contents before/after T, including appropriate [delimiters](#delimiters). - `"carve/copy T"`: cut/copy T. - Core Changers - `"bring T"`: insert a copy of T at the cursor/selection. - `"bring T1 to T2"`: replace T2 with T. - - `"bring T1 before/after T2"`: insert a copy of T1 before/after T2, including appropriate delimiters. + - `"bring T1 before/after T2"`: insert a copy of T1 before/after T2, including appropriate [delimiters](#delimiters). - `"move T1 [to/before/after T2]"`: like `"bring"`, but also deletes the source (ie it 'moves' T1 instead of copying it) - - `"chuck T"`: delete T and appropriate delimiter. - - `"change T"`: delete T and set cursor(s) to where T was; delimiters are unchanged. + - `"chuck T"`: delete T and appropriate [delimiters](#delimiters). + - `"change T"`: delete T and set cursor(s) to where T was; [delimiters](#delimiters) are unchanged. - `"drink/pour T"`: edit new line before/after T. - IDE-related - `"follow T"`: open URL or go to definition of T. @@ -42,8 +43,11 @@ Targets are represented by `T` with a possible digit. Here are some very useful modifiers: - Syntactic scopes ([reference](README.md#syntactic-scopes)) are great for expanding the target to what you want to operate on, like the containing function. - - `"arg"` and `"item"`: for items in a comma-separated list, like `"chuck item air"` or `"bring air after arg bat"`. Commas are inserted / removed as necessary to keep things syntactically valid. `"item"` works for all comma-separated items; `"arg"` only targets function arguments / parameters - - `"funk"` for function. + - `"arg"` and `"item"`: for items in a comma-separated list, like `"chuck item air"` or `"bring air after arg bat"`. + Commas are inserted / removed as necessary to keep things syntactically valid. + `"item"` works for all comma-separated items; + `"arg"` only targets function arguments/parameters + - `"funk"` for a function definition/declaration. - `"state"` for statement (which might span multiple lines or only part of a line). - Other modifiers that are like syntactic scopes in that they expand the target. - [`"file"`](README.md#file) for the whole file. @@ -57,7 +61,7 @@ Here are some very useful modifiers: And you can reuse the above scopes when using [relative/ordinal modifiers](README.md#previous--next--ordinal--number). Some examples: -- `"[number] [scope]s"`, like `"chuck three lines row 12"` to delete rows 12-14. +- `"[number] [scope]s"`, like `"chuck three lines air"` to delete three lines, starting with the line that contains the air token. - `"[number] [scope]s backward"`, like `"chuck three lines backward row 12"` to delete rows 10-12. - `"[nth] [scope]"`, like `"chuck second word air"` to delete "Banana" from "appleBananaCherry". - `"[nth] last [scope]"`, like `"chuck last char air"` to delete "s" from "apples". @@ -100,7 +104,7 @@ For instance, `"take air and bat"` could be changed to have independent modifier ### Destinations -The `"paste"` commands has a single target that is a destination. +The `"paste"` command has a single target that is a destination. The second targets of `"bring"` and `"move"` commands are destinations. In `"bring air before bat"`, `"air"` is the non-destination first target and `"before bat"` is a destination (and second target). From d1b2327984ce2244dcf633f75d0baf8c15a96b66 Mon Sep 17 00:00:00 2001 From: Pokey Rule <755842+pokey@users.noreply.github.com> Date: Wed, 30 Aug 2023 15:40:06 +0100 Subject: [PATCH 24/26] Tweaks --- docs/user/guide-intermediate.md | 54 ++++++++++++++++++--------------- 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/docs/user/guide-intermediate.md b/docs/user/guide-intermediate.md index d44f96a495..5d71be686f 100644 --- a/docs/user/guide-intermediate.md +++ b/docs/user/guide-intermediate.md @@ -1,42 +1,46 @@ -# Guide to intermediate level Cursorless +# Guide to intermediate-level Cursorless -This document will try to: +Starting to feel comfortable with the basics? Great 🙌! Let's get you to the next level. This document will do the following: -- Highlight the most useful actions and modifiers in Cursorless so you know which ones to focus on learning first. -- Bring together a few important concepts that underlie a lot of Cursorless behavior. +- Highlight the actions and modifiers in Cursorless that the pros use most. +- Teach you a few important concepts that underlie a lot of Cursorless behavior. - Walk through some example editing operations that are common but perhaps tricky to a beginner. -This document assumes that you understand the very basics of cursorless, like what commands `"take air"` and `"chuck line"` do. -If you don't have the basics down, please read some of [the main documentation page](README.md) and/or watch [the Cursorless tutorial videos](https://www.youtube.com/watch?v=5mAzHGM2M0k&list=PLXv2sppxeoQZz49evjy4T0QJRIgc_JPqs). +This document assumes that you understand the very basics of Cursorless, like `"take air"` and `"chuck line"`. +If those commands don't mean anything to you, we'd advise having a look at of [the main documentation page](README.md) and watching [the Cursorless tutorial videos](https://www.youtube.com/watch?v=5mAzHGM2M0k&list=PLXv2sppxeoQZz49evjy4T0QJRIgc_JPqs) to get off the ground. -It is planned for this guide to be expanded to both basic and advanced levels. +We plan to add basic and advanced levels before and after this guide; for now the [the main documentation page](README.md) and the YouTube videos are the best place to learn basic / advanced Cursorless. + +Note that we use the following conventions here: + +- Words in square braces (`[]`) are optional, eg `hello [world]` means you can say `"hello"` or `"hello world"`. +- Slashes (`/`) show alternatives. For example, `hello/world` means you can say `"hello"` or `"world"`. +- Targets are represented by `T` with a possible digit, eg `T` or `T1` or `T2`. For example, `bring T1 to T2` means you can say `"bring air to bat"`. ## Important actions -Here are some of the most useful actions. -Parts in square braces (`[]`) are optional. -Slashes (`/`) show alternatives. -Targets are represented by `T` with a possible digit. +Here are some of the most useful actions: -- Selection Manipulation - - `"take T"`: set selection. - - `"pre/post T"`: set selection before/after T. +- Moving the cursor + - `"take T"`: select the target `T`. Note that you'll use this action less and less as you get more comfortable with the other Cursorless actions. + - `"pre/post T"`: place your cursor before/after T. - Clipboard - - `"paste to T"`: replace T with clipboard contents. - - `"paste before/after T"`: insert clipboard contents before/after T, including appropriate [delimiters](#delimiters). - - `"carve/copy T"`: cut/copy T. -- Core Changers - - `"bring T"`: insert a copy of T at the cursor/selection. - - `"bring T1 to T2"`: replace T2 with T. - - `"bring T1 before/after T2"`: insert a copy of T1 before/after T2, including appropriate [delimiters](#delimiters). - - `"move T1 [to/before/after T2]"`: like `"bring"`, but also deletes the source (ie it 'moves' T1 instead of copying it) - - `"chuck T"`: delete T and appropriate [delimiters](#delimiters). - - `"change T"`: delete T and set cursor(s) to where T was; [delimiters](#delimiters) are unchanged. - - `"drink/pour T"`: edit new line before/after T. + - `"paste to T"`: replace `T` with clipboard contents. + - `"paste before/after T"`: insert clipboard contents before/after `T`, including appropriate [delimiters](#delimiters). + - `"carve/copy T"`: cut/copy `T`. +- Changing text + - `"bring T"`: insert a copy of `T` at the cursor/selection. + - `"bring T1 to T2"`: replace `T2` with `T1`. + - `"bring T1 before/after T2"`: insert a copy of `T1` before/after `T2`, including appropriate [delimiters](#delimiters). + - `"move T1 [to/before/after T2]"`: like `"bring"`, but also deletes the source (ie it 'moves' `T1` instead of copying it) + - `"chuck T"`: delete `T` and appropriate [delimiters](#delimiters). + - `"change T"`: delete `T` and set cursor(s) to where `T` was; [delimiters](#delimiters) are unchanged. + - `"drink/pour T"`: edit new line before/after `T`. - IDE-related - `"follow T"`: open URL or go to definition of T. - `"quick fix T"`: show available quick fixes for T (eg rename, extract variable, etc). - `"reference T"`: show references to T. + - `"rename T"`: invokes the built-in IDE rename operation on `T`, which will update all references to the given variable to the new name. ## Important modifiers From 5324363bf122c8484adcebc91aec4c085a972322 Mon Sep 17 00:00:00 2001 From: Andreas Arvidsson Date: Fri, 8 Sep 2023 14:36:18 +0200 Subject: [PATCH 25/26] Update guide-intermediate.md fixed bug --- docs/user/guide-intermediate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/guide-intermediate.md b/docs/user/guide-intermediate.md index 5d71be686f..fc7fb76747 100644 --- a/docs/user/guide-intermediate.md +++ b/docs/user/guide-intermediate.md @@ -291,7 +291,7 @@ Cursorless also has good support for operating on parts of a token. Cursorless can recognize and operate on words within a snake_case, camelCase, or PascalCase token. - `"chuck third word air"` or `"chuck last word air"` to delete `"_cherry"` from `"apple_banana_cherry"`. -- `"change second word past third word air"` to delete `"BananaCherry"` from `"AppleBananaCherryDate"`. +- `"change second past third word air"` to delete `"BananaCherry"` from `"AppleBananaCherryDate"`. - `"chuck last 2 words air"` to delete the last two words of the air token. - `"chuck tail token third word air"` to delete from the third word to the last word of the air token. It is probably easier to do `"chuck third word past last word air"`. From 808b5b4f6676b9f98af453db784b6de9994dbdf8 Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Fri, 8 Sep 2023 10:04:55 -0500 Subject: [PATCH 26/26] typo fix --- docs/user/guide-intermediate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/guide-intermediate.md b/docs/user/guide-intermediate.md index fc7fb76747..333ef88663 100644 --- a/docs/user/guide-intermediate.md +++ b/docs/user/guide-intermediate.md @@ -291,7 +291,7 @@ Cursorless also has good support for operating on parts of a token. Cursorless can recognize and operate on words within a snake_case, camelCase, or PascalCase token. - `"chuck third word air"` or `"chuck last word air"` to delete `"_cherry"` from `"apple_banana_cherry"`. -- `"change second past third word air"` to delete `"BananaCherry"` from `"AppleBananaCherryDate"`. +- `"chuck second past third word air"` to delete `"BananaCherry"` from `"AppleBananaCherryDate"`. - `"chuck last 2 words air"` to delete the last two words of the air token. - `"chuck tail token third word air"` to delete from the third word to the last word of the air token. It is probably easier to do `"chuck third word past last word air"`.