Add "mark" action to bookmark a target

[pokey]

The problem

Cursorless has no way to store a reference to a target for future use. The most obvious use case for this functionality is basic bookmarking, where a user can create a short name for a location in a document to jump back to later.

However, this basic functionality only scratches the surface of what can be done using an operation that creates a named reference to a cursorless target. There are two main aspects to cursorless that makes this type of bookmark far more powerful than what can be done using a simple bookmarking library.

A rich set of actions

The first component is that cursorless supports many different actions. The basic operation of jumping back to a bookmark as described at the top of this issue can be accomplished by issuing the "take" action on the book mark. Even this operation, though, is likely more powerful than with a traditional bookmarks library, because it can be used to restore an exact set of selections, and these selections will be updated even as the document evolves.

However, these bookmarks can also be referred to without ever jumping to them. For example, a user could book mark a location in a file and then browse around their project directory moving statements and functions into that file by using the bookmark as the destination of a "move" command.

Semantically rich targets

The second component that makes cursorless bookmarks powerful is the fact that a cursorless target can be much more than just a location in a document. Cursorless targets can contain rich contextual information such as how the target functions within the parse tree of the file to enable smart updating such as adding new items to a list. Cursorless targets could also be stitched together into cross file bookmarks to enable updating multiple files at the same time. Cursorless targets also needn't be restricted to locations in documents at all. See below for a bit more about this type of use case.

The solution

• Add a new action called "mark" which bookmarks its target. This goes into the default "mark" bookmark, which can then be used in a phrase such as "take mark"
• The user could also say "mark <target> as <word>" and that would create a named bookmark so the user could say "take [mark] <word>"
• The user could also optionally add a color and an icon which would show up in the gutter of the document and the color would be used to highlight the text of the bookmark
• If the user doesn't provide color and icon ones will automatically be chosen for them, or potentially just use gray for the color or don't show a color or don't show an icon if they don't specify. We'll have to figure this one out based on what feels right with usage
• These marks could be in another file, so Have protection against modifying things off screen #45 would apply here
• Marks should be persisted on disk so that they can last across restarts. Might want to keep them within the workspace?
• Would need to automatically keep them up-to-date using Generalize navigation map #191
• Make sure this feature interacts well with notebooks
• Need to leverage Expose state pokey/command-server#8 to expose the list of known bookmarks as a talon list

Fun stuff

In this section we discuss various advanced / experimental possible use cases for cursorless bookmarks. See What's next for more about this type of use case.

Non-positional targets

These bookmarks could actually be used to capture arbitrary targets, literal strings, snippets made on the fly from targets by specifying "holes", etc. This functionality enables much more complex chains because they can extend beyond a single voice command

These "bookmarks" could go into the user's bookmark library to be used again

Pipelines

Could capture recent sequence of commands, or sequence of commands leading to a bookmark, allowing user to turn that into a reusable pipeline that goes into the library as well. Should these pipelines just be a form of bookmark / target as well?

Smart marks

Could be defined via a regex rather than a range, to make them more robust. Would be useful for long-lived marks, marks that are persisted with the repo, and plop.js-like functionality

Social marks

• These bookmarks could be shared with other users, creating a library of reusable pipelines
• For a specific project they could be checked into version control

Viewing marks

• Could have a web view to visualize the marks

[pokey]

update from meet-up:

• keep content range up-to-date using range updater, specifying closedClosed as endpoint semantics
• do debounced re-running of containing scope to see if content range needs to expand so we can keep highlights up-to-date. Only do this for edits that touch one of the endpoints of content range
• when target is actually used, re-run containing again to ensure we have good leading / trailing / whatever else
• examples to consider, using "item" as running example, with original highlight of bbb in [aaa, bbb, ccc]:
  • [aaa, bbb, ddd, ccc] (insertion of , at boundary)
  • [aaa, bbb + ddd, ccc] (insertion of other than , at boundary)
  • [aaa, bb + b, ccc] (insertion of other than , internally)
  • [aaa, bb, b, ccc] (insertion of , internally)