potemkin

Leiningen

[potemkin "0.4.6"]

deps.edn

potemkin/potemkin {:mvn/version "0.4.6"}

import-vars

Clojure namespaces conflate the layout of your code and your API. For larger libraries, this generally means that you either have large namespaces (e.g. clojure.core) or a large number of namespaces that have to be used in concert to accomplish non-trivial tasks (e.g. Ring).

The former approach places an onus on the creator of the library; the various orthogonal pieces of his library all coexist, which can make it difficult to keep everything straight. The latter approach places an onus on the consumers of the library, forcing them to remember exactly what functionality resides where before they can actually use it.

import-vars allows functions, macros, and values to be defined in one namespace, and exposed in another. This means that the structure of your code and the structure of your API can be decoupled.

(import-vars
  [clojure.walk
    prewalk
    postwalk]
  [clojure.data
    diff])

def-map-type

A Clojure map implements the following interfaces: clojure.lang.IPersistentCollection, clojure.lang.IPersistentMap, clojure.lang.Counted, clojure.lang.Seqable, clojure.lang.ILookup, clojure.lang.Associative, clojure.lang.IObj, java.lang.Object, java.util.Map, java.util.concurrent.Callable, java.lang.Runnable, and clojure.lang.IFn. Between them, there’s a few dozen functions, many with overlapping functionality, all of which need to be correctly implemented.

Despite this, there are only six functions which really matter: get, assoc, dissoc, keys, meta, and with-meta. def-map-type is a variant of deftype which, if those six functions are implemented, will look and act like a Clojure map.

For instance, here’s a map which will automatically realize any delays, allowing for lazy evaluation semantics:

(def-map-type LazyMap [m mta]
  (get [_ k default-value]
    (if (contains? m k)
      (let [v (get m k)]
        (if (instance? clojure.lang.Delay v)
          @v
          v))
      default-value))
  (assoc [_ k v]
    (LazyMap. (assoc m k v) mta))
  (dissoc [_ k]
     (LazyMap. (dissoc m k) mta))
  (keys [_]
    (keys m))
  (meta [_]
    mta)
  (with-meta [_ mta]
    (LazyMap. m mta)))

def-derived-map

Often a map is just a view onto another object, especially when dealing with Java APIs. While we can create a function which converts it into an entirely separate object, for both performance and memory reasons it can be useful to create a map which simply acts as a delegate to the underlying objects:

(def-derived-map StringProperties [^String s]
  :base s
  :lower-case (.toLowerCase s)
  :upper-case (.toUpperCase s))

Each time the key :lower-case is looked up, it will invoke `.toLowerCase. The resulting datatype behaves exactly like a normal Clojure map; new keys can be added and derived keys can be removed.

defprotocol+

A drop in replacement for defprotocol that is more REPL-friendly.

A protocol created with Clojure’s defprotocol always creates new instance at load time. If a protocol is reloaded, a defrecord in another namespace that is referencing the procotol will not automatically be updated to the new protocol instance.

One telltale symptom of this disconnect can be a No implementation of method exception when calling record methods.

Potemkin’s defprotocol+ improves the REPL experience by only creating a new instance of a protocol if the procotol body has changed.

unify-gensyms

Gensyms enforce hygiene within macros, but when quote syntax is nested, they can become a pain. This, for instance, doesn’t work:

`(let [x# 1]
   ~@(map
       (fn [n] `(+ x# ~n))
       (range 3)))

Because x# is going to expand to a different gensym in the two different contexts. One way to work around this is to explicitly create a gensym ourselves:

(let [x-sym (gensym "x")]
  `(let [~x-sym 1]
     ~@(map
         (fn [n] `(+ ~x-sym ~n))
         (range 3))))

However, this is pretty tedious, since we may need to define quite a few of these explicit gensym names. Using unify-gensyms, however, we can rely on the convention that any var with two hashes at the end should be unified:

(unify-gensyms
  `(let [x## 1]
     ~@(map
         (fn [n] `(+ x## ~n))
         (range 3)))