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

[Mark H Weaver <mhw@netris.org>]

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