From 813387b45e3661e06f6a4e9faf18369d0beb53f6 Mon Sep 17 00:00:00 2001 From: Jacob Egner Date: Mon, 31 Jul 2023 10:26:29 -0500 Subject: [PATCH 1/3] add `"just"` section to reference page --- docs/user/README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/user/README.md b/docs/user/README.md index 70cc5cd7ff..299ce48703 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -331,6 +331,26 @@ If your cursor is touching a token, you can say `"take every instance"` to selec Pro tip: if you say eg `"take five instances air"`, and it turns out you need more, you can say eg `"take that and next two instances that"` to select the next two instances after the last instance you selected. +##### `"just"` + +The `"just"` modifier strips the target of any semantic information, treating it as just a raw range. +This stripping to a raw range has a few implications... + +- A raw range will not have any recognized delimeters. + For example... + - `"chuck just line"` will delete only the content of the current line. + The line delimeter (a line ending) remains and the result is a blank line. + - For comparison, `"chuck line"` will delete the current line content and its line ending, so there is one fewer line in the file. +- A raw range will inherit insertion delimiters from its source in the case of a bring. + For example, the difference between `"bring arg air and bat after just left paren"` and `"bring arg air and bat after token left paren"` will tell Cursorless to use `, ` as the delimiter when joining air and bat instead of using the token delimiters that `"token left paren"` would have. +- In the case of `"instance"`, by default `"every instance air"` will only consider instances of the air token that are themselves full tokens, but `"every instance just air"` doesn't have such a restriction, because we've stripped air of its semantic "token-ness". + +Some examples: + +- `"chuck just air"`: deletes just the air token, leaving spaces undisturbed. +- `"chuck just line"`: deletes just the content of the line, leaving a blank line. +- `"bring bat after just air"`: results in something like `aaabbb` where the bat token was copied after the air token with no delimeter between them. + ###### Experimental: `"from"` We have experimental support for prefixing a command with `"from "` to narrow the range within which `"every instance"` searches, or to set the start point from which `"next instance"` searches. For example: From 2564f38f2145ace539bfd01691b824f947615114 Mon Sep 17 00:00:00 2001 From: Pokey Rule <755842+pokey@users.noreply.github.com> Date: Wed, 2 Aug 2023 11:24:15 +0100 Subject: [PATCH 2/3] Wordsmithing --- docs/user/README.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/user/README.md b/docs/user/README.md index 299ce48703..e461d49d9d 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -333,17 +333,15 @@ Pro tip: if you say eg `"take five instances air"`, and it turns out you need mo ##### `"just"` -The `"just"` modifier strips the target of any semantic information, treating it as just a raw range. -This stripping to a raw range has a few implications... - -- A raw range will not have any recognized delimeters. - For example... - - `"chuck just line"` will delete only the content of the current line. - The line delimeter (a line ending) remains and the result is a blank line. - - For comparison, `"chuck line"` will delete the current line content and its line ending, so there is one fewer line in the file. -- A raw range will inherit insertion delimiters from its source in the case of a bring. - For example, the difference between `"bring arg air and bat after just left paren"` and `"bring arg air and bat after token left paren"` will tell Cursorless to use `, ` as the delimiter when joining air and bat instead of using the token delimiters that `"token left paren"` would have. -- In the case of `"instance"`, by default `"every instance air"` will only consider instances of the air token that are themselves full tokens, but `"every instance just air"` doesn't have such a restriction, because we've stripped air of its semantic "token-ness". +The `"just"` modifier strips the target of any semantic information, treating it as just a raw range, with the following effects: + +- The new target has no leading or trailing delimiters. For example: + - `"chuck just air"` will delete just the air token, leaving spaces undisturbed, unlike the default behaviour of `"chuck air"` that deletes the air token along with any leading or trailing spaces. + - `"chuck just line"` will delete only the content of the current line, without removing the line ending, resulting in a blank line, unlike the default behaviour of `"chuck line"` that removes the line entirely, leaving no blank line. +- A raw range does not have its own insertion delimitiers. + - For example, `"paste after just air"` will paste directly after the air token, without inserting a space, as opposed to the way `"paste after air"` would insert a space before the pasted content. + - If you use `"just"` on the destination of a `"bring"` command, it will inherit its insertion delimiters from the source of the `"bring"` action. For example, in the command `"bring arg air and bat after just paren"`, the `"air"` and `"bat"` arguments will be joined by commas. In contrast, `"bring arg air and bat after token paren"` would join the arguments with spaces. +- In the case of [`"instance"`](#instance), by default `"every instance air"` will only consider instances of the air token that are themselves full tokens, but `"every instance just air"` doesn't have such a restriction, because we've stripped air of its semantic "token-ness". Some examples: From 22bab26897bd7afa153f54ab4207c9a1ebea95ce Mon Sep 17 00:00:00 2001 From: Pokey Rule <755842+pokey@users.noreply.github.com> Date: Mon, 7 Aug 2023 15:29:13 +0100 Subject: [PATCH 3/3] Tweak wording --- docs/user/README.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/user/README.md b/docs/user/README.md index e461d49d9d..bae2e29822 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -336,8 +336,17 @@ Pro tip: if you say eg `"take five instances air"`, and it turns out you need mo The `"just"` modifier strips the target of any semantic information, treating it as just a raw range, with the following effects: - The new target has no leading or trailing delimiters. For example: - - `"chuck just air"` will delete just the air token, leaving spaces undisturbed, unlike the default behaviour of `"chuck air"` that deletes the air token along with any leading or trailing spaces. + + - `"chuck just air"` will delete just the air token, leaving adjacent spaces undisturbed, unlike the default behaviour of `"chuck air"` that deletes the air token _and_ cleans up adjacent whitespace as appropriate. Ie for + + ``` + bbb aaa ccc + ``` + + `"chuck just air"` would result in `bbb ccc` (note the double space in the middle), whereas `"chuck air"` would result in `bbb ccc`. + - `"chuck just line"` will delete only the content of the current line, without removing the line ending, resulting in a blank line, unlike the default behaviour of `"chuck line"` that removes the line entirely, leaving no blank line. + - A raw range does not have its own insertion delimitiers. - For example, `"paste after just air"` will paste directly after the air token, without inserting a space, as opposed to the way `"paste after air"` would insert a space before the pasted content. - If you use `"just"` on the destination of a `"bring"` command, it will inherit its insertion delimiters from the source of the `"bring"` action. For example, in the command `"bring arg air and bat after just paren"`, the `"air"` and `"bat"` arguments will be joined by commas. In contrast, `"bring arg air and bat after token paren"` would join the arguments with spaces.