Document internals

[vvvvalvalval]

The reader should understand:

• what information is created and accessed by what processes, and where it's stored.
• how spy / letsc / defsc work

[divs1210]

Hi @vvvvalvalval , could you add some details?
Clojure 'reader' or the user?
Any way I could help out?

[vvvvalvalval]

Clojure 'reader' or the user?

The user of the library.

I am actually not sure this documentation section is still needed, because I filed this issue before creating the 'Pitfalls' section in the README: https://github.com/vvvvalvalval/scope-capture/wiki/Pitfalls-with-(browser-connected)-ClojureScript-REPLs.

@divs1210 One way you could help is to tell me how documentation could be improved. What parts of scope-capture, its value prop, its usage or its internal, seem unclear or dubious to you?

[viebel]

@vvvvalvalval As a user of this awesome lib, I'd like to understand the internals of the spy macro: What parts of Clojure do you use in order to be able to get the list of all the bindings, including destructured bindings etc...?

[vvvvalvalval]

Hey @viebel, I should document this indeed, thanks.

The list of in-scope locals is actually provided by the Clojure compiler: macros can read it in a value bound to a 'magical' &env local. In scope-capture, this value gets passed to helper functions under the name amp-env.

Unfortunately, the schema of &env varies depending on whether you're compiling with Clojure JVM or ClojureScript, which incurs a penalty in complexity to make scope-capture cross-platform. See here:

scope-capture/src/sc/impl.cljc

Line 131 in 897978e

(extract-local-names (:sc/local-names-extractor opts)

.