From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Tomas Volf <~@wolfsden.cz> Newsgroups: gmane.lisp.guile.bugs Subject: bug#68506: [PATCH v3] doc: Extend documentation for (ice-9 match) Date: Tue, 16 Jan 2024 13:56:43 +0100 Message-ID: <20240116125722.14973-1-~@wolfsden.cz> Mime-Version: 1.0 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="7974"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Tomas Volf <~@wolfsden.cz> To: 68506@debbugs.gnu.org Original-X-From: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Tue Jan 16 13:59:31 2024 Return-path: Envelope-to: guile-bugs@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 1rPj2R-0001rx-FC for guile-bugs@m.gmane-mx.org; Tue, 16 Jan 2024 13:59:31 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rPj29-00061z-EA; Tue, 16 Jan 2024 07:59:13 -0500 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 1rPj1z-0005v9-2R for bug-guile@gnu.org; Tue, 16 Jan 2024 07:59:04 -0500 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rPj1y-0005iZ-7o for bug-guile@gnu.org; Tue, 16 Jan 2024 07:59:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rPj1y-0004pL-54 for bug-guile@gnu.org; Tue, 16 Jan 2024 07:59:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Tomas Volf <~@wolfsden.cz> Original-Sender: "Debbugs-submit" Resent-CC: bug-guile@gnu.org Resent-Date: Tue, 16 Jan 2024 12:59:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 68506 X-GNU-PR-Package: guile X-GNU-PR-Keywords: patch X-Debbugs-Original-To: bug-guile@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.170540991518514 (code B ref -1); Tue, 16 Jan 2024 12:59:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 16 Jan 2024 12:58:35 +0000 Original-Received: from localhost ([127.0.0.1]:48093 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rPj1W-0004oY-Tq for submit@debbugs.gnu.org; Tue, 16 Jan 2024 07:58:35 -0500 Original-Received: from lists.gnu.org ([2001:470:142::17]:34152) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <~@wolfsden.cz>) id 1rPj1U-0004oF-4e for submit@debbugs.gnu.org; Tue, 16 Jan 2024 07:58:32 -0500 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 <~@wolfsden.cz>) id 1rPj1O-0005cO-D2 for bug-guile@gnu.org; Tue, 16 Jan 2024 07:58:26 -0500 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 <~@wolfsden.cz>) id 1rPj1L-0005bj-Pa for bug-guile@gnu.org; Tue, 16 Jan 2024 07:58:26 -0500 Original-Received: by wolfsden.cz (Postfix, from userid 104) id 1C3CC2525EC; Tue, 16 Jan 2024 12:58:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=wolfsden.cz; s=mail; t=1705409901; bh=pIjEnBevyCKk8CgMYXcVGoh2po3FQAc2Sim2iuXGduw=; h=From:To:Cc:Subject:Date; b=SxvR48p4Fa+wbdPHs0JQ+YaehS1YhUpZU2iomLOa20/JFQxX2+RjotFlsbVWj7SW5 n1CJj92PpYZmKIMk7EaZCCVSYp6GxTSB6+pLs5JfnI/ardvvIIpuxDvxMO547w3E0K 47Oou9I5wYrSHzHB1hXomggGtQI0Ik2c8DhxateMA7DRtUHWVtx2233arJIe5pheKV KbtOqH/54F2ZgU9XNOI7FlbH28OkIxZekEzLBcfZjqlXInM0wHIK8m6sousePmbDDN gvigJ0FkqAZpM8Vo32lvAaFlE3H5nTV/aiqONg+EKGmCS6+qlDoKSm5dzMjdJ5K5PZ DJPMJ5bWg6oJBehFU7hZu397TL8SIeoe9aLkanmcUTAyWiKSTPTZ7JUrC5L1JE+a6f f9uOHobrVP1gp5gCylwtCm8/GaaOG5W/3RdkK7rVQEFNy6Oos5sCZ+dp5Xl1PWmBO1 X6ISIIpY0FnhApX12tvlozOp2MBRCXTgYWKlThX6Z55mzKwCFn6GEm0VV0bfJt/GIM 4PNQxpJAQcsdmxDSfu3TgaOm01oyMd+ZaPz9+cmlAP+I1byczM0Fag5BI0VeH7dBti 7JSo7ta6TxSlmxDgvJcajyRJua9TjbdCVGIDJjdyyIYgwz2rC56BA3yDuDO3GTGDGY HMoh1UqI2y2GnHcqMY+P0zzU= Original-Received: from localhost (unknown [81.17.16.72]) by wolfsden.cz (Postfix) with ESMTPSA id 946B3255CAC; Tue, 16 Jan 2024 12:58:20 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=wolfsden.cz; s=mail; t=1705409900; bh=pIjEnBevyCKk8CgMYXcVGoh2po3FQAc2Sim2iuXGduw=; h=From:To:Cc:Subject:Date; b=E2u+tAOaZ75ISDdRG3D3FgcMJq3XOMYXVdFnlQOtWGz4YoOyPIZaXB/fVZLnSpOP2 /NIe8Tau5IPnm9fFSmMJ8WLJJbttwEa0htjPUJygZK/DwWDXpHcsbPeptwSbStx/Gk 5pyU8E9sTMXNEyUPQwZZbe9c25bY9mI+K9/UukMl0bicWxPG7VwjnYGZV8Rz/lNwge obYryZkW7VuX3Q/+URHKIxUaDHtlhL2/36DMrf9v7DLHxbFNck2u00PNwW1/A7el94 OY2ckvZA+lxqMD0jFFB9R++WOTCIwQxxVv7hl0D1m6lmMSTEfSbLj7jIY0lXJB7gS8 RyccJLQ+mx9OMHN2zIWTOJPanVcuUPBs3LwvbZFbeMQp9fxJRiFJpsYtahueT5f5DM e/1xjS/GjKcVXGfuEebcI3j0hxc0GMBDLXuRT+iFNMDURYGl306JW5kZ0O2214YQbh w9xZ+nf3ZOreUpK8xiU/85s3LpZ2V58JNB6NS+uBEmnY6f+Hcj014lWYDYcgHPVMAN csKPcGhNsKgPWy1q8K1ZlisZ9LHsctoUx00KzL/dKiP9qDnUPYxdjGn9BHa+09D94J 7TWKj2IAKS57fznVNTCEBo0cz5gsirYTgQcZJ16s+PI5JM/2MMj5e5fCFTo6pr3kWc tLZpmOMqSOMZ+E1Q+kXchAjs= X-Mailer: git-send-email 2.41.0 Received-SPF: pass client-ip=37.205.8.62; envelope-from=~@wolfsden.cz; helo=wolfsden.cz X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list 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-mx.org@gnu.org Original-Sender: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.lisp.guile.bugs:10753 Archived-At: Extend the documentation for (ice-9 match) module with explanations 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. --- v2: * drop myself from THANKS file, someone else can thank me if they want to * remove most of unnecessary lets * spelling and wording fixes * add new paragraph describing (and ...) v3: Attempt to resolve feedback regarding the let usage: > Whether you choose to to inline it or not, please do it consistently. I removed all of them except two. The very first one, since in this case I believe it leads to the comments being more readable: (let ((l '(hello (world)))) (match l ;; <- the input object (('hello (who)) ;; <- the pattern who))) ;; <- the expression evaluated upon matching It also creates a nice contrast with the second example, which now also demonstrates that you do not have to use the let, and the object can be inline. Second case is the "more complex example", where I believe the let again leads to significantly more readable code (keeping alice and bob together) to outweigh the perceived inconsistency. If requested, I can of course nuke these two usages as well. Previous discussion happened on the mailing list. doc/ref/match.texi | 90 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 86 insertions(+), 4 deletions(-) diff --git a/doc/ref/match.texi b/doc/ref/match.texi index f5ea43118..774fc856e 100644 --- a/doc/ref/match.texi +++ b/doc/ref/match.texi @@ -50,10 +50,9 @@ list---i.e., the symbol @code{world}. An error would be raised if The same object can be matched against a simpler pattern: @example -(let ((l '(hello (world)))) - (match l - ((x y) - (values x y)))) +(match '(hello (world)) + ((x y) + (values x y))) @result{} hello @result{} (world) @end example @@ -181,6 +180,89 @@ 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, the pattern @code{string} binds the +value to the identifier @code{string} and the pattern @code{"string"} +matches if the value is @code{"string"}. An example demonstrating this +(by using very bad naming): + +@example +(match "foo" + (number number)) +@result{} "foo" +@end example + +The field operator (@code{(= field pat)}) has no relation to the fields +of 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 +(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 records. Patterns are matched against the slots in order, +not all have to be present, and there is no way to skip a slot. An +example demonstrating the usage: + +@example +(define-record-type + (make-foo bar baz zab) + foo? + (bar foo-bar) + (baz foo-baz) + (zab foo-zab)) + +(match (make-foo 1 '2 "three") + ;; 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 as if in the @code{(and ...)}. If, for example, you want +to check whether something is a symbol and at the same time bind the +value to a variable, it could look like this: + +@example +(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 + +The @code{(and ...)} is of course useful as well, especially if no +predicate is required. While you could use @code{(const #t)} as the +predicate, using @code{(and ...)} is better. For example, capturing an +object iff it is a list of at least two items can be done like this: + +@example +(match '(foo baz bar) + ((and (a b ...) lst) + lst)) +@result{} (foo baz bar) +@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