`let x = `*xint* in ...

. If we wanted instead to have a version which accepted not an `int` but rather an `int` in a Reader monad box, we could write instead:
+
+ let letx xx body = xx >>= fun xint -> shift (insert 'x' xint) body
+
+
+### Examples ###
+
+Here are some examples of using the Reader Monad modules to evaluate some simple expressions using bound variables. First, you could look at [[this Haskell code|/code/reader1.hs]]. It `import`s the `Control.Monad.Reader` library, which is where Haskell's Reader monad can be found. It declares an `Env` type that we'll implement as a simple *function* from `Char`s to `Int`s. Then it defines an "empty" environment `env0`, and a function `insert` for adding new bindings to an `env`. Next, we make a general function `getint` that can create monadic values like the `getx` illustrated above. We show how to use `getx` and `gety` to write monadic versions of `y + x` and `3 + x`. Next, we define a `letx` function as illustrated above (the second version, that takes a monadic value `xx` as its argument). We show how to use this to write a monadic version of `let x = 2 in y + x`. The final line of the file applies `runReader` to the monadic value we've built --- this is Haskell's way of doing what we do in OCaml with `run`, namely to remove the abstraction barrier and see what concrete type is really constituting our `Reader Env a`s --- and we supply it with the empty environment, which will be sufficient since the expression we're interpreting has no free variables. Haskell binds the variable `res` to the result. You can run this code inside `ghci` by typing `:load /path/to/reader1.hs`. (You could also say `:add ...` instead of `:load ...`.) Then type `res`, and Haskell will report back `5`.
+
+[[This OCaml code|/code/reader1.ml]] does exactly the same thing only using our OCaml monad libraries instead. The biggest difference from the Haskell version is in the first few lines, where we have to generate a Reader monad module parameterized on the `env` type that we intend to work with.
+
+Here's a more complicated example. This time we want to be able to bind variables to lambda abstracts as well as to `int`s. So our `env` type will need to be more complex; it will have to associate `char`s with a disjoint sum of `int`s and lambda abstracts. Now what will the type of the lambda abstracts be? Let's just restrict our attention to abstracts whose bodies return `int`s. But they might get those `int`s by performing operations on bound variables, so the body expressions need to be interpreted monadically, as `int Reader`s. We'll construe the whole lambda abstract as a function from `int Reader`s (that is, the monadic values which are provided as arguments to the lambda abstract) to their results, so the lambda abstract will have the type `int Reader -> int Reader`. In OCaml that will be `int R.t -> int R.t`, and in Haskell `Reader Env Int -> Reader Env Int`. Since variables can be bound to either `int`s or to lambda abstracts, we declare our environments like this in OCaml:
+
+ type bound = Int of int | Fun of (int R.t -> int R.t)
+ type env = char -> bound
+
+and like this in Haskell:
+
+ data Bound = Int Int | Fun (Reader Env Int -> Reader Env Int)
+ type Env = Char -> Bound
+
+There is a tricky issue in the OCaml case, though, in that when working with OCaml, we have to *generate* our R Reader monad module, parameterized on the type of the `env`, but here we see that we need access to the *type* `'a R.t` from the generated R module in order to declare the `env`. Fortunately, it is possible to do this, by having the module that declares the `env` and the module that has our Reader monad in it be mutually recursively defined. The first few lines of [[this OCaml code|/code/reader2.ml]] do the tricky work.
+
+After that, our [[Haskell code|/code/reader2.hs]] and [[OCaml code|/code/reader2.ml]] proceed basically the same, allowing for the difference in syntax and vocabulary between Haskell and OCaml. The `getint` function works like before, except now we have to pull the int out from behind the `Int` constructor of our disjoint sum type `bound`. We have a parallel `getfun` function. Then we interpret the variable `x` using the monadic value `getint 'x'`, and we interpret the variable `f` using the monadic value `getfun 'f'`. The `letx` operation is similarly adjusted, and we also have a parallel `letf`.
+
+The really new thing in this code, compared to the previous example, is our definition of a monadic value to interpret the lambda abstract `\y -> y + x`, that `f` gets bound to. And also our interpretation of the expression `f 3`, which looks up a function that the variable `f` is bound to, and then applies it to (a monadically-lifted version of) `3`. (We have the argument be monadically lifted so that we could also say, for example, `f y`.)
+
+
+## OK, what else is in the OCaml Monad modules? ##
+
+I won't give an exhaustive list here. But here is the output of `module type SOMETHING = sig include Monad.BLAH end` for some of the `BLAH`s:
+
+
+ module type STATE =
+ sig
+ type store
+ type 'a t
+ type 'a result = store -> 'a * store
+ (* plus the other usual monadic stuff, and: *)
+ val get : store t
+ val gets : (store -> 'a) -> 'a t
+ val modify : (store -> store) -> unit t
+ val put : store -> unit t
+ end
+
+The `store` type has to be provided by you, when you generate the module, similarly to as in the Reader monad. The `'a result` type shows the real definition of an `'a State` type, otherwise kept abstract as `'a t`. Instead of the special operations `ask` and so on that the Reader monad has, State has the operations `get`, `gets`, `modify`, and `put`. The first two work just like `ask` and `asks` did for the Reader monad. The third one works *similarly* to `shift` for the Reader monad, with the crucial difference that the rebinding that `shift` introduces is in effect only for the `body` argument of the `shift` operation. Outside of that `body`, we revert to the originally supplied `env`. But notice that `modify` doesn't take any `body` argument. `modify` introduces changes to the supplied `store` that once introduced *stay in place*, until we manually change them again. Thus with the Reader monad you'd do things like this:
+
+ R.(xx >>= fun x -> ... shift (insert ...) body >>= fun y -> (* now we're using the unshifted env *) ...)
+
+With the State monad you'd instead do things like this:
+
+ S.(xx >>= fun x -> ... modify (fun old_store -> new_store) >>= fun () -> (* we continue using the modified store, until it's modified once again *) ...)
+
+Since the pattern `... >>= fun () -> ...` or `... >>= fun variable_you_never_use -> ...` occurs often when working with monads, there's a shorthand: you can instead say `... >> ...`, with `>>` in place of `>>= fun pattern ->`.
+
+Here's another monad module signature:
+
+ module type WRITER =
+ sig
+ type log
+ type 'a t
+ type 'a result = 'a * log
+ (* plus the other usual monadic stuff, and: *)
+ val listen : 'a t -> ('a * log) t
+ val listens : (log -> 'b) -> 'a t -> ('a * 'b) t
+ val tell : log -> unit t
+ val censor : (log -> log) -> 'a t -> 'a t
+ end
+
+Writer is very similar to Reader: first, it is parameterized on something like an `env`, here called a `log`. (A typical implementation for `log` would be the `string` type.) Second, the Writer operations `listen`, `listens`, and `censor` parallel the Reader operations `ask`, `asks`, and `shift`. But one difference is that with Writer, you cannot choose what initial `env` (`log`) to supply. You always begin with the `empty` `log` (such as `""` for `string`s). A second difference is that the types differ. Compare:
+
+ module type READER =
+ sig
+ ...
+ val ask : env t
+ val asks : (env -> 'a) -> 'a t
+ val shift : (env -> env) -> 'a t -> 'a t
+ end
+
+Whereas Writer's `sensor` and Reader's `shift` have isomorphic types, there is some extra complextity to Writer's `listen` and `listens`, compared to `ask` and `asks`. What this extra complexity means is that for `Writer`, listening happens only in a local context. You can't `listen` to what got written to the log before you installed your `listen`ing tap. But you can return payloads that are dependent on what you've heard in the local context.
+
+Unlike Reader, Writer also has a `tell` operation, which is akin to the `put` operation in the State monad. The difference is that the `tell` function takes a `log` as argument and *appends* that to the existing `log`. You can't erase or overwrite elements already in the `log`; you can only append to it. However, if you like, you can `censor` the log in arbitrary ways and use that when interpreting other monadic values locally. After that local context, though, we return to the original log (
+
+Here's a complex example that illustrates this. First we will use the helper function `String.upper` (from "juli8.ml") and a second helper function that we define like this:
+
+ let bracket log = "{" ^ log ^ "}"
+
+Next, we construct some monadic values and reveal them at the end using `run`:
+
+ module W_L = Monad.Writer(struct
+ type log = string
+ let empty = ""
+ let append s1 s2 = if s1 = "" then s2 else if s2 = "" then s1 else s1 ^ " " ^ s2
+ end)
+ module W = Writer1.M;;
+ W.(let xx = tell "one" >> listens bracket (tell "two" >> mid 10) in
+ let yy = censor String.upper (tell "zero" >> listens bracket xx) in
+ let zz = tell "before" >> yy >>= fun y -> tell "after" >> mid y in
+ ...);;
+
+The monadic value `xx` writes "one" to the log, then discards the resulting `()` payload (it continues `>> ...` rather than `>>= fun var -> ...`). Then we have a use of `listens`. This will evaluate its body `tell "two" >> mid 10` and return as payload a pair of the body's original payload and a bracketed copy of the local log. Thus the payload of `listens bracket (tell "two" >> mid 10)` will be `(10, "{two}")`. The `"one"` that got written to the log earlier isn't accessible to `listens`; however it does stay in the log. Hence the result of `run xx`, showing first the payload and then the log, would be:
+
+ - : (int * string) W.result = ((10, "{two}"), "one two")
+
+Now `yy` uses that `xx` monadic value to illustrate the use of `censor`. Here we have `censor` apply `String.upper` to the log generated in the local context it's applied to, hence the result of `run yy` would be:
+
+ - : ((int * string) * string) W.result = (((10, "{two}"), "{one two}"), "ZERO ONE TWO three")
+
+The final value `zz` shows what happens to entries written to the log before and after the `censor`ing that occurs in `yy`, namely nothing. That is, `run zz` is:
+
+- : ((int * string) * string) W.result = (((10, "{two}"), "{one two}"), "before ZERO ONE TWO after")
+
+Let's look at some more familiar monad signatures. Here is one:
+
+ module type OPTION =
+ sig
+ type 'a t
+ type 'a result = 'a option
+ (* plus the other usual monadic stuff, and: *)
+ val mzero : 'a t
+ val guard : bool -> unit t
+ val test : ('a option -> bool) -> 'a t -> 'a t
+ end
+
+This is what's exposed in the `Monad.Option.M` module (with `Option` and `List`, you can also leave off the initial `Monad.`). In the parent `Monad.Option` module itself, there are many more operations. Similarly, `Monad.List` (aka just `List`) exposes many more operations than `Monad.List.M` does. The `.M` modules restrict us to just the monadic interface. Unlike Reader and State and Writer, the Option and List monads don't need to be parameterized on environments or anything else of that sort. The Option monad has three additional monadic operations, analogues of which are also all present in List. First, there is the `mzero` monadic value, implemented as `None` and satisfying the Monad Laws for `mzero` we explained elsewhere. The key one to remember is that `mzero` aborts a chain of composed Kleisli functions. That is, `mzero >>= anything` is always `mzero`. `guard` takes a boolean argument and if its false, gives `mzero`. If the argument is true, it just gives the uninteresting `mid ()`, hence the typical way to use `guard` is as:
+
+ module O = Option.M;;
+ O.(guard some_bool_expr >> more_monadic_stuff)
+
+If `some_bool_expr` is true, then this will ignore its payload and go on to compute `more_monadic_stuff`; if it's false, then the whole chain gets ignored because of the distinctive behavior of `mzero`.
+
+The third special operation in the Option monad is `test`. This lets you supply a function that takes an ordinary `'a option` type (that is, one where the "abstraction curtain" imposed by the `'a O.t` type is not in place) and returns a bool. Then you take an Option monadic value (one where the "abstraction curtain" *is* in place). OCaml will temporarily remove the abstraction curtain on the second argument and see how the function you supplied assesses it. If the result is `true`, then the result is identical to that Option monadic value, unaltered. If the result is `false`, then the result is `mzero`. (For those of you who know Frank Veltman's work on dynamic semantics for epistemic modals, this is a key component.)
+
+Here is the List monadic interface:
+
+ module type LIST =
+ sig
+ type 'a t
+ type 'a result = 'a list
+ (* plus the other usual monadic stuff, and: *)
+ val mzero : 'a t
+ val guard : bool -> unit t
+ val test : ('a list -> bool) -> 'a t -> 'a t
+ val ( ++ ) : 'a t -> 'a t -> 'a t
+ val pick : 'a t -> ('a * 'a t) t
+ end
+
+The `mzero` and `guard` and `test` operations work analogously to the ones in the Option monad. The `++` (infix) operation is like `List.append` (OCaml also uses `@` for that), with the difference that `++` is defined on the abstract List monadic values of type `'a List.M.t`, not the OCaml native lists (with the "abstraction curtain" removed). In Haskell, `++` works on either native lists or elements of the List monad, because Haskell doesn't distinguish them. Haskell doesn't impose an abstraction curtain in the case of its List and Maybe monads. `pick` is an operation that transforms (the abstract version of) `[1; 2; 3]` to (the abstract version of) `[(1, [2; 3]); (2, [1; 3]); (3, [1; 2])]`.
+
+Here is another monadic interface:
+
+ module type TREE =
+ sig
+ type 'a tree
+ type 'a t
+ type 'a result = 'a tree
+ (* plus the other usual monadic stuff, and: *)
+ val ( ++ ) : 'a t -> 'a t -> 'a t
+ end
+
+This is the signature/module type for the Monad.LTree module. ("LTree" for *leaf-labeled* trees.)
+
+You can create leaf-only trees using the monadic function `mid`. You can join two trees together using the function `++`, paralleling the one in List. Note that in the Tree case, unlike the List case, `++` is not associative: `xx ++ (yy ++ zz)` is not the same as `(xx + yy) ++ zz`. Nor is there any `mzero` for trees as implemented by this module.
+
--
2.11.0