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

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

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