Consider combining macros/functions in one namespace

[Engelberg]

The README demonstrates using specter by "using" both the macros and specter namespaces. But some of the names are common enough that I would prefer to "require" them with an alias. The problem: because the README only demonstrates usage with no namespace qualifications, it is not obvious how to remember which parts of the API are functions and which are macros, and therefore it can be hard to recall which namespace to find which thing in. To some extent, macros vs functions are an implementation detail, and I as a user don't necessarily know which way a given thing is implemented.

Consider combining macros/functions into a unified API of all the core public API functions (it's fine if things like transients remain separate, since that is a conceptual classification that is easy to remember, not an implementation-based classification).

Potemkin is a valuable tool for pulling things from separate implementation namespaces into one API namespace for public consumption.

[nathanmarz]

I agree, and this is how it used to be. The split was done for ClojureScript compatibility.

[Engelberg]

I have found potemkin's import-vars to be a great tool for dealing with this. import-vars copies over the docstring and other pertinent info about the var from the implementation namespace to the API namespace -- works seamlessly on both functions and macros.

So, potentially you could keep the separate implementation namespaces for Clojurescript users, but Clojure users could access the vars through a com.rpl.specter.core namespace.

Main downside of using potemkin is that it contains a lot of other stuff irrelevant to this particular use and the other stuff causes it to be somewhat fragile -- tends to break when new versions of Clojure come out until potemkin is updated. I wish Clojure had a built-in solution for something like import-vars.

[nathanmarz]

Apparently ClojureScript allows a macros namespace to be the same name as a ClojureScript namespace (not sure if this was added recently or not). That means Specter's namespaces can be merged.

[Engelberg]

I also discovered this just a couple weeks ago. I think there are some subtleties to be aware of, because the namespace file is processed once looking for only macros, and then again looking for all the non-macros. So if I understand correctly, this means the macro can't depend on a function in the same namespace. But since you already have the code factored into two separate namespaces, I would imagine it wouldn't be too hard to meet the constraints imposed by this two-pass system.

[nathanmarz]

Tried doing this today but ran into a major problem. When I put the macros namespace in specter.clj and keep the functions in specter.cljc, only the specter.clj file is loaded when doing a use at a Clojure repl:

user=> (use 'com.rpl.specter)
nil
user=> ALL

CompilerException java.lang.RuntimeException: Unable to resolve symbol: ALL in this context, compiling:(/private/var/folders/w6/4l9gm76n00bckj3210cv1rdw0000gn/T/form-init27325069843801310.clj:1:4652) 
user=> select

CompilerException java.lang.RuntimeException: Can't take value of a macro: #'com.rpl.specter/select, compiling:(/private/var/folders/w6/4l9gm76n00bckj3210cv1rdw0000gn/T/form-init27325069843801310.clj:1:4652)

Doing (load-file "src/clj/com/rpl/specter.cljc") gets it working, but that's not a satisfactory solution.

[aengelberg]

Yeah, I don't think having both a clj and a cljc file for a given namespace is a supported use case. Couldn't you put the macros into specter.cljc but using the #?(:clj) reader conditional?

[nathanmarz]

Great idea, that worked. This is now implemented for 0.13.0.