Add `-str` substitution variables to custom REPL commands

[djblue]

Currently, things like $file-text are difficult to use because the raw text of the file is substituted into the custom REPL command, often yielding invalid code. By provided the data as a pre-escaped string, the value of the file can more easily be used in custom REPL commands.

[djblue]

I feel like the underlying issue is getting a value from the editor as data, such as the value of a file as a string. An issue that arises is that there are different chunks of text a user might want; which is why custom repl commands currently have so many variables. An option to solve this issue is to provide all variables as data via edn with a single variable $edn-info:

{:line 1
 :column 20
 :file "/Users/..."
 :file-text "(ns hello.world) (def foo ..)"
 :ns hello.world
 :editor-ns hello.world
 :selection "(def ...)"
 :current-form "(def foo ...)"
 :current-pair  "(def foo ...)"
 :enclosing-for "(def foo ...)"
 :top-level-form "(def foo ...)"
 :current-fn  "(def foo foo ...)"
 :op-level-defined-symbol foo
 :head "..."
 :tail "..."}

However, if this is an expensive data structure to compute and serialize, an alternative representation could be allowing a user to select which keys are available in the serialized edn value with the following syntax:

#calva/info [:line :column :ns]

which could expand into the following minimal edn data structure:

{:line 1 :column 20 :ns hello.world}

@PEZ please let me know if this comment clear up the issue.

[PEZ]

Thanks for this suggestion, @djblue!

I like the idea to stop and ponder a bit before we continue to just add variables flatly as we have been doing so far. Some things for us to remember in fixing this are:

1. We need to make sure the current variables continue working
2. Some of the variables have hover- counterparts that are used by the custom REPL hover commands.
3. We support configuring both repl and hover custom commands via both VS Code settings (JSON) and via Calva config.edn (I don't remember right now if we support a global/user level config, but I think we don't.)
4. Libraries can provide custom commands and hovers. (Which we store in .calva/config.edn, iirc).

A benefit with the current scheme is that is very simple to understand how to use it, and even for more complicated uses, someone that understand the REPL will most often be able to figure it out. It's a bit unclear to me what the usage settings would look like using the alternative suggestions there. Can you provide some examples? How it looks now and how it what it would look like utilizing the new scheme.

As for performance, I think that most often it is not an issue. At least not in terms of risk making it worse. The current way we do it does all the work for all the variables regardless of which are used. Depending on how we go about implementing a new scheme, we do have an opportunity to make it much smarter.

[PEZ]

Another option here is to provide the “variants” of a variable through some syntax. E.g. for -str variants, something like "$(str $file-text)". This could potentially open up for other transformations and even navigation (unclear to me how this would look, but it “feels” like it should be possible 😄).