From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:47557) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cw3k1-0001J5-7s for guix-patches@gnu.org; Thu, 06 Apr 2017 05:30:14 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cw3jw-000226-Ej for guix-patches@gnu.org; Thu, 06 Apr 2017 05:30:09 -0400 Received: from debbugs.gnu.org ([208.118.235.43]:36275) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cw3jw-000222-B9 for guix-patches@gnu.org; Thu, 06 Apr 2017 05:30:04 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1cw3jw-00063l-24 for guix-patches@gnu.org; Thu, 06 Apr 2017 05:30:04 -0400 Subject: bug#26382: [PATCH 3/3] monads: Improve mlet, mlet*, and mbegin documentation. Resent-Message-ID: From: Chris Marusich Date: Thu, 6 Apr 2017 02:28:36 -0700 Message-Id: <20170406092836.24766-3-cmmarusich@gmail.com> In-Reply-To: <20170406092836.24766-1-cmmarusich@gmail.com> References: <20170406091546.24107-1-cmmarusich@gmail.com> <20170406092836.24766-1-cmmarusich@gmail.com> List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+kyle=kyleam.com@gnu.org Sender: "Guix-patches" To: 26382@debbugs.gnu.org Cc: Chris Marusich * doc/guix.texi ((guix) The Store Monad) : Clarify their intended usage. * guix/monads.scm (mlet*, mbegin): Update docstrings accordingly. --- doc/guix.texi | 14 +++++++++++--- guix/monads.scm | 16 +++++++++++----- 2 files changed, 22 insertions(+), 8 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index a1aae8f6c..5cd33a31d 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -4011,8 +4011,15 @@ in this example: @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @ @var{body} ... Bind the variables @var{var} to the monadic values @var{mval} in -@var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the -``normal'' value @var{val}, as per @code{let}. +@var{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 @var{mval} and making @var{var} refer to that +raw, non-monadic value within the scope of the @var{body}. The form +(@var{var} -> @var{val}) binds @var{var} to the ``normal'' value +@var{val}, as per @code{let}. The binding operations occur in sequence +from left to right. The last expression of @var{body} must be a monadic +expression, and its result will become the result of the @code{mlet} or +@code{mlet*} when run in the @var{monad}. @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let} (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}). @@ -4020,7 +4027,8 @@ Bind the variables @var{var} to the monadic values @var{mval} in @deffn {Scheme System} mbegin @var{monad} @var{mexp} ... Bind @var{mexp} and the following monadic expressions in sequence, -returning the result of the last expression. +returning the result of the last expression. Every expression in the +sequence must be a monadic expression. This is akin to @code{mlet}, except that the return values of the monadic expressions are ignored. In that sense, it is analogous to diff --git a/guix/monads.scm b/guix/monads.scm index fe3d5d78f..2f66f4262 100644 --- a/guix/monads.scm +++ b/guix/monads.scm @@ -157,9 +157,14 @@ though BIND is simply binary, as in: (define-syntax mlet* (syntax-rules (->) - "Bind the given monadic values MVAL to the given variables VAR. When the -form is (VAR -> VAL), bind VAR to the non-monadic value VAL in the same way as -'let'." + "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." ;; Note: the '->' symbol corresponds to 'is:' in 'better-monads.rkt'. ((_ monad () body ...) (with-monad monad body ...)) @@ -185,8 +190,9 @@ form is (VAR -> VAL), bind VAR to the non-monadic value VAL in the same way as (define-syntax mbegin (syntax-rules (%current-monad) - "Bind the given monadic expressions in sequence, returning the result of -the last one." + "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." ((_ %current-monad mexp) mexp) ((_ %current-monad mexp rest ...) -- 2.12.0