---
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
