Handle words

Author: pokey

docs/user/README.md

@@ -311,6 +311,26 @@ foo.bar baz|bongo
 
 Saying `"every paint"` would select `foo.bar` and `baz|bongo`.
 
+##### `"instance"`
+
+The `"instance"` modifier searches for occurrences of the text of the target. For example:
+
+- `"take every instance air"`: selects all instances of the token with a hat over the letter `a` in the whole document
+- `"take two instances air"`: selects the first two instances of the token with a hat over the letter `a`, starting from that token itself
+- `"take next instance air"`: selects the next instance of the token with a hat over the letter `a`, starting from that token itself
+- `"chuck every instance two tokens air"`: deletes all occurrences of the two tokens beginning from the token with a hat over the letter `a`. For example if there were a hat over the `a` in `aaa.bbb`, it would delete every occurrence of `aaa.` in the file.
+- `"take every instance air past bat"`: if there were hats over the `a` and `b` in `aaa ccc bbb ddd`, it would selects all occurrences of `aaa ccc bbb` (which is the text corresponding to the range `"air past bat"`)
+
+Note in the final example how the `"instance"` modifier constructs the instance based on the range `"air past bat"`, rather than the individual tokens `"air"` and `"bat"`, as you might expect given the way other modifiers behave. Effectively `"instance"` applies to everything after the `"instance"` modifier, rather than just the next modifier.
+
+Note also that `"instance"` considers the type of target used to construct the instance. So for example, `"take every instance air"` will only select tokens that
+are identical to the token with a hat over the letter `a`, skipping over bigger tokens that contain the token with a hat over the letter `a` as a substring. For example, if there were a hat over the `a` in `aaa`, it would select every occurrence of `aaa` in the file, but not `aaaaa`. If you want to avoid this behaviour, you can
+use the `"just"` modifier, eg `"take every instance just air"`.
+
+If your cursor is touching a token, you can say `"take every instance air"` to select all instances of the given token.
+
+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.
+
 ##### Surrounding pair
 
 Cursorless has support for expanding the selection to the nearest containing paired delimiter, eg the surrounding parentheses, curly brackets, etc.
@@ -351,7 +371,7 @@ For example:
 
 If your cursor / mark is between two delimiters (not adjacent to one), then saying either "left" or "right" will cause cursorless to just expand to the nearest delimiters on either side, without trying to determine whether they are opening or closing delimiters.
 
-#### `"its"`
+##### `"its"`
 
 The the modifier `"its"` is intended to be used as part of a compound target, and will tell Cursorless to use the previously mentioned mark in the compound target.
 

packages/cursorless-engine/src/processTargets/modifiers/InstanceStage.ts

@@ -121,6 +121,12 @@ export default class InstanceStage implements ModifierStage {
     const filterScopeType = getFilterScopeType(target);
 
     if (filterScopeType != null) {
+      // If the target is a line, token or word, we want to filter out any
+      // instances of the text that are not also a line, token or word.  For
+      // those that are, we want to return the target as a line, token or word
+      // target.  For example, if the user says "take every instance air", we
+      // won't return matches where we find the text of the "air" token as part
+      // of a larger token.
       const containingScopeModifier = this.modifierStageFactory.create({
         type: "containingScope",
         scopeType: filterScopeType,
@@ -129,6 +135,9 @@ export default class InstanceStage implements ModifierStage {
       return ifilter(
         imap(iterable, (target) => {
           try {
+            // Just try to expand to the containing scope. If it fails or is not
+            // equal to the target, we know the match is not a line, token or
+            // word.
             const containingScope = containingScopeModifier.run(target);
 
             if (
@@ -160,6 +169,10 @@ function getFilterScopeType(target: Target): ScopeType | null {
     return { type: "token" };
   }
 
+  if (target.isWord) {
+    return { type: "word" };
+  }
+
   return null;
 }
 

packages/cursorless-engine/src/processTargets/targets/BaseTarget.ts

@@ -37,6 +37,7 @@ export default abstract class BaseTarget implements Target {
   isRaw = false;
   isImplicit = false;
   isNotebookCell = false;
+  isWord = false;
 
   constructor(parameters: CommonTargetParameters) {
     this.state = {

packages/cursorless-engine/src/processTargets/targets/SubTokenWordTarget.ts

@@ -14,6 +14,7 @@ export default class SubTokenWordTarget extends BaseTarget {
   private trailingDelimiterRange_?: Range;
   insertionDelimiter: string;
   isToken = false;
+  isWord = true;
 
   constructor(parameters: SubTokenTargetParameters) {
     super(parameters);

packages/cursorless-engine/src/typings/target.types.ts

@@ -47,6 +47,9 @@ export interface Target {
   /** If true this target should be treated as a token */
   readonly isToken: boolean;
 
+  /** If true this target should be treated as a word */
+  readonly isWord: boolean;
+
   /**
    * If `true`, then this target has an explicit scope type, and so should never
    * be automatically expanded to a containing scope.

packages/cursorless-vscode-e2e/src/suite/fixtures/recorded/modifiers/instance/clearTwoInstancesLastWordAir.yml

@@ -0,0 +1,35 @@
+languageId: plaintext
+command:
+  version: 5
+  spokenForm: clear two instances last word air
+  action: {name: clearAndSetSelection}
+  targets:
+    - type: primitive
+      modifiers:
+        - type: relativeScope
+          scopeType: {type: instance}
+          offset: 0
+          length: 2
+          direction: forward
+        - type: ordinalScope
+          scopeType: {type: word}
+          start: -1
+          length: 1
+      mark: {type: decoratedSymbol, symbolColor: default, character: a}
+  usePrePhraseSnapshot: true
+initialState:
+  documentContents: aaaBbb cccBbbb dddBbb
+  selections:
+    - anchor: {line: 0, character: 21}
+      active: {line: 0, character: 21}
+  marks:
+    default.a:
+      start: {line: 0, character: 0}
+      end: {line: 0, character: 6}
+finalState:
+  documentContents: aaa cccBbbb ddd
+  selections:
+    - anchor: {line: 0, character: 3}
+      active: {line: 0, character: 3}
+    - anchor: {line: 0, character: 15}
+      active: {line: 0, character: 15}