Hold a state of type s, which is allowed to be mutated by an action of a monoid w.

The state s has the role of the current state. An a is computed while performing a side effect in m, and these can depend on the current state.

The type w encodes changes (or updates, edits, commits, diffs, patches ...) to the state s. This relation is captured by the RightAction type class from monoid-extras. It contains a method, act :: w -> s -> s, which implements the semantics of w as the type of updates to s.

The standard example is that of a big record where we only want to change a small portion:

data User = User
  { name :: Text
  , password :: Hash
  , ...
  , addresses :: Map Text Address
  , ...
  }

If all changes that our business logic should be able to perform are adding or deleting an address, it would be cumbersome to work in a State User monad, since we only want to modify a small portion. Instead, we define a type of changes to User:

data ChangeAddress
  -- | Add an address under a given key
  = Add Text Address
  -- | Delete the address for the given key
  | Delete Text

instance RightAction ChangeAddress User where
  act = ...

Now we can conveniently work in the monad ChangesetT User [ChangeAddress] m. (Note the list type which gives us a free Monoid instance.) Here we can perform operations like change [Add "home" homeAddress] or change [Delete "work"] to modify the addresses, current to view the current state (containing all changes so far), or apply a more complex function like revise $ const $ filter (/= Delete "default") which would remove all changes that attempt to delete the "default" address.

As a further example, if s represents some type of time stamps, then w can be a type of durations: Two timestamps cannot be added, but two durations can. A computation in ChangesetT s w could then have access to some simulated notion of "current time", while being able to add symbolic "delays".

Another class of examples arises operation based or commutative Conflict-free Replicated Data Type (CRDT). Then s is the internal state (the "payload") of the CRDT, and w is the update operation. For example s = Int, and for w we would define data Count = Increment | Decrement.

The Monad and Applicative classes are defined by performing the first action, then acting with the monoid output onto the state, and then perform the second action with the updated state. So for example, change Increment >> current is different from current >>= (n -> change Increment >> return n): If we apply flip evalChangeset 0 to each, the first one would return 1, while the second returns 0.

So, if at any point in a do notation we want to inspect the current state, we can assume that all previous changes have been applied. In that sense, this monad behaves very much like any other state monad transformer.

Extract the changes that would be applied.

Run the action with an initial state and apply all resulting changes to it.

Run the action with an initial state and extract only the value.

Run the action with an initial state and extract only the state.

See changeset.

The A suffix means that only Applicative is required, not Monad.

See change.

The A suffix means that only Applicative is required, not Monad.

See current.

The A suffix means that only Applicative is required, not Monad.

Like lift from the MonadTrans class, but with fewer constraints.

Change the action that would be applied.

The function in the second position of the tuple receives the initial state and the change that would be applied. It has to output the action that will be applied instead.

Adds the to-be-applied changes to the foreground value.

Precomposes the current state with a function to before computing the change.

Apply a function to the change.

Like (<*>) from Applicative, but ignore the change from the first action in the initial state for the second action.

This only needs an Applicative constraint on m, not Monad.

Like hoist from the mmorph package, but with no constraints.

A pure changeset acts in the Identity monad. The only effects it has are inspecting the current state, and adding a change.

Changeset s w a is isomorphic to s -> (w, a).

Like getChangesetT.

Like getChangeT.

Like runChangesetT.

Like evalChangesetT.

Like execChangesetT.

A collection of individual changes.

Often, we only want to define a type for single changes to a state. In that case, Changes is handy. It serves as a container for changes that don't have a Monoid or Semigroup instance. All changes are applied sequentially.

To inspect or edit Changes, see the type classes Functor, Foldable, Traversable, Filterable and Witherable.

Create Changes from a list of changes.

Append a single change.

When addChange w cs acts on a state with actRight, w will be applied last.

Create a Changes from a single change.

Apply a single change.

A list can be changed by prepending an element, or removing one.

To change an element of a list, see the indexed changes from changeset-lens.

An integer can be incremented by 1.

Change a Maybe by either deleting the value or forcing it to be present.

Set the state to the given Maybe value.

Set the state to Just.

Set the state to Nothing.

Change a Functor structure by applying a change for every element through fmap.

Apply changes only to Just values.

Apply changes only to Just values.