Generic scope handler interfaces (cursorless-dev#1031)

* Original scope handlers

* More stuff

* Use proper token stage in sub token stage

* Work around for identifier matcher

* Use new scope handler in relative scope stage

* Use new scope handlers in ordinal scope stage

* Update usage of containing indices

* Rename

* Refactored create target

* Clean up

* clean up

* Add some tests that should pass

* Add a bunch more tests

* Attempt at different approach to scope handlers

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

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

* Initial implementation of new idea

* More work on this stuff

* Rename and add some todos

* More stuff

* Tweaks

* Renames and docstrings

* Restructuring

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

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

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

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

* More jsdocs

* Tweaks

* Test fixes

* Fix error messages

* Revert `OrdinalScopeStage`

* Tweak

* jsdocs; fix import

* Don't export legacy types

* Fix import

* Preparation for surrounding pairs

* Naming cleanup

* Unify `getLegacyScopeStage` functions

* Lots of cleanup

* Fix regex `lastIndex` issue

* More cleanup

* More cleanup

* More cleanup

* Add `ancestorIndex` in prepartion for cursorless-dev#124

* Add more jsdocs

* More docs

* More docs

* docstrings

* Improve hierarchical error type

* Docs

* More minor dog tweaks

* More docs

* More docs

* Doc strings and a couple tests

* Remove `isPreferredOver`

* Support `ancestorIndex` on api surface

* Improved jsdocs

* Split and cleanup relative stages

* Make scope handler constructor args optional

* More legacy type fixes

* Add `"identifier"` scope

* Working new code

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

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

* Docs + cheatsheet

* Update docs

* Add jsdoc

* jsdoc

* JSDocs

* doc tweaks

* reflow

* Tweaks

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

Author: 3 people

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",

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]:

src/modifiers/scopes.py

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