Symbolic Keywords

In many clojure libraries, the behavior of complex functions may be controlled by a map. For example:

(:require [brewtility.units :as units])
(units/display :volume 1.5 :liter) ;; => "1.5 l"
(units/display :volume 1.5 :liter {:suffix :full}) ;; => "1.5 liter"

This allows us to easily extend the definition of a single function to fulfill multiple complex needs; however, option maps come with considerable drawbacks. When a map is keyed with keywords, it is easy to introduce subtle, hard-to-detect errors. Since most of these functions select default values for keys not present, typos can lead to meaningful differences in behavior. For example:

(:require [brewtility.units :as units])
(units/display :volume 1.5 :liter) ;; => "1.5 l"

;; Note the missing "f" in the key :sufix
(units/display :volume 1.5 :liter {:sufix :full}) ;; => "1.5 l"

Because keywords aren't picked up by the auto-complete features of most editors, they're vulnerable to all classes of transpositional errors. Further, the options themselves are unable to carry metadata and documentation with them, making them little more than magic values.

For this reason, it is helpful for libraries to include symbols which point to the "magic" keywords used in option maps. This has several benefits:

• Misspelled or incorrect option keys are compile-time errors, instead of runtime bugs
• Symbols can carry metadata like documentation, deprecation notices, and point to alternative options
• Context-aware editors can auto-complete options

Here's an example:

(:require [brewtility.units :as units]
          [brewtility.units.options :as options])

(units/display options/volume 1.5 options/liter) ;; => "1.5 l"
(units/display options/volume 1.5 options/liter {options/suffix options/full}) ;; => "1.5 liter"

These keywords are available in the namespaces ending in .options. These files live as close to the code relying on them as possible; for example, the options for all unit conversion operations (e.g. brewtility.units, brewtility.units.time, brewtility.units.color, etc.) are available in brewtility.units.options.

Further, the keywords in these namespaces are strictly preferred for library development. A single source of truth for the name of a common option, such as precision, limits the possibility of incorrectly retrieving the values used by that option.