Expand cursorless talon command api

[pokey]

We'd like for users to be able to define more complex custom grammars. To do so, they'll need full access to the types of commands supported by cursorless, whereas today they can just do a single target, with no extra arguments

• Support multiple targets
• Support extraArgs
• Support getText action
• Document target api representation and allow users to pass in home-made targets
• Require user to specify api version number if they use home-made targets
• Add support for reformat action to our custom api #2246
• Add actions.user.cursorless_implicit_target_command?
• Important to include version number for backwards compatibility

Proposal

See #492 (comment) below

Old proposal

• Create a new action called cursorless_target that accepts a list of scope ids, followed by an optional target dict. Can accept None as last arg as well and that's equivalent to "this" / omitting mark. If it gets a target it prepends the containing scope modifiers to the target's modifiers
• In the future we can support things like cursorless_target("every", "collectionItem", "this")

Example

complete [<user.cursorless_target>]:
    target = user.cursorless_target("collectionItem", cursorless_target)
    user.cursorless_command("setSelectionBefore", target)
    key(right:3 delete x)

More verbose alternative

complete [<user.cursorless_target>]:
    user_target = cursorless_target or "this"
    item_modifier = user.cursorless_containing_scope("collectionItem")
    target = user.cursorless_add_modifier(item_modifier, user_target)
    # Could reduce the above two lines to:
    # target = user.cursorless_expand_to_scope("collectionItem", user_target)

Use cases

Checking a box in a markdown checklist

See also #452 and #453

Consider if we want to support extending/overriding other internal cursorless features.

eg support for when focus is not on the text editor. #1717 (comment)

[tararoys]

Allow custom grammars for reformat action is what I vote!

[josharian]

Sample use case:

hug <phrase>$:
    mimic("chuck leading " + phrase)
kiss <phrase>$:
    mimic("chuck trailing " + phrase)
(cosy|cozy) <phrase>$:
    m = "chuck leading " + phrase
    m = m + " and trailing " 
    m = m + phrase
    mimic(m)

[josharian]

Since it often helps to have concrete, real world use cases written down, here is a running list of things I am currently implementing using mimic. (Will update it over time.)

pre line <x>
chuck leading <x>
chuck trailing <x>

[josharian]

GitHub failed to backlink this comment, so here it is manually: #1655 (comment)

[pokey]

update from meet-up: there are a couple approaches

Use csvs

We could have custom modifier and action csvs which map from a spoken form to some representation of compound modifiers / actions. Here are a couple possibilities for representing "chuck previous char" as a custom action:

• remove previous character
• remove relative(-1; character)
• remove relative(-1) character
• remove <~ relative(-1; character)
• relative(-1; character) | remove (inspired by jq)

Benefit of using identifiers rather than spoken form is that they can change spoken form without breaking these, at the expense of being a bit harder to read / write

In a csv this would be something like

experimental/custom_actions.csv:

Spoken form, value
shave, remove <~ relative(-1; character)

For custom modifiers, we could have another csv where it's the same syntax but without the leading action. Eg

experimental/custom_modifiers.csv:

Spoken form, value
duet, nScopes(2; token)

We could use this syntax in other places, eg

• To pass in to an action eg user.cursorless_command("remove previous character", cursorless_target)
• For use in some kind of "cursorless scripting language" (issue to follow, but in the meantime see sam for inspiration)

Could have a command to automatically generate this syntax, eg "dump modifier two tokens" to type out nScopes(2; token), or "dump action chuck previous char"

The benefit of this csv approach is that it's compact, and these are super easy to share / find in other people's repos, so even if people struggle a bit to read / write the syntax, power users could come up with cool compound modifiers / actions that others steal

Use a set of Talon actions

Another approach is to expose actions that users can use to build up targets. Eg

shave <user.cursorless_target>:
    target = user.cursorless_modifier_relative("character", -1, cursorless_target)
    user.cursorless_action_remove(target)

Note that it's not immediately obvious how to use this approach for custom modifiers, eg "duet" above.

The benefit of this approach is that we don't need to have a custom parser, and the user can easily use it in Python, etc. The syntax will also be familiar for users of Talon / Python

One disadvantage is that we potentially have less flexibility to change things, because we're locked into this api, whereas with our custom grammar we have more wiggle room.

We could add version numbers, eg user.cursorless_v6_modifier_relative, but then we run into an issue where a user might take something returned from user.cursorless_v6_modifier_relative and try to pass it to user.cursorless_v7_action_remove. We effectively have an api surface where each function is kind of its own "api surface island" that needs to be able to interact with anything else. Which we could solve probably with a lot of version numbers on every little object, but that seems painful to maintain

[josharian]

Using the spoken form directly is pretty appealing though. What if it always parsed used the default spoken forms? It’s not too hard to look up the default spoken form, once you understand cursorless well enough to have your own dialect. And they’d be fully transferable from one user to another.

And if needed you could use sql-like placeholders to indicate substitution locations (lots of options here).