From 44cd55752aad2a69e1583a2cb37c3b98c5c44ad3 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Ludovic=20Court=C3=A8s?= Date: Sat, 17 Nov 2012 16:07:00 +0100 Subject: [PATCH] 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. --- doc/ref/api-compound.texi | 12 ++++++++---- doc/ref/match.texi | 29 +++++++++++++++++++++++++++-- 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: -- 2.20.1