methodical.core — robhanlon22/methodical 0.10.1-alpha

Combined interface to everything in Methodical you'd normally want to use.

+-method-combination clj

(+-method-combination)

Executes all applicable primary methods, returnings the sum of the values returned by each method. Same constraints as othe CLOS operator-style method combinations.

add-aux-method clj

(add-aux-method method-table qualifier dispatch-value f)

Add an auxiliary method implementation for qualifer (e.g. :before) and dispatch-value. Unlike primary methods, auxiliary methods are not limited to one method per dispatch value; thus this method does not remove existing methods for this dispatch value. existing

add-aux-method! clj

(add-aux-method! multifn-var qualifier dispatch-val f)

Destructive version of add-aux-method. Operates on a var defining a Methodical multifn.

add-aux-method-with-unique-key clj

(add-aux-method-with-unique-key multifn qualifier dispatch-val f unique-key)

Adds an auxiliary method with a unique-key stored in its metadata. This unique key can later be used to remove the auxiliary method with remove-aux-method-with-unique-key. If a method with this key already exists for this qualifier and dispatch value, replaces the original.

add-aux-method-with-unique-key! clj

(add-aux-method-with-unique-key! multifn-var
                                 qualifier
                                 dispatch-val
                                 f
                                 unique-key)

Destructive version of add-aux-method-with-unique-key. Operates on a var defining a Methodical multifn.

add-primary-method clj

(add-primary-method method-table dispatch-value f)

Set the primary method implementation for dispatch-value, replacing it if it already exists.

add-primary-method! clj

(add-primary-method! multifn-var dispatch-val f)

Destructive version of add-primary-method. Operates on a var defining a Methodical multifn.

allowed-qualifiers clj

(allowed-qualifiers method-combination)

The set containg all qualifiers supported by this method combination. nil in the set means the method combination supports primary methods (because primary methods have no qualifier); all other values refer to auxiliary methods with that qualifer, e.g. :before, :after, or :around.

(allowed-qualifiers (clojure-method-combination)) ;-> #{nil} (allowed-qualifiers (clos-method-combination)) ;-> #{nil :before :after :around} (allowed-qualifiers (doseq-method-combination)) ;-> #{:doseq}

and-method-combination clj

(and-method-combination)

Invoke all applicable primary methods, from most-specific to least-specific; reducing the results as if by and. Like and, this method invocation short-circuits if any implementation returns a falsey value. Otherwise, this method returns the value returned by the last method invoked.

applicable-primary-method clj

(applicable-primary-method multifn dispatch-value)

Return the primary method that would be use for dispatch-value, including ones from ancestor dispatch values or the default dipsatch value.

Like primary-method, the method returned will not have any implicit args (such as next-method) bound.

aux-methods clj

(aux-methods multifn)

(aux-methods multifn dispatch-value)

(aux-methods multifn qualifier dispatch-value)

Get all auxiliary methods explicitly specified for dispatch-value. This function does not include methods that would otherwise still be applicable (e.g., methods for ancestor dispatch values) -- the methods explicitly defined for this exact match.

• With 1 arg: methods come back as a map of qualifier -> dispatch value -> [method].
• With 2 args: methods come back as a map of qualifier -> [method].
• With 3 args: methods come back as sequence of methods.

cached-multifn-impl clj

(cached-multifn-impl impl)

(cached-multifn-impl impl cache)

Wrap a MultiFnImpl in a CachedMultiFnImpl, which adds caching to calculated effective methods. The cache itself is swappable with other caches that implement different strategies.

clojure-method-combination clj

(clojure-method-combination)

Simple method combination strategy that mimics the way vanilla Clojure multimethods combine methods; that is, to say, not at all. Like vanilla Clojure multimethods, this method combination only supports primary methods.

clojure-method-table clj

(clojure-method-table)

(clojure-method-table m)

Create a new Clojure-style method table. Clojure-style method tables only support primary methods.

clojure-multifn-impl clj

(clojure-multifn-impl dispatch-fn
                      &
                      {:keys [hierarchy default-value prefers method-table]})

Create a mulitfn impl that largely behaves the same way as a vanilla Clojure multimethod.

clos-method-combination clj

(clos-method-combination)

Method combination stategy that mimics the standard method combination in the Common Lisp Object System (CLOS). Supports :before, :after, and :around auxiliary methods. The values returned by :before and :after methods are ignored. Primary methods and around methods get an implicit next-method arg (see Methodical dox for more on what this means).

clos-multifn-impl clj

(clos-multifn-impl dispatch-fn
                   &
                   {:keys [hierarchy default-value prefers primary-method-table
                           aux-method-table]})

Convenience for creating a new multifn instances that for the most part mimics the behavior of CLOS generic functions using the standard method combination. Supports :before, :after, and :around auxiliary methods, but values of :before and :after methods are ignored, rather than threaded. Primary and :around methods each get an implicit next-method arg.

combine-methods clj

(combine-methods method-combination primary-methods aux-methods)

Combine a sequence of matching primary-methods with aux-methods (a map of qualifier -> sequence of methods) into a single effective method.

concat-method-combination clj

(concat-method-combination)

Like the seq-method-combination, but concatenates all the results together.

seq-method-combination : map :: concat-method-combination : mapcat

default-aux-methods clj

(default-aux-methods multifn)

Get a map of aux qualifer -> methods for the default dispatch value, if any exist.

default-dispatch-value clj

(default-dispatch-value dispatcher)

Default dispatch value to use if no other dispatch value matches.

default-effective-method clj

(default-effective-method multifn)

Return the effective (combined) method for the default dispatch value, if one can be computed.

default-multifn clj

(default-multifn dispatch-fn & {:keys [hierarchy default-value prefers]})

Create a new Methodical multifn using the default impl.

default-multifn-impl clj

(default-multifn-impl dispatch-fn & {:keys [hierarchy default-value prefers]})

Create a basic multifn impl using default choices for method combination, dispatcher, and method table.

default-primary-method clj

(default-primary-method multifn)

Get the default primary method associated with this mutlifn, if one exists.

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.

dispatch-fn clj

(dispatch-fn multifn)

Return a function that can be used to calculate dispatch values of given arg(s).

dispatch-value clj

(dispatch-value dispatcher)

(dispatch-value dispatcher a)

(dispatch-value dispatcher a b)

(dispatch-value dispatcher a b c)

(dispatch-value dispatcher a b c d)

(dispatch-value dispatcher a b c d more)

Return an appropriate dispatch value for args passed to a multimethod. (This method is equivalent in purpose to the dispatch function of vanilla Clojure multimethods.)

dispatcher clj

(dispatcher multifn)

Get the dispatcher associated with this multifn.

do-method-combination clj

(do-method-combination)

Based on the CLOS progn method combination. Sequentially executes all applicable primary methods, presumably for side-effects, in order from most-specific to least-specific; returns the value returned by the least-specific method. do method combinations support :around auxiliary methods, but not :before or :after methods.

effective-method clj

(effective-method multifn dispatch-value)

Return the effective method for dispatch-value. The effective method is a combined primary method and applicable auxiliary methods that can be called like a normal function. effective-method is similar in purpose to get-method in vanilla Clojure multimethods; a different name is used here because I felt get-method would be ambiguous with regards to whether it returns only a primary method or a combined effective method.

effective-primary-method clj

(effective-primary-method multifn dispatch-value)

Build and effective method equivalent that would be used for this dispatch-value if it had no applicable auxiliary methods. Implicit args (such as next-method) will be bound appropriately.

everything-dispatcher clj

(everything-dispatcher &
                       {:keys [hierarchy prefers]
                        :or {hierarchy (var clojure.core/global-hierarchy)
                             prefers {}}})

A Dispatcher that always considers all primary and auxiliary methods to be matches; does not calculate dispatch values for arguments when invoking. Dispatch values are still used to sort methods from most- to least- specific, using hierarchy and map of prefers.

matching-aux-methods clj

(matching-aux-methods dispatcher method-table dispatch-value)

Return a map of aux method qualifier -> sequence of applicable methods for dispatch-value, sorted from most-specific to least-specific.

matching-primary-methods clj

(matching-primary-methods dispatcher method-table dispatch-value)

Return a sequence of applicable primary methods for dispatch-value, sorted from most-specific to least-specific. The standard dispatcher also checks to make sure methods in the sequence are not ambiguously specific, replacing ambiguous methods with ones that will throw an Exception when invoked.

max-method-combination clj

(max-method-combination)

Executes all applicable primary methods, and returns the maximum value returned by any one implemenation. Same constraints as othe CLOS operator-style method combinations.

method-combination clj

(method-combination multifn)

Get the method combination associated with this multifn.

method-table clj

(method-table multifn)

Get the method table associated with this multifn.

min-method-combination clj

(min-method-combination)

Based on the CLOS method combination of the same name. Executes all applicable primary methods, returning the minimum value returned by any implementation. Like do method combinations, min supports :around auxiliary methods, but not :before or :after.

multi-default-dispatcher clj

(multi-default-dispatcher dispatch-fn
                          &
                          {:keys [hierarchy default-value prefers]
                           :or {hierarchy (var clojure.core/global-hierarchy)
                                default-value :default
                                prefers {}}})

Like the standard dispatcher, 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])

multifn clj

(multifn impl)

(multifn impl mta)

(multifn impl mta cache)

Create a new cached Methodical multifn using impl as the multifn implementation.

or-method-combination clj

(or-method-combination)

Like the and combination, but combines result as if by or; short-circuits after the first matching primary method returns a truthy value.

prefer-method clj

(prefer-method dispatcher dispatch-val-x dispatch-val-y)

Prefer dispatch-val-x over dispatch-val-y for dispatch and method combinations.

prefer-method! clj

(prefer-method! multifn-var dispatch-val-x dispatch-val-y)

Destructive version of prefer-method. Operates on a var defining a Methodical multifn.

Note that vanilla Clojure prefer-method is actually itself destructive, so this function is actually the Methodical equivalent of that function. prefer-method! is used by Methodical to differentiate the operation from our nondestructive prefer-method, which returns a copy of the multifn with an altered dispatch table.

prefers clj

(prefers dispatcher)

Return a map of preferred dispatch value -> set of other dispatch values.

primary-method clj

(primary-method multifn dispatch-value)

Get the primary method explicitly specified for dispatch-value. This function does not return methods that would otherwise still be applicable (e.g., methods for ancestor dispatch values) -- just the methods explicitly defined for this exact match. (If you want methods that will be used, including those of ancestors dispatch values, you can use applicable-primary-method or effective-primary-method instead.)

Note that the primary method will not have any implicit args (e.g. next-method) bound the way it normally would when combined into an effective method; you will need to supply this yourself (or pass nil for no next-method).

primary-methods clj

(primary-methods method-table)

Get a dispatch-value -> fn map of all primary methods assoicated with this method table.

remove-all-aux-methods clj

(remove-all-aux-methods multifn)

(remove-all-aux-methods multifn qualifier)

(remove-all-aux-methods multifn qualifier dispatch-value)

With one arg, remove all auxiliary methods for a multifn. With two args, remove all auxiliary methods for the given qualifier (e.g. :before). With three args, remove all auxiliary methods for a given qualifier and dispatch-value.

remove-all-aux-methods! clj

(remove-all-aux-methods! multifn-var)

(remove-all-aux-methods! multifn-var qualifier)

(remove-all-aux-methods! multifn-var qualifier dispatch-val)

Destructive version of remove-all-aux-methods. Operates on a var defining a Methodical multifn.

remove-all-aux-methods-for-dispatch-val clj

(remove-all-aux-methods-for-dispatch-val multifn dispatch-value)

Remove all auxiliary methods for dispatch-value for all qualifiers.

remove-all-aux-methods-for-dispatch-val! clj

(remove-all-aux-methods-for-dispatch-val! multifn-var dispatch-value)

Destructive version of remove-all-aux-methods-for-dispatch-val. Operates on a var defining a Methodical multifn.

remove-all-methods clj

(remove-all-methods multifn)

Remove all primary and auxiliary methods, including default implementations.

remove-all-methods! clj

(remove-all-methods! multifn-var)

Destructive version of remove-all-methods. Operates on a var defining a Methodical multifn.

remove-all-primary-methods clj

(remove-all-primary-methods multifn)

Remove all primary methods, for all dispatch values (including the default value), for this multifn or method table.

remove-all-primary-methods! clj

(remove-all-primary-methods! multifn-var)

Destructive version of remove-all-primary-methods. Operates on a var defining a Methodical multifn.

remove-aux-method clj

(remove-aux-method method-table qualifier dispatch-val method)

Remove an auxiliary method from a method table. Because multiple auxiliary methods are allowed for the same dispatch value, existing implementations of MethodTable are currently only able to remove exact matches -- for functions, this usually means identical objects.

In the future, I hope to fix this by storing unique indentifiers in the metadata of methods in the map.

remove-aux-method! clj

(remove-aux-method! multifn-var qualifier dispatch-val f)

Destructive version of remove-aux-method. Operates on a var defining a Methodical multifn.

remove-aux-method-with-unique-key clj

(remove-aux-method-with-unique-key multifn qualifier dispatch-val unique-key)

Remove an auxiliary method that was added by add-aux-method-with-unique-key, if one exists. Returns multifn.

remove-aux-method-with-unique-key! clj

(remove-aux-method-with-unique-key! multifn-var
                                    qualifier
                                    dispatch-val
                                    unique-key)

Destructive version of remove-aux-method-with-unique-key. Operates on a var defining a Methodical multifn.

remove-primary-method clj

(remove-primary-method method-table dispatch-value)

Remove the primary method for dispatch-value.

remove-primary-method! clj

(remove-primary-method! multifn-var dispatch-val)

Destructive version of remove-primary-method. Operates on a var defining a Methodical multifn.

seq-method-combination clj

(seq-method-combination)

Executes all applicable primary methods, from most-specific to least-specific; returns a sequence of results from the method invocations. Inspired by CLOS nconc and append method combinations, but unlike those, this combination returns a completely lazy sequence. Like other CLOS-operator-inspired method combinations, this combination currently supports :around methods, but not :before or :after methods.

simple-cache clj

(simple-cache)

(simple-cache m)

Create a basic dumb cache. The simple cache stores

standard-dispatcher clj

(standard-dispatcher dispatch-fn
                     &
                     {:keys [hierarchy default-value prefers]
                      :or {hierarchy (var clojure.core/global-hierarchy)
                           default-value :default
                           prefers {}}})

Create a stanadrd Methodical multifn dispatcher. The standard dispatcher replicates the way vanilla Clojure multimethods handle multimethod dispatch, with support for a custom hierarchy, default-value and map of prefers.

standard-method-table clj

(standard-method-table)

(standard-method-table primary aux)

Create a new standard method table that supports both primary and auxiliary methods.

standard-multifn-impl clj

(standard-multifn-impl combo dispatcher method-table)

Create a basic multifn impl using method combination combo, dispatcher dispatcher, and method-table.

thread-first-method-combination clj

(thread-first-method-combination)

Similar the the standard CLOS-style method combination, but threads the result of each :before and :after auxiliary methods, as well as the primary method, as the first arg of subsequent method invocations.

thread-last-method-combination clj

(thread-last-method-combination)

Similar the the standard CLOS-style method combination, but threads the result of each :before and :after auxiliary methods, as well as the primary method, as the last arg of subsequent method invocations.

transform-fn-tail clj

(transform-fn-tail method-combination qualifier fn-tail)

Make appropriate transformations to the fn-tail of a defmethod macro expansion for a primary method (qualifier will be nil) or an auxiliary method. You can use this method to add implicit args like next-method to the body of a defmethod macro. (Because this method is invoked during macroexpansion, it should return a Clojure form.)

uncached-multifn clj

(uncached-multifn impl)

(uncached-multifn impl mta)

Create a new Methodical multifn using impl as the multifn implementation; impl itself should implement MultiFnImpl. DOES NOT CACHE EFFECTIVE METHODS -- use multifn instead, unless you like slow dispatch times.

watching-cache clj

(watching-cache cache references)

Wrap cache in a WatchingCache, which clears the cache whenever one of the watched references (such as vars or atoms) changes. Intended primarily for use with 'permanent' MultiFns, such as those created with defmulti; this is rarely needed or wanted for transient multifns.

with-dispatcher clj

(with-dispatcher multifn new-dispatcher)

Return a copy of this multifn using new-dispatcher as its dispatcher.

with-method-table clj

(with-method-table multifn new-method-table)

Return a copy of this multifn using new-method-table as its method table.