Merge from emacs-24; up to 2012-11-26T19:56:14Z!monnier@iro.umontreal.ca

3 files changed, 144 insertions, 33 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 7238d958d8a..05716cd77b3 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,10 @@
+2012-12-10  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * control.texi (Pattern maching case statement): New node.
+
+        * customize.texi (Variable Definitions): Mention the default :group
+        for defcustoms (bug#13093).
+
 2012-12-09  Glenn Morris  <rgm@gnu.org>
 
         * customize.texi (Variable Definitions): Mention eval-defun
@@ -27,7 +34,7 @@
         * display.texi (Defining Faces):
         * sequences.texi (Char-Tables): Fix xref.
 
-        * keymaps.texi (Key Sequences): kbd is now a function.
+        * keymaps.texi (Key Sequences): `kbd' is now a function.
 
         * commands.texi (Using Interactive): Fix index entry.
 
@@ -47,16 +54,14 @@
         (Windows and Frames): Fix example.  Move description of
         window-in-direction here.
         (Recombining Windows): Fix example.
-        (Buffers and Windows): Fix description of
-        replace-buffer-in-windows.
+        (Buffers and Windows): Fix description of replace-buffer-in-windows.
         (Switching Buffers): Reword.
         (Display Action Functions): Minor adjustments.
         (Choosing Window Options): Minor fixes.
         (Window History): Minor rewording.
         (Dedicated Windows): Correct and reword part describing how
         dedicatedness affects functions removing buffers or windows.
-        * buffers.texi (The Buffer List): Fix description of
-        bury-buffer.
+        * buffers.texi (The Buffer List): Fix description of bury-buffer.
 
 2012-11-24  Chong Yidong  <cyd@gnu.org>
 
@@ -115,8 +120,8 @@
 
         * windows.texi (Choosing Window): Rewrite description of
         display-buffer-alist (Bug#12167).
-        (Display Action Functions): Mention inhibit-switch-frame.  Fix
-        description of display-buffer-below-selected.  Reorder actions.
+        (Display Action Functions): Mention inhibit-switch-frame.
+        Fix description of display-buffer-below-selected.  Reorder actions.
         Add example (Bug#12848).
 
 2012-11-16  Glenn Morris  <rgm@gnu.org>
@@ -215,11 +220,11 @@
         switch-to-buffer-preserve-window-point.
         (Display Action Functions): Document window-height and
         window-width alist entries.
-        (Display Action Functions): Document
-        display-buffer-below-selected and
+        (Display Action Functions):
+        Document display-buffer-below-selected and
         display-buffer-in-previous-window.
-        (Quitting Windows): Document quit-restore-window.  Rewrite
-        section.
+        (Quitting Windows): Document quit-restore-window.
+        Rewrite section.
         (Window Configurations): In window-state-get mention that
         argument window must be valid.
         (Window Parameters): Document quit-restore window parameter
@@ -319,8 +324,8 @@
         * minibuf.texi (Text from Minibuffer): Document read-regexp
         changes.
 
-        * nonascii.texi (Selecting a Representation): Document
-        set-buffer-multibyte changes.
+        * nonascii.texi (Selecting a Representation):
+        Document set-buffer-multibyte changes.
 
         * keymaps.texi (Toolkit Differences): Node deleted.
         (Easy Menu): New node.
@@ -1092,8 +1097,8 @@
 
 2012-04-12  Jari Aalto  <jari.aalto@cante.net>
 
-        * processes.texi (Synchronous Processes): Mention
-        `default-directory' (bug#7515).
+        * processes.texi (Synchronous Processes):
+        Mention `default-directory' (bug#7515).
 
 2012-04-09  Chong Yidong  <cyd@gnu.org>
 
@@ -1116,8 +1121,8 @@
 
         * minibuf.texi (Programmed Completion): Remove obsolete variable
         completion-annotate-function.
-        (Completion Variables): Rename from Completion Styles.  Document
-        completion-extra-properties.  Document completion-styles-alist
+        (Completion Variables): Rename from Completion Styles.
+        Document completion-extra-properties.  Document completion-styles-alist
         change.
         (Reading File Names): minibuffer-local-filename-must-match-map is
         not used anymore.
@@ -1252,8 +1257,8 @@
         Minor clarifications.
         (Defining Faces): Copyedits.  Update face example.
         (Attribute Functions): Mark set-face-foreground etc as commands.
-        (Face Remapping): Mention text-scale-adjust.  Clarify
-        face-remapping-alist and related docs.
+        (Face Remapping): Mention text-scale-adjust.
+        Clarify face-remapping-alist and related docs.
         (Face Functions): Don't document make-face or copy-face.
 
 2012-03-20  Chong Yidong  <cyd@gnu.org>
@@ -1594,8 +1599,8 @@
         (Syntax Properties): Document syntax-propertize-function and
         syntax-propertize-extend-region-functions.
         (Motion via Parsing): Clarify scan-lists. Fix indentation.
-        (Parser State): Update for the new "c" comment style.  Fix
-        description of item 7 (comment style).
+        (Parser State): Update for the new "c" comment style.
+        Fix description of item 7 (comment style).
 
         * modes.texi (Minor Modes): Update how mode commands should treat
         arguments now.
@@ -1673,9 +1678,9 @@
 
         * debugging.texi (Debugging): Copyedits.  Describe testcover, ERT.
         (Error Debugging): Note that debug-ignored-errors overrides list
-        values of debug-on-error too.  Add xref to Signaling Errors.  Note
-        that debug-on-signal is not customizable.  Mention
-        condition-case-unless-debug.
+        values of debug-on-error too.  Add xref to Signaling Errors.
+        Note that debug-on-signal is not customizable.
+        Mention condition-case-unless-debug.
         (Compilation Errors): Node deleted.
 
         * compile.texi (Compiler Errors): Move a paragraph here from
@@ -1791,15 +1796,15 @@
 2012-02-04  Chong Yidong  <cyd@gnu.org>
 
         * functions.texi (What Is a Function): Add closures.  Mention
-        "return value" terminology.  Add xref for command-execute.  Remove
-        unused "keystroke command" terminology.
+        "return value" terminology.  Add xref for command-execute.
+        Remove unused "keystroke command" terminology.
         (Lambda Expressions): Give a different example than in the
         following subsection.  Add xref to Anonymous Functions.
         (Function Documentation): Remove gratuitous markup.
         (Function Names): Move introductory text to `What Is a Function'.
         (Defining Functions): Fix defun argument spec.
-        (Anonymous Functions): Document lambda macro explicitly.  Mention
-        effects on lexical binding.
+        (Anonymous Functions): Document lambda macro explicitly.
+        Mention effects on lexical binding.
         (Function Cells): Downplay direct usage of fset.
         (Closures): New node.
         (Inline Functions): Remove "open-code" terminology.
@@ -1930,8 +1935,8 @@
         * variables.texi (Variables, Local Variables, Void Variables):
         Edit to make the descriptions less specific to dynamic binding.
         (Local Variables): Default max-specpdl-size is now 1300.
-        (Defining Variables): Edits for lexical scoping.  Delete
-        information about starting docstrings with *.  De-document
+        (Defining Variables): Edits for lexical scoping.
+        Delete information about starting docstrings with *.  De-document
         user-variable-p.
         (Tips for Defining): Remove an unimportant discussion of quitting
         in the middle of a load.
@@ -2019,8 +2024,8 @@
 
 2012-01-06  Chong Yidong  <cyd@gnu.org>
 
-        * variables.texi (Directory Local Variables): Document
-        hack-dir-local-variables-non-file-buffer.
+        * variables.texi (Directory Local Variables):
+        Document hack-dir-local-variables-non-file-buffer.
 
 2012-01-06  Glenn Morris  <rgm@gnu.org>
 
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 489e5cc5b22..00b0a75a3e2 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -285,6 +285,110 @@ For example:
 @end group
 @end example
 
+@menu
+* Pattern maching case statement::
+@end menu
+
+@node Pattern maching case statement
+@subsection Pattern maching case statement
+@cindex pcase
+@cindex pattern matching
+
+To compare a particular value against various possible cases, the macro
+@code{pcase} can come handy.  It takes the following form:
+
+@example
+(pcase @var{exp} @var{branch}1 @var{branch}2 @var{branch}3 @dots{})
+@end example
+
+where each @var{branch} takes the form @code{(@var{upattern}
+@var{body-forms}@dots{})}.
+
+It will first evaluate @var{exp} and then compare the value against each
+@var{upattern} to see which @var{branch} to use, after which it will run the
+corresponding @var{body-forms}.  A common use case is to distinguish
+between a few different constant values:
+
+@example
+(pcase (get-return-code x)
+  (`success       (message "Done!"))
+  (`would-block   (message "Sorry, can't do it now"))
+  (`read-only     (message "The shmliblick is read-only"))
+  (`access-denied (message "You do not have the needed rights"))
+  (code           (message "Unknown return code %S" code)))
+@end example
+
+In the last clause, @code{code} is a variable that gets bound to the value that
+was returned by @code{(get-return-code x)}.
+
+To give a more complex example, a simple interpreter for a little
+expression language could look like:
+
+@example
+(defun evaluate (exp env)
+  (pcase exp
+    (`(add ,x ,y)         (+ (evaluate x env) (evaluate y env)))
+    (`(call ,fun ,arg)    (funcall (evaluate fun) (evaluate arg env)))
+    (`(fn ,arg ,body)     (lambda (val)
+                            (evaluate body (cons (cons arg val) env))))
+    ((pred numberp)       exp)
+    ((pred symbolp)       (cdr (assq exp env)))
+    (_                    (error "Unknown expression %S" exp))))
+@end example
+
+Where @code{`(add ,x ,y)} is a pattern that checks that @code{exp} is a three
+element list starting with the symbol @code{add}, then extracts the second and
+third elements and binds them to the variables @code{x} and @code{y}.
+@code{(pred numberp)} is a pattern that simply checks that @code{exp}
+is a number, and @code{_} is the catch-all pattern that matches anything.
+
+There are two kinds of patterns involved in @code{pcase}, called
+@emph{U-patterns} and @emph{Q-patterns}.  The @var{upattern} mentioned above
+are U-patterns and can take the following forms:
+
+@table @code
+@item `@var{qpattern}
+This is one of the most common form of patterns.  The intention is to mimic the
+backquote macro: this pattern matches those values that could have been built
+by such a backquote expression.  Since we're pattern matching rather than
+building a value, the unquote does not indicate where to plug an expression,
+but instead it lets one specify a U-pattern that should match the value at
+that location.
+
+More specifically, a Q-pattern can take the following forms:
+@table @code
+@item (@var{qpattern1} . @var{qpattern2})
+This pattern matches any cons cell whose @code{car} matches @var{QPATTERN1} and
+whose @code{cdr} matches @var{PATTERN2}.
+@item @var{atom}
+This pattern matches any atom @code{equal} to @var{atom}.
+@item ,@var{upattern}
+This pattern matches any object that matches the @var{upattern}.
+@end table
+
+@item @var{symbol}
+A mere symbol in a U-pattern matches anything, and additionally let-binds this
+symbol to the value that it matched, so that you can later refer to it, either
+in the @var{body-forms} or also later in the pattern.
+@item _
+This so-called @emph{don't care} pattern matches anything, like the previous
+one, but unless symbol patterns it does not bind any variable.
+@item (pred @var{pred})
+This pattern matches if the function @var{pred} returns non-@code{nil} when
+called with the object being matched.
+@item (or @var{upattern1} @var{upattern2}@dots{})
+This pattern matches as soon as one of the argument patterns succeeds.
+All argument patterns should let-bind the same variables.
+@item (and @var{upattern1} @var{upattern2}@dots{})
+This pattern matches only if all the argument patterns succeed.
+@item (guard @var{exp})
+This pattern ignores the object being examined and simply succeeds if @var{exp}
+evaluates to non-@code{nil} and fails otherwise.  It is typically used inside
+an @code{and} pattern.  For example, @code{(and x (guard (< x 10)))}
+is a pattern which matches any number smaller than 10 and let-binds it to
+the variable @code{x}.
+@end table
+
 @node Combining Conditions
 @section Constructs for Combining Conditions
 
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index c8d09760b53..56e091eabf2 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -303,7 +303,9 @@ evaluate at any time.
 The argument @var{doc} specifies the documentation string for the
 variable.
 
-Every @code{defcustom} should specify @code{:group} at least once.
+If a @code{defcustom} does not specify any @code{:group}, the last group
+defined with @code{defgroup} in the same file will be used.  This way, most
+@code{defcustom} do not need an explicit @code{:group}.
 
 When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
 mode (@code{eval-defun}), a special feature of @code{eval-defun}