The XMonad class defines the basic operations over a parameterized (indexed) monad, where two type parameters must be correctly chained.

These monads have been described by Oleg Kiselyov in parameterized monads

Indexed monads have been previously released by Edward A. Kmett and Reiner Pope as the package indexed - this package adds other monadic functions and freer indexed monad XFree.

Semantically, these computations can represent type-level state changes of some associated resource, with the first index parameter meaning initial resource state prior to the computation, and the second index - the final resource state, making each computation an edge in the graph of resource state transitions.

Chained type parameters in bind operation require that associated resource changes are continuos.

When combined with computations defined as GADTs and singleton types they can be used to limit allowed computations depending on the context (that is reflected in the final type of the previous and initial type of the next computations) and to make type-level state transitions dependent on the run-time parameters and also on the results of the previous computations.

do expressions can support such parameterized monads using RebindableSyntax extension and Control.XMonad.Do module (it has to be imported separately).

If your code contains any action that can fail (e.g. "monadic" binding with a potentially incomplete pattern match, your computation needs to be an instance of XMonadFail as well to be used in do expression.

To use do expressions Prelude has to be explicitly imported hiding monad operators:

import Prelude hiding ((>>), (>>=))

Instances of XMonad should satisfy the same laws as Monad:

Left identity

xreturn a >>=: k = k a

Right identity

m >>=: xreturn = m

Associativity

m >>=: (\x -> k x >>=: h) = (m >>=: k) >>=: h

XMonad and XApplicative operations should relate as follows:

• xpure = xreturn

• mf <*>: m = mf >>=: (\f -> m >>=: (\x -> xreturn (f x)))

The above laws imply:

• fmap f xs  =  xs >>=: xreturn . f

• (>>:) = (*>:)

and that xpure and (<*>:) satisfy the applicative functor laws.

Promote a function to XMonad.

Promote a binary function to XMonad, scanning the monadic arguments from left to right.

Promote a function to a monad, scanning the monadic arguments from left to right.

liftXM operations can be replaced by uses of ap, which promotes function application.

return f `ap` x1 `ap` ... `ap` xn

is equivalent to

liftMn f x1 x2 ... xn

The xjoin function removes one level of indexed monadic structure, projecting its bound argument into the outer level.

'join bss' can be understood as the do expression

do bs <- bss
   bs

Please note the chaining order of type parameters - from outside to inside.

Left-to-right composition of Kleisli arrows.

'(f >=>: g) a' is equivalent to \x -> f x >>=: g

Right-to-left composition of Kleisli arrows. Same as (>=>:), with the arguments flipped.

This operator resembles function composition (.):

(.)    ::             (b ->       c) -> (a ->       b) -> a ->       c
(<=<:) :: XMonad m => (b -> m q r c) -> (a -> m p q b) -> a -> m p r c

Strict version of <$> for indexed monads.

When a type-indexed computation value is bound in do-notation (using RebindableSyntax for XMonad), the pattern on the left hand side of <- might not match. In this case, this class provides a function xfail to recover.

An XMonad without an XMonadFail instance may only be used in conjunction with pattern that always match, such as newtypes, tuples, data types with only a single data constructor, and irrefutable patterns (~pat).

Instances of XMonadFail should satisfy the following law: xfail s should be a left zero for >>=:.

xfail s >>=: f = xfail s