Lambda Island

Clojure’s variable argument functions combined with map destructuring results in a concise syntax for keyword arguments. We’ll pick this feature apart to see exactly what’s inside. You’ll learn about “mapply”, and learn why keyword arguments aren’t always the best solution.

Transcript

I want to zoom in for a moment on the use of keyword arguments in Clojure. Although the syntax takes some getting used to they’re a great feature to acquaint yourself with. And the best part? They don’t really exist!

To set the stage, we’ll start with a simple Hiccup component, for rendering information about a specific tea on our website.

(defn tea-info-sheet [& {:keys [name type description]}]
  [:div.tea
   [:h2.name name (if type [:em "(" [:a {:href (str "/type/" type)} type] ")"])]
   [:p.description description]])

And here’s how you would use it. The arguments are specified as key-value pairs, the way you would when creating a hash-map.

(tea-info-sheet :name "Alishan"
                :type "Wulong"
                :description "Hand picked high-mountain tea grown close to the Yushan national park.")

;;=>
[:div.tea
 [:h2.name "Alishan" [:em "(" [:a {:href "/type/Wulong"} "Wulong"] ")"]]
 [:p.description
  "Hand picked high-mountain tea grown close to the Yushan national park."]]

There’s quite some syntax in that argument list though. Let’s try to pick that apart, until we get to the bottom of it, then build it up again step by step.

The first thing you notice is that initial ampersand. Normally in an argument list this is followed by a single “rest” argument, which will receive any remaining arguments gathered up in a collection.

This function demostrates that, the first argument is assigned to the first argument name, and arguments 2 to 4 are assigned to rest-of-the-args as a list.

(defn demo [first-arg & rest-of-the-args]
  {:first-arg first-arg
   :rest-of-args rest-of-the-args})

(demo 1 2 3 4)
;;=>
{:first-arg 1, :rest-of-args (2 3 4)}

Or take this separate function, a variation on clojure.string/join. The first argument is a separator, which we put in between each pair of remaining arguments with interpose, before turning the whole lot into a single string.

(defn separate [separator & rest]
  (apply str (interpose separator rest)))

(separate "," "foo" "bar" "baz")

If we take the ampersand out of our tea-info-sheet function, we now get a function which takes only a single argument, which should be a map which will be destructured.

Now when we call it we need to round up these key-value pairs in a map.

(defn tea-info-sheet [{:keys [name type description]}]
  [:div.tea
   [:h2.name name (if type [:em "(" [:a {:href (str "/type/" type)} type] ")"])]
   [:p.description description]])

(tea-info-sheet {:name "Alishan"
                 :type "Wulong"
                 :description "Hand picked high-mountain tea grown close to the Yushan national park."})

;;=>
[:div.tea
 [:h2.name "Alishan" [:em "(" [:a {:href "/type/Wulong"} "Wulong"] ")"]]
 [:p.description
  "Hand picked high-mountain tea grown close to the Yushan national park."]]

Let’s make it more clear that this function really only takes a single argument by doing the destructuring separately.

(defn tea-info-sheet [tea-props]
  (let [{:keys [name type description]} tea-props]
    [:div.tea
     [:h2.name name (if type [:em "(" [:a {:href (str "/type/" type)} type] ")"])]
     [:p.description description]]))

This destructuring still uses some pretty magical syntax, using this keys keyword plus a vector of symbols. This is really just a shorthand for destructuring each key separately.

This syntax used to trip me up, because I assumed it would follow the structure of the map, with keywords on the left, and the to-be-assigned variable name on the right, but it makes sense if you think of it as a binding form. In a let-block the to-be-assigned variable name also comes on the left, and the same is true when destructuring maps.

(defn tea-info-sheet [tea-props]
  (let [{name :name
         type :type
         description :description} tea-props]
    [:div.tea
     [:h2.name name (if type [:em "(" [:a {:href (str "/type/" type)} type] ")"])]
     [:p.description description]]))

And this in turn is nothing but syntactic sugar for pulling out each value separately.

(defn tea-info-sheet [tea-props]
  (let [name (:name tea-props)
        type (:type tea-props)
        description (:description tea-props)]
    [:div.tea
     [:h2.name name (if type [:em "(" [:a {:href (str "/type/" type)} type] ")"])]
     [:p.description description]]))

Now let’s go one step back, so we have the map destructuring again, and then make our function take a variable number of arguments. Now it works again like it did before, but the fact that it does is a bit surprising, after all we know that tea-props will be a list, but yet somehow we can treat it as if it’s a map.

(defn tea-info-sheet [& tea-props]
  (let [{name :name
         type :type
         description :description} tea-props]
    [:div.tea
     [:h2.name name (if type [:em "(" [:a {:href (str "/type/" type)} type] ")"])]
     [:p.description description]]))

Turns out if you try to destructure a sequence into a map, Clojure will convert it for you behind the scene. This can be any sequence like lists and vectors, and even lazy sequences.

(defn demo [coll]
  (let [{name :name
         type :type} coll]
    {"its name" name
     "its type" type}))

(demo '(:name "Alishan" :type "Wulong"))
;;=>
{"it's name" "Alishan", "it's type" "Wulong"}

So now a lot should become clear. Let’s turn this function back into the original version. Eliminating the let is straightforward, and we can use the more concise map destructuring syntax. This syntax has an extra advantage: we can specify fallback values, using :or. :or takes a map, but you can think of it as a kind of let, as it uses similar binding forms, with a symbol followed by a value.

(defn tea-info-sheet [& {:keys [name type description]
                         :or {name "Generic tea"
                              description "No description given"}}]
  [:div.tea
   [:h2.name name (if type [:em "(" [:a {:href (str "/type/" type)} type] ")"])]
   [:p.description description]])

(tea-info-sheet :name "Alishan")
;;=>
[:div.tea [:h2.name "Alishan" nil] [:p.description "No description given"]]

Now suppose we want to pull this header out into a separate “product-title” component. It also takes keyword arguments just like the main component, so I pass on the ones it needs.

(defn product-title [& {:keys [name type]}]
  [:h2.name name (if type [:em "(" [:a {:href (str "/type/" type)} type] ")"])])

(defn tea-info-sheet [& {:keys [name type description]
                         :or {name "Generic tea"
                              description "No description given"}}]
  [:div.tea
   (product-title :name name
                  :type type)
   [:p.description description]])

But we’ve introduced some duplication here, it’s not much in this case, but it would be much nicer if we could just pass the map of tea properties on to the other component.

Getting hold of the properties is straightforward, besides :keys and :or we can add an :as keyword to capture to original input.

Passing it on to the other component isn’t straightforward at all though. Even though it also destructures its arguments to a map, we can’t just pass it a map. Instead we first need to turn the map into a flat sequence again, and then use apply, since the items in the sequence should be passed as individual arguments.

Ugh. What a mess.

(defn product-title [& {:keys [name type]}]
  [:h2.name name (if type [:em "(" [:a {:href (str "/type/" type)} type] ")"])])

(defn tea-info-sheet [& {:keys [name type description]
                         :or {name "Generic tea"
                              description "No description given"}
                         :as tea-props}]
  [:div.tea
   (apply product-title (apply concat tea-props))
   [:p.description description]])

(tea-info-sheet :description "Fine tea" :type "tea")
;; =>
[:div.tea [:h2.name nil [:em "(" [:a {:href "/type/tea"} "tea"] ")"]] [:p.description "Fine tea"]]

We can clean this up by using mapply, which is like regular apply, but works with maps. mapply is not included with Clojure, but it’s part of all the main Clojure utility libraries like Medley, Encore, or Prismatic’s Plumbing. There’s even a project on Clojars that only implements mapply. In total Crossclj.info currently lists 29 separate libraries all implementing their own `mapply.

Here’s what a potential implementation looks like.

(defn mapply
  [f & args]
  (apply f (apply concat (butlast args) (last args))))

Using that our function becomes a little bit less silly, but there’s another problem. Let’s actually use our current implementation, but rely on the fallback values.

The name disappeared! Turns out that even though we supplied fallback values, this :as tea-props still contains the original input without the defaults.

We could repeat them in the other component, but that’s also not great.

(defn product-title [& {:keys [name type]}]
  [:h2.name name (if type [:em "(" [:a {:href (str "/type/" type)} type] ")"])])

(defn tea-info-sheet [& {:keys [name type description]
                         :or {name "Generic tea"
                              description "No description given"}
                         :as tea-props}]
  [:div.tea
   (mapply product-title tea-props)
   [:p.description description]])

(tea-info-sheet)

I hope I’ve demonstrated that using keyword arguments in this way can have real drawbacks. And what did we gain? We’ve saved the consumer of our API one pair of curlies.

Maybe it’s time to admit that tea-props are a first class citizen in our code, something that we can pass around, and that many functions can consume.

If we change the two component functions to accept a single map, then we no longer need mapply, and it’s more clear that they really accept the same type of thing.

(defn product-title [{:keys [name type]
                      :or {name "Generic Tea"
                           description "No description given"}}]
  [:h2.name name (if type
                   [:em "(" [:a {:href (str "/type/" type)} type] ")"])])

(defn tea-info-sheet [{:keys [name type description]
                       :or {name "Generic Tea"
                            description "No description given"}
                       :as tea-props}]
  [:div.tea
   (product-title tea-props)
   [:p.description description]])



(tea-info-sheet {:name "Alishan"
                 :type "Oolong"
                 :description "Hand picked high-mountain tea grown close to the Yushan national park"})

Finally for convenience, but also for safety and validation, we can provide a tea-props “constructor” function. We can make sure this always returns a map with all the necessary keys. It’s also a good place to provide specs to check for invalid usage.

(defn tea-props [& {:as props}]
  (merge {:name "Generic Tea"
          :description "No description given"} props))

Clojure Keyword Arguments