From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Tomas Volf Newsgroups: gmane.lisp.guile.devel Subject: Re: [PATCH] doc: Extend documentation for (ice-9 match) Date: Sun, 15 Oct 2023 19:40:01 +0200 Message-ID: References: <20230906142222.11673-1-wolf@wolfsden.cz> <61413d94-833e-ac1a-fa86-556c6b88d9d9@telenet.be> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="uWnynsAIzlO/SJM2" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="15555"; mail-complaints-to="usenet@ciao.gmane.io" Cc: guile-devel@gnu.org To: Maxime Devos Original-X-From: guile-devel-bounces+guile-devel=m.gmane-mx.org@gnu.org Sun Oct 15 19:40:36 2023 Return-path: Envelope-to: guile-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1qs56R-0003qQ-S3 for guile-devel@m.gmane-mx.org; Sun, 15 Oct 2023 19:40:36 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qs565-00050c-3I; Sun, 15 Oct 2023 13:40:13 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qs561-0004yq-Pe for guile-devel@gnu.org; Sun, 15 Oct 2023 13:40:09 -0400 Original-Received: from wolfsden.cz ([37.205.8.62]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qs55z-00009d-5D for guile-devel@gnu.org; Sun, 15 Oct 2023 13:40:09 -0400 Original-Received: by wolfsden.cz (Postfix, from userid 104) id 9CF6D26D7A4; Sun, 15 Oct 2023 17:40:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=wolfsden.cz; s=mail; t=1697391603; bh=LoJFNL4f5DYxTY/nE2v9d4+6lhxPGCH5fdPqq3rlz60=; h=Date:From:To:Cc:Subject:References:In-Reply-To; b=OLmEalKafGfdg46Js/R65vtuTnFcGPlfj5uEmCOMSw/Vss3veYZss139IwJL9H9MM hwRI2qyvtQ3w9AejWmbESrFmdom3Qq7Dc3mU3x17D0335nLQ+l27PJ0EEFEzAifZxW F+X0DpGCMgox6S2GRmNFbHVRkoT4ET/H6PPghbik4k+6xqXb6f3FY7rSLo6uTNwaRn 9I1XTjDVGZBzvf3pj4QUpNtMBzk2uurhlf4z+ncfr8PoRC6BVyU6She8pOhFEv2L2m xdpW2GZqogkayYK7A9ARj64N8Ttv12c9dIMELya3pwyZIlJG9A05dHPCTVXCDSBxIE AULRW2qwptUZKVAJ5BP8dbLVqNXm8CdOCvgVrOGmFOsglG8gJ5sX/JpsxNqIcRHU5M IUliN2MMORDKB/4cosDyaQSvyEFfVHb4EeOUv61YGGXy5k2gCrF6gthqhH9BiJQlkc QNi0+BFzJFJBAmqQo2na13svPihbvlbvcisFZqLmnSBVbveCkfrEXpNuxltOT+z8EE Ljoz0gTP1LRlSBxoVUYTry3wNT7QMwEVN+dQHHIZPxggsfYu0HaEi4xptSa3zdGaXR N7UpJxsKVE0nS7483WAtwAizc7Bmry9IwnQXyZMT/ty2FIqMNjzZp1kfDn47YyTT5a SStSurKO39+7z3ihWCTVb/q4= Original-Received: from localhost (unknown [146.70.134.168]) by wolfsden.cz (Postfix) with ESMTPSA id 842CD26C9B3; Sun, 15 Oct 2023 17:40:02 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=wolfsden.cz; s=mail; t=1697391602; bh=LoJFNL4f5DYxTY/nE2v9d4+6lhxPGCH5fdPqq3rlz60=; h=Date:From:To:Cc:Subject:References:In-Reply-To; b=miotN8FD0mtgingplXlOBXd53oXdV5bYjAN8iap8FcxQFD9ErNnWpqHQDh+a1/ACs tpYDSyXwxNo5mIl42WkPWsRGyPuKSAQJolNPm+poK+/2gfCnBXboUv3sY/CM2xqp3i kLbZOk43MrQYyIyziRju9o8aqJ3Z2D3NnuBXgj/8xlkPKbjSb5OfGVY7vx1lzV32bP FOs/XuxrizhujdpfFgvWT5RHw3x9ZZCnyIl3Gl9aHvxVtrWYfLpG9u0OcsvVyI8Jiv 8YxkIOkCoMDGS/ZVrmboCYqxJq353GP2XLXq+Wv/i20jNxoBqloMBnJb5F46hESIe6 QF2u02qTvMSX1pbJ1xxCdGUnJH/CO9CIvd66TnLUeVVViLGfNAaWO1TcvwUxDPA7D+ GAKyUOBDQxzxuwUB2M5fD9TCW7XPdfRzC1TuhRdZElmtSXHrv+E0iu1oOjhNdmQIRn X1pap5/YrZT92sPN7o+xJ8d8gSQ9mXw3X77AZVPmdXhwFup5E0mrGKpk0KzzTAkmxn TGFHtTLf4eWhRh9i3pFF2ShD9KPVLgS5DDb+FnCWZud3rAaDpOicBrW4U/cT1cWpeI ibuVkjrVGt51STgQthA9Q4i/S5agLRpf57QACJFX+Up4yzY8MZPIELzYySg1D/FRS9 RrpXrFfeMr9+vv5SUYpqim4c= Original-Received: from localhost (localhost [local]) by localhost (OpenSMTPD) with ESMTPA id 205d8a98; Sun, 15 Oct 2023 17:40:01 +0000 (UTC) Content-Disposition: inline In-Reply-To: <61413d94-833e-ac1a-fa86-556c6b88d9d9@telenet.be> Received-SPF: none client-ip=37.205.8.62; envelope-from=ws@wolfsnet.cz; helo=wolfsden.cz X-Spam_score_int: -16 X-Spam_score: -1.7 X-Spam_bar: - X-Spam_report: (-1.7 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, HEADER_FROM_DIFFERENT_DOMAINS=0.25, SPF_HELO_PASS=-0.001, SPF_NONE=0.001, UNPARSEABLE_RELAY=0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane-mx.org@gnu.org Original-Sender: guile-devel-bounces+guile-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.lisp.guile.devel:22027 Archived-At: --uWnynsAIzlO/SJM2 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Hello, thanks for the review! My reactions are below. On 2023-09-20 00:57:33 +0200, Maxime Devos wrote: >=20 >=20 > Op 06-09-2023 om 16:06 schreef Tomas Volf: > > Extend the documentation for (ice-9 match) module with explanation of > > some of the patterns and also provide more examples for them. That > > should make it more useful for people trying to use the module for the > > first time just based on the documentation. > > > > * doc/ref/match.texi (Pattern Matching): Explain some patterns and > > provide more examples > > --- > > When I tried to use (ice-9 match) for the first time, I was not able to, > > except the most basic usage. The documentation was not very helful, so > > I went to the IRC. I got help, but I was also asked to try to > > contribute to the docs with examples that would have helped me in the > > first place. > > > > I think even more additions would be useful, but I still do not > > understand the pattern matching fully, so they are not a part of this > > patch. Examples would be: How and when I should use quasi-patterns? > > What does `ooo' stand for? Does `box' refer to SRFI-111 or something > > else? > Note: there is a previous patch for improving (ice-9 match) documentation > named =E2=80=98[PATCH v3] docs/match: pattern matcher example makeover=E2= =80=99, though IIRC > it needed some changes. Maybe you can adapt some things from it. As long > as it doesn't descend in fake gatekeeping accusations again, it would be > nice if it wasn't for nothing. I managed to find it, and there even seems to be a v4. I sadly do not have= the time to work through it right now, and I do not want to make any promises regarding if/when I will have it. So for now I incorporated your feedback = and will sent it as v v2. >=20 > Smaller incremental improvements like this would also be nice, though. >=20 > > > > I was following the HACKING file, so I added myself into the THANKS > > file, I am not sure if I was supposed to for this relatively trivial > > change. > I think you aren't supposed to (whether it is trivial or not). Instead, I > think that others are supposed to add you to THANKS, otherwise you would = be > thanking yourself. That is, however, a personal disagreement I have with > HACKING. >=20 > I think that triviality or not is irrelevant; time spent on evaluating > whether something is trivial or not is better spent on doing more > contributors. Besides, THANKS says =E2=80=98Contributors since the last = release=E2=80=99, > not =E2=80=98Contributors of non-trivial changes since the last release= =E2=80=99. Makes sense, removed. >=20 > > > > THANKS | 1 + > > doc/ref/match.texi | 75 ++++++++++++++++++++++++++++++++++++++++++++++ > > 2 files changed, 76 insertions(+) > > > > diff --git a/THANKS b/THANKS > > index aa4877e95..bb07cda83 100644 > > --- a/THANKS > > +++ b/THANKS > > @@ -38,6 +38,7 @@ Contributors since the last release: > > BT Templeton > > David Thompson > > Bake Timmons > > + Tomas Volf > > Mark H Weaver > > G=C3=B6ran Weinholt > > Ralf Wildenhues > > diff --git a/doc/ref/match.texi b/doc/ref/match.texi > > index f5ea43118..b5a0147fa 100644 > > --- a/doc/ref/match.texi > > +++ b/doc/ref/match.texi > > @@ -181,6 +181,81 @@ The names @code{quote}, @code{quasiquote}, > @code{unquote}, > > @code{or}, @code{not}, @code{set!}, @code{get!}, @code{...}, and > > @code{___} cannot be used as pattern variables. > > > > +@code{string}, @code{number}, and others refer to literal strings, > > +numbers, and others. Therefore pattern @code{string} binds the value = to > > +identifier @code{string}, pattern @code{"string"} matches if the value > > +is @code{"string"}. > It would do pause after =E2=80=98therefore=E2=80=99, not =E2=80=98before= =E2=80=99. Might just be a personal > thing, though. Also, something about joining two sentences with a comma > instead of =E2=80=98and=E2=80=99 bothers me. Also=C2=B2, I find it diffi= cult to tell whether > adding =E2=80=98the=E2=80=99 before =E2=80=98pattern=E2=80=99 would be be= tter or worse. What do you think? Maybe. I am not that skilled with articles, so I defer to you here. It at least does not sound worse to me. >=20 > =E2=80=98Therefore, pattern @code{string} binds the value to >=20 > > Therefore the pattern @code{string} binds the value to > > the identifier @code{string} and the pattern [...]. >=20 > > Example demonstrating this (by using very bad > > +naming): > Maybe =E2=80=98An example=E2=80=99? But again, dunno. Here as well. >=20 > > + > > +@example > > +(let () > > + (match "foo" > > + (number number))) > > +@result{} "foo" > > +@end example > > + > > +The field operator (@code{(=3D field pat)}) has no relation to the fie= lds > > +of SRFI-9 records. The @code{field} should be an expression evaluating > > +to a procedure taking a single argument, and @code{pat} is matched > > +against the return value. Simple example: >=20 > s/SRFI-9 records/records >=20 > There's other methods for defining records to that it has no relation too! Ah, good point. >=20 > > +@example > > +(let () > > + (match '(1 2) > > + ((=3D cadr x) > > + x))) > > +@result{} 2 > > +@end example > > + > > +The record operator(@code{($ record-name pat_1 ... pat_n)}) can be used > > +for matching SRFI-9 and SRFI-99 records. Patterns are matched against > > +the slots in order, not all have to be present, and there is no way to > > +skip a slot. Example demonstrating the usage: > Probably also RNRS records, structs and (ice-9 records), though I haven't > tested that. >=20 > Basically, all record types except perhaps GOOPS. >=20 > Though perhaps no slot order is guaranteed for RNRS and GOOPS, even if it > happens to work currently? Dunno. >=20 > I don't think it's _supposed_ to work with opaque RNRS records, but that's > probably not yet implemented. I decided to just leave out the type and went with "for matching records." There seems to be many kinds, and I have no idea with which it does work. = Being less precise (no type) is probably better than being wrong. >=20 > > +@example > > +(define-record-type > > + (make-foo bar baz zab) > > + foo? > > + (bar foo-bar) > > + (baz foo-baz) > > + (zab foo-zab)) > > + > > +(let ((obj (make-foo 1 '2 "three"))) > > + (match obj > > + ;; Make sure obj is a instance, with bar slot being a number > > + ;; and zab slot being a string. We do not care about baz slot, > > + ;; therefore we use _ to match anything. > > + (($ (? number?) _ (? string?)) > > + "ok"))) > > +@result{} "ok" > > +@end example > You could inline 'obj' here -- unless there is a bug, match doesn't evalu= ate > its =E2=80=98argument=E2=80=99 multiple times. I am not aware of any bugs here, but I wanted to adhere to the style of the original examples: (let ((l '(hello (world)))) (match l ;; <- the input object (('hello (who)) ;; <- the pattern who))) ;; <- the expression evaluated upon matching I can inline it if you would prefer. >=20 > > + > > +If you need to ensure that a value is of a specific record type and at > > +the same time bind it to a variable, the record operator will not be > > +enough by itself, since you can only capture the fields. You would ne= ed > > +to combine it with other patterns, for example @code{(? foo? obj)}. > > + > > +When you need to apply multiple patterns, or a check and a pattern, you > > +can use (@code{(? predicate pat_1 ... pat_n)}) for that. The patterns > > +are evaluated is if in the @code{(and ...)}. > That last sentence needs a grammar check. Right, typo corrected. >=20 > > If, for example, you want > > +to check something is a symbol and at the same time bind the value to a > > +variable, it could look like this: > s/something/if something >=20 > or >=20 > s/something/whether something >=20 > > + > > +@example > > +(let () > > + (match '(delete . some-id) > > + (('delete . (? symbol? id)) > > + ;; We now could, for example, use the id to delete from some alis= t. > > + id))) > Slightly misleading: while in this particular example you don't need it, = you > can also use =E2=80=98and=E2=80=99 for that. Especially useful if there = is no predicate in > play/if the predicate would be (const #true). I think I understand what you mean, but I was not sure how to reword it to = make it less misleading. So I instead added one more paragraph exonerating the = (and =2E..). >=20 > Whereas the previous 'let' might just be a matter of personal style, this > let serves no purpose at all. I would eliminate this distraction to > eliminate the tiny risk that someone might be confused by it. The "a more complex example" uses the (let () ...) form, so I just did the = same. Now I realize it is used to scope the (define-record-type). I removed the = let =66rom here and from few other places where it was not required. >=20 > > +@result{} some-id > > +@end example > > + > > +@c FIXME: Remove this remark once everything is clearly described and > > +@c consulting the comment is no longer necessary. > > +If you are unclear about how something works, you can try consulting t= he > > +large comment at the top of the @code{module/ice-9/match.upstream.scm} > > +file in your guile distribution. > s/guile/Guile. >=20 > That's not supposed to be there, but given the current (lack of) (ice-9 > match) documentation, I suppose it's reasonable. >=20 > Best regards, > Maxime. Have a nice day, Tomas --=20 There are only two hard things in Computer Science: cache invalidation, naming things and off-by-one errors. --uWnynsAIzlO/SJM2 Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEEt4NJs4wUfTYpiGikL7/ufbZ/wakFAmUsI/EACgkQL7/ufbZ/ wam15A//eO9kzOJUPst/l0ucrwIcJ0UQbuH4CSsDcUhg1SCUwZyHNz4zvFStBglw u5W6KnaPHVH8BtA2Fsd3THRW2k0gHByUB7eBIaIgbRHQxI2jEBQvn4LA/LuYZZ2O Vgsjd72cxiBkMS0EBW+Gm2//4bIOtwdV4dmAVvvZ9BBXe7Ll0QwCkN7NdX7dUp// LLfmgvhKGOJFKIuy6nwvYbRMnzq+AtYdgr3U8BrInzMoUl/rQgM42SkrlXwxwDZX VXpJQ9F9X0cewUy+Ti7VZyZX2bBqKYU9z3AdI2h5lN3On387NRrfIkbQinN3DCLq ZPsClUFETct6hBbYqQXzWfgTpvBtSkNpybM2xADd1wuy4582lB96FCBGy80Nk+Rl gVkCHvP3BuFbU7Y5iNB6RTVL/U6EZDS3JpcHCJTydDjLzXbmWe3EH6a1ftJVZd/9 5p74vofH6XDS/JhFZVnTsdyW2o6H/KU21zFA5FuEN36NlsrOUUAF1VZJuXDsnBtr Qt4Zw4wjomsy2uJOvZbmJi9+dUCxPMJQEoijnv8yCklwzZgnmh8Gmcg2ilmMP4wa gIi3bl1ul8lrjDz3Oy4XycAn9d6Ivpu3zOl9mlm0SFvMYtuPstu6W+UaqwTNqqFg h8xDFsIGyItJH/qpaloRlOPfgj7YHLhf9BWGCWStYQ+oXge9Hbw= =1vj6 -----END PGP SIGNATURE----- --uWnynsAIzlO/SJM2--