bug#30144: [PATCH] doc: Document (ice-9 match) macros.

bug#30144: [PATCH] doc: Document (ice-9 match) macros.

[Arun Isaac]

* doc/ref/match.texi: Document match-lambda, match-lambda*, match-let,
  match-let* and match-letrec.
---
 doc/ref/match.texi | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 63 insertions(+), 2 deletions(-)

diff --git a/doc/ref/match.texi b/doc/ref/match.texi
index 12e3814ae..4d85fe3f9 100644
--- a/doc/ref/match.texi
+++ b/doc/ref/match.texi
@@ -213,8 +213,69 @@ 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}.
+
+@deffn {Scheme Syntax} match-lambda exp clause1 clause2 @dots{}
+Create a procedure of one argument that matches its argument against
+each clause.
+
+@example
+(match-lambda clause1 clause2 @dots{})
+@equiv{}
+(lambda (arg) (match arg clause1 clause2 @dots{}))
+@end example
+@end deffn
+
+@deffn {Scheme Syntax} match-lambda* exp clause1 clause2 @dots{}
+Create a procedure of any number of arguments that matches its argument
+list against each clause.
+
+Equivalent to
+@example
+(match-lambda* clause1 clause2 @dots{})
+@equiv{}
+(lambda args (match args clause1 clause2 @dots{}))
+@end example
+@end deffn
+
+@deffn {Scheme Syntax} match-let ((variable expression) @dots{}) body
+Match each variable 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*}.
+
+@example
+(match-let (((x y) (list 1 2))
+	    ((a b) (list 3 4)))
+  (list a b x y))
+@result{}
+(3 4 1 2)
+@end example
+@end deffn
+
+@deffn {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.
+
+@example
+(match-let* (((x y) (list 1 2))
+	     ((a b) (list x 4)))
+  (list a b x y))
+@equiv{}
+(match-let (((x y) (list 1 2)))
+  (match-let (((a b) (list x 4)))
+    (list a b x y)))
+@result{}
+(1 4 1 2)
+@end example
+@end deffn
+
+@deffn {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.
+@end deffn
 
 Guile also comes with a pattern matcher specifically tailored to SXML
 trees, @xref{sxml-match}.
-- 
2.15.1

bug#30144: [PATCH] doc: Document (ice-9 match) macros.

[Mark H Weaver]

Hi Arun,

Arun Isaac <arunisaac@systemreboot.net> writes:

> * doc/ref/match.texi: Document match-lambda, match-lambda*, match-let,
>   match-let* and match-letrec.

Modulo a few minor nits, which I'll describe in another message, this
patch looks great to me!  Would you be willing to assign the copyright
to the Free Software Foundation, so that we could install it in Guile?
If you agree, I'll follow up off-list.

   Thank you!
      Mark

bug#30144: [PATCH] doc: Document (ice-9 match) macros.

[Arun Isaac]

Mark H Weaver <mhw@netris.org> writes:

> Would you be willing to assign the copyright to the Free Software
> Foundation, so that we could install it in Guile?

Yes, sure. I'd be happy to assign copyright to the FSF. Let me know what
I should do.

bug#30144: [PATCH] doc: Document (ice-9 match) macros.

[Ludovic Courtès]

Hi Mark,

Mark H Weaver <mhw@netris.org> skribis:

> Arun Isaac <arunisaac@systemreboot.net> writes:
>
>> * doc/ref/match.texi: Document match-lambda, match-lambda*, match-let,
>>   match-let* and match-letrec.
>
> Modulo a few minor nits, which I'll describe in another message, this
> patch looks great to me!

Now that Arun’s assignment is on file, is there anything you’d like to
add to the patch?  Or should we commit as is?

Thanks,
Ludo’.

bug#30144: [PATCH] doc: Document (ice-9 match) macros.

[Mark H Weaver]

Hi Arun,

I apologize for the long delay on this.  This patch mostly looks great
to me, but there are a few minor issues.  Please see below for comments.

Arun Isaac <arunisaac@systemreboot.net> writes:

> * doc/ref/match.texi: Document match-lambda, match-lambda*, match-let,
>   match-let* and match-letrec.
> ---
>  doc/ref/match.texi | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 63 insertions(+), 2 deletions(-)
>
> diff --git a/doc/ref/match.texi b/doc/ref/match.texi
> index 12e3814ae..4d85fe3f9 100644
> --- a/doc/ref/match.texi
> +++ b/doc/ref/match.texi
> @@ -213,8 +213,69 @@ 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}.
> +
> +@deffn {Scheme Syntax} match-lambda exp clause1 clause2 @dots{}
> +Create a procedure of one argument that matches its argument against
> +each clause.

How about adding "and evaluates the corresponding expressions" or
something like that?

> +
> +@example
> +(match-lambda clause1 clause2 @dots{})
> +@equiv{}
> +(lambda (arg) (match arg clause1 clause2 @dots{}))
> +@end example

It might be nicer to include an actual example here, rather than just
showing the raw transformation.  What do you think?

> +@end deffn
> +
> +@deffn {Scheme Syntax} match-lambda* exp clause1 clause2 @dots{}
> +Create a procedure of any number of arguments that matches its argument
> +list against each clause.
> +
> +Equivalent to
> +@example
> +(match-lambda* clause1 clause2 @dots{})
> +@equiv{}
> +(lambda args (match args clause1 clause2 @dots{}))
> +@end example
> +@end deffn

My suggestions above for 'match-lambda' also apply to 'match-lambda*'.

> +
> +@deffn {Scheme Syntax} match-let ((variable expression) @dots{}) body

"variable" here should be replaced with "pattern".  In general, any
pattern can go there.

> +Match each variable 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

It's only analogous to a named let if a variable name is inserted
immediately after 'match-let', before the clauses.  In fact, the
named-let case is not covered by the first line of your definition where
you give the syntax.

How about removing any mention of named-let in this definition, and then
add a separate brief definition for the named-let variant of
'match-let'?  It might be worthwhile to keep them separate given that
their use cases and relevant examples are so different.  What do you
think?

> +and can also be used for recursive functions which match on their
> +arguments as in @code{match-lambda*}.
> +
> +@example
> +(match-let (((x y) (list 1 2))
> +	    ((a b) (list 3 4)))

There's a tab character in the line above, which causes things to not
line up properly when looking at the diff.  Could you convert tabs to
spaces?  In emacs, it can be done using M-x untabify.

Would you like to send a revised patch?

     Mark

bug#30144: [PATCH] doc: Document (ice-9 match) macros.

[Mark H Weaver]

Mark H Weaver <mhw@netris.org> writes:

> Arun Isaac <arunisaac@systemreboot.net> writes:
>> +@deffn {Scheme Syntax} match-lambda exp clause1 clause2 @dots{}
>> +Create a procedure of one argument that matches its argument against
>> +each clause.
>
> How about adding "and evaluates the corresponding expressions" or
> something like that?

It occurs to me that we should also document the return value.  How
about adding "and returns the result(s) of evaluating the corresponding
expressions"?

      Mark

bug#30144: [PATCH] doc: Document (ice-9 match) macros.

[Arun Isaac]

>> +Match each variable 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
>
> It's only analogous to a named let if a variable name is inserted
> immediately after 'match-let', before the clauses.  In fact, the
> named-let case is not covered by the first line of your definition where
> you give the syntax.

> How about removing any mention of named-let in this definition, and then
> add a separate brief definition for the named-let variant of
> 'match-let'?  It might be worthwhile to keep them separate given that
> their use cases and relevant examples are so different.  What do you
> think?

I have made all the other changes except this one. I have never used
match-let analogous to a named let, and am unable to get a working
example. If you could show me a working example, I'll add it to the new
patch.

I'll send you the revised patch once we decide on the above. Thanks!

bug#30144: [PATCH] doc: Document (ice-9 match) macros.

[Mark H Weaver]

Hi Arun,

Arun Isaac <arunisaac@systemreboot.net> writes:

>>> +Match each variable 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
>>
>> It's only analogous to a named let if a variable name is inserted
>> immediately after 'match-let', before the clauses.  In fact, the
>> named-let case is not covered by the first line of your definition where
>> you give the syntax.
>
>> How about removing any mention of named-let in this definition, and then
>> add a separate brief definition for the named-let variant of
>> 'match-let'?  It might be worthwhile to keep them separate given that
>> their use cases and relevant examples are so different.  What do you
>> think?
>
> I have made all the other changes except this one. I have never used
> match-let analogous to a named let, and am unable to get a working
> example. If you could show me a working example, I'll add it to the new
> patch.
>
> I'll send you the revised patch once we decide on the above. Thanks!

I thought about it, and I can't easily think of a good use for named
'match-let'.  Any recursion needs a base case, which requires at least
two cases in the match, but 'match-let' does not allow for multiple
cases for its matches.

How about if we omit an example for named 'match-let', and simply say
something like:

@deffn {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}.

     Thanks!
       Mark

bug#30144: [PATCH 0/1] Document (ice-9 match) macros

[Arun Isaac]

Hi,

I have made all the changes you suggested. Patch follows.

Thanks.

Arun Isaac (1):
  doc: Document (ice-9 match) macros.

 doc/ref/match.texi | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 90 insertions(+), 2 deletions(-)

-- 
2.15.1

bug#30144: [PATCH 1/1] doc: Document (ice-9 match) macros.

[Arun Isaac]

* doc/ref/match.texi: Document match-lambda, match-lambda*, match-let,
  match-let* and match-letrec.
---
 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 12e3814ae..0fc5105d1 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}.
+
+@deffn {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.
+
+@example
+(match-lambda clause1 clause2 @dots{})
+@equiv{}
+(lambda (arg) (match arg clause1 clause2 @dots{}))
+@end example
+@end deffn
+
+@example
+((match-lambda
+   (('hello (who))
+    who))
+ '(hello (world)))
+@result{} world
+@end example
+
+@deffn {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.
+
+@example
+(match-lambda* clause1 clause2 @dots{})
+@equiv{}
+(lambda args (match args clause1 clause2 @dots{}))
+@end example
+@end deffn
+
+@example
+((match-lambda*
+   (('hello (who))
+    who))
+ 'hello '(world))
+@result{} world
+@end example
+
+@deffn {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*}.
+
+@example
+(match-let (((x y) (list 1 2))
+            ((a b) (list 3 4)))
+  (list a b x y))
+@result{}
+(3 4 1 2)
+@end example
+@end deffn
+
+@deffn {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}.
+@end deffn
+
+@deffn {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.
+
+@example
+(match-let* (((x y) (list 1 2))
+             ((a b) (list x 4)))
+  (list a b x y))
+@equiv{}
+(match-let (((x y) (list 1 2)))
+  (match-let (((a b) (list x 4)))
+    (list a b x y)))
+@result{}
+(1 4 1 2)
+@end example
+@end deffn
+
+@deffn {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.
+@end deffn
 
 Guile also comes with a pattern matcher specifically tailored to SXML
 trees, @xref{sxml-match}.
-- 
2.15.1

bug#30144: [PATCH 1/1] doc: Document (ice-9 match) macros.

[Ludovic Courtès]

Hi Arun,

Arun Isaac <arunisaac@systemreboot.net> skribis:

> * doc/ref/match.texi: Document match-lambda, match-lambda*, match-let,
>   match-let* and match-letrec.

Finally applied.  Thanks for improving the manual!

Ludo’.