[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] fix/bug-31311-pcase-doc 567342a 2/3: move ‘Pattern-Matchi
From: |
Thien-Thi Nguyen |
Subject: |
[Emacs-diffs] fix/bug-31311-pcase-doc 567342a 2/3: move ‘Pattern-Matching Conditional’ after ‘Combining Conditions’ |
Date: |
Mon, 21 May 2018 12:36:12 -0400 (EDT) |
branch: fix/bug-31311-pcase-doc
commit 567342a88e5349e701e448a90bc24611bf321caa
Author: Thien-Thi Nguyen <address@hidden>
Commit: Thien-Thi Nguyen <address@hidden>
move ‘Pattern-Matching Conditional’ after ‘Combining Conditions’
Since ‘pcase’ supports "sequence patterns" ‘and’ and ‘or’,
it's more helpful to refer back to the values-processing
analogs, than forward (IMHO).
---
doc/lispref/control.texi | 258 +++++++++++++++++++++++------------------------
doc/lispref/elisp.texi | 5 +-
2 files changed, 127 insertions(+), 136 deletions(-)
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 4733ed1..b0cd777 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -37,8 +37,8 @@ structure constructs (@pxref{Macros}).
@menu
* Sequencing:: Evaluation in textual order.
* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}.
-* Pattern-Matching Conditional:: @code{pcase}, @code{pcase-defmacro}, etc.
* Combining Conditions:: @code{and}, @code{or}, @code{not}.
+* Pattern-Matching Conditional:: How to use @code{pcase} and friends.
* Iteration:: @code{while} loops.
* Generators:: Generic sequences and coroutines.
* Nonlocal Exits:: Jumping out of a sequence.
@@ -289,12 +289,131 @@ For example:
@end group
@end example
address@hidden Issue: This node is between ‘Conditionals’ and ‘Combining
Conditions’.
address@hidden The latter describes ‘and’ and ‘or’, which have core
pattern
address@hidden analogs (the so-called ``sequencing patterns''). That
portion
address@hidden currently xrefs ‘Combining Conditions’, a forward-ref.
address@hidden Question: Should this section (and its subsections) be
moved
address@hidden after ‘Combining Conditions’ so that the xref is
backwards?
address@hidden Combining Conditions
address@hidden Constructs for Combining Conditions
address@hidden combining conditions
+
+ This section describes three constructs that are often used together
+with @code{if} and @code{cond} to express complicated conditions. The
+constructs @code{and} and @code{or} can also be used individually as
+kinds of multiple conditional constructs.
+
address@hidden not condition
+This function tests for the falsehood of @var{condition}. It returns
address@hidden if @var{condition} is @code{nil}, and @code{nil} otherwise.
+The function @code{not} is identical to @code{null}, and we recommend
+using the name @code{null} if you are testing for an empty list.
address@hidden defun
+
address@hidden and address@hidden
+The @code{and} special form tests whether all the @var{conditions} are
+true. It works by evaluating the @var{conditions} one by one in the
+order written.
+
+If any of the @var{conditions} evaluates to @code{nil}, then the result
+of the @code{and} must be @code{nil} regardless of the remaining
address@hidden; so @code{and} returns @code{nil} right away, ignoring
+the remaining @var{conditions}.
+
+If all the @var{conditions} turn out address@hidden, then the value of
+the last of them becomes the value of the @code{and} form. Just
address@hidden(and)}, with no @var{conditions}, returns @code{t}, appropriate
+because all the @var{conditions} turned out address@hidden (Think
+about it; which one did not?)
+
+Here is an example. The first condition returns the integer 1, which is
+not @code{nil}. Similarly, the second condition returns the integer 2,
+which is not @code{nil}. The third condition is @code{nil}, so the
+remaining condition is never evaluated.
+
address@hidden
address@hidden
+(and (print 1) (print 2) nil (print 3))
+ @print{} 1
+ @print{} 2
address@hidden nil
address@hidden group
address@hidden example
+
+Here is a more realistic example of using @code{and}:
+
address@hidden
address@hidden
+(if (and (consp foo) (eq (car foo) 'x))
+ (message "foo is a list starting with x"))
address@hidden group
address@hidden example
+
address@hidden
+Note that @code{(car foo)} is not executed if @code{(consp foo)} returns
address@hidden, thus avoiding an error.
+
address@hidden expressions can also be written using either @code{if} or
address@hidden Here's how:
+
address@hidden
address@hidden
+(and @var{arg1} @var{arg2} @var{arg3})
address@hidden
+(if @var{arg1} (if @var{arg2} @var{arg3}))
address@hidden
+(cond (@var{arg1} (cond (@var{arg2} @var{arg3}))))
address@hidden group
address@hidden example
address@hidden defspec
+
address@hidden or address@hidden
+The @code{or} special form tests whether at least one of the
address@hidden is true. It works by evaluating all the
address@hidden one by one in the order written.
+
+If any of the @var{conditions} evaluates to a address@hidden value, then
+the result of the @code{or} must be address@hidden; so @code{or} returns
+right away, ignoring the remaining @var{conditions}. The value it
+returns is the address@hidden value of the condition just evaluated.
+
+If all the @var{conditions} turn out @code{nil}, then the @code{or}
+expression returns @code{nil}. Just @code{(or)}, with no
address@hidden, returns @code{nil}, appropriate because all the
address@hidden turned out @code{nil}. (Think about it; which one
+did not?)
+
+For example, this expression tests whether @code{x} is either
address@hidden or the integer zero:
+
address@hidden
+(or (eq x nil) (eq x 0))
address@hidden example
+
+Like the @code{and} construct, @code{or} can be written in terms of
address@hidden For example:
+
address@hidden
address@hidden
+(or @var{arg1} @var{arg2} @var{arg3})
address@hidden
+(cond (@var{arg1})
+ (@var{arg2})
+ (@var{arg3}))
address@hidden group
address@hidden example
+
+You could almost write @code{or} in terms of @code{if}, but not quite:
+
address@hidden
address@hidden
+(if @var{arg1} @var{arg1}
+ (if @var{arg2} @var{arg2}
+ @var{arg3}))
address@hidden group
address@hidden example
+
address@hidden
+This is not completely equivalent because it can evaluate @var{arg1} or
address@hidden twice. By contrast, @code{(or @var{arg1} @var{arg2}
address@hidden)} never evaluates any argument more than once.
address@hidden defspec
+
@node Pattern-Matching Conditional
@section Pattern-Matching Conditional
@cindex pcase
@@ -1046,131 +1165,6 @@ evaluation results:
(evaluate '(sub 1 2) nil) @result{} error
@end example
address@hidden Combining Conditions
address@hidden Constructs for Combining Conditions
address@hidden combining conditions
-
- This section describes three constructs that are often used together
-with @code{if} and @code{cond} to express complicated conditions. The
-constructs @code{and} and @code{or} can also be used individually as
-kinds of multiple conditional constructs.
-
address@hidden not condition
-This function tests for the falsehood of @var{condition}. It returns
address@hidden if @var{condition} is @code{nil}, and @code{nil} otherwise.
-The function @code{not} is identical to @code{null}, and we recommend
-using the name @code{null} if you are testing for an empty list.
address@hidden defun
-
address@hidden and address@hidden
-The @code{and} special form tests whether all the @var{conditions} are
-true. It works by evaluating the @var{conditions} one by one in the
-order written.
-
-If any of the @var{conditions} evaluates to @code{nil}, then the result
-of the @code{and} must be @code{nil} regardless of the remaining
address@hidden; so @code{and} returns @code{nil} right away, ignoring
-the remaining @var{conditions}.
-
-If all the @var{conditions} turn out address@hidden, then the value of
-the last of them becomes the value of the @code{and} form. Just
address@hidden(and)}, with no @var{conditions}, returns @code{t}, appropriate
-because all the @var{conditions} turned out address@hidden (Think
-about it; which one did not?)
-
-Here is an example. The first condition returns the integer 1, which is
-not @code{nil}. Similarly, the second condition returns the integer 2,
-which is not @code{nil}. The third condition is @code{nil}, so the
-remaining condition is never evaluated.
-
address@hidden
address@hidden
-(and (print 1) (print 2) nil (print 3))
- @print{} 1
- @print{} 2
address@hidden nil
address@hidden group
address@hidden example
-
-Here is a more realistic example of using @code{and}:
-
address@hidden
address@hidden
-(if (and (consp foo) (eq (car foo) 'x))
- (message "foo is a list starting with x"))
address@hidden group
address@hidden example
-
address@hidden
-Note that @code{(car foo)} is not executed if @code{(consp foo)} returns
address@hidden, thus avoiding an error.
-
address@hidden expressions can also be written using either @code{if} or
address@hidden Here's how:
-
address@hidden
address@hidden
-(and @var{arg1} @var{arg2} @var{arg3})
address@hidden
-(if @var{arg1} (if @var{arg2} @var{arg3}))
address@hidden
-(cond (@var{arg1} (cond (@var{arg2} @var{arg3}))))
address@hidden group
address@hidden example
address@hidden defspec
-
address@hidden or address@hidden
-The @code{or} special form tests whether at least one of the
address@hidden is true. It works by evaluating all the
address@hidden one by one in the order written.
-
-If any of the @var{conditions} evaluates to a address@hidden value, then
-the result of the @code{or} must be address@hidden; so @code{or} returns
-right away, ignoring the remaining @var{conditions}. The value it
-returns is the address@hidden value of the condition just evaluated.
-
-If all the @var{conditions} turn out @code{nil}, then the @code{or}
-expression returns @code{nil}. Just @code{(or)}, with no
address@hidden, returns @code{nil}, appropriate because all the
address@hidden turned out @code{nil}. (Think about it; which one
-did not?)
-
-For example, this expression tests whether @code{x} is either
address@hidden or the integer zero:
-
address@hidden
-(or (eq x nil) (eq x 0))
address@hidden example
-
-Like the @code{and} construct, @code{or} can be written in terms of
address@hidden For example:
-
address@hidden
address@hidden
-(or @var{arg1} @var{arg2} @var{arg3})
address@hidden
-(cond (@var{arg1})
- (@var{arg2})
- (@var{arg3}))
address@hidden group
address@hidden example
-
-You could almost write @code{or} in terms of @code{if}, but not quite:
-
address@hidden
address@hidden
-(if @var{arg1} @var{arg1}
- (if @var{arg2} @var{arg2}
- @var{arg3}))
address@hidden group
address@hidden example
-
address@hidden
-This is not completely equivalent because it can evaluate @var{arg1} or
address@hidden twice. By contrast, @code{(or @var{arg1} @var{arg2}
address@hidden)} never evaluates any argument more than once.
address@hidden defspec
-
@node Iteration
@section Iteration
@cindex iteration
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index e15c92d44..6c3182b 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -475,14 +475,11 @@ Control Structures
* Sequencing:: Evaluation in textual order.
* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}.
* Combining Conditions:: @code{and}, @code{or}, @code{not}.
+* Pattern-Matching Conditional:: How to use @code{pcase} and friends.
* Iteration:: @code{while} loops.
* Generators:: Generic sequences and coroutines.
* Nonlocal Exits:: Jumping out of a sequence.
-Conditionals
-
-* Pattern-Matching Conditional:: How to use @code{pcase}.
-
Nonlocal Exits
* Catch and Throw:: Nonlocal exits for the program's own purposes.