Generic scope handler interfaces

cursorless-talon/src/cheatsheet_html/sections/modifiers.py

@@ -121,6 +121,10 @@ def get_modifiers():
                     "spokenForm": f"{complex_modifiers['previous']} <number> <scope>s",
                     "description": "previous <number> instances of <scope>",
                 },
+                {
+                    "spokenForm": f"<scope> {complex_modifiers['backward']}",
+                    "description": "single instance of <scope> including target, going backwards",
+                },
                 {
                     "spokenForm": f"<number> <scope>s {complex_modifiers['backward']}",
                     "description": "<number> instances of <scope> including target, going backwards",

cursorless-talon/src/modifiers/relative_scope.py

@@ -56,11 +56,23 @@ def cursorless_relative_scope_count(m) -> dict[str, Any]:
     )
 
 
+@mod.capture(rule="<user.cursorless_scope_type> {user.cursorless_backward_modifier}")
+def cursorless_relative_scope_one_backward(m) -> dict[str, Any]:
+    """Take scope backward, eg `funk backward`"""
+    return create_relative_scope_modifier(
+        m.cursorless_scope_type,
+        0,
+        1,
+        m.cursorless_backward_modifier,
+    )
+
+
 @mod.capture(
     rule=(
         "<user.cursorless_relative_scope_singular> | "
         "<user.cursorless_relative_scope_plural> | "
-        "<user.cursorless_relative_scope_count>"
+        "<user.cursorless_relative_scope_count> | "
+        "<user.cursorless_relative_scope_one_backward>"
     )
 )
 def cursorless_relative_scope(m) -> dict[str, Any]:

cursorless-talon/src/modifiers/scopes.py

@@ -58,6 +58,7 @@
     # Text-based scope types
     "char": "character",
     "word": "word",
+    "identifier": "identifier",
     "block": "paragraph",
     "cell": "notebookCell",
     "file": "document",

docs/user/README.md

@@ -281,6 +281,16 @@ The `"token"` modifier expands its input to the nearest containing token. This m
 - `"take token"`
 - `"chuck token"`
 
+##### `"identifier`
+
+The `"identifier"` modifier behaves like `"token"`, but only considers tokens that are viable identifiers. For example `"identifier"` could be used to select `foo`, `fooBar`, or `foo_bar`, but not `.`, `=`, `+=`, etc. For example:
+
+- `"copy identifier"`
+- `"take identifier"`
+- `"chuck identifier"`
+
+This scope type is useful with ordinals, allowing you to say eg `"last identifier"` to refer to the last identifier on the current line.
+
 ##### `"paint"`
 
 Both of the commands below will expand from the mark forward and backward to include all adjacent non-whitespace characters.

src/core/commandVersionUpgrades/upgradeV2ToV3/targetDescriptorV2.types.ts

@@ -1,32 +1,28 @@
 import { HatStyleName } from "../../hatStyles";
 
-export interface CursorMark {
+interface CursorMark {
   type: "cursor";
 }
 
-export interface ThatMark {
+interface ThatMark {
   type: "that";
 }
 
-export interface SourceMark {
+interface SourceMark {
   type: "source";
 }
 
-export interface NothingMark {
+interface NothingMark {
   type: "nothing";
 }
 
-export interface LastCursorPositionMark {
-  type: "lastCursorPosition";
-}
-
-export interface DecoratedSymbolMark {
+interface DecoratedSymbolMark {
   type: "decoratedSymbol";
   symbolColor: HatStyleName;
   character: string;
 }
 
-export type LineNumberType = "absolute" | "relative" | "modulo100";
+type LineNumberType = "absolute" | "relative" | "modulo100";
 
 export interface LineNumberPositionV2 {
   type: LineNumberType;
@@ -48,7 +44,7 @@ export type MarkV2 =
   | NothingMark
   | LineNumberMarkV2;
 
-export type SimpleSurroundingPairName =
+type SimpleSurroundingPairName =
   | "angleBrackets"
   | "backtickQuotes"
   | "curlyBrackets"
@@ -60,11 +56,8 @@ export type SimpleSurroundingPairName =
   | "parentheses"
   | "singleQuotes"
   | "squareBrackets";
-export type ComplexSurroundingPairName =
-  | "string"
-  | "any"
-  | "collectionBoundary";
-export type SurroundingPairName =
+type ComplexSurroundingPairName = "string" | "any" | "collectionBoundary";
+type SurroundingPairName =
   | SimpleSurroundingPairName
   | ComplexSurroundingPairName;
 
@@ -123,17 +116,17 @@ export type SimpleScopeTypeTypeV2 =
   | "boundedNonWhitespaceSequence"
   | "url";
 
-export interface SimpleScopeType {
+interface SimpleScopeType {
   type: SimpleScopeTypeTypeV2;
 }
 
-export interface CustomRegexScopeType {
+interface CustomRegexScopeType {
   type: "customRegex";
   regex: string;
 }
 
-export type SurroundingPairDirection = "left" | "right";
-export interface SurroundingPairScopeType {
+type SurroundingPairDirection = "left" | "right";
+interface SurroundingPairScopeType {
   type: "surroundingPair";
   delimiter: SurroundingPairName;
   forceDirection?: SurroundingPairDirection;
@@ -145,37 +138,32 @@ export interface SurroundingPairScopeType {
   requireStrongContainment?: boolean;
 }
 
-export type ScopeType =
+export type ScopeTypeV2 =
   | SimpleScopeType
   | SurroundingPairScopeType
   | CustomRegexScopeType;
 
-export interface ContainingSurroundingPairModifier
-  extends ContainingScopeModifier {
-  scopeType: SurroundingPairScopeType;
-}
-
-export interface InteriorOnlyModifier {
+interface InteriorOnlyModifier {
   type: "interiorOnly";
 }
 
-export interface ExcludeInteriorModifier {
+interface ExcludeInteriorModifier {
   type: "excludeInterior";
 }
 
-export interface ContainingScopeModifier {
+interface ContainingScopeModifier {
   type: "containingScope";
-  scopeType: ScopeType;
+  scopeType: ScopeTypeV2;
 }
 
-export interface EveryScopeModifier {
+interface EveryScopeModifier {
   type: "everyScope";
-  scopeType: ScopeType;
+  scopeType: ScopeTypeV2;
 }
 
-export interface OrdinalRangeModifier {
+export interface OrdinalRangeModifierV2 {
   type: "ordinalRange";
-  scopeType: ScopeType;
+  scopeType: ScopeTypeV2;
   anchor: number;
   active: number;
   excludeAnchor?: boolean;
@@ -187,21 +175,21 @@ export interface OrdinalRangeModifier {
  * example if it is the destination of a bring or move it should inherit the
  * type information such as delimiters from its source.
  */
-export interface RawSelectionModifier {
+interface RawSelectionModifier {
   type: "toRawSelection";
 }
 
-export interface LeadingModifier {
+interface LeadingModifier {
   type: "leading";
 }
 
-export interface TrailingModifier {
+interface TrailingModifier {
   type: "trailing";
 }
 
-export type Position = "before" | "after" | "start" | "end";
+type Position = "before" | "after" | "start" | "end";
 
-export interface PositionModifier {
+interface PositionModifier {
   type: "position";
   position: Position;
 }
@@ -213,7 +201,7 @@ export interface PartialPrimitiveTargetDescriptorV2 {
   isImplicit?: boolean;
 }
 
-export interface HeadTailModifier {
+interface HeadTailModifier {
   type: "extendThroughStartOf" | "extendThroughEndOf";
   modifiers?: ModifierV2[];
 }
@@ -222,7 +210,7 @@ export interface HeadTailModifier {
  * Runs {@link modifier} if the target has no explicit scope type, ie if
  * {@link Target.hasExplicitScopeType} is `false`.
  */
-export interface ModifyIfUntypedModifier {
+interface ModifyIfUntypedModifier {
   type: "modifyIfUntyped";
 
   /**
@@ -236,7 +224,7 @@ export interface ModifyIfUntypedModifier {
  * doesn't throw an error, returning the output from the first modifier not
  * throwing an error.
  */
-export interface CascadingModifier {
+interface CascadingModifier {
   type: "cascading";
 
   /**
@@ -251,7 +239,7 @@ export type ModifierV2 =
   | ExcludeInteriorModifier
   | ContainingScopeModifier
   | EveryScopeModifier
-  | OrdinalRangeModifier
+  | OrdinalRangeModifierV2
   | HeadTailModifier
   | LeadingModifier
   | TrailingModifier
@@ -281,50 +269,7 @@ export type PartialTargetDescriptorV2 =
   | PartialRangeTargetDescriptorV2
   | PartialListTargetDescriptorV2;
 
-export interface PrimitiveTargetDescriptor
-  extends PartialPrimitiveTargetDescriptorV2 {
-  /**
-   * The mark, eg "air", "this", "that", etc
-   */
-  mark: MarkV2;
-
-  /**
-   * Zero or more modifiers that will be applied in sequence to the output from
-   * the mark.  Note that the modifiers will be applied in reverse order.  For
-   * example, if the user says "take first char name air", then we will apply
-   * "name" to the output of "air" to select the name of the function or
-   * statement containing "air", then apply "first char" to select the first
-   * character of the name.
-   */
-  modifiers: ModifierV2[];
-
-  /**
-   * We separate the positional modifier from the other modifiers because it
-   * behaves differently and and makes the target behave like a destination for
-   * example for bring.  This change is the first step toward #803
-   */
-  positionModifier?: PositionModifier;
-}
-
-export interface RangeTargetDescriptor {
-  type: "range";
-  anchor: PrimitiveTargetDescriptor;
-  active: PrimitiveTargetDescriptor;
-  excludeAnchor: boolean;
-  excludeActive: boolean;
-  rangeType: RangeType;
-}
 // continuous is one single continuous selection between the two targets
 // vertical puts a selection on each line vertically between the two targets
 
-export type RangeType = "continuous" | "vertical";
-
-export interface ListTargetDescriptor {
-  type: "list";
-  elements: (PrimitiveTargetDescriptor | RangeTargetDescriptor)[];
-}
-
-export type TargetDescriptor =
-  | PrimitiveTargetDescriptor
-  | RangeTargetDescriptor
-  | ListTargetDescriptor;
+type RangeType = "continuous" | "vertical";

src/core/commandVersionUpgrades/upgradeV2ToV3/upgradeV2ToV3.ts

@@ -17,10 +17,10 @@ import {
   LineNumberPositionV2,
   MarkV2,
   ModifierV2,
-  OrdinalRangeModifier,
+  OrdinalRangeModifierV2,
   PartialPrimitiveTargetDescriptorV2,
   PartialTargetDescriptorV2,
-  ScopeType,
+  ScopeTypeV2,
 } from "./targetDescriptorV2.types";
 
 export function upgradeV2ToV3(command: CommandV2): CommandV3 {
@@ -104,7 +104,7 @@ function createLineNumberMark(
 }
 
 function createOrdinalModifier(
-  modifier: OrdinalRangeModifier
+  modifier: OrdinalRangeModifierV2
 ): OrdinalScopeModifier | RangeModifier {
   if (modifier.anchor === modifier.active) {
     return createAbsoluteOrdinalModifier(modifier.scopeType, modifier.anchor);
@@ -130,7 +130,7 @@ function createLineNumberMarkFromPos(
 }
 
 function createAbsoluteOrdinalModifier(
-  scopeType: ScopeType,
+  scopeType: ScopeTypeV2,
   start: number
 ): OrdinalScopeModifier {
   return {