[Guile-commits] 07/07: doc: Document (ice-9 match) macros.

[Ludovic Courtès]

civodul pushed a commit to branch stable-2.2
in repository guile.

commit 1c970da59eb28e0a76d03e3f3689020b779679c9
Author: Arun Isaac <address@hidden>
Date:   Fri Mar 23 19:52:04 2018 +0530

    doc: Document (ice-9 match) macros.
    
    * doc/ref/match.texi: Document match-lambda, match-lambda*, match-let,
      match-let* and match-letrec.
    
    Signed-off-by: Ludovic Courtès <address@hidden>
---
 doc/ref/match.texi | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 90 insertions(+), 2 deletions(-)

diff --git a/doc/ref/match.texi b/doc/ref/match.texi
index 12e3814..0fc5105 100644
--- a/doc/ref/match.texi
+++ b/doc/ref/match.texi
@@ -213,8 +213,96 @@ any @var{person} whose second slot is a promise that 
evaluates to a
 one-element list containing a @var{person} whose first slot is
 @code{"Bob"}.
 
-Please refer to the @code{ice-9/match.upstream.scm} file in your Guile
-installation for more details.
+The @code{(ice-9 match)} module also provides the following convenient
+syntactic sugar macros wrapping around @code{match}.
+
address@hidden {Scheme Syntax} match-lambda exp clause1 clause2 @dots{}
+Create a procedure of one argument that matches its argument against
+each clause, and returns the result of evaluating the corresponding
+expressions.
+
address@hidden
+(match-lambda clause1 clause2 @dots{})
address@hidden
+(lambda (arg) (match arg clause1 clause2 @dots{}))
address@hidden example
address@hidden deffn
+
address@hidden
+((match-lambda
+   (('hello (who))
+    who))
+ '(hello (world)))
address@hidden world
address@hidden example
+
address@hidden {Scheme Syntax} match-lambda* exp clause1 clause2 @dots{}
+Create a procedure of any number of arguments that matches its argument
+list against each clause, and returns the result of evaluating the
+corresponding expressions.
+
address@hidden
+(match-lambda* clause1 clause2 @dots{})
address@hidden
+(lambda args (match args clause1 clause2 @dots{}))
address@hidden example
address@hidden deffn
+
address@hidden
+((match-lambda*
+   (('hello (who))
+    who))
+ 'hello '(world))
address@hidden world
address@hidden example
+
address@hidden {Scheme Syntax} match-let ((pattern expression) @dots{}) body
+Match each pattern to the corresponding expression, and evaluate the
+body with all matched variables in scope.  Raise an error if any of the
+expressions fail to match.  @code{match-let} is analogous to named let
+and can also be used for recursive functions which match on their
+arguments as in @code{match-lambda*}.
+
address@hidden
+(match-let (((x y) (list 1 2))
+            ((a b) (list 3 4)))
+  (list a b x y))
address@hidden
+(3 4 1 2)
address@hidden example
address@hidden deffn
+
address@hidden {Scheme Syntax} match-let variable ((pattern init) @dots{}) body
+Similar to @code{match-let}, but analogously to @dfn{named let}, locally
+bind VARIABLE to a new procedure which accepts as many arguments as
+there are INIT expressions.  The procedure is initially applied to the
+results of evaluating the INIT expressions.  When called, the procedure
+matches each argument against the corresponding PATTERN, and returns the
+result(s) of evaluating the BODY expressions.  @xref{while do,
+Iteration}, for more on @dfn{named let}.
address@hidden deffn
+
address@hidden {Scheme Syntax} match-let* ((variable expression) @dots{}) body
+Similar to @code{match-let}, but analogously to @code{let*}, match and
+bind the variables in sequence, with preceding match variables in scope.
+
address@hidden
+(match-let* (((x y) (list 1 2))
+             ((a b) (list x 4)))
+  (list a b x y))
address@hidden
+(match-let (((x y) (list 1 2)))
+  (match-let (((a b) (list x 4)))
+    (list a b x y)))
address@hidden
+(1 4 1 2)
address@hidden example
address@hidden deffn
+
address@hidden {Scheme Syntax} match-letrec ((variable expression) @dots{}) body
+Similar to @code{match-let}, but analogously to @code{letrec}, match and
+bind the variables with all match variables in scope.
address@hidden deffn
 
 Guile also comes with a pattern matcher specifically tailored to SXML
 trees, @xref{sxml-match}.