   This version is newer than the second printed edition of the GNU
Emacs Lisp Reference Manual.  It corresponds to Emacs Version 19.19.

   Published by the Free Software Foundation 675 Massachusetts Avenue
Cambridge, MA 02139 USA

   Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.

Syntax of Regular Expressions
-----------------------------

   Regular expressions have a syntax in which a few characters are
special constructs and the rest are "ordinary".  An ordinary character
is a simple regular expression which matches that character and nothing
else.  The special characters are `$', `^', `.', `*', `+', `?', `[',
`]' and `\'; no new special characters will be defined in the future.
Any other character appearing in a regular expression is ordinary,
unless a `\' precedes it.

   For example, `f' is not a special character, so it is ordinary, and
therefore `f' is a regular expression that matches the string `f' and
no other string.  (It does *not* match the string `ff'.)  Likewise, `o'
is a regular expression that matches only `o'.

   Any two regular expressions A and B can be concatenated.  The result
is a regular expression which matches a string if A matches some amount
of the beginning of that string and B matches the rest of the string.

   As a simple example, we can concatenate the regular expressions `f'
and `o' to get the regular expression `fo', which matches only the
string `fo'.  Still trivial.  To do something more powerful, you need
to use one of the special characters.  Here is a list of them:

`. (Period)'
     is a special character that matches any single character except a
     newline.  Using concatenation, we can make regular expressions
     like `a.b' which matches any three-character string which begins
     with `a' and ends with `b'.

`*'
     is not a construct by itself; it is a suffix that means the
     preceding regular expression is to be repeated as many times as
     possible.  In `fo*', the `*' applies to the `o', so `fo*' matches
     one `f' followed by any number of `o's.  The case of zero `o's is
     allowed: `fo*' does match `f'.

     `*' always applies to the *smallest* possible preceding
     expression.  Thus, `fo*' has a repeating `o', not a repeating `fo'.

     The matcher processes a `*' construct by matching, immediately, as
     many repetitions as can be found.  Then it continues with the rest
     of the pattern.  If that fails, backtracking occurs, discarding
     some of the matches of the `*'-modified construct in case that
     makes it possible to match the rest of the pattern.  For example,
     matching `ca*ar' against the string `caaar', the `a*' first tries
     to match all three `a's; but the rest of the pattern is `ar' and
     there is only `r' left to match, so this try fails.  The next
     alternative is for `a*' to match only two `a's.  With this choice,
     the rest of the regexp matches successfully.

`+'
     is a suffix character similar to `*' except that it must match the
     preceding expression at least once.  So, for example, `ca+r' will
     match the strings `car' and `caaaar' but not the string `cr',
     whereas `ca*r' would match all three strings.

`?'
     is a suffix character similar to `*' except that it can match the
     preceding expression either once or not at all.  For example,
     `ca?r' will match `car' or `cr'; nothing else.

`[ ... ]'
     `[' begins a "character set", which is terminated by a `]'.  In
     the simplest case, the characters between the two form the set.
     Thus, `[ad]' matches either one `a' or one `d', and `[ad]*'
     matches any string composed of just `a's and `d's (including the
     empty string), from which it follows that `c[ad]*r' matches `cr',
     `car', `cdr', `caddaar', etc.

     Character ranges can also be included in a character set, by
     writing two characters with a `-' between them.  Thus, `[a-z]'
     matches any lower case letter.  Ranges may be intermixed freely
     with individual characters, as in `[a-z$%.]', which matches any
     lower case letter or `$', `%' or a period.

     Note that the usual special characters are not special any more
     inside a character set.  A completely different set of special
     characters exists inside character sets: `]', `-' and `^'.

     To include a `]' in a character set, make it the first character.
     For example, `[]a]' matches `]' or `a'.  To include a `-', write
     `-' as the first or last character in the range.

     To include `^', make it other than the first character in the set.

`[^ ... ]'
     `[^' begins a "complement character set", which matches any
     character except the ones specified.  Thus, `[^a-z0-9A-Z]' matches
     all characters *except* letters and digits.

     `^' is not special in a character set unless it is the first
     character.  The character following the `^' is treated as if it
     were first (thus, `-' and `]' are not special there).

     Note that a complement character set can match a newline, unless
     newline is mentioned as one of the characters not to match.

`^'
     is a special character that matches the empty string, but only at
     the beginning of a line in the text being matched.  Otherwise it
     fails to match anything.  Thus, `^foo' matches a `foo' which occurs
     at the beginning of a line.

     When matching a string, `^' matches at the beginning of the string
     or after a newline character `\n'.

`$'
     is similar to `^' but matches only at the end of a line.  Thus,
     `x+$' matches a string of one `x' or more at the end of a line.

     When matching a string, `$' matches at the end of the string or
     before a newline character `\n'.

`\'
     has two functions: it quotes the special characters (including
     `\'), and it introduces additional special constructs.

     Because `\' quotes special characters, `\$' is a regular
     expression which matches only `$', and `\[' is a regular
     expression which matches only `[', and so on.

     Note that `\' also has special meaning in the read syntax of Lisp
     strings (see String Type.), and must be quoted with `\'.  For
     example, the regular expression that matches the `\' character is
     `\\'.  To write a Lisp string that contains the characters `\\',
     Lisp syntax requires you to quote each `\' with another `\'.
     Therefore, the read syntax for a regular expression matching `\'
     is `"\\\\"'.

   *Please note:* for historical compatibility, special characters are
treated as ordinary ones if they are in contexts where their special
meanings make no sense.  For example, `*foo' treats `*' as ordinary
since there is no preceding expression on which the `*' can act.  It is
poor practice to depend on this behavior; better to quote the special
character anyway, regardless of where it appears.

   For the most part, `\' followed by any character matches only that
character.  However, there are several exceptions: characters which,
when preceded by `\', are special constructs.  Such characters are
always ordinary when encountered on their own.  Here is a table of `\'
constructs:

`\|'
     specifies an alternative.  Two regular expressions A and B with
     `\|' in between form an expression that matches anything that
     either A or B matches.

     Thus, `foo\|bar' matches either `foo' or `bar' but no other string.

     `\|' applies to the largest possible surrounding expressions.
     Only a surrounding `\( ... \)' grouping can limit the grouping
     power of `\|'.

     Full backtracking capability exists to handle multiple uses of
     `\|'.

`\( ... \)'
     is a grouping construct that serves three purposes:

       1. To enclose a set of `\|' alternatives for other operations.
          Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.

       2. To enclose a complicated expression for a suffix character
          such as `*' to operate on.  Thus, `ba\(na\)*' matches
          `bananana', etc., with any (zero or more) number of `na'
          strings.

       3. To record a matched substring for future reference.

     This last application is not a consequence of the idea of a
     parenthetical grouping; it is a separate feature which happens to
     be assigned as a second meaning to the same `\( ... \)' construct
     because there is no conflict in practice between the two meanings.
     Here is an explanation of this feature:

`\DIGIT'
     matches the same text which is matched the DIGITth time by a
     previous `\( ... \)' construct.

     In other words, after the end of a `\( ... \)' construct.  the
     matcher remembers the beginning and end of the text matched by
     that construct.  Then, later on in the regular expression, you can
     use `\' followed by DIGIT to mean "match the same text matched the
     DIGITth time by the `\( ... \)' construct."

     The strings matching the first nine `\( ... \)' constructs
     appearing in a regular expression are assigned numbers 1 through 9
     in the order that the open parentheses appear in the regular
     expression.  So you can use `\1' through `\9' to refer to the text
     matched by the corresponding `\( ... \)' constructs.

     For example, `\(.*\)\1' matches any newline-free string that is
     composed of two identical halves.  The `\(.*\)' matches the first
     half, which may be anything, but the `\1' that follows must match
     the same exact text.

`\`'
     matches the empty string, provided it is at the beginning of the
     buffer or string being matched against.

`\''
     matches the empty string, provided it is at the end of the buffer
     or string being matched against.

`\='
     matches the empty string, provided it is at point.  (This
     construct is not defined when matching against a string.)

`\b'
     matches the empty string, provided it is at the beginning or end
     of a word.  Thus, `\bfoo\b' matches any occurrence of `foo' as a
     separate word.  `\bballs?\b' matches `ball' or `balls' as a
     separate word.

`\B'
     matches the empty string, provided it is *not* at the beginning or
     end of a word.

`\<'
     matches the empty string, provided it is at the beginning of a
     word.

`\>'
     matches the empty string, provided it is at the end of a word.

`\w'
     matches any word-constituent character.  The editor syntax table
     determines which characters these are.  See Syntax Tables.

`\W'
     matches any character that is not a word-constituent.

`\sCODE'
     matches any character whose syntax is CODE.  Here CODE is a
     character which represents a syntax code: thus, `w' for word
     constituent, `-' for whitespace, `(' for open parenthesis, etc.
     See Syntax Tables, for a list of the codes.

`\SCODE'
     matches any character whose syntax is not CODE.

   Not every string is a valid regular expression.  For example, any
string with unbalanced square brackets is invalid, and so is a string
that ends with a single `\'.  If an invalid regular expression is
passed to any of the search functions, an `invalid-regexp' error is
signaled.

 - Function: regexp-quote STRING
     This function returns a regular expression string which matches
     exactly STRING and nothing else.  This allows you to request an
     exact string match when calling a function that wants a regular
     expression.

          (regexp-quote "^The cat$")
               => "\\^The cat\\$"

     One use of `regexp-quote' is to combine an exact string match with
     context described as a regular expression.  For example, this
     searches for the string which is the value of `string', surrounded
     by whitespace:

          (re-search-forward
           (concat "\\s " (regexp-quote string) "\\s "))

Complex Regexp Example
----------------------

   Here is a complicated regexp, used by Emacs to recognize the end of a
sentence together with any whitespace that follows.  It is the value of
the variable `sentence-end'.

   First, we show the regexp as a string in Lisp syntax to enable you to
distinguish the spaces from the tab characters.  The string constant
begins and ends with a double-quote.  `\"' stands for a double-quote as
part of the string, `\\' for a backslash as part of the string, `\t'
for a tab and `\n' for a newline.

     "[.?!][]\"')}]*\\($\\|\t\\|  \\)[ \t\n]*"

   In contrast, if you evaluate the variable `sentence-end', you will
see the following:

     sentence-end
     =>
     "[.?!][]\"')}]*\\($\\|  \\|  \\)[
     ]*"

In this case, the tab and carriage return are the actual characters.

   This regular expression contains four parts in succession and can be
deciphered as follows:

`[.?!]'
     The first part of the pattern consists of three characters, a
     period, a question mark and an exclamation mark, within square
     brackets.  The match must begin with one of these three characters.

`[]\"')}]*'
     The second part of the pattern matches any closing braces and
     quotation marks, zero or more of them, that may follow the period,
     question mark or exclamation mark.  The `\"' is Lisp syntax for a
     double-quote in a string.  The `*' at the end indicates that the
     immediately preceding regular expression (a character set, in this
     case) may be repeated zero or more times.

`\\($\\|\t\\|  \\)'
     The third part of the pattern matches the whitespace that follows
     the end of a sentence: the end of a line, or a tab, or two spaces.
     The double backslashes are needed to prevent Emacs from reading
     the parentheses and vertical bars as part of the search pattern;
     the parentheses are used to mark the group and the vertical bars
     are used to indicated that the patterns to either side of them are
     alternatives.  The dollar sign is used to match the end of a line.
     The tab character is written using `\t' and the two spaces are
     written as themselves.

`[ \t\n]*'
     Finally, the last part of the pattern indicates that the end of
     the line or the whitespace following the period, question mark or
     exclamation mark may, but need not, be followed by additional
     whitespace.

Regular Expression Searching
============================

   In GNU Emacs, you can search for the next match for a regexp either
incrementally or not.  Incremental search commands are described in the
`The GNU Emacs Manual'.  See Regular Expression Search (emacs).
Here we describe only the search functions useful in programs.
The principal one is `re-search-forward'.

 - Command: re-search-forward REGEXP &optional LIMIT NOERROR REPEAT
     This function searches forward in the current buffer for a string
     of text that is matched by the regular expression REGEXP.  The
     function skips over any amount of text that is not matched by
     REGEXP, and leaves point at the end of the first string found that
     does match.

     If the search is successful (i.e., if text matching REGEXP is
     found), then point moves to the end of that text, and the function
     returns the new value of point.

     What happens when the search fails depends on the value of
     NOERROR.  If NOERROR is `nil', a `search-failed' error is
     signaled.  If NOERROR is `t', `re-search-forward' does nothing and
     returns `nil'.  If NOERROR is neither `nil' nor `t', then
     `re-search-forward' moves point to LIMIT (or the end of the
     buffer) and returns `nil'.

     If LIMIT is non-`nil' (it must be a position in the current
     buffer), then it is the upper bound to the search.  No match
     extending after that position is accepted.

     If REPEAT is supplied (it must be a positive number), then the
     search is repeated that many times (each time starting at the end
     of the previous time's match).  The call succeeds if all these
     searches succeeded, and point is left at the end of the match
     found by the last search.  Otherwise the search fails.

     In the following example, point is initially located directly
     before the `T'.  After evaluating the form, point is located at
     the end of that line (between the `t' of `hat' and before the
     newline).

          ---------- Buffer: foo ----------
          I read "-!-The cat in the hat
          comes back" twice.
          ---------- Buffer: foo ----------

          (re-search-forward "[a-z]+" nil t 5)
               => t

          ---------- Buffer: foo ----------
          I read "The cat in the hat-!-
          comes back" twice.
          ---------- Buffer: foo ----------

 - Command: re-search-backward REGEXP &optional LIMIT NOERROR REPEAT
     This function searches backward in the current buffer for a string
     of text that is matched by the regular expression REGEXP, leaving
     point at the beginning of the first text found.

     This function is analogous to `re-search-forward', but they are
     not simple mirror images.  `re-search-forward' finds the match
     whose beginning is as close as possible.  If `re-search-backward'
     were a perfect mirror image, it would find the match whose end is
     as close as possible.  However, in fact it finds the match whose
     beginning is as close as possible.  The reason is that matching a
     regular expression at a given spot always works from beginning to
     end, and is done at a specified beginning position.  Thus, true
     mirror-image behavior would require a special feature for matching
     regexps from end to beginning.

 - Function: string-match REGEXP STRING &optional START
     This function returns the index of the start of the first match for
     the regular expression REGEXP in STRING, or `nil' if there is no
     match.  If START is non-`nil', the search starts at that index in
     STRING.

     For example,

          (string-match
           "quick" "The quick brown fox jumped quickly.")
               => 4
          (string-match
           "quick" "The quick brown fox jumped quickly." 8)
               => 27

     The index of the first character of the string is 0, the index of
     the second character is 1, and so on.

     After this function returns, the index of the first character
     beyond the match is available as `(match-end 0)'.  See Match Data.

          (string-match
           "quick" "The quick brown fox jumped quickly." 8)
               => 27

          (match-end 0)
               => 32

     The `match-beginning' and `match-end' functions are described
     together; see Match Data.

 - Function: looking-at REGEXP
     This function determines whether the text in the current buffer
     directly following point matches the regular expression REGEXP.
     "Directly following" means precisely that: the search is
     "anchored" and it must succeed starting with the first character
     following point.  The result is `t' if so, `nil' otherwise.

     This function does not move point, but it updates the match data,
     which you can access using `match-beginning' or `match-end'.
     See Match Data.

     In this example, point is located directly before the `T'.  If it
     were anywhere else, the result would be `nil'.

          ---------- Buffer: foo ----------
          I read "-!-The cat in the hat
          comes back" twice.
          ---------- Buffer: foo ----------

          (looking-at "The cat in the hat$")
               => t

Replacement
===========

 - Function: perform-replace FROM-STRING REPLACEMENTS QUERY-FLAG
          REGEXP-FLAG DELIMITED-FLAG &optional REPEAT-COUNT MAP
     This function is the guts of `query-replace' and related commands.
     It searches for occurrences of FROM-STRING and replaces some or
     all of them.  If QUERY-FLAG is `nil', it replaces all occurrences;
     otherwise, it asks the user what to do about each one.

     If REGEXP-FLAG is non-`nil', then FROM-STRING is considered a
     regular expression; otherwise, it must match literally.  If
     DELIMITED-FLAG is non-`nil', then only replacements surrounded by
     word boundaries are considered.

     The argument REPLACEMENTS specifies what to replace occurrences
     with.  If it is a string, that string is used.  It can also be a
     list of strings, to be used in cyclic order.

     If REPEAT-COUNT is non-`nil', it should be an integer, the number
     of occurrences to consider.  In this case, `perform-replace'
     returns after considering that many occurrences.

     Normally, the keymap `query-replace-map' defines the possible user
     responses.  The argument MAP, if non-`nil', is a keymap to use
     instead of `query-replace-map'.

 - Variable: query-replace-map
     This variable holds a special keymap that defines the valid user
     responses for `query-replace' and related functions, as well as
     `y-or-n-p' and `map-y-or-n-p'.  It is special in two ways:

        * The "key bindings" are not commands, just symbols that are
          meaningful to the functions that use this map.

        * Prefix keys are not supported; each key binding must be for a
          single event key sequence.  This is because the functions
          don't use read key sequence to get the input; instead, they
          read a single event and look it up "by hand."

   Here are the meaningful "bindings" for `query-replace-map'.  Several
of them are meaningful only for `query-replace' and friends.

`act'
     Do take the action.  The action being considered--in other words,
     "yes."

`skip'
     Do not take action for this question--in other words, "no."

`exit'
     Answer this question "no," and don't ask any more.

`act-and-exit'
     Answer this question "yes," and don't ask any more.

`act-and-show'
     Answer this question "yes," but show the results--don't advance
     yet.

`automatic'
     Answer this question and all subsequent questions in the series
     with "yes," without further user interaction.

`backup'
     Move back to the previous place that a question was asked about.

`edit'
     Enter a recursive edit to deal with this item--instead of any
     other answer.

`delete-and-edit'
     Delete the text being considered, then enter a recursive edit to
     replace it.

`recenter'
     Redisplay and center the window, then ask the same question again.

`quit'
     Perform a quit right away.  Only the `y-or-n-p' functions use this
     answer.

`help'
     Display some help, then ask again.

The Match Data
==============

   Emacs keeps track of the positions of the start and end of segments
of text found during a regular expression search.  This means, for
example, that you can search for a complex pattern, such as a date in
an Rmail message, and extract parts of it.

   Because the match data normally describe the most recent search only,
you must be careful not to do another search inadvertently between the
search you wish to refer back to and the use of the match data.  If you
can't avoid another intervening search, you must save and restore the
match data around it, to prevent it from being overwritten.

Simple Match Data Access
------------------------

   This section explains how to use the match data to find the starting
point or ending point of the text that was matched by a particular
search, or by a particular parenthetical subexpression of a regular
expression.

 - Function: match-beginning COUNT
     This function returns the position of the start of text matched by
     the last regular expression searched for.  COUNT, a number,
     specifies a subexpression whose start position is the value.  If
     COUNT is zero, then the value is the position of the text matched
     by the whole regexp.  If COUNT is greater than zero, then the
     value is the position of the beginning of the text matched by the
     COUNTth subexpression, regardless of whether it was used in the
     final match.

     Subexpressions of a regular expression are those expressions
     grouped inside of parentheses, `\(...\)'.  The COUNTth
     subexpression is found by counting occurrences of `\(' from the
     beginning of the whole regular expression.  The first
     subexpression is numbered 1, the second 2, and so on.

     The value is `nil' for a parenthetical grouping inside of a `\|'
     alternative that wasn't used in the match.

     The `match-end' function is similar to the `match-beginning'
     function except that it returns the position of the end of the
     matched text.

     Here is an example, with a comment showing the numbers of the
     positions in the text:

          (string-match
           "\\(qu\\)\\(ick\\)" "The quick fox jumped quickly.")
               => 4            ;^^^^^^^^^^
                               ;0123456789

          (match-beginning 1)               ; The beginning of the match
               => 4                         ;   with `qu' is at index 4.

          (match-beginning 2)               ; The beginning of the match
               => 6                         ;   with `ick' is at index 6.

          (match-end 1)                     ; The end of the match
               => 6                         ;   with `qu' is at index 6.

          (match-end 2)                     ; The end of the match
               => 9                         ;   with `ick' is at index 9.

     Here is another example.  Before the form is evaluated, point is
     located at the beginning of the line.  After evaluating the search
     form, point is located on the line between the space and the word
     `in'.  The beginning of the entire match is at the 9th character
     of the buffer (`T'), and the beginning of the match for the first
     subexpression is at the 13th character (`c').

          (list
            (re-search-forward "The \\(cat \\)")
            (match-beginning 0)
            (match-beginning 1))
              => (t 9 13)

          ---------- Buffer: foo ----------
          I read "The cat -!-in the hat comes back" twice.
                  ^   ^
                  9  13
          ---------- Buffer: foo ----------

     (Note that in this case, the index returned is a buffer position;
     the first character of the buffer counts as 1.)

 - Function: match-end COUNT
     This function returns the position of the end of text matched by
     the last regular expression searched for.  This function is
     otherwise similar to `match-beginning'.

Replacing the Text That Matched
-------------------------------

   This function replaces the text matched by the last search with
REPLACEMENT.

 - Function: replace-match REPLACEMENT &optional FIXEDCASE LITERAL
     If FIXEDCASE is non-`nil', then the case of the replacement text
     is not changed; otherwise, the replacement text is converted to a
     different case depending upon the capitalization of the text to be
     replaced.  If the original text is all upper case, the replacement
     text is converted to upper case, except when all of the words in
     the original text are only one character long.  In that event, the
     replacement text is capitalized.  If *all* of the words in the
     original text are capitalized, then all of the words in the
     replacement text are capitalized.

     If LITERAL is non-`nil', then REPLACEMENT is inserted exactly as
     it is, the only alterations being case changes as needed.  If it
     is `nil' (the default), then the character `\' is treated
     specially.  If a `\' appears in REPLACEMENT, then it must be part
     of one of the following sequences:

    `\&'
          `\&' stands for the entire text being replaced.

    `\N'
          `\N' stands for the Nth subexpression in the original regexp.
          Subexpressions are those expressions grouped inside of
          `\(...\)'.  N is a digit.

    `\\'
          `\\' stands for a single `\' in the replacement text.

     `replace-match' leaves point at the end of the replacement text,
     and returns `t'.

Accessing the Entire Match Data
-------------------------------

   The functions `match-data' and `store-match-data' let you read or
write the entire match data, all at once.

 - Function: match-data
     This function returns a new list containing all the information on
     what text the last search matched.  Element zero is the position
     of the beginning of the match for the whole expression; element
     one is the position of the end of the match for the expression.
     The next two elements are the positions of the beginning and end
     of the match for the first subexpression.  In general, element

     number 2N corresponds to `(match-beginning N)'; and element

     number 2N + 1 corresponds to `(match-end N)'.

     All the elements are markers or `nil' if matching was done on a
     buffer, and all are integers or `nil' if matching was done on a
     string with `string-match'.  (In Emacs 18 and earlier versions,
     markers were used even for matching on a string, except in the case
     of the integer 0.)

     As always, there must be no possibility of intervening searches
     between the call to a search function and the call to `match-data'
     that is intended to access the match-data for that search.

          (match-data)
               =>  (#<marker at 9 in foo>
                    #<marker at 17 in foo>
                    #<marker at 13 in foo>
                    #<marker at 17 in foo>)

 - Function: store-match-data MATCH-LIST
     This function sets the match data from the elements of MATCH-LIST,
     which should be a list that was the value of a previous call to
     `match-data'.

     If MATCH-LIST refers to a buffer that doesn't exist, you don't get
     an error; that sets the match data in a meaningless but harmless
     way.

Saving and Restoring the Match Data
-----------------------------------

   All asynchronous process functions (filters and sentinels) and
functions that use `recursive-edit' should save and restore the match
data if they do a search or if they let the user type arbitrary
commands.  Saving the match data is useful in other cases as
well--whenever you want to access the match data resulting from an
earlier search, notwithstanding another intervening search.

   This example shows the problem that can arise if you fail to attend
to this requirement:

     (re-search-forward "The \\(cat \\)")
          => 48
     (foo)                   ; Perhaps `foo' does
                             ;   more searching.
     (match-end 0)
          => 61              ; Unexpected result---not 48!

   In Emacs versions 19 and later, you can save and restore the match
data with `save-match-data':

 - Special Form: save-match-data BODY...
     This special form executes BODY, saving and restoring the match
     data around it.  This is useful if you wish to do a search without
     altering the match data that resulted from an earlier search.

   You can use `store-match-data' together with `match-data' to imitate
the effect of the special form `save-match-data'.  This is useful for
writing code that can run in Emacs 18.  Here is how:

     (let ((data (match-data)))
       (unwind-protect
           ...   ; May change the original match data.
         (store-match-data data)))

Standard Regular Expressions Used in Editing
============================================

   Here are the regular expressions standardly used in editing:

 - Variable: page-delimiter
     This is the regexp describing line-beginnings that separate pages.
     The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"').

 - Variable: paragraph-separate
     This is the regular expression for recognizing the beginning of a
     line that separates paragraphs.  (If you change this, you may have
     to change `paragraph-start' also.)  The default value is `"^[
     \t\f]*$"', which is a line that consists entirely of spaces, tabs,
     and form feeds.

 - Variable: paragraph-start
     This is the regular expression for recognizing the beginning of a
     line that starts *or* separates paragraphs.  The default value is
     `"^[ \t\n\f]"', which matches a line starting with a space, tab,
     newline, or form feed.

 - Variable: sentence-end
     This is the regular expression describing the end of a sentence.
     (All paragraph boundaries also end sentences, regardless.)  The
     default value is:

          "[.?!][]\"')}]*\\($\\|\t\\| \\)[ \t\n]*"

     This means a period, question mark or exclamation mark, followed
     by a closing brace, followed by tabs, spaces or new lines.

     For a detailed explanation of this regular expression, see
     Regexp Example.

Searching and Case
==================

   By default, searches in Emacs ignore the case of the text they are
searching through; if you specify searching for `FOO', then `Foo' or
`foo' is also considered a match.  Regexps, and in particular character
sets, are included: thus, `[aB]' would match `a' or `A' or `b' or `B'.

   If you do not want this feature, set the variable `case-fold-search'
to `nil'.  Then all letters must match exactly, including case.  This
is a per-buffer-local variable; altering the variable affects only the
current buffer.  (see Intro to Buffer-Local.)  Alternatively, you
may change the value of `default-case-fold-search', which is the
default value of `case-fold-search' for buffers that do not override it.

 - User Option: case-replace
     This variable determines whether `query-replace' should preserve
     case in replacements.  If the variable is `nil', then case need
     not be preserved.

 - User Option: case-fold-search
     This buffer-local variable determines whether searches should
     ignore case.  If the variable is `nil' they do not ignore case;
     otherwise they do ignore case.

 - Variable: default-case-fold-search
     The value of this variable is the default value for
     `case-fold-search' in buffers that do not override it.  This is the
     same as `(default-value 'case-fold-search)'.

Syntax Tables
*************

   A "syntax table" provides Emacs with the information that determines
the syntactic use of each character in a buffer.  This information is
used by the parsing commands, the complex movement commands, and others
to determine where words, symbols, and other syntactic constructs begin
and end.  The current syntax table controls the meaning of the word
motion functions (see Word Motion.) and the list motion functions
(see List Motion.) as well as the functions in this chapter.

   A syntax table is a vector of 256 elements; it contains one entry for
each of the 256 ASCII characters of an 8-bit byte.  Each element is an
integer that encodes the syntax of the character in question.

   Syntax tables are used only for moving across text, not for the GNU
Emacs Lisp reader.  GNU Emacs Lisp uses built-in syntactic rules when
reading Lisp expressions, and these rules cannot be changed.

   Each buffer has its own major mode, and each major mode has its own
idea of the syntactic class of various characters.  For example, in Lisp
mode, the character `;' begins a comment, but in C mode, it terminates
a statement.  To support these variations, Emacs makes the choice of
syntax table local to each buffer.  Typically, each major mode has its
own syntax table and installs that table in each buffer which uses that
mode.  Changing this table alters the syntax in all those buffers as
well as in any buffers subsequently put in that mode.  Occasionally
several similar modes share one syntax table.  See Example Major Modes,
for an example of how to set up a syntax table.

 - Function: syntax-table-p OBJECT
     This function returns `t' if OBJECT is a vector of length 256
     elements.  This means that the vector may be a syntax table.
     However, according to this test, any vector of length 256 is
     considered to be a syntax table, no matter what its contents.

Syntax Descriptors
==================

   This section describes the syntax classes and flags that denote the
syntax of a character, and how they are represented as a "syntax
descriptor", which is a Lisp string that you pass to
`modify-syntax-entry' to specify the desired syntax.

   Emacs defines twelve "syntax classes".  Each syntax table puts each
character into one class.  There is no necessary relationship between
the class of a character in one syntax table and its class in any other
table.

   Each class is designated by a mnemonic character which serves as the
name of the class when you need to specify a class.  Usually the
designator character is one which is frequently put in that class;
however, its meaning as a designator is unvarying and independent of how
it is actually classified.

   A syntax descriptor is a Lisp string which specifies a syntax class,
a matching character (unused except for parenthesis classes) and flags.
The first character is the designator for a syntax class.  The second
character is the character to match; if it is unused, put a space there.
Then come the characters for any desired flags.  If no matching
character or flags are needed, one character is sufficient.

   Thus, the descriptor for the character `*' in C mode is `. 23'
(i.e., punctuation, matching character slot unused, second character of
a comment-starter, first character of an comment-ender), and the entry
for `/' is `. 14' (i.e., punctuation, matching character slot unused,
first character of a comment-starter, second character of a
comment-ender).

Table of Syntax Classes
-----------------------

   Here is a summary of the classes, the characters that stand for them,
their meanings, and examples of their use.

 - Syntax class: whitespace character
     "Whitespace characters" (designated with ` ' or `-') separate
     symbols and words from each other.  Typically, whitespace
     characters have no other syntactic use, and multiple whitespace
     characters are syntactically equivalent to a single one.  Space,
     tab, newline and formfeed are almost always considered whitespace.

 - Syntax class: word constituent
     "Word constituents" (designated with `w') are parts of normal
     English words and are typically used in variable and command names
     in programs.  All upper and lower case letters and the digits are
     typically word constituents.

 - Syntax class: symbol constituent
     "Symbol constituents" (designated with `_') are the extra
     characters that are used in variable and command names along with
     word constituents.  For example, the symbol constituents class is
     used in Lisp mode to indicate that certain characters may be part
     of symbol names even though they are not part of English words.
     These characters are `$&*+-_<>'.  In standard C, the only
     non-word-constituent character that is valid in symbols is
     underscore (`_').

 - Syntax class: punctuation character
     "Punctuation characters" (`.') are those characters that are used
     as punctuation in English, or are used in some way in a programming
     language to separate symbols from one another.  Most programming
     language modes, including Emacs Lisp mode, have no characters in
     this class since the few characters that are not symbol or word
     constituents all have other uses.

 - Syntax class: open parenthesis character
 - Syntax class: close parenthesis character
     Open and close "parenthesis characters" are characters used in
     dissimilar pairs to surround sentences or expressions.  Such a
     grouping is begun with an open parenthesis character and
     terminated with a close.  Each open parenthesis character matches
     a particular close parenthesis character, and vice versa.
     Normally, Emacs indicates momentarily the matching open
     parenthesis when you insert a close parenthesis.  See Blinking.

     The class of open parentheses is designated with `(', and that of
     close parentheses with `)'.

     In English text, and in C code, the parenthesis pairs are `()',
     `[]', and `{}'.  In Emacs Lisp, the delimiters for lists and
     vectors (`()' and `[]') are classified as parenthesis characters.

 - Syntax class: string quote
     "String quote characters" (designated with `"') is used to delimit
     string constants in many languages, including Lisp and C.  The
     same string quote character appears at the beginning and the end
     of a string.  Such quoted strings do not nest.

     The parsing facilities of Emacs consider a string as a single
     token.  The usual syntactic meanings of the characters in the
     string are suppressed.

     The Lisp modes have two string quote characters: double-quote (`"')
     and vertical bar (`|').  `|' is not used in Emacs Lisp, but it is
     used in Common Lisp.  C also has two string quote characters:
     double-quote for strings, and single-quote (`'') for character
     constants.

     English text has no string quote characters because English is not
     a programming language.  Although quotation marks are used in
     English, we do not want them to turn off the usual syntactic
     properties of other characters in the quotation.

 - Syntax class: escape
     An "escape character" (designated with `\') starts an escape
     sequence such as is used in C string and character constants.  The
     character `\' belongs to this class in both C and Lisp.  (In C, it
     is used thus only inside strings, but it turns out to cause no
     trouble to treat it this way throughout C code.)

     Characters in this class count as part of words if
     `words-include-escapes' is non-`nil'.  See Word Motion.

 - Syntax class: character quote
     A "character quote character" (designated with `/') quotes the
     following character so that it loses its normal syntactic meaning.
     This differs from an escape character in that only the character
     immediately following is ever affected.

     Characters in this class count as part of words if
     `words-include-escapes' is non-`nil'.  See Word Motion.

     This class is not currently used in any standard Emacs modes.

 - Syntax class: paired delimiter
     "Paired delimiter characters" (designated with `$') are like
     string quote characters except that the syntactic properties of the
     characters between the delimiters are not suppressed.  Only TeX
     mode uses a paired identical delimiter presently--the `$' that
     begins and ends math mode.

 - Syntax class: expression prefix
     An "expression prefix operator" (designated with `'') is used for
     syntactic operators that are part of an expression if they appear
     next to one but are not part of an adjoining symbol.  These
     characters in Lisp include the apostrophe, `'' (used for quoting),
     the comma, `,' (used in macros), and `#' (used in the read syntax
     for certain data types).

 - Syntax class: comment starter
 - Syntax class: comment ender
     The "comment starter" and "comment ender" characters are used in
     different languages to delimit comments.  These classes are
     designated with `<' and `>', respectively.

     English text has no comment characters.  In Lisp, the semicolon
     (`;') starts a comment and a newline or formfeed ends one.

Syntax Flags
------------

   In addition to the classes, entries for characters in a syntax table
can include flags.  There are six possible flags, represented by the
characters `1', `2', `3', `4', `b' and `p'.

   All the flags except `p' are used to describe multi-character
comment delimiters.  The digit flags indicate that a character can
*also* be part of a comment sequence, in addition to the syntactic
properties associated with its character class.  The flags are
independent of the class and each other for the sake of characters such
as `*' in C mode, which is a punctuation character, *and* the second
character of a start-of-comment sequence (`/*'), *and* the first
character of an end-of-comment sequence (`*/').

   The flags for a character C are:

   * `1' means C is the start of a two-character comment start sequence.

   * `2' means C is the second character of such a sequence.

   * `3' means C is the start of a two-character comment end sequence.

   * `4' means C is the second character of such a sequence.

   * `b' means that C as a comment delimiter belongs to the alternative
     "b" comment style.

     Emacs can now supports two comment styles simultaneously.  (This
     is for the sake of C++.)  More specifically, it can recognize two
     different comment-start sequences.  Both must share the same first
     character; only the second character may differ.  Mark the second
     character of the "b"-style comment start sequence with the `b'
     flag.

     The two styles of comment can have different comment-end
     sequences.  A comment-end sequence (one or two characters) applies
     to the "b" style if its first character has the `b' flag set;
     otherwise, it applies to the "a" style.

     The appropriate comment syntax settings for C++ are as follows:

    `/'
          `124b'

    `*'
          `23'

    newline
          `>b'

     Thus `/*' is a comment-start sequence for "a" style, `//' is a
     comment-start sequence for "b" style, `*/' is a comment-end
     sequence for "a" style, and newline is a comment-end sequence for
     "b" style.

   * `p' identifies an additional "prefix character" for Lisp syntax.
     These characters are treated as whitespace when they appear between
     expressions.  When they appear within an expression, they are
     handled according to their usual syntax codes.

     The function `backward-prefix-chars' moves back over these
     characters, as well as over characters whose primary syntax class
     is prefix (`'').