Support inline snippets; add Talon snippet api (#1329)

- Fixes #1324
- Fixes #1325 

Note that I created a Talon-side insertion api that supports the full
set of options, including substitutions, targets, and scopes, but
decided to leave it out for now because I'm not sure exactly how it
should look and we don't need it for the mathfly support we're planning
to use it for. In particular, we should probably figure out #803 before
we implement the more complex api because snippets really want a
destination, not a target. I did use the complex Talon-side api to
record some tests of the extension api, though

Here is the complex Talon snippet insertion api in case useful at some
point

<details><summary>Complex talon api</summary>

```diff
From e39e03e3a06a6db4f1edb245a5225037d0ea08d3 Mon Sep 17 00:00:00 2001
From: Pokey Rule <[email protected]>
Date: Fri, 24 Mar 2023 14:22:40 +0000
Subject: [PATCH] Complex insert snippet Talon api

---
 cursorless-talon/src/snippets.py | 35 ++++++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 8 deletions(-)

diff --git a/cursorless-talon/src/snippets.py b/cursorless-talon/src/snippets.py
index a9f100f..409512011 100644
--- a/cursorless-talon/src/snippets.py
+++ b/cursorless-talon/src/snippets.py
@@ -91,15 +91,34 @@ class Actions:
             },
         )
 
-    def cursorless_insert_snippet(body: str):
+    def cursorless_insert_snippet(
+        body: str,
+        target: Optional[dict] = None,
+        scope: Optional[str] = None,
+        snippet_variable: Optional[str] = None,
+        text: Optional[str] = None,
+    ):
         """Inserts a custom snippet"""
-        actions.user.cursorless_implicit_target_command(
-            "insertSnippet",
-            {
-                "type": "custom",
-                "body": body,
-            },
-        )
+        snippet_arg: dict[str, Any] = {
+            "type": "custom",
+            "body": body,
+        }
+        if scope:
+            snippet_arg["scopeType"] = {"type": scope}
+        if snippet_variable:
+            snippet_arg["substitutions"] = {snippet_variable: text}
+
+        if target:
+            actions.user.cursorless_single_target_command_with_arg_list(
+                "insertSnippet",
+                target,
+                [snippet_arg],
+            )
+        else:
+            actions.user.cursorless_implicit_target_command(
+                "insertSnippet",
+                snippet_arg,
+            )
 
     def cursorless_wrap_with_snippet_by_name(
         name: str, variable_name: str, target: dict
-- 
2.39.2

```

</details>

## Checklist

- [x] I have added
[tests](https://www.cursorless.org/docs/contributing/test-case-recorder/)
- [x] I have updated the
[docs](https://github.com/cursorless-dev/cursorless/tree/main/docs) and
[cheatsheet](https://github.com/cursorless-dev/cursorless/tree/main/cursorless-talon/src/cheatsheet)
- [x] I have not broken the cheatsheet

Author: pokey

src/actions/wrap.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass
-from typing import Literal
+from typing import Literal, Union
 
 from talon import Module, actions
 
@@ -9,7 +9,7 @@
 @dataclass
 class Wrapper:
     type: Literal["pairedDelimiter", "snippet"]
-    extra_args: list[str]
+    extra_args: list[Union[str, dict]]
 
 
 mod = Module()
@@ -30,7 +30,26 @@ def cursorless_wrapper(m) -> Wrapper:
             extra_args=[paired_delimiter_info.left, paired_delimiter_info.right],
         )
     except AttributeError:
-        return Wrapper(type="snippet", extra_args=[m.cursorless_wrapper_snippet])
+        snippet_name, variable_name = parse_snippet_location(
+            m.cursorless_wrapper_snippet
+        )
+        return Wrapper(
+            type="snippet",
+            extra_args=[
+                {
+                    "type": "named",
+                    "name": snippet_name,
+                    "variableName": variable_name,
+                }
+            ],
+        )
+
+
+def parse_snippet_location(snippet_location: str) -> tuple[str, str]:
+    [snippet_name, variable_name] = snippet_location.split(".")
+    if snippet_name is None or variable_name is None:
+        raise Exception("Snippet location missing '.'")
+    return (snippet_name, variable_name)
 
 
 # Maps from (action_type, wrapper_type) to action name

src/command.py

@@ -12,7 +12,7 @@
 mod = Module()
 
 CURSORLESS_COMMAND_ID = "cursorless.command"
-CURSORLESS_COMMAND_VERSION = 4
+CURSORLESS_COMMAND_VERSION = 5
 last_phrase = None
 
 

src/cursorless_snippets.talon

@@ -8,4 +8,4 @@ tag: user.cursorless
     user.cursorless_single_target_command(cursorless_insert_snippet_action, cursorless_positional_target, cursorless_insertion_snippet)
 
 {user.cursorless_insert_snippet_action} {user.cursorless_insertion_snippet_single_phrase} <user.text> [{user.cursorless_phrase_terminator}]:
-    user.cursorless_insert_snippet_with_phrase(cursorless_insert_snippet_action, cursorless_insertion_snippet_single_phrase, text)
+    user.private_cursorless_insert_snippet_with_phrase(cursorless_insert_snippet_action, cursorless_insertion_snippet_single_phrase, text)

src/snippets.py

@@ -1,3 +1,5 @@
+from typing import Any, Optional
+
 from talon import Module, actions, app
 
 from .csv_overrides import init_csv_and_watch_changes
@@ -27,13 +29,13 @@
 @mod.capture(
     rule="{user.cursorless_insertion_snippet_no_phrase} | {user.cursorless_insertion_snippet_single_phrase}"
 )
-def cursorless_insertion_snippet(m) -> str:
+def cursorless_insertion_snippet(m) -> dict:
     try:
-        return m.cursorless_insertion_snippet_no_phrase
+        name = m.cursorless_insertion_snippet_no_phrase
     except AttributeError:
-        pass
+        name = m.cursorless_insertion_snippet_single_phrase.split(".")[0]
 
-    return m.cursorless_insertion_snippet_single_phrase.split(".")[0]
+    return {"type": "named", "name": name}
 
 
 # NOTE: Please do not change these dicts.  Use the CSVs for customization.
@@ -65,13 +67,76 @@ def cursorless_insertion_snippet(m) -> str:
 
 @mod.action_class
 class Actions:
-    def cursorless_insert_snippet_with_phrase(
+    def private_cursorless_insert_snippet_with_phrase(
         action: str, snippet_description: str, text: str
     ):
         """Perform cursorless wrap action"""
         snippet_name, snippet_variable = snippet_description.split(".")
         actions.user.cursorless_implicit_target_command(
-            action, snippet_name, {snippet_variable: text}
+            action,
+            {
+                "type": "named",
+                "name": snippet_name,
+                "substitutions": {snippet_variable: text},
+            },
+        )
+
+    def cursorless_insert_snippet_by_name(name: str):
+        """Inserts a named snippet"""
+        actions.user.cursorless_implicit_target_command(
+            "insertSnippet",
+            {
+                "type": "named",
+                "name": name,
+            },
+        )
+
+    def cursorless_insert_snippet(body: str):
+        """Inserts a custom snippet"""
+        actions.user.cursorless_implicit_target_command(
+            "insertSnippet",
+            {
+                "type": "custom",
+                "body": body,
+            },
+        )
+
+    def cursorless_wrap_with_snippet_by_name(
+        name: str, variable_name: str, target: dict
+    ):
+        """Wrap target with a named snippet"""
+        actions.user.cursorless_single_target_command_with_arg_list(
+            "wrapWithSnippet",
+            target,
+            [
+                {
+                    "type": "named",
+                    "name": name,
+                    "variableName": variable_name,
+                }
+            ],
+        )
+
+    def cursorless_wrap_with_snippet(
+        body: str,
+        target: dict,
+        variable_name: Optional[str] = None,
+        scope: Optional[str] = None,
+    ):
+        """Wrap target with a custom snippet"""
+        snippet_arg: dict[str, Any] = {
+            "type": "custom",
+            "body": body,
+        }
+        if scope is not None:
+            snippet_arg["scopeType"] = {"type": scope}
+        if variable_name is not None:
+            snippet_arg["variableName"] = variable_name
+
+        actions.user.cursorless_single_target_command_with_arg_list(
+            "wrapWithSnippet",
+            target,
+            [snippet_arg],
         )