This is ../../info/elisp, produced by makeinfo version 4.13 from
elisp.texi.

This is edition 3.0 of the GNU Emacs Lisp Reference Manual,
corresponding to Emacs version 23.4.

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999,
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
2012  Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with the Invariant Sections being "GNU General Public
     License," with the Front-Cover texts being "A GNU Manual," and
     with the Back-Cover Texts as in (a) below.  A copy of the license
     is included in the section entitled "GNU Free Documentation
     License."

     (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
     modify this GNU manual.  Buying copies from the FSF supports it in
     developing GNU and promoting software freedom."

INFO-DIR-SECTION GNU Emacs Lisp
START-INFO-DIR-ENTRY
* Elisp: (elisp).       The Emacs Lisp Reference Manual.
END-INFO-DIR-ENTRY


File: elisp,  Node: Regexp Special,  Next: Char Classes,  Up: Syntax of Regexps

34.3.1.1 Special Characters in Regular Expressions
..................................................

Here is a list of the characters that are special in a regular
expression.

`.' (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 that begins
     with `a' and ends with `b'.

`*'
     is not a construct by itself; it is a postfix operator that means
     to match the preceding regular expression repetitively as many
     times as possible.  Thus, `o*' matches any number of `o's
     (including no `o's).

     `*' always applies to the _smallest_ possible preceding
     expression.  Thus, `fo*' has a repeating `o', not a repeating
     `fo'.  It matches `f', `fo', `foo', and so on.

     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 the hope that
     that will make it possible to match the rest of the pattern.  For
     example, in 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.

     *Warning:* Nested repetition operators can run for an indefinitely
     long time, if they lead to ambiguous matching.  For example,
     trying to match the regular expression `\(x+y*\)*a' against the
     string `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz' could take hours
     before it ultimately fails.  Emacs must try each way of grouping
     the `x's before concluding that none of them can work.  Even
     worse, `\(x*\)*' can match the null string in infinitely many
     ways, so it causes an infinite loop.  To avoid these problems,
     check nested repetitions carefully, to make sure that they do not
     cause combinatorial explosions in backtracking.

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

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

`*?', `+?', `??'
     These are "non-greedy" variants of the operators `*', `+' and `?'.
     Where those operators match the largest possible substring
     (consistent with matching the entire containing expression), the
     non-greedy variants match the smallest possible substring
     (consistent with matching the entire containing expression).

     For example, the regular expression `c[ad]*a' when applied to the
     string `cdaaada' matches the whole string; but the regular
     expression `c[ad]*?a', applied to that same string, matches just
     `cda'.  (The smallest possible match here for `[ad]*?' that
     permits the whole expression to match is `d'.)

`[ ... ]'
     is a "character alternative", which begins with `[' and is
     terminated by `]'.  In the simplest case, the characters between
     the two brackets are what this character alternative can match.

     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).  It follows that `c[ad]*r' matches `cr', `car',
     `cdr', `caddaar', etc.

     You can also include character ranges in a character alternative,
     by writing the starting and ending characters with a `-' between
     them.  Thus, `[a-z]' matches any lower-case ASCII letter.  Ranges
     may be intermixed freely with individual characters, as in
     `[a-z$%.]', which matches any lower case ASCII letter or `$', `%'
     or period.

     Note that the usual regexp special characters are not special
     inside a character alternative.  A completely different set of
     characters is special inside character alternatives: `]', `-' and
     `^'.

     To include a `]' in a character alternative, you must make it the
     first character.  For example, `[]a]' matches `]' or `a'.  To
     include a `-', write `-' as the first or last character of the
     character alternative, or put it after a range.  Thus, `[]-]'
     matches both `]' and `-'.

     To include `^' in a character alternative, put it anywhere but at
     the beginning.

     If a range starts with a unibyte character C and ends with a
     multibyte character C2, the range is divided into two parts: one
     is `C..?\377', the other is `C1..C2', where C1 is the first
     character of the charset to which C2 belongs.

     A character alternative can also specify named character classes
     (*note Char Classes::).  This is a POSIX feature whose syntax is
     `[:CLASS:]'.  Using a character class is equivalent to mentioning
     each of the characters in that class; but the latter is not
     feasible in practice, since some classes include thousands of
     different characters.

`[^ ... ]'
     `[^' begins a "complemented character alternative".  This 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 alternative unless it is the
     first character.  The character following the `^' is treated as if
     it were first (in other words, `-' and `]' are not special there).

     A complemented character alternative can match a newline, unless
     newline is mentioned as one of the characters not to match.  This
     is in contrast to the handling of regexps in programs such as
     `grep'.

     You can specify named character classes, just like in character
     alternatives.  For instance, `[^[:ascii:]]' matches any non-ASCII
     character.  *Note Char Classes::.

`^'
     When matching a buffer, `^' matches the empty string, but only at
     the beginning of a line in the text being matched (or the
     beginning of the accessible portion of the buffer).  Otherwise it
     fails to match anything.  Thus, `^foo' matches a `foo' that occurs
     at the beginning of a line.

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

     For historical compatibility reasons, `^' can be used only at the
     beginning of the regular expression, or after `\(', `\(?:' or `\|'.

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

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

     For historical compatibility reasons, `$' can be used only at the
     end of the regular expression, or before `\)' or `\|'.

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

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

     Note that `\' also has special meaning in the read syntax of Lisp
     strings (*note 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; quote the special character
anyway, regardless of where it appears.

   As a `\' is not special inside a character alternative, it can never
remove the special meaning of `-' or `]'.  So you should not quote
these characters when they have no special meaning either.  This would
not clarify anything, since backslashes can legitimately precede these
characters where they _have_ special meaning, as in `[^\]' (`"[^\\]"'
for Lisp string syntax), which matches any single character except a
backslash.

   In practice, most `]' that occur in regular expressions close a
character alternative and hence are special.  However, occasionally a
regular expression may try to match a complex pattern of literal `['
and `]'.  In such situations, it sometimes may be necessary to
carefully parse the regexp from the start to determine which square
brackets enclose a character alternative.  For example, `[^][]]'
consists of the complemented character alternative `[^][]' (which
matches any single character that is not a square bracket), followed by
a literal `]'.

   The exact rules are that at the beginning of a regexp, `[' is
special and `]' not.  This lasts until the first unquoted `[', after
which we are in a character alternative; `[' is no longer special
(except when it starts a character class) but `]' is special, unless it
immediately follows the special `[' or that `[' followed by a `^'.
This lasts until the next special `]' that does not end a character
class.  This ends the character alternative and restores the ordinary
syntax of regular expressions; an unquoted `[' is special again and a
`]' not.


File: elisp,  Node: Char Classes,  Next: Regexp Backslash,  Prev: Regexp Special,  Up: Syntax of Regexps

34.3.1.2 Character Classes
..........................

Here is a table of the classes you can use in a character alternative,
and what they mean:

`[:ascii:]'
     This matches any ASCII character (codes 0-127).

`[:alnum:]'
     This matches any letter or digit.  (At present, for multibyte
     characters, it matches anything that has word syntax.)

`[:alpha:]'
     This matches any letter.  (At present, for multibyte characters, it
     matches anything that has word syntax.)

`[:blank:]'
     This matches space and tab only.

`[:cntrl:]'
     This matches any ASCII control character.

`[:digit:]'
     This matches `0' through `9'.  Thus, `[-+[:digit:]]' matches any
     digit, as well as `+' and `-'.

`[:graph:]'
     This matches graphic characters--everything except ASCII control
     characters, space, and the delete character.

`[:lower:]'
     This matches any lower-case letter, as determined by the current
     case table (*note Case Tables::).  If `case-fold-search' is
     non-`nil', this also matches any upper-case letter.

`[:multibyte:]'
     This matches any multibyte character (*note Text
     Representations::).

`[:nonascii:]'
     This matches any non-ASCII character.

`[:print:]'
     This matches printing characters--everything except ASCII control
     characters and the delete character.

`[:punct:]'
     This matches any punctuation character.  (At present, for multibyte
     characters, it matches anything that has non-word syntax.)

`[:space:]'
     This matches any character that has whitespace syntax (*note
     Syntax Class Table::).

`[:unibyte:]'
     This matches any unibyte character (*note Text Representations::).

`[:upper:]'
     This matches any upper-case letter, as determined by the current
     case table (*note Case Tables::).  If `case-fold-search' is
     non-`nil', this also matches any lower-case letter.

`[:word:]'
     This matches any character that has word syntax (*note Syntax
     Class Table::).

`[:xdigit:]'
     This matches the hexadecimal digits: `0' through `9', `a' through
     `f' and `A' through `F'.


File: elisp,  Node: Regexp Backslash,  Prev: Char Classes,  Up: Syntax of Regexps

34.3.1.3 Backslash Constructs in Regular Expressions
....................................................

For the most part, `\' followed by any character matches only that
character.  However, there are several exceptions: certain
two-character sequences starting with `\' that have special meanings.
(The character after the `\' in such a sequence is always ordinary when
used on its own.)  Here is a table of the special `\' 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 `\|'.

     If you need full backtracking capability to handle multiple uses of
     `\|', use the POSIX regular expression functions (*note POSIX
     Regexps::).

`\{M\}'
     is a postfix operator that repeats the previous pattern exactly M
     times.  Thus, `x\{5\}' matches the string `xxxxx' and nothing
     else.  `c[ad]\{3\}r' matches string such as `caaar', `cdddr',
     `cadar', and so on.

`\{M,N\}'
     is a more general postfix operator that specifies repetition with a
     minimum of M repeats and a maximum of N repeats.  If M is omitted,
     the minimum is 0; if N is omitted, there is no maximum.

     For example, `c[ad]\{1,2\}r' matches the strings `car', `cdr',
     `caar', `cadr', `cdar', and `cddr', and nothing else.
     `\{0,1\}' or `\{,1\}' is equivalent to `?'.
     `\{0,\}' or `\{,\}' is equivalent to `*'.
     `\{1,\}' is equivalent to `+'.

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

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

       2. To enclose a complicated expression for the postfix operators
          `*', `+' and `?' to operate on.  Thus, `ba\(na\)*' matches
          `ba', `bana', `banana', `bananana', etc., with any number
          (zero or more) of `na' strings.

       3. To record a matched substring for future reference with
          `\DIGIT' (see below).

     This last application is not a consequence of the idea of a
     parenthetical grouping; it is a separate feature that was assigned
     as a second meaning to the same `\( ... \)' construct because, in
     practice, there was usually no conflict between the two meanings.
     But occasionally there is a conflict, and that led to the
     introduction of shy groups.

`\(?: ... \)'
     is the "shy group" construct.  A shy group serves the first two
     purposes of an ordinary group (controlling the nesting of other
     operators), but it does not get a number, so you cannot refer back
     to its value with `\DIGIT'.  Shy groups are particularly useful
     for mechanically-constructed regular expressions, because they can
     be added automatically without altering the numbering of ordinary,
     non-shy groups.

     Shy groups are also called "non-capturing" or "unnumbered groups".

`\(?NUM: ... \)'
     is the "explicitly numbered group" construct.  Normal groups get
     their number implicitly, based on their position, which can be
     inconvenient.  This construct allows you to force a particular
     group number.  There is no particular restriction on the numbering,
     e.g. you can have several groups with the same number in which case
     the last one to match (i.e. the rightmost match) will win.
     Implicitly numbered groups always get the smallest integer larger
     than the one of any previous group.

`\DIGIT'
     matches the same text that matched the DIGITth occurrence of a
     grouping (`\( ... \)') construct.

     In other words, after the end of a group, the matcher remembers the
     beginning and end of the text matched by that group.  Later on in
     the regular expression you can use `\' followed by DIGIT to match
     that same text, whatever it may have been.

     The strings matching the first nine grouping constructs appearing
     in the entire regular expression passed to a search or matching
     function 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 grouping 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.

     If a `\( ... \)' construct matches more than once (which can
     happen, for instance, if it is followed by `*'), only the last
     match is recorded.

     If a particular grouping construct in the regular expression was
     never matched--for instance, if it appears inside of an
     alternative that wasn't used, or inside of a repetition that
     repeated zero times--then the corresponding `\DIGIT' construct
     never matches anything.  To use an artificial example,
     `\(foo\(b*\)\|lose\)\2' cannot match `lose': the second
     alternative inside the larger group matches it, but then `\2' is
     undefined and can't match anything.  But it can match `foobb',
     because the first alternative matches `foob' and `\2' matches `b'.

`\w'
     matches any word-constituent character.  The editor syntax table
     determines which characters these are.  *Note 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 that represents a syntax code: thus, `w' for word
     constituent, `-' for whitespace, `(' for open parenthesis, etc.
     To represent whitespace syntax, use either `-' or a space
     character.  *Note Syntax Class Table::, for a list of syntax codes
     and the characters that stand for them.

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

`\cC'
     matches any character whose category is C.  Here C is a character
     that represents a category: thus, `c' for Chinese characters or
     `g' for Greek characters in the standard category table.

`\CC'
     matches any character whose category is not C.

   The following regular expression constructs match the empty
string--that is, they don't use up any characters--but whether they
match depends on the context.  For all, the beginning and end of the
accessible portion of the buffer are treated as if they were the actual
beginning and end of the buffer.

`\`'
     matches the empty string, but only at the beginning of the buffer
     or string being matched against.

`\''
     matches the empty string, but only at the end of the buffer or
     string being matched against.

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

`\b'
     matches the empty string, but only 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 at the beginning or end of the buffer (or string)
     regardless of what text appears next to it.

`\B'
     matches the empty string, but _not_ at the beginning or end of a
     word, nor at the beginning or end of the buffer (or string).

`\<'
     matches the empty string, but only at the beginning of a word.
     `\<' matches at the beginning of the buffer (or string) only if a
     word-constituent character follows.

`\>'
     matches the empty string, but only at the end of a word.  `\>'
     matches at the end of the buffer (or string) only if the contents
     end with a word-constituent character.

`\_<'
     matches the empty string, but only at the beginning of a symbol.  A
     symbol is a sequence of one or more word or symbol constituent
     characters.  `\_<' matches at the beginning of the buffer (or
     string) only if a symbol-constituent character follows.

`\_>'
     matches the empty string, but only at the end of a symbol.  `\_>'
     matches at the end of the buffer (or string) only if the contents
     end with a symbol-constituent character.

   Not every string is a valid regular expression.  For example, a
string that ends inside a character alternative without terminating `]'
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.


File: elisp,  Node: Regexp Example,  Next: Regexp Functions,  Prev: Syntax of Regexps,  Up: Regular Expressions

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

Here is a complicated regexp which was formerly used by Emacs to
recognize the end of a sentence together with any whitespace that
follows.  (Nowadays Emacs uses a similar but more complex default
regexp constructed by the function `sentence-end'.  *Note Standard
Regexps::.)

   First, we show the regexp as a string in Lisp syntax to distinguish
spaces from 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 this string, you will see the following:

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

In this output, tab and newline appear as themselves.

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

`[.?!]'
     The first part of the pattern is a character alternative that
     matches any one of three characters: period, question mark, and
     exclamation mark.  The match must begin with one of these three
     characters.  (This is one point where the new default regexp used
     by Emacs differs from the old.  The new value also allows some
     non-ASCII characters that end a sentence without any following
     whitespace.)

`[]\"')}]*'
     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 alternative,
     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 (optionally with a
     space), or a tab, or two spaces.  The double backslashes mark the
     parentheses and vertical bars as regular expression syntax; the
     parentheses delimit a group and the vertical bars separate
     alternatives.  The dollar sign is used to match the end of a line.

`[ \t\n]*'
     Finally, the last part of the pattern matches any additional
     whitespace beyond the minimum needed to end a sentence.


File: elisp,  Node: Regexp Functions,  Prev: Regexp Example,  Up: Regular Expressions

34.3.3 Regular Expression Functions
-----------------------------------

These functions operate on regular expressions.

 -- Function: regexp-quote string
     This function returns a regular expression whose only exact match
     is STRING.  Using this regular expression in `looking-at' will
     succeed only if the next characters in the buffer are STRING;
     using it in a search function will succeed if the text being
     searched contains STRING.

     This allows you to request an exact string match or search 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 that is the value of STRING, surrounded by
     whitespace:

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

 -- Function: regexp-opt strings &optional paren
     This function returns an efficient regular expression that will
     match any of the strings in the list STRINGS.  This is useful when
     you need to make matching or searching as fast as possible--for
     example, for Font Lock mode.

     If the optional argument PAREN is non-`nil', then the returned
     regular expression is always enclosed by at least one
     parentheses-grouping construct.  If PAREN is `words', then that
     construct is additionally surrounded by `\<' and `\>'.

     This simplified definition of `regexp-opt' produces a regular
     expression which is equivalent to the actual value (but not as
     efficient):

          (defun regexp-opt (strings paren)
            (let ((open-paren (if paren "\\(" ""))
                  (close-paren (if paren "\\)" "")))
              (concat open-paren
                      (mapconcat 'regexp-quote strings "\\|")
                      close-paren)))

 -- Function: regexp-opt-depth regexp
     This function returns the total number of grouping constructs
     (parenthesized expressions) in REGEXP.  This does not include shy
     groups (*note Regexp Backslash::).


File: elisp,  Node: Regexp Search,  Next: POSIX Regexps,  Prev: Regular Expressions,  Up: Searching and Matching

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

In GNU Emacs, you can search for the next match for a regular
expression either incrementally or not.  For incremental search
commands, see *note Regular Expression Search: (emacs)Regexp Search.
Here we describe only the search functions useful in programs.  The
principal one is `re-search-forward'.

   These search functions convert the regular expression to multibyte if
the buffer is multibyte; they convert the regular expression to unibyte
if the buffer is unibyte.  *Note Text Representations::.

 -- 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 match found.  It
     returns the new value of point.

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

     If REPEAT is supplied, it must be a positive number; the search is
     repeated that many times; each repetition starts at the end of the
     previous match.  If all these successive searches succeed, the
     search succeeds, moving point and returning its new value.
     Otherwise the search fails.  What `re-search-forward' does when
     the search fails depends on the value of NOERROR:

    `nil'
          Signal a `search-failed' error.

    `t'
          Do nothing and return `nil'.

    anything else
          Move point to LIMIT (or the end of the accessible portion of
          the buffer) and return `nil'.

     In the following example, point is initially before the `T'.
     Evaluating the search call moves point to the end of that line
     (between the `t' of `hat' and the newline).

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

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

          ---------- 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 to the starting point.  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 (and yet
     ends before the starting point).  The reason for this is that
     matching a regular expression at a given spot always works from
     beginning to end, and starts at a specified beginning position.

     A true mirror-image of `re-search-forward' would require a special
     feature for matching regular expressions from end to beginning.
     It's not worth the trouble of implementing that.

 -- 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)'.  *Note Match
     Data::.

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

          (match-end 0)
               => 32

 -- Function: string-match-p regexp string &optional start
     This predicate function does what `string-match' does, but it
     avoids modifying the 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 can succeed only 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' and `match-end'.
     *Note Match Data::.  If you need to test for a match without
     modifying the match data, use `looking-at-p', described below.

     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

 -- Function: looking-back regexp &optional limit greedy
     This function returns `t' if REGEXP matches text before point,
     ending at point, and `nil' otherwise.

     Because regular expression matching works only going forward, this
     is implemented by searching backwards from point for a match that
     ends at point.  That can be quite slow if it has to search a long
     distance.  You can bound the time required by specifying LIMIT,
     which says not to search before LIMIT.  In this case, the match
     that is found must begin at or after LIMIT.

     If GREEDY is non-`nil', this function extends the match backwards
     as far as possible, stopping when a single additional previous
     character cannot be part of a match for regexp.  When the match is
     extended, its starting position is allowed to occur before LIMIT.

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

          (looking-back "read \"" 3)
               => t
          (looking-back "read \"" 4)
               => nil

 -- Function: looking-at-p regexp
     This predicate function works like `looking-at', but without
     updating the match data.

 -- Variable: search-spaces-regexp
     If this variable is non-`nil', it should be a regular expression
     that says how to search for whitespace.  In that case, any group of
     spaces in a regular expression being searched for stands for use of
     this regular expression.  However, spaces inside of constructs
     such as `[...]' and `*', `+', `?' are not affected by
     `search-spaces-regexp'.

     Since this variable affects all regular expression search and match
     constructs, you should bind it temporarily for as small as possible
     a part of the code.


File: elisp,  Node: POSIX Regexps,  Next: Match Data,  Prev: Regexp Search,  Up: Searching and Matching

34.5 POSIX Regular Expression Searching
=======================================

The usual regular expression functions do backtracking when necessary
to handle the `\|' and repetition constructs, but they continue this
only until they find _some_ match.  Then they succeed and report the
first match found.

   This section describes alternative search functions which perform the
full backtracking specified by the POSIX standard for regular expression
matching.  They continue backtracking until they have tried all
possibilities and found all matches, so they can report the longest
match, as required by POSIX.  This is much slower, so use these
functions only when you really need the longest match.

   The POSIX search and match functions do not properly support the
non-greedy repetition operators (*note non-greedy: Regexp Special.).
This is because POSIX backtracking conflicts with the semantics of
non-greedy repetition.

 -- Command: posix-search-forward regexp &optional limit noerror repeat
     This is like `re-search-forward' except that it performs the full
     backtracking specified by the POSIX standard for regular expression
     matching.

 -- Command: posix-search-backward regexp &optional limit noerror repeat
     This is like `re-search-backward' except that it performs the full
     backtracking specified by the POSIX standard for regular expression
     matching.

 -- Function: posix-looking-at regexp
     This is like `looking-at' except that it performs the full
     backtracking specified by the POSIX standard for regular expression
     matching.

 -- Function: posix-string-match regexp string &optional start
     This is like `string-match' except that it performs the full
     backtracking specified by the POSIX standard for regular expression
     matching.


File: elisp,  Node: Match Data,  Next: Search and Replace,  Prev: POSIX Regexps,  Up: Searching and Matching

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

Emacs keeps track of the start and end positions of the segments of
text found during a search; this is called the "match data".  Thanks to
the match data, you can search for a complex pattern, such as a date in
a mail message, and then extract parts of the match under control of
the pattern.

   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.

* Menu:

* Replacing Match::       Replacing a substring that was matched.
* Simple Match Data::     Accessing single items of match data,
                            such as where a particular subexpression started.
* Entire Match Data::     Accessing the entire match data at once, as a list.
* Saving Match Data::     Saving and restoring the match data.


File: elisp,  Node: Replacing Match,  Next: Simple Match Data,  Up: Match Data

34.6.1 Replacing the Text that Matched
--------------------------------------

This function replaces all or part of the text matched by the last
search.  It works by means of the match data.

 -- Function: replace-match replacement &optional fixedcase literal
          string subexp
     This function replaces the text in the buffer (or in STRING) that
     was matched by the last search.  It replaces that text with
     REPLACEMENT.

     If you did the last search in a buffer, you should specify `nil'
     for STRING and make sure that the current buffer when you call
     `replace-match' is the one in which you did the searching or
     matching.  Then `replace-match' does the replacement by editing
     the buffer; it leaves point at the end of the replacement text, and
     returns `t'.

     If you did the search in a string, pass the same string as STRING.
     Then `replace-match' does the replacement by constructing and
     returning a new string.

     If FIXEDCASE is non-`nil', then `replace-match' uses the
     replacement text without case conversion; otherwise, it converts
     the replacement text depending upon the capitalization of the text
     to be replaced.  If the original text is all upper case, this
     converts the replacement text to upper case.  If all words of the
     original text are capitalized, this capitalizes all the words of
     the replacement text.  If all the words are one-letter and they
     are all upper case, they are treated as capitalized words rather
     than all-upper-case words.

     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', where N is a digit, stands for the text that matched
          the Nth subexpression in the original regexp.  Subexpressions
          are those expressions grouped inside `\(...\)'.  If the Nth
          subexpression never matched, an empty string is substituted.

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

     These substitutions occur after case conversion, if any, so the
     strings they substitute are never case-converted.

     If SUBEXP is non-`nil', that says to replace just subexpression
     number SUBEXP of the regexp that was matched, not the entire
     match.  For example, after matching `foo \(ba*r\)', calling
     `replace-match' with 1 as SUBEXP means to replace just the text
     that matched `\(ba*r\)'.

 -- Function: match-substitute-replacement replacement &optional
          fixedcase literal string subexp
     This function returns the text that would be inserted into the
     buffer by `replace-match', but without modifying the buffer.  It is
     useful if you want to present the user with actual replacement
     result, with constructs like `\N' or `\&' substituted with matched
     groups.  Arguments REPLACEMENT and optional FIXEDCASE, LITERAL,
     STRING and SUBEXP have the same meaning as for `replace-match'.


File: elisp,  Node: Simple Match Data,  Next: Entire Match Data,  Prev: Replacing Match,  Up: Match Data

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

This section explains how to use the match data to find out what was
matched by the last search or match operation, if it succeeded.

   You can ask about the entire matching text, or about a particular
parenthetical subexpression of a regular expression.  The COUNT
argument in the functions below specifies which.  If COUNT is zero, you
are asking about the entire match.  If COUNT is positive, it specifies
which subexpression you want.

   Recall that the subexpressions of a regular expression are those
expressions grouped with escaped 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.  Only regular expressions can have
subexpressions--after a simple string search, the only information
available is about the entire match.

   Every successful search sets the match data.  Therefore, you should
query the match data immediately after searching, before calling any
other function that might perform another search.  Alternatively, you
may save and restore the match data (*note Saving Match Data::) around
the call to functions that could perform another search.

   A search which fails may or may not alter the match data.  In the
past, a failing search did not do this, but we may change it in the
future.  So don't try to rely on the value of the match data after a
failing search.

 -- Function: match-string count &optional in-string
     This function returns, as a string, the text matched in the last
     search or match operation.  It returns the entire text if COUNT is
     zero, or just the portion corresponding to the COUNTth
     parenthetical subexpression, if COUNT is positive.

     If the last such operation was done against a string with
     `string-match', then you should pass the same string as the
     argument IN-STRING.  After a buffer search or match, you should
     omit IN-STRING or pass `nil' for it; but you should make sure that
     the current buffer when you call `match-string' is the one in
     which you did the searching or matching.

     The value is `nil' if COUNT is out of range, or for a
     subexpression inside a `\|' alternative that wasn't used or a
     repetition that repeated zero times.

 -- Function: match-string-no-properties count &optional in-string
     This function is like `match-string' except that the result has no
     text properties.

 -- Function: match-beginning count
     This function returns the position of the start of text matched by
     the last regular expression searched for, or a subexpression of it.

     If COUNT is zero, then the value is the position of the start of
     the entire match.  Otherwise, COUNT specifies a subexpression in
     the regular expression, and the value of the function is the
     starting position of the match for that subexpression.

     The value is `nil' for a subexpression inside a `\|' alternative
     that wasn't used or a repetition that repeated zero times.

 -- Function: match-end count
     This function is like `match-beginning' except that it returns the
     position of the end of the match, rather than the position of the
     beginning.

   Here is an example of using the match data, with a comment showing
the positions within the text:

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

     (match-string 0 "The quick fox jumped quickly.")
          => "quick"
     (match-string 1 "The quick fox jumped quickly.")
          => "qu"
     (match-string 2 "The quick fox jumped quickly.")
          => "ick"

     (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.  Point is initially located at the beginning
of the line.  Searching moves point to 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))
         => (17 9 13)

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

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


File: elisp,  Node: Entire Match Data,  Next: Saving Match Data,  Prev: Simple Match Data,  Up: Match Data

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

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

 -- Function: match-data &optional integers reuse reseat
     This function returns a list of positions (markers or integers)
     that record 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, and so on.  In general, element number 2N
     corresponds to `(match-beginning N)'; and element number 2N + 1
     corresponds to `(match-end N)'.

     Normally all the elements are markers or `nil', but if INTEGERS is
     non-`nil', that means to use integers instead of markers.  (In
     that case, the buffer itself is appended as an additional element
     at the end of the list, to facilitate complete restoration of the
     match data.)  If the last match was done on a string with
     `string-match', then integers are always used, since markers can't
     point into a string.

     If REUSE is non-`nil', it should be a list.  In that case,
     `match-data' stores the match data in REUSE.  That is, REUSE is
     destructively modified.  REUSE does not need to have the right
     length.  If it is not long enough to contain the match data, it is
     extended.  If it is too long, the length of REUSE stays the same,
     but the elements that were not used are set to `nil'.  The purpose
     of this feature is to reduce the need for garbage collection.

     If RESEAT is non-`nil', all markers on the REUSE list are reseated
     to point to nowhere.

     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: set-match-data match-list &optional reseat
     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'.  (More precisely, anything that has the same format
     will work.)

     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.

     If RESEAT is non-`nil', all markers on the MATCH-LIST list are
     reseated to point to nowhere.

     `store-match-data' is a semi-obsolete alias for `set-match-data'.


File: elisp,  Node: Saving Match Data,  Prev: Entire Match Data,  Up: Match Data

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

When you call a function that may do a search, you may need to save and
restore the match data around that call, if you want to preserve the
match data from an earlier search for later use.  Here is an example
that shows the problem that arises if you fail to save the match data:

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

   You can save and restore the match data with `save-match-data':

 -- Macro: save-match-data body...
     This macro executes BODY, saving and restoring the match data
     around it.  The return value is the value of the last form in BODY.

   You could use `set-match-data' together with `match-data' to imitate
the effect of the special form `save-match-data'.  Here is how:

     (let ((data (match-data)))
       (unwind-protect
           ...   ; Ok to change the original match data.
         (set-match-data data)))

   Emacs automatically saves and restores the match data when it runs
process filter functions (*note Filter Functions::) and process
sentinels (*note Sentinels::).


File: elisp,  Node: Search and Replace,  Next: Standard Regexps,  Prev: Match Data,  Up: Searching and Matching

34.7 Search and Replace
=======================

If you want to find all matches for a regexp in part of the buffer, and
replace them, the best way is to write an explicit loop using
`re-search-forward' and `replace-match', like this:

     (while (re-search-forward "foo[ \t]+bar" nil t)
       (replace-match "foobar"))

*Note Replacing the Text that Matched: Replacing Match, for a
description of `replace-match'.

   However, replacing matches in a string is more complex, especially
if you want to do it efficiently.  So Emacs provides a function to do
this.

 -- Function: replace-regexp-in-string regexp rep string &optional
          fixedcase literal subexp start
     This function copies STRING and searches it for matches for
     REGEXP, and replaces them with REP.  It returns the modified copy.
     If START is non-`nil', the search for matches starts at that index
     in STRING, so matches starting before that index are not changed.

     This function uses `replace-match' to do the replacement, and it
     passes the optional arguments FIXEDCASE, LITERAL and SUBEXP along
     to `replace-match'.

     Instead of a string, REP can be a function.  In that case,
     `replace-regexp-in-string' calls REP for each match, passing the
     text of the match as its sole argument.  It collects the value REP
     returns and passes that to `replace-match' as the replacement
     string.  The match-data at this point are the result of matching
     REGEXP against a substring of STRING.

   If you want to write a command along the lines of `query-replace',
you can use `perform-replace' to do the work.

 -- Function: perform-replace from-string replacements query-flag
          regexp-flag delimited-flag &optional repeat-count map start
          end
     This function is the guts of `query-replace' and related commands.
     It searches for occurrences of FROM-STRING in the text between
     positions START and END and replaces some or all of them.  If
     START is `nil' (or omitted), point is used instead, and the end of
     the buffer's accessible portion is used for END.

     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 REPLACEMENTS is a cons cell, `(FUNCTION . DATA)', this means to
     call FUNCTION after each match to get the replacement text.  This
     function is called with two arguments: DATA, and the number of
     replacements already made.

     If REPEAT-COUNT is non-`nil', it should be an integer.  Then it
     specifies how many times to use each of the strings in the
     REPLACEMENTS list before advancing cyclically to the next one.

     If FROM-STRING contains upper-case letters, then `perform-replace'
     binds `case-fold-search' to `nil', and it uses the `replacements'
     without altering the case of them.

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

     This function uses one of two functions to search for the next
     occurrence of FROM-STRING.  These functions are specified by the
     values of two variables: `replace-re-search-function' and
     `replace-search-function'.  The former is called when the argument
     REGEXP-FLAG is non-`nil', the latter when it is `nil'.

 -- Variable: query-replace-map
     This variable holds a special keymap that defines the valid user
     responses for `perform-replace' and the commands that use it, as
     well as `y-or-n-p' and `map-y-or-n-p'.  This map is unusual 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 being considered--in other words, "yes."

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

`exit'
     Answer this question "no," and give up on the entire series of
     questions, assuming that the answers will be "no."

`act-and-exit'
     Answer this question "yes," and give up on the entire series of
     questions, assuming that subsequent answers will be "no."

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

`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 question--instead of any
     other action that would normally be taken.

`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 `y-or-n-p' and related functions
     use this answer.

`help'
     Display some help, then ask again.

 -- Variable: multi-query-replace-map
     This variable holds a keymap that extends `query-replace-map' by
     providing additional keybindings that are useful in multi-buffer
     replacements.

 -- Variable: replace-search-function
     This variable specifies a function that `perform-replace' calls to
     search for the next string to replace.  Its default value is
     `search-forward'.  Any other value should name a function of 3
     arguments: the first 3 arguments of `search-forward' (*note String
     Search::).

 -- Variable: replace-re-search-function
     This variable specifies a function that `perform-replace' calls to
     search for the next regexp to replace.  Its default value is
     `re-search-forward'.  Any other value should name a function of 3
     arguments: the first 3 arguments of `re-search-forward' (*note
     Regexp Search::).


File: elisp,  Node: Standard Regexps,  Prev: Search and Replace,  Up: Searching and Matching

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

This section describes some variables that hold regular expressions
used for certain purposes in editing:

 -- User Option: page-delimiter
     This is the regular expression describing line-beginnings that
     separate pages.  The default value is `"^\014"' (i.e., `"^^L"' or
     `"^\C-l"'); this matches a line that starts with a formfeed
     character.

   The following two regular expressions should _not_ assume the match
always starts at the beginning of a line; they should not use `^' to
anchor the match.  Most often, the paragraph commands do check for a
match only at the beginning of a line, which means that `^' would be
superfluous.  When there is a nonzero left margin, they accept matches
that start after the left margin.  In that case, a `^' would be
incorrect.  However, a `^' is harmless in modes where a left margin is
never used.

 -- User Option: 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 matches a line that consists entirely of
     spaces, tabs, and form feeds (after its left margin).

 -- User Option: paragraph-start
     This is the regular expression for recognizing the beginning of a
     line that starts _or_ separates paragraphs.  The default value is
     `"\f\\|[ \t]*$"', which matches a line containing only whitespace
     or starting with a form feed (after its left margin).

 -- User Option: sentence-end
     If non-`nil', the value should be a regular expression describing
     the end of a sentence, including the whitespace following the
     sentence.  (All paragraph boundaries also end sentences,
     regardless.)

     If the value is `nil', the default, then the function
     `sentence-end' has to construct the regexp.  That is why you
     should always call the function `sentence-end' to obtain the
     regexp to be used to recognize the end of a sentence.

 -- Function: sentence-end
     This function returns the value of the variable `sentence-end', if
     non-`nil'.  Otherwise it returns a default value based on the
     values of the variables `sentence-end-double-space' (*note
     Definition of sentence-end-double-space::),
     `sentence-end-without-period' and `sentence-end-without-space'.


File: elisp,  Node: Syntax Tables,  Next: Abbrevs,  Prev: Searching and Matching,  Up: Top

35 Syntax Tables
****************

A "syntax table" specifies the syntactic textual function of each
character.  This information is used by the "parsing functions", 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 (*note Word Motion::)
and the list motion functions (*note List Motion::), as well as the
functions in this chapter.

* Menu:

* Basics: Syntax Basics.     Basic concepts of syntax tables.
* Desc: Syntax Descriptors.  How characters are classified.
* Syntax Table Functions::   How to create, examine and alter syntax tables.
* Syntax Properties::        Overriding syntax with text properties.
* Motion and Syntax::        Moving over characters with certain syntaxes.
* Parsing Expressions::      Parsing balanced expressions
                                using the syntax table.
* Standard Syntax Tables::   Syntax tables used by various major modes.
* Syntax Table Internals::   How syntax table information is stored.
* Categories::               Another way of classifying character syntax.


File: elisp,  Node: Syntax Basics,  Next: Syntax Descriptors,  Up: Syntax Tables

35.1 Syntax Table Concepts
==========================

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 (*note Word Motion::) and the list motion functions
(*note List Motion::) as well as the functions in this chapter.

A syntax table is a char-table (*note Char-Tables::).  The element at
index C describes the character with code C.  The element's value
should be a list that encodes the syntax of the character in question.

   Syntax tables are used only for moving across text, not for the Emacs
Lisp reader.  Emacs Lisp uses built-in syntactic rules when reading Lisp
expressions, and these rules cannot be changed.  (Some Lisp systems
provide ways to redefine the read syntax, but we decided to leave this
feature out of Emacs Lisp for simplicity.)

   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 that 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.  *Note Example Major
Modes::, for an example of how to set up a syntax table.

   A syntax table can inherit the data for some characters from the
standard syntax table, while specifying other characters itself.  The
"inherit" syntax class means "inherit this character's syntax from the
standard syntax table."  Just changing the standard syntax for a
character affects all syntax tables that inherit from it.

 -- Function: syntax-table-p object
     This function returns `t' if OBJECT is a syntax table.


File: elisp,  Node: Syntax Descriptors,  Next: Syntax Table Functions,  Prev: Syntax Basics,  Up: Syntax Tables

35.2 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 syntax you want.

   The syntax table specifies a syntax class for each character.  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 that is often assigned that class; however,
its meaning as a designator is unvarying and independent of what syntax
that character currently has.  Thus, `\' as a designator character
always gives "escape character" syntax, regardless of what syntax `\'
currently has.

   A syntax descriptor is a Lisp string that specifies a syntax class, a
matching character (used only for the 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.

   For example, the syntax 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 a 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).

* Menu:

* Syntax Class Table::      Table of syntax classes.
* Syntax Flags::            Additional flags each character can have.


File: elisp,  Node: Syntax Class Table,  Next: Syntax Flags,  Up: Syntax Descriptors

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

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

 -- Syntax class: whitespace character
     "Whitespace characters" (designated by ` ' or `-') separate
     symbols and words from each other.  Typically, whitespace
     characters have no other syntactic significance, and multiple
     whitespace characters are syntactically equivalent to a single
     one.  Space, tab, newline and formfeed are classified as
     whitespace in almost all major modes.

 -- Syntax class: word constituent
     "Word constituents" (designated by `w') are parts of words in
     human languages, 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 by `_') 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" (designated by `.') 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.
     Some programming language modes, such as Emacs Lisp mode, have no
     characters in this class since the few characters that are not
     symbol or word constituents all have other uses.  Other
     programming language modes, such as C mode, use punctuation syntax
     for operators.

 -- 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.  *Note Blinking::.

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

     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 by `"') are used in many
     languages, including Lisp and C, to delimit string constants.  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-syntax character
     An "escape character" (designated by `\') 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'.  *Note Word Motion::.

 -- Syntax class: character quote
     A "character quote character" (designated by `/') 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'.  *Note Word Motion::.

     This class is used for backslash in TeX mode.

 -- Syntax class: paired delimiter
     "Paired delimiter characters" (designated by `$') 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 delimiter presently--the `$' that both enters
     and leaves math mode.

 -- Syntax class: expression prefix
     An "expression prefix operator" (designated by `'') is used for
     syntactic operators that are considered as part of an expression
     if they appear next to one.  In Lisp modes, these characters
     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
     various languages to delimit comments.  These classes are
     designated by `<' and `>', respectively.

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

 -- Syntax class: inherit standard syntax
     This syntax class does not specify a particular syntax.  It says
     to look in the standard syntax table to find the syntax of this
     character.  The designator for this syntax class is `@'.

 -- Syntax class: generic comment delimiter
     A "generic comment delimiter" (designated by `!') starts or ends a
     special kind of comment.  _Any_ generic comment delimiter matches
     _any_ generic comment delimiter, but they cannot match a comment
     starter or comment ender; generic comment delimiters can only
     match each other.

     This syntax class is primarily meant for use with the
     `syntax-table' text property (*note Syntax Properties::).  You can
     mark any range of characters as forming a comment, by giving the
     first and last characters of the range `syntax-table' properties
     identifying them as generic comment delimiters.

 -- Syntax class: generic string delimiter
     A "generic string delimiter" (designated by `|') starts or ends a
     string.  This class differs from the string quote class in that
     _any_ generic string delimiter can match any other generic string
     delimiter; but they do not match ordinary string quote characters.

     This syntax class is primarily meant for use with the
     `syntax-table' text property (*note Syntax Properties::).  You can
     mark any range of characters as forming a string constant, by
     giving the first and last characters of the range `syntax-table'
     properties identifying them as generic string delimiters.


File: elisp,  Node: Syntax Flags,  Prev: Syntax Class Table,  Up: Syntax Descriptors

35.2.2 Syntax Flags
-------------------

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

   All the flags except `n' and `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 (`*/').

   Here is a table of the possible flags for a character C, and what
they mean:

   * `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 supports two comment styles simultaneously in any one syntax
     table.  This is for the sake of C++.  Each style of comment syntax
     has its own comment-start sequence and its own comment-end
     sequence.  Each comment must stick to one style or the other;
     thus, if it starts with the comment-start sequence of style "b,"
     it must also end with the comment-end sequence of style "b."

     The two comment-start sequences must begin with the same
     character; only the second character may differ.  Mark the second
     character of the "b"-style comment-start sequence with the `b'
     flag.

     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'

     This defines four comment-delimiting sequences:

    `/*'
          This is a comment-start sequence for "a" style because the
          second character, `*', does not have the `b' flag.

    `//'
          This is a comment-start sequence for "b" style because the
          second character, `/', does have the `b' flag.

    `*/'
          This is a comment-end sequence for "a" style because the first
          character, `*', does not have the `b' flag.

    newline
          This is a comment-end sequence for "b" style, because the
          newline character has the `b' flag.

   * `n' on a comment delimiter character specifies that this kind of
     comment can be nested.  For a two-character comment delimiter, `n'
     on either character makes it nestable.

   * `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 classes.

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


File: elisp,  Node: Syntax Table Functions,  Next: Syntax Properties,  Prev: Syntax Descriptors,  Up: Syntax Tables

35.3 Syntax Table Functions
===========================

In this section we describe functions for creating, accessing and
altering syntax tables.

 -- Function: make-syntax-table &optional table
     This function creates a new syntax table, with all values
     initialized to `nil'.  If TABLE is non-`nil', it becomes the
     parent of the new syntax table, otherwise the standard syntax
     table is the parent.  Like all char-tables, a syntax table
     inherits from its parent.  Thus the original syntax of all
     characters in the returned syntax table is determined by the
     parent.  *Note Char-Tables::.

     Most major mode syntax tables are created in this way.

 -- Function: copy-syntax-table &optional table
     This function constructs a copy of TABLE and returns it.  If TABLE
     is not supplied (or is `nil'), it returns a copy of the standard
     syntax table.  Otherwise, an error is signaled if TABLE is not a
     syntax table.

 -- Command: modify-syntax-entry char syntax-descriptor &optional table
     This function sets the syntax entry for CHAR according to
     SYNTAX-DESCRIPTOR.  CHAR can be a character, or a cons cell of the
     form `(MIN . MAX)'; in the latter case, the function sets the
     syntax entries for all characters in the range between MIN and
     MAX, inclusive.

     The syntax is changed only for TABLE, which defaults to the
     current buffer's syntax table, and not in any other syntax table.
     The argument SYNTAX-DESCRIPTOR specifies the desired syntax; this
     is a string beginning with a class designator character, and
     optionally containing a matching character and flags as well.
     *Note Syntax Descriptors::.

     This function always returns `nil'.  The old syntax information in
     the table for this character is discarded.

     An error is signaled if the first character of the syntax
     descriptor is not one of the seventeen syntax class designator
     characters.  An error is also signaled if CHAR is not a character.

     Examples:

          ;; Put the space character in class whitespace.
          (modify-syntax-entry ?\s " ")
               => nil

          ;; Make `$' an open parenthesis character,
          ;;   with `^' as its matching close.
          (modify-syntax-entry ?$ "(^")
               => nil

          ;; Make `^' a close parenthesis character,
          ;;   with `$' as its matching open.
          (modify-syntax-entry ?^ ")$")
               => nil

          ;; Make `/' a punctuation character,
          ;;   the first character of a start-comment sequence,
          ;;   and the second character of an end-comment sequence.
          ;;   This is used in C mode.
          (modify-syntax-entry ?/ ". 14")
               => nil

 -- Function: char-syntax character
     This function returns the syntax class of CHARACTER, represented
     by its mnemonic designator character.  This returns _only_ the
     class, not any matching parenthesis or flags.

     An error is signaled if CHAR is not a character.

     The following examples apply to C mode.  The first example shows
     that the syntax class of space is whitespace (represented by a
     space).  The second example shows that the syntax of `/' is
     punctuation.  This does not show the fact that it is also part of
     comment-start and -end sequences.  The third example shows that
     open parenthesis is in the class of open parentheses.  This does
     not show the fact that it has a matching character, `)'.

          (string (char-syntax ?\s))
               => " "

          (string (char-syntax ?/))
               => "."

          (string (char-syntax ?\())
               => "("

     We use `string' to make it easier to see the character returned by
     `char-syntax'.

 -- Function: set-syntax-table table
     This function makes TABLE the syntax table for the current buffer.
     It returns TABLE.

 -- Function: syntax-table
     This function returns the current syntax table, which is the table
     for the current buffer.

 -- Macro: with-syntax-table TABLE BODY...
     This macro executes BODY using TABLE as the current syntax table.
     It returns the value of the last form in BODY, after restoring the
     old current syntax table.

     Since each buffer has its own current syntax table, we should make
     that more precise: `with-syntax-table' temporarily alters the
     current syntax table of whichever buffer is current at the time
     the macro execution starts.  Other buffers are not affected.


File: elisp,  Node: Syntax Properties,  Next: Motion and Syntax,  Prev: Syntax Table Functions,  Up: Syntax Tables

35.4 Syntax Properties
======================

When the syntax table is not flexible enough to specify the syntax of a
language, you can use `syntax-table' text properties to override the
syntax table for specific character occurrences in the buffer.  *Note
Text Properties::.  You can use Font Lock mode to set `syntax-table'
text properties.  *Note Setting Syntax Properties::.

   The valid values of `syntax-table' text property are:

SYNTAX-TABLE
     If the property value is a syntax table, that table is used
     instead of the current buffer's syntax table to determine the
     syntax for this occurrence of the character.

`(SYNTAX-CODE . MATCHING-CHAR)'
     A cons cell of this format specifies the syntax for this
     occurrence of the character.  (*note Syntax Table Internals::)

`nil'
     If the property is `nil', the character's syntax is determined from
     the current syntax table in the usual way.

 -- Variable: parse-sexp-lookup-properties
     If this is non-`nil', the syntax scanning functions pay attention
     to syntax text properties.  Otherwise they use only the current
     syntax table.


File: elisp,  Node: Motion and Syntax,  Next: Parsing Expressions,  Prev: Syntax Properties,  Up: Syntax Tables

35.5 Motion and Syntax
======================

This section describes functions for moving across characters that have
certain syntax classes.

 -- Function: skip-syntax-forward syntaxes &optional limit
     This function moves point forward across characters having syntax
     classes mentioned in SYNTAXES (a string of syntax class
     characters).  It stops when it encounters the end of the buffer, or
     position LIMIT (if specified), or a character it is not supposed
     to skip.

     If SYNTAXES starts with `^', then the function skips characters
     whose syntax is _not_ in SYNTAXES.

     The return value is the distance traveled, which is a nonnegative
     integer.

 -- Function: skip-syntax-backward syntaxes &optional limit
     This function moves point backward across characters whose syntax
     classes are mentioned in SYNTAXES.  It stops when it encounters
     the beginning of the buffer, or position LIMIT (if specified), or
     a character it is not supposed to skip.

     If SYNTAXES starts with `^', then the function skips characters
     whose syntax is _not_ in SYNTAXES.

     The return value indicates the distance traveled.  It is an
     integer that is zero or less.

 -- Function: backward-prefix-chars
     This function moves point backward over any number of characters
     with expression prefix syntax.  This includes both characters in
     the expression prefix syntax class, and characters with the `p'
     flag.


File: elisp,  Node: Parsing Expressions,  Next: Standard Syntax Tables,  Prev: Motion and Syntax,  Up: Syntax Tables

35.6 Parsing Expressions
========================

This section describes functions for parsing and scanning balanced
expressions, also known as "sexps".  Basically, a sexp is either a
balanced parenthetical grouping, a string, or a symbol name (a sequence
of characters whose syntax is either word constituent or symbol
constituent).  However, characters whose syntax is expression prefix
are treated as part of the sexp if they appear next to it.

   The syntax table controls the interpretation of characters, so these
functions can be used for Lisp expressions when in Lisp mode and for C
expressions when in C mode.  *Note List Motion::, for convenient
higher-level functions for moving over balanced expressions.

   A character's syntax controls how it changes the state of the
parser, rather than describing the state itself.  For example, a string
delimiter character toggles the parser state between "in-string" and
"in-code," but the syntax of characters does not directly say whether
they are inside a string.  For example (note that 15 is the syntax code
for generic string delimiters),

     (put-text-property 1 9 'syntax-table '(15 . nil))

does not tell Emacs that the first eight chars of the current buffer
are a string, but rather that they are all string delimiters.  As a
result, Emacs treats them as four consecutive empty string constants.

* Menu:

* Motion via Parsing::       Motion functions that work by parsing.
* Position Parse::           Determining the syntactic state of a position.
* Parser State::             How Emacs represents a syntactic state.
* Low-Level Parsing::        Parsing across a specified region.
* Control Parsing::          Parameters that affect parsing.


File: elisp,  Node: Motion via Parsing,  Next: Position Parse,  Up: Parsing Expressions

35.6.1 Motion Commands Based on Parsing
---------------------------------------

This section describes simple point-motion functions that operate based
on parsing expressions.

 -- Function: scan-lists from count depth
     This function scans forward COUNT balanced parenthetical groupings
     from position FROM.  It returns the position where the scan stops.
     If COUNT is negative, the scan moves backwards.

     If DEPTH is nonzero, parenthesis depth counting begins from that
     value.  The only candidates for stopping are places where the
     depth in parentheses becomes zero; `scan-lists' counts COUNT such
     places and then stops.  Thus, a positive value for DEPTH means go
     out DEPTH levels of parenthesis.

     Scanning ignores comments if `parse-sexp-ignore-comments' is
     non-`nil'.

     If the scan reaches the beginning or end of the buffer (or its
     accessible portion), and the depth is not zero, an error is
     signaled.  If the depth is zero but the count is not used up,
     `nil' is returned.

 -- Function: scan-sexps from count
     This function scans forward COUNT sexps from position FROM.  It
     returns the position where the scan stops.  If COUNT is negative,
     the scan moves backwards.

     Scanning ignores comments if `parse-sexp-ignore-comments' is
     non-`nil'.

     If the scan reaches the beginning or end of (the accessible part
     of) the buffer while in the middle of a parenthetical grouping, an
     error is signaled.  If it reaches the beginning or end between
     groupings but before count is used up, `nil' is returned.

 -- Function: forward-comment count
     This function moves point forward across COUNT complete comments
       (that is, including the starting delimiter and the terminating
     delimiter if any), plus any whitespace encountered on the way.  It
     moves backward if COUNT is negative.  If it encounters anything
     other than a comment or whitespace, it stops, leaving point at the
     place where it stopped.  This includes (for instance) finding the
     end of a comment when moving forward and expecting the beginning
     of one.  The function also stops immediately after moving over the
     specified number of complete comments.  If COUNT comments are
     found as expected, with nothing except whitespace between them, it
     returns `t'; otherwise it returns `nil'.

     This function cannot tell whether the "comments" it traverses are
     embedded within a string.  If they look like comments, it treats
     them as comments.

   To move forward over all comments and whitespace following point, use
`(forward-comment (buffer-size))'.  `(buffer-size)' is a good argument
to use, because the number of comments in the buffer cannot exceed that
many.


File: elisp,  Node: Position Parse,  Next: Parser State,  Prev: Motion via Parsing,  Up: Parsing Expressions

35.6.2 Finding the Parse State for a Position
---------------------------------------------

For syntactic analysis, such as in indentation, often the useful thing
is to compute the syntactic state corresponding to a given buffer
position.  This function does that conveniently.

 -- Function: syntax-ppss &optional pos
     This function returns the parser state (see next section) that the
     parser would reach at position POS starting from the beginning of
     the buffer.  This is equivalent to `(parse-partial-sexp
     (point-min) POS)', except that `syntax-ppss' uses a cache to speed
     up the computation.  Due to this optimization, the 2nd value
     (previous complete subexpression) and 6th value (minimum
     parenthesis depth) of the returned parser state are not meaningful.

   `syntax-ppss' automatically hooks itself to
`before-change-functions' to keep its cache consistent.  But updating
can fail if `syntax-ppss' is called while `before-change-functions' is
temporarily let-bound, or if the buffer is modified without obeying the
hook, such as when using `inhibit-modification-hooks'.  For this
reason, it is sometimes necessary to flush the cache manually.

 -- Function: syntax-ppss-flush-cache beg &rest ignored-args
     This function flushes the cache used by `syntax-ppss', starting at
     position BEG.  The remaining arguments, IGNORED-ARGS, are ignored;
     this function accepts them so that it can be directly used on
     hooks such as `before-change-functions' (*note Change Hooks::).

   Major modes can make `syntax-ppss' run faster by specifying where it
needs to start parsing.

 -- Variable: syntax-begin-function
     If this is non-`nil', it should be a function that moves to an
     earlier buffer position where the parser state is equivalent to
     `nil'--in other words, a position outside of any comment, string,
     or parenthesis.  `syntax-ppss' uses it to further optimize its
     computations, when the cache gives no help.


File: elisp,  Node: Parser State,  Next: Low-Level Parsing,  Prev: Position Parse,  Up: Parsing Expressions

35.6.3 Parser State
-------------------

A "parser state" is a list of ten elements describing the final state
of parsing text syntactically as part of an expression.  The parsing
functions in the following sections return a parser state as the value,
and in some cases accept one as an argument also, so that you can
resume parsing after it stops.  Here are the meanings of the elements
of the parser state:

  0. The depth in parentheses, counting from 0.  *Warning:* this can be
     negative if there are more close parens than open parens between
     the start of the defun and point.

  1. The character position of the start of the innermost parenthetical
     grouping containing the stopping point; `nil' if none.

  2. The character position of the start of the last complete
     subexpression terminated; `nil' if none.

  3. Non-`nil' if inside a string.  More precisely, this is the
     character that will terminate the string, or `t' if a generic
     string delimiter character should terminate it.

  4. `t' if inside a comment (of either style), or the comment nesting
     level if inside a kind of comment that can be nested.

  5. `t' if point is just after a quote character.

  6. The minimum parenthesis depth encountered during this scan.

  7. What kind of comment is active: `nil' for a comment of style "a"
     or when not inside a comment, `t' for a comment of style "b," and
     `syntax-table' for a comment that should be ended by a generic
     comment delimiter character.

  8. The string or comment start position.  While inside a comment,
     this is the position where the comment began; while inside a
     string, this is the position where the string began.  When outside
     of strings and comments, this element is `nil'.

  9. Internal data for continuing the parsing.  The meaning of this
     data is subject to change; it is used if you pass this list as the
     STATE argument to another call.

   Elements 1, 2, and 6 are ignored in a state which you pass as an
argument to continue parsing, and elements 8 and 9 are used only in
trivial cases.  Those elements serve primarily to convey information to
the Lisp program which does the parsing.

   One additional piece of useful information is available from a
parser state using this function:

 -- Function: syntax-ppss-toplevel-pos state
     This function extracts, from parser state STATE, the last position
     scanned in the parse which was at top level in grammatical
     structure.  "At top level" means outside of any parentheses,
     comments, or strings.

     The value is `nil' if STATE represents a parse which has arrived
     at a top level position.

   We have provided this access function rather than document how the
data is represented in the state, because we plan to change the
representation in the future.


File: elisp,  Node: Low-Level Parsing,  Next: Control Parsing,  Prev: Parser State,  Up: Parsing Expressions

35.6.4 Low-Level Parsing
------------------------

The most basic way to use the expression parser is to tell it to start
at a given position with a certain state, and parse up to a specified
end position.

 -- Function: parse-partial-sexp start limit &optional target-depth
          stop-before state stop-comment
     This function parses a sexp in the current buffer starting at
     START, not scanning past LIMIT.  It stops at position LIMIT or
     when certain criteria described below are met, and sets point to
     the location where parsing stops.  It returns a parser state
     describing the status of the parse at the point where it stops.

     If the third argument TARGET-DEPTH is non-`nil', parsing stops if
     the depth in parentheses becomes equal to TARGET-DEPTH.  The depth
     starts at 0, or at whatever is given in STATE.

     If the fourth argument STOP-BEFORE is non-`nil', parsing stops
     when it comes to any character that starts a sexp.  If
     STOP-COMMENT is non-`nil', parsing stops when it comes to the
     start of a comment.  If STOP-COMMENT is the symbol `syntax-table',
     parsing stops after the start of a comment or a string, or the end
     of a comment or a string, whichever comes first.

     If STATE is `nil', START is assumed to be at the top level of
     parenthesis structure, such as the beginning of a function
     definition.  Alternatively, you might wish to resume parsing in the
     middle of the structure.  To do this, you must provide a STATE
     argument that describes the initial status of parsing.  The value
     returned by a previous call to `parse-partial-sexp' will do nicely.


File: elisp,  Node: Control Parsing,  Prev: Low-Level Parsing,  Up: Parsing Expressions

35.6.5 Parameters to Control Parsing
------------------------------------

 -- Variable: multibyte-syntax-as-symbol
     If this variable is non-`nil', `scan-sexps' treats all non-ASCII
     characters as symbol constituents regardless of what the syntax
     table says about them.  (However, text properties can still
     override the syntax.)

 -- User Option: parse-sexp-ignore-comments
     If the value is non-`nil', then comments are treated as whitespace
     by the functions in this section and by `forward-sexp',
     `scan-lists' and `scan-sexps'.

   The behavior of `parse-partial-sexp' is also affected by
`parse-sexp-lookup-properties' (*note Syntax Properties::).

   You can use `forward-comment' to move forward or backward over one
comment or several comments.


File: elisp,  Node: Standard Syntax Tables,  Next: Syntax Table Internals,  Prev: Parsing Expressions,  Up: Syntax Tables

35.7 Some Standard Syntax Tables
================================

Most of the major modes in Emacs have their own syntax tables.  Here
are several of them:

 -- Function: standard-syntax-table
     This function returns the standard syntax table, which is the
     syntax table used in Fundamental mode.

 -- Variable: text-mode-syntax-table
     The value of this variable is the syntax table used in Text mode.

 -- Variable: c-mode-syntax-table
     The value of this variable is the syntax table for C-mode buffers.

 -- Variable: emacs-lisp-mode-syntax-table
     The value of this variable is the syntax table used in Emacs Lisp
     mode by editing commands.  (It has no effect on the Lisp `read'
     function.)


File: elisp,  Node: Syntax Table Internals,  Next: Categories,  Prev: Standard Syntax Tables,  Up: Syntax Tables

35.8 Syntax Table Internals
===========================

Lisp programs don't usually work with the elements directly; the
Lisp-level syntax table functions usually work with syntax descriptors
(*note Syntax Descriptors::).  Nonetheless, here we document the
internal format.  This format is used mostly when manipulating syntax
properties.

   Each element of a syntax table is a cons cell of the form
`(SYNTAX-CODE . MATCHING-CHAR)'.  The CAR, SYNTAX-CODE, is an integer
that encodes the syntax class, and any flags.  The CDR, MATCHING-CHAR,
is non-`nil' if a character to match was specified.

   This table gives the value of SYNTAX-CODE which corresponds to each
syntactic type.

     Integer Class          Integer Class          Integer Class
     0    whitespace        5    close parenthesis 10    character quote
     1    punctuation       6    expression prefix 11    comment-start
     2    word              7    string quote      12    comment-end
     3    symbol            8    paired delimiter  13    inherit
     4    open parenthesis  9    escape            14    generic comment
     15   generic string                           

   For example, the usual syntax value for `(' is `(4 . 41)'.  (41 is
the character code for `)'.)

   The flags are encoded in higher order bits, starting 16 bits from the
least significant bit.  This table gives the power of two which
corresponds to each syntax flag.

     Prefix Flag            Prefix Flag            Prefix Flag
     `1'    `(lsh 1 16)'    `4'    `(lsh 1 19)'    `b'    `(lsh 1 21)'
     `2'    `(lsh 1 17)'    `p'    `(lsh 1 20)'    `n'    `(lsh 1 22)'
     `3'    `(lsh 1 18)'                           

 -- Function: string-to-syntax DESC
     This function returns the internal form corresponding to the syntax
     descriptor DESC, a cons cell `(SYNTAX-CODE . MATCHING-CHAR)'.

 -- Function: syntax-after pos
     This function returns the syntax code of the character in the
     buffer after position POS, taking account of syntax properties as
     well as the syntax table.  If POS is outside the buffer's
     accessible portion (*note accessible portion: Narrowing.), this
     function returns `nil'.

 -- Function: syntax-class syntax
     This function returns the syntax class of the syntax code SYNTAX.
     (It masks off the high 16 bits that hold the flags encoded in the
     syntax descriptor.)  If SYNTAX is `nil', it returns `nil'; this is
     so evaluating the expression

          (syntax-class (syntax-after pos))

     where `pos' is outside the buffer's accessible portion, will yield
     `nil' without throwing errors or producing wrong syntax class
     codes.


File: elisp,  Node: Categories,  Prev: Syntax Table Internals,  Up: Syntax Tables

35.9 Categories
===============

"Categories" provide an alternate way of classifying characters
syntactically.  You can define several categories as needed, then
independently assign each character to one or more categories.  Unlike
syntax classes, categories are not mutually exclusive; it is normal for
one character to belong to several categories.

   Each buffer has a "category table" which records which categories
are defined and also which characters belong to each category.  Each
category table defines its own categories, but normally these are
initialized by copying from the standard categories table, so that the
standard categories are available in all modes.

   Each category has a name, which is an ASCII printing character in
the range ` ' to `~'.  You specify the name of a category when you
define it with `define-category'.

   The category table is actually a char-table (*note Char-Tables::).
The element of the category table at index C is a "category set"--a
bool-vector--that indicates which categories character C belongs to.
In this category set, if the element at index CAT is `t', that means
category CAT is a member of the set, and that character C belongs to
category CAT.

   For the next three functions, the optional argument TABLE defaults
to the current buffer's category table.

 -- Function: define-category char docstring &optional table
     This function defines a new category, with name CHAR and
     documentation DOCSTRING, for the category table TABLE.

 -- Function: category-docstring category &optional table
     This function returns the documentation string of category CATEGORY
     in category table TABLE.

          (category-docstring ?a)
               => "ASCII"
          (category-docstring ?l)
               => "Latin"

 -- Function: get-unused-category &optional table
     This function returns a category name (a character) which is not
     currently defined in TABLE.  If all possible categories are in use
     in TABLE, it returns `nil'.

 -- Function: category-table
     This function returns the current buffer's category table.

 -- Function: category-table-p object
     This function returns `t' if OBJECT is a category table, otherwise
     `nil'.

 -- Function: standard-category-table
     This function returns the standard category table.

 -- Function: copy-category-table &optional table
     This function constructs a copy of TABLE and returns it.  If TABLE
     is not supplied (or is `nil'), it returns a copy of the standard
     category table.  Otherwise, an error is signaled if TABLE is not a
     category table.

 -- Function: set-category-table table
     This function makes TABLE the category table for the current
     buffer.  It returns TABLE.

 -- Function: make-category-table
     This creates and returns an empty category table.  In an empty
     category table, no categories have been allocated, and no
     characters belong to any categories.

 -- Function: make-category-set categories
     This function returns a new category set--a bool-vector--whose
     initial contents are the categories listed in the string
     CATEGORIES.  The elements of CATEGORIES should be category names;
     the new category set has `t' for each of those categories, and
     `nil' for all other categories.

          (make-category-set "al")
               => #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"

 -- Function: char-category-set char
     This function returns the category set for character CHAR in the
     current buffer's category table.  This is the bool-vector which
     records which categories the character CHAR belongs to.  The
     function `char-category-set' does not allocate storage, because it
     returns the same bool-vector that exists in the category table.

          (char-category-set ?a)
               => #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"

 -- Function: category-set-mnemonics category-set
     This function converts the category set CATEGORY-SET into a string
     containing the characters that designate the categories that are
     members of the set.

          (category-set-mnemonics (char-category-set ?a))
               => "al"

 -- Function: modify-category-entry char category &optional table reset
     This function modifies the category set of CHAR in category table
     TABLE (which defaults to the current buffer's category table).
     CHAR can be a character, or a cons cell of the form `(MIN . MAX)';
     in the latter case, the function modifies the category sets of all
     characters in the range between MIN and MAX, inclusive.

     Normally, it modifies a category set by adding CATEGORY to it.
     But if RESET is non-`nil', then it deletes CATEGORY instead.

 -- Command: describe-categories &optional buffer-or-name
     This function describes the category specifications in the current
     category table.  It inserts the descriptions in a buffer, and then
     displays that buffer.  If BUFFER-OR-NAME is non-`nil', it
     describes the category table of that buffer instead.


File: elisp,  Node: Abbrevs,  Next: Processes,  Prev: Syntax Tables,  Up: Top

36 Abbrevs and Abbrev Expansion
*******************************

An abbreviation or "abbrev" is a string of characters that may be
expanded to a longer string.  The user can insert the abbrev string and
find it replaced automatically with the expansion of the abbrev.  This
saves typing.

   The set of abbrevs currently in effect is recorded in an "abbrev
table".  Each buffer has a local abbrev table, but normally all buffers
in the same major mode share one abbrev table.  There is also a global
abbrev table.  Normally both are used.

   An abbrev table is represented as an obarray.  *Note Creating
Symbols::, for information about obarrays.  Each abbreviation is
represented by a symbol in the obarray.  The symbol's name is the
abbreviation; its value is the expansion; its function definition is
the hook function for performing the expansion (*note Defining
Abbrevs::); and its property list cell contains various additional
properties, including the use count and the number of times the
abbreviation has been expanded (*note Abbrev Properties::).

   Certain abbrevs, called "system abbrevs", are defined by a major
mode instead of the user.  A system abbrev is identified by its
non-`nil' `:system' property (*note Abbrev Properties::).  When abbrevs
are saved to an abbrev file, system abbrevs are omitted.  *Note Abbrev
Files::.

   Because the symbols used for abbrevs are not interned in the usual
obarray, they will never appear as the result of reading a Lisp
expression; in fact, normally they are never used except by the code
that handles abbrevs.  Therefore, it is safe to use them in an
extremely nonstandard way.

   For the user-level commands for abbrevs, see *note Abbrev Mode:
(emacs)Abbrevs.

* Menu:

* Abbrev Mode::                 Setting up Emacs for abbreviation.
* Tables: Abbrev Tables.        Creating and working with abbrev tables.
* Defining Abbrevs::            Specifying abbreviations and their expansions.
* Files: Abbrev Files.          Saving abbrevs in files.
* Expansion: Abbrev Expansion.  Controlling expansion; expansion subroutines.
* Standard Abbrev Tables::      Abbrev tables used by various major modes.
* Abbrev Properties::           How to read and set abbrev properties.
                                Which properties have which effect.
* Abbrev Table Properties::     How to read and set abbrev table properties.
                                Which properties have which effect.


File: elisp,  Node: Abbrev Mode,  Next: Abbrev Tables,  Prev: Abbrevs,  Up: Abbrevs

36.1 Setting Up Abbrev Mode
===========================

Abbrev mode is a minor mode controlled by the variable `abbrev-mode'.

 -- User Option: abbrev-mode
     If this variable is non-`nil', abbrevs are automatically expanded
     in the buffer.  If the value is `nil', abbrevs may be defined, but
     they are not expanded automatically.

     This variable automatically becomes buffer-local when set in any
     fashion.


File: elisp,  Node: Abbrev Tables,  Next: Defining Abbrevs,  Prev: Abbrev Mode,  Up: Abbrevs

36.2 Abbrev Tables
==================

This section describes how to create and manipulate abbrev tables.

 -- Function: make-abbrev-table &optional props
     This function creates and returns a new, empty abbrev table--an
     obarray containing no symbols.  It is a vector filled with zeros.
     PROPS is a property list that is applied to the new table (*note
     Abbrev Table Properties::).

 -- Function: abbrev-table-p object
     This function returns a non-`nil' value if OBJECT is an abbrev
     table.

 -- Function: clear-abbrev-table abbrev-table
     This function undefines all the abbrevs in ABBREV-TABLE, leaving
     it empty.  It always returns `nil'.

 -- Function: copy-abbrev-table abbrev-table
     This function returns a copy of ABBREV-TABLE--a new abbrev table
     containing the same abbrev definitions.  There is one difference
     between the contents of ABBREV-TABLE and the returned copy: all
     abbrevs in the latter have their property lists set to `nil'.

 -- Function: define-abbrev-table tabname definitions &optional
          docstring &rest props
     This function defines TABNAME (a symbol) as an abbrev table name,
     i.e., as a variable whose value is an abbrev table.  It defines
     abbrevs in the table according to DEFINITIONS, a list of elements
     of the form `(ABBREVNAME EXPANSION [HOOK] [PROPS...])'.  These
     elements are passed as arguments to `define-abbrev'.  The return
     value is always `nil'.

     The optional string DOCSTRING is the documentation string of the
     variable TABNAME.  The property list PROPS is applied to the
     abbrev table (*note Abbrev Table Properties::).

     If this function is called more than once for the same TABNAME,
     subsequent calls add the definitions in DEFINITIONS to TABNAME,
     rather than overriding the entire original contents.  (A
     subsequent call only overrides abbrevs explicitly redefined or
     undefined in DEFINITIONS.)

 -- Variable: abbrev-table-name-list
     This is a list of symbols whose values are abbrev tables.
     `define-abbrev-table' adds the new abbrev table name to this list.

 -- Function: insert-abbrev-table-description name &optional human
     This function inserts before point a description of the abbrev
     table named NAME.  The argument NAME is a symbol whose value is an
     abbrev table.  The return value is always `nil'.

     If HUMAN is non-`nil', the description is human-oriented.  System
     abbrevs are listed and identified as such.  Otherwise the
     description is a Lisp expression--a call to `define-abbrev-table'
     that would define NAME as it is currently defined, but without the
     system abbrevs.  (The mode or package using NAME is supposed to
     add these to NAME separately.)


File: elisp,  Node: Defining Abbrevs,  Next: Abbrev Files,  Prev: Abbrev Tables,  Up: Abbrevs

36.3 Defining Abbrevs
=====================

`define-abbrev' is the low-level basic function for defining an abbrev
in an abbrev table.

   When a major mode defines a system abbrev, it should call
`define-abbrev' and specify a `t' for the `:system' property.  Be aware
that any saved non-"system" abbrevs are restored at startup, i.e.
before some major modes are loaded.  Therefore, major modes should not
assume that their abbrev tables are empty when they are first loaded.

 -- Function: define-abbrev abbrev-table name expansion &optional hook
          &rest props
     This function defines an abbrev named NAME, in ABBREV-TABLE, to
     expand to EXPANSION and call HOOK, with properties PROPS (*note
     Abbrev Properties::).  The return value is NAME.  The `:system'
     property in PROPS is treated specially here: if it has the value
     `force', then it will overwrite an existing definition even for a
     non-"system" abbrev of the same name.

     NAME should be a string.  The argument EXPANSION is normally the
     desired expansion (a string), or `nil' to undefine the abbrev.  If
     it is anything but a string or `nil', then the abbreviation
     "expands" solely by running HOOK.

     The argument HOOK is a function or `nil'.  If HOOK is non-`nil',
     then it is called with no arguments after the abbrev is replaced
     with EXPANSION; point is located at the end of EXPANSION when HOOK
     is called.

     If HOOK is a non-`nil' symbol whose `no-self-insert' property is
     non-`nil', HOOK can explicitly control whether to insert the
     self-inserting input character that triggered the expansion.  If
     HOOK returns non-`nil' in this case, that inhibits insertion of
     the character.  By contrast, if HOOK returns `nil',
     `expand-abbrev' also returns `nil', as if expansion had not really
     occurred.

     Normally, `define-abbrev' sets the variable `abbrevs-changed' to
     `t', if it actually changes the abbrev.  (This is so that some
     commands will offer to save the abbrevs.)  It does not do this for
     a system abbrev, since those aren't saved anyway.

 -- User Option: only-global-abbrevs
     If this variable is non-`nil', it means that the user plans to use
     global abbrevs only.  This tells the commands that define
     mode-specific abbrevs to define global ones instead.  This
     variable does not alter the behavior of the functions in this
     section; it is examined by their callers.


File: elisp,  Node: Abbrev Files,  Next: Abbrev Expansion,  Prev: Defining Abbrevs,  Up: Abbrevs

36.4 Saving Abbrevs in Files
============================

A file of saved abbrev definitions is actually a file of Lisp code.
The abbrevs are saved in the form of a Lisp program to define the same
abbrev tables with the same contents.  Therefore, you can load the file
with `load' (*note How Programs Do Loading::).  However, the function
`quietly-read-abbrev-file' is provided as a more convenient interface.

   User-level facilities such as `save-some-buffers' can save abbrevs
in a file automatically, under the control of variables described here.

 -- User Option: abbrev-file-name
     This is the default file name for reading and saving abbrevs.

 -- Function: quietly-read-abbrev-file &optional filename
     This function reads abbrev definitions from a file named FILENAME,
     previously written with `write-abbrev-file'.  If FILENAME is
     omitted or `nil', the file specified in `abbrev-file-name' is
     used.  `save-abbrevs' is set to `t' so that changes will be saved.

     This function does not display any messages.  It returns `nil'.

 -- User Option: save-abbrevs
     A non-`nil' value for `save-abbrevs' means that Emacs should offer
     the user to save abbrevs when files are saved.  If the value is
     `silently', Emacs saves the abbrevs without asking the user.
     `abbrev-file-name' specifies the file to save the abbrevs in.

 -- Variable: abbrevs-changed
     This variable is set non-`nil' by defining or altering any abbrevs
     (except system abbrevs).  This serves as a flag for various Emacs
     commands to offer to save your abbrevs.

 -- Command: write-abbrev-file &optional filename
     Save all abbrev definitions (except system abbrevs), for all abbrev
     tables listed in `abbrev-table-name-list', in the file FILENAME,
     in the form of a Lisp program that when loaded will define the
     same abbrevs.  If FILENAME is `nil' or omitted, `abbrev-file-name'
     is used.  This function returns `nil'.


File: elisp,  Node: Abbrev Expansion,  Next: Standard Abbrev Tables,  Prev: Abbrev Files,  Up: Abbrevs

36.5 Looking Up and Expanding Abbreviations
===========================================

Abbrevs are usually expanded by certain interactive commands, including
`self-insert-command'.  This section describes the subroutines used in
writing such commands, as well as the variables they use for
communication.

 -- Function: abbrev-symbol abbrev &optional table
     This function returns the symbol representing the abbrev named
     ABBREV.  The value returned is `nil' if that abbrev is not
     defined.  The optional second argument TABLE is the abbrev table
     in which to look it up.  If TABLE is `nil', this function tries
     first the current buffer's local abbrev table, and second the
     global abbrev table.

 -- Function: abbrev-expansion abbrev &optional table
     This function returns the string that ABBREV would expand into (as
     defined by the abbrev tables used for the current buffer).  If
     ABBREV is not a valid abbrev, the function returns `nil'.  The
     optional argument TABLE specifies the abbrev table to use, as in
     `abbrev-symbol'.

 -- Command: expand-abbrev
     This command expands the abbrev before point, if any.  If point
     does not follow an abbrev, this command does nothing.  The command
     returns the abbrev symbol if it did expansion, `nil' otherwise.

     If the abbrev symbol has a hook function which is a symbol whose
     `no-self-insert' property is non-`nil', and if the hook function
     returns `nil' as its value, then `expand-abbrev' returns `nil'
     even though expansion did occur.

 -- Function: abbrev-insert abbrev &optional name start end
     This function inserts the abbrev expansion of `abbrev', replacing
     the text between `start' and `end'.  If `start' is omitted, it
     defaults to point.  `name', if non-`nil', should be the name by
     which this abbrev was found (a string); it is used to figure out
     whether to adjust the capitalization of the expansion.  The
     function returns `abbrev' if the abbrev was successfully inserted.

 -- Command: abbrev-prefix-mark &optional arg
     This command marks the current location of point as the beginning
     of an abbrev.  The next call to `expand-abbrev' will use the text
     from here to point (where it is then) as the abbrev to expand,
     rather than using the previous word as usual.

     First, this command expands any abbrev before point, unless ARG is
     non-`nil'.  (Interactively, ARG is the prefix argument.)  Then it
     inserts a hyphen before point, to indicate the start of the next
     abbrev to be expanded.  The actual expansion removes the hyphen.

 -- User Option: abbrev-all-caps
     When this is set non-`nil', an abbrev entered entirely in upper
     case is expanded using all upper case.  Otherwise, an abbrev
     entered entirely in upper case is expanded by capitalizing each
     word of the expansion.

 -- Variable: abbrev-start-location
     The value of this variable is a buffer position (an integer or a
     marker) for `expand-abbrev' to use as the start of the next abbrev
     to be expanded.  The value can also be `nil', which means to use
     the word before point instead.  `abbrev-start-location' is set to
     `nil' each time `expand-abbrev' is called.  This variable is also
     set by `abbrev-prefix-mark'.

 -- Variable: abbrev-start-location-buffer
     The value of this variable is the buffer for which
     `abbrev-start-location' has been set.  Trying to expand an abbrev
     in any other buffer clears `abbrev-start-location'.  This variable
     is set by `abbrev-prefix-mark'.

 -- Variable: last-abbrev
     This is the `abbrev-symbol' of the most recent abbrev expanded.
     This information is left by `expand-abbrev' for the sake of the
     `unexpand-abbrev' command (*note Expanding Abbrevs:
     (emacs)Expanding Abbrevs.).

 -- Variable: last-abbrev-location
     This is the location of the most recent abbrev expanded.  This
     contains information left by `expand-abbrev' for the sake of the
     `unexpand-abbrev' command.

 -- Variable: last-abbrev-text
     This is the exact expansion text of the most recent abbrev
     expanded, after case conversion (if any).  Its value is `nil' if
     the abbrev has already been unexpanded.  This contains information
     left by `expand-abbrev' for the sake of the `unexpand-abbrev'
     command.

 -- Variable: abbrev-expand-functions
     This is a special hook run _around_ the `expand-abbrev' function.
     Each function on this hook is called with a single argument: a
     function that performs the normal abbrev expansion.  The hook
     function can hence do anything it wants before and after
     performing the expansion.  It can also choose not to call its
     argument, thus overriding the default behavior; or it may even
     call it several times.  The function should return the abbrev
     symbol if expansion took place.

   The following sample code shows a simple use of
`abbrev-expand-functions'.  It assumes that `foo-mode' is a mode for
editing certain files in which lines that start with `#' are comments.
You want to use Text mode abbrevs for those lines.  The regular local
abbrev table, `foo-mode-abbrev-table' is appropriate for all other
lines.  Then you can put the following code in your `.emacs' file.
*Note Standard Abbrev Tables::, for the definitions of
`local-abbrev-table' and `text-mode-abbrev-table'.

     (defun foo-mode-abbrev-expand-function (expand)
       (if (not (save-excursion (forward-line 0) (eq (char-after) ?#)))
           ;; Performs normal expansion.
           (funcall expand)
         ;; We're inside a comment: use the text-mode abbrevs.
         (let ((local-abbrev-table text-mode-abbrev-table))
           (funcall expand))))

     (add-hook 'foo-mode-hook
               #'(lambda ()
                   (add-hook 'abbrev-expand-functions
                             'foo-mode-abbrev-expand-function
                             nil t)))


File: elisp,  Node: Standard Abbrev Tables,  Next: Abbrev Properties,  Prev: Abbrev Expansion,  Up: Abbrevs

36.6 Standard Abbrev Tables
===========================

Here we list the variables that hold the abbrev tables for the
preloaded major modes of Emacs.

 -- Variable: global-abbrev-table
     This is the abbrev table for mode-independent abbrevs.  The abbrevs
     defined in it apply to all buffers.  Each buffer may also have a
     local abbrev table, whose abbrev definitions take precedence over
     those in the global table.

 -- Variable: local-abbrev-table
     The value of this buffer-local variable is the (mode-specific)
     abbreviation table of the current buffer.  It can also be a list of
     such tables.

 -- Variable: abbrev-minor-mode-table-alist
     The value of this variable is a list of elements of the form
     `(MODE . ABBREV-TABLE)' where MODE is the name of a variable: if
     the variable is bound to a non-`nil' value, then the ABBREV-TABLE
     is active, otherwise it is ignored.  ABBREV-TABLE can also be a
     list of abbrev tables.

 -- Variable: fundamental-mode-abbrev-table
     This is the local abbrev table used in Fundamental mode; in other
     words, it is the local abbrev table in all buffers in Fundamental
     mode.

 -- Variable: text-mode-abbrev-table
     This is the local abbrev table used in Text mode.

 -- Variable: lisp-mode-abbrev-table
     This is the local abbrev table used in Lisp mode and Emacs Lisp
     mode.


File: elisp,  Node: Abbrev Properties,  Next: Abbrev Table Properties,  Prev: Standard Abbrev Tables,  Up: Abbrevs

36.7 Abbrev Properties
======================

Abbrevs have properties, some of which influence the way they work.
You can provide them as arguments to `define-abbrev' and you can
manipulate them with the following functions:

 -- Function: abbrev-put abbrev prop val
     Set the property PROP of ABBREV to value VAL.

 -- Function: abbrev-get abbrev prop
     Return the property PROP of ABBREV, or `nil' if the abbrev has no
     such property.

   The following properties have special meanings:

`:count'
     This property counts the number of times the abbrev has been
     expanded.  If not explicitly set, it is initialized to 0 by
     `define-abbrev'.

`:system'
     If non-`nil', this property marks the abbrev as a system abbrev.
     Such abbrevs are not saved (*note Abbrev Files::).

`:enable-function'
     If non-`nil', this property should be a function of no arguments
     which returns `nil' if the abbrev should not be used and `t'
     otherwise.

`:case-fixed'
     If non-`nil', this property indicates that the case of the
     abbrev's name is significant and should only match a text with the
     same pattern of capitalization.  It also disables the code that
     modifies the capitalization of the expansion.


File: elisp,  Node: Abbrev Table Properties,  Prev: Abbrev Properties,  Up: Abbrevs

36.8 Abbrev Table Properties
============================

Like abbrevs, abbrev tables have properties, some of which influence
the way they work.  You can provide them as arguments to
`define-abbrev-table' and you can manipulate them with the functions:

 -- Function: abbrev-table-put table prop val
     Set the property PROP of abbrev table TABLE to value VAL.

 -- Function: abbrev-table-get table prop
     Return the property PROP of abbrev table TABLE, or `nil' if the
     abbrev has no such property.

   The following properties have special meaning:

`:enable-function'
     This is like the `:enable-function' abbrev property except that it
     applies to all abbrevs in the table and is used even before trying
     to find the abbrev before point so it can dynamically modify the
     abbrev table.

`:case-fixed'
     This is like the `:case-fixed' abbrev property except that it
     applies to all abbrevs in the table.

`:regexp'
     If non-`nil', this property is a regular expression that indicates
     how to extract the name of the abbrev before point before looking
     it up in the table.  When the regular expression matches before
     point, the abbrev name is expected to be in submatch 1.  If this
     property is `nil', `expand-function' defaults to
     `"\\<\\(\\w+\\)\\W"'.  This property allows the use of abbrevs
     whose name contains characters of non-word syntax.

`:parents'
     This property holds the list of tables from which to inherit other
     abbrevs.

`:abbrev-table-modiff'
     This property holds a counter incremented each time a new abbrev is
     added to the table.



File: elisp,  Node: Processes,  Next: Display,  Prev: Abbrevs,  Up: Top

37 Processes
************

In the terminology of operating systems, a "process" is a space in
which a program can execute.  Emacs runs in a process.  Emacs Lisp
programs can invoke other programs in processes of their own.  These are
called "subprocesses" or "child processes" of the Emacs process, which
is their "parent process".

   A subprocess of Emacs may be "synchronous" or "asynchronous",
depending on how it is created.  When you create a synchronous
subprocess, the Lisp program waits for the subprocess to terminate
before continuing execution.  When you create an asynchronous
subprocess, it can run in parallel with the Lisp program.  This kind of
subprocess is represented within Emacs by a Lisp object which is also
called a "process."  Lisp programs can use this object to communicate
with the subprocess or to control it.  For example, you can send
signals, obtain status information, receive output from the process, or
send input to it.

 -- Function: processp object
     This function returns `t' if OBJECT represents an Emacs
     subprocess, `nil' otherwise.

   In addition to subprocesses of the current Emacs session, you can
also access other processes running on your machine.  *Note System
Processes::.

* Menu:

* Subprocess Creation::      Functions that start subprocesses.
* Shell Arguments::          Quoting an argument to pass it to a shell.
* Synchronous Processes::    Details of using synchronous subprocesses.
* Asynchronous Processes::   Starting up an asynchronous subprocess.
* Deleting Processes::       Eliminating an asynchronous subprocess.
* Process Information::      Accessing run-status and other attributes.
* Input to Processes::       Sending input to an asynchronous subprocess.
* Signals to Processes::     Stopping, continuing or interrupting
                               an asynchronous subprocess.
* Output from Processes::    Collecting output from an asynchronous subprocess.
* Sentinels::                Sentinels run when process run-status changes.
* Query Before Exit::        Whether to query if exiting will kill a process.
* System Processes::         Accessing other processes running on your system.
* Transaction Queues::       Transaction-based communication with subprocesses.
* Network::                  Opening network connections.
* Network Servers::          Network servers let Emacs accept net connections.
* Datagrams::                UDP network connections.
* Low-Level Network::        Lower-level but more general function
                               to create connections and servers.
* Misc Network::             Additional relevant functions for net connections.
* Serial Ports::             Communicating with serial ports.
* Byte Packing::             Using bindat to pack and unpack binary data.


File: elisp,  Node: Subprocess Creation,  Next: Shell Arguments,  Up: Processes

37.1 Functions that Create Subprocesses
=======================================

There are three primitives that create a new subprocess in which to run
a program.  One of them, `start-process', creates an asynchronous
process and returns a process object (*note Asynchronous Processes::).
The other two, `call-process' and `call-process-region', create a
synchronous process and do not return a process object (*note
Synchronous Processes::).

   Synchronous and asynchronous processes are explained in the following
sections.  Since the three functions are all called in a similar
fashion, their common arguments are described here.

   In all cases, the function's PROGRAM argument specifies the program
to be run.  An error is signaled if the file is not found or cannot be
executed.  If the file name is relative, the variable `exec-path'
contains a list of directories to search.  Emacs initializes
`exec-path' when it starts up, based on the value of the environment
variable `PATH'.  The standard file name constructs, `~', `.', and
`..', are interpreted as usual in `exec-path', but environment variable
substitutions (`$HOME', etc.) are not recognized; use
`substitute-in-file-name' to perform them (*note File Name
Expansion::).  `nil' in this list refers to `default-directory'.

   Executing a program can also try adding suffixes to the specified
name:

 -- Variable: exec-suffixes
     This variable is a list of suffixes (strings) to try adding to the
     specified program file name.  The list should include `""' if you
     want the name to be tried exactly as specified.  The default value
     is system-dependent.

   *Please note:* The argument PROGRAM contains only the name of the
program; it may not contain any command-line arguments.  You must use
ARGS to provide those.

   Each of the subprocess-creating functions has a BUFFER-OR-NAME
argument which specifies where the standard output from the program will
go.  It should be a buffer or a buffer name; if it is a buffer name,
that will create the buffer if it does not already exist.  It can also
be `nil', which says to discard the output unless a filter function
handles it.  (*Note Filter Functions::, and *note Read and Print::.)
Normally, you should avoid having multiple processes send output to the
same buffer because their output would be intermixed randomly.

   All three of the subprocess-creating functions have a `&rest'
argument, ARGS.  The ARGS must all be strings, and they are supplied to
PROGRAM as separate command line arguments.  Wildcard characters and
other shell constructs have no special meanings in these strings, since
the strings are passed directly to the specified program.

   The subprocess gets its current directory from the value of
`default-directory' (*note File Name Expansion::).

   The subprocess inherits its environment from Emacs, but you can
specify overrides for it with `process-environment'.  *Note System
Environment::.

 -- Variable: exec-directory
     The value of this variable is a string, the name of a directory
     that contains programs that come with GNU Emacs, programs intended
     for Emacs to invoke.  The program `movemail' is an example of such
     a program; Rmail uses it to fetch new mail from an inbox.

 -- User Option: exec-path
     The value of this variable is a list of directories to search for
     programs to run in subprocesses.  Each element is either the name
     of a directory (i.e., a string), or `nil', which stands for the
     default directory (which is the value of `default-directory').  

     The value of `exec-path' is used by `call-process' and
     `start-process' when the PROGRAM argument is not an absolute file
     name.


File: elisp,  Node: Shell Arguments,  Next: Synchronous Processes,  Prev: Subprocess Creation,  Up: Processes

37.2 Shell Arguments
====================

Lisp programs sometimes need to run a shell and give it a command that
contains file names that were specified by the user.  These programs
ought to be able to support any valid file name.  But the shell gives
special treatment to certain characters, and if these characters occur
in the file name, they will confuse the shell.  To handle these
characters, use the function `shell-quote-argument':

 -- Function: shell-quote-argument argument
     This function returns a string which represents, in shell syntax,
     an argument whose actual contents are ARGUMENT.  It should work
     reliably to concatenate the return value into a shell command and
     then pass it to a shell for execution.

     Precisely what this function does depends on your operating
     system.  The function is designed to work with the syntax of your
     system's standard shell; if you use an unusual shell, you will
     need to redefine this function.

          ;; This example shows the behavior on GNU and Unix systems.
          (shell-quote-argument "foo > bar")
               => "foo\\ \\>\\ bar"

          ;; This example shows the behavior on MS-DOS and MS-Windows.
          (shell-quote-argument "foo > bar")
               => "\"foo > bar\""

     Here's an example of using `shell-quote-argument' to construct a
     shell command:

          (concat "diff -c "
                  (shell-quote-argument oldfile)
                  " "
                  (shell-quote-argument newfile))

   The following two functions are useful for combining a list of
individual command-line argument strings into a single string, and
taking a string apart into a list of individual command-line arguments.
These functions are mainly intended to be used for converting user
input in the minibuffer, a Lisp string, into a list of string arguments
to be passed to `call-process' or `start-process', or for the
converting such lists of arguments in a single Lisp string to be
presented in the minibuffer or echo area.

 -- Function: split-string-and-unquote string &optional separators
     This function splits STRING into substrings at matches for the
     regular expression SEPARATORS, like `split-string' does (*note
     Creating Strings::); in addition, it removes quoting from the
     substrings.  It then makes a list of the substrings and returns it.

     If SEPARATORS is omitted or `nil', it defaults to `"\\s-+"', which
     is a regular expression that matches one or more characters with
     whitespace syntax (*note Syntax Class Table::).

     This function supports two types of quoting: enclosing a whole
     string in double quotes `"..."', and quoting individual characters
     with a backslash escape `\'.  The latter is also used in Lisp
     strings, so this function can handle those as well.

 -- Function: combine-and-quote-strings list-of-strings &optional
          separator
     This function concatenates LIST-OF-STRINGS into a single string,
     quoting each string as necessary.  It also sticks the SEPARATOR
     string between each pair of strings; if SEPARATOR is omitted or
     `nil', it defaults to `" "'.  The return value is the resulting
     string.

     The strings in LIST-OF-STRINGS that need quoting are those that
     include SEPARATOR as their substring.  Quoting a string encloses
     it in double quotes `"..."'.  In the simplest case, if you are
     consing a command from the individual command-line arguments,
     every argument that includes embedded blanks will be quoted.


File: elisp,  Node: Synchronous Processes,  Next: Asynchronous Processes,  Prev: Shell Arguments,  Up: Processes

37.3 Creating a Synchronous Process
===================================

After a "synchronous process" is created, Emacs waits for the process
to terminate before continuing.  Starting Dired on GNU or Unix(1) is an
example of this: it runs `ls' in a synchronous process, then modifies
the output slightly.  Because the process is synchronous, the entire
directory listing arrives in the buffer before Emacs tries to do
anything with it.

   While Emacs waits for the synchronous subprocess to terminate, the
user can quit by typing `C-g'.  The first `C-g' tries to kill the
subprocess with a `SIGINT' signal; but it waits until the subprocess
actually terminates before quitting.  If during that time the user
types another `C-g', that kills the subprocess instantly with `SIGKILL'
and quits immediately (except on MS-DOS, where killing other processes
doesn't work).  *Note Quitting::.

   The synchronous subprocess functions return an indication of how the
process terminated.

   The output from a synchronous subprocess is generally decoded using a
coding system, much like text read from a file.  The input sent to a
subprocess by `call-process-region' is encoded using a coding system,
much like text written into a file.  *Note Coding Systems::.

 -- Function: call-process program &optional infile destination display
          &rest args
     This function calls PROGRAM in a separate process and waits for it
     to finish.

     The standard input for the process comes from file INFILE if
     INFILE is not `nil', and from the null device otherwise.  The
     argument DESTINATION says where to put the process output.  Here
     are the possibilities:

    a buffer
          Insert the output in that buffer, before point.  This
          includes both the standard output stream and the standard
          error stream of the process.

    a string
          Insert the output in a buffer with that name, before point.

    `t'
          Insert the output in the current buffer, before point.

    `nil'
          Discard the output.

    0
          Discard the output, and return `nil' immediately without
          waiting for the subprocess to finish.

          In this case, the process is not truly synchronous, since it
          can run in parallel with Emacs; but you can think of it as
          synchronous in that Emacs is essentially finished with the
          subprocess as soon as this function returns.

          MS-DOS doesn't support asynchronous subprocesses, so this
          option doesn't work there.

    `(REAL-DESTINATION ERROR-DESTINATION)'
          Keep the standard output stream separate from the standard
          error stream; deal with the ordinary output as specified by
          REAL-DESTINATION, and dispose of the error output according
          to ERROR-DESTINATION.  If ERROR-DESTINATION is `nil', that
          means to discard the error output, `t' means mix it with the
          ordinary output, and a string specifies a file name to
          redirect error output into.

          You can't directly specify a buffer to put the error output
          in; that is too difficult to implement.  But you can achieve
          this result by sending the error output to a temporary file
          and then inserting the file into a buffer.

     If DISPLAY is non-`nil', then `call-process' redisplays the buffer
     as output is inserted.  (However, if the coding system chosen for
     decoding output is `undecided', meaning deduce the encoding from
     the actual data, then redisplay sometimes cannot continue once
     non-ASCII characters are encountered.  There are fundamental
     reasons why it is hard to fix this; see *note Output from
     Processes::.)

     Otherwise the function `call-process' does no redisplay, and the
     results become visible on the screen only when Emacs redisplays
     that buffer in the normal course of events.

     The remaining arguments, ARGS, are strings that specify command
     line arguments for the program.

     The value returned by `call-process' (unless you told it not to
     wait) indicates the reason for process termination.  A number
     gives the exit status of the subprocess; 0 means success, and any
     other value means failure.  If the process terminated with a
     signal, `call-process' returns a string describing the signal.

     In the examples below, the buffer `foo' is current.

          (call-process "pwd" nil t)
               => 0

          ---------- Buffer: foo ----------
          /usr/user/lewis/manual
          ---------- Buffer: foo ----------

          (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
               => 0

          ---------- Buffer: bar ----------
          lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh

          ---------- Buffer: bar ----------

     Here is a good example of the use of `call-process', which used to
     be found in the definition of `insert-directory':

          (call-process insert-directory-program nil t nil SWITCHES
                        (if full-directory-p
                            (concat (file-name-as-directory file) ".")
                          file))

 -- Function: process-file program &optional infile buffer display
          &rest args
     This function processes files synchronously in a separate process.
     It is similar to `call-process' but may invoke a file handler based
     on the value of the variable `default-directory'.  The current
     working directory of the subprocess is `default-directory'.

     The arguments are handled in almost the same way as for
     `call-process', with the following differences:

     Some file handlers may not support all combinations and forms of
     the arguments INFILE, BUFFER, and DISPLAY.  For example, some file
     handlers might behave as if DISPLAY were `nil', regardless of the
     value actually passed.  As another example, some file handlers
     might not support separating standard output and error output by
     way of the BUFFER argument.

     If a file handler is invoked, it determines the program to run
     based on the first argument PROGRAM.  For instance, consider that a
     handler for remote files is invoked.  Then the path that is used
     for searching the program might be different than `exec-path'.

     The second argument INFILE may invoke a file handler.  The file
     handler could be different from the handler chosen for the
     `process-file' function itself.  (For example, `default-directory'
     could be on a remote host, whereas INFILE is on another remote
     host.  Or `default-directory' could be non-special, whereas INFILE
     is on a remote host.)

     If BUFFER is a list of the form `(REAL-DESTINATION
     ERROR-DESTINATION)', and ERROR-DESTINATION names a file, then the
     same remarks as for INFILE apply.

     The remaining arguments (ARGS) will be passed to the process
     verbatim.  Emacs is not involved in processing file names that are
     present in ARGS.  To avoid confusion, it may be best to avoid
     absolute file names in ARGS, but rather to specify all file names
     as relative to `default-directory'.  The function
     `file-relative-name' is useful for constructing such relative file
     names.

 -- Variable: process-file-side-effects
     This variable indicates, whether a call of `process-file' changes
     remote files.

     Per default, this variable is always set to `t', meaning that a
     call of `process-file' could potentially change any file on a
     remote host.  When set to `nil', a file handler could optimize its
     behaviour with respect to remote file attributes caching.

     This variable should never be changed by `setq'.  Instead of, it
     shall be set only by let-binding.

 -- Function: call-process-region start end program &optional delete
          destination display &rest args
     This function sends the text from START to END as standard input
     to a process running PROGRAM.  It deletes the text sent if DELETE
     is non-`nil'; this is useful when DESTINATION is `t', to insert
     the output in the current buffer in place of the input.

     The arguments DESTINATION and DISPLAY control what to do with the
     output from the subprocess, and whether to update the display as
     it comes in.  For details, see the description of `call-process',
     above.  If DESTINATION is the integer 0, `call-process-region'
     discards the output and returns `nil' immediately, without waiting
     for the subprocess to finish (this only works if asynchronous
     subprocesses are supported).

     The remaining arguments, ARGS, are strings that specify command
     line arguments for the program.

     The return value of `call-process-region' is just like that of
     `call-process': `nil' if you told it to return without waiting;
     otherwise, a number or string which indicates how the subprocess
     terminated.

     In the following example, we use `call-process-region' to run the
     `cat' utility, with standard input being the first five characters
     in buffer `foo' (the word `input').  `cat' copies its standard
     input into its standard output.  Since the argument DESTINATION is
     `t', this output is inserted in the current buffer.

          ---------- Buffer: foo ----------
          input-!-
          ---------- Buffer: foo ----------

          (call-process-region 1 6 "cat" nil t)
               => 0

          ---------- Buffer: foo ----------
          inputinput-!-
          ---------- Buffer: foo ----------

     The `shell-command-on-region' command uses `call-process-region'
     like this:

          (call-process-region
           start end
           shell-file-name      ; Name of program.
           nil                  ; Do not delete region.
           buffer               ; Send output to `buffer'.
           nil                  ; No redisplay during output.
           "-c" command)        ; Arguments for the shell.

 -- Function: call-process-shell-command command &optional infile
          destination display &rest args
     This function executes the shell command COMMAND synchronously in
     a separate process.  The final arguments ARGS are additional
     arguments to add at the end of COMMAND.  The other arguments are
     handled as in `call-process'.

 -- Function: process-file-shell-command command &optional infile
          destination display &rest args
     This function is like `call-process-shell-command', but uses
     `process-file' internally.  Depending on `default-directory',
     COMMAND can be executed also on remote hosts.

 -- Function: shell-command-to-string command
     This function executes COMMAND (a string) as a shell command, then
     returns the command's output as a string.

 -- Function: process-lines program &rest args
     This function runs PROGRAM in a separate process, waits for it to
     finish, and returns its output as a list of strings.  Each string
     in the list holds a single line of text output by the program; the
     end-of-line characters are stripped from each line.  The arguments
     beyond PROGRAM, ARGS, are strings that specify command-line
     arguments with which to run the program.

     If PROGRAM exits with a non-zero exit status, this function
     signals an error.

     This function works by calling `call-process', so program output
     is decoded in the same way as for `call-process'.

   ---------- Footnotes ----------

   (1) On other systems, Emacs uses a Lisp emulation of `ls'; see *note
Contents of Directories::.


File: elisp,  Node: Asynchronous Processes,  Next: Deleting Processes,  Prev: Synchronous Processes,  Up: Processes

37.4 Creating an Asynchronous Process
=====================================

After an "asynchronous process" is created, Emacs and the subprocess
both continue running immediately.  The process thereafter runs in
parallel with Emacs, and the two can communicate with each other using
the functions described in the following sections.  However,
communication is only partially asynchronous: Emacs sends data to the
process only when certain functions are called, and Emacs accepts data
from the process only when Emacs is waiting for input or for a time
delay.

   Here we describe how to create an asynchronous process.

 -- Function: start-process name buffer-or-name program &rest args
     This function creates a new asynchronous subprocess and starts the
     program PROGRAM running in it.  It returns a process object that
     stands for the new subprocess in Lisp.  The argument NAME
     specifies the name for the process object; if a process with this
     name already exists, then NAME is modified (by appending `<1>',
     etc.) to be unique.  The buffer BUFFER-OR-NAME is the buffer to
     associate with the process.

     The remaining arguments, ARGS, are strings that specify command
     line arguments for the program.

     In the example below, the first process is started and runs
     (rather, sleeps) for 100 seconds.  Meanwhile, the second process
     is started, and given the name `my-process<1>' for the sake of
     uniqueness.  It inserts the directory listing at the end of the
     buffer `foo', before the first process finishes.  Then it
     finishes, and a message to that effect is inserted in the buffer.
     Much later, the first process finishes, and another message is
     inserted in the buffer for it.

          (start-process "my-process" "foo" "sleep" "100")
               => #<process my-process>

          (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
               => #<process my-process<1>>

          ---------- Buffer: foo ----------
          total 2
          lrwxrwxrwx  1 lewis     14 Jul 22 10:12 gnuemacs --> /emacs
          -rwxrwxrwx  1 lewis     19 Jul 30 21:02 lemon

          Process my-process<1> finished

          Process my-process finished
          ---------- Buffer: foo ----------

 -- Function: start-file-process name buffer-or-name program &rest args
     Like `start-process', this function starts a new asynchronous
     subprocess running PROGRAM in it, and returns its process
     object--when `default-directory' is not a magic file name.

     If `default-directory' is magic, the function invokes its file
     handler instead.  This handler ought to run PROGRAM, perhaps on
     the local host, perhaps on a remote host that corresponds to
     `default-directory'.  In the latter case, the local part of
     `default-directory' becomes the working directory of the process.

     This function does not try to invoke file name handlers for
     PROGRAM or for the PROGRAM-ARGS.

     Depending on the implementation of the file handler, it might not
     be possible to apply `process-filter' or `process-sentinel' to the
     resulting process object (*note Filter Functions::, *note
     Sentinels::).

     Some file handlers may not support `start-file-process' (for
     example `ange-ftp-hook-function').  In such cases, the function
     does nothing and returns `nil'.

 -- Function: start-process-shell-command name buffer-or-name command
     This function is like `start-process' except that it uses a shell
     to execute the specified command.  The argument COMMAND is a shell
     command name.  The variable `shell-file-name' specifies which
     shell to use.

     The point of running a program through the shell, rather than
     directly with `start-process', is so that you can employ shell
     features such as wildcards in the arguments.  It follows that if
     you include an arbitrary user-specified arguments in the command,
     you should quote it with `shell-quote-argument' first, so that any
     special shell characters do _not_ have their special shell
     meanings.  *Note Shell Arguments::.

 -- Function: start-file-process-shell-command name buffer-or-name
          command
     This function is like `start-process-shell-command', but uses
     `start-file-process' internally.  By this, COMMAND can be executed
     also on remote hosts, depending on `default-directory'.

 -- Variable: process-connection-type
     This variable controls the type of device used to communicate with
     asynchronous subprocesses.  If it is non-`nil', then PTYs are
     used, when available.  Otherwise, pipes are used.

     PTYs are usually preferable for processes visible to the user, as
     in Shell mode, because they allow job control (`C-c', `C-z', etc.)
     to work between the process and its children, whereas pipes do
     not.  For subprocesses used for internal purposes by programs, it
     is often better to use a pipe, because they are more efficient.  In
     addition, the total number of PTYs is limited on many systems and
     it is good not to waste them.

     The value of `process-connection-type' takes effect when
     `start-process' is called.  So you can specify how to communicate
     with one subprocess by binding the variable around the call to
     `start-process'.

          (let ((process-connection-type nil))  ; Use a pipe.
            (start-process ...))

     To determine whether a given subprocess actually got a pipe or a
     PTY, use the function `process-tty-name' (*note Process
     Information::).


File: elisp,  Node: Deleting Processes,  Next: Process Information,  Prev: Asynchronous Processes,  Up: Processes

37.5 Deleting Processes
=======================

"Deleting a process" disconnects Emacs immediately from the subprocess.
Processes are deleted automatically after they terminate, but not
necessarily right away.  You can delete a process explicitly at any
time.  If you delete a terminated process explicitly before it is
deleted automatically, no harm results.  Deleting a running process
sends a signal to terminate it (and its child processes if any), and
calls the process sentinel if it has one.  *Note Sentinels::.

   When a process is deleted, the process object itself continues to
exist as long as other Lisp objects point to it.  All the Lisp
primitives that work on process objects accept deleted processes, but
those that do I/O or send signals will report an error.  The process
mark continues to point to the same place as before, usually into a
buffer where output from the process was being inserted.

 -- User Option: delete-exited-processes
     This variable controls automatic deletion of processes that have
     terminated (due to calling `exit' or to a signal).  If it is
     `nil', then they continue to exist until the user runs
     `list-processes'.  Otherwise, they are deleted immediately after
     they exit.

 -- Function: delete-process process
     This function deletes a process, killing it with a `SIGKILL'
     signal.  The argument may be a process, the name of a process, a
     buffer, or the name of a buffer.  (A buffer or buffer-name stands
     for the process that `get-buffer-process' returns.)  Calling
     `delete-process' on a running process terminates it, updates the
     process status, and runs the sentinel (if any) immediately.  If the
     process has already terminated, calling `delete-process' has no
     effect on its status, or on the running of its sentinel (which will
     happen sooner or later).

          (delete-process "*shell*")
               => nil


File: elisp,  Node: Process Information,  Next: Input to Processes,  Prev: Deleting Processes,  Up: Processes

37.6 Process Information
========================

Several functions return information about processes.  `list-processes'
is provided for interactive use.

 -- Command: list-processes &optional query-only
     This command displays a listing of all living processes.  In
     addition, it finally deletes any process whose status was `Exited'
     or `Signaled'.  It returns `nil'.

     If QUERY-ONLY is non-`nil' then it lists only processes whose
     query flag is non-`nil'.  *Note Query Before Exit::.

 -- Function: process-list
     This function returns a list of all processes that have not been
     deleted.

          (process-list)
               => (#<process display-time> #<process shell>)

 -- Function: get-process name
     This function returns the process named NAME, or `nil' if there is
     none.  An error is signaled if NAME is not a string.

          (get-process "shell")
               => #<process shell>

 -- Function: process-command process
     This function returns the command that was executed to start
     PROCESS.  This is a list of strings, the first string being the
     program executed and the rest of the strings being the arguments
     that were given to the program.

          (process-command (get-process "shell"))
               => ("/bin/csh" "-i")

 -- Function: process-contact process &optional key
     This function returns information about how a network or serial
     process was set up.  For a network process, when KEY is `nil', it
     returns `(HOSTNAME SERVICE)' which specifies what you connected
     to.  For a serial process, when KEY is `nil', it returns `(PORT
     SPEED)'.  For an ordinary child process, this function always
     returns `t'.

     If KEY is `t', the value is the complete status information for
     the connection, server, or serial port; that is, the list of
     keywords and values specified in `make-network-process' or
     `make-serial-process', except that some of the values represent
     the current status instead of what you specified.

     For a network process:

    `:buffer'
          The associated value is the process buffer.

    `:filter'
          The associated value is the process filter function.

    `:sentinel'
          The associated value is the process sentinel function.

    `:remote'
          In a connection, the address in internal format of the remote
          peer.

    `:local'
          The local address, in internal format.

    `:service'
          In a server, if you specified `t' for SERVICE, this value is
          the actual port number.

     `:local' and `:remote' are included even if they were not
     specified explicitly in `make-network-process'.

     For a serial process, see `make-serial-process' and
     `serial-process-configure' for a list of keys.

     If KEY is a keyword, the function returns the value corresponding
     to that keyword.

 -- Function: process-id process
     This function returns the PID of PROCESS.  This is an integer that
     distinguishes the process PROCESS from all other processes running
     on the same computer at the current time.  The PID of a process is
     chosen by the operating system kernel when the process is started
     and remains constant as long as the process exists.

 -- Function: process-name process
     This function returns the name of PROCESS.

 -- Function: process-status process-name
     This function returns the status of PROCESS-NAME as a symbol.  The
     argument PROCESS-NAME must be a process, a buffer, or a process
     name (a string).

     The possible values for an actual subprocess are:

    `run'
          for a process that is running.

    `stop'
          for a process that is stopped but continuable.

    `exit'
          for a process that has exited.

    `signal'
          for a process that has received a fatal signal.

    `open'
          for a network connection that is open.

    `closed'
          for a network connection that is closed.  Once a connection
          is closed, you cannot reopen it, though you might be able to
          open a new connection to the same place.

    `connect'
          for a non-blocking connection that is waiting to complete.

    `failed'
          for a non-blocking connection that has failed to complete.

    `listen'
          for a network server that is listening.

    `nil'
          if PROCESS-NAME is not the name of an existing process.

          (process-status (get-buffer "*shell*"))
               => run
          x
               => #<process xx<1>>
          (process-status x)
               => exit

     For a network connection, `process-status' returns one of the
     symbols `open' or `closed'.  The latter means that the other side
     closed the connection, or Emacs did `delete-process'.

 -- Function: process-type process
     This function returns the symbol `network' for a network
     connection or server, `serial' for a serial port connection, or
     `real' for a real subprocess.

 -- Function: process-exit-status process
     This function returns the exit status of PROCESS or the signal
     number that killed it.  (Use the result of `process-status' to
     determine which of those it is.)  If PROCESS has not yet
     terminated, the value is 0.

 -- Function: process-tty-name process
     This function returns the terminal name that PROCESS is using for
     its communication with Emacs--or `nil' if it is using pipes
     instead of a terminal (see `process-connection-type' in *note
     Asynchronous Processes::).

 -- Function: process-coding-system process
     This function returns a cons cell describing the coding systems in
     use for decoding output from PROCESS and for encoding input to
     PROCESS (*note Coding Systems::).  The value has this form:

          (CODING-SYSTEM-FOR-DECODING . CODING-SYSTEM-FOR-ENCODING)

 -- Function: set-process-coding-system process &optional
          decoding-system encoding-system
     This function specifies the coding systems to use for subsequent
     output from and input to PROCESS.  It will use DECODING-SYSTEM to
     decode subprocess output, and ENCODING-SYSTEM to encode subprocess
     input.

   Every process also has a property list that you can use to store
miscellaneous values associated with the process.

 -- Function: process-get process propname
     This function returns the value of the PROPNAME property of
     PROCESS.

 -- Function: process-put process propname value
     This function sets the value of the PROPNAME property of PROCESS
     to VALUE.

 -- Function: process-plist process
     This function returns the process plist of PROCESS.

 -- Function: set-process-plist process plist
     This function sets the process plist of PROCESS to PLIST.


File: elisp,  Node: Input to Processes,  Next: Signals to Processes,  Prev: Process Information,  Up: Processes

37.7 Sending Input to Processes
===============================

Asynchronous subprocesses receive input when it is sent to them by
Emacs, which is done with the functions in this section.  You must
specify the process to send input to, and the input data to send.  The
data appears on the "standard input" of the subprocess.

   Some operating systems have limited space for buffered input in a
PTY.  On these systems, Emacs sends an EOF periodically amidst the
other characters, to force them through.  For most programs, these EOFs
do no harm.

   Subprocess input is normally encoded using a coding system before the
subprocess receives it, much like text written into a file.  You can use
`set-process-coding-system' to specify which coding system to use
(*note Process Information::).  Otherwise, the coding system comes from
`coding-system-for-write', if that is non-`nil'; or else from the
defaulting mechanism (*note Default Coding Systems::).

   Sometimes the system is unable to accept input for that process,
because the input buffer is full.  When this happens, the send functions
wait a short while, accepting output from subprocesses, and then try
again.  This gives the subprocess a chance to read more of its pending
input and make space in the buffer.  It also allows filters, sentinels
and timers to run--so take account of that in writing your code.

   In these functions, the PROCESS argument can be a process or the
name of a process, or a buffer or buffer name (which stands for a
process via `get-buffer-process').  `nil' means the current buffer's
process.

 -- Function: process-send-string process string
     This function sends PROCESS the contents of STRING as standard
     input.  If it is `nil', the current buffer's process is used.

     The function returns `nil'.

          (process-send-string "shell<1>" "ls\n")
               => nil


          ---------- Buffer: *shell* ----------
          ...
          introduction.texi               syntax-tables.texi~
          introduction.texi~              text.texi
          introduction.txt                text.texi~
          ...
          ---------- Buffer: *shell* ----------

 -- Function: process-send-region process start end
     This function sends the text in the region defined by START and
     END as standard input to PROCESS.

     An error is signaled unless both START and END are integers or
     markers that indicate positions in the current buffer.  (It is
     unimportant which number is larger.)

 -- Function: process-send-eof &optional process
     This function makes PROCESS see an end-of-file in its input.  The
     EOF comes after any text already sent to it.

     The function returns PROCESS.

          (process-send-eof "shell")
               => "shell"

 -- Function: process-running-child-p &optional process
     This function will tell you whether a PROCESS has given control of
     its terminal to its own child process.  The value is `t' if this is
     true, or if Emacs cannot tell; it is `nil' if Emacs can be certain
     that this is not so.


File: elisp,  Node: Signals to Processes,  Next: Output from Processes,  Prev: Input to Processes,  Up: Processes

37.8 Sending Signals to Processes
=================================

"Sending a signal" to a subprocess is a way of interrupting its
activities.  There are several different signals, each with its own
meaning.  The set of signals and their names is defined by the operating
system.  For example, the signal `SIGINT' means that the user has typed
`C-c', or that some analogous thing has happened.

   Each signal has a standard effect on the subprocess.  Most signals
kill the subprocess, but some stop or resume execution instead.  Most
signals can optionally be handled by programs; if the program handles
the signal, then we can say nothing in general about its effects.

   You can send signals explicitly by calling the functions in this
section.  Emacs also sends signals automatically at certain times:
killing a buffer sends a `SIGHUP' signal to all its associated
processes; killing Emacs sends a `SIGHUP' signal to all remaining
processes.  (`SIGHUP' is a signal that usually indicates that the user
hung up the phone.)

   Each of the signal-sending functions takes two optional arguments:
PROCESS and CURRENT-GROUP.

   The argument PROCESS must be either a process, a process name, a
buffer, a buffer name, or `nil'.  A buffer or buffer name stands for a
process through `get-buffer-process'.  `nil' stands for the process
associated with the current buffer.  An error is signaled if PROCESS
does not identify a process.

   The argument CURRENT-GROUP is a flag that makes a difference when
you are running a job-control shell as an Emacs subprocess.  If it is
non-`nil', then the signal is sent to the current process-group of the
terminal that Emacs uses to communicate with the subprocess.  If the
process is a job-control shell, this means the shell's current subjob.
If it is `nil', the signal is sent to the process group of the
immediate subprocess of Emacs.  If the subprocess is a job-control
shell, this is the shell itself.

   The flag CURRENT-GROUP has no effect when a pipe is used to
communicate with the subprocess, because the operating system does not
support the distinction in the case of pipes.  For the same reason,
job-control shells won't work when a pipe is used.  See
`process-connection-type' in *note Asynchronous Processes::.

 -- Function: interrupt-process &optional process current-group
     This function interrupts the process PROCESS by sending the signal
     `SIGINT'.  Outside of Emacs, typing the "interrupt character"
     (normally `C-c' on some systems, and `DEL' on others) sends this
     signal.  When the argument CURRENT-GROUP is non-`nil', you can
     think of this function as "typing `C-c'" on the terminal by which
     Emacs talks to the subprocess.

 -- Function: kill-process &optional process current-group
     This function kills the process PROCESS by sending the signal
     `SIGKILL'.  This signal kills the subprocess immediately, and
     cannot be handled by the subprocess.

 -- Function: quit-process &optional process current-group
     This function sends the signal `SIGQUIT' to the process PROCESS.
     This signal is the one sent by the "quit character" (usually `C-b'
     or `C-\') when you are not inside Emacs.

 -- Function: stop-process &optional process current-group
     This function stops the process PROCESS by sending the signal
     `SIGTSTP'.  Use `continue-process' to resume its execution.

     Outside of Emacs, on systems with job control, the "stop character"
     (usually `C-z') normally sends this signal.  When CURRENT-GROUP is
     non-`nil', you can think of this function as "typing `C-z'" on the
     terminal Emacs uses to communicate with the subprocess.

 -- Function: continue-process &optional process current-group
     This function resumes execution of the process PROCESS by sending
     it the signal `SIGCONT'.  This presumes that PROCESS was stopped
     previously.

 -- Function: signal-process process signal
     This function sends a signal to process PROCESS.  The argument
     SIGNAL specifies which signal to send; it should be an integer.

     The PROCESS argument can be a system process ID; that allows you
     to send signals to processes that are not children of Emacs.
     *Note System Processes::.


File: elisp,  Node: Output from Processes,  Next: Sentinels,  Prev: Signals to Processes,  Up: Processes

37.9 Receiving Output from Processes
====================================

There are two ways to receive the output that a subprocess writes to
its standard output stream.  The output can be inserted in a buffer,
which is called the associated buffer of the process, or a function
called the "filter function" can be called to act on the output.  If
the process has no buffer and no filter function, its output is
discarded.

   When a subprocess terminates, Emacs reads any pending output, then
stops reading output from that subprocess.  Therefore, if the
subprocess has children that are still live and still producing output,
Emacs won't receive that output.

   Output from a subprocess can arrive only while Emacs is waiting: when
reading terminal input, in `sit-for' and `sleep-for' (*note Waiting::),
and in `accept-process-output' (*note Accepting Output::).  This
minimizes the problem of timing errors that usually plague parallel
programming.  For example, you can safely create a process and only
then specify its buffer or filter function; no output can arrive before
you finish, if the code in between does not call any primitive that
waits.

 -- Variable: process-adaptive-read-buffering
     On some systems, when Emacs reads the output from a subprocess, the
     output data is read in very small blocks, potentially resulting in
     very poor performance.  This behavior can be remedied to some
     extent by setting the variable PROCESS-ADAPTIVE-READ-BUFFERING to a
     non-`nil' value (the default), as it will automatically delay
     reading from such processes, thus allowing them to produce more
     output before Emacs tries to read it.

   It is impossible to separate the standard output and standard error
streams of the subprocess, because Emacs normally spawns the subprocess
inside a pseudo-TTY, and a pseudo-TTY has only one output channel.  If
you want to keep the output to those streams separate, you should
redirect one of them to a file--for example, by using an appropriate
shell command.

* Menu:

* Process Buffers::         If no filter, output is put in a buffer.
* Filter Functions::        Filter functions accept output from the process.
* Decoding Output::         Filters can get unibyte or multibyte strings.
* Accepting Output::        How to wait until process output arrives.


File: elisp,  Node: Process Buffers,  Next: Filter Functions,  Up: Output from Processes

37.9.1 Process Buffers
----------------------

A process can (and usually does) have an "associated buffer", which is
an ordinary Emacs buffer that is used for two purposes: storing the
output from the process, and deciding when to kill the process.  You
can also use the buffer to identify a process to operate on, since in
normal practice only one process is associated with any given buffer.
Many applications of processes also use the buffer for editing input to
be sent to the process, but this is not built into Emacs Lisp.

   Unless the process has a filter function (*note Filter Functions::),
its output is inserted in the associated buffer.  The position to insert
the output is determined by the `process-mark', which is then updated
to point to the end of the text just inserted.  Usually, but not
always, the `process-mark' is at the end of the buffer.

   Killing the associated buffer of a process also kills the process.
Emacs asks for confirmation first, if the process's
`process-query-on-exit-flag' is non-`nil' (*note Query Before Exit::).
This confirmation is done by the function
`process-kill-buffer-query-function', which is run from
`kill-buffer-query-functions' (*note Killing Buffers::).

 -- Function: process-buffer process
     This function returns the associated buffer of the process PROCESS.

          (process-buffer (get-process "shell"))
               => #<buffer *shell*>

 -- Function: process-mark process
     This function returns the process marker for PROCESS, which is the
     marker that says where to insert output from the process.

     If PROCESS does not have a buffer, `process-mark' returns a marker
     that points nowhere.

     Insertion of process output in a buffer uses this marker to decide
     where to insert, and updates it to point after the inserted text.
     That is why successive batches of output are inserted
     consecutively.

     Filter functions normally should use this marker in the same
     fashion as is done by direct insertion of output in the buffer.  A
     good example of a filter function that uses `process-mark' is
     found at the end of the following section.

     When the user is expected to enter input in the process buffer for
     transmission to the process, the process marker separates the new
     input from previous output.

 -- Function: set-process-buffer process buffer
     This function sets the buffer associated with PROCESS to BUFFER.
     If BUFFER is `nil', the process becomes associated with no buffer.

 -- Function: get-buffer-process buffer-or-name
     This function returns a nondeleted process associated with the
     buffer specified by BUFFER-OR-NAME.  If there are several processes
     associated with it, this function chooses one (currently, the one
     most recently created, but don't count on that).  Deletion of a
     process (see `delete-process') makes it ineligible for this
     function to return.

     It is usually a bad idea to have more than one process associated
     with the same buffer.

          (get-buffer-process "*shell*")
               => #<process shell>

     Killing the process's buffer deletes the process, which kills the
     subprocess with a `SIGHUP' signal (*note Signals to Processes::).


File: elisp,  Node: Filter Functions,  Next: Decoding Output,  Prev: Process Buffers,  Up: Output from Processes

37.9.2 Process Filter Functions
-------------------------------

A process "filter function" is a function that receives the standard
output from the associated process.  If a process has a filter, then
_all_ output from that process is passed to the filter.  The process
buffer is used directly for output from the process only when there is
no filter.

   The filter function can only be called when Emacs is waiting for
something, because process output arrives only at such times.  Emacs
waits when reading terminal input, in `sit-for' and `sleep-for' (*note
Waiting::), and in `accept-process-output' (*note Accepting Output::).

   A filter function must accept two arguments: the associated process
and a string, which is output just received from it.  The function is
then free to do whatever it chooses with the output.

   Quitting is normally inhibited within a filter function--otherwise,
the effect of typing `C-g' at command level or to quit a user command
would be unpredictable.  If you want to permit quitting inside a filter
function, bind `inhibit-quit' to `nil'.  In most cases, the right way
to do this is with the macro `with-local-quit'.  *Note Quitting::.

   If an error happens during execution of a filter function, it is
caught automatically, so that it doesn't stop the execution of whatever
program was running when the filter function was started.  However, if
`debug-on-error' is non-`nil', the error-catching is turned off.  This
makes it possible to use the Lisp debugger to debug the filter
function.  *Note Debugger::.

   Many filter functions sometimes or always insert the text in the
process's buffer, mimicking the actions of Emacs when there is no
filter.  Such filter functions need to use `set-buffer' in order to be
sure to insert in that buffer.  To avoid setting the current buffer
semipermanently, these filter functions must save and restore the
current buffer.  They should also update the process marker, and in some
cases update the value of point.  Here is how to do these things:

     (defun ordinary-insertion-filter (proc string)
       (with-current-buffer (process-buffer proc)
         (let ((moving (= (point) (process-mark proc))))
           (save-excursion
             ;; Insert the text, advancing the process marker.
             (goto-char (process-mark proc))
             (insert string)
             (set-marker (process-mark proc) (point)))
           (if moving (goto-char (process-mark proc))))))

The reason to use `with-current-buffer', rather than using
`save-excursion' to save and restore the current buffer, is so as to
preserve the change in point made by the second call to `goto-char'.

   To make the filter force the process buffer to be visible whenever
new text arrives, insert the following line just before the
`with-current-buffer' construct:

     (display-buffer (process-buffer proc))

   To force point to the end of the new output, no matter where it was
previously, eliminate the variable `moving' and call `goto-char'
unconditionally.

   In earlier Emacs versions, every filter function that did regular
expression searching or matching had to explicitly save and restore the
match data.  Now Emacs does this automatically for filter functions;
they never need to do it explicitly.  *Note Match Data::.

   A filter function that writes the output into the buffer of the
process should check whether the buffer is still alive.  If it tries to
insert into a dead buffer, it will get an error.  The expression
`(buffer-name (process-buffer PROCESS))' returns `nil' if the buffer is
dead.

   The output to the function may come in chunks of any size.  A program
that produces the same output twice in a row may send it as one batch of
200 characters one time, and five batches of 40 characters the next.  If
the filter looks for certain text strings in the subprocess output, make
sure to handle the case where one of these strings is split across two
or more batches of output; one way to do this is to insert the received
text into a temporary buffer, which can then be searched.

 -- Function: set-process-filter process filter
     This function gives PROCESS the filter function FILTER.  If FILTER
     is `nil', it gives the process no filter.

 -- Function: process-filter process
     This function returns the filter function of PROCESS, or `nil' if
     it has none.

   Here is an example of use of a filter function:

     (defun keep-output (process output)
        (setq kept (cons output kept)))
          => keep-output
     (setq kept nil)
          => nil
     (set-process-filter (get-process "shell") 'keep-output)
          => keep-output
     (process-send-string "shell" "ls ~/other\n")
          => nil
     kept
          => ("lewis@slug[8] % "
     "FINAL-W87-SHORT.MSS    backup.otl              kolstad.mss~
     address.txt             backup.psf              kolstad.psf
     backup.bib~             david.mss               resume-Dec-86.mss~
     backup.err              david.psf               resume-Dec.psf
     backup.mss              dland                   syllabus.mss
     "
     "#backups.mss#          backup.mss~             kolstad.mss
     ")


File: elisp,  Node: Decoding Output,  Next: Accepting Output,  Prev: Filter Functions,  Up: Output from Processes

37.9.3 Decoding Process Output
------------------------------

When Emacs writes process output directly into a multibyte buffer, it
decodes the output according to the process output coding system.  If
the coding system is `raw-text' or `no-conversion', Emacs converts the
unibyte output to multibyte using `string-to-multibyte', and inserts
the resulting multibyte text.

   You can use `set-process-coding-system' to specify which coding
system to use (*note Process Information::).  Otherwise, the coding
system comes from `coding-system-for-read', if that is non-`nil'; or
else from the defaulting mechanism (*note Default Coding Systems::).
If the text output by a process contains null bytes, Emacs by default
uses `no-conversion' for it; see *note inhibit-null-byte-detection:
Lisp and Coding Systems, for how to control this behavior.

   *Warning:* Coding systems such as `undecided' which determine the
coding system from the data do not work entirely reliably with
asynchronous subprocess output.  This is because Emacs has to process
asynchronous subprocess output in batches, as it arrives.  Emacs must
try to detect the proper coding system from one batch at a time, and
this does not always work.  Therefore, if at all possible, specify a
coding system that determines both the character code conversion and
the end of line conversion--that is, one like `latin-1-unix', rather
than `undecided' or `latin-1'.

   When Emacs calls a process filter function, it provides the process
output as a multibyte string or as a unibyte string according to the
process's filter coding system.  Emacs decodes the output according to
the process output coding system, which usually produces a multibyte
string, except for coding systems such as `binary' and `raw-text'


File: elisp,  Node: Accepting Output,  Prev: Decoding Output,  Up: Output from Processes

37.9.4 Accepting Output from Processes
--------------------------------------

Output from asynchronous subprocesses normally arrives only while Emacs
is waiting for some sort of external event, such as elapsed time or
terminal input.  Occasionally it is useful in a Lisp program to
explicitly permit output to arrive at a specific point, or even to wait
until output arrives from a process.

 -- Function: accept-process-output &optional process seconds millisec
          just-this-one
     This function allows Emacs to read pending output from processes.
     The output is inserted in the associated buffers or given to their
     filter functions.  If PROCESS is non-`nil' then this function does
     not return until some output has been received from PROCESS.

     The arguments SECONDS and MILLISEC let you specify timeout
     periods.  The former specifies a period measured in seconds and the
     latter specifies one measured in milliseconds.  The two time
     periods thus specified are added together, and
     `accept-process-output' returns after that much time, whether or
     not there has been any subprocess output.

     The argument MILLISEC is semi-obsolete nowadays because SECONDS
     can be a floating point number to specify waiting a fractional
     number of seconds.  If SECONDS is 0, the function accepts whatever
     output is pending but does not wait.

     If PROCESS is a process, and the argument JUST-THIS-ONE is
     non-`nil', only output from that process is handled, suspending
     output from other processes until some output has been received
     from that process or the timeout expires.  If JUST-THIS-ONE is an
     integer, also inhibit running timers.  This feature is generally
     not recommended, but may be necessary for specific applications,
     such as speech synthesis.

     The function `accept-process-output' returns non-`nil' if it did
     get some output, or `nil' if the timeout expired before output
     arrived.


File: elisp,  Node: Sentinels,  Next: Query Before Exit,  Prev: Output from Processes,  Up: Processes

37.10 Sentinels: Detecting Process Status Changes
=================================================

A "process sentinel" is a function that is called whenever the
associated process changes status for any reason, including signals
(whether sent by Emacs or caused by the process's own actions) that
terminate, stop, or continue the process.  The process sentinel is also
called if the process exits.  The sentinel receives two arguments: the
process for which the event occurred, and a string describing the type
of event.

   The string describing the event looks like one of the following:

   * `"finished\n"'.

   * `"exited abnormally with code EXITCODE\n"'.

   * `"NAME-OF-SIGNAL\n"'.

   * `"NAME-OF-SIGNAL (core dumped)\n"'.

   A sentinel runs only while Emacs is waiting (e.g., for terminal
input, or for time to elapse, or for process output).  This avoids the
timing errors that could result from running them at random places in
the middle of other Lisp programs.  A program can wait, so that
sentinels will run, by calling `sit-for' or `sleep-for' (*note
Waiting::), or `accept-process-output' (*note Accepting Output::).
Emacs also allows sentinels to run when the command loop is reading
input.  `delete-process' calls the sentinel when it terminates a
running process.

   Emacs does not keep a queue of multiple reasons to call the sentinel
of one process; it records just the current status and the fact that
there has been a change.  Therefore two changes in status, coming in
quick succession, can call the sentinel just once.  However, process
termination will always run the sentinel exactly once.  This is because
the process status can't change again after termination.

   Emacs explicitly checks for output from the process before running
the process sentinel.  Once the sentinel runs due to process
termination, no further output can arrive from the process.

   A sentinel that writes the output into the buffer of the process
should check whether the buffer is still alive.  If it tries to insert
into a dead buffer, it will get an error.  If the buffer is dead,
`(buffer-name (process-buffer PROCESS))' returns `nil'.

   Quitting is normally inhibited within a sentinel--otherwise, the
effect of typing `C-g' at command level or to quit a user command would
be unpredictable.  If you want to permit quitting inside a sentinel,
bind `inhibit-quit' to `nil'.  In most cases, the right way to do this
is with the macro `with-local-quit'.  *Note Quitting::.

   If an error happens during execution of a sentinel, it is caught
automatically, so that it doesn't stop the execution of whatever
programs was running when the sentinel was started.  However, if
`debug-on-error' is non-`nil', the error-catching is turned off.  This
makes it possible to use the Lisp debugger to debug the sentinel.
*Note Debugger::.

   While a sentinel is running, the process sentinel is temporarily set
to `nil' so that the sentinel won't run recursively.  For this reason
it is not possible for a sentinel to specify a new sentinel.

   In earlier Emacs versions, every sentinel that did regular expression
searching or matching had to explicitly save and restore the match data.
Now Emacs does this automatically for sentinels; they never need to do
it explicitly.  *Note Match Data::.

 -- Function: set-process-sentinel process sentinel
     This function associates SENTINEL with PROCESS.  If SENTINEL is
     `nil', then the process will have no sentinel.  The default
     behavior when there is no sentinel is to insert a message in the
     process's buffer when the process status changes.

     Changes in process sentinel take effect immediately--if the
     sentinel is slated to be run but has not been called yet, and you
     specify a new sentinel, the eventual call to the sentinel will use
     the new one.

          (defun msg-me (process event)
             (princ
               (format "Process: %s had the event `%s'" process event)))
          (set-process-sentinel (get-process "shell") 'msg-me)
               => msg-me
          (kill-process (get-process "shell"))
               -| Process: #<process shell> had the event `killed'
               => #<process shell>

 -- Function: process-sentinel process
     This function returns the sentinel of PROCESS, or `nil' if it has
     none.

 -- Function: waiting-for-user-input-p
     While a sentinel or filter function is running, this function
     returns non-`nil' if Emacs was waiting for keyboard input from the
     user at the time the sentinel or filter function was called, `nil'
     if it was not.


File: elisp,  Node: Query Before Exit,  Next: System Processes,  Prev: Sentinels,  Up: Processes

37.11 Querying Before Exit
==========================

When Emacs exits, it terminates all its subprocesses by sending them
the `SIGHUP' signal.  Because subprocesses may be doing valuable work,
Emacs normally asks the user to confirm that it is ok to terminate
them.  Each process has a query flag which, if non-`nil', says that
Emacs should ask for confirmation before exiting and thus killing that
process.  The default for the query flag is `t', meaning _do_ query.

 -- Function: process-query-on-exit-flag process
     This returns the query flag of PROCESS.

 -- Function: set-process-query-on-exit-flag process flag
     This function sets the query flag of PROCESS to FLAG.  It returns
     FLAG.

          ;; Don't query about the shell process
          (set-process-query-on-exit-flag (get-process "shell") nil)
               => t

 -- Function: process-kill-without-query process &optional do-query
     This function clears the query flag of PROCESS, so that Emacs will
     not query the user on account of that process.

     Actually, the function does more than that: it returns the old
     value of the process's query flag, and sets the query flag to
     DO-QUERY.  Please don't use this function to do those things any
     more--please use the newer, cleaner functions
     `process-query-on-exit-flag' and `set-process-query-on-exit-flag'
     in all but the simplest cases.  The only way you should use
     `process-kill-without-query' nowadays is like this:

          ;; Don't query about the shell process
          (process-kill-without-query (get-process "shell"))


File: elisp,  Node: System Processes,  Next: Transaction Queues,  Prev: Query Before Exit,  Up: Processes

37.12 Accessing Other Processes
===============================

In addition to accessing and manipulating processes that are
subprocesses of the current Emacs session, Emacs Lisp programs can also
access other processes running on the same machine.  We call these
"system processes", to distinguish between them and Emacs subprocesses.

   Emacs provides several primitives for accessing system processes.
Not all platforms support these primitives; on those which don't, these
primitives return `nil'.

 -- Function: list-system-processes
     This function returns a list of all the processes running on the
     system.  Each process is identified by its PID, a numerical
     process ID that is assigned by the OS and distinguishes the process
     from all the other processes running on the same machine at the
     same time.

 -- Function: process-attributes pid
     This function returns an alist of attributes for the process
     specified by its process ID PID.  Each association in the alist is
     of the form `(KEY . VALUE)', where KEY designates the attribute
     and VALUE is the value of that attribute.  The various attribute
     KEY's that this function can return are listed below.  Not all
     platforms support all of these attributes; if an attribute is not
     supported, its association will not appear in the returned alist.
     Values that are numbers can be either integer or floating-point,
     depending on the magnitude of the value.

    `euid'
          The effective user ID of the user who invoked the process.
          The corresponding VALUE is a number.  If the process was
          invoked by the same user who runs the current Emacs session,
          the value is identical to what `user-uid' returns (*note User
          Identification::).

    `user'
          User name corresponding to the process's effective user ID, a
          string.

    `egid'
          The group ID of the effective user ID, a number.

    `group'
          Group name corresponding to the effective user's group ID, a
          string.

    `comm'
          The name of the command that runs in the process.  This is a
          string that usually specifies the name of the executable file
          of the process, without the leading directories.  However,
          some special system processes can report strings that do not
          correspond to an executable file of a program.

    `state'
          The state code of the process.  This is a short string that
          encodes the scheduling state of the process.  Here's a list
          of the most frequently seen codes:

         `"D"'
               uninterruptible sleep (usually I/O)

         `"R"'
               running

         `"S"'
               interruptible sleep (waiting for some event)

         `"T"'
               stopped, e.g., by a job control signal

         `"Z"'
               "zombie": a process that terminated, but was not reaped
               by its parent

          For the full list of the possible states, see the manual page
          of the `ps' command.

    `ppid'
          The process ID of the parent process, a number.

    `pgrp'
          The process group ID of the process, a number.

    `sess'
          The session ID of the process.  This is a number that is the
          process ID of the process's "session leader".

    `ttname'
          A string that is the name of the process's controlling
          terminal.  On Unix and GNU systems, this is normally the file
          name of the corresponding terminal device, such as
          `/dev/pts65'.

    `tpgid'
          The numerical process group ID of the foreground process
          group that uses the process's terminal.

    `minflt'
          The number of minor page faults caused by the process since
          its beginning.  (Minor page faults are those that don't
          involve reading from disk.)

    `majflt'
          The number of major page faults caused by the process since
          its beginning.  (Major page faults require a disk to be read,
          and are thus more expensive than minor page faults.)

    `cminflt'
    `cmajflt'
          Like `minflt' and `majflt', but include the number of page
          faults for all the child processes of the given process.

    `utime'
          Time spent by the process in the user context, for running the
          application's code.  The corresponding VALUE is in the
          `(HIGH LOW MICROSEC)' format, the same format used by
          functions `current-time' (*note current-time: Time of Day.)
          and `file-attributes' (*note File Attributes::).

    `stime'
          Time spent by the process in the system (kernel) context, for
          processing system calls.  The corresponding VALUE is in the
          same format as for `utime'.

    `time'
          The sum of `utime' and `stime'.  The corresponding VALUE is
          in the same format as for `utime'.

    `cutime'
    `cstime'
    `ctime'
          Like `utime', `stime', and `time', but include the times of
          all the child processes of the given process.

    `pri'
          The numerical priority of the process.

    `nice'
          The "nice value" of the process, a number.  (Processes with
          smaller nice values get scheduled more favorably.)

    `thcount'
          The number of threads in the process.

    `start'
          The time when the process was started, in the same
          `(HIGH LOW MICROSEC)' format used by `current-time' and
          `file-attributes'.

    `etime'
          The time elapsed since the process started, in the
          `(HIGH LOW MICROSEC)' format.

    `vsize'
          The virtual memory size of the process, measured in kilobytes.

    `rss'
          The size of the process's "resident set", the number of
          kilobytes occupied by the process in the machine's physical
          memory.

    `pcpu'
          The percentage of the CPU time used by the process since it
          started.  The corresponding VALUE is a floating-point number
          between 0 and 100.

    `pmem'
          The percentage of the total physical memory installed on the
          machine used by the process's resident set.  The value is a
          floating-point number between 0 and 100.

    `args'
          The command-line with which the process was invoked.  This is
          a string in which individual command-line arguments are
          separated by blanks; whitespace characters that are embedded
          in the arguments are quoted as appropriate for the system's
          shell: escaped by backslash characters on GNU and Unix, and
          enclosed in double quote characters on Windows.  Thus, this
          command-line string can be directly used in primitives such
          as `shell-command'.



File: elisp,  Node: Transaction Queues,  Next: Network,  Prev: System Processes,  Up: Processes

37.13 Transaction Queues
========================

You can use a "transaction queue" to communicate with a subprocess
using transactions.  First use `tq-create' to create a transaction
queue communicating with a specified process.  Then you can call
`tq-enqueue' to send a transaction.

 -- Function: tq-create process
     This function creates and returns a transaction queue
     communicating with PROCESS.  The argument PROCESS should be a
     subprocess capable of sending and receiving streams of bytes.  It
     may be a child process, or it may be a TCP connection to a server,
     possibly on another machine.

 -- Function: tq-enqueue queue question regexp closure fn &optional
          delay-question
     This function sends a transaction to queue QUEUE.  Specifying the
     queue has the effect of specifying the subprocess to talk to.

     The argument QUESTION is the outgoing message that starts the
     transaction.  The argument FN is the function to call when the
     corresponding answer comes back; it is called with two arguments:
     CLOSURE, and the answer received.

     The argument REGEXP is a regular expression that should match text
     at the end of the entire answer, but nothing before; that's how
     `tq-enqueue' determines where the answer ends.

     If the argument DELAY-QUESTION is non-`nil', delay sending this
     question until the process has finished replying to any previous
     questions.  This produces more reliable results with some
     processes.

     The return value of `tq-enqueue' itself is not meaningful.

 -- Function: tq-close queue
     Shut down transaction queue QUEUE, waiting for all pending
     transactions to complete, and then terminate the connection or
     child process.

   Transaction queues are implemented by means of a filter function.
*Note Filter Functions::.


File: elisp,  Node: Network,  Next: Network Servers,  Prev: Transaction Queues,  Up: Processes

37.14 Network Connections
=========================

Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
connections to other processes on the same machine or other machines.
A network connection is handled by Lisp much like a subprocess, and is
represented by a process object.  However, the process you are
communicating with is not a child of the Emacs process, so it has no
process ID, and you can't kill it or send it signals.  All you can do
is send and receive data.  `delete-process' closes the connection, but
does not kill the program at the other end; that program must decide
what to do about closure of the connection.

   Lisp programs can listen for connections by creating network
servers.  A network server is also represented by a kind of process
object, but unlike a network connection, the network server never
transfers data itself.  When it receives a connection request, it
creates a new network connection to represent the connection just made.
(The network connection inherits certain information, including the
process plist, from the server.)  The network server then goes back to
listening for more connection requests.

   Network connections and servers are created by calling
`make-network-process' with an argument list consisting of
keyword/argument pairs, for example `:server t' to create a server
process, or `:type 'datagram' to create a datagram connection.  *Note
Low-Level Network::, for details.  You can also use the
`open-network-stream' function described below.

   To distinguish the different types of processes, the `process-type'
function returns the symbol `network' for a network connection or
server, `serial' for a serial port connection, or `real' for a real
subprocess.

   The `process-status' function returns `open', `closed', `connect',
and `failed' for network connections.  For a network server, the status
is always `listen'.  None of those values is possible for a real
subprocess.  *Note Process Information::.

   You can stop and resume operation of a network process by calling
`stop-process' and `continue-process'.  For a server process, being
stopped means not accepting new connections.  (Up to 5 connection
requests will be queued for when you resume the server; you can
increase this limit, unless it is imposed by the operating system.)
For a network stream connection, being stopped means not processing
input (any arriving input waits until you resume the connection).  For
a datagram connection, some number of packets may be queued but input
may be lost.  You can use the function `process-command' to determine
whether a network connection or server is stopped; a non-`nil' value
means yes.

 -- Function: open-network-stream name buffer-or-name host service
     This function opens a TCP connection, and returns a process object
     that represents the connection.

     The NAME argument specifies the name for the process object.  It
     is modified as necessary to make it unique.

     The BUFFER-OR-NAME argument is the buffer to associate with the
     connection.  Output from the connection is inserted in the buffer,
     unless you specify a filter function to handle the output.  If
     BUFFER-OR-NAME is `nil', it means that the connection is not
     associated with any buffer.

     The arguments HOST and SERVICE specify where to connect to; HOST
     is the host name (a string), and SERVICE is the name of a defined
     network service (a string) or a port number (an integer).


File: elisp,  Node: Network Servers,  Next: Datagrams,  Prev: Network,  Up: Processes

37.15 Network Servers
=====================

You create a server by calling `make-network-process' with `:server t'.
The server will listen for connection requests from clients.  When it
accepts a client connection request, that creates a new network
connection, itself a process object, with the following parameters:

   * The connection's process name is constructed by concatenating the
     server process' NAME with a client identification string.  The
     client identification string for an IPv4 connection looks like
     `<A.B.C.D:P>'.  Otherwise, it is a unique number in brackets, as
     in `<NNN>'.  The number is unique for each connection in the Emacs
     session.

   * If the server's filter is non-`nil', the connection process does
     not get a separate process buffer; otherwise, Emacs creates a new
     buffer for the purpose.  The buffer name is the server's buffer
     name or process name, concatenated with the client identification
     string.

     The server's process buffer value is never used directly by Emacs,
     but it is passed to the log function, which can log connections by
     inserting text there.

   * The communication type and the process filter and sentinel are
     inherited from those of the server.  The server never directly
     uses its filter and sentinel; their sole purpose is to initialize
     connections made to the server.

   * The connection's process contact info is set according to the
     client's addressing information (typically an IP address and a
     port number).  This information is associated with the
     `process-contact' keywords `:host', `:service', `:remote'.

   * The connection's local address is set up according to the port
     number used for the connection.

   * The client process' plist is initialized from the server's plist.


File: elisp,  Node: Datagrams,  Next: Low-Level Network,  Prev: Network Servers,  Up: Processes

37.16 Datagrams
===============

A datagram connection communicates with individual packets rather than
streams of data.  Each call to `process-send' sends one datagram packet
(*note Input to Processes::), and each datagram received results in one
call to the filter function.

   The datagram connection doesn't have to talk with the same remote
peer all the time.  It has a "remote peer address" which specifies
where to send datagrams to.  Each time an incoming datagram is passed
to the filter function, the peer address is set to the address that
datagram came from; that way, if the filter function sends a datagram,
it will go back to that place.  You can specify the remote peer address
when you create the datagram connection using the `:remote' keyword.
You can change it later on by calling `set-process-datagram-address'.

 -- Function: process-datagram-address process
     If PROCESS is a datagram connection or server, this function
     returns its remote peer address.

 -- Function: set-process-datagram-address process address
     If PROCESS is a datagram connection or server, this function sets
     its remote peer address to ADDRESS.


File: elisp,  Node: Low-Level Network,  Next: Misc Network,  Prev: Datagrams,  Up: Processes

37.17 Low-Level Network Access
==============================

You can also create network connections by operating at a lower level
than that of `open-network-stream', using `make-network-process'.

* Menu:

* Proc: Network Processes.   Using `make-network-process'.
* Options: Network Options.  Further control over network connections.
* Features: Network Feature Testing.
                             Determining which network features work on
                               the machine you are using.


File: elisp,  Node: Network Processes,  Next: Network Options,  Up: Low-Level Network

37.17.1 `make-network-process'
------------------------------

The basic function for creating network connections and network servers
is `make-network-process'.  It can do either of those jobs, depending
on the arguments you give it.

 -- Function: make-network-process &rest args
     This function creates a network connection or server and returns
     the process object that represents it.  The arguments ARGS are a
     list of keyword/argument pairs.  Omitting a keyword is always
     equivalent to specifying it with value `nil', except for
     `:coding', `:filter-multibyte', and `:reuseaddr'.  Here are the
     meaningful keywords:

    :name NAME
          Use the string NAME as the process name.  It is modified if
          necessary to make it unique.

    :type TYPE
          Specify the communication type.  A value of `nil' specifies a
          stream connection (the default); `datagram' specifies a
          datagram connection; `seqpacket' specifies a "sequenced
          packet stream" connection.  Both connections and servers can
          be of these types.

    :server SERVER-FLAG
          If SERVER-FLAG is non-`nil', create a server.  Otherwise,
          create a connection.  For a stream type server, SERVER-FLAG
          may be an integer which then specifies the length of the
          queue of pending connections to the server.  The default
          queue length is 5.

    :host HOST
          Specify the host to connect to.  HOST should be a host name or
          Internet address, as a string, or the symbol `local' to
          specify the local host.  If you specify HOST for a server, it
          must specify a valid address for the local host, and only
          clients connecting to that address will be accepted.

    :service SERVICE
          SERVICE specifies a port number to connect to, or, for a
          server, the port number to listen on.  It should be a service
          name that translates to a port number, or an integer
          specifying the port number directly.  For a server, it can
          also be `t', which means to let the system select an unused
          port number.

    :family FAMILY
          FAMILY specifies the address (and protocol) family for
          communication.  `nil' means determine the proper address
          family automatically for the given HOST and SERVICE.  `local'
          specifies a Unix socket, in which case HOST is ignored.
          `ipv4' and `ipv6' specify to use IPv4 and IPv6 respectively.

    :local LOCAL-ADDRESS
          For a server process, LOCAL-ADDRESS is the address to listen
          on.  It overrides FAMILY, HOST and SERVICE, and you may as
          well not specify them.

    :remote REMOTE-ADDRESS
          For a connection, REMOTE-ADDRESS is the address to connect to.
          It overrides FAMILY, HOST and SERVICE, and you may as well
          not specify them.

          For a datagram server, REMOTE-ADDRESS specifies the initial
          setting of the remote datagram address.

          The format of LOCAL-ADDRESS or REMOTE-ADDRESS depends on the
          address family:

             - An IPv4 address is represented as a five-element vector
               of four 8-bit integers and one 16-bit integer `[A B C D
               P]' corresponding to numeric IPv4 address A.B.C.D and
               port number P.

             - An IPv6 address is represented as a nine-element vector
               of 16-bit integers `[A B C D E F G H P]' corresponding
               to numeric IPv6 address A:B:C:D:E:F:G:H and port number
               P.

             - A local address is represented as a string which
               specifies the address in the local address space.

             - An "unsupported family" address is represented by a cons
               `(F . AV)', where F is the family number and AV is a
               vector specifying the socket address using one element
               per address data byte.  Do not rely on this format in
               portable code, as it may depend on implementation
               defined constants, data sizes, and data structure
               alignment.

    :nowait BOOL
          If BOOL is non-`nil' for a stream connection, return without
          waiting for the connection to complete.  When the connection
          succeeds or fails, Emacs will call the sentinel function,
          with a second argument matching `"open"' (if successful) or
          `"failed"'.  The default is to block, so that
          `make-network-process' does not return until the connection
          has succeeded or failed.

    :stop STOPPED
          Start the network connection or server in the `stopped' state
          if STOPPED is non-`nil'.

    :buffer BUFFER
          Use BUFFER as the process buffer.

    :coding CODING
          Use CODING as the coding system for this process.  To specify
          different coding systems for decoding data from the
          connection and for encoding data sent to it, specify
          `(DECODING .  ENCODING)' for CODING.

          If you don't specify this keyword at all, the default is to
          determine the coding systems from the data.

    :noquery QUERY-FLAG
          Initialize the process query flag to QUERY-FLAG.  *Note Query
          Before Exit::.

    :filter FILTER
          Initialize the process filter to FILTER.

    :sentinel SENTINEL
          Initialize the process sentinel to SENTINEL.

    :log LOG
          Initialize the log function of a server process to LOG.  The
          log function is called each time the server accepts a network
          connection from a client.  The arguments passed to the log
          function are SERVER, CONNECTION, and MESSAGE, where SERVER is
          the server process, CONNECTION is the new process for the
          connection, and MESSAGE is a string describing what has
          happened.

    :plist PLIST
          Initialize the process plist to PLIST.

     The original argument list, modified with the actual connection
     information, is available via the `process-contact' function.


File: elisp,  Node: Network Options,  Next: Network Feature Testing,  Prev: Network Processes,  Up: Low-Level Network

37.17.2 Network Options
-----------------------

The following network options can be specified when you create a
network process.  Except for `:reuseaddr', you can also set or modify
these options later, using `set-network-process-option'.

   For a server process, the options specified with
`make-network-process' are not inherited by the client connections, so
you will need to set the necessary options for each child connection as
it is created.

:bindtodevice DEVICE-NAME
     If DEVICE-NAME is a non-empty string identifying a network
     interface name (see `network-interface-list'), only handle packets
     received on that interface.  If DEVICE-NAME is `nil' (the
     default), handle packets received on any interface.

     Using this option may require special privileges on some systems.

:broadcast BROADCAST-FLAG
     If BROADCAST-FLAG is non-`nil' for a datagram process, the process
     will receive datagram packet sent to a broadcast address, and be
     able to send packets to a broadcast address.  Ignored for a stream
     connection.

:dontroute DONTROUTE-FLAG
     If DONTROUTE-FLAG is non-`nil', the process can only send to hosts
     on the same network as the local host.

:keepalive KEEPALIVE-FLAG
     If KEEPALIVE-FLAG is non-`nil' for a stream connection, enable
     exchange of low-level keep-alive messages.

:linger LINGER-ARG
     If LINGER-ARG is non-`nil', wait for successful transmission of
     all queued packets on the connection before it is deleted (see
     `delete-process').  If LINGER-ARG is an integer, it specifies the
     maximum time in seconds to wait for queued packets to be sent
     before closing the connection.  Default is `nil' which means to
     discard unsent queued packets when the process is deleted.

:oobinline OOBINLINE-FLAG
     If OOBINLINE-FLAG is non-`nil' for a stream connection, receive
     out-of-band data in the normal data stream.  Otherwise, ignore
     out-of-band data.

:priority PRIORITY
     Set the priority for packets sent on this connection to the integer
     PRIORITY.  The interpretation of this number is protocol specific,
     such as setting the TOS (type of service) field on IP packets sent
     on this connection.  It may also have system dependent effects,
     such as selecting a specific output queue on the network interface.

:reuseaddr REUSEADDR-FLAG
     If REUSEADDR-FLAG is non-`nil' (the default) for a stream server
     process, allow this server to reuse a specific port number (see
     `:service') unless another process on this host is already
     listening on that port.  If REUSEADDR-FLAG is `nil', there may be
     a period of time after the last use of that port (by any process
     on the host), where it is not possible to make a new server on
     that port.

 -- Function: set-network-process-option process option value &optional
          no-error
     This function sets or modifies a network option for network process
     PROCESS.  See `make-network-process' for details of options OPTION
     and their corresponding values VALUE.  If NO-ERROR is non-`nil',
     this function returns `nil' instead of signaling an error if
     OPTION is not a supported option.  If the function successfully
     completes, it returns `t'.

     The current setting of an option is available via the
     `process-contact' function.


File: elisp,  Node: Network Feature Testing,  Prev: Network Options,  Up: Low-Level Network

37.17.3 Testing Availability of Network Features
------------------------------------------------

To test for the availability of a given network feature, use `featurep'
like this:

     (featurep 'make-network-process '(KEYWORD VALUE))

The result of the first form is `t' if it works to specify KEYWORD with
value VALUE in `make-network-process'.  The result of the second form
is `t' if KEYWORD is supported by `make-network-process'.  Here are
some of the KEYWORD--VALUE pairs you can test in this way.

`(:nowait t)'
     Non-`nil' if non-blocking connect is supported.

`(:type datagram)'
     Non-`nil' if datagrams are supported.

`(:family local)'
     Non-`nil' if local (a.k.a. "UNIX domain") sockets are supported.

`(:family ipv6)'
     Non-`nil' if IPv6 is supported.

`(:service t)'
     Non-`nil' if the system can select the port for a server.

   To test for the availability of a given network option, use
`featurep' like this:

     (featurep 'make-network-process 'KEYWORD)

Here are some of the options you can test in this way.

`:bindtodevice'
`:broadcast'
`:dontroute'
`:keepalive'
`:linger'
`:oobinline'
`:priority'
`:reuseaddr'
     That particular network option is supported by
     `make-network-process' and `set-network-process-option'.


File: elisp,  Node: Misc Network,  Next: Serial Ports,  Prev: Low-Level Network,  Up: Processes

37.18 Misc Network Facilities
=============================

These additional functions are useful for creating and operating on
network connections.  Note that they are supported only on some systems.

 -- Function: network-interface-list
     This function returns a list describing the network interfaces of
     the machine you are using.  The value is an alist whose elements
     have the form `(NAME . ADDRESS)'.  ADDRESS has the same form as
     the LOCAL-ADDRESS and REMOTE-ADDRESS arguments to
     `make-network-process'.

 -- Function: network-interface-info ifname
     This function returns information about the network interface named
     IFNAME.  The value is a list of the form `(ADDR BCAST NETMASK
     HWADDR FLAGS)'.

    ADDR
          The Internet protocol address.

    BCAST
          The broadcast address.

    NETMASK
          The network mask.

    HWADDR
          The layer 2 address (Ethernet MAC address, for instance).

    FLAGS
          The current flags of the interface.

 -- Function: format-network-address address &optional omit-port
     This function converts the Lisp representation of a network
     address to a string.

     A five-element vector `[A B C D P]' represents an IPv4 address
     A.B.C.D and port number P.  `format-network-address' converts that
     to the string `"A.B.C.D:P"'.

     A nine-element vector `[A B C D E F G H P]' represents an IPv6
     address along with a port number.  `format-network-address'
     converts that to the string `"[A:B:C:D:E:F:G:H]:P"'.

     If the vector does not include the port number, P, or if OMIT-PORT
     is non-`nil', the result does not include the `:P' suffix.


File: elisp,  Node: Serial Ports,  Next: Byte Packing,  Prev: Misc Network,  Up: Processes

37.19 Communicating with Serial Ports
=====================================

Emacs can communicate with serial ports.  For interactive use, `M-x
serial-term' opens a terminal window.  In a Lisp program,
`make-serial-process' creates a process object.

   The serial port can be configured at run-time, without having to
close and re-open it.  The function `serial-process-configure' lets you
change the speed, bytesize, and other parameters.  In a terminal window
created by `serial-term', you can click on the mode line for
configuration.

   A serial connection is represented by a process object which can be
used similar to a subprocess or network process.  You can send and
receive data and configure the serial port.  A serial process object
has no process ID, you can't send signals to it, and the status codes
are different from other types of processes.  `delete-process' on the
process object or `kill-buffer' on the process buffer close the
connection, but this does not affect the device connected to the serial
port.

   The function `process-type' returns the symbol `serial' for a
process object representing a serial port connection.

   Serial ports are available on GNU/Linux, Unix, and Windows systems.

 -- Command: serial-term port speed
     Start a terminal-emulator for a serial port in a new buffer.  PORT
     is the name of the serial port to which to connect.  For example,
     this could be `/dev/ttyS0' on Unix.  On Windows, this could be
     `COM1', or `\\.\COM10' (double the backslashes in Lisp strings).

     SPEED is the speed of the serial port in bits per second.  9600 is
     a common value.  The buffer is in Term mode; see *note Term Mode:
     (emacs)Term Mode, for the commands to use in that buffer.  You can
     change the speed and the configuration in the mode line menu.

 -- Function: make-serial-process &rest args
     This function creates a process and a buffer.  Arguments are
     specified as keyword/argument pairs.  Here's the list of the
     meaningful keywords:

    `:port PORT (mandatory)'
          This is the name of the serial port.  On Unix and GNU
          systems, this is a file name such as `/dev/ttyS0'.  On
          Windows, this could be `COM1', or `\\.\COM10' for ports
          higher than `COM9' (double the backslashes in Lisp strings).

    `:speed SPEED (mandatory)'
          The speed of the serial port in bits per second.  This
          function calls `serial-process-configure' to handle the speed.

    `:name NAME'
          The name of the process.  If NAME is not given, PORT will
          serve as the process name as well.

    `:buffer BUFFER'
          The buffer to associate with the process.  The value could be
          either a buffer or a string that names a buffer.  Process
          output goes at the end of that buffer, unless you specify an
          output stream or filter function to handle the output.  If
          BUFFER is not given, the process buffer's name is taken from
          the value of the `:name' keyword.

    `:coding CODING'
          If CODING is a symbol, it specifies the coding system used for
          both reading and writing for this process.  If CODING is a
          cons `(decoding . encoding)', DECODING is used for reading,
          and ENCODING is used for writing.  If not specified, the
          default is to determine the coding systems from data itself.

    `:noquery QUERY-FLAG'
          Initialize the process query flag to QUERY-FLAG.  *Note Query
          Before Exit::.  The flags defaults to `nil' if unspecified.

    `:stop BOOL'
          Start process in the `stopped' state if BOOL is non-`nil'.
          In the stopped state, a serial process does not accept
          incoming data, but you can send outgoing data.  The stopped
          state is cleared by `continue-process' and set by
          `stop-process'.

    `:filter FILTER'
          Install FILTER as the process filter.

    `:sentinel SENTINEL'
          Install SENTINEL as the process sentinel.

    `:plist PLIST'
          Install PLIST as the initial plist of the process.

    `:speed'
    `:bytesize'
    `:parity'
    `:stopbits'
    `:flowcontrol'
          These are handled by `serial-process-configure', which is
          called by `make-serial-process'.

     The original argument list, possibly modified by later
     configuration, is available via the function `process-contact'.

     Here is an example:

          (make-serial-process :port "/dev/ttyS0" :speed 9600)

 -- Function: serial-process-configure &rest args
     This functions configures a serial port connection.  Arguments are
     specified as keyword/argument pairs.  Attributes that are not given
     are re-initialized from the process's current configuration
     (available via the function `process-contact') or set to
     reasonable default values.  The following arguments are defined:

    `:process PROCESS'
    `:name NAME'
    `:buffer BUFFER'
    `:port PORT'
          Any of these arguments can be given to identify the process
          that is to be configured.  If none of these arguments is
          given, the current buffer's process is used.

    `:speed SPEED'
          The speed of the serial port in bits per second, a.k.a. "baud
          rate".  The value can be any number, but most serial ports
          work only at a few defined values between 1200 and 115200,
          with 9600 being the most common value.  If SPEED is `nil',
          the function ignores all other arguments and does not
          configure the port.  This may be useful for special serial
          ports such as Bluetooth-to-serial converters which can only
          be configured through AT commands sent through the
          connection.  The value of `nil' for SPEED is valid only for
          connections that were already opened by a previous call to
          `make-serial-process' or `serial-term'.

    `:bytesize BYTESIZE'
          The number of bits per byte, which can be 7 or 8.  If BYTESIZE
          is not given or `nil', it defaults to 8.

    `:parity PARITY'
          The value can be `nil' (don't use parity), the symbol `odd'
          (use odd parity), or the symbol `even' (use even parity).  If
          PARITY is not given, it defaults to no parity.

    `:stopbits STOPBITS'
          The number of stopbits used to terminate a transmission of
          each byte.  STOPBITS can be 1 or 2.  If STOPBITS is not given
          or `nil', it defaults to 1.

    `:flowcontrol FLOWCONTROL'
          The type of flow control to use for this connection, which is
          either `nil' (don't use flow control), the symbol `hw' (use
          RTS/CTS hardware flow control), or the symbol `sw' (use
          XON/XOFF software flow control).  If FLOWCONTROL is not
          given, it defaults to no flow control.

     `serial-process-configure' is called by `make-serial-process' for
     the initial configuration of the serial port.


File: elisp,  Node: Byte Packing,  Prev: Serial Ports,  Up: Processes

37.20 Packing and Unpacking Byte Arrays
=======================================

This section describes how to pack and unpack arrays of bytes, usually
for binary network protocols.  These functions convert byte arrays to
alists, and vice versa.  The byte array can be represented as a unibyte
string or as a vector of integers, while the alist associates symbols
either with fixed-size objects or with recursive sub-alists.

   Conversion from byte arrays to nested alists is also known as
"deserializing" or "unpacking", while going in the opposite direction
is also known as "serializing" or "packing".

* Menu:

* Bindat Spec::         Describing data layout.
* Bindat Functions::    Doing the unpacking and packing.
* Bindat Examples::     Samples of what bindat.el can do for you!


File: elisp,  Node: Bindat Spec,  Next: Bindat Functions,  Up: Byte Packing

37.20.1 Describing Data Layout
------------------------------

To control unpacking and packing, you write a "data layout
specification", a special nested list describing named and typed
"fields".  This specification controls length of each field to be
processed, and how to pack or unpack it.  We normally keep bindat specs
in variables whose names end in `-bindat-spec'; that kind of name is
automatically recognized as "risky."

   A field's "type" describes the size (in bytes) of the object that
the field represents and, in the case of multibyte fields, how the
bytes are ordered within the field.  The two possible orderings are
"big endian" (also known as "network byte ordering") and "little
endian."  For instance, the number `#x23cd' (decimal 9165) in big
endian would be the two bytes `#x23' `#xcd'; and in little endian,
`#xcd' `#x23'.  Here are the possible type values:

`u8'
`byte'
     Unsigned byte, with length 1.

`u16'
`word'
`short'
     Unsigned integer in network byte order, with length 2.

`u24'
     Unsigned integer in network byte order, with length 3.

`u32'
`dword'
`long'
     Unsigned integer in network byte order, with length 4.  Note:
     These values may be limited by Emacs' integer implementation
     limits.

`u16r'
`u24r'
`u32r'
     Unsigned integer in little endian order, with length 2, 3 and 4,
     respectively.

`str LEN'
     String of length LEN.

`strz LEN'
     Zero-terminated string, in a fixed-size field with length LEN.

`vec LEN [TYPE]'
     Vector of LEN elements of type TYPE, or bytes if not TYPE is
     specified.  The TYPE is any of the simple types above, or another
     vector specified as a list `(vec LEN [TYPE])'.

`ip'
     Four-byte vector representing an Internet address.  For example:
     `[127 0 0 1]' for localhost.

`bits LEN'
     List of set bits in LEN bytes.  The bytes are taken in big endian
     order and the bits are numbered starting with `8 * LEN - 1' and
     ending with zero.  For example: `bits 2' unpacks `#x28' `#x1c' to
     `(2 3 4 11 13)' and `#x1c' `#x28' to `(3 5 10 11 12)'.

`(eval FORM)'
     FORM is a Lisp expression evaluated at the moment the field is
     unpacked or packed.  The result of the evaluation should be one of
     the above-listed type specifications.

   For a fixed-size field, the length LEN is given as an integer
specifying the number of bytes in the field.

   When the length of a field is not fixed, it typically depends on the
value of a preceding field.  In this case, the length LEN can be given
either as a list `(NAME ...)' identifying a "field name" in the format
specified for `bindat-get-field' below, or by an expression `(eval
FORM)' where FORM should evaluate to an integer, specifying the field
length.

   A field specification generally has the form `([NAME] HANDLER)'.
The square braces indicate that NAME is optional.  (Don't use names
that are symbols meaningful as type specifications (above) or handler
specifications (below), since that would be ambiguous.)  NAME can be a
symbol or the expression `(eval FORM)', in which case FORM should
evaluate to a symbol.

   HANDLER describes how to unpack or pack the field and can be one of
the following:

`TYPE'
     Unpack/pack this field according to the type specification TYPE.

`eval FORM'
     Evaluate FORM, a Lisp expression, for side-effect only.  If the
     field name is specified, the value is bound to that field name.

`fill LEN'
     Skip LEN bytes.  In packing, this leaves them unchanged, which
     normally means they remain zero.  In unpacking, this means they
     are ignored.

`align LEN'
     Skip to the next multiple of LEN bytes.

`struct SPEC-NAME'
     Process SPEC-NAME as a sub-specification.  This describes a
     structure nested within another structure.

`union FORM (TAG SPEC)...'
     Evaluate FORM, a Lisp expression, find the first TAG that matches
     it, and process its associated data layout specification SPEC.
     Matching can occur in one of three ways:

        * If a TAG has the form `(eval EXPR)', evaluate EXPR with the
          variable `tag' dynamically bound to the value of FORM.  A
          non-`nil' result indicates a match.

        * TAG matches if it is `equal' to the value of FORM.

        * TAG matches unconditionally if it is `t'.

`repeat COUNT FIELD-SPECS...'
     Process the FIELD-SPECS recursively, in order, then repeat
     starting from the first one, processing all the specs COUNT times
     overall.  The COUNT is given using the same formats as a field
     length--if an `eval' form is used, it is evaluated just once.  For
     correct operation, each spec in FIELD-SPECS must include a name.

   For the `(eval FORM)' forms used in a bindat specification, the FORM
can access and update these dynamically bound variables during
evaluation:

`last'
     Value of the last field processed.

`bindat-raw'
     The data as a byte array.

`bindat-idx'
     Current index (within `bindat-raw') for unpacking or packing.

`struct'
     The alist containing the structured data that have been unpacked so
     far, or the entire structure being packed.  You can use
     `bindat-get-field' to access specific fields of this structure.

`count'
`index'
     Inside a `repeat' block, these contain the maximum number of
     repetitions (as specified by the COUNT parameter), and the current
     repetition number (counting from 0).  Setting `count' to zero will
     terminate the inner-most repeat block after the current repetition
     has completed.


File: elisp,  Node: Bindat Functions,  Next: Bindat Examples,  Prev: Bindat Spec,  Up: Byte Packing

37.20.2 Functions to Unpack and Pack Bytes
------------------------------------------

In the following documentation, SPEC refers to a data layout
specification, `bindat-raw' to a byte array, and STRUCT to an alist
representing unpacked field data.

 -- Function: bindat-unpack spec bindat-raw &optional bindat-idx
     This function unpacks data from the unibyte string or byte array
     `bindat-raw' according to SPEC.  Normally this starts unpacking at
     the beginning of the byte array, but if BINDAT-IDX is non-`nil', it
     specifies a zero-based starting position to use instead.

     The value is an alist or nested alist in which each element
     describes one unpacked field.

 -- Function: bindat-get-field struct &rest name
     This function selects a field's data from the nested alist STRUCT.
     Usually STRUCT was returned by `bindat-unpack'.  If NAME
     corresponds to just one argument, that means to extract a
     top-level field value.  Multiple NAME arguments specify repeated
     lookup of sub-structures.  An integer name acts as an array index.

     For example, if NAME is `(a b 2 c)', that means to find field `c'
     in the third element of subfield `b' of field `a'.  (This
     corresponds to `struct.a.b[2].c' in C.)

   Although packing and unpacking operations change the organization of
data (in memory), they preserve the data's "total length", which is the
sum of all the fields' lengths, in bytes.  This value is not generally
inherent in either the specification or alist alone; instead, both
pieces of information contribute to its calculation.  Likewise, the
length of a string or array being unpacked may be longer than the data's
total length as described by the specification.

 -- Function: bindat-length spec struct
     This function returns the total length of the data in STRUCT,
     according to SPEC.

 -- Function: bindat-pack spec struct &optional bindat-raw bindat-idx
     This function returns a byte array packed according to SPEC from
     the data in the alist STRUCT.  Normally it creates and fills a new
     byte array starting at the beginning.  However, if BINDAT-RAW is
     non-`nil', it specifies a pre-allocated unibyte string or vector to
     pack into.  If BINDAT-IDX is non-`nil', it specifies the starting
     offset for packing into `bindat-raw'.

     When pre-allocating, you should make sure `(length BINDAT-RAW)'
     meets or exceeds the total length to avoid an out-of-range error.

 -- Function: bindat-ip-to-string ip
     Convert the Internet address vector IP to a string in the usual
     dotted notation.

          (bindat-ip-to-string [127 0 0 1])
               => "127.0.0.1"


File: elisp,  Node: Bindat Examples,  Prev: Bindat Functions,  Up: Byte Packing

37.20.3 Examples of Byte Unpacking and Packing
----------------------------------------------

Here is a complete example of byte unpacking and packing:

     (defvar fcookie-index-spec
       '((:version  u32)
         (:count    u32)
         (:longest  u32)
         (:shortest u32)
         (:flags    u32)
         (:delim    u8)
         (:ignored  fill 3)
         (:offset   repeat (:count)
                    (:foo u32)))
       "Description of a fortune cookie index file's contents.")

     (defun fcookie (cookies &optional index)
       "Display a random fortune cookie from file COOKIES.
     Optional second arg INDEX specifies the associated index
     filename, which is by default constructed by appending
     \".dat\" to COOKIES.  Display cookie text in possibly
     new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME
     is COOKIES without the directory part."
       (interactive "fCookies file: ")
       (let* ((info (with-temp-buffer
                      (insert-file-contents-literally
                       (or index (concat cookies ".dat")))
                      (bindat-unpack fcookie-index-spec
                                     (buffer-string))))
              (sel (random (bindat-get-field info :count)))
              (beg (cdar (bindat-get-field info :offset sel)))
              (end (or (cdar (bindat-get-field info
                                               :offset (1+ sel)))
                       (nth 7 (file-attributes cookies)))))
         (switch-to-buffer
          (get-buffer-create
           (format "*Fortune Cookie: %s*"
                   (file-name-nondirectory cookies))))
         (erase-buffer)
         (insert-file-contents-literally
          cookies nil beg (- end 3))))

     (defun fcookie-create-index (cookies &optional index delim)
       "Scan file COOKIES, and write out its index file.
     Optional second arg INDEX specifies the index filename,
     which is by default constructed by appending \".dat\" to
     COOKIES.  Optional third arg DELIM specifies the unibyte
     character which, when found on a line of its own in
     COOKIES, indicates the border between entries."
       (interactive "fCookies file: ")
       (setq delim (or delim ?%))
       (let ((delim-line (format "\n%c\n" delim))
             (count 0)
             (max 0)
             min p q len offsets)
         (unless (= 3 (string-bytes delim-line))
           (error "Delimiter cannot be represented in one byte"))
         (with-temp-buffer
           (insert-file-contents-literally cookies)
           (while (and (setq p (point))
                       (search-forward delim-line (point-max) t)
                       (setq len (- (point) 3 p)))
             (setq count (1+ count)
                   max (max max len)
                   min (min (or min max) len)
                   offsets (cons (1- p) offsets))))
         (with-temp-buffer
           (set-buffer-multibyte nil)
           (insert
            (bindat-pack
             fcookie-index-spec
             `((:version . 2)
               (:count . ,count)
               (:longest . ,max)
               (:shortest . ,min)
               (:flags . 0)
               (:delim . ,delim)
               (:offset . ,(mapcar (lambda (o)
                                     (list (cons :foo o)))
                                   (nreverse offsets))))))
           (let ((coding-system-for-write 'raw-text-unix))
             (write-file (or index (concat cookies ".dat")))))))

   Following is an example of defining and unpacking a complex
structure.  Consider the following C structures:

     struct header {
         unsigned long    dest_ip;
         unsigned long    src_ip;
         unsigned short   dest_port;
         unsigned short   src_port;
     };

     struct data {
         unsigned char    type;
         unsigned char    opcode;
         unsigned short   length;  /* In network byte order */
         unsigned char    id[8];   /* null-terminated string  */
         unsigned char    data[/* (length + 3) & ~3 */];
     };

     struct packet {
         struct header    header;
         unsigned long    counters[2];  /* In little endian order */
         unsigned char    items;
         unsigned char    filler[3];
         struct data      item[/* items */];

     };

   The corresponding data layout specification:

     (setq header-spec
           '((dest-ip   ip)
             (src-ip    ip)
             (dest-port u16)
             (src-port  u16)))

     (setq data-spec
           '((type      u8)
             (opcode    u8)
             (length    u16)  ;; network byte order
             (id        strz 8)
             (data      vec (length))
             (align     4)))

     (setq packet-spec
           '((header    struct header-spec)
             (counters  vec 2 u32r)   ;; little endian order
             (items     u8)
             (fill      3)
             (item      repeat (items)
                        (struct data-spec))))

   A binary data representation:

     (setq binary-data
           [ 192 168 1 100 192 168 1 101 01 28 21 32
             160 134 1 0 5 1 0 0 2 0 0 0
             2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0
             1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])

   The corresponding decoded structure:

     (setq decoded (bindat-unpack packet-spec binary-data))
          =>
     ((header
       (dest-ip   . [192 168 1 100])
       (src-ip    . [192 168 1 101])
       (dest-port . 284)
       (src-port  . 5408))
      (counters . [100000 261])
      (items . 2)
      (item ((data . [1 2 3 4 5])
             (id . "ABCDEF")
             (length . 5)
             (opcode . 3)
             (type . 2))
            ((data . [6 7 8 9 10 11 12])
             (id . "BCDEFG")
             (length . 7)
             (opcode . 4)
             (type . 1))))

   Fetching data from this structure:

     (bindat-get-field decoded 'item 1 'id)
          => "BCDEFG"


File: elisp,  Node: Display,  Next: System Interface,  Prev: Processes,  Up: Top

38 Emacs Display
****************

This chapter describes a number of features related to the display that
Emacs presents to the user.

* Menu:

* Refresh Screen::      Clearing the screen and redrawing everything on it.
* Forcing Redisplay::   Forcing redisplay.
* Truncation::          Folding or wrapping long text lines.
* The Echo Area::       Displaying messages at the bottom of the screen.
* Warnings::            Displaying warning messages for the user.
* Invisible Text::      Hiding part of the buffer text.
* Selective Display::   Hiding part of the buffer text (the old way).
* Temporary Displays::  Displays that go away automatically.
* Overlays::            Use overlays to highlight parts of the buffer.
* Width::               How wide a character or string is on the screen.
* Line Height::         Controlling the height of lines.
* Faces::               A face defines a graphics style for text characters:
                          font, colors, etc.
* Fringes::             Controlling window fringes.
* Scroll Bars::         Controlling vertical scroll bars.
* Display Property::    Enabling special display features.
* Images::              Displaying images in Emacs buffers.
* Buttons::             Adding clickable buttons to Emacs buffers.
* Abstract Display::    Emacs' Widget for Object Collections.
* Blinking::            How Emacs shows the matching open parenthesis.
* Usual Display::       The usual conventions for displaying nonprinting chars.
* Display Tables::      How to specify other conventions.
* Beeping::             Audible signal to the user.
* Window Systems::      Which window system is being used.


File: elisp,  Node: Refresh Screen,  Next: Forcing Redisplay,  Up: Display

38.1 Refreshing the Screen
==========================

The function `redraw-frame' clears and redisplays the entire contents
of a given frame (*note Frames::).  This is useful if the screen is
corrupted.

 -- Function: redraw-frame frame
     This function clears and redisplays frame FRAME.

   Even more powerful is `redraw-display':

 -- Command: redraw-display
     This function clears and redisplays all visible frames.

   In Emacs, processing user input takes priority over redisplay.  If
you call these functions when input is available, they don't redisplay
immediately, but the requested redisplay does happen eventually--after
all the input has been processed.

   On text-only terminals, suspending and resuming Emacs normally also
refreshes the screen.  Some terminal emulators record separate contents
for display-oriented programs such as Emacs and for ordinary sequential
display.  If you are using such a terminal, you might want to inhibit
the redisplay on resumption.

 -- User Option: no-redraw-on-reenter
     This variable controls whether Emacs redraws the entire screen
     after it has been suspended and resumed.  Non-`nil' means there is
     no need to redraw, `nil' means redrawing is needed.  The default
     is `nil'.


File: elisp,  Node: Forcing Redisplay,  Next: Truncation,  Prev: Refresh Screen,  Up: Display

38.2 Forcing Redisplay
======================

Emacs normally tries to redisplay the screen whenever it waits for
input.  With the following function, you can request an immediate
attempt to redisplay, in the middle of Lisp code, without actually
waiting for input.

 -- Function: redisplay &optional force
     This function tries immediately to redisplay, provided there are no
     pending input events.

     If the optional argument FORCE is non-`nil', it does all pending
     redisplay work even if input is available, with no pre-emption.

     The function returns `t' if it actually tried to redisplay, and
     `nil' otherwise.  A value of `t' does not mean that redisplay
     proceeded to completion; it could have been pre-empted by newly
     arriving terminal input.

   `redisplay' with no argument tries immediately to redisplay, but has
no effect on the usual rules for what parts of the screen to redisplay.
By contrast, the following function adds certain windows to the pending
redisplay work (as if their contents had completely changed), but
doesn't immediately try to do any redisplay work.

 -- Function: force-window-update &optional object
     This function forces some or all windows to be updated on next
     redisplay.  If OBJECT is a window, it requires eventual redisplay
     of that window.  If OBJECT is a buffer or buffer name, it requires
     eventual redisplay of all windows displaying that buffer.  If
     OBJECT is `nil' (or omitted), it requires eventual redisplay of
     all windows.

   `force-window-update' does not do a redisplay immediately.  (Emacs
will do that when it waits for input.)  Rather, its effect is to put
more work on the queue to be done by redisplay whenever there is a
chance.

   Emacs redisplay normally stops if input arrives, and does not happen
at all if input is available before it starts.  Most of the time, this
is exactly what you want.  However, you can prevent preemption by
binding `redisplay-dont-pause' to a non-`nil' value.

 -- Variable: redisplay-dont-pause
     If this variable is non-`nil', pending input does not prevent or
     halt redisplay; redisplay occurs, and finishes, regardless of
     whether input is available.

 -- Variable: redisplay-preemption-period
     This variable specifies how many seconds Emacs waits between checks
     for new input during redisplay.  (The default is 0.1 seconds.)  If
     input has arrived when Emacs checks, it pre-empts redisplay and
     processes the available input before trying again to redisplay.

     If this variable is `nil', Emacs does not check for input during
     redisplay, and redisplay cannot be preempted by input.

     This variable is only obeyed on graphical terminals.  For text
     terminals, see *note Terminal Output::.


File: elisp,  Node: Truncation,  Next: The Echo Area,  Prev: Forcing Redisplay,  Up: Display

38.3 Truncation
===============

When a line of text extends beyond the right edge of a window, Emacs
can "continue" the line (make it "wrap" to the next screen line), or
"truncate" the line (limit it to one screen line).  The additional
screen lines used to display a long text line are called "continuation"
lines.  Continuation is not the same as filling; continuation happens
on the screen only, not in the buffer contents, and it breaks a line
precisely at the right margin, not at a word boundary.  *Note Filling::.

   On a graphical display, tiny arrow images in the window fringes
indicate truncated and continued lines (*note Fringes::).  On a text
terminal, a `$' in the rightmost column of the window indicates
truncation; a `\' on the rightmost column indicates a line that
"wraps."  (The display table can specify alternate characters to use
for this; *note Display Tables::).

 -- User Option: truncate-lines
     If this buffer-local variable is non-`nil', lines that extend
     beyond the right edge of the window are truncated; otherwise, they
     are continued.  As a special exception, the variable
     `truncate-partial-width-windows' takes precedence in
     "partial-width" windows (i.e., windows that do not occupy the
     entire frame width).

 -- User Option: truncate-partial-width-windows
     This variable controls line truncation in "partial-width" windows.
     A partial-width window is one that does not occupy the entire frame
     width (*note Splitting Windows::).  If the value is `nil', line
     truncation is determined by the variable `truncate-lines' (see
     above).  If the value is an integer N, lines are truncated if the
     partial-width window has fewer than N columns, regardless of the
     value of `truncate-lines'; if the partial-width window has N or
     more columns, line truncation is determined by `truncate-lines'.
     For any other non-`nil' value, lines are truncated in every
     partial-width window, regardless of the value of `truncate-lines'.

   When horizontal scrolling (*note Horizontal Scrolling::) is in use in
a window, that forces truncation.

 -- Variable: wrap-prefix
     If this buffer-local variable is non-`nil', it defines a "prefix"
     that is prepended to every continuation line at display-time.  (If
     lines are truncated, the wrap-prefix is never used.)  It may be a
     string, an image, or a stretch-glyph; the value is interpreted in
     the same way as a `display' text property.  *Note Display
     Property::.

     A wrap-prefix may also be specified for regions of text, using the
     `wrap-prefix' text or overlay property.  This takes precedence
     over the `wrap-prefix' variable.  *Note Special Properties::.

 -- Variable: line-prefix
     If this buffer-local variable is non-`nil', it defines a "prefix"
     that is prepended to every non-continuation line at display-time.
     It may be a string, an image, or a stretch-glyph; the value is
     interpreted in the same way as a `display' text property.  *Note
     Display Property::.

     A line-prefix may also be specified for regions of text using the
     `line-prefix' text or overlay property.  This takes precedence
     over the `line-prefix' variable.  *Note Special Properties::.

   If your buffer contains _very_ long lines, and you use continuation
to display them, computing the continuation lines can make Emacs
redisplay slow.  The column computation and indentation functions also
become slow.  Then you might find it advisable to set
`cache-long-line-scans' to `t'.

 -- Variable: cache-long-line-scans
     If this variable is non-`nil', various indentation and motion
     functions, and Emacs redisplay, cache the results of scanning the
     buffer, and consult the cache to avoid rescanning regions of the
     buffer unless they are modified.

     Turning on the cache slows down processing of short lines somewhat.

     This variable is automatically buffer-local in every buffer.


File: elisp,  Node: The Echo Area,  Next: Warnings,  Prev: Truncation,  Up: Display

38.4 The Echo Area
==================

The "echo area" is used for displaying error messages (*note Errors::),
for messages made with the `message' primitive, and for echoing
keystrokes.  It is not the same as the minibuffer, despite the fact
that the minibuffer appears (when active) in the same place on the
screen as the echo area.  The `GNU Emacs Manual' specifies the rules
for resolving conflicts between the echo area and the minibuffer for
use of that screen space (*note The Minibuffer: (emacs)Minibuffer.).

   You can write output in the echo area by using the Lisp printing
functions with `t' as the stream (*note Output Functions::), or
explicitly.

* Menu:

* Displaying Messages:: Explicitly displaying text in the echo area.
* Progress::            Informing user about progress of a long operation.
* Logging Messages::    Echo area messages are logged for the user.
* Echo Area Customization:: Controlling the echo area.


File: elisp,  Node: Displaying Messages,  Next: Progress,  Up: The Echo Area

38.4.1 Displaying Messages in the Echo Area
-------------------------------------------

This section describes the functions for explicitly producing echo area
messages.  Many other Emacs features display messages there, too.

 -- Function: message format-string &rest arguments
     This function displays a message in the echo area.  The argument
     FORMAT-STRING is similar to a C language `printf' format string.
     See `format' in *note Formatting Strings::, for the details on the
     conversion specifications.  `message' returns the constructed
     string.

     In batch mode, `message' prints the message text on the standard
     error stream, followed by a newline.

     If FORMAT-STRING, or strings among the ARGUMENTS, have `face' text
     properties, these affect the way the message is displayed.

     If FORMAT-STRING is `nil' or the empty string, `message' clears
     the echo area; if the echo area has been expanded automatically,
     this brings it back to its normal size.  If the minibuffer is
     active, this brings the minibuffer contents back onto the screen
     immediately.

          (message "Minibuffer depth is %d."
                   (minibuffer-depth))
           -| Minibuffer depth is 0.
          => "Minibuffer depth is 0."

          ---------- Echo Area ----------
          Minibuffer depth is 0.
          ---------- Echo Area ----------

     To automatically display a message in the echo area or in a
     pop-buffer, depending on its size, use `display-message-or-buffer'
     (see below).

 -- Macro: with-temp-message message &rest body
     This construct displays a message in the echo area temporarily,
     during the execution of BODY.  It displays MESSAGE, executes BODY,
     then returns the value of the last body form while restoring the
     previous echo area contents.

 -- Function: message-or-box format-string &rest arguments
     This function displays a message like `message', but may display it
     in a dialog box instead of the echo area.  If this function is
     called in a command that was invoked using the mouse--more
     precisely, if `last-nonmenu-event' (*note Command Loop Info::) is
     either `nil' or a list--then it uses a dialog box or pop-up menu to
     display the message.  Otherwise, it uses the echo area.  (This is
     the same criterion that `y-or-n-p' uses to make a similar
     decision; see *note Yes-or-No Queries::.)

     You can force use of the mouse or of the echo area by binding
     `last-nonmenu-event' to a suitable value around the call.

 -- Function: message-box format-string &rest arguments
     This function displays a message like `message', but uses a dialog
     box (or a pop-up menu) whenever that is possible.  If it is
     impossible to use a dialog box or pop-up menu, because the
     terminal does not support them, then `message-box' uses the echo
     area, like `message'.

 -- Function: display-message-or-buffer message &optional buffer-name
          not-this-window frame
     This function displays the message MESSAGE, which may be either a
     string or a buffer.  If it is shorter than the maximum height of
     the echo area, as defined by `max-mini-window-height', it is
     displayed in the echo area, using `message'.  Otherwise,
     `display-buffer' is used to show it in a pop-up buffer.

     Returns either the string shown in the echo area, or when a pop-up
     buffer is used, the window used to display it.

     If MESSAGE is a string, then the optional argument BUFFER-NAME is
     the name of the buffer used to display it when a pop-up buffer is
     used, defaulting to `*Message*'.  In the case where MESSAGE is a
     string and displayed in the echo area, it is not specified whether
     the contents are inserted into the buffer anyway.

     The optional arguments NOT-THIS-WINDOW and FRAME are as for
     `display-buffer', and only used if a buffer is displayed.

 -- Function: current-message
     This function returns the message currently being displayed in the
     echo area, or `nil' if there is none.


File: elisp,  Node: Progress,  Next: Logging Messages,  Prev: Displaying Messages,  Up: The Echo Area

38.4.2 Reporting Operation Progress
-----------------------------------

When an operation can take a while to finish, you should inform the
user about the progress it makes.  This way the user can estimate
remaining time and clearly see that Emacs is busy working, not hung.

   Functions listed in this section provide simple and efficient way of
reporting operation progress.  Here is a working example that does
nothing useful:

     (let ((progress-reporter
            (make-progress-reporter "Collecting mana for Emacs..."
                                    0  500)))
       (dotimes (k 500)
         (sit-for 0.01)
         (progress-reporter-update progress-reporter k))
       (progress-reporter-done progress-reporter))

 -- Function: make-progress-reporter message min-value max-value
          &optional current-value min-change min-time
     This function creates and returns a "progress reporter"--an object
     you will use as an argument for all other functions listed here.
     The idea is to precompute as much data as possible to make
     progress reporting very fast.

     When this progress reporter is subsequently used, it will display
     MESSAGE in the echo area, followed by progress percentage.
     MESSAGE is treated as a simple string.  If you need it to depend
     on a filename, for instance, use `format' before calling this
     function.

     MIN-VALUE and MAX-VALUE arguments stand for starting and final
     states of your operation.  For instance, if you scan a buffer,
     they should be the results of `point-min' and `point-max'
     correspondingly.  It is required that MAX-VALUE is greater than
     MIN-VALUE.  If you create progress reporter when some part of the
     operation has already been completed, then specify CURRENT-VALUE
     argument.  But normally you should omit it or set it to `nil'--it
     will default to MIN-VALUE then.

     Remaining arguments control the rate of echo area updates.
     Progress reporter will wait for at least MIN-CHANGE more percents
     of the operation to be completed before printing next message.
     MIN-TIME specifies the minimum time in seconds to pass between
     successive prints.  It can be fractional.  Depending on Emacs and
     system capabilities, progress reporter may or may not respect this
     last argument or do it with varying precision.  Default value for
     MIN-CHANGE is 1 (one percent), for MIN-TIME--0.2 (seconds.)

     This function calls `progress-reporter-update', so the first
     message is printed immediately.

 -- Function: progress-reporter-update reporter value
     This function does the main work of reporting progress of your
     operation.  It displays the message of REPORTER, followed by
     progress percentage determined by VALUE.  If percentage is zero,
     or close enough according to the MIN-CHANGE and MIN-TIME
     arguments, then it is omitted from the output.

     REPORTER must be the result of a call to `make-progress-reporter'.
     VALUE specifies the current state of your operation and must be
     between MIN-VALUE and MAX-VALUE (inclusive) as passed to
     `make-progress-reporter'.  For instance, if you scan a buffer,
     then VALUE should be the result of a call to `point'.

     This function respects MIN-CHANGE and MIN-TIME as passed to
     `make-progress-reporter' and so does not output new messages on
     every invocation.  It is thus very fast and normally you should not
     try to reduce the number of calls to it: resulting overhead will
     most likely negate your effort.

 -- Function: progress-reporter-force-update reporter value &optional
          new-message
     This function is similar to `progress-reporter-update' except that
     it prints a message in the echo area unconditionally.

     The first two arguments have the same meaning as for
     `progress-reporter-update'.  Optional NEW-MESSAGE allows you to
     change the message of the REPORTER.  Since this functions always
     updates the echo area, such a change will be immediately presented
     to the user.

 -- Function: progress-reporter-done reporter
     This function should be called when the operation is finished.  It
     prints the message of REPORTER followed by word "done" in the echo
     area.

     You should always call this function and not hope for
     `progress-reporter-update' to print "100%."  Firstly, it may never
     print it, there are many good reasons for this not to happen.
     Secondly, "done" is more explicit.

 -- Macro: dotimes-with-progress-reporter (var count [result]) message
          body...
     This is a convenience macro that works the same way as `dotimes'
     does, but also reports loop progress using the functions described
     above.  It allows you to save some typing.

     You can rewrite the example in the beginning of this node using
     this macro this way:

          (dotimes-with-progress-reporter
              (k 500)
              "Collecting some mana for Emacs..."
            (sit-for 0.01))


File: elisp,  Node: Logging Messages,  Next: Echo Area Customization,  Prev: Progress,  Up: The Echo Area

38.4.3 Logging Messages in `*Messages*'
---------------------------------------

Almost all the messages displayed in the echo area are also recorded in
the `*Messages*' buffer so that the user can refer back to them.  This
includes all the messages that are output with `message'.

 -- User Option: message-log-max
     This variable specifies how many lines to keep in the `*Messages*'
     buffer.  The value `t' means there is no limit on how many lines to
     keep.  The value `nil' disables message logging entirely.  Here's
     how to display a message and prevent it from being logged:

          (let (message-log-max)
            (message ...))

   To make `*Messages*' more convenient for the user, the logging
facility combines successive identical messages.  It also combines
successive related messages for the sake of two cases: question
followed by answer, and a series of progress messages.

   A "question followed by an answer" means two messages like the ones
produced by `y-or-n-p': the first is `QUESTION', and the second is
`QUESTION...ANSWER'.  The first message conveys no additional
information beyond what's in the second, so logging the second message
discards the first from the log.

   A "series of progress messages" means successive messages like those
produced by `make-progress-reporter'.  They have the form
`BASE...HOW-FAR', where BASE is the same each time, while HOW-FAR
varies.  Logging each message in the series discards the previous one,
provided they are consecutive.

   The functions `make-progress-reporter' and `y-or-n-p' don't have to
do anything special to activate the message log combination feature.
It operates whenever two consecutive messages are logged that share a
common prefix ending in `...'.


File: elisp,  Node: Echo Area Customization,  Prev: Logging Messages,  Up: The Echo Area

38.4.4 Echo Area Customization
------------------------------

These variables control details of how the echo area works.

 -- Variable: cursor-in-echo-area
     This variable controls where the cursor appears when a message is
     displayed in the echo area.  If it is non-`nil', then the cursor
     appears at the end of the message.  Otherwise, the cursor appears
     at point--not in the echo area at all.

     The value is normally `nil'; Lisp programs bind it to `t' for
     brief periods of time.

 -- Variable: echo-area-clear-hook
     This normal hook is run whenever the echo area is cleared--either
     by `(message nil)' or for any other reason.

 -- User Option: echo-keystrokes
     This variable determines how much time should elapse before command
     characters echo.  Its value must be an integer or floating point
     number, which specifies the number of seconds to wait before
     echoing.  If the user types a prefix key (such as `C-x') and then
     delays this many seconds before continuing, the prefix key is
     echoed in the echo area.  (Once echoing begins in a key sequence,
     all subsequent characters in the same key sequence are echoed
     immediately.)

     If the value is zero, then command input is not echoed.

 -- Variable: message-truncate-lines
     Normally, displaying a long message resizes the echo area to
     display the entire message.  But if the variable
     `message-truncate-lines' is non-`nil', the echo area does not
     resize, and the message is truncated to fit it, as in Emacs 20 and
     before.

   The variable `max-mini-window-height', which specifies the maximum
height for resizing minibuffer windows, also applies to the echo area
(which is really a special use of the minibuffer window.  *Note
Minibuffer Misc::.).


File: elisp,  Node: Warnings,  Next: Invisible Text,  Prev: The Echo Area,  Up: Display

38.5 Reporting Warnings
=======================

"Warnings" are a facility for a program to inform the user of a
possible problem, but continue running.

* Menu:

* Warning Basics::      Warnings concepts and functions to report them.
* Warning Variables::   Variables programs bind to customize their warnings.
* Warning Options::     Variables users set to control display of warnings.


File: elisp,  Node: Warning Basics,  Next: Warning Variables,  Up: Warnings

38.5.1 Warning Basics
---------------------

Every warning has a textual message, which explains the problem for the
user, and a "severity level" which is a symbol.  Here are the possible
severity levels, in order of decreasing severity, and their meanings:

`:emergency'
     A problem that will seriously impair Emacs operation soon if you
     do not attend to it promptly.

`:error'
     A report of data or circumstances that are inherently wrong.

`:warning'
     A report of data or circumstances that are not inherently wrong,
     but raise suspicion of a possible problem.

`:debug'
     A report of information that may be useful if you are debugging.

   When your program encounters invalid input data, it can either
signal a Lisp error by calling `error' or `signal' or report a warning
with severity `:error'.  Signaling a Lisp error is the easiest thing to
do, but it means the program cannot continue processing.  If you want
to take the trouble to implement a way to continue processing despite
the bad data, then reporting a warning of severity `:error' is the
right way to inform the user of the problem.  For instance, the Emacs
Lisp byte compiler can report an error that way and continue compiling
other functions.  (If the program signals a Lisp error and then handles
it with `condition-case', the user won't see the error message; it could
show the message to the user by reporting it as a warning.)

   Each warning has a "warning type" to classify it.  The type is a
list of symbols.  The first symbol should be the custom group that you
use for the program's user options.  For example, byte compiler
warnings use the warning type `(bytecomp)'.  You can also subcategorize
the warnings, if you wish, by using more symbols in the list.

 -- Function: display-warning type message &optional level buffer-name
     This function reports a warning, using MESSAGE as the message and
     TYPE as the warning type.  LEVEL should be the severity level,
     with `:warning' being the default.

     BUFFER-NAME, if non-`nil', specifies the name of the buffer for
     logging the warning.  By default, it is `*Warnings*'.

 -- Function: lwarn type level message &rest args
     This function reports a warning using the value of `(format
     MESSAGE ARGS...)' as the message.  In other respects it is
     equivalent to `display-warning'.

 -- Function: warn message &rest args
     This function reports a warning using the value of `(format
     MESSAGE ARGS...)' as the message, `(emacs)' as the type, and
     `:warning' as the severity level.  It exists for compatibility
     only; we recommend not using it, because you should specify a
     specific warning type.


File: elisp,  Node: Warning Variables,  Next: Warning Options,  Prev: Warning Basics,  Up: Warnings

38.5.2 Warning Variables
------------------------

Programs can customize how their warnings appear by binding the
variables described in this section.

 -- Variable: warning-levels
     This list defines the meaning and severity order of the warning
     severity levels.  Each element defines one severity level, and
     they are arranged in order of decreasing severity.

     Each element has the form `(LEVEL STRING FUNCTION)', where LEVEL
     is the severity level it defines.  STRING specifies the textual
     description of this level.  STRING should use `%s' to specify
     where to put the warning type information, or it can omit the `%s'
     so as not to include that information.

     The optional FUNCTION, if non-`nil', is a function to call with no
     arguments, to get the user's attention.

     Normally you should not change the value of this variable.

 -- Variable: warning-prefix-function
     If non-`nil', the value is a function to generate prefix text for
     warnings.  Programs can bind the variable to a suitable function.
     `display-warning' calls this function with the warnings buffer
     current, and the function can insert text in it.  That text becomes
     the beginning of the warning message.

     The function is called with two arguments, the severity level and
     its entry in `warning-levels'.  It should return a list to use as
     the entry (this value need not be an actual member of
     `warning-levels').  By constructing this value, the function can
     change the severity of the warning, or specify different handling
     for a given severity level.

     If the variable's value is `nil' then there is no function to call.

 -- Variable: warning-series
     Programs can bind this variable to `t' to say that the next
     warning should begin a series.  When several warnings form a
     series, that means to leave point on the first warning of the
     series, rather than keep moving it for each warning so that it
     appears on the last one.  The series ends when the local binding
     is unbound and `warning-series' becomes `nil' again.

     The value can also be a symbol with a function definition.  That is
     equivalent to `t', except that the next warning will also call the
     function with no arguments with the warnings buffer current.  The
     function can insert text which will serve as a header for the
     series of warnings.

     Once a series has begun, the value is a marker which points to the
     buffer position in the warnings buffer of the start of the series.

     The variable's normal value is `nil', which means to handle each
     warning separately.

 -- Variable: warning-fill-prefix
     When this variable is non-`nil', it specifies a fill prefix to use
     for filling each warning's text.

 -- Variable: warning-type-format
     This variable specifies the format for displaying the warning type
     in the warning message.  The result of formatting the type this way
     gets included in the message under the control of the string in the
     entry in `warning-levels'.  The default value is `" (%s)"'.  If
     you bind it to `""' then the warning type won't appear at all.


File: elisp,  Node: Warning Options,  Prev: Warning Variables,  Up: Warnings

38.5.3 Warning Options
----------------------

These variables are used by users to control what happens when a Lisp
program reports a warning.

 -- User Option: warning-minimum-level
     This user option specifies the minimum severity level that should
     be shown immediately to the user.  The default is `:warning', which
     means to immediately display all warnings except `:debug' warnings.

 -- User Option: warning-minimum-log-level
     This user option specifies the minimum severity level that should
     be logged in the warnings buffer.  The default is `:warning', which
     means to log all warnings except `:debug' warnings.

 -- User Option: warning-suppress-types
     This list specifies which warning types should not be displayed
     immediately for the user.  Each element of the list should be a
     list of symbols.  If its elements match the first elements in a
     warning type, then that warning is not displayed immediately.

 -- User Option: warning-suppress-log-types
     This list specifies which warning types should not be logged in the
     warnings buffer.  Each element of the list should be a list of
     symbols.  If it matches the first few elements in a warning type,
     then that warning is not logged.


File: elisp,  Node: Invisible Text,  Next: Selective Display,  Prev: Warnings,  Up: Display

38.6 Invisible Text
===================

You can make characters "invisible", so that they do not appear on the
screen, with the `invisible' property.  This can be either a text
property (*note Text Properties::) or a property of an overlay (*note
Overlays::).  Cursor motion also partly ignores these characters; if
the command loop finds point within them, it moves point to the other
side of them.

   In the simplest case, any non-`nil' `invisible' property makes a
character invisible.  This is the default case--if you don't alter the
default value of `buffer-invisibility-spec', this is how the
`invisible' property works.  You should normally use `t' as the value
of the `invisible' property if you don't plan to set
`buffer-invisibility-spec' yourself.

   More generally, you can use the variable `buffer-invisibility-spec'
to control which values of the `invisible' property make text
invisible.  This permits you to classify the text into different subsets
in advance, by giving them different `invisible' values, and
subsequently make various subsets visible or invisible by changing the
value of `buffer-invisibility-spec'.

   Controlling visibility with `buffer-invisibility-spec' is especially
useful in a program to display the list of entries in a database.  It
permits the implementation of convenient filtering commands to view
just a part of the entries in the database.  Setting this variable is
very fast, much faster than scanning all the text in the buffer looking
for properties to change.

 -- Variable: buffer-invisibility-spec
     This variable specifies which kinds of `invisible' properties
     actually make a character invisible.  Setting this variable makes
     it buffer-local.

    `t'
          A character is invisible if its `invisible' property is
          non-`nil'.  This is the default.

    a list
          Each element of the list specifies a criterion for
          invisibility; if a character's `invisible' property fits any
          one of these criteria, the character is invisible.  The list
          can have two kinds of elements:

         `ATOM'
               A character is invisible if its `invisible' property
               value is ATOM or if it is a list with ATOM as a member.

         `(ATOM . t)'
               A character is invisible if its `invisible' property
               value is ATOM or if it is a list with ATOM as a member.
               Moreover, a sequence of such characters displays as an
               ellipsis.

   Two functions are specifically provided for adding elements to
`buffer-invisibility-spec' and removing elements from it.

 -- Function: add-to-invisibility-spec element
     This function adds the element ELEMENT to
     `buffer-invisibility-spec'.  If `buffer-invisibility-spec' was
     `t', it changes to a list, `(t)', so that text whose `invisible'
     property is `t' remains invisible.

 -- Function: remove-from-invisibility-spec element
     This removes the element ELEMENT from `buffer-invisibility-spec'.
     This does nothing if ELEMENT is not in the list.

   A convention for use of `buffer-invisibility-spec' is that a major
mode should use the mode's own name as an element of
`buffer-invisibility-spec' and as the value of the `invisible' property:

     ;; If you want to display an ellipsis:
     (add-to-invisibility-spec '(my-symbol . t))
     ;; If you don't want ellipsis:
     (add-to-invisibility-spec 'my-symbol)

     (overlay-put (make-overlay beginning end)
                  'invisible 'my-symbol)

     ;; When done with the overlays:
     (remove-from-invisibility-spec '(my-symbol . t))
     ;; Or respectively:
     (remove-from-invisibility-spec 'my-symbol)

   You can check for invisibility using the following function:

 -- Function: invisible-p pos-or-prop
     If POS-OR-PROP is a marker or number, this function returns a
     non-`nil' value if the text at that position is invisible.

     If POS-OR-PROP is any other kind of Lisp object, that is taken to
     mean a possible value of the `invisible' text or overlay property.
     In that case, this function returns a non-`nil' value if that
     value would cause text to become invisible, based on the current
     value of `buffer-invisibility-spec'.

   Ordinarily, functions that operate on text or move point do not care
whether the text is invisible.  The user-level line motion commands
ignore invisible newlines if `line-move-ignore-invisible' is non-`nil'
(the default), but only because they are explicitly programmed to do so.

   However, if a command ends with point inside or immediately before
invisible text, the main editing loop moves point further forward or
further backward (in the same direction that the command already moved
it) until that condition is no longer true.  Thus, if the command moved
point back into an invisible range, Emacs moves point back to the
beginning of that range, and then back one more character.  If the
command moved point forward into an invisible range, Emacs moves point
forward up to the first visible character that follows the invisible
text.

   Incremental search can make invisible overlays visible temporarily
and/or permanently when a match includes invisible text.  To enable
this, the overlay should have a non-`nil' `isearch-open-invisible'
property.  The property value should be a function to be called with
the overlay as an argument.  This function should make the overlay
visible permanently; it is used when the match overlaps the overlay on
exit from the search.

   During the search, such overlays are made temporarily visible by
temporarily modifying their invisible and intangible properties.  If you
want this to be done differently for a certain overlay, give it an
`isearch-open-invisible-temporary' property which is a function.  The
function is called with two arguments: the first is the overlay, and
the second is `nil' to make the overlay visible, or `t' to make it
invisible again.


File: elisp,  Node: Selective Display,  Next: Temporary Displays,  Prev: Invisible Text,  Up: Display

38.7 Selective Display
======================

"Selective display" refers to a pair of related features for hiding
certain lines on the screen.

   The first variant, explicit selective display, is designed for use
in a Lisp program: it controls which lines are hidden by altering the
text.  This kind of hiding in some ways resembles the effect of the
`invisible' property (*note Invisible Text::), but the two features are
different and do not work the same way.

   In the second variant, the choice of lines to hide is made
automatically based on indentation.  This variant is designed to be a
user-level feature.

   The way you control explicit selective display is by replacing a
newline (control-j) with a carriage return (control-m).  The text that
was formerly a line following that newline is now hidden.  Strictly
speaking, it is temporarily no longer a line at all, since only
newlines can separate lines; it is now part of the previous line.

   Selective display does not directly affect editing commands.  For
example, `C-f' (`forward-char') moves point unhesitatingly into hidden
text.  However, the replacement of newline characters with carriage
return characters affects some editing commands.  For example,
`next-line' skips hidden lines, since it searches only for newlines.
Modes that use selective display can also define commands that take
account of the newlines, or that control which parts of the text are
hidden.

   When you write a selectively displayed buffer into a file, all the
control-m's are output as newlines.  This means that when you next read
in the file, it looks OK, with nothing hidden.  The selective display
effect is seen only within Emacs.

 -- Variable: selective-display
     This buffer-local variable enables selective display.  This means
     that lines, or portions of lines, may be made hidden.

        * If the value of `selective-display' is `t', then the character
          control-m marks the start of hidden text; the control-m, and
          the rest of the line following it, are not displayed.  This
          is explicit selective display.

        * If the value of `selective-display' is a positive integer,
          then lines that start with more than that many columns of
          indentation are not displayed.

     When some portion of a buffer is hidden, the vertical movement
     commands operate as if that portion did not exist, allowing a
     single `next-line' command to skip any number of hidden lines.
     However, character movement commands (such as `forward-char') do
     not skip the hidden portion, and it is possible (if tricky) to
     insert or delete text in an hidden portion.

     In the examples below, we show the _display appearance_ of the
     buffer `foo', which changes with the value of `selective-display'.
     The _contents_ of the buffer do not change.

          (setq selective-display nil)
               => nil

          ---------- Buffer: foo ----------
          1 on this column
           2on this column
            3n this column
            3n this column
           2on this column
          1 on this column
          ---------- Buffer: foo ----------

          (setq selective-display 2)
               => 2

          ---------- Buffer: foo ----------
          1 on this column
           2on this column
           2on this column
          1 on this column
          ---------- Buffer: foo ----------

 -- User Option: selective-display-ellipses
     If this buffer-local variable is non-`nil', then Emacs displays
     `...' at the end of a line that is followed by hidden text.  This
     example is a continuation of the previous one.

          (setq selective-display-ellipses t)
               => t

          ---------- Buffer: foo ----------
          1 on this column
           2on this column ...
           2on this column
          1 on this column
          ---------- Buffer: foo ----------

     You can use a display table to substitute other text for the
     ellipsis (`...').  *Note Display Tables::.


File: elisp,  Node: Temporary Displays,  Next: Overlays,  Prev: Selective Display,  Up: Display

38.8 Temporary Displays
=======================

Temporary displays are used by Lisp programs to put output into a
buffer and then present it to the user for perusal rather than for
editing.  Many help commands use this feature.

 -- Special Form: with-output-to-temp-buffer buffer-name forms...
     This function executes FORMS while arranging to insert any output
     they print into the buffer named BUFFER-NAME, which is first
     created if necessary, and put into Help mode.  Finally, the buffer
     is displayed in some window, but not selected.

     If the FORMS do not change the major mode in the output buffer, so
     that it is still Help mode at the end of their execution, then
     `with-output-to-temp-buffer' makes this buffer read-only at the
     end, and also scans it for function and variable names to make them
     into clickable cross-references.  *Note Tips for Documentation
     Strings: Docstring hyperlinks, in particular the item on
     hyperlinks in documentation strings, for more details.

     The string BUFFER-NAME specifies the temporary buffer, which need
     not already exist.  The argument must be a string, not a buffer.
     The buffer is erased initially (with no questions asked), and it is
     marked as unmodified after `with-output-to-temp-buffer' exits.

     `with-output-to-temp-buffer' binds `standard-output' to the
     temporary buffer, then it evaluates the forms in FORMS.  Output
     using the Lisp output functions within FORMS goes by default to
     that buffer (but screen display and messages in the echo area,
     although they are "output" in the general sense of the word, are
     not affected).  *Note Output Functions::.

     Several hooks are available for customizing the behavior of this
     construct; they are listed below.

     The value of the last form in FORMS is returned.

          ---------- Buffer: foo ----------
           This is the contents of foo.
          ---------- Buffer: foo ----------

          (with-output-to-temp-buffer "foo"
              (print 20)
              (print standard-output))
          => #<buffer foo>

          ---------- Buffer: foo ----------
          20

          #<buffer foo>

          ---------- Buffer: foo ----------

 -- User Option: temp-buffer-show-function
     If this variable is non-`nil', `with-output-to-temp-buffer' calls
     it as a function to do the job of displaying a help buffer.  The
     function gets one argument, which is the buffer it should display.

     It is a good idea for this function to run `temp-buffer-show-hook'
     just as `with-output-to-temp-buffer' normally would, inside of
     `save-selected-window' and with the chosen window and buffer
     selected.

 -- Variable: temp-buffer-setup-hook
     This normal hook is run by `with-output-to-temp-buffer' before
     evaluating BODY.  When the hook runs, the temporary buffer is
     current.  This hook is normally set up with a function to put the
     buffer in Help mode.

 -- Variable: temp-buffer-show-hook
     This normal hook is run by `with-output-to-temp-buffer' after
     displaying the temporary buffer.  When the hook runs, the
     temporary buffer is current, and the window it was displayed in is
     selected.

 -- Function: momentary-string-display string position &optional char
          message
     This function momentarily displays STRING in the current buffer at
     POSITION.  It has no effect on the undo list or on the buffer's
     modification status.

     The momentary display remains until the next input event.  If the
     next input event is CHAR, `momentary-string-display' ignores it
     and returns.  Otherwise, that event remains buffered for
     subsequent use as input.  Thus, typing CHAR will simply remove the
     string from the display, while typing (say) `C-f' will remove the
     string from the display and later (presumably) move point forward.
     The argument CHAR is a space by default.

     The return value of `momentary-string-display' is not meaningful.

     If the string STRING does not contain control characters, you can
     do the same job in a more general way by creating (and then
     subsequently deleting) an overlay with a `before-string' property.
     *Note Overlay Properties::.

     If MESSAGE is non-`nil', it is displayed in the echo area while
     STRING is displayed in the buffer.  If it is `nil', a default
     message says to type CHAR to continue.

     In this example, point is initially located at the beginning of the
     second line:

          ---------- Buffer: foo ----------
          This is the contents of foo.
          -!-Second line.
          ---------- Buffer: foo ----------

          (momentary-string-display
            "**** Important Message! ****"
            (point) ?\r
            "Type RET when done reading")
          => t

          ---------- Buffer: foo ----------
          This is the contents of foo.
          **** Important Message! ****Second line.
          ---------- Buffer: foo ----------

          ---------- Echo Area ----------
          Type RET when done reading
          ---------- Echo Area ----------


File: elisp,  Node: Overlays,  Next: Width,  Prev: Temporary Displays,  Up: Display

38.9 Overlays
=============

You can use "overlays" to alter the appearance of a buffer's text on
the screen, for the sake of presentation features.  An overlay is an
object that belongs to a particular buffer, and has a specified
beginning and end.  It also has properties that you can examine and set;
these affect the display of the text within the overlay.

   The visual effect of an overlay is the same as of the corresponding
text property (*note Text Properties::).  However, due to a different
implementation, overlays generally don't scale well (many operations
take a time that is proportional to the number of overlays in the
buffer).  If you need to affect the visual appearance of many portions
in the buffer, we recommend using text properties.

   An overlay uses markers to record its beginning and end; thus,
editing the text of the buffer adjusts the beginning and end of each
overlay so that it stays with the text.  When you create the overlay,
you can specify whether text inserted at the beginning should be inside
the overlay or outside, and likewise for the end of the overlay.

* Menu:

* Managing Overlays::   Creating and moving overlays.
* Overlay Properties::  How to read and set properties.
                          What properties do to the screen display.
* Finding Overlays::    Searching for overlays.


File: elisp,  Node: Managing Overlays,  Next: Overlay Properties,  Up: Overlays

38.9.1 Managing Overlays
------------------------

This section describes the functions to create, delete and move
overlays, and to examine their contents.  Overlay changes are not
recorded in the buffer's undo list, since the overlays are not part of
the buffer's contents.

 -- Function: overlayp object
     This function returns `t' if OBJECT is an overlay.

 -- Function: make-overlay start end &optional buffer front-advance
          rear-advance
     This function creates and returns an overlay that belongs to
     BUFFER and ranges from START to END.  Both START and END must
     specify buffer positions; they may be integers or markers.  If
     BUFFER is omitted, the overlay is created in the current buffer.

     The arguments FRONT-ADVANCE and REAR-ADVANCE specify the marker
     insertion type for the start of the overlay and for the end of the
     overlay, respectively.  *Note Marker Insertion Types::.  If they
     are both `nil', the default, then the overlay extends to include
     any text inserted at the beginning, but not text inserted at the
     end.  If FRONT-ADVANCE is non-`nil', text inserted at the
     beginning of the overlay is excluded from the overlay.  If
     REAR-ADVANCE is non-`nil', text inserted at the end of the overlay
     is included in the overlay.

 -- Function: overlay-start overlay
     This function returns the position at which OVERLAY starts, as an
     integer.

 -- Function: overlay-end overlay
     This function returns the position at which OVERLAY ends, as an
     integer.

 -- Function: overlay-buffer overlay
     This function returns the buffer that OVERLAY belongs to.  It
     returns `nil' if OVERLAY has been deleted.

 -- Function: delete-overlay overlay
     This function deletes OVERLAY.  The overlay continues to exist as
     a Lisp object, and its property list is unchanged, but it ceases
     to be attached to the buffer it belonged to, and ceases to have
     any effect on display.

     A deleted overlay is not permanently disconnected.  You can give
     it a position in a buffer again by calling `move-overlay'.

 -- Function: move-overlay overlay start end &optional buffer
     This function moves OVERLAY to BUFFER, and places its bounds at
     START and END.  Both arguments START and END must specify buffer
     positions; they may be integers or markers.

     If BUFFER is omitted, OVERLAY stays in the same buffer it was
     already associated with; if OVERLAY was deleted, it goes into the
     current buffer.

     The return value is OVERLAY.

     This is the only valid way to change the endpoints of an overlay.
     Do not try modifying the markers in the overlay by hand, as that
     fails to update other vital data structures and can cause some
     overlays to be "lost."

 -- Function: remove-overlays &optional start end name value
     This function removes all the overlays between START and END whose
     property NAME has the value VALUE.  It can move the endpoints of
     the overlays in the region, or split them.

     If NAME is omitted or `nil', it means to delete all overlays in
     the specified region.  If START and/or END are omitted or `nil',
     that means the beginning and end of the buffer respectively.
     Therefore, `(remove-overlays)' removes all the overlays in the
     current buffer.

 -- Function: copy-overlay overlay
     This function returns a copy of OVERLAY.  The copy has the same
     endpoints and properties as OVERLAY.  However, the marker
     insertion type for the start of the overlay and for the end of the
     overlay are set to their default values (*note Marker Insertion
     Types::).

   Here are some examples:

     ;; Create an overlay.
     (setq foo (make-overlay 1 10))
          => #<overlay from 1 to 10 in display.texi>
     (overlay-start foo)
          => 1
     (overlay-end foo)
          => 10
     (overlay-buffer foo)
          => #<buffer display.texi>
     ;; Give it a property we can check later.
     (overlay-put foo 'happy t)
          => t
     ;; Verify the property is present.
     (overlay-get foo 'happy)
          => t
     ;; Move the overlay.
     (move-overlay foo 5 20)
          => #<overlay from 5 to 20 in display.texi>
     (overlay-start foo)
          => 5
     (overlay-end foo)
          => 20
     ;; Delete the overlay.
     (delete-overlay foo)
          => nil
     ;; Verify it is deleted.
     foo
          => #<overlay in no buffer>
     ;; A deleted overlay has no position.
     (overlay-start foo)
          => nil
     (overlay-end foo)
          => nil
     (overlay-buffer foo)
          => nil
     ;; Undelete the overlay.
     (move-overlay foo 1 20)
          => #<overlay from 1 to 20 in display.texi>
     ;; Verify the results.
     (overlay-start foo)
          => 1
     (overlay-end foo)
          => 20
     (overlay-buffer foo)
          => #<buffer display.texi>
     ;; Moving and deleting the overlay does not change its properties.
     (overlay-get foo 'happy)
          => t

   Emacs stores the overlays of each buffer in two lists, divided
around an arbitrary "center position."  One list extends backwards
through the buffer from that center position, and the other extends
forwards from that center position.  The center position can be anywhere
in the buffer.

 -- Function: overlay-recenter pos
     This function recenters the overlays of the current buffer around
     position POS.  That makes overlay lookup faster for positions near
     POS, but slower for positions far away from POS.

   A loop that scans the buffer forwards, creating overlays, can run
faster if you do `(overlay-recenter (point-max))' first.

