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)