summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ref/api-compound.texi12
-rw-r--r--doc/ref/match.texi29
2 files changed, 35 insertions, 6 deletions
diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi
index 27dbcbf53..379ae808a 100644
--- a/doc/ref/api-compound.texi
+++ b/doc/ref/api-compound.texi
@@ -105,10 +105,14 @@ Return 1 when @var{x} is a pair; otherwise return 0.
The two parts of a pair are traditionally called @dfn{car} and
@dfn{cdr}. They can be retrieved with procedures of the same name
(@code{car} and @code{cdr}), and can be modified with the procedures
-@code{set-car!} and @code{set-cdr!}. Since a very common operation in
-Scheme programs is to access the car of a car of a pair, or the car of
-the cdr of a pair, etc., the procedures called @code{caar},
-@code{cadr} and so on are also predefined.
+@code{set-car!} and @code{set-cdr!}.
+
+Since a very common operation in Scheme programs is to access the car of
+a car of a pair, or the car of the cdr of a pair, etc., the procedures
+called @code{caar}, @code{cadr} and so on are also predefined. However,
+using these procedures is often detrimental to readability, and
+error-prone. Thus, accessing the contents of a list is usually better
+achieved using pattern matching techniques (@pxref{Pattern Matching}).
@rnindex car
@rnindex cdr
diff --git a/doc/ref/match.texi b/doc/ref/match.texi
index 40b5be899..12e3814ae 100644
--- a/doc/ref/match.texi
+++ b/doc/ref/match.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 2010, 2011 Free Software Foundation, Inc.
+@c Copyright (C) 2010, 2011, 2012 Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@c
@@ -44,7 +44,8 @@ because it is a two-element list whose first element is the symbol
@code{hello} and whose second element is a one-element list. Here
@var{who} is a pattern variable. @code{match}, the pattern matcher,
locally binds @var{who} to the value contained in this one-element
-list---i.e., the symbol @code{world}.
+list---i.e., the symbol @code{world}. An error would be raised if
+@var{l} did not match the pattern.
The same object can be matched against a simpler pattern:
@@ -61,6 +62,30 @@ Here pattern @code{(x y)} matches any two-element list, regardless of
the types of these elements. Pattern variables @var{x} and @var{y} are
bound to, respectively, the first and second element of @var{l}.
+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))
+@end example
+
+@noindent
+This expression returns the first element of each list within @var{lst}.
+For proper lists of proper lists, it is equivalent to @code{(map car
+lst)}. However, it performs additional checks to make sure that
+@var{lst} and the lists therein are proper lists, as prescribed by the
+pattern, raising an error if they are not.
+
+Compared to hand-written code, pattern matching noticeably improves
+clarity and conciseness---no need to resort to series of @code{car} and
+@code{cdr} calls when matching lists, for instance. It also improves
+robustness, by making sure the input @emph{completely} matches the
+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: