From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Mark H Weaver Newsgroups: gmane.lisp.guile.bugs Subject: bug#30144: [PATCH] doc: Document (ice-9 match) macros. Date: Fri, 16 Mar 2018 00:05:39 -0400 Message-ID: <87woyc4qcs.fsf@netris.org> References: <20180117122504.25583-1-arunisaac@systemreboot.net> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1521173112 28527 195.159.176.226 (16 Mar 2018 04:05:12 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 16 Mar 2018 04:05:12 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.3 (gnu/linux) Cc: 30144@debbugs.gnu.org To: Arun Isaac Original-X-From: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Fri Mar 16 05:05:08 2018 Return-path: Envelope-to: guile-bugs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ewgc8-0007IO-3N for guile-bugs@m.gmane.org; Fri, 16 Mar 2018 05:05:08 +0100 Original-Received: from localhost ([::1]:54910 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ewge9-0007J8-5H for guile-bugs@m.gmane.org; Fri, 16 Mar 2018 00:07:13 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:43793) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ewge2-0007Ic-QD for bug-guile@gnu.org; Fri, 16 Mar 2018 00:07:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ewgdy-00069P-PI for bug-guile@gnu.org; Fri, 16 Mar 2018 00:07:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:55960) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1ewgdy-00069G-LP for bug-guile@gnu.org; Fri, 16 Mar 2018 00:07:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ewgdy-0000eI-Av for bug-guile@gnu.org; Fri, 16 Mar 2018 00:07:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Mark H Weaver Original-Sender: "Debbugs-submit" Resent-CC: bug-guile@gnu.org Resent-Date: Fri, 16 Mar 2018 04:07:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 30144 X-GNU-PR-Package: guile X-GNU-PR-Keywords: patch Original-Received: via spool by 30144-submit@debbugs.gnu.org id=B30144.15211732052472 (code B ref 30144); Fri, 16 Mar 2018 04:07:02 +0000 Original-Received: (at 30144) by debbugs.gnu.org; 16 Mar 2018 04:06:45 +0000 Original-Received: from localhost ([127.0.0.1]:35624 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ewgdf-0000dm-0W for submit@debbugs.gnu.org; Fri, 16 Mar 2018 00:06:44 -0400 Original-Received: from world.peace.net ([50.252.239.5]:47852) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ewgdc-0000dY-QG for 30144@debbugs.gnu.org; Fri, 16 Mar 2018 00:06:41 -0400 Original-Received: from pool-72-93-30-18.bstnma.east.verizon.net ([72.93.30.18] helo=yeeloong) by world.peace.net with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1ewgdW-0003Kq-Rj; Fri, 16 Mar 2018 00:06:35 -0400 In-Reply-To: <20180117122504.25583-1-arunisaac@systemreboot.net> (Arun Isaac's message of "Wed, 17 Jan 2018 17:55:04 +0530") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-guile@gnu.org List-Id: "Bug reports for GUILE, GNU's Ubiquitous Extension Language" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Original-Sender: "bug-guile" Xref: news.gmane.org gmane.lisp.guile.bugs:9023 Archived-At: 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 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