From 21180cfb601e7a65a7c42703517b86b49cfe7065 Mon Sep 17 00:00:00 2001 From: Will Sommers Date: Sat, 28 May 2022 10:56:13 -0400 Subject: [PATCH 1/7] Add various additions to documentation --- docs/user/README.md | 104 ++++++++++++++++++++++++++++++++------------ 1 file changed, 76 insertions(+), 28 deletions(-) diff --git a/docs/user/README.md b/docs/user/README.md index 9d197d2781..d6f78b0358 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -128,33 +128,37 @@ Note that if the mark is `"this"`, and you have multiple cursors, the modifiers For programming languages where Cursorless has rich parse tree support, we support modifiers that expand to the nearest containing function, class, etc. See [the source code](../../src/languages/constants.ts) for a list of supported languages. Below is a list of supported scope types, keeping in mind that this table can sometimes lag behind the actual list. Your cheatsheet (say "cursorless help") will have the most up-to-date list. -| Term | Syntactic element | -| -------------- | --------------------------------------------------- | -| `"arg"` | function parameter or function call argument | -| `"attribute"` | attribute, eg on html element | -| `"call"` | function call, eg `foo(1, 2)` | -| `"class name"` | the name in a class declaration | -| `"class"` | class definition | -| `"comment"` | comment | -| `"condition"` | condition, eg in an if statement, while loop etc | -| `"element"` | xml element | -| `"end tag"` | xml end tag | -| `"funk name"` | the name in a function declaration | -| `"funk"` | name function declaration | -| `"if state"` | if statement | -| `"item"` | an entry in a map / object / list | -| `"key"` | key in a map / object | -| `"lambda"` | anonymous lambda function | -| `"list"` | list / array | -| `"map"` | map / object | -| `"name"` | the name in a declaration (eg function name) | -| `"regex"` | regular expression | -| `"start tag"` | xml start tag | -| `"state"` | a statement, eg `let foo;` | -| `"string"` | string | -| `"tags"` | xml both tags | -| `"type"` | a type annotation or declaration | -| `"value"` | a value eg in a map / object, return statement, etc | +| Term | Syntactic element | +| ------------------- | ----------------------------------------------------------------- | +| **Language Scopes** | Scopes that rely a language's syntax | +| `"arg"` | function parameter or function call argument | +| `"attribute"` | attribute, eg on html element | +| `"call"` | function call, eg `foo(1, 2)` | +| `"class name"` | the name in a class declaration | +| `"class"` | class definition | +| `"comment"` | comment | +| `"condition"` | condition, eg in an if statement, while loop etc | +| `"element"` | xml element | +| `"end tag"` | xml end tag | +| `"funk name"` | the name in a function declaration | +| `"funk"` | name function declaration | +| `"if state"` | if statement | +| `"item"` | an entry in a map / object / list | +| `"key"` | key in a map / object | +| `"lambda"` | anonymous lambda function | +| `"list"` | list / array | +| `"map"` | map / object | +| `"name"` | the name in a declaration (eg function name) | +| `"regex"` | regular expression | +| `"start tag"` | xml start tag | +| `"state"` | a statement, eg `let foo;` | +| `"string"` | string | +| `"tags"` | xml both tags | +| `"type"` | a type annotation or declaration | +| `"value"` | a value eg in a map / object, return statement, etc | +| **Textual Scopes** | Scopes that rely on text parsing, ignoring syntax | +| `"paragraph"` | a set of lines not separated by an starting and ending empty line | +| `"paint"` | a selection of contiguous non-whitespace characters | For example, `"take funk blue air"` selects the function containing the token with a blue hat over the letter `'a'`. @@ -202,7 +206,7 @@ Selects the line including the token containing letter 'a' with a blue hat. ##### `"file"` -The word file can be used to expand the target to refer to the entire file. +The word '`"file"` can be used to expand the target to refer to the entire file. - `"copy file"` - `"take file"` @@ -210,6 +214,33 @@ The word file can be used to expand the target to refer to the entire file. For example, `"take file [blue] air"` selects the file including the token containing letter 'a' with a blue hat. +##### `"head & tail"` + +The words `"head"` and `"tail"` can be used to create a selection from the cursor's position, through the beginning or end of the line, respectively. + +- `"take head"`: select from the cursor the start of the line +- `"take tail"`: select from the cursor to the end of the line +- `"take head spun"` +- `"take tail spun"` + +When you have a single cursor point and issue the first two commands, a selection will be made from that position to either the beginning or end of the file. If you have any code highlighted or address a mark(see last two examples) a selection joining the existing selection plus either the beginning or end of the line. + +##### `"paragraph"` + +The `"paragraph"` modifier expands to above and below the target to select lines until an empty line is reached. + +- `"take paragraph"` +- `"take paragraph "` + +##### `"paint"` + +The `"paint"` modifier is useful when selecting trailing delimiters or multiple nodes. To be clear, Cursorless tries to do the correct thing selecting a scope or when deleting `"value"` or `"key"`. However, sometimes paint is useful. + +- `"take paint"` +- `"take paint "` + +Both of the commands will expand from a mark and return a selection up until a leading and trailing whitespace character. + ##### Surrounding pair Cursorless has support for expanding the selection to the nearest containing paired delimiter, eg the surrounding parentheses. @@ -401,6 +432,23 @@ The wrap command can be used to wrap a given target with a pair of symbols - `"round wrap "`: wraps the target with parentheses - `"box wrap "`: wraps the target with square brackets +### Slice + +The slice command is used to add multiple cursors to the editor. Each cursor is inserted at the same column on each row requested within the command. + +- `"pre slice "` +- `"pre slice (past|until) "` + +The first command is equivalent to the second command when `"past"` is used. When `"until"` is used in the second command, cursors are inserted from the first target through to the line above the second target. + +### Reverse/Shuffle/Sort + +These commands are to be paired with the `"item"` scope and can be used to reorder items within a list. + +- `"shuffle every item "` +- `"sort every item "` +- `"reverse every item "` + eg: `box wrap blue air` Wraps the token containing letter 'a' with a blue hat in square brackets. From 338e6ab68d50025c5893f7164db01d8fb2d16270 Mon Sep 17 00:00:00 2001 From: Will Sommers Date: Tue, 31 May 2022 16:41:03 -0400 Subject: [PATCH 2/7] Add head/tail to scopes list --- cursorless-talon/src/cheatsheet/sections/scopes.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cursorless-talon/src/cheatsheet/sections/scopes.py b/cursorless-talon/src/cheatsheet/sections/scopes.py index a9df0cd2a5..5f566b42c7 100644 --- a/cursorless-talon/src/cheatsheet/sections/scopes.py +++ b/cursorless-talon/src/cheatsheet/sections/scopes.py @@ -4,7 +4,7 @@ def get_scopes(): return { **get_lists( - ["scope_type", "selection_type", "subtoken_scope_type"], + ["scope_type", "selection_type", "subtoken_scope_type", "head_tail"], {"argumentOrParameter": "Argument"}, ), "

": "Paired delimiter", From f50df540c7d1edab8cc2a1b348829712a62064fd Mon Sep 17 00:00:00 2001 From: Will Sommers Date: Tue, 31 May 2022 17:14:18 -0400 Subject: [PATCH 3/7] Update Readme according to feedback --- docs/user/README.md | 102 +++++++++++++++++++++----------------------- 1 file changed, 49 insertions(+), 53 deletions(-) diff --git a/docs/user/README.md b/docs/user/README.md index c18b238fa9..354909d202 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -128,37 +128,33 @@ Note that if the mark is `"this"`, and you have multiple cursors, the modifiers For programming languages where Cursorless has rich parse tree support, we support modifiers that expand to the nearest containing function, class, etc. See [the source code](../../src/languages/constants.ts) for a list of supported languages. Below is a list of supported scope types, keeping in mind that this table can sometimes lag behind the actual list. Your cheatsheet (say "cursorless help") will have the most up-to-date list. -| Term | Syntactic element | -| ------------------- | ----------------------------------------------------------------- | -| **Language Scopes** | Scopes that rely a language's syntax | -| `"arg"` | function parameter or function call argument | -| `"attribute"` | attribute, eg on html element | -| `"call"` | function call, eg `foo(1, 2)` | -| `"class name"` | the name in a class declaration | -| `"class"` | class definition | -| `"comment"` | comment | -| `"condition"` | condition, eg in an if statement, while loop etc | -| `"element"` | xml element | -| `"end tag"` | xml end tag | -| `"funk name"` | the name in a function declaration | -| `"funk"` | name function declaration | -| `"if state"` | if statement | -| `"item"` | an entry in a map / object / list | -| `"key"` | key in a map / object | -| `"lambda"` | anonymous lambda function | -| `"list"` | list / array | -| `"map"` | map / object | -| `"name"` | the name in a declaration (eg function name) | -| `"regex"` | regular expression | -| `"start tag"` | xml start tag | -| `"state"` | a statement, eg `let foo;` | -| `"string"` | string | -| `"tags"` | xml both tags | -| `"type"` | a type annotation or declaration | -| `"value"` | a value eg in a map / object, return statement, etc | -| **Textual Scopes** | Scopes that rely on text parsing, ignoring syntax | -| `"paragraph"` | a set of lines not separated by an starting and ending empty line | -| `"paint"` | a selection of contiguous non-whitespace characters | +| Term | Syntactic element | +| -------------- | --------------------------------------------------- | +| `"arg"` | function parameter or function call argument | +| `"attribute"` | attribute, eg on html element | +| `"call"` | function call, eg `foo(1, 2)` | +| `"class name"` | the name in a class declaration | +| `"class"` | class definition | +| `"comment"` | comment | +| `"condition"` | condition, eg in an if statement, while loop etc | +| `"element"` | xml element | +| `"end tag"` | xml end tag | +| `"funk name"` | the name in a function declaration | +| `"funk"` | name function declaration | +| `"if state"` | if statement | +| `"item"` | an entry in a map / object / list | +| `"key"` | key in a map / object | +| `"lambda"` | anonymous lambda function | +| `"list"` | list / array | +| `"map"` | map / object | +| `"name"` | the name in a declaration (eg function name) | +| `"regex"` | regular expression | +| `"start tag"` | xml start tag | +| `"state"` | a statement, eg `let foo;` | +| `"string"` | string | +| `"tags"` | xml both tags | +| `"type"` | a type annotation or declaration | +| `"value"` | a value eg in a map / object, return statement, etc | For example, `"take funk blue air"` selects the function containing the token with a blue hat over the letter `'a'`. @@ -216,30 +212,28 @@ For example, `"take file [blue] air"` selects the file including the token conta ##### `"head & tail"` -The words `"head"` and `"tail"` can be used to create a selection from the cursor's position, through the beginning or end of the line, respectively. +The words `"head"` and `"tail"` can be used to create a selection from the input mark, through the beginning or end of the line, respectively. - `"take head"`: select from the cursor the start of the line - `"take tail"`: select from the cursor to the end of the line -- `"take head spun"` -- `"take tail spun"` +- `"take head air"`: selects the mark through to start of the line +- `"take tail air"`: selects the mark through to the end of the line -When you have a single cursor point and issue the first two commands, a selection will be made from that position to either the beginning or end of the file. If you have any code highlighted or address a mark(see last two examples) a selection joining the existing selection plus either the beginning or end of the line. +##### `"block"` -##### `"paragraph"` +The `"block"` modifier expands to above and below the target to select lines until an empty line is reached. -The `"paragraph"` modifier expands to above and below the target to select lines until an empty line is reached. - -- `"take paragraph"` -- `"take paragraph "` +- `"take block"` +- `"take block "` ##### `"paint"` -The `"paint"` modifier is useful when selecting trailing delimiters or multiple nodes. To be clear, Cursorless tries to do the correct thing selecting a scope or when deleting `"value"` or `"key"`. However, sometimes paint is useful. +Both of the commands below will expand from the mark forward and backward to include all adjacent non-whitespace characters. - `"take paint"` - `"take paint "` -Both of the commands will expand from a mark and return a selection up until a leading and trailing whitespace character. +The `"paint"` modifier is useful when selecting trailing delimiters or multiple nodes. To be clear, Cursorless tries to do the correct thing selecting a scope or when deleting `"value"` or `"key"`. However, sometimes paint is useful. ##### Surrounding pair @@ -425,29 +419,31 @@ eg: `move blue air to green bat` Replaces the token containing letter 'b' with a green hat using the token containing letter 'a' with a blue hat, and the delete the latter token. -### Wrap/Rewrap - -The wrap command can be used to wrap a given target with a pair of symbols - -- `"round wrap "`: wraps the target with parentheses -- `"box wrap "`: wraps the target with square brackets - ### Slice The slice command is used to add multiple cursors to the editor. Each cursor is inserted at the same column on each row requested within the command. - `"pre slice "` -- `"pre slice (past|until) "` - -The first command is equivalent to the second command when `"past"` is used. When `"until"` is used in the second command, cursors are inserted from the first target through to the line above the second target. +- `"pre slice past "`: Add cursors from the first target through to the second target's line(inclusive end) +- `"pre slice until "`: Add cursors until the second target's line(non-inclusive end) +- `"pre slice between "`: Add cursors between first and second target's lines(non-inclusive start and end) ### Reverse/Shuffle/Sort -These commands are to be paired with the `"item"` scope and can be used to reorder items within a list. +These commands are to be paired with the `"item"` scope or can be used with multiple selections. - `"shuffle every item "` - `"sort every item "` - `"reverse every item "` +- `"sort line air slice bat"`: sort lines within the selection. +- `"sort this"`: Sort the multiple selections. + +### Wrap/Rewrap + +The wrap command can be used to wrap a given target with a pair of symbols + +- `"round wrap "`: wraps the target with parentheses +- `"box wrap "`: wraps the target with square brackets eg: `box wrap blue air` From c76756cd74cfd2bdc45a0a2b4c0cb31e155eccba Mon Sep 17 00:00:00 2001 From: Pokey Rule <755842+pokey@users.noreply.github.com> Date: Wed, 17 Aug 2022 14:27:07 +0100 Subject: [PATCH 4/7] Apply suggestions from code review --- docs/user/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/README.md b/docs/user/README.md index 991be1fa41..9743adcd26 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -447,8 +447,8 @@ Replaces the token containing letter 'b' with a green hat using the token contai The slice command is used to add multiple cursors to the editor. Each cursor is inserted at the same column on each row requested within the command. -- `"pre slice "` - `"pre slice past "`: Add cursors from the first target through to the second target's line(inclusive end) +- `"pre slice "`: Shortened version of above `"slice past"` command - `"pre slice until "`: Add cursors until the second target's line(non-inclusive end) - `"pre slice between "`: Add cursors between first and second target's lines(non-inclusive start and end) From c43b5c55d9e3ccc5ff856953a9730484cd065067 Mon Sep 17 00:00:00 2001 From: Pokey Rule <755842+pokey@users.noreply.github.com> Date: Wed, 17 Aug 2022 14:35:19 +0100 Subject: [PATCH 5/7] Tweaks --- docs/user/README.md | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/docs/user/README.md b/docs/user/README.md index 9743adcd26..0d6275e842 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -257,7 +257,13 @@ Both of the commands below will expand from the mark forward and backward to inc - `"take paint"` - `"take paint "` -The `"paint"` modifier is useful when selecting trailing delimiters or multiple nodes. To be clear, Cursorless tries to do the correct thing selecting a scope or when deleting `"value"` or `"key"`. However, sometimes paint is useful. +For example, in the following text: + +``` +foo.bar baz|bongo +``` + +Saying `"every paint"` would select `foo.bar` and `baz|bongo`. ##### Surrounding pair @@ -321,6 +327,20 @@ eg: `take blue air past green bat` Selects the range from the token containing letter 'a' with a blue hat past the token containing letter 'b' with a green hat. +##### Vertical ranges + +The `"slice"` range modifier is used to refer to multiple targets that are vertically aligned. It is commonly used with the `"pre"` action to add multiple cursors to the editor. Each cursor is inserted at the same column on each row requested within the command. + +- `"pre slice past "`: Add cursors from the first target through to the second target's line(inclusive end) +- `"pre slice "`: Shortened version of above `"slice past"` command +- `"pre slice until "`: Add cursors until the second target's line(non-inclusive end) +- `"pre slice between "`: Add cursors between first and second target's lines(non-inclusive start and end) + +For example: + +- `"pre air slice bat"`: Places cursors at the same position on every line (inclusive) between token with hat over the `a` and token with the hat over the `b`. The position will be the start of the token with a hat over the `a` +- `"chuck tail air slice end of block"`: Delete the end of every line from air through the end of its non-empty line block. + #### List targets In addition to range targets, cursorless supports list targets, which allow you to refer to multiple targets at the same time. When combined with the `"take"` action, this will result in multiple cursors, for other actions, such as `"chuck"` the action will be applied to all the different targets at once. @@ -443,15 +463,6 @@ eg: `move blue air to green bat` Replaces the token containing letter 'b' with a green hat using the token containing letter 'a' with a blue hat, and the delete the latter token. -### Slice - -The slice command is used to add multiple cursors to the editor. Each cursor is inserted at the same column on each row requested within the command. - -- `"pre slice past "`: Add cursors from the first target through to the second target's line(inclusive end) -- `"pre slice "`: Shortened version of above `"slice past"` command -- `"pre slice until "`: Add cursors until the second target's line(non-inclusive end) -- `"pre slice between "`: Add cursors between first and second target's lines(non-inclusive start and end) - ### Reverse/Shuffle/Sort These commands are to be paired with the `"item"` scope or can be used with multiple selections. From 61307b261a12a893bdebf0d1b4c3460e9c057ce3 Mon Sep 17 00:00:00 2001 From: Pokey Rule <755842+pokey@users.noreply.github.com> Date: Wed, 17 Aug 2022 14:45:04 +0100 Subject: [PATCH 6/7] Tweaks --- docs/user/README.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/user/README.md b/docs/user/README.md index 0d6275e842..bcd69a3975 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -233,15 +233,20 @@ The word '`"file"` can be used to expand the target to refer to the entire file. For example, `"take file [blue] air"` selects the file including the token containing letter 'a' with a blue hat. -##### `"head & tail"` +##### `"head"` and `"tail"` -The words `"head"` and `"tail"` can be used to create a selection from the input mark, through the beginning or end of the line, respectively. +The modifiers `"head"` and `"tail"` can be used to expand a target through the beginning or end of the line, respectively. - `"take head"`: select from the cursor the start of the line - `"take tail"`: select from the cursor to the end of the line - `"take head air"`: selects the mark through to start of the line - `"take tail air"`: selects the mark through to the end of the line +When followed by a modifier, they will expand their input to the start or end of the given modifier range. For example: + +- `"take head funk"`: select from the cursor the start of the containing function +- `"chuck tail class air"`: Delete from the token with a hat over the letter `a` through the end of its containing class + ##### `"token"` The `"token"` modifier expands its input to the nearest containing token. This modifier is often used without a mark, either to select the token adjacent to your cursor or to expand your selection to the nearest containing token range. For example: @@ -465,7 +470,7 @@ Replaces the token containing letter 'b' with a green hat using the token contai ### Reverse/Shuffle/Sort -These commands are to be paired with the `"item"` scope or can be used with multiple selections. +These commands accept multiple selections, and change their order. For example: - `"shuffle every item "` - `"sort every item "` From 8a4957b0d80c1c7159f10b09c35764a578103ec9 Mon Sep 17 00:00:00 2001 From: Pokey Rule <755842+pokey@users.noreply.github.com> Date: Wed, 17 Aug 2022 14:46:44 +0100 Subject: [PATCH 7/7] Revert fix to old cheatsheet --- cursorless-talon/src/cheatsheet/sections/scopes.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cursorless-talon/src/cheatsheet/sections/scopes.py b/cursorless-talon/src/cheatsheet/sections/scopes.py index 8a8c3abb5a..1df251ac69 100644 --- a/cursorless-talon/src/cheatsheet/sections/scopes.py +++ b/cursorless-talon/src/cheatsheet/sections/scopes.py @@ -4,7 +4,7 @@ def get_scopes(): return { **get_lists( - ["scope_type", "subtoken_scope_type", "head_tail"], + ["scope_type", "subtoken_scope_type"], {"argumentOrParameter": "Argument"}, ), "

": "Paired delimiter",