Support inline snippets; add Talon snippet api

[pokey]

• Fixes Support rich object as argument to snippet actions #1324
• Fixes Support talon API for inserting and wrapping with snippets #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

Complex talon api

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 a9f100f58..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

Checklist

• I have added tests
• I have updated the docs and cheatsheet
• I have not broken the cheatsheet

[pokey]

A bit annoying we'll have to bump this one every time we increment command version number, but I think it's not unreasonable: we probably do want to be ensuring that the test case recorder is recording tests using the latest command version

[AndreasArvidsson]

Maybe we should have a test to make sure that this test actually contains the latest version?

[pokey]

The test case recorder test fails on this one if you don't bump. Are you saying we should add another test?

[AndreasArvidsson]

Shouldn't this line always be the last person then?

cursorless/packages/cursorless-vscode-e2e/src/suite/testCaseRecorder.test.ts

Line 76 in b07458b

version: 4,

[pokey]

I believe the command that gets captured by recorder is after we do normalisation / upgrade at the start of running the command. So even if we pass 4 there, the command that gets captured has version 5

As to whether that's the right thing to do, I could go either way. I think slightly better to capture normalised version. If we want to be able to record legacy command, we could add a flag to test case recorder to enable that

[pokey]

Tempted to switch custom to inline everywhere. WDYT @AndreasArvidsson ? We already support "custom" snippets, which means ones that aren't part of the built-in Cursorless snippets, so I think this terminology is confusing

[AndreasArvidsson]

But isn't that more or less the same thing? In one instance you send a custom snippet in the other case you define a custom snippet.

[pokey]

The confusing thing is that if you want to use one of the custom snippets you've defined, you don't use custom snippet arg, you use named snippet

[pokey]

• cursorless_insert_custom_snippet => cursorless_insert_snippet
• cursorless_insert_named_snippet => cursorless_insert_snippet_by_name
• cursorless_wrap_with_custom_snippet => cursorless_wrap_with_snippet
• cursorless_wrap_with_named_snippet => cursorless_wrap_with_snippet_by_name