desiderata

Things wanted or needed but missing from clojure.core.

This is not just a collection of utility functions, but more significant features (and maybe some utility functions).

defrecord

You can use systems.thoughtfull.desiderata/defrecord as a drop-in replacement for clojure.core/defrecord and what you get are four new features. The first (minor) feature is the factory function (i.e. map->...) takes keyword arguments.

Docstring

systems.thoughtfull.desiderata/defrecord takes a docstring that it appends to the end of both the factory and positional factory functions.

user> (require '[systems.thoughtfull.desiderata :as desiderata])
nil

user> (desiderata/defrecord Widget
"A widget for frobbing gizmos.

width and height are in metric."
[width height])
user.Widget

user> (doc map->Widget)
-------------------------
user/map->Widget
([& {:keys [width height]}])
  Factory function for class user.Widget, taking a map of keywords to field values.

  A widget for frobbing gizmos.
  
  width and height are in metric.
nil

user> (doc ->Widget)
-------------------------
user/->Widget
([width height])
  Positional factory function for class user.Widget.

  A widget for frobbing gizmos.
  
  width and height are in metric.
nil

Defaults

You can specify a map of default values for fields (and non-fields) with the systems.thoughtfull.desiderata/defaults option. Values given to the factory or positional factory functions will override defaults.

user> (desiderata/defrecord Gizmo
[name]
::desiderata/defaults
{:name "Gizmo"
 :color :blue})
user.Gizmo

user> (->Gizmo "the Great")
{:name "the Great", :color :blue}

user> (map->Gizmo :texture :bumpy)
{:name "Gizmo", :color :blue, :texture :bumpy}

Initializer

A method specified with the same name as the defrecord is an initializer method called from both the factory and positional factory functions. As a sanity check, it must return an instance of the defrecord, otherwise an IllegalStateException is thrown.

user> (desiderata/defrecord Company
[debt equity]
(Company
  [this]
  (assoc this :gearing-ratio (/ debt equity))))
user.Company

user> (->Company 100 1000)
{:debt 100, :equity 1000, :gearing-ratio 1/10}