methodical.macros — robhanlon22/methodical 0.10.1-alpha

Methodical versions of vanilla Clojure defmulti and defmethod macros.

define-aux-method clj macro

(define-aux-method multifn-symb qualifier dispatch-val unique-key? & fn-tail)

Define a new auxiliary method. Used primarily as part of the implementation of defmethod; prefer that macro to using this directly.

define-primary-method clj macro

(define-primary-method multifn-symb dispatch-val & fn-tail)

Define a new primary method. Used primarily as part of the implementation of defmethod; prefer that macro to using this directly.

defmethod clj macro

(defmethod multifn-symb dispatch-val & fn-tail)

(defmethod multifn-symb aux-qualifier dispatch-val unique-key? & fn-tail)

Define a new multimethod method implementation. Syntax is the same as for vanilla Clojure defmethod, but you may also define auxiliary methods by passing an optional auxiliary method qualifier before the dispatch value:

;; define a new primary method (defmethod some-multifn Bird [_] ...)

;; define a new auxiliary method (defmethod some-multifn :before Toucan [_] ...)

defmulti clj macro

(defmulti name-symb
          docstring?
          attr-map?
          &
          {:keys [dispatcher combo method-table cache]})

(defmulti name-symb
          docstring?
          attr-map?
          dispatch-fn
          &
          {:keys [hierarchy default-value prefers combo method-table cache]})

Creates a new Methodical multimethod named by a Var. Usage of this macro mimics usage of vanilla Clojure defmulti, and it can be used as a drop-in replacement; it does, however, support a larger set of options. In addition to the usual :default and :hierarchy options, you many specifiy:

• :combo - The method combination to use for this multimethods. Method combinations define how multiple applicable methods are combined; which auxiliary methods, e.g. :before or :after methods, are supported; and whether other advanced facilities, such as next-method, are available. There are over a dozen method combinations that ship as part of Methodical; many are inspired by their equivalents in the Common Lisp Object System. The default method combination is the thread-last method combination.

• :dispatcher - The dispatcher handles dispatch values when invoking a multimethod, and whether one dispatch value (and thus, whether its corresponding method) is considered to be more-specific or otherwise preferred over another dispatch value. The default dispatcher largely mimics the behavior of the Clojure dispatcher, using a single hierarchy augmented by a prefers table to control dispatch, with one big improvement: when dispatching on multiple values, it supports default methods that specialize on some args and use the default for others. (e.g. [String :default])

  Note that the :hierarchy, :default-value and the positional dispatch-fn are provided as conveniences for creating a default dispatcher; if you pass a :dispatcher arg instead, those arguments are not required and will be ignored.

• :cache - controls caching behavior for effective methods. The default simple cache mimics the behavior of vanilla Clojure multimethods.

• :method-table - maintains tables of dispatch value -> primary method and auxiliary method qualifier -> dispatch value -> methods. The default implementation is a pair of simple maps.

The above options comprise the main constituent parts of a Methodical multimethod, and the majority of those parts have several alternative implementations available in methodical.impl. Defining additional implementations is straightforward as well: see methodical.interface for more details.

Other improvements over vanilla Clojure defmulti:

• Evaluating the form a second time (e.g., when reloading a namespace) will not redefine the multimethod, unless you have modified its form -- unlike vanilla Clojure multimethods, which need to be unmapped from the namespace to make such minor tweaks as changing the dispatch function.