Iteration-based scope handler interface (#1096)

* Iteration-based scope handler interface

* Remove `getPreferredScopeTouchingPosition`

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* `isPreferredOver` skeleton

* Reintroduce token preferences

* Attempt at more simplification

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Tweak hints

* Cleanup

* Remove `allowNoOverlap` from requirements

* New RelativeInclusive semantics

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add tests

* Migrate early stopping to base class

* More doc tweaks

* More doc tweaks

* More docs

* More docs

* More docs

* More doc strings

* More cleanup

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* More docs

* More docs

* More docs

* Fixes

* More docs

* More docstring tweaks

* Tweak docs

* Address PR comments

* Tweak token `isPreferredOver`

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: pokey

src/modifiers/modifiers.py

@@ -5,7 +5,7 @@
 from .interior import interior_modifiers
 from .ordinal_scope import first_modifiers, last_modifiers
 from .range_type import range_types
-from .relative_scope import backward_modifiers, previous_next_modifiers
+from .relative_scope import forward_backward_modifiers, previous_next_modifiers
 from .simple_scope_modifier import simple_scope_modifiers
 
 mod = Module()
@@ -81,7 +81,7 @@ def on_ready():
             "first_modifier": first_modifiers,
             "last_modifier": last_modifiers,
             "previous_next_modifier": previous_next_modifiers,
-            "backward_modifier": backward_modifiers,
+            "forward_backward_modifier": forward_backward_modifiers,
         },
     )
 

src/modifiers/relative_scope.py

@@ -3,12 +3,17 @@
 from talon import Module
 
 previous_next_modifiers = {"previous": "previous", "next": "next"}
-backward_modifiers = {"backward": "backward"}
+forward_backward_modifiers = {
+    "forward": "forward",
+    "backward": "backward",
+}
 
 mod = Module()
 
 mod.list("cursorless_previous_next_modifier", desc="Cursorless previous/next modifiers")
-mod.list("cursorless_backward_modifier", desc="Cursorless backward modifiers")
+mod.list(
+    "cursorless_forward_backward_modifier", desc="Cursorless forward/backward modifiers"
+)
 
 
 @mod.capture(rule="{user.cursorless_previous_next_modifier}")
@@ -44,26 +49,28 @@ def cursorless_relative_scope_plural(m) -> dict[str, Any]:
 
 
 @mod.capture(
-    rule="<user.private_cursorless_number_small> <user.cursorless_scope_type_plural> [{user.cursorless_backward_modifier}]"
+    rule="<user.private_cursorless_number_small> <user.cursorless_scope_type_plural> [{user.cursorless_forward_backward_modifier}]"
 )
 def cursorless_relative_scope_count(m) -> dict[str, Any]:
     """Relative count scope. `three funks`"""
     return create_relative_scope_modifier(
         m.cursorless_scope_type_plural,
         0,
         m.private_cursorless_number_small,
-        getattr(m, "cursorless_backward_modifier", "forward"),
+        getattr(m, "cursorless_forward_backward_modifier", "forward"),
     )
 
 
-@mod.capture(rule="<user.cursorless_scope_type> {user.cursorless_backward_modifier}")
+@mod.capture(
+    rule="<user.cursorless_scope_type> {user.cursorless_forward_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,
+        m.cursorless_forward_backward_modifier,
     )