API for clojure.algo.monads - Monad Macros and Definitions 0.1.7 (in development)

by Konrad Hinsen

Full namespace name: clojure.algo.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 Blog posts on monads in Clojure

Protocols



writer-monad-protocol

Protocol
Accumulation of values into containers
Known implementations: clojure.lang.APersistentSet, clojure.lang.IPersistentList, clojure.lang.IPersistentVector, java.lang.String

writer-m-add

function
Usage: (writer-m-add container value)
add value to container, return new container

      
      
      
    

writer-m-combine

function
Usage: (writer-m-combine container1 container2)
combine two containers, return new container

      
      
      
    
Source

Public Variables and Functions



ask

function
Usage: (ask)
Returns the environment.

    
    
    Source
  


asks

function
Usage: (asks f)
Returns a function of the current environment.

    
    
    Source
  


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
  


cond-statement

function
Usage: (cond-statement expr mexpr continuation)
Process a :cond steps when adding a new monadic step to the mexpr.

    
    
    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
  


local

function
Usage: (local f g)
Runs reader g in the context of an environment modified by f

    
    
    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 transformer 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
  


reader-m

var

    
Monad describing computations which read values from a shared environment.
Also known as the environment monad.

    
    
    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.