search

vvvvalvalval / scope-capture

Project your Clojure(Script) REPL into the same context as your code when it ran
MIT License
573 stars 14 forks source link

Document internals #9

Open vvvvalvalval opened 6 years ago

vvvvalvalval commented 6 years ago

The reader should understand:

divs1210 commented 6 years ago

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

vvvvalvalval commented 6 years ago

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 commented 5 years ago

@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 commented 5 years ago

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: https://github.com/vvvvalvalval/scope-capture/blob/897978eae42d1e5dfe88f582cc81473014b42b85/src/sc/impl.cljc#L131.