API for monads - clojure-contrib v1.3 (in development)

by Konrad Hinsen

Full namespace name: clojure.contrib.monads

Overview

This library contains the most commonly used monads as well
as macros for defining and using monads and useful monadic
functions.
See also: Monad tutorial part 1 Monad tutorial part 2 Monad tutorial part 3 Monad tutorial part 4 Monads in Clojure part 1 Monads in Clojure part 2

Public Variables and Functions



call-cc

function
Usage: (call-cc f)
A computation in the cont monad that calls function f with a single
argument representing the current continuation. The function f should
return a continuation (which becomes the return value of call-cc),
or call the passed-in current continuation to terminate.
Source


cont-m

var

  
Monad describing computations in continuation-passing style. The monadic
values are functions that are called with a single argument representing
the continuation of the computation, to which they pass their result.
Source


defmonad

macro
Usage: (defmonad name doc-string operations)
       (defmonad name operations)
Define a named monad by defining the monad operations. The definitions
are written like bindings to the monad operations m-bind and
m-result (required) and m-zero and m-plus (optional).
Source


defmonadfn

macro
Usage: (defmonadfn name docstring? attr-map? args expr)
       (defmonadfn name docstring? attr-map? (args expr) ...)
Like defn, but for functions that use monad operations and are used inside
a with-monad block.
Source


domonad

macro
Usage: (domonad steps expr)
       (domonad name steps expr)
Monad comprehension. Takes the name of a monad, a vector of steps
given as binding-form/monadic-expression pairs, and a result value
specified by expr. The monadic-expression terms can use the binding
variables of the previous steps.
If the monad contains a definition of m-zero, the step list can also
contain conditions of the form :when p, where the predicate p can
contain the binding variables from all previous steps.
A clause of the form :let [binding-form expr ...], where the bindings
are given as a vector as for the use in let, establishes additional
bindings that can be used in the following steps.
Source


fetch-state

function
Usage: (fetch-state)
Return a state-monad function that returns the current state and does not
modify it.
Source


fetch-val

function
Usage: (fetch-val key)
Return a state-monad function that assumes the state to be a map and
returns the value corresponding to the given key. The state is not modified.
Source


identity-m

var

  
Monad describing plain computations. This monad does in fact nothing
at all. It is useful for testing, for combination with monad
transformers, and for code that is parameterized with a monad.
Source


m-chain

var

  
Chains together monadic computation steps that are each functions
of one parameter. Each step is called with the result of the previous
step as its argument. (m-chain (step1 step2)) is equivalent to
(fn [x] (domonad [r1 (step1 x) r2 (step2 r1)] r2)).
Source


m-fmap

var

  
Bind the monadic value m to the function returning (f x) for argument x
Source


m-join

var

  
Converts a monadic value containing a monadic value into a 'simple'
monadic value.
Source


m-lift

macro
Usage: (m-lift n f)
Converts a function f of n arguments into a function of n
monadic arguments returning a monadic value.
Source


m-map

var

  
'Executes' the sequence of monadic values resulting from mapping
f onto the values xs. f must return a monadic value.
Source


m-reduce

var

  
Return the reduction of (m-lift 2 f) over the list of monadic values mvs
with initial value (m-result val).
Source


m-seq

var

  
'Executes' the monadic values in ms and returns a sequence of the
basic values contained in them.
Source


m-until

var

  
While (p x) is false, replace x by the value returned by the
monadic computation (f x). Return (m-result x) for the first
x for which (p x) is true.
Source


m-when

macro
Usage: (m-when test m-expr)
If test is logical true, return monadic value m-expr, else return
(m-result nil).
Source


m-when-not

macro
Usage: (m-when-not test m-expr)
If test if logical false, return monadic value m-expr, else return
(m-result nil).
Source


maybe-m

var

  
Monad describing computations with possible failures. Failure is
represented by nil, any other value is considered valid. As soon as
a step returns nil, the whole computation will yield nil as well.
Source


maybe-t

function
Usage: (maybe-t m)
       (maybe-t m nothing)
       (maybe-t m nothing which-m-plus)
Monad transformer that transforms a monad m into a monad in which
the base values can be invalid (represented by nothing, which defaults
to nil). The third argument chooses if m-zero and m-plus are inherited
from the base monad (use :m-plus-from-base) or adopt maybe-like
behaviour (use :m-plus-from-transformer). The default is :m-plus-from-base
if the base monad m has a definition for m-plus, and
:m-plus-from-transformer otherwise.
Source


monad

macro
Usage: (monad operations)
Define a monad by defining the monad operations. The definitions
are written like bindings to the monad operations m-bind and
m-result (required) and m-zero and m-plus (optional).
Source


monad-transformer

macro
Usage: (monad-transformer base which-m-plus operations)
Define a monad transforer in terms of the monad operations and the base
monad. The argument which-m-plus chooses if m-zero and m-plus are taken
from the base monad or from the transformer.
Source


run-cont

function
Usage: (run-cont c)
Execute the computation c in the cont monad and return its result.
Source


sequence-m

var

  
Monad describing multi-valued computations, i.e. computations
that can yield multiple values. Any object implementing the seq
protocol can be used as a monadic value.
Source


sequence-t

function
Usage: (sequence-t m)
       (sequence-t m which-m-plus)
Monad transformer that transforms a monad m into a monad in which
the base values are sequences. The argument which-m-plus chooses
if m-zero and m-plus are inherited from the base monad
(use :m-plus-from-base) or adopt sequence-like
behaviour (use :m-plus-from-transformer). The default is :m-plus-from-base
if the base monad m has a definition for m-plus, and
:m-plus-from-transformer otherwise.
Source


set-m

var

  
Monad describing multi-valued computations, like sequence-m,
but returning sets of results instead of sequences of results.
Source


set-state

function
Usage: (set-state s)
Return a state-monad function that replaces the current state by s and
returns the previous state.
Source


set-val

function
Usage: (set-val key val)
Return a state-monad function that assumes the state to be a map and
replaces the value associated with key by val. The old value is returned.
Source


state-m

var

  
Monad describing stateful computations. The monadic values have the
structure (fn [old-state] [result new-state]).
Source


state-m-until

function
Usage: (state-m-until p f x)
An optimized implementation of m-until for the state monad that
replaces recursion by a loop.
Source


state-t

function
Usage: (state-t m)
Monad transformer that transforms a monad m into a monad of stateful
computations that have the base monad type as their result.
Source


update-state

function
Usage: (update-state f)
Return a state-monad function that replaces the current state by the
result of f applied to the current state and that returns the old state.
Source


update-val

function
Usage: (update-val key f)
Return a state-monad function that assumes the state to be a map and
replaces the value associated with the given key by the return value
of f applied to the old value. The old value is returned.
Source


with-monad

macro
Usage: (with-monad monad & exprs)
Evaluates an expression after replacing the keywords defining the
monad operations by the functions associated with these keywords
in the monad definition given by name.
Source


with-state-field

function
Usage: (with-state-field key statement)
Returns a state-monad function that expects a map as its state and
runs statement (another state-monad function) on the state defined by
the map entry corresponding to key. The map entry is updated with the
new state returned by statement.
Source


writer-m

function
Usage: (writer-m empty-accumulator)
Monad describing computations that accumulate data on the side, e.g. for
logging. The monadic values have the structure [value log]. Any of the
accumulators from clojure.contrib.accumulators can be used for storing the
log data. Its empty value is passed as a parameter.
Source
Logo & site design by Tom Hickey.
Clojure auto-documentation system by Tom Faulhaber.