doc: Strengthen the case for pattern matching.

* doc/ref/api-compound.texi (Pairs): Warn against `cadr' & co., and add
  a link to "Pattern Matching".
* doc/ref/match.texi (Pattern Matching): Add example with nested lists.
  Add paragraph comparing `match' expressions and hand-written code.

diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi
index 27dbcbf..379ae80 100644 (file)
--- 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 40b5be8..12e3814 100644 (file)
--- 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: