From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Blake Shaw Newsgroups: gmane.lisp.guile.devel Subject: [PATCH v1 6/6] docs/match:style reviewing with pdf, adding newlines Date: Fri, 27 Jan 2023 01:58:01 +0700 Message-ID: <20230126185801.19064-6-blake@reproduciblemedia.com> References: <20230126185801.19064-1-blake@reproduciblemedia.com> Mime-Version: 1.0 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="23894"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Blake Shaw To: guile-devel@gnu.org Original-X-From: guile-devel-bounces+guile-devel=m.gmane-mx.org@gnu.org Fri Jan 27 02:44:25 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 1pLDmx-00061E-E0 for guile-devel@m.gmane-mx.org; Fri, 27 Jan 2023 02:44:23 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pLDmN-0004Wf-UR; Thu, 26 Jan 2023 20:43:47 -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 1pL7SE-0008Sy-TV for guile-devel@gnu.org; Thu, 26 Jan 2023 13:58:34 -0500 Original-Received: from out2.migadu.com ([2001:41d0:2:aacc::]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pL7SC-0007c7-Ve for guile-devel@gnu.org; Thu, 26 Jan 2023 13:58:34 -0500 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=reproduciblemedia.com; s=key1; t=1674759511; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=pnui9aDgKaS7Onjxit2EsA3VfqwyjtX6AUgAYvEcvuE=; b=qJF44VnLpypRo9EY993HwZ2pfrj1/cZgA7iFpjV5KF9ZXB/81KEBvKejKBVG4BmZfNfn4l mphBztWsptR/Vge0vG6zo22mfOV46w6TW7fgdlttW2GzxcdZjJhpw0Oazvla7DAIaH4hMA Mmpjn0COAQF0M3cv29IbbNtEcrvDrMY= In-Reply-To: <20230126185801.19064-1-blake@reproduciblemedia.com> X-Migadu-Flow: FLOW_OUT Received-SPF: pass client-ip=2001:41d0:2:aacc::; envelope-from=blake@reproduciblemedia.com; helo=out2.migadu.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 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, RCVD_IN_DNSWL_LOW=-0.7, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Mailman-Approved-At: Thu, 26 Jan 2023 20:43:44 -0500 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:21642 Archived-At: --- doc/ref/match.texi | 78 ++++++++++++++++++++++++++++------------------ 1 file changed, 47 insertions(+), 31 deletions(-) diff --git a/doc/ref/match.texi b/doc/ref/match.texi index 5512103c4..38745e173 100644 --- a/doc/ref/match.texi +++ b/doc/ref/match.texi @@ -19,15 +19,15 @@ @cindex pattern matching @cindex (ice-9 match) -The @code{(ice-9 match)} module provides a @dfn{pattern matcher}, +@* The @code{(ice-9 match)} module provides a @dfn{pattern matcher}, written by Alex Shinn, and compatible with Andrew K. Wright's pattern matcher found in many Scheme implementations. -A pattern matcher does precisely what the name implies: it matches -some arbitrary pattern, and returns some result accordingly. - -@lisp +@* @noindent A pattern matcher does precisely what the name implies: it +matches some arbitrary pattern, and returns some result accordingly. +@* +@example (define (english-base-ten->number name) (match name ('zero 0) @@ -40,40 +40,43 @@ some arbitrary pattern, and returns some result accordingly. ('seven 7) ('eight 8) ('nine 9))) - -@end lisp +@end example -@lisp +@* +@example (english-base-ten->number 'six) - @result{} 6 -@end lisp +@end example -@lisp +@example (apply + (map english-base-ten->number '(one two three four))) @result{} 10 -@end lisp +@end example -@cindex pattern variable -Pattern matchers may contain @dfn{pattern variables}, local bindings -to all elements that match a pattern. +@* +@page +@cindex pattern variable +@noindent Pattern matchers may contain @dfn{pattern variables}, +local bindings to all elements that match a pattern. -@example -(let re ((ns '(one two three four ten)) - (total 0)) +@example + +(let re ([ns '(one two three four 9)] [total 0]) (match ns - ((e) (+ total (english-base-ten->number e))) - ((e . es) - (re es (+ total (english-base-ten->number e)))))) -@result{} 20 + [(e) (+ total (english-base-ten->number e))] + [(e . es) + (re es (+ total (english-base-ten->number e)))])) + +@result{} 19 @end example -In this example, the list @var{ns} matches the pattern +@* +@noindent In this example, the list @var{ns} matches the pattern @code{(e . es)}, where the pattern variable @var{e} corresponds -to the `car` of @var{ns} and the pattern variable @var{es} -corresponds to the `cdr` of @var{ns}. +to the metaphoical "car" of @var{ns} and the pattern variable @var{es} +corresponds to the "cdr" of @var{ns}. -A tail call @code{re} is then initiated and we `cdr` down the +A tail call @code{re} is then initiated and we "cdr" down the list by recurring on the tail @var{es}, applying our matcher @code{english-base-ten->number} to each element of @var{ns} until only a single element @code{(e)} remains, causing the @var{total} @@ -82,15 +85,16 @@ to be computed. In modern Scheme programming it is common to use of @code{cond}, @code{car} and @code{cdr}, so it's important to understand how these idioms translate. +@* Patterns can be composed and nested. For instance, @code{...} (ellipsis) means that the previous pattern may be matched zero or more times in a list: @example + (match lst - (((heads tails ...) ...) - heads)) -@result{} + (((heads tails ...) ...) heads)) + @end example @noindent @@ -104,25 +108,31 @@ A pattern matcher can match an object against several patterns and extract the elements that make it up. @example + (let ((m '((l1 . r1) (l2 . r2) (l3 . r3)))) (match m (((left . right) ...) (list left right)))) + @result{} ((l1 l2 l3) (r1 r2 r3)) @end example @example + (let ((m '((1 . (a . b)) (2 . (c . d)) (3 . (e . f))))) (match m (((key . (left . right)) ...) (fold-right acons '() key right )))) + @result{} ((1 . b) (2 . d) (3 . f)) @end example @example + (match '(((a b c) e f g) 1 2 3) ((((head ...) . rest) tails ...) (acons tails head rest ))) + @result {} (((1 2 3) a b c) e f g) @end example @@ -130,6 +140,7 @@ Patterns can represent any Scheme object: lists, strings, symbols, records, etc. @example + (let re ((m #(a "b" c "d" e "f" g))) (match m ((or (e) #(e)) e) @@ -137,7 +148,9 @@ records, etc. (e1 e2 es ...)) (cons (cons e1 e2) (re es))))) + @result{} ((a . "b") (c . "d") (e . "f") . g) + @end example When a matching pattern is found, an expression associated with the @@ -145,12 +158,15 @@ pattern is evaluated, optionally with all pattern variables bound to the corresponding elements of the object. @example + (let re ((m '(a b c d e f g h i))) (match m ((e) e) ((e1 e2 es ...) (acons e1 e2 (re es))))) + @result{} ((a . b) (c . d) (e . f) (g . h) . i) + @end example Compared to hand-written code, pattern matching noticeably improves @@ -161,7 +177,7 @@ pattern---conversely, hand-written code often trades robustness for conciseness. And of course, @code{match} is a macro, and the code it expands to is just as efficient as equivalent hand-written code. -The pattern matcher is defined as follows: +@noindent @* We define @emph{match} as follows. @* @deffn {Scheme Syntax} match exp clause1 clause2 @dots{} Match object @var{exp} against the patterns in @var{clause1} @@ -188,7 +204,7 @@ arbitrary Scheme expression, possibly referring to pattern variables of @c @c clause ::= (pat body) | (pat => exp) -The syntax and interpretation of patterns is as follows: +@noindent @* The syntax and interpretation of patterns is as follows: @* @verbatim patterns: matches: -- 2.39.1