[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] emacs-25 d7a93ef: Minor improvements to 'pcase' documentat
From: |
Eli Zaretskii |
Subject: |
[Emacs-diffs] emacs-25 d7a93ef: Minor improvements to 'pcase' documentation |
Date: |
Fri, 29 Jan 2016 09:42:42 +0000 |
branch: emacs-25
commit d7a93efd0e512ce145ee696561054f8065fe03ab
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>
Minor improvements to 'pcase' documentation
* doc/lispref/control.texi (Pattern matching case statement):
Improve the documentation of 'pcase' per comments. See two
discussion threads on address@hidden for the details:
http://lists.gnu.org/archive/html/emacs-devel/2016-01/msg01335.html
http://lists.gnu.org/archive/html/emacs-devel/2016-01/msg01336.html.
---
doc/lispref/control.texi | 55 +++++++++++++++++++++++++++++----------------
1 files changed, 35 insertions(+), 20 deletions(-)
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 6fa802d..3f48c45 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -304,15 +304,15 @@ is useful to select alternatives based on more general
conditions that
distinguish between broad classes of values. The @code{pcase} macro
allows you to choose between alternatives based on matching the value
of an expression against a series of patterns. A pattern can be a
-literal value (comparison to literal values is what @code{cond} does),
-or it can be a more general description of the expected structure of
-the expression's value.
+literal value (for comparisons to literal values you'd use
address@hidden), or it can be a more general description of the expected
+structure of the expression's value.
@defmac pcase expression &rest clauses
Evaluate @var{expression} and choose among an arbitrary number of
alternatives based on the value of @var{expression}. The possible
alternatives are specified by @var{clauses}, each of which must be a
-list of the form @code{(@var{pattern} @var{body-forms})}.
+list of the form @code{(@var{pattern} @address@hidden)}.
@code{pcase} tries to match the value of @var{expression} to the
@var{pattern} of each clause, in textual order. If the value matches,
the clause succeeds; @code{pcase} then evaluates its @var{body-forms},
@@ -328,7 +328,7 @@ Note: In the description of the patterns below, we use
``the value
being matched'' to refer to the value of the @var{expression} that is
the first argument of @code{pcase}.
-A UPattern can have one of the following forms:
+A UPattern can have the following forms:
@table @code
@@ -337,7 +337,8 @@ Matches if the value being matched is @code{equal} to
@var{val}.
@item @var{atom}
Matches any @var{atom}, which can be a keyword, a number, or a string.
(These are self-quoting, so this kind of UPattern is actually a
-shorthand for @code{'@var{atom}}.)
+shorthand for @code{'@var{atom}}.) Note that a string or a float
+matches any string or float with the same contents/value.
@item _
Matches any value. This is known as @dfn{don't care} or @dfn{wildcard}.
@item @var{symbol}
@@ -362,7 +363,8 @@ Matches if the specified @var{expression} matches the
specified
an @emph{arbitrary} expression, not just the expression that is the
first argument to @code{pcase}. (It is called @code{let} because
@var{upattern} can bind symbols to values using the @var{symbol}
-UPattern.)
+UPattern. For example:
address@hidden@code{((or `(key . ,val) (let val 5)) val)}}.)
@item (app @var{function} @var{upattern})
Matches if @var{function} applied to the value being matched returns a
value that matches @var{upattern}. This is like the @code{pred}
@@ -407,24 +409,27 @@ Here's an illustrative example of using UPatterns:
(code (message "Unknown return code %S" code)))
@end example
-The QPatterns are more powerful. They allow matching the value of the
address@hidden that is the first argument of @code{pcase} against
-specifications of its @emph{structure}. For example, you can specify
-that the value must be a list of 2 elements whose first element is a
-string and the second element is a number. QPatterns can have one of
-the following forms:
+In addition, you can use backquoted patterns that are more powerful.
+They allow matching the value of the @var{expression} that is the
+first argument of @code{pcase} against specifications of its
address@hidden For example, you can specify that the value must be
+a list of 2 elements whose first element is a specific string and the
+second element is any value with a backquoted pattern like
address@hidden("first" ,second-elem)}.
+
+Backquoted patterns have the form @address@hidden where
address@hidden can have the following forms:
@table @code
address@hidden `(@var{qpattern1} . @var{qpattern2})
address@hidden (@var{qpattern1} . @var{qpattern2})
Matches if the value being matched is a cons cell whose @code{car}
matches @var{qpattern1} and whose @code{cdr} matches @var{qpattern2}.
address@hidden address@hidden @var{qpattern2} @dots{} @var{qpatternm}]
+This readily generalizes to backquoted lists as in
address@hidden@code{(@var{qpattern1} @var{qpattern2} @dots{})}}.
address@hidden address@hidden @var{qpattern2} @dots{} @var{qpatternm}]
Matches if the value being matched is a vector of length @var{m} whose
@address@hidden(@var{m}-1)}th elements match @var{qpattern1},
@var{qpattern2} @dots{} @var{qpatternm}, respectively.
address@hidden `(,@var{upattern1} ,@var{upattern2} @dots{})
-Matches if the value being matched is a list whose elements match the
-corresponding @var{upattern1}, @var{upattern2}, etc.
@item @var{atom}
Matches if corresponding element of the value being matched is
@code{equal} to the specified @var{atom}.
@@ -433,6 +438,13 @@ Matches if the corresponding element of the value being
matched
matches the specified @var{upattern}.
@end table
+Note that uses of QPatterns can be expressed using only UPatterns, as
+QPatterns are implemented on top of UPatterns using
address@hidden, described below. However, using QPatterns will
+in many cases lead to a more readable code.
address@hidden FIXME: There should be an example here showing how a 'pcase' that
address@hidden uses QPatterns can be rewritten using UPatterns.
+
@end defmac
Here is an example of using @code{pcase} to implement a simple
@@ -476,8 +488,11 @@ Additional UPatterns can be defined using the
@code{pcase-defmacro}
macro.
@defmac pcase-defmacro name args &rest body
-Define a new UPattern for @code{pcase}. The UPattern will have the
-form @code{(@var{name} @var{args})}.
+Define a new kind of UPattern for @code{pcase}. The new UPattern will
+be invoked as @code{(@var{name} @var{actual-args})}. The @var{body}
+should describe how to rewrite the UPattern @var{name} into some other
+UPattern. The rewriting will be the result of evaluating @var{body}
+in an environment where @var{args} are bound to @var{actual-args}.
@end defmac
@node Combining Conditions
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] emacs-25 d7a93ef: Minor improvements to 'pcase' documentation,
Eli Zaretskii <=