Document custom command action (#2921)

Co-authored-by: Pokey Rule <[email protected]>

Author: AndreasArvidsson

cursorless-talon-dev/src/cursorless_test.talon

@@ -32,8 +32,8 @@ test api extract decorated marks <user.cursorless_target>:
 test api alternate highlight nothing:
     user.private_cursorless_test_alternate_highlight_nothing()
 
-test api parsed: user.cursorless_custom_command("chuck block")
+test api parsed: user.cursorless_x_custom_command("chuck block")
 test api parsed <user.cursorless_target>:
-    user.cursorless_custom_command("chuck block <target>", cursorless_target)
+    user.cursorless_x_custom_command("chuck block <target>", cursorless_target)
 test api parsed <user.cursorless_target> plus <user.cursorless_target>:
-    user.cursorless_custom_command("bring block <target1> after <target2>", cursorless_target_1, cursorless_target_2)
+    user.cursorless_x_custom_command("bring block <target1> after <target2>", cursorless_target_1, cursorless_target_2)

cursorless-talon/src/public_api.py

@@ -26,7 +26,7 @@ def cursorless_create_destination(
 
 @mod.action_class
 class CommandActions:
-    def cursorless_custom_command(
+    def cursorless_x_custom_command(
         content: str,  # pyright: ignore [reportGeneralTypeIssues]
         arg1: Optional[Any] = None,
         arg2: Optional[Any] = None,

packages/cursorless-org-docs/src/docs/user/customization.md

@@ -204,3 +204,40 @@ _You can disable the default Cursorless reformat command by prefixing the spoken
 <user.formatters> form <user.cursorless_target>:
     user.cursorless_reformat(cursorless_target, formatters)
 ```
+
+### Experimental custom command action
+
+:::warning
+
+This feature is experimental! Not as thoroughly tested as the rest of Cursorless and might change in the future. Early adopters should subscribe to this [discussion](https://github.com/cursorless-dev/cursorless/discussions/2942) to get updates about breaking changes\_
+
+:::
+
+`user.cursorless_x_custom_command(command: string, *args)`
+
+Run a custom Cursorless command by parsing the specified command string. Supports a subset of the Cursorless grammar, with **default** spoken forms (not your custom spoken forms). See https://www.cursorless.org/custom-command-railroad to see the subset of our grammar that we support today.
+
+- Utilizes default Cursorless spoken forms in the command string.
+- Optional target arguments can be interpolated in the command string. (see examples below)
+
+#### Examples
+
+In order to map `"scratch"` to perform `"chuck block"`:
+
+```talon
+scratch: user.cursorless_x_custom_command("chuck block")
+```
+
+To map `"scratch air"` => `"chuck block air"`
+
+```talon
+scratch <user.cursorless_target>:
+    user.cursorless_x_custom_command("chuck block <target>", cursorless_target)
+```
+
+To map `"combine air plus bat"` => `"bring block air after bat"`
+
+```talon
+combine <user.cursorless_target> plus <user.cursorless_target>:
+    user.cursorless_x_custom_command("bring block <target1> after <target2>", cursorless_target_1, cursorless_target_2)
+```