A few words from Agical

Keeping the :arglists of Clojure functions DRY

Peter Strömberg

The problem: function-a takes the same arguments as function-b. In fact, function-a calls function-b. Without too much synchronized updating of the function signatures, I want (doc function-a) to show me the same argument lists as (doc function-b).

The solution: Use :arglists in the metadata of the function.

(defn function-b [{:keys [a b c]}]
  (println a b c))

(defn function-a
  {:arglists '([{:keys [a b c]}])}
  [args]
  (function-b args))

That’s the TL;DR. Read on for some rationale, and for some nerdy diving into the worlds of static and dynamic analysis.

I had a case where I had several “pairs” of functions that shared their interface. The functions return SVG and the interface is a configuration map. One of the functions in a pair returns Hiccup, because that’s what I need for the components rendering the SVG. The other returns the rendered string, because that’s what I need for a JavaScript library I use that also renders the SVG.

Here’s a contrived example with the hiccup-producing part of the pair: traffic-light-symbol-hiccup:

(ns nrepl-lsp-arglists.svg-example
  (:require [hiccup2.core :as h]))

(def kind->color {:stop :red
                  :wait :yellow
                  :go :green})

(defn- styled-circle [{:keys [size style]}]
  [:svg {:width size
         :height size
         :viewBox [0 0 512 512]
         :fill :none
         :xmlns "http://www.w3.org/2000/svg"}
   [:circle (merge {:cx 256
                    :cy 256
                    :r 200}
                   style)]])

(defn traffic-light-symbol-hiccup
  "Returns SVG for a traffic light symbol as an SVG circle.
   Args:
   * size: The size (radius) of the circle.
   * kind: The kind of the traffic light, one of :stop, :wait, :go.
   * bells?: Whether the circle should have bells.
   * whistles?: Whether the circle should have whistles."
  [{:keys [size kind bells? whistles?]}]
  (styled-circle {:size size
                  :style (merge {:fill (kind->color kind :black)
                                 :stroke :darkgrey}
                                (when-not bells? {:fill-opacity 0.25})
                                (when whistles? {:stroke-width 5
                                                 :stroke-dasharray [10 10]}))}))

Now, the string producing function is as simple as:

(defn traffic-light-symbol-string [props]
  (h/html (traffic-light-symbol-hiccup props)))

The problem with this is that my Clojure development environment (Calva) will not be very helpful with looking up information about the traffic-light-symbol-string function. No docs and the argument list of props will be displayed.

Calva also has parameter hints that I can pop up while typing out the params, and they will also simply say props.

Well, sure there are better alternatives. One a bit more verbose:

(defn traffic-light-symbol-string-2 [{:keys [size kind bells? whistles?]}]
  (h/html (traffic-light-symbol-hiccup {:size size
                                        :kind kind
                                        :bells? bells?
                                        :whistles? whistles?})))

The bigger problem here is that I need to re-assemble the configuration map. That we can fix using:

(defn traffic-light-symbol-string-3 [{:keys [size kind bells? whistles?] :as props}]
  (h/html (traffic-light-symbol-hiccup props)))

But now the linter (Calva is clj-kondo powered) complains about unused variables keys, kind, bells?, and whistles?. Suppress unused-binding diagnostics to the rescue:

#_{:clj-kondo/ignore [:unused-binding]}
(defn traffic-light-symbol-string-3 [{:keys [size kind bells? whistles?] :as props}]
  (h/html (traffic-light-symbol-hiccup props)))

However, in my real project some of the -string functions have let, and other local binding-boxes, and I do want clj-kondo to help with those… So, I took this to the Clojurians Slack and asked for advice which way to go, and I also asked if there was some way I was missing.

There is a way.

I got help from several Clojure and Clojure tooling experts, so it turned into a super enlightening discussion for me. And there is icing on the cake! Let’s repeat it.

The solution: Use :arglists in the metadata of the function.

(defn traffic-light-symbol-string-arglists
  {:arglists '[[{:keys [size type bells? whistles?]}]]}
  [props]
  (h/html (traffic-light-symbol-hiccup props)))

Calva has two providers of help with the documentation and arguments list of functions: nREPL and clojure-lsp. nREPL is dynamic and will tell me the truth about the argument list from what is evaluated/compiled into the running program. clojure-lsp is static and will tell me the truth about the argument list from what is typed into the file. Both of these providers honor the :arglists metadata.

In most development sessions (at least for me) both clojure-lsp and nREPL are running providing power to Calva. If the function is compiled into the program, nREPL’s answer will be used, otherwise clojure-lsp’s answer. In practice there is only a short period of time between the function text being updated and the code being compiled when I work, so both answers will be the same when I need to look them up.

Caveat. You may be tempted to provide the metadata like so:

(defn ^{:arglists '[[{:keys [size type bells? whistles?]}]]}
  traffic-light-symbol-string-arglists 
  [props]
  (h/html (traffic-light-symbol-hiccup props)))

This should be the same, and for clojure-lsp it doesn’t matter. However, the Clojure compiler will overwrite the :arglists entry of the metadata, or rather remove it, since it is not present in the attr-map. So doing it like that will render the nREPL answer the less useful [props] again (and Calva will not know that this has happened and choose this more boring answer). Now you know. I recommend you check that Slack thread out!

But what about the doc string? I have to admit I haven’t asked the experts about this yet, but here is what I currently do:

(defn traffic-light-symbol-string-arglists-w-doc
  "Returns a string for a traffic light symbol as an SVG circle.
   See `traffic-light-symbol` for more details."
  {:arglists '[[{:keys [size type bells? whistles?]}]]
   :doc (:doc (meta #'traffic-light-symbol-hiccup))}
  [props]
  (h/html (traffic-light-symbol-hiccup props)))

The reason I have both a regular doc string and a :doc entry in the attr-map is that the attr map is populated dynamically, so only nREPL will see it. The shorter docstring is a backup for clojure-lsp to show:

When the function is compiled, nREPL (and thus Calva) will provide the following answer::

I can only conclude my learnings from this inquiry with: The attr-map FTW!

Addendum. Wouldn’t it be nice if the REPL-version worked in clojure-lsp too? And wouldn’t it be nice if it worked for both the argument lists and for the doc string? Like so:

(defn function-b
  "Prints `:a`, `:b`, and `:c` from the argment map.
   * :a The a of the map
   * :b The b of the map
   * :c The c of the map"
  [{:keys [a b c]}]
  (println a b c))

(defn function-a
  {:arglists (:arglists (meta #'function-b))
   :doc (:doc (meta #'function-b))}
  [args]
  (function-b args))

There’s an issue for that! https://github.com/clojure-lsp/clojure-lsp/issues/1811

Peter Strömberg

Peter Strömberg is an autodidact programming nerd living in Stockholm, Sweden. He has been all over the (coder) place for a long time. After some 20 years in the profession he made an attempt to leave it for another passion of his: Product. That attempt ended when Peter was introduced to Clojure and he felt how it gave him back all the joy of programming, and then some.

You can contract Peter for remote Clojure/ClojureScript gigs up to 80% of an FTE. The other 20% Agical pays him to spend doing open source work. Most often this is about maintaining Calva, a popular Visual Studio Code Clojure IDE extension which Peter created 2018.