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: [PATCH] doc: Extend documentation for (ice-9 match) Date: Wed, 6 Sep 2023 16:06:38 +0200 Message-ID: <20230906142222.11673-1-wolf@wolfsden.cz> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="746"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Tomas Volf To: guile-devel@gnu.org Original-X-From: guile-devel-bounces+guile-devel=m.gmane-mx.org@gnu.org Wed Sep 06 17:05: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 1qdu63-000AVW-UM for guile-devel@m.gmane-mx.org; Wed, 06 Sep 2023 17:05:36 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qdu5k-00025Q-7c; Wed, 06 Sep 2023 11:05:16 -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 1qdtQZ-0005XA-B5 for guile-devel@gnu.org; Wed, 06 Sep 2023 10:22:43 -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 1qdtQV-0003Iz-Qv for guile-devel@gnu.org; Wed, 06 Sep 2023 10:22:43 -0400 Original-Received: by wolfsden.cz (Postfix, from userid 104) id 6976127EBDC; Wed, 6 Sep 2023 14:22:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=wolfsden.cz; s=mail; t=1694010156; bh=n1GJSZDoRpvdUYcgFViUAriX2YkvVSLFSBawSYxX234=; h=From:To:Cc:Subject:Date; b=bFCRDFxumt1Xg/Cc4M1OnAAsfI7ikUxrTN0KSabEw+Lx4pgvy2Vv1yinBTH0r1NFN p/Mxf/1vq9PWhEIO/gtmfZYPDcb51UY9afNA9V2j8TyO3G1zV+8/Mh88NHmEH7cARo r9vy5A1tnAb/F3z43EAooRpOyMbJz5mEaAjbyGOFBRjnidSlhnQJBekt5jkuaNtnMf HXWEn7BxKvB/ZdTyL4Amc3iDo5EV2dZrDQpl/b+TRJF3rS1ywpVoFoQYKJtV7WUPn/ kfe9sekGk1/S/5aQso3Y2C7LorDHXpuP2KwM6gdlWKmA3MYdDVmcEcGz1mJY8X7T7e qRnSGpd+P3aKEN49w6fbnO6GsBZ44zz/y7GEDot8U2D60cBfYr2ulCDW0EUqvR2+vf HdtYdBzESg099NlWvcuecU7Vh/mAf7dlI+Tq0/BSrfWCb2GX4DewZLJna9xGkPWB0z 3SUPYHEA12lylIGo1tRLT0x7eprEZ0dVaRbWs7yiUvGeEr6icQZNp6gr6knY1O6Gnz ODGxDCBX25ewoaS2cvIHsHdZhkFqiYb0jTGrV6zzgsWyZ7Z42q3Qstd9obGduJCIYM Y2bM1lJmTIHyVT/WRfXd9MHafwNcUYme1LVzffaF/yhwkpIu0tZNZCkwpsEAZrO7Zv MWbnLb3cYsHHVcZnke4ZuhHE= Original-Received: from localhost (unknown [193.32.127.135]) by wolfsden.cz (Postfix) with ESMTPSA id CAC4127F6CC; Wed, 6 Sep 2023 14:22:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=wolfsden.cz; s=mail; t=1694010155; bh=n1GJSZDoRpvdUYcgFViUAriX2YkvVSLFSBawSYxX234=; h=From:To:Cc:Subject:Date; b=Q/pCwasmV6bpwOlmcCONcETdnQhA814fHJaC438RU9cmZgxhCRlsitcntLAle6Wla 4AdOqWU7vqlLqhD/NjiCSRROZXoJSwiXnerTNoEn9raWYTq/lAmvGZ45xv3YRjwCUw K7VRs0gM6If1gSyL+lvQ1T+xYO85jMLJXmSBkIjJMF02XeAdStmjMdAneZJMY+kdSS hgOx+hKc7eYgS/XuJ5qLhck3UOQ12mRgHxFkLVVN+w8eYDUSdw2T+XkQVDTjKNnIzh YL4HxMzJtL8vTva4IuJE3tra2YI5vrnSwcDz3xo5Llh/TT6F1xaoWXwflRW+yLv0MX sQf6P1zOJ2KH8NwLvv5vyEoMH2FGgnFNVmqwB1qu8TebfKvq7cwO4ue2TDwJVku0+q VqJSQqY8AL/h0ycFGt7efmYgEp0QdOrzrpEjowK86rGb2HHD7oQrki8IUkAbeXNsus wnx/pR0Zi5H6NARpH3lAlMHnY9vGwFCGi6EQJbtDIwMlOdmR9Bi8lUag2ZUpJfaiic 4jeyh2wc+9NtD7Tu3QsgLnSilisOkx9oVLbZARrlHZ2798tGLnm3yMyxhUgDhPzncx AhHnWgmfiWhdm0Gm7ZOQ8IU/k5fvH3sd8LExHZ2REW6E2oWMuLExoyNfNRKtL5okyv uf/7SCmkZIR9CClDFES6xFeE= Original-Received: from localhost (localhost [local]) by localhost (OpenSMTPD) with ESMTPA id 8af3ba35; Wed, 6 Sep 2023 14:22:35 +0000 (UTC) X-Mailer: git-send-email 2.41.0 Received-SPF: none client-ip=37.205.8.62; envelope-from=ws@wolfsnet.cz; helo=wolfsden.cz X-Spam_score_int: -17 X-Spam_score: -1.8 X-Spam_bar: - X-Spam_report: (-1.8 / 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.249, SPF_HELO_PASS=-0.001, SPF_NONE=0.001, UNPARSEABLE_RELAY=0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-Mailman-Approved-At: Wed, 06 Sep 2023 11:05:14 -0400 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:21944 Archived-At: 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? 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. 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öran 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"}. Example demonstrating this (by using very bad +naming): + +@example +(let () + (match "foo" + (number number))) +@result{} "foo" +@end example + +The field operator (@code{(= field pat)}) has no relation to the fields +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: + +@example +(let () + (match '(1 2) + ((= 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: + +@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 + +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 need +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 ...)}. 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: + +@example +(let () + (match '(delete . some-id) + (('delete . (? symbol? id)) + ;; We now could, for example, use the id to delete from some alist. + id))) +@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 the +large comment at the top of the @code{module/ice-9/match.upstream.scm} +file in your guile distribution. + Here is a more complex example: @example -- 2.41.0