The procedures that operate on the store described in the previous sections all take an open connection to the build daemon as their first argument. Although the underlying model is functional, they either have side effects or depend on the current state of the store.
The former is inconvenient: the connection to the build daemon has to be carried around in all those functions, making it impossible to compose functions that do not take that parameter with functions that do. The latter can be problematic: since store operations have side effects and/or depend on external state, they have to be properly sequenced.
This is where the
(guix monads) module comes in. This module
provides a framework for working with monads, and a particularly
useful monad for our uses, the store monad. Monads are a construct
that allows two things: associating “context” with values (in our case,
the context is the store), and building sequences of computations (here
computations include accesses to the store). Values in a monad—values
that carry this additional context—are called monadic values;
procedures that return such values are called monadic procedures.
Consider this “normal” procedure:
(define (sh-symlink store) ;; Return a derivation that symlinks the 'bash' executable. (let* ((drv (package-derivation store bash)) (out (derivation->output-path drv)) (sh (string-append out "/bin/bash"))) (build-expression->derivation store "sh" `(symlink ,sh %output))))
(guix monads) and
(guix gexp), it may be rewritten as a
(define (sh-symlink) ;; Same, but return a monadic value. (mlet %store-monad ((drv (package->derivation bash))) (gexp->derivation "sh" #~(symlink (string-append #$drv "/bin/bash") #$output))))
There are several things to note in the second version: the
parameter is now implicit and is “threaded” in the calls to the
gexp->derivation monadic procedures,
and the monadic value returned by
package->derivation is bound
mlet instead of plain
As it turns out, the call to
package->derivation can even be omitted
since it will take place implicitly, as we will see later
(define (sh-symlink) (gexp->derivation "sh" #~(symlink (string-append #$bash "/bin/bash") #$output)))
Calling the monadic
sh-symlink has no effect. As someone once said,
“you exit a monad like you exit a building on fire: by running”. So, to
exit the monad and get the desired effect, one must use
(run-with-store (open-connection) (sh-symlink)) ⇒ /gnu/store/...-sh-symlink
Note that the
(guix monad-repl) module extends the Guile REPL with
new “commands” to make it easier to deal with monadic procedures:
enter-store-monad (veja Using Guix Interactively). The former is used to “run” a single monadic value
through the store:
scheme@(guile-user)> ,run-in-store (package->derivation hello) $1 = #<derivation /gnu/store/…-hello-2.9.drv => …>
The latter enters a recursive REPL, where all the return values are automatically run through the store:
scheme@(guile-user)> ,enter-store-monad store-monad@(guile-user) > (package->derivation hello) $2 = #<derivation /gnu/store/…-hello-2.9.drv => …> store-monad@(guile-user) > (text-file "foo" "Hello!") $3 = "/gnu/store/…-foo" store-monad@(guile-user) > ,q scheme@(guile-user)>
Note that non-monadic values cannot be returned in the
Other meta-commands are available at the REPL, such as
build a file-like object (veja Using Guix Interactively).
The main syntactic forms to deal with monads in general are provided by the
(guix monads) module and are described below.
return forms in body as being in
Return a monadic value that encapsulates val.
Bind monadic value mval, passing its “contents” to monadic procedures mproc…22. There can be one mproc or several of them, as in this example:
(run-with-state (with-monad %state-monad (>>= (return 1) (lambda (x) (return (+ 1 x))) (lambda (x) (return (* 2 x))))) 'some-state) ⇒ 4 ⇒ some-state
Bind the variables var to the monadic values mval in body,
which is a sequence of expressions. As with the bind operator, this can be
thought of as “unpacking” the raw, non-monadic value “contained” in
mval and making var refer to that raw, non-monadic value within
the scope of the body. The form (var -> val) binds
var to the “normal” value val, as per
let. The binding
operations occur in sequence from left to right. The last expression of
body must be a monadic expression, and its result will become the
result of the
mlet* when run in the monad.
mlet* is to
let* is to
(veja Local Bindings em GNU Guile Reference Manual).
Bind mexp and the following monadic expressions in sequence, returning the result of the last expression. Every expression in the sequence must be a monadic expression.
This is akin to
mlet, except that the return values of the monadic
expressions are ignored. In that sense, it is analogous to
but applied to monadic expressions.
When condition is true, evaluate the sequence of monadic expressions
mexp0..mexp* as in an
mbegin. When condition is
*unspecified* in the current monad. Every expression
in the sequence must be a monadic expression.
When condition is false, evaluate the sequence of monadic expressions
mexp0..mexp* as in an
mbegin. When condition is
*unspecified* in the current monad. Every expression in
the sequence must be a monadic expression.
(guix monads) module provides the state monad, which allows
an additional value—the state—to be threaded through monadic
The state monad. Procedures in the state monad can access and change the state that is threaded.
Consider the example below. The
square procedure returns a value in
the state monad. It returns the square of its argument, but also increments
the current state value:
(define (square x) (mlet %state-monad ((count (current-state))) (mbegin %state-monad (set-current-state (+ 1 count)) (return (* x x))))) (run-with-state (sequence %state-monad (map square (iota 3))) 0) ⇒ (0 1 4) ⇒ 3
When “run” through
%state-monad, we obtain that additional state
value, which is the number of
Return the current state as a monadic value.
Set the current state to value and return the previous state as a monadic value.
Push value to the current state, which is assumed to be a list, and return the previous state as a monadic value.
Pop a value from the current state and return it as a monadic value. The state is assumed to be a list.
Run monadic value mval starting with state as the initial state. Return two values: the resulting value, and the resulting state.
The main interface to the store monad, provided by the
module, is as follows.
The store monad—an alias for
Values in the store monad encapsulate accesses to the store. When its
effect is needed, a value of the store monad must be “evaluated” by
passing it to the
run-with-store procedure (see below).
value in the store monad, in store, an open store connection.
Return as a monadic value the absolute file name in the store of the file containing text, a string. references is a list of store items that the resulting text file refers to; it defaults to the empty list.
Return as a monadic value the absolute file name in the store of the file containing data, a bytevector. references is a list of store items that the resulting binary file refers to; it defaults to the empty list.
interned in the store. Use name as its store name, or the basename of file if name is omitted.
When recursive? is true, the contents of file are added recursively; if file designates a flat file and recursive? is true, its contents are added, and its permission bits are kept.
When recursive? is true, call
stat) for each directory entry, where file is the entry’s
absolute file name and stat is the result of
entries for which select? does not return true.
The example below adds a file to the store, under two different names:
(run-with-store (open-connection) (mlet %store-monad ((a (interned-file "README")) (b (interned-file "README" "LEGU-MIN"))) (return (list a b)))) ⇒ ("/gnu/store/rwm…-README" "/gnu/store/44i…-LEGU-MIN")
(guix packages) module exports the following package-related
monadic value in the absolute file name of file within the output directory of package. When file is omitted, return the name of the output directory of package. When target is true, use it as a cross-compilation target triplet.
Note that this procedure does not build package. Thus, the result might or might not designate an existing file. We recommend not using this procedure unless you know what you are doing.
package-cross-derivation (veja Definindo pacotes).
This operation is commonly referred to as “bind”, but that name denotes an unrelated procedure in Guile. Thus we use this somewhat cryptic symbol inherited from the Haskell language.