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

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

   This is edition 2.9 of the GNU Emacs Lisp Reference Manual,
corresponding to Emacs version 22.3.

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999,
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008  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.2 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 are free to copy and modify
     this GNU Manual. Buying copies from GNU Press supports the FSF in
     developing GNU and promoting software freedom."


File: elisp,  Node: Columns,  Next: Indentation,  Prev: Sorting,  Up: Text

32.16 Counting Columns
======================

The column functions convert between a character position (counting
characters from the beginning of the buffer) and a column position
(counting screen characters from the beginning of a line).

   These functions count each character according to the number of
columns it occupies on the screen.  This means control characters count
as occupying 2 or 4 columns, depending upon the value of `ctl-arrow',
and tabs count as occupying a number of columns that depends on the
value of `tab-width' and on the column where the tab begins.  *Note
Usual Display::.

   Column number computations ignore the width of the window and the
amount of horizontal scrolling.  Consequently, a column value can be
arbitrarily high.  The first (or leftmost) column is numbered 0.  They
also ignore overlays and text properties, aside from invisibility.

 -- Function: current-column
     This function returns the horizontal position of point, measured in
     columns, counting from 0 at the left margin.  The column position
     is the sum of the widths of all the displayed representations of
     the characters between the start of the current line and point.

     For an example of using `current-column', see the description of
     `count-lines' in *note Text Lines::.

 -- Function: move-to-column column &optional force
     This function moves point to COLUMN in the current line.  The
     calculation of COLUMN takes into account the widths of the
     displayed representations of the characters between the start of
     the line and point.

     If column COLUMN is beyond the end of the line, point moves to the
     end of the line.  If COLUMN is negative, point moves to the
     beginning of the line.

     If it is impossible to move to column COLUMN because that is in
     the middle of a multicolumn character such as a tab, point moves
     to the end of that character.  However, if FORCE is non-`nil', and
     COLUMN is in the middle of a tab, then `move-to-column' converts
     the tab into spaces so that it can move precisely to column
     COLUMN.  Other multicolumn characters can cause anomalies despite
     FORCE, since there is no way to split them.

     The argument FORCE also has an effect if the line isn't long
     enough to reach column COLUMN; if it is `t', that means to add
     whitespace at the end of the line to reach that column.

     If COLUMN is not an integer, an error is signaled.

     The return value is the column number actually moved to.


File: elisp,  Node: Indentation,  Next: Case Changes,  Prev: Columns,  Up: Text

32.17 Indentation
=================

The indentation functions are used to examine, move to, and change
whitespace that is at the beginning of a line.  Some of the functions
can also change whitespace elsewhere on a line.  Columns and indentation
count from zero at the left margin.

* Menu:

* Primitive Indent::      Functions used to count and insert indentation.
* Mode-Specific Indent::  Customize indentation for different modes.
* Region Indent::         Indent all the lines in a region.
* Relative Indent::       Indent the current line based on previous lines.
* Indent Tabs::           Adjustable, typewriter-like tab stops.
* Motion by Indent::      Move to first non-blank character.


File: elisp,  Node: Primitive Indent,  Next: Mode-Specific Indent,  Up: Indentation

32.17.1 Indentation Primitives
------------------------------

This section describes the primitive functions used to count and insert
indentation.  The functions in the following sections use these
primitives.  *Note Width::, for related functions.

 -- Function: current-indentation
     This function returns the indentation of the current line, which is
     the horizontal position of the first nonblank character.  If the
     contents are entirely blank, then this is the horizontal position
     of the end of the line.

 -- Command: indent-to column &optional minimum
     This function indents from point with tabs and spaces until COLUMN
     is reached.  If MINIMUM is specified and non-`nil', then at least
     that many spaces are inserted even if this requires going beyond
     COLUMN.  Otherwise the function does nothing if point is already
     beyond COLUMN.  The value is the column at which the inserted
     indentation ends.

     The inserted whitespace characters inherit text properties from the
     surrounding text (usually, from the preceding text only).  *Note
     Sticky Properties::.

 -- User Option: indent-tabs-mode
     If this variable is non-`nil', indentation functions can insert
     tabs as well as spaces.  Otherwise, they insert only spaces.
     Setting this variable automatically makes it buffer-local in the
     current buffer.


File: elisp,  Node: Mode-Specific Indent,  Next: Region Indent,  Prev: Primitive Indent,  Up: Indentation

32.17.2 Indentation Controlled by Major Mode
--------------------------------------------

An important function of each major mode is to customize the <TAB> key
to indent properly for the language being edited.  This section
describes the mechanism of the <TAB> key and how to control it.  The
functions in this section return unpredictable values.

 -- Variable: indent-line-function
     This variable's value is the function to be used by <TAB> (and
     various commands) to indent the current line.  The command
     `indent-according-to-mode' does no more than call this function.

     In Lisp mode, the value is the symbol `lisp-indent-line'; in C
     mode, `c-indent-line'; in Fortran mode, `fortran-indent-line'.
     The default value is `indent-relative'.

 -- Command: indent-according-to-mode
     This command calls the function in `indent-line-function' to
     indent the current line in a way appropriate for the current major
     mode.

 -- Command: indent-for-tab-command
     This command calls the function in `indent-line-function' to indent
     the current line; however, if that function is
     `indent-to-left-margin', `insert-tab' is called instead.  (That is
     a trivial command that inserts a tab character.)

 -- Command: newline-and-indent
     This function inserts a newline, then indents the new line (the one
     following the newline just inserted) according to the major mode.

     It does indentation by calling the current `indent-line-function'.
     In programming language modes, this is the same thing <TAB> does,
     but in some text modes, where <TAB> inserts a tab,
     `newline-and-indent' indents to the column specified by
     `left-margin'.

 -- Command: reindent-then-newline-and-indent
     This command reindents the current line, inserts a newline at
     point, and then indents the new line (the one following the
     newline just inserted).

     This command does indentation on both lines according to the
     current major mode, by calling the current value of
     `indent-line-function'.  In programming language modes, this is
     the same thing <TAB> does, but in some text modes, where <TAB>
     inserts a tab, `reindent-then-newline-and-indent' indents to the
     column specified by `left-margin'.


File: elisp,  Node: Region Indent,  Next: Relative Indent,  Prev: Mode-Specific Indent,  Up: Indentation

32.17.3 Indenting an Entire Region
----------------------------------

This section describes commands that indent all the lines in the
region.  They return unpredictable values.

 -- Command: indent-region start end to-column
     This command indents each nonblank line starting between START
     (inclusive) and END (exclusive).  If TO-COLUMN is `nil',
     `indent-region' indents each nonblank line by calling the current
     mode's indentation function, the value of `indent-line-function'.

     If TO-COLUMN is non-`nil', it should be an integer specifying the
     number of columns of indentation; then this function gives each
     line exactly that much indentation, by either adding or deleting
     whitespace.

     If there is a fill prefix, `indent-region' indents each line by
     making it start with the fill prefix.

 -- Variable: indent-region-function
     The value of this variable is a function that can be used by
     `indent-region' as a short cut.  It should take two arguments, the
     start and end of the region.  You should design the function so
     that it will produce the same results as indenting the lines of the
     region one by one, but presumably faster.

     If the value is `nil', there is no short cut, and `indent-region'
     actually works line by line.

     A short-cut function is useful in modes such as C mode and Lisp
     mode, where the `indent-line-function' must scan from the
     beginning of the function definition: applying it to each line
     would be quadratic in time.  The short cut can update the scan
     information as it moves through the lines indenting them; this
     takes linear time.  In a mode where indenting a line individually
     is fast, there is no need for a short cut.

     `indent-region' with a non-`nil' argument TO-COLUMN has a
     different meaning and does not use this variable.

 -- Command: indent-rigidly start end count
     This command indents all lines starting between START (inclusive)
     and END (exclusive) sideways by COUNT columns.  This "preserves
     the shape" of the affected region, moving it as a rigid unit.
     Consequently, this command is useful not only for indenting
     regions of unindented text, but also for indenting regions of
     formatted code.

     For example, if COUNT is 3, this command adds 3 columns of
     indentation to each of the lines beginning in the region specified.

     In Mail mode, `C-c C-y' (`mail-yank-original') uses
     `indent-rigidly' to indent the text copied from the message being
     replied to.

 -- Function: indent-code-rigidly start end columns &optional
          nochange-regexp
     This is like `indent-rigidly', except that it doesn't alter lines
     that start within strings or comments.

     In addition, it doesn't alter a line if NOCHANGE-REGEXP matches at
     the beginning of the line (if NOCHANGE-REGEXP is non-`nil').


File: elisp,  Node: Relative Indent,  Next: Indent Tabs,  Prev: Region Indent,  Up: Indentation

32.17.4 Indentation Relative to Previous Lines
----------------------------------------------

This section describes two commands that indent the current line based
on the contents of previous lines.

 -- Command: indent-relative &optional unindented-ok
     This command inserts whitespace at point, extending to the same
     column as the next "indent point" of the previous nonblank line.
     An indent point is a non-whitespace character following
     whitespace.  The next indent point is the first one at a column
     greater than the current column of point.  For example, if point
     is underneath and to the left of the first non-blank character of
     a line of text, it moves to that column by inserting whitespace.

     If the previous nonblank line has no next indent point (i.e., none
     at a great enough column position), `indent-relative' either does
     nothing (if UNINDENTED-OK is non-`nil') or calls
     `tab-to-tab-stop'.  Thus, if point is underneath and to the right
     of the last column of a short line of text, this command ordinarily
     moves point to the next tab stop by inserting whitespace.

     The return value of `indent-relative' is unpredictable.

     In the following example, point is at the beginning of the second
     line:

                      This line is indented twelve spaces.
          -!-The quick brown fox jumped.

     Evaluation of the expression `(indent-relative nil)' produces the
     following:

                      This line is indented twelve spaces.
                      -!-The quick brown fox jumped.

     In this next example, point is between the `m' and `p' of `jumped':

                      This line is indented twelve spaces.
          The quick brown fox jum-!-ped.

     Evaluation of the expression `(indent-relative nil)' produces the
     following:

                      This line is indented twelve spaces.
          The quick brown fox jum  -!-ped.

 -- Command: indent-relative-maybe
     This command indents the current line like the previous nonblank
     line, by calling `indent-relative' with `t' as the UNINDENTED-OK
     argument.  The return value is unpredictable.

     If the previous nonblank line has no indent points beyond the
     current column, this command does nothing.


File: elisp,  Node: Indent Tabs,  Next: Motion by Indent,  Prev: Relative Indent,  Up: Indentation

32.17.5 Adjustable "Tab Stops"
------------------------------

This section explains the mechanism for user-specified "tab stops" and
the mechanisms that use and set them.  The name "tab stops" is used
because the feature is similar to that of the tab stops on a
typewriter.  The feature works by inserting an appropriate number of
spaces and tab characters to reach the next tab stop column; it does not
affect the display of tab characters in the buffer (*note Usual
Display::).  Note that the <TAB> character as input uses this tab stop
feature only in a few major modes, such as Text mode.  *Note Tab Stops:
(emacs)Tab Stops.

 -- Command: tab-to-tab-stop
     This command inserts spaces or tabs before point, up to the next
     tab stop column defined by `tab-stop-list'.  It searches the list
     for an element greater than the current column number, and uses
     that element as the column to indent to.  It does nothing if no
     such element is found.

 -- User Option: tab-stop-list
     This variable is the list of tab stop columns used by
     `tab-to-tab-stops'.  The elements should be integers in increasing
     order.  The tab stop columns need not be evenly spaced.

     Use `M-x edit-tab-stops' to edit the location of tab stops
     interactively.


File: elisp,  Node: Motion by Indent,  Prev: Indent Tabs,  Up: Indentation

32.17.6 Indentation-Based Motion Commands
-----------------------------------------

These commands, primarily for interactive use, act based on the
indentation in the text.

 -- Command: back-to-indentation
     This command moves point to the first non-whitespace character in
     the current line (which is the line in which point is located).
     It returns `nil'.

 -- Command: backward-to-indentation &optional arg
     This command moves point backward ARG lines and then to the first
     nonblank character on that line.  It returns `nil'.  If ARG is
     omitted or `nil', it defaults to 1.

 -- Command: forward-to-indentation &optional arg
     This command moves point forward ARG lines and then to the first
     nonblank character on that line.  It returns `nil'.  If ARG is
     omitted or `nil', it defaults to 1.


File: elisp,  Node: Case Changes,  Next: Text Properties,  Prev: Indentation,  Up: Text

32.18 Case Changes
==================

The case change commands described here work on text in the current
buffer.  *Note Case Conversion::, for case conversion functions that
work on strings and characters.  *Note Case Tables::, for how to
customize which characters are upper or lower case and how to convert
them.

 -- Command: capitalize-region start end
     This function capitalizes all words in the region defined by START
     and END.  To capitalize means to convert each word's first
     character to upper case and convert the rest of each word to lower
     case.  The function returns `nil'.

     If one end of the region is in the middle of a word, the part of
     the word within the region is treated as an entire word.

     When `capitalize-region' is called interactively, START and END
     are point and the mark, with the smallest first.

          ---------- Buffer: foo ----------
          This is the contents of the 5th foo.
          ---------- Buffer: foo ----------

          (capitalize-region 1 44)
          => nil

          ---------- Buffer: foo ----------
          This Is The Contents Of The 5th Foo.
          ---------- Buffer: foo ----------

 -- Command: downcase-region start end
     This function converts all of the letters in the region defined by
     START and END to lower case.  The function returns `nil'.

     When `downcase-region' is called interactively, START and END are
     point and the mark, with the smallest first.

 -- Command: upcase-region start end
     This function converts all of the letters in the region defined by
     START and END to upper case.  The function returns `nil'.

     When `upcase-region' is called interactively, START and END are
     point and the mark, with the smallest first.

 -- Command: capitalize-word count
     This function capitalizes COUNT words after point, moving point
     over as it does.  To capitalize means to convert each word's first
     character to upper case and convert the rest of each word to lower
     case.  If COUNT is negative, the function capitalizes the -COUNT
     previous words but does not move point.  The value is `nil'.

     If point is in the middle of a word, the part of the word before
     point is ignored when moving forward.  The rest is treated as an
     entire word.

     When `capitalize-word' is called interactively, COUNT is set to
     the numeric prefix argument.

 -- Command: downcase-word count
     This function converts the COUNT words after point to all lower
     case, moving point over as it does.  If COUNT is negative, it
     converts the -COUNT previous words but does not move point.  The
     value is `nil'.

     When `downcase-word' is called interactively, COUNT is set to the
     numeric prefix argument.

 -- Command: upcase-word count
     This function converts the COUNT words after point to all upper
     case, moving point over as it does.  If COUNT is negative, it
     converts the -COUNT previous words but does not move point.  The
     value is `nil'.

     When `upcase-word' is called interactively, COUNT is set to the
     numeric prefix argument.


File: elisp,  Node: Text Properties,  Next: Substitution,  Prev: Case Changes,  Up: Text

32.19 Text Properties
=====================

Each character position in a buffer or a string can have a "text
property list", much like the property list of a symbol (*note Property
Lists::).  The properties belong to a particular character at a
particular place, such as, the letter `T' at the beginning of this
sentence or the first `o' in `foo'--if the same character occurs in two
different places, the two occurrences in general have different
properties.

   Each property has a name and a value.  Both of these can be any Lisp
object, but the name is normally a symbol.  Typically each property
name symbol is used for a particular purpose; for instance, the text
property `face' specifies the faces for displaying the character (*note
Special Properties::).  The usual way to access the property list is to
specify a name and ask what value corresponds to it.

   If a character has a `category' property, we call it the "property
category" of the character.  It should be a symbol.  The properties of
the symbol serve as defaults for the properties of the character.

   Copying text between strings and buffers preserves the properties
along with the characters; this includes such diverse functions as
`substring', `insert', and `buffer-substring'.

* Menu:

* Examining Properties::   Looking at the properties of one character.
* Changing Properties::	   Setting the properties of a range of text.
* Property Search::	   Searching for where a property changes value.
* Special Properties::	   Particular properties with special meanings.
* Format Properties::      Properties for representing formatting of text.
* Sticky Properties::      How inserted text gets properties from
                             neighboring text.
* Saving Properties::      Saving text properties in files, and reading
                             them back.
* Lazy Properties::        Computing text properties in a lazy fashion
                             only when text is examined.
* Clickable Text::         Using text properties to make regions of text
                             do something when you click on them.
* Links and Mouse-1::      How to make <Mouse-1> follow a link.
* Fields::                 The `field' property defines
                             fields within the buffer.
* Not Intervals::	   Why text properties do not use
			     Lisp-visible text intervals.


File: elisp,  Node: Examining Properties,  Next: Changing Properties,  Up: Text Properties

32.19.1 Examining Text Properties
---------------------------------

The simplest way to examine text properties is to ask for the value of
a particular property of a particular character.  For that, use
`get-text-property'.  Use `text-properties-at' to get the entire
property list of a character.  *Note Property Search::, for functions
to examine the properties of a number of characters at once.

   These functions handle both strings and buffers.  Keep in mind that
positions in a string start from 0, whereas positions in a buffer start
from 1.

 -- Function: get-text-property pos prop &optional object
     This function returns the value of the PROP property of the
     character after position POS in OBJECT (a buffer or string).  The
     argument OBJECT is optional and defaults to the current buffer.

     If there is no PROP property strictly speaking, but the character
     has a property category that is a symbol, then `get-text-property'
     returns the PROP property of that symbol.

 -- Function: get-char-property position prop &optional object
     This function is like `get-text-property', except that it checks
     overlays first and then text properties.  *Note Overlays::.

     The argument OBJECT may be a string, a buffer, or a window.  If it
     is a window, then the buffer displayed in that window is used for
     text properties and overlays, but only the overlays active for that
     window are considered.  If OBJECT is a buffer, then overlays in
     that buffer are considered first, in order of decreasing priority,
     followed by the text properties.  If OBJECT is a string, only text
     properties are considered, since strings never have overlays.

 -- Function: get-char-property-and-overlay position prop &optional
          object
     This is like `get-char-property', but gives extra information
     about the overlay that the property value comes from.

     Its value is a cons cell whose CAR is the property value, the same
     value `get-char-property' would return with the same arguments.
     Its CDR is the overlay in which the property was found, or `nil',
     if it was found as a text property or not found at all.

     If POSITION is at the end of OBJECT, both the CAR and the CDR of
     the value are `nil'.

 -- Variable: char-property-alias-alist
     This variable holds an alist which maps property names to a list of
     alternative property names.  If a character does not specify a
     direct value for a property, the alternative property names are
     consulted in order; the first non-`nil' value is used.  This
     variable takes precedence over `default-text-properties', and
     `category' properties take precedence over this variable.

 -- Function: text-properties-at position &optional object
     This function returns the entire property list of the character at
     POSITION in the string or buffer OBJECT.  If OBJECT is `nil', it
     defaults to the current buffer.

 -- Variable: default-text-properties
     This variable holds a property list giving default values for text
     properties.  Whenever a character does not specify a value for a
     property, neither directly, through a category symbol, or through
     `char-property-alias-alist', the value stored in this list is used
     instead.  Here is an example:

          (setq default-text-properties '(foo 69)
                char-property-alias-alist nil)
          ;; Make sure character 1 has no properties of its own.
          (set-text-properties 1 2 nil)
          ;; What we get, when we ask, is the default value.
          (get-text-property 1 'foo)
               => 69


File: elisp,  Node: Changing Properties,  Next: Property Search,  Prev: Examining Properties,  Up: Text Properties

32.19.2 Changing Text Properties
--------------------------------

The primitives for changing properties apply to a specified range of
text in a buffer or string.  The function `set-text-properties' (see
end of section) sets the entire property list of the text in that
range; more often, it is useful to add, change, or delete just certain
properties specified by name.

   Since text properties are considered part of the contents of the
buffer (or string), and can affect how a buffer looks on the screen,
any change in buffer text properties marks the buffer as modified.
Buffer text property changes are undoable also (*note Undo::).
Positions in a string start from 0, whereas positions in a buffer start
from 1.

 -- Function: put-text-property start end prop value &optional object
     This function sets the PROP property to VALUE for the text between
     START and END in the string or buffer OBJECT.  If OBJECT is `nil',
     it defaults to the current buffer.

 -- Function: add-text-properties start end props &optional object
     This function adds or overrides text properties for the text
     between START and END in the string or buffer OBJECT.  If OBJECT
     is `nil', it defaults to the current buffer.

     The argument PROPS specifies which properties to add.  It should
     have the form of a property list (*note Property Lists::): a list
     whose elements include the property names followed alternately by
     the corresponding values.

     The return value is `t' if the function actually changed some
     property's value; `nil' otherwise (if PROPS is `nil' or its values
     agree with those in the text).

     For example, here is how to set the `comment' and `face'
     properties of a range of text:

          (add-text-properties START END
                               '(comment t face highlight))

 -- Function: remove-text-properties start end props &optional object
     This function deletes specified text properties from the text
     between START and END in the string or buffer OBJECT.  If OBJECT
     is `nil', it defaults to the current buffer.

     The argument PROPS specifies which properties to delete.  It
     should have the form of a property list (*note Property Lists::):
     a list whose elements are property names alternating with
     corresponding values.  But only the names matter--the values that
     accompany them are ignored.  For example, here's how to remove the
     `face' property.

          (remove-text-properties START END '(face nil))

     The return value is `t' if the function actually changed some
     property's value; `nil' otherwise (if PROPS is `nil' or if no
     character in the specified text had any of those properties).

     To remove all text properties from certain text, use
     `set-text-properties' and specify `nil' for the new property list.

 -- Function: remove-list-of-text-properties start end
          list-of-properties &optional object
     Like `remove-text-properties' except that LIST-OF-PROPERTIES is a
     list of property names only, not an alternating list of property
     names and values.

 -- Function: set-text-properties start end props &optional object
     This function completely replaces the text property list for the
     text between START and END in the string or buffer OBJECT.  If
     OBJECT is `nil', it defaults to the current buffer.

     The argument PROPS is the new property list.  It should be a list
     whose elements are property names alternating with corresponding
     values.

     After `set-text-properties' returns, all the characters in the
     specified range have identical properties.

     If PROPS is `nil', the effect is to get rid of all properties from
     the specified range of text.  Here's an example:

          (set-text-properties START END nil)

     Do not rely on the return value of this function.

   The easiest way to make a string with text properties is with
`propertize':

 -- Function: propertize string &rest properties
     This function returns a copy of STRING which has the text
     properties PROPERTIES.  These properties apply to all the
     characters in the string that is returned.  Here is an example that
     constructs a string with a `face' property and a `mouse-face'
     property:

          (propertize "foo" 'face 'italic
                      'mouse-face 'bold-italic)
               => #("foo" 0 3 (mouse-face bold-italic face italic))

     To put different properties on various parts of a string, you can
     construct each part with `propertize' and then combine them with
     `concat':

          (concat
           (propertize "foo" 'face 'italic
                       'mouse-face 'bold-italic)
           " and "
           (propertize "bar" 'face 'italic
                       'mouse-face 'bold-italic))
               => #("foo and bar"
                           0 3 (face italic mouse-face bold-italic)
                           3 8 nil
                           8 11 (face italic mouse-face bold-italic))

   See also the function `buffer-substring-no-properties' (*note Buffer
Contents::) which copies text from the buffer but does not copy its
properties.


File: elisp,  Node: Property Search,  Next: Special Properties,  Prev: Changing Properties,  Up: Text Properties

32.19.3 Text Property Search Functions
--------------------------------------

In typical use of text properties, most of the time several or many
consecutive characters have the same value for a property.  Rather than
writing your programs to examine characters one by one, it is much
faster to process chunks of text that have the same property value.

   Here are functions you can use to do this.  They use `eq' for
comparing property values.  In all cases, OBJECT defaults to the
current buffer.

   For high performance, it's very important to use the LIMIT argument
to these functions, especially the ones that search for a single
property--otherwise, they may spend a long time scanning to the end of
the buffer, if the property you are interested in does not change.

   These functions do not move point; instead, they return a position
(or `nil').  Remember that a position is always between two characters;
the position returned by these functions is between two characters with
different properties.

 -- Function: next-property-change pos &optional object limit
     The function scans the text forward from position POS in the
     string or buffer OBJECT till it finds a change in some text
     property, then returns the position of the change.  In other
     words, it returns the position of the first character beyond POS
     whose properties are not identical to those of the character just
     after POS.

     If LIMIT is non-`nil', then the scan ends at position LIMIT.  If
     there is no property change before that point,
     `next-property-change' returns LIMIT.

     The value is `nil' if the properties remain unchanged all the way
     to the end of OBJECT and LIMIT is `nil'.  If the value is
     non-`nil', it is a position greater than or equal to POS.  The
     value equals POS only when LIMIT equals POS.

     Here is an example of how to scan the buffer by chunks of text
     within which all properties are constant:

          (while (not (eobp))
            (let ((plist (text-properties-at (point)))
                  (next-change
                   (or (next-property-change (point) (current-buffer))
                       (point-max))))
              Process text from point to NEXT-CHANGE...
              (goto-char next-change)))

 -- Function: previous-property-change pos &optional object limit
     This is like `next-property-change', but scans back from POS
     instead of forward.  If the value is non-`nil', it is a position
     less than or equal to POS; it equals POS only if LIMIT equals POS.

 -- Function: next-single-property-change pos prop &optional object
          limit
     The function scans text for a change in the PROP property, then
     returns the position of the change.  The scan goes forward from
     position POS in the string or buffer OBJECT.  In other words, this
     function returns the position of the first character beyond POS
     whose PROP property differs from that of the character just after
     POS.

     If LIMIT is non-`nil', then the scan ends at position LIMIT.  If
     there is no property change before that point,
     `next-single-property-change' returns LIMIT.

     The value is `nil' if the property remains unchanged all the way to
     the end of OBJECT and LIMIT is `nil'.  If the value is non-`nil',
     it is a position greater than or equal to POS; it equals POS only
     if LIMIT equals POS.

 -- Function: previous-single-property-change pos prop &optional object
          limit
     This is like `next-single-property-change', but scans back from
     POS instead of forward.  If the value is non-`nil', it is a
     position less than or equal to POS; it equals POS only if LIMIT
     equals POS.

 -- Function: next-char-property-change pos &optional limit
     This is like `next-property-change' except that it considers
     overlay properties as well as text properties, and if no change is
     found before the end of the buffer, it returns the maximum buffer
     position rather than `nil' (in this sense, it resembles the
     corresponding overlay function `next-overlay-change', rather than
     `next-property-change').  There is no OBJECT operand because this
     function operates only on the current buffer.  It returns the next
     address at which either kind of property changes.

 -- Function: previous-char-property-change pos &optional limit
     This is like `next-char-property-change', but scans back from POS
     instead of forward, and returns the minimum buffer position if no
     change is found.

 -- Function: next-single-char-property-change pos prop &optional
          object limit
     This is like `next-single-property-change' except that it
     considers overlay properties as well as text properties, and if no
     change is found before the end of the OBJECT, it returns the
     maximum valid position in OBJECT rather than `nil'.  Unlike
     `next-char-property-change', this function _does_ have an OBJECT
     operand; if OBJECT is not a buffer, only text-properties are
     considered.

 -- Function: previous-single-char-property-change pos prop &optional
          object limit
     This is like `next-single-char-property-change', but scans back
     from POS instead of forward, and returns the minimum valid
     position in OBJECT if no change is found.

 -- Function: text-property-any start end prop value &optional object
     This function returns non-`nil' if at least one character between
     START and END has a property PROP whose value is VALUE.  More
     precisely, it returns the position of the first such character.
     Otherwise, it returns `nil'.

     The optional fifth argument, OBJECT, specifies the string or
     buffer to scan.  Positions are relative to OBJECT.  The default
     for OBJECT is the current buffer.

 -- Function: text-property-not-all start end prop value &optional
          object
     This function returns non-`nil' if at least one character between
     START and END does not have a property PROP with value VALUE.
     More precisely, it returns the position of the first such
     character.  Otherwise, it returns `nil'.

     The optional fifth argument, OBJECT, specifies the string or
     buffer to scan.  Positions are relative to OBJECT.  The default
     for OBJECT is the current buffer.


File: elisp,  Node: Special Properties,  Next: Format Properties,  Prev: Property Search,  Up: Text Properties

32.19.4 Properties with Special Meanings
----------------------------------------

Here is a table of text property names that have special built-in
meanings.  The following sections list a few additional special property
names that control filling and property inheritance.  All other names
have no standard meaning, and you can use them as you like.

   Note: the properties `composition', `display', `invisible' and
`intangible' can also cause point to move to an acceptable place, after
each Emacs command.  *Note Adjusting Point::.

`category'
     If a character has a `category' property, we call it the "property
     category" of the character.  It should be a symbol.  The
     properties of this symbol serve as defaults for the properties of
     the character.

`face'
     You can use the property `face' to control the font and color of
     text.  *Note Faces::, for more information.

     In the simplest case, the value is a face name.  It can also be a
     list; then each element can be any of these possibilities;

        * A face name (a symbol or string).

        * A property list of face attributes.  This has the form
          (KEYWORD VALUE ...), where each KEYWORD is a face attribute
          name and VALUE is a meaningful value for that attribute.
          With this feature, you do not need to create a face each time
          you want to specify a particular attribute for certain text.
          *Note Face Attributes::.

        * A cons cell with the form `(foreground-color . COLOR-NAME)'
          or `(background-color . COLOR-NAME)'.  These are older,
          deprecated equivalents for `(:foreground COLOR-NAME)' and
          `(:background COLOR-NAME)'.  Please convert code that uses
          them.

     It works to use the latter two forms directly as the value of the
     `face' property.

     Font Lock mode (*note Font Lock Mode::) works in most buffers by
     dynamically updating the `face' property of characters based on
     the context.

`font-lock-face'
     The `font-lock-face' property is equivalent to the `face' property
     when Font Lock mode is enabled.  When Font Lock mode is disabled,
     `font-lock-face' has no effect.

     The `font-lock-mode' property is useful for special modes that
     implement their own highlighting.  *Note Precalculated
     Fontification::.

     This property is new in Emacs 22.1.

`mouse-face'
     The property `mouse-face' is used instead of `face' when the mouse
     is on or near the character.  For this purpose, "near" means that
     all text between the character and where the mouse is have the same
     `mouse-face' property value.

`fontified'
     This property says whether the text is ready for display.  If
     `nil', Emacs's redisplay routine calls the functions in
     `fontification-functions' (*note Auto Faces::) to prepare this
     part of the buffer before it is displayed.  It is used internally
     by the "just in time" font locking code.

`display'
     This property activates various features that change the way text
     is displayed.  For example, it can make text appear taller or
     shorter, higher or lower, wider or narrow, or replaced with an
     image.  *Note Display Property::.

`help-echo'
     If text has a string as its `help-echo' property, then when you
     move the mouse onto that text, Emacs displays that string in the
     echo area, or in the tooltip window (*note Tooltips:
     (emacs)Tooltips.).

     If the value of the `help-echo' property is a function, that
     function is called with three arguments, WINDOW, OBJECT and POS
     and should return a help string or `nil' for none.  The first
     argument, WINDOW is the window in which the help was found.  The
     second, OBJECT, is the buffer, overlay or string which had the
     `help-echo' property.  The POS argument is as follows:

        * If OBJECT is a buffer, POS is the position in the buffer.

        * If OBJECT is an overlay, that overlay has a `help-echo'
          property, and POS is the position in the overlay's buffer.

        * If OBJECT is a string (an overlay string or a string displayed
          with the `display' property), POS is the position in that
          string.

     If the value of the `help-echo' property is neither a function nor
     a string, it is evaluated to obtain a help string.

     You can alter the way help text is displayed by setting the
     variable `show-help-function' (*note Help display::).

     This feature is used in the mode line and for other active text.

`keymap'
     The `keymap' property specifies an additional keymap for commands.
     When this keymap applies, it is used for key lookup before the
     minor mode keymaps and before the buffer's local map.  *Note
     Active Keymaps::.  If the property value is a symbol, the symbol's
     function definition is used as the keymap.

     The property's value for the character before point applies if it
     is non-`nil' and rear-sticky, and the property's value for the
     character after point applies if it is non-`nil' and front-sticky.
     (For mouse clicks, the position of the click is used instead of
     the position of point.)

`local-map'
     This property works like `keymap' except that it specifies a
     keymap to use _instead of_ the buffer's local map.  For most
     purposes (perhaps all purposes), it is better to use the `keymap'
     property.

`syntax-table'
     The `syntax-table' property overrides what the syntax table says
     about this particular character.  *Note Syntax Properties::.

`read-only'
     If a character has the property `read-only', then modifying that
     character is not allowed.  Any command that would do so gets an
     error, `text-read-only'.  If the property value is a string, that
     string is used as the error message.

     Insertion next to a read-only character is an error if inserting
     ordinary text there would inherit the `read-only' property due to
     stickiness.  Thus, you can control permission to insert next to
     read-only text by controlling the stickiness.  *Note Sticky
     Properties::.

     Since changing properties counts as modifying the buffer, it is not
     possible to remove a `read-only' property unless you know the
     special trick: bind `inhibit-read-only' to a non-`nil' value and
     then remove the property.  *Note Read Only Buffers::.

`invisible'
     A non-`nil' `invisible' property can make a character invisible on
     the screen.  *Note Invisible Text::, for details.

`intangible'
     If a group of consecutive characters have equal and non-`nil'
     `intangible' properties, then you cannot place point between them.
     If you try to move point forward into the group, point actually
     moves to the end of the group.  If you try to move point backward
     into the group, point actually moves to the start of the group.

     If consecutive characters have unequal non-`nil' `intangible'
     properties, they belong to separate groups; each group is
     separately treated as described above.

     When the variable `inhibit-point-motion-hooks' is non-`nil', the
     `intangible' property is ignored.

`field'
     Consecutive characters with the same `field' property constitute a
     "field".  Some motion functions including `forward-word' and
     `beginning-of-line' stop moving at a field boundary.  *Note
     Fields::.

`cursor'
     Normally, the cursor is displayed at the end of any overlay and
     text property strings present at the current window position.  You
     can place the cursor on any desired character of these strings by
     giving that character a non-`nil' CURSOR text property.

`pointer'
     This specifies a specific pointer shape when the mouse pointer is
     over this text or image.  *Note Pointer Shape::, for possible
     pointer shapes.

`line-spacing'
     A newline can have a `line-spacing' text or overlay property that
     controls the height of the display line ending with that newline.
     The property value overrides the default frame line spacing and
     the buffer local `line-spacing' variable.  *Note Line Height::.

`line-height'
     A newline can have a `line-height' text or overlay property that
     controls the total height of the display line ending in that
     newline.  *Note Line Height::.

`modification-hooks'
     If a character has the property `modification-hooks', then its
     value should be a list of functions; modifying that character
     calls all of those functions.  Each function receives two
     arguments: the beginning and end of the part of the buffer being
     modified.  Note that if a particular modification hook function
     appears on several characters being modified by a single
     primitive, you can't predict how many times the function will be
     called.

     If these functions modify the buffer, they should bind
     `inhibit-modification-hooks' to `t' around doing so, to avoid
     confusing the internal mechanism that calls these hooks.

     Overlays also support the `modification-hooks' property, but the
     details are somewhat different (*note Overlay Properties::).

`insert-in-front-hooks'
`insert-behind-hooks'
     The operation of inserting text in a buffer also calls the
     functions listed in the `insert-in-front-hooks' property of the
     following character and in the `insert-behind-hooks' property of
     the preceding character.  These functions receive two arguments,
     the beginning and end of the inserted text.  The functions are
     called _after_ the actual insertion takes place.

     See also *note Change Hooks::, for other hooks that are called
     when you change text in a buffer.

`point-entered'
`point-left'
     The special properties `point-entered' and `point-left' record
     hook functions that report motion of point.  Each time point
     moves, Emacs compares these two property values:

        * the `point-left' property of the character after the old
          location, and

        * the `point-entered' property of the character after the new
          location.

     If these two values differ, each of them is called (if not `nil')
     with two arguments: the old value of point, and the new one.

     The same comparison is made for the characters before the old and
     new locations.  The result may be to execute two `point-left'
     functions (which may be the same function) and/or two
     `point-entered' functions (which may be the same function).  In
     any case, all the `point-left' functions are called first,
     followed by all the `point-entered' functions.

     It is possible with `char-after' to examine characters at various
     buffer positions without moving point to those positions.  Only an
     actual change in the value of point runs these hook functions.

      -- Variable: inhibit-point-motion-hooks
          When this variable is non-`nil', `point-left' and
          `point-entered' hooks are not run, and the `intangible'
          property has no effect.  Do not set this variable globally;
          bind it with `let'.

      -- Variable: show-help-function
          If this variable is non-`nil', it specifies a function called
          to display help strings.  These may be `help-echo'
          properties, menu help strings (*note Simple Menu Items::,
          *note Extended Menu Items::), or tool bar help strings (*note
          Tool Bar::).  The specified function is called with one
          argument, the help string to display.  Tooltip mode (*note
          Tooltips: (emacs)Tooltips.) provides an example.

`composition'
     This text property is used to display a sequence of characters as a
     single glyph composed from components.  For instance, in Thai a
     base consonant is composed with the following combining vowel as a
     single glyph.  The value should be a character or a sequence
     (vector, list, or string) of integers.

        * If it is a character, it means to display that character
          instead of the text in the region.

        * If it is a string, it means to display that string's contents
          instead of the text in the region.

        * If it is a vector or list, the elements are characters
          interleaved with internal codes specifying how to compose the
          following character with the previous one.


File: elisp,  Node: Format Properties,  Next: Sticky Properties,  Prev: Special Properties,  Up: Text Properties

32.19.5 Formatted Text Properties
---------------------------------

These text properties affect the behavior of the fill commands.  They
are used for representing formatted text.  *Note Filling::, and *note
Margins::.

`hard'
     If a newline character has this property, it is a "hard" newline.
     The fill commands do not alter hard newlines and do not move words
     across them.  However, this property takes effect only if the
     `use-hard-newlines' minor mode is enabled.  *Note Hard and Soft
     Newlines: (emacs)Hard and Soft Newlines.

`right-margin'
     This property specifies an extra right margin for filling this
     part of the text.

`left-margin'
     This property specifies an extra left margin for filling this part
     of the text.

`justification'
     This property specifies the style of justification for filling
     this part of the text.


File: elisp,  Node: Sticky Properties,  Next: Saving Properties,  Prev: Format Properties,  Up: Text Properties

32.19.6 Stickiness of Text Properties
-------------------------------------

Self-inserting characters normally take on the same properties as the
preceding character.  This is called "inheritance" of properties.

   In a Lisp program, you can do insertion with inheritance or without,
depending on your choice of insertion primitive.  The ordinary text
insertion functions such as `insert' do not inherit any properties.
They insert text with precisely the properties of the string being
inserted, and no others.  This is correct for programs that copy text
from one context to another--for example, into or out of the kill ring.
To insert with inheritance, use the special primitives described in this
section.  Self-inserting characters inherit properties because they work
using these primitives.

   When you do insertion with inheritance, _which_ properties are
inherited, and from where, depends on which properties are "sticky".
Insertion after a character inherits those of its properties that are
"rear-sticky".  Insertion before a character inherits those of its
properties that are "front-sticky".  When both sides offer different
sticky values for the same property, the previous character's value
takes precedence.

   By default, a text property is rear-sticky but not front-sticky;
thus, the default is to inherit all the properties of the preceding
character, and nothing from the following character.

   You can control the stickiness of various text properties with two
specific text properties, `front-sticky' and `rear-nonsticky', and with
the variable `text-property-default-nonsticky'.  You can use the
variable to specify a different default for a given property.  You can
use those two text properties to make any specific properties sticky or
nonsticky in any particular part of the text.

   If a character's `front-sticky' property is `t', then all its
properties are front-sticky.  If the `front-sticky' property is a list,
then the sticky properties of the character are those whose names are
in the list.  For example, if a character has a `front-sticky' property
whose value is `(face read-only)', then insertion before the character
can inherit its `face' property and its `read-only' property, but no
others.

   The `rear-nonsticky' property works the opposite way.  Most
properties are rear-sticky by default, so the `rear-nonsticky' property
says which properties are _not_ rear-sticky.  If a character's
`rear-nonsticky' property is `t', then none of its properties are
rear-sticky.  If the `rear-nonsticky' property is a list, properties
are rear-sticky _unless_ their names are in the list.

 -- Variable: text-property-default-nonsticky
     This variable holds an alist which defines the default
     rear-stickiness of various text properties.  Each element has the
     form `(PROPERTY . NONSTICKINESS)', and it defines the stickiness
     of a particular text property, PROPERTY.

     If NONSTICKINESS is non-`nil', this means that the property
     PROPERTY is rear-nonsticky by default.  Since all properties are
     front-nonsticky by default, this makes PROPERTY nonsticky in both
     directions by default.

     The text properties `front-sticky' and `rear-nonsticky', when
     used, take precedence over the default NONSTICKINESS specified in
     `text-property-default-nonsticky'.

   Here are the functions that insert text with inheritance of
properties:

 -- Function: insert-and-inherit &rest strings
     Insert the strings STRINGS, just like the function `insert', but
     inherit any sticky properties from the adjoining text.

 -- Function: insert-before-markers-and-inherit &rest strings
     Insert the strings STRINGS, just like the function
     `insert-before-markers', but inherit any sticky properties from the
     adjoining text.

   *Note Insertion::, for the ordinary insertion functions which do not
inherit.


File: elisp,  Node: Saving Properties,  Next: Lazy Properties,  Prev: Sticky Properties,  Up: Text Properties

32.19.7 Saving Text Properties in Files
---------------------------------------

You can save text properties in files (along with the text itself), and
restore the same text properties when visiting or inserting the files,
using these two hooks:

 -- Variable: write-region-annotate-functions
     This variable's value is a list of functions for `write-region' to
     run to encode text properties in some fashion as annotations to
     the text being written in the file.  *Note Writing to Files::.

     Each function in the list is called with two arguments: the start
     and end of the region to be written.  These functions should not
     alter the contents of the buffer.  Instead, they should return
     lists indicating annotations to write in the file in addition to
     the text in the buffer.

     Each function should return a list of elements of the form
     `(POSITION . STRING)', where POSITION is an integer specifying the
     relative position within the text to be written, and STRING is the
     annotation to add there.

     Each list returned by one of these functions must be already
     sorted in increasing order by POSITION.  If there is more than one
     function, `write-region' merges the lists destructively into one
     sorted list.

     When `write-region' actually writes the text from the buffer to the
     file, it intermixes the specified annotations at the corresponding
     positions.  All this takes place without modifying the buffer.

 -- Variable: after-insert-file-functions
     This variable holds a list of functions for `insert-file-contents'
     to call after inserting a file's contents.  These functions should
     scan the inserted text for annotations, and convert them to the
     text properties they stand for.

     Each function receives one argument, the length of the inserted
     text; point indicates the start of that text.  The function should
     scan that text for annotations, delete them, and create the text
     properties that the annotations specify.  The function should
     return the updated length of the inserted text, as it stands after
     those changes.  The value returned by one function becomes the
     argument to the next function.

     These functions should always return with point at the beginning of
     the inserted text.

     The intended use of `after-insert-file-functions' is for converting
     some sort of textual annotations into actual text properties.  But
     other uses may be possible.

   We invite users to write Lisp programs to store and retrieve text
properties in files, using these hooks, and thus to experiment with
various data formats and find good ones.  Eventually we hope users will
produce good, general extensions we can install in Emacs.

   We suggest not trying to handle arbitrary Lisp objects as text
property names or values--because a program that general is probably
difficult to write, and slow.  Instead, choose a set of possible data
types that are reasonably flexible, and not too hard to encode.

   *Note Format Conversion::, for a related feature.


File: elisp,  Node: Lazy Properties,  Next: Clickable Text,  Prev: Saving Properties,  Up: Text Properties

32.19.8 Lazy Computation of Text Properties
-------------------------------------------

Instead of computing text properties for all the text in the buffer,
you can arrange to compute the text properties for parts of the text
when and if something depends on them.

   The primitive that extracts text from the buffer along with its
properties is `buffer-substring'.  Before examining the properties,
this function runs the abnormal hook `buffer-access-fontify-functions'.

 -- Variable: buffer-access-fontify-functions
     This variable holds a list of functions for computing text
     properties.  Before `buffer-substring' copies the text and text
     properties for a portion of the buffer, it calls all the functions
     in this list.  Each of the functions receives two arguments that
     specify the range of the buffer being accessed.  (The buffer
     itself is always the current buffer.)

   The function `buffer-substring-no-properties' does not call these
functions, since it ignores text properties anyway.

   In order to prevent the hook functions from being called more than
once for the same part of the buffer, you can use the variable
`buffer-access-fontified-property'.

 -- Variable: buffer-access-fontified-property
     If this variable's value is non-`nil', it is a symbol which is used
     as a text property name.  A non-`nil' value for that text property
     means, "the other text properties for this character have already
     been computed."

     If all the characters in the range specified for `buffer-substring'
     have a non-`nil' value for this property, `buffer-substring' does
     not call the `buffer-access-fontify-functions' functions.  It
     assumes these characters already have the right text properties,
     and just copies the properties they already have.

     The normal way to use this feature is that the
     `buffer-access-fontify-functions' functions add this property, as
     well as others, to the characters they operate on.  That way, they
     avoid being called over and over for the same text.


File: elisp,  Node: Clickable Text,  Next: Links and Mouse-1,  Prev: Lazy Properties,  Up: Text Properties

32.19.9 Defining Clickable Text
-------------------------------

"Clickable text" is text that can be clicked, with either the the mouse
or via keyboard commands, to produce some result.  Many major modes use
clickable text to implement features such as hyper-links.  The `button'
package provides an easy way to insert and manipulate clickable text.
*Note Buttons::.

   In this section, we will explain how to manually set up clickable
text in a buffer using text properties.  This involves two things: (1)
indicating clickability when the mouse moves over the text, and (2)
making `RET' or a mouse click on that text do something.

   Indicating clickability usually involves highlighting the text, and
often involves displaying helpful information about the action, such as
which mouse button to press, or a short summary of the action.  This
can be done with the `mouse-face' and `help-echo' text properties.
*Note Special Properties::.  Here is an example of how Dired does it:

     (condition-case nil
         (if (dired-move-to-filename)
             (add-text-properties
              (point)
              (save-excursion
                (dired-move-to-end-of-filename)
                (point))
              '(mouse-face highlight
                help-echo "mouse-2: visit this file in other window")))
       (error nil))

The first two arguments to `add-text-properties' specify the beginning
and end of the text.

   The usual way to make the mouse do something when you click it on
this text is to define `mouse-2' in the major mode's keymap.  The job
of checking whether the click was on clickable text is done by the
command definition.  Here is how Dired does it:

     (defun dired-mouse-find-file-other-window (event)
       "In Dired, visit the file or directory name you click on."
       (interactive "e")
       (let (window pos file)
         (save-excursion
           (setq window (posn-window (event-end event))
                 pos (posn-point (event-end event)))
           (if (not (windowp window))
               (error "No file chosen"))
           (set-buffer (window-buffer window))
           (goto-char pos)
           (setq file (dired-get-file-for-visit)))
         (if (file-directory-p file)
             (or (and (cdr dired-subdir-alist)
                      (dired-goto-subdir file))
                 (progn
                   (select-window window)
                   (dired-other-window file)))
           (select-window window)
           (find-file-other-window (file-name-sans-versions file t)))))

The reason for the `save-excursion' construct is to avoid changing the
current buffer.  In this case, Dired uses the functions `posn-window'
and `posn-point' to determine which buffer the click happened in and
where, and in that buffer, `dired-get-file-for-visit' to determine which
file to visit.

   Instead of defining a mouse command for the major mode, you can
define a key binding for the clickable text itself, using the `keymap'
text property:

     (let ((map (make-sparse-keymap)))
       (define-key map [mouse-2] 'operate-this-button)
       (put-text-property (point)
                          (save-excursion
                            (dired-move-to-end-of-filename)
                            (point))
                          'keymap map))

This method makes it possible to define different commands for various
clickable pieces of text.  Also, the major mode definition (or the
global definition) remains available for the rest of the text in the
buffer.


File: elisp,  Node: Links and Mouse-1,  Next: Fields,  Prev: Clickable Text,  Up: Text Properties

32.19.10 Links and Mouse-1
--------------------------

The normal Emacs command for activating text in read-only buffers is
<Mouse-2>, which includes following textual links.  However, most
graphical applications use <Mouse-1> for following links.  For
compatibility, <Mouse-1> follows links in Emacs too, when you click on
a link quickly without moving the mouse.  The user can customize this
behavior through the variable `mouse-1-click-follows-link'.

   To define text as a link at the Lisp level, you should bind the
`mouse-2' event to a command to follow the link.  Then, to indicate that
<Mouse-1> should also follow the link, you should specify a
`follow-link' condition either as a text property or as a key binding:

`follow-link' property
     If the clickable text has a non-`nil' `follow-link' text or overlay
     property, that specifies the condition.

`follow-link' event
     If there is a binding for the `follow-link' event, either on the
     clickable text or in the local keymap, the binding is the
     condition.

   Regardless of how you set the `follow-link' condition, its value is
used as follows to determine whether the given position is inside a
link, and (if so) to compute an "action code" saying how <Mouse-1>
should handle the link.

`mouse-face'
     If the condition is `mouse-face', a position is inside a link if
     there is a non-`nil' `mouse-face' property at that position.  The
     action code is always `t'.

     For example, here is how Info mode handles <Mouse-1>:

          (define-key Info-mode-map [follow-link] 'mouse-face)

a function
     If the condition is a valid function, FUNC, then a position POS is
     inside a link if `(FUNC POS)' evaluates to non-`nil'.  The value
     returned by FUNC serves as the action code.

     For example, here is how pcvs enables <Mouse-1> to follow links on
     file names only:

          (define-key map [follow-link]
            (lambda (pos)
              (eq (get-char-property pos 'face) 'cvs-filename-face)))

anything else
     If the condition value is anything else, then the position is
     inside a link and the condition itself is the action code.
     Clearly you should only specify this kind of condition on the text
     that constitutes a link.

The action code tells <Mouse-1> how to follow the link:

a string or vector
     If the action code is a string or vector, the <Mouse-1> event is
     translated into the first element of the string or vector; i.e.,
     the action of the <Mouse-1> click is the local or global binding of
     that character or symbol.  Thus, if the action code is `"foo"',
     <Mouse-1> translates into `f'.  If it is `[foo]', <Mouse-1>
     translates into <foo>.

anything else
     For any other non-`nil' action code, the `mouse-1' event is
     translated into a `mouse-2' event at the same position.

   To define <Mouse-1> to activate a button defined with
`define-button-type', give the button a `follow-link' property with a
value as specified above to determine how to follow the link.  For
example, here is how Help mode handles <Mouse-1>:

     (define-button-type 'help-xref
       'follow-link t
       'action #'help-button-action)

   To define <Mouse-1> on a widget defined with `define-widget', give
the widget a `:follow-link' property with a value as specified above to
determine how to follow the link.

   For example, here is how the `link' widget specifies that a
<Mouse-1> click shall be translated to <RET>:

     (define-widget 'link 'item
       "An embedded link."
       :button-prefix 'widget-link-prefix
       :button-suffix 'widget-link-suffix
       :follow-link "\C-m"
       :help-echo "Follow the link."
       :format "%[%t%]")

 -- Function: mouse-on-link-p pos
     This function returns non-`nil' if position POS in the current
     buffer is on a link.  POS can also be a mouse event location, as
     returned by `event-start' (*note Accessing Mouse::).


File: elisp,  Node: Fields,  Next: Not Intervals,  Prev: Links and Mouse-1,  Up: Text Properties

32.19.11 Defining and Using Fields
----------------------------------

A field is a range of consecutive characters in the buffer that are
identified by having the same value (comparing with `eq') of the
`field' property (either a text-property or an overlay property).  This
section describes special functions that are available for operating on
fields.

   You specify a field with a buffer position, POS.  We think of each
field as containing a range of buffer positions, so the position you
specify stands for the field containing that position.

   When the characters before and after POS are part of the same field,
there is no doubt which field contains POS: the one those characters
both belong to.  When POS is at a boundary between fields, which field
it belongs to depends on the stickiness of the `field' properties of
the two surrounding characters (*note Sticky Properties::).  The field
whose property would be inherited by text inserted at POS is the field
that contains POS.

   There is an anomalous case where newly inserted text at POS would
not inherit the `field' property from either side.  This happens if the
previous character's `field' property is not rear-sticky, and the
following character's `field' property is not front-sticky.  In this
case, POS belongs to neither the preceding field nor the following
field; the field functions treat it as belonging to an empty field
whose beginning and end are both at POS.

   In all of these functions, if POS is omitted or `nil', the value of
point is used by default.  If narrowing is in effect, then POS should
fall within the accessible portion.  *Note Narrowing::.

 -- Function: field-beginning &optional pos escape-from-edge limit
     This function returns the beginning of the field specified by POS.

     If POS is at the beginning of its field, and ESCAPE-FROM-EDGE is
     non-`nil', then the return value is always the beginning of the
     preceding field that _ends_ at POS, regardless of the stickiness
     of the `field' properties around POS.

     If LIMIT is non-`nil', it is a buffer position; if the beginning
     of the field is before LIMIT, then LIMIT will be returned instead.

 -- Function: field-end &optional pos escape-from-edge limit
     This function returns the end of the field specified by POS.

     If POS is at the end of its field, and ESCAPE-FROM-EDGE is
     non-`nil', then the return value is always the end of the following
     field that _begins_ at POS, regardless of the stickiness of the
     `field' properties around POS.

     If LIMIT is non-`nil', it is a buffer position; if the end of the
     field is after LIMIT, then LIMIT will be returned instead.

 -- Function: field-string &optional pos
     This function returns the contents of the field specified by POS,
     as a string.

 -- Function: field-string-no-properties &optional pos
     This function returns the contents of the field specified by POS,
     as a string, discarding text properties.

 -- Function: delete-field &optional pos
     This function deletes the text of the field specified by POS.

 -- Function: constrain-to-field new-pos old-pos &optional
          escape-from-edge only-in-line inhibit-capture-property
     This function "constrains" NEW-POS to the field that OLD-POS
     belongs to--in other words, it returns the position closest to
     NEW-POS that is in the same field as OLD-POS.

     If NEW-POS is `nil', then `constrain-to-field' uses the value of
     point instead, and moves point to the resulting position as well
     as returning it.

     If OLD-POS is at the boundary of two fields, then the acceptable
     final positions depend on the argument ESCAPE-FROM-EDGE.  If
     ESCAPE-FROM-EDGE is `nil', then NEW-POS must be in the field whose
     `field' property equals what new characters inserted at OLD-POS
     would inherit.  (This depends on the stickiness of the `field'
     property for the characters before and after OLD-POS.)  If
     ESCAPE-FROM-EDGE is non-`nil', NEW-POS can be anywhere in the two
     adjacent fields.  Additionally, if two fields are separated by
     another field with the special value `boundary', then any point
     within this special field is also considered to be "on the
     boundary."

     Commands like `C-a' with no argumemt, that normally move backward
     to a specific kind of location and stay there once there, probably
     should specify `nil' for ESCAPE-FROM-EDGE.  Other motion commands
     that check fields should probably pass `t'.

     If the optional argument ONLY-IN-LINE is non-`nil', and
     constraining NEW-POS in the usual way would move it to a different
     line, NEW-POS is returned unconstrained.  This used in commands
     that move by line, such as `next-line' and `beginning-of-line', so
     that they respect field boundaries only in the case where they can
     still move to the right line.

     If the optional argument INHIBIT-CAPTURE-PROPERTY is non-`nil',
     and OLD-POS has a non-`nil' property of that name, then any field
     boundaries are ignored.

     You can cause `constrain-to-field' to ignore all field boundaries
     (and so never constrain anything) by binding the variable
     `inhibit-field-text-motion' to a non-`nil' value.


File: elisp,  Node: Not Intervals,  Prev: Fields,  Up: Text Properties

32.19.12 Why Text Properties are not Intervals
----------------------------------------------

Some editors that support adding attributes to text in the buffer do so
by letting the user specify "intervals" within the text, and adding the
properties to the intervals.  Those editors permit the user or the
programmer to determine where individual intervals start and end.  We
deliberately provided a different sort of interface in Emacs Lisp to
avoid certain paradoxical behavior associated with text modification.

   If the actual subdivision into intervals is meaningful, that means
you can distinguish between a buffer that is just one interval with a
certain property, and a buffer containing the same text subdivided into
two intervals, both of which have that property.

   Suppose you take the buffer with just one interval and kill part of
the text.  The text remaining in the buffer is one interval, and the
copy in the kill ring (and the undo list) becomes a separate interval.
Then if you yank back the killed text, you get two intervals with the
same properties.  Thus, editing does not preserve the distinction
between one interval and two.

   Suppose we "fix" this problem by coalescing the two intervals when
the text is inserted.  That works fine if the buffer originally was a
single interval.  But suppose instead that we have two adjacent
intervals with the same properties, and we kill the text of one interval
and yank it back.  The same interval-coalescence feature that rescues
the other case causes trouble in this one: after yanking, we have just
one interval.  One again, editing does not preserve the distinction
between one interval and two.

   Insertion of text at the border between intervals also raises
questions that have no satisfactory answer.

   However, it is easy to arrange for editing to behave consistently for
questions of the form, "What are the properties of this character?"  So
we have decided these are the only questions that make sense; we have
not implemented asking questions about where intervals start or end.

   In practice, you can usually use the text property search functions
in place of explicit interval boundaries.  You can think of them as
finding the boundaries of intervals, assuming that intervals are always
coalesced whenever possible.  *Note Property Search::.

   Emacs also provides explicit intervals as a presentation feature; see
*note Overlays::.


File: elisp,  Node: Substitution,  Next: Transposition,  Prev: Text Properties,  Up: Text

32.20 Substituting for a Character Code
=======================================

The following functions replace characters within a specified region
based on their character codes.

 -- Function: subst-char-in-region start end old-char new-char
          &optional noundo
     This function replaces all occurrences of the character OLD-CHAR
     with the character NEW-CHAR in the region of the current buffer
     defined by START and END.

     If NOUNDO is non-`nil', then `subst-char-in-region' does not
     record the change for undo and does not mark the buffer as
     modified.  This was useful for controlling the old selective
     display feature (*note Selective Display::).

     `subst-char-in-region' does not move point and returns `nil'.

          ---------- Buffer: foo ----------
          This is the contents of the buffer before.
          ---------- Buffer: foo ----------

          (subst-char-in-region 1 20 ?i ?X)
               => nil

          ---------- Buffer: foo ----------
          ThXs Xs the contents of the buffer before.
          ---------- Buffer: foo ----------

 -- Function: translate-region start end table
     This function applies a translation table to the characters in the
     buffer between positions START and END.

     The translation table TABLE is a string or a char-table; `(aref
     TABLE OCHAR)' gives the translated character corresponding to
     OCHAR.  If TABLE is a string, any characters with codes larger
     than the length of TABLE are not altered by the translation.

     The return value of `translate-region' is the number of characters
     that were actually changed by the translation.  This does not
     count characters that were mapped into themselves in the
     translation table.


File: elisp,  Node: Registers,  Next: Base 64,  Prev: Transposition,  Up: Text

32.21 Registers
===============

A register is a sort of variable used in Emacs editing that can hold a
variety of different kinds of values.  Each register is named by a
single character.  All ASCII characters and their meta variants (but
with the exception of `C-g') can be used to name registers.  Thus,
there are 255 possible registers.  A register is designated in Emacs
Lisp by the character that is its name.

 -- Variable: register-alist
     This variable is an alist of elements of the form `(NAME .
     CONTENTS)'.  Normally, there is one element for each Emacs
     register that has been used.

     The object NAME is a character (an integer) identifying the
     register.

   The CONTENTS of a register can have several possible types:

a number
     A number stands for itself.  If `insert-register' finds a number
     in the register, it converts the number to decimal.

a marker
     A marker represents a buffer position to jump to.

a string
     A string is text saved in the register.

a rectangle
     A rectangle is represented by a list of strings.

`(WINDOW-CONFIGURATION POSITION)'
     This represents a window configuration to restore in one frame,
     and a position to jump to in the current buffer.

`(FRAME-CONFIGURATION POSITION)'
     This represents a frame configuration to restore, and a position
     to jump to in the current buffer.

(file FILENAME)
     This represents a file to visit; jumping to this value visits file
     FILENAME.

(file-query FILENAME POSITION)
     This represents a file to visit and a position in it; jumping to
     this value visits file FILENAME and goes to buffer position
     POSITION.  Restoring this type of position asks the user for
     confirmation first.

   The functions in this section return unpredictable values unless
otherwise stated.

 -- Function: get-register reg
     This function returns the contents of the register REG, or `nil'
     if it has no contents.

 -- Function: set-register reg value
     This function sets the contents of register REG to VALUE.  A
     register can be set to any value, but the other register functions
     expect only certain data types.  The return value is VALUE.

 -- Command: view-register reg
     This command displays what is contained in register REG.

 -- Command: insert-register reg &optional beforep
     This command inserts contents of register REG into the current
     buffer.

     Normally, this command puts point before the inserted text, and the
     mark after it.  However, if the optional second argument BEFOREP
     is non-`nil', it puts the mark before and point after.  You can
     pass a non-`nil' second argument BEFOREP to this function
     interactively by supplying any prefix argument.

     If the register contains a rectangle, then the rectangle is
     inserted with its upper left corner at point.  This means that
     text is inserted in the current line and underneath it on
     successive lines.

     If the register contains something other than saved text (a
     string) or a rectangle (a list), currently useless things happen.
     This may be changed in the future.


File: elisp,  Node: Transposition,  Next: Registers,  Prev: Substitution,  Up: Text

32.22 Transposition of Text
===========================

This subroutine is used by the transposition commands.

 -- Function: transpose-regions start1 end1 start2 end2 &optional
          leave-markers
     This function exchanges two nonoverlapping portions of the buffer.
     Arguments START1 and END1 specify the bounds of one portion and
     arguments START2 and END2 specify the bounds of the other portion.

     Normally, `transpose-regions' relocates markers with the transposed
     text; a marker previously positioned within one of the two
     transposed portions moves along with that portion, thus remaining
     between the same two characters in their new position.  However,
     if LEAVE-MARKERS is non-`nil', `transpose-regions' does not do
     this--it leaves all markers unrelocated.


File: elisp,  Node: Base 64,  Next: MD5 Checksum,  Prev: Registers,  Up: Text

32.23 Base 64 Encoding
======================

Base 64 code is used in email to encode a sequence of 8-bit bytes as a
longer sequence of ASCII graphic characters.  It is defined in Internet
RFC(1)2045.  This section describes the functions for converting to and
from this code.

 -- Function: base64-encode-region beg end &optional no-line-break
     This function converts the region from BEG to END into base 64
     code.  It returns the length of the encoded text.  An error is
     signaled if a character in the region is multibyte, i.e. in a
     multibyte buffer the region must contain only characters from the
     charsets `ascii', `eight-bit-control' and `eight-bit-graphic'.

     Normally, this function inserts newline characters into the encoded
     text, to avoid overlong lines.  However, if the optional argument
     NO-LINE-BREAK is non-`nil', these newlines are not added, so the
     output is just one long line.

 -- Function: base64-encode-string string &optional no-line-break
     This function converts the string STRING into base 64 code.  It
     returns a string containing the encoded text.  As for
     `base64-encode-region', an error is signaled if a character in the
     string is multibyte.

     Normally, this function inserts newline characters into the encoded
     text, to avoid overlong lines.  However, if the optional argument
     NO-LINE-BREAK is non-`nil', these newlines are not added, so the
     result string is just one long line.

 -- Function: base64-decode-region beg end
     This function converts the region from BEG to END from base 64
     code into the corresponding decoded text.  It returns the length of
     the decoded text.

     The decoding functions ignore newline characters in the encoded
     text.

 -- Function: base64-decode-string string
     This function converts the string STRING from base 64 code into
     the corresponding decoded text.  It returns a unibyte string
     containing the decoded text.

     The decoding functions ignore newline characters in the encoded
     text.

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

   (1) An RFC, an acronym for "Request for Comments", is a numbered
Internet informational document describing a standard.  RFCs are
usually written by technical experts acting on their own initiative,
and are traditionally written in a pragmatic, experience-driven manner.


File: elisp,  Node: MD5 Checksum,  Next: Atomic Changes,  Prev: Base 64,  Up: Text

32.24 MD5 Checksum
==================

MD5 cryptographic checksums, or "message digests", are 128-bit
"fingerprints" of a document or program.  They are used to verify that
you have an exact and unaltered copy of the data.  The algorithm to
calculate the MD5 message digest is defined in Internet RFC(1)1321.
This section describes the Emacs facilities for computing message
digests.

 -- Function: md5 object &optional start end coding-system noerror
     This function returns the MD5 message digest of OBJECT, which
     should be a buffer or a string.

     The two optional arguments START and END are character positions
     specifying the portion of OBJECT to compute the message digest
     for.  If they are `nil' or omitted, the digest is computed for the
     whole of OBJECT.

     The function `md5' does not compute the message digest directly
     from the internal Emacs representation of the text (*note Text
     Representations::).  Instead, it encodes the text using a coding
     system, and computes the message digest from the encoded text.  The
     optional fourth argument CODING-SYSTEM specifies which coding
     system to use for encoding the text.  It should be the same coding
     system that you used to read the text, or that you used or will use
     when saving or sending the text.  *Note Coding Systems::, for more
     information about coding systems.

     If CODING-SYSTEM is `nil' or omitted, the default depends on
     OBJECT.  If OBJECT is a buffer, the default for CODING-SYSTEM is
     whatever coding system would be chosen by default for writing this
     text into a file.  If OBJECT is a string, the user's most
     preferred coding system (*note prefer-coding-system:
     (emacs)Recognize Coding.) is used.

     Normally, `md5' signals an error if the text can't be encoded
     using the specified or chosen coding system.  However, if NOERROR
     is non-`nil', it silently uses `raw-text' coding instead.

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

   (1) For an explanation of what is an RFC, see the footnote in *note
Base 64::.


File: elisp,  Node: Atomic Changes,  Next: Change Hooks,  Prev: MD5 Checksum,  Up: Text

32.25 Atomic Change Groups
==========================

In data base terminology, an "atomic" change is an indivisible
change--it can succeed entirely or it can fail entirely, but it cannot
partly succeed.  A Lisp program can make a series of changes to one or
several buffers as an "atomic change group", meaning that either the
entire series of changes will be installed in their buffers or, in case
of an error, none of them will be.

   To do this for one buffer, the one already current, simply write a
call to `atomic-change-group' around the code that makes the changes,
like this:

     (atomic-change-group
       (insert foo)
       (delete-region x y))

If an error (or other nonlocal exit) occurs inside the body of
`atomic-change-group', it unmakes all the changes in that buffer that
were during the execution of the body.  This kind of change group has
no effect on any other buffers--any such changes remain.

   If you need something more sophisticated, such as to make changes in
various buffers constitute one atomic group, you must directly call
lower-level functions that `atomic-change-group' uses.

 -- Function: prepare-change-group &optional buffer
     This function sets up a change group for buffer BUFFER, which
     defaults to the current buffer.  It returns a "handle" that
     represents the change group.  You must use this handle to activate
     the change group and subsequently to finish it.

   To use the change group, you must "activate" it.  You must do this
before making any changes in the text of BUFFER.

 -- Function: activate-change-group handle
     This function activates the change group that HANDLE designates.

   After you activate the change group, any changes you make in that
buffer become part of it.  Once you have made all the desired changes
in the buffer, you must "finish" the change group.  There are two ways
to do this: you can either accept (and finalize) all the changes, or
cancel them all.

 -- Function: accept-change-group handle
     This function accepts all the changes in the change group
     specified by HANDLE, making them final.

 -- Function: cancel-change-group handle
     This function cancels and undoes all the changes in the change
     group specified by HANDLE.

   Your code should use `unwind-protect' to make sure the group is
always finished.  The call to `activate-change-group' should be inside
the `unwind-protect', in case the user types `C-g' just after it runs.
(This is one reason why `prepare-change-group' and
`activate-change-group' are separate functions, because normally you
would call `prepare-change-group' before the start of that
`unwind-protect'.)  Once you finish the group, don't use the handle
again--in particular, don't try to finish the same group twice.

   To make a multibuffer change group, call `prepare-change-group' once
for each buffer you want to cover, then use `nconc' to combine the
returned values, like this:

     (nconc (prepare-change-group buffer-1)
            (prepare-change-group buffer-2))

   You can then activate the multibuffer change group with a single call
to `activate-change-group', and finish it with a single call to
`accept-change-group' or `cancel-change-group'.

   Nested use of several change groups for the same buffer works as you
would expect.  Non-nested use of change groups for the same buffer will
get Emacs confused, so don't let it happen; the first change group you
start for any given buffer should be the last one finished.


File: elisp,  Node: Change Hooks,  Prev: Atomic Changes,  Up: Text

32.26 Change Hooks
==================

These hook variables let you arrange to take notice of all changes in
all buffers (or in a particular buffer, if you make them buffer-local).
See also *note Special Properties::, for how to detect changes to
specific parts of the text.

   The functions you use in these hooks should save and restore the
match data if they do anything that uses regular expressions;
otherwise, they will interfere in bizarre ways with the editing
operations that call them.

 -- Variable: before-change-functions
     This variable holds a list of functions to call before any buffer
     modification.  Each function gets two arguments, the beginning and
     end of the region that is about to change, represented as
     integers.  The buffer that is about to change is always the
     current buffer.

 -- Variable: after-change-functions
     This variable holds a list of functions to call after any buffer
     modification.  Each function receives three arguments: the
     beginning and end of the region just changed, and the length of
     the text that existed before the change.  All three arguments are
     integers.  The buffer that's about to change is always the current
     buffer.

     The length of the old text is the difference between the buffer
     positions before and after that text as it was before the change.
     As for the changed text, its length is simply the difference
     between the first two arguments.

   Output of messages into the `*Messages*' buffer does not call these
functions.

 -- Macro: combine-after-change-calls body...
     The macro executes BODY normally, but arranges to call the
     after-change functions just once for a series of several
     changes--if that seems safe.

     If a program makes several text changes in the same area of the
     buffer, using the macro `combine-after-change-calls' around that
     part of the program can make it run considerably faster when
     after-change hooks are in use.  When the after-change hooks are
     ultimately called, the arguments specify a portion of the buffer
     including all of the changes made within the
     `combine-after-change-calls' body.

     *Warning:* You must not alter the values of
     `after-change-functions' within the body of a
     `combine-after-change-calls' form.

     *Warning:* if the changes you combine occur in widely scattered
     parts of the buffer, this will still work, but it is not advisable,
     because it may lead to inefficient behavior for some change hook
     functions.

 -- Variable: first-change-hook
     This variable is a normal hook that is run whenever a buffer is
     changed that was previously in the unmodified state.

 -- Variable: inhibit-modification-hooks
     If this variable is non-`nil', all of the change hooks are
     disabled; none of them run.  This affects all the hook variables
     described above in this section, as well as the hooks attached to
     certain special text properties (*note Special Properties::) and
     overlay properties (*note Overlay Properties::).

     Also, this variable is bound to non-`nil' while running those same
     hook variables, so that by default modifying the buffer from a
     modification hook does not cause other modification hooks to be
     run.  If you do want modification hooks to be run in a particular
     piece of code that is itself run from a modification hook, then
     rebind locally `inhibit-modification-hooks' to `nil'.


File: elisp,  Node: Non-ASCII Characters,  Next: Searching and Matching,  Prev: Text,  Up: Top

33 Non-ASCII Characters
***********************

This chapter covers the special issues relating to non-ASCII characters
and how they are stored in strings and buffers.

* Menu:

* Text Representations::    Unibyte and multibyte representations
* Converting Representations::  Converting unibyte to multibyte and vice versa.
* Selecting a Representation::  Treating a byte sequence as unibyte or multi.
* Character Codes::         How unibyte and multibyte relate to
                                codes of individual characters.
* Character Sets::          The space of possible character codes
                                is divided into various character sets.
* Chars and Bytes::         More information about multibyte encodings.
* Splitting Characters::    Converting a character to its byte sequence.
* Scanning Charsets::       Which character sets are used in a buffer?
* Translation of Characters::   Translation tables are used for conversion.
* Coding Systems::          Coding systems are conversions for saving files.
* Input Methods::           Input methods allow users to enter various
                                non-ASCII characters without special keyboards.
* Locales::                 Interacting with the POSIX locale.


File: elisp,  Node: Text Representations,  Next: Converting Representations,  Up: Non-ASCII Characters

33.1 Text Representations
=========================

Emacs has two "text representations"--two ways to represent text in a
string or buffer.  These are called "unibyte" and "multibyte".  Each
string, and each buffer, uses one of these two representations.  For
most purposes, you can ignore the issue of representations, because
Emacs converts text between them as appropriate.  Occasionally in Lisp
programming you will need to pay attention to the difference.

   In unibyte representation, each character occupies one byte and
therefore the possible character codes range from 0 to 255.  Codes 0
through 127 are ASCII characters; the codes from 128 through 255 are
used for one non-ASCII character set (you can choose which character
set by setting the variable `nonascii-insert-offset').

   In multibyte representation, a character may occupy more than one
byte, and as a result, the full range of Emacs character codes can be
stored.  The first byte of a multibyte character is always in the range
128 through 159 (octal 0200 through 0237).  These values are called
"leading codes".  The second and subsequent bytes of a multibyte
character are always in the range 160 through 255 (octal 0240 through
0377); these values are "trailing codes".

   Some sequences of bytes are not valid in multibyte text: for example,
a single isolated byte in the range 128 through 159 is not allowed.  But
character codes 128 through 159 can appear in multibyte text,
represented as two-byte sequences.  All the character codes 128 through
255 are possible (though slightly abnormal) in multibyte text; they
appear in multibyte buffers and strings when you do explicit encoding
and decoding (*note Explicit Encoding::).

   In a buffer, the buffer-local value of the variable
`enable-multibyte-characters' specifies the representation used.  The
representation for a string is determined and recorded in the string
when the string is constructed.

 -- Variable: enable-multibyte-characters
     This variable specifies the current buffer's text representation.
     If it is non-`nil', the buffer contains multibyte text; otherwise,
     it contains unibyte text.

     You cannot set this variable directly; instead, use the function
     `set-buffer-multibyte' to change a buffer's representation.

 -- Variable: default-enable-multibyte-characters
     This variable's value is entirely equivalent to `(default-value
     'enable-multibyte-characters)', and setting this variable changes
     that default value.  Setting the local binding of
     `enable-multibyte-characters' in a specific buffer is not allowed,
     but changing the default value is supported, and it is a reasonable
     thing to do, because it has no effect on existing buffers.

     The `--unibyte' command line option does its job by setting the
     default value to `nil' early in startup.

 -- Function: position-bytes position
     Return the byte-position corresponding to buffer position POSITION
     in the current buffer.  This is 1 at the start of the buffer, and
     counts upward in bytes.  If POSITION is out of range, the value is
     `nil'.

 -- Function: byte-to-position byte-position
     Return the buffer position corresponding to byte-position
     BYTE-POSITION in the current buffer.  If BYTE-POSITION is out of
     range, the value is `nil'.

 -- Function: multibyte-string-p string
     Return `t' if STRING is a multibyte string.

 -- Function: string-bytes string
     This function returns the number of bytes in STRING.  If STRING is
     a multibyte string, this can be greater than `(length STRING)'.


File: elisp,  Node: Converting Representations,  Next: Selecting a Representation,  Prev: Text Representations,  Up: Non-ASCII Characters

33.2 Converting Text Representations
====================================

Emacs can convert unibyte text to multibyte; it can also convert
multibyte text to unibyte, though this conversion loses information.  In
general these conversions happen when inserting text into a buffer, or
when putting text from several strings together in one string.  You can
also explicitly convert a string's contents to either representation.

   Emacs chooses the representation for a string based on the text that
it is constructed from.  The general rule is to convert unibyte text to
multibyte text when combining it with other multibyte text, because the
multibyte representation is more general and can hold whatever
characters the unibyte text has.

   When inserting text into a buffer, Emacs converts the text to the
buffer's representation, as specified by `enable-multibyte-characters'
in that buffer.  In particular, when you insert multibyte text into a
unibyte buffer, Emacs converts the text to unibyte, even though this
conversion cannot in general preserve all the characters that might be
in the multibyte text.  The other natural alternative, to convert the
buffer contents to multibyte, is not acceptable because the buffer's
representation is a choice made by the user that cannot be overridden
automatically.

   Converting unibyte text to multibyte text leaves ASCII characters
unchanged, and likewise character codes 128 through 159.  It converts
the non-ASCII codes 160 through 255 by adding the value
`nonascii-insert-offset' to each character code.  By setting this
variable, you specify which character set the unibyte characters
correspond to (*note Character Sets::).  For example, if
`nonascii-insert-offset' is 2048, which is `(- (make-char
'latin-iso8859-1) 128)', then the unibyte non-ASCII characters
correspond to Latin 1.  If it is 2688, which is `(- (make-char
'greek-iso8859-7) 128)', then they correspond to Greek letters.

   Converting multibyte text to unibyte is simpler: it discards all but
the low 8 bits of each character code.  If `nonascii-insert-offset' has
a reasonable value, corresponding to the beginning of some character
set, this conversion is the inverse of the other: converting unibyte
text to multibyte and back to unibyte reproduces the original unibyte
text.

 -- Variable: nonascii-insert-offset
     This variable specifies the amount to add to a non-ASCII character
     when converting unibyte text to multibyte.  It also applies when
     `self-insert-command' inserts a character in the unibyte non-ASCII
     range, 128 through 255.  However, the functions `insert' and
     `insert-char' do not perform this conversion.

     The right value to use to select character set CS is `(-
     (make-char CS) 128)'.  If the value of `nonascii-insert-offset' is
     zero, then conversion actually uses the value for the Latin 1
     character set, rather than zero.

 -- Variable: nonascii-translation-table
     This variable provides a more general alternative to
     `nonascii-insert-offset'.  You can use it to specify independently
     how to translate each code in the range of 128 through 255 into a
     multibyte character.  The value should be a char-table, or `nil'.
     If this is non-`nil', it overrides `nonascii-insert-offset'.

   The next three functions either return the argument STRING, or a
newly created string with no text properties.

 -- Function: string-make-unibyte string
     This function converts the text of STRING to unibyte
     representation, if it isn't already, and returns the result.  If
     STRING is a unibyte string, it is returned unchanged.  Multibyte
     character codes are converted to unibyte according to
     `nonascii-translation-table' or, if that is `nil', using
     `nonascii-insert-offset'.  If the lookup in the translation table
     fails, this function takes just the low 8 bits of each character.

 -- Function: string-make-multibyte string
     This function converts the text of STRING to multibyte
     representation, if it isn't already, and returns the result.  If
     STRING is a multibyte string or consists entirely of ASCII
     characters, it is returned unchanged.  In particular, if STRING is
     unibyte and entirely ASCII, the returned string is unibyte.  (When
     the characters are all ASCII, Emacs primitives will treat the
     string the same way whether it is unibyte or multibyte.)  If
     STRING is unibyte and contains non-ASCII characters, the function
     `unibyte-char-to-multibyte' is used to convert each unibyte
     character to a multibyte character.

 -- Function: string-to-multibyte string
     This function returns a multibyte string containing the same
     sequence of character codes as STRING.  Unlike
     `string-make-multibyte', this function unconditionally returns a
     multibyte string.  If STRING is a multibyte string, it is returned
     unchanged.

 -- Function: multibyte-char-to-unibyte char
     This convert the multibyte character CHAR to a unibyte character,
     based on `nonascii-translation-table' and `nonascii-insert-offset'.

 -- Function: unibyte-char-to-multibyte char
     This convert the unibyte character CHAR to a multibyte character,
     based on `nonascii-translation-table' and `nonascii-insert-offset'.


File: elisp,  Node: Selecting a Representation,  Next: Character Codes,  Prev: Converting Representations,  Up: Non-ASCII Characters

33.3 Selecting a Representation
===============================

Sometimes it is useful to examine an existing buffer or string as
multibyte when it was unibyte, or vice versa.

 -- Function: set-buffer-multibyte multibyte
     Set the representation type of the current buffer.  If MULTIBYTE
     is non-`nil', the buffer becomes multibyte.  If MULTIBYTE is
     `nil', the buffer becomes unibyte.

     This function leaves the buffer contents unchanged when viewed as a
     sequence of bytes.  As a consequence, it can change the contents
     viewed as characters; a sequence of two bytes which is treated as
     one character in multibyte representation will count as two
     characters in unibyte representation.  Character codes 128 through
     159 are an exception.  They are represented by one byte in a
     unibyte buffer, but when the buffer is set to multibyte, they are
     converted to two-byte sequences, and vice versa.

     This function sets `enable-multibyte-characters' to record which
     representation is in use.  It also adjusts various data in the
     buffer (including overlays, text properties and markers) so that
     they cover the same text as they did before.

     You cannot use `set-buffer-multibyte' on an indirect buffer,
     because indirect buffers always inherit the representation of the
     base buffer.

 -- Function: string-as-unibyte string
     This function returns a string with the same bytes as STRING but
     treating each byte as a character.  This means that the value may
     have more characters than STRING has.

     If STRING is already a unibyte string, then the value is STRING
     itself.  Otherwise it is a newly created string, with no text
     properties.  If STRING is multibyte, any characters it contains of
     charset `eight-bit-control' or `eight-bit-graphic' are converted
     to the corresponding single byte.

 -- Function: string-as-multibyte string
     This function returns a string with the same bytes as STRING but
     treating each multibyte sequence as one character.  This means
     that the value may have fewer characters than STRING has.

     If STRING is already a multibyte string, then the value is STRING
     itself.  Otherwise it is a newly created string, with no text
     properties.  If STRING is unibyte and contains any individual
     8-bit bytes (i.e. not part of a multibyte form), they are
     converted to the corresponding multibyte character of charset
     `eight-bit-control' or `eight-bit-graphic'.


File: elisp,  Node: Character Codes,  Next: Character Sets,  Prev: Selecting a Representation,  Up: Non-ASCII Characters

33.4 Character Codes
====================

The unibyte and multibyte text representations use different character
codes.  The valid character codes for unibyte representation range from
0 to 255--the values that can fit in one byte.  The valid character
codes for multibyte representation range from 0 to 524287, but not all
values in that range are valid.  The values 128 through 255 are not
entirely proper in multibyte text, but they can occur if you do explicit
encoding and decoding (*note Explicit Encoding::).  Some other character
codes cannot occur at all in multibyte text.  Only the ASCII codes 0
through 127 are completely legitimate in both representations.

 -- Function: char-valid-p charcode &optional genericp
     This returns `t' if CHARCODE is valid (either for unibyte text or
     for multibyte text).

          (char-valid-p 65)
               => t
          (char-valid-p 256)
               => nil
          (char-valid-p 2248)
               => t

     If the optional argument GENERICP is non-`nil', this function also
     returns `t' if CHARCODE is a generic character (*note Splitting
     Characters::).


File: elisp,  Node: Character Sets,  Next: Chars and Bytes,  Prev: Character Codes,  Up: Non-ASCII Characters

33.5 Character Sets
===================

Emacs classifies characters into various "character sets", each of
which has a name which is a symbol.  Each character belongs to one and
only one character set.

   In general, there is one character set for each distinct script.  For
example, `latin-iso8859-1' is one character set, `greek-iso8859-7' is
another, and `ascii' is another.  An Emacs character set can hold at
most 9025 characters; therefore, in some cases, characters that would
logically be grouped together are split into several character sets.
For example, one set of Chinese characters, generally known as Big 5,
is divided into two Emacs character sets, `chinese-big5-1' and
`chinese-big5-2'.

   ASCII characters are in character set `ascii'.  The non-ASCII
characters 128 through 159 are in character set `eight-bit-control',
and codes 160 through 255 are in character set `eight-bit-graphic'.

 -- Function: charsetp object
     Returns `t' if OBJECT is a symbol that names a character set,
     `nil' otherwise.

 -- Variable: charset-list
     The value is a list of all defined character set names.

 -- Function: charset-list
     This function returns the value of `charset-list'.  It is only
     provided for backward compatibility.

 -- Function: char-charset character
     This function returns the name of the character set that CHARACTER
     belongs to, or the symbol `unknown' if CHARACTER is not a valid
     character.

 -- Function: charset-plist charset
     This function returns the charset property list of the character
     set CHARSET.  Although CHARSET is a symbol, this is not the same
     as the property list of that symbol.  Charset properties are used
     for special purposes within Emacs.

 -- Command: list-charset-chars charset
     This command displays a list of characters in the character set
     CHARSET.


File: elisp,  Node: Chars and Bytes,  Next: Splitting Characters,  Prev: Character Sets,  Up: Non-ASCII Characters

33.6 Characters and Bytes
=========================

In multibyte representation, each character occupies one or more bytes.
Each character set has an "introduction sequence", which is normally
one or two bytes long.  (Exception: the `ascii' character set and the
`eight-bit-graphic' character set have a zero-length introduction
sequence.)  The introduction sequence is the beginning of the byte
sequence for any character in the character set.  The rest of the
character's bytes distinguish it from the other characters in the same
character set.  Depending on the character set, there are either one or
two distinguishing bytes; the number of such bytes is called the
"dimension" of the character set.

 -- Function: charset-dimension charset
     This function returns the dimension of CHARSET; at present, the
     dimension is always 1 or 2.

 -- Function: charset-bytes charset
     This function returns the number of bytes used to represent a
     character in character set CHARSET.

   This is the simplest way to determine the byte length of a character
set's introduction sequence:

     (- (charset-bytes CHARSET)
        (charset-dimension CHARSET))


File: elisp,  Node: Splitting Characters,  Next: Scanning Charsets,  Prev: Chars and Bytes,  Up: Non-ASCII Characters

33.7 Splitting Characters
=========================

The functions in this section convert between characters and the byte
values used to represent them.  For most purposes, there is no need to
be concerned with the sequence of bytes used to represent a character,
because Emacs translates automatically when necessary.

 -- Function: split-char character
     Return a list containing the name of the character set of
     CHARACTER, followed by one or two byte values (integers) which
     identify CHARACTER within that character set.  The number of byte
     values is the character set's dimension.

     If CHARACTER is invalid as a character code, `split-char' returns
     a list consisting of the symbol `unknown' and CHARACTER.

          (split-char 2248)
               => (latin-iso8859-1 72)
          (split-char 65)
               => (ascii 65)
          (split-char 128)
               => (eight-bit-control 128)

 -- Function: make-char charset &optional code1 code2
     This function returns the character in character set CHARSET whose
     position codes are CODE1 and CODE2.  This is roughly the inverse
     of `split-char'.  Normally, you should specify either one or both
     of CODE1 and CODE2 according to the dimension of CHARSET.  For
     example,

          (make-char 'latin-iso8859-1 72)
               => 2248

     Actually, the eighth bit of both CODE1 and CODE2 is zeroed before
     they are used to index CHARSET.  Thus you may use, for instance,
     an ISO 8859 character code rather than subtracting 128, as is
     necessary to index the corresponding Emacs charset.

   If you call `make-char' with no BYTE-VALUES, the result is a
"generic character" which stands for CHARSET.  A generic character is
an integer, but it is _not_ valid for insertion in the buffer as a
character.  It can be used in `char-table-range' to refer to the whole
character set (*note Char-Tables::).  `char-valid-p' returns `nil' for
generic characters.  For example:

     (make-char 'latin-iso8859-1)
          => 2176
     (char-valid-p 2176)
          => nil
     (char-valid-p 2176 t)
          => t
     (split-char 2176)
          => (latin-iso8859-1 0)

   The character sets `ascii', `eight-bit-control', and
`eight-bit-graphic' don't have corresponding generic characters.  If
CHARSET is one of them and you don't supply CODE1, `make-char' returns
the character code corresponding to the smallest code in CHARSET.


File: elisp,  Node: Scanning Charsets,  Next: Translation of Characters,  Prev: Splitting Characters,  Up: Non-ASCII Characters

33.8 Scanning for Character Sets
================================

Sometimes it is useful to find out which character sets appear in a
part of a buffer or a string.  One use for this is in determining which
coding systems (*note Coding Systems::) are capable of representing all
of the text in question.

 -- Function: charset-after &optional pos
     This function return the charset of a character in the current
     buffer at position POS.  If POS is omitted or `nil', it defaults
     to the current value of point.  If POS is out of range, the value
     is `nil'.

 -- Function: find-charset-region beg end &optional translation
     This function returns a list of the character sets that appear in
     the current buffer between positions BEG and END.

     The optional argument TRANSLATION specifies a translation table to
     be used in scanning the text (*note Translation of Characters::).
     If it is non-`nil', then each character in the region is translated
     through this table, and the value returned describes the translated
     characters instead of the characters actually in the buffer.

 -- Function: find-charset-string string &optional translation
     This function returns a list of the character sets that appear in
     the string STRING.  It is just like `find-charset-region', except
     that it applies to the contents of STRING instead of part of the
     current buffer.


File: elisp,  Node: Translation of Characters,  Next: Coding Systems,  Prev: Scanning Charsets,  Up: Non-ASCII Characters

33.9 Translation of Characters
==============================

A "translation table" is a char-table that specifies a mapping of
characters into characters.  These tables are used in encoding and
decoding, and for other purposes.  Some coding systems specify their
own particular translation tables; there are also default translation
tables which apply to all other coding systems.

   For instance, the coding-system `utf-8' has a translation table that
maps characters of various charsets (e.g., `latin-iso8859-X') into
Unicode character sets.  This way, it can encode Latin-2 characters
into UTF-8.  Meanwhile, `unify-8859-on-decoding-mode' operates by
specifying `standard-translation-table-for-decode' to translate Latin-X
characters into corresponding Unicode characters.

 -- Function: make-translation-table &rest translations
     This function returns a translation table based on the argument
     TRANSLATIONS.  Each element of TRANSLATIONS should be a list of
     elements of the form `(FROM . TO)'; this says to translate the
     character FROM into TO.

     The arguments and the forms in each argument are processed in
     order, and if a previous form already translates TO to some other
     character, say TO-ALT, FROM is also translated to TO-ALT.

     You can also map one whole character set into another character
     set with the same dimension.  To do this, you specify a generic
     character (which designates a character set) for FROM (*note
     Splitting Characters::).  In this case, if TO is also a generic
     character, its character set should have the same dimension as
     FROM's.  Then the translation table translates each character of
     FROM's character set into the corresponding character of TO's
     character set.  If FROM is a generic character and TO is an
     ordinary character, then the translation table translates every
     character of FROM's character set into TO.

   In decoding, the translation table's translations are applied to the
characters that result from ordinary decoding.  If a coding system has
property `translation-table-for-decode', that specifies the translation
table to use.  (This is a property of the coding system, as returned by
`coding-system-get', not a property of the symbol that is the coding
system's name. *Note Basic Concepts of Coding Systems: Coding System
Basics.)  Otherwise, if `standard-translation-table-for-decode' is
non-`nil', decoding uses that table.

   In encoding, the translation table's translations are applied to the
characters in the buffer, and the result of translation is actually
encoded.  If a coding system has property
`translation-table-for-encode', that specifies the translation table to
use.  Otherwise the variable `standard-translation-table-for-encode'
specifies the translation table.

 -- Variable: standard-translation-table-for-decode
     This is the default translation table for decoding, for coding
     systems that don't specify any other translation table.

 -- Variable: standard-translation-table-for-encode
     This is the default translation table for encoding, for coding
     systems that don't specify any other translation table.

 -- Variable: translation-table-for-input
     Self-inserting characters are translated through this translation
     table before they are inserted.  Search commands also translate
     their input through this table, so they can compare more reliably
     with what's in the buffer.

     `set-buffer-file-coding-system' sets this variable so that your
     keyboard input gets translated into the character sets that the
     buffer is likely to contain.  This variable automatically becomes
     buffer-local when set.


File: elisp,  Node: Coding Systems,  Next: Input Methods,  Prev: Translation of Characters,  Up: Non-ASCII Characters

33.10 Coding Systems
====================

When Emacs reads or writes a file, and when Emacs sends text to a
subprocess or receives text from a subprocess, it normally performs
character code conversion and end-of-line conversion as specified by a
particular "coding system".

   How to define a coding system is an arcane matter, and is not
documented here.

* Menu:

* Coding System Basics::        Basic concepts.
* Encoding and I/O::            How file I/O functions handle coding systems.
* Lisp and Coding Systems::     Functions to operate on coding system names.
* User-Chosen Coding Systems::  Asking the user to choose a coding system.
* Default Coding Systems::      Controlling the default choices.
* Specifying Coding Systems::   Requesting a particular coding system
                                    for a single file operation.
* Explicit Encoding::           Encoding or decoding text without doing I/O.
* Terminal I/O Encoding::       Use of encoding for terminal I/O.
* MS-DOS File Types::           How DOS "text" and "binary" files
                                    relate to coding systems.


File: elisp,  Node: Coding System Basics,  Next: Encoding and I/O,  Up: Coding Systems

33.10.1 Basic Concepts of Coding Systems
----------------------------------------

"Character code conversion" involves conversion between the encoding
used inside Emacs and some other encoding.  Emacs supports many
different encodings, in that it can convert to and from them.  For
example, it can convert text to or from encodings such as Latin 1, Latin
2, Latin 3, Latin 4, Latin 5, and several variants of ISO 2022.  In some
cases, Emacs supports several alternative encodings for the same
characters; for example, there are three coding systems for the Cyrillic
(Russian) alphabet: ISO, Alternativnyj, and KOI8.

   Most coding systems specify a particular character code for
conversion, but some of them leave the choice unspecified--to be chosen
heuristically for each file, based on the data.

   In general, a coding system doesn't guarantee roundtrip identity:
decoding a byte sequence using coding system, then encoding the
resulting text in the same coding system, can produce a different byte
sequence.  However, the following coding systems do guarantee that the
byte sequence will be the same as what you originally decoded:

     chinese-big5 chinese-iso-8bit cyrillic-iso-8bit emacs-mule
     greek-iso-8bit hebrew-iso-8bit iso-latin-1 iso-latin-2 iso-latin-3
     iso-latin-4 iso-latin-5 iso-latin-8 iso-latin-9 iso-safe
     japanese-iso-8bit japanese-shift-jis korean-iso-8bit raw-text

   Encoding buffer text and then decoding the result can also fail to
reproduce the original text.  For instance, if you encode Latin-2
characters with `utf-8' and decode the result using the same coding
system, you'll get Unicode characters (of charset
`mule-unicode-0100-24ff').  If you encode Unicode characters with
`iso-latin-2' and decode the result with the same coding system, you'll
get Latin-2 characters.

   "End of line conversion" handles three different conventions used on
various systems for representing end of line in files.  The Unix
convention is to use the linefeed character (also called newline).  The
DOS convention is to use a carriage-return and a linefeed at the end of
a line.  The Mac convention is to use just carriage-return.

   "Base coding systems" such as `latin-1' leave the end-of-line
conversion unspecified, to be chosen based on the data.  "Variant
coding systems" such as `latin-1-unix', `latin-1-dos' and `latin-1-mac'
specify the end-of-line conversion explicitly as well.  Most base
coding systems have three corresponding variants whose names are formed
by adding `-unix', `-dos' and `-mac'.

   The coding system `raw-text' is special in that it prevents
character code conversion, and causes the buffer visited with that
coding system to be a unibyte buffer.  It does not specify the
end-of-line conversion, allowing that to be determined as usual by the
data, and has the usual three variants which specify the end-of-line
conversion.  `no-conversion' is equivalent to `raw-text-unix': it
specifies no conversion of either character codes or end-of-line.

   The coding system `emacs-mule' specifies that the data is
represented in the internal Emacs encoding.  This is like `raw-text' in
that no code conversion happens, but different in that the result is
multibyte data.

 -- Function: coding-system-get coding-system property
     This function returns the specified property of the coding system
     CODING-SYSTEM.  Most coding system properties exist for internal
     purposes, but one that you might find useful is `mime-charset'.
     That property's value is the name used in MIME for the character
     coding which this coding system can read and write.  Examples:

          (coding-system-get 'iso-latin-1 'mime-charset)
               => iso-8859-1
          (coding-system-get 'iso-2022-cn 'mime-charset)
               => iso-2022-cn
          (coding-system-get 'cyrillic-koi8 'mime-charset)
               => koi8-r

     The value of the `mime-charset' property is also defined as an
     alias for the coding system.


File: elisp,  Node: Encoding and I/O,  Next: Lisp and Coding Systems,  Prev: Coding System Basics,  Up: Coding Systems

33.10.2 Encoding and I/O
------------------------

The principal purpose of coding systems is for use in reading and
writing files.  The function `insert-file-contents' uses a coding
system for decoding the file data, and `write-region' uses one to
encode the buffer contents.

   You can specify the coding system to use either explicitly (*note
Specifying Coding Systems::), or implicitly using a default mechanism
(*note Default Coding Systems::).  But these methods may not completely
specify what to do.  For example, they may choose a coding system such
as `undefined' which leaves the character code conversion to be
determined from the data.  In these cases, the I/O operation finishes
the job of choosing a coding system.  Very often you will want to find
out afterwards which coding system was chosen.

 -- Variable: buffer-file-coding-system
     This buffer-local variable records the coding system that was used
     to visit the current buffer.  It is used for saving the buffer,
     and for writing part of the buffer with `write-region'.  If the
     text to be written cannot be safely encoded using the coding
     system specified by this variable, these operations select an
     alternative encoding by calling the function
     `select-safe-coding-system' (*note User-Chosen Coding Systems::).
     If selecting a different encoding requires to ask the user to
     specify a coding system, `buffer-file-coding-system' is updated to
     the newly selected coding system.

     `buffer-file-coding-system' does _not_ affect sending text to a
     subprocess.

 -- Variable: save-buffer-coding-system
     This variable specifies the coding system for saving the buffer (by
     overriding `buffer-file-coding-system').  Note that it is not used
     for `write-region'.

     When a command to save the buffer starts out to use
     `buffer-file-coding-system' (or `save-buffer-coding-system'), and
     that coding system cannot handle the actual text in the buffer,
     the command asks the user to choose another coding system (by
     calling `select-safe-coding-system').  After that happens, the
     command also updates `buffer-file-coding-system' to represent the
     coding system that the user specified.

 -- Variable: last-coding-system-used
     I/O operations for files and subprocesses set this variable to the
     coding system name that was used.  The explicit encoding and
     decoding functions (*note Explicit Encoding::) set it too.

     *Warning:* Since receiving subprocess output sets this variable,
     it can change whenever Emacs waits; therefore, you should copy the
     value shortly after the function call that stores the value you are
     interested in.

   The variable `selection-coding-system' specifies how to encode
selections for the window system.  *Note Window System Selections::.

 -- Variable: file-name-coding-system
     The variable `file-name-coding-system' specifies the coding system
     to use for encoding file names.  Emacs encodes file names using
     that coding system for all file operations.  If
     `file-name-coding-system' is `nil', Emacs uses a default coding
     system determined by the selected language environment.  In the
     default language environment, any non-ASCII characters in file
     names are not encoded specially; they appear in the file system
     using the internal Emacs representation.

   *Warning:* if you change `file-name-coding-system' (or the language
environment) in the middle of an Emacs session, problems can result if
you have already visited files whose names were encoded using the
earlier coding system and are handled differently under the new coding
system.  If you try to save one of these buffers under the visited file
name, saving may use the wrong file name, or it may get an error.  If
such a problem happens, use `C-x C-w' to specify a new file name for
that buffer.


File: elisp,  Node: Lisp and Coding Systems,  Next: User-Chosen Coding Systems,  Prev: Encoding and I/O,  Up: Coding Systems

33.10.3 Coding Systems in Lisp
------------------------------

Here are the Lisp facilities for working with coding systems:

 -- Function: coding-system-list &optional base-only
     This function returns a list of all coding system names (symbols).
     If BASE-ONLY is non-`nil', the value includes only the base coding
     systems.  Otherwise, it includes alias and variant coding systems
     as well.

 -- Function: coding-system-p object
     This function returns `t' if OBJECT is a coding system name or
     `nil'.

 -- Function: check-coding-system coding-system
     This function checks the validity of CODING-SYSTEM.  If that is
     valid, it returns CODING-SYSTEM.  Otherwise it signals an error
     with condition `coding-system-error'.

 -- Function: coding-system-eol-type coding-system
     This function returns the type of end-of-line (a.k.a. "eol")
     conversion used by CODING-SYSTEM.  If CODING-SYSTEM specifies a
     certain eol conversion, the return value is an integer 0, 1, or 2,
     standing for `unix', `dos', and `mac', respectively.  If
     CODING-SYSTEM doesn't specify eol conversion explicitly, the
     return value is a vector of coding systems, each one with one of
     the possible eol conversion types, like this:

          (coding-system-eol-type 'latin-1)
               => [latin-1-unix latin-1-dos latin-1-mac]

     If this function returns a vector, Emacs will decide, as part of
     the text encoding or decoding process, what eol conversion to use.
     For decoding, the end-of-line format of the text is auto-detected,
     and the eol conversion is set to match it (e.g., DOS-style CRLF
     format will imply `dos' eol conversion).  For encoding, the eol
     conversion is taken from the appropriate default coding system
     (e.g., `default-buffer-file-coding-system' for
     `buffer-file-coding-system'), or from the default eol conversion
     appropriate for the underlying platform.

 -- Function: coding-system-change-eol-conversion coding-system eol-type
     This function returns a coding system which is like CODING-SYSTEM
     except for its eol conversion, which is specified by `eol-type'.
     EOL-TYPE should be `unix', `dos', `mac', or `nil'.  If it is
     `nil', the returned coding system determines the end-of-line
     conversion from the data.

     EOL-TYPE may also be 0, 1 or 2, standing for `unix', `dos' and
     `mac', respectively.

 -- Function: coding-system-change-text-conversion eol-coding
          text-coding
     This function returns a coding system which uses the end-of-line
     conversion of EOL-CODING, and the text conversion of TEXT-CODING.
     If TEXT-CODING is `nil', it returns `undecided', or one of its
     variants according to EOL-CODING.

 -- Function: find-coding-systems-region from to
     This function returns a list of coding systems that could be used
     to encode a text between FROM and TO.  All coding systems in the
     list can safely encode any multibyte characters in that portion of
     the text.

     If the text contains no multibyte characters, the function returns
     the list `(undecided)'.

 -- Function: find-coding-systems-string string
     This function returns a list of coding systems that could be used
     to encode the text of STRING.  All coding systems in the list can
     safely encode any multibyte characters in STRING.  If the text
     contains no multibyte characters, this returns the list
     `(undecided)'.

 -- Function: find-coding-systems-for-charsets charsets
     This function returns a list of coding systems that could be used
     to encode all the character sets in the list CHARSETS.

 -- Function: detect-coding-region start end &optional highest
     This function chooses a plausible coding system for decoding the
     text from START to END.  This text should be a byte sequence
     (*note Explicit Encoding::).

     Normally this function returns a list of coding systems that could
     handle decoding the text that was scanned.  They are listed in
     order of decreasing priority.  But if HIGHEST is non-`nil', then
     the return value is just one coding system, the one that is
     highest in priority.

     If the region contains only ASCII characters except for such
     ISO-2022 control characters ISO-2022 as `ESC', the value is
     `undecided' or `(undecided)', or a variant specifying end-of-line
     conversion, if that can be deduced from the text.

 -- Function: detect-coding-string string &optional highest
     This function is like `detect-coding-region' except that it
     operates on the contents of STRING instead of bytes in the buffer.

   *Note Process Information: Coding systems for a subprocess, in
particular the description of the functions `process-coding-system' and
`set-process-coding-system', for how to examine or set the coding
systems used for I/O to a subprocess.


File: elisp,  Node: User-Chosen Coding Systems,  Next: Default Coding Systems,  Prev: Lisp and Coding Systems,  Up: Coding Systems

33.10.4 User-Chosen Coding Systems
----------------------------------

 -- Function: select-safe-coding-system from to &optional
          default-coding-system accept-default-p file
     This function selects a coding system for encoding specified text,
     asking the user to choose if necessary.  Normally the specified
     text is the text in the current buffer between FROM and TO.  If
     FROM is a string, the string specifies the text to encode, and TO
     is ignored.

     If DEFAULT-CODING-SYSTEM is non-`nil', that is the first coding
     system to try; if that can handle the text,
     `select-safe-coding-system' returns that coding system.  It can
     also be a list of coding systems; then the function tries each of
     them one by one.  After trying all of them, it next tries the
     current buffer's value of `buffer-file-coding-system' (if it is not
     `undecided'), then the value of
     `default-buffer-file-coding-system' and finally the user's most
     preferred coding system, which the user can set using the command
     `prefer-coding-system' (*note Recognizing Coding Systems:
     (emacs)Recognize Coding.).

     If one of those coding systems can safely encode all the specified
     text, `select-safe-coding-system' chooses it and returns it.
     Otherwise, it asks the user to choose from a list of coding systems
     which can encode all the text, and returns the user's choice.

     DEFAULT-CODING-SYSTEM can also be a list whose first element is t
     and whose other elements are coding systems.  Then, if no coding
     system in the list can handle the text, `select-safe-coding-system'
     queries the user immediately, without trying any of the three
     alternatives described above.

     The optional argument ACCEPT-DEFAULT-P, if non-`nil', should be a
     function to determine whether a coding system selected without
     user interaction is acceptable. `select-safe-coding-system' calls
     this function with one argument, the base coding system of the
     selected coding system.  If ACCEPT-DEFAULT-P returns `nil',
     `select-safe-coding-system' rejects the silently selected coding
     system, and asks the user to select a coding system from a list of
     possible candidates.

     If the variable `select-safe-coding-system-accept-default-p' is
     non-`nil', its value overrides the value of ACCEPT-DEFAULT-P.

     As a final step, before returning the chosen coding system,
     `select-safe-coding-system' checks whether that coding system is
     consistent with what would be selected if the contents of the
     region were read from a file.  (If not, this could lead to data
     corruption in a file subsequently re-visited and edited.)
     Normally, `select-safe-coding-system' uses `buffer-file-name' as
     the file for this purpose, but if FILE is non-`nil', it uses that
     file instead (this can be relevant for `write-region' and similar
     functions).  If it detects an apparent inconsistency,
     `select-safe-coding-system' queries the user before selecting the
     coding system.

   Here are two functions you can use to let the user specify a coding
system, with completion.  *Note Completion::.

 -- Function: read-coding-system prompt &optional default
     This function reads a coding system using the minibuffer,
     prompting with string PROMPT, and returns the coding system name
     as a symbol.  If the user enters null input, DEFAULT specifies
     which coding system to return.  It should be a symbol or a string.

 -- Function: read-non-nil-coding-system prompt
     This function reads a coding system using the minibuffer,
     prompting with string PROMPT, and returns the coding system name
     as a symbol.  If the user tries to enter null input, it asks the
     user to try again.  *Note Coding Systems::.


File: elisp,  Node: Default Coding Systems,  Next: Specifying Coding Systems,  Prev: User-Chosen Coding Systems,  Up: Coding Systems

33.10.5 Default Coding Systems
------------------------------

This section describes variables that specify the default coding system
for certain files or when running certain subprograms, and the function
that I/O operations use to access them.

   The idea of these variables is that you set them once and for all to
the defaults you want, and then do not change them again.  To specify a
particular coding system for a particular operation in a Lisp program,
don't change these variables; instead, override them using
`coding-system-for-read' and `coding-system-for-write' (*note
Specifying Coding Systems::).

 -- Variable: auto-coding-regexp-alist
     This variable is an alist of text patterns and corresponding coding
     systems. Each element has the form `(REGEXP . CODING-SYSTEM)'; a
     file whose first few kilobytes match REGEXP is decoded with
     CODING-SYSTEM when its contents are read into a buffer.  The
     settings in this alist take priority over `coding:' tags in the
     files and the contents of `file-coding-system-alist' (see below).
     The default value is set so that Emacs automatically recognizes
     mail files in Babyl format and reads them with no code conversions.

 -- Variable: file-coding-system-alist
     This variable is an alist that specifies the coding systems to use
     for reading and writing particular files.  Each element has the
     form `(PATTERN . CODING)', where PATTERN is a regular expression
     that matches certain file names.  The element applies to file
     names that match PATTERN.

     The CDR of the element, CODING, should be either a coding system,
     a cons cell containing two coding systems, or a function name (a
     symbol with a function definition).  If CODING is a coding system,
     that coding system is used for both reading the file and writing
     it.  If CODING is a cons cell containing two coding systems, its
     CAR specifies the coding system for decoding, and its CDR
     specifies the coding system for encoding.

     If CODING is a function name, the function should take one
     argument, a list of all arguments passed to
     `find-operation-coding-system'.  It must return a coding system or
     a cons cell containing two coding systems.  This value has the same
     meaning as described above.

 -- Variable: process-coding-system-alist
     This variable is an alist specifying which coding systems to use
     for a subprocess, depending on which program is running in the
     subprocess.  It works like `file-coding-system-alist', except that
     PATTERN is matched against the program name used to start the
     subprocess.  The coding system or systems specified in this alist
     are used to initialize the coding systems used for I/O to the
     subprocess, but you can specify other coding systems later using
     `set-process-coding-system'.

   *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 handles
asynchronous subprocess output in batches, as it arrives.  If the coding
system leaves the character code conversion unspecified, or leaves the
end-of-line conversion unspecified, Emacs must try to detect the proper
conversion from one batch at a time, and this does not always work.

   Therefore, with an asynchronous subprocess, if at all possible, use a
coding system which 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'.

 -- Variable: network-coding-system-alist
     This variable is an alist that specifies the coding system to use
     for network streams.  It works much like
     `file-coding-system-alist', with the difference that the PATTERN
     in an element may be either a port number or a regular expression.
     If it is a regular expression, it is matched against the network
     service name used to open the network stream.

 -- Variable: default-process-coding-system
     This variable specifies the coding systems to use for subprocess
     (and network stream) input and output, when nothing else specifies
     what to do.

     The value should be a cons cell of the form `(INPUT-CODING .
     OUTPUT-CODING)'.  Here INPUT-CODING applies to input from the
     subprocess, and OUTPUT-CODING applies to output to it.

 -- Variable: auto-coding-functions
     This variable holds a list of functions that try to determine a
     coding system for a file based on its undecoded contents.

     Each function in this list should be written to look at text in the
     current buffer, but should not modify it in any way.  The buffer
     will contain undecoded text of parts of the file.  Each function
     should take one argument, SIZE, which tells it how many characters
     to look at, starting from point.  If the function succeeds in
     determining a coding system for the file, it should return that
     coding system.  Otherwise, it should return `nil'.

     If a file has a `coding:' tag, that takes precedence, so these
     functions won't be called.

 -- Function: find-operation-coding-system operation &rest arguments
     This function returns the coding system to use (by default) for
     performing OPERATION with ARGUMENTS.  The value has this form:

          (DECODING-SYSTEM . ENCODING-SYSTEM)

     The first element, DECODING-SYSTEM, is the coding system to use
     for decoding (in case OPERATION does decoding), and
     ENCODING-SYSTEM is the coding system for encoding (in case
     OPERATION does encoding).

     The argument OPERATION is a symbol, one of `write-region',
     `start-process', `call-process', `call-process-region',
     `insert-file-contents', or `open-network-stream'.  These are the
     names of the Emacs I/O primitives that can do character code and
     eol conversion.

     The remaining arguments should be the same arguments that might be
     given to the corresponding I/O primitive.  Depending on the
     primitive, one of those arguments is selected as the "target".
     For example, if OPERATION does file I/O, whichever argument
     specifies the file name is the target.  For subprocess primitives,
     the process name is the target.  For `open-network-stream', the
     target is the service name or port number.

     Depending on OPERATION, this function looks up the target in
     `file-coding-system-alist', `process-coding-system-alist', or
     `network-coding-system-alist'.  If the target is found in the
     alist, `find-operation-coding-system' returns its association in
     the alist; otherwise it returns `nil'.

     If OPERATION is `insert-file-contents', the argument corresponding
     to the target may be a cons cell of the form `(FILENAME .
     BUFFER)').  In that case, FILENAME is a file name to look up in
     `file-coding-system-alist', and BUFFER is a buffer that contains
     the file's contents (not yet decoded).  If
     `file-coding-system-alist' specifies a function to call for this
     file, and that function needs to examine the file's contents (as
     it usually does), it should examine the contents of BUFFER instead
     of reading the file.


File: elisp,  Node: Specifying Coding Systems,  Next: Explicit Encoding,  Prev: Default Coding Systems,  Up: Coding Systems

33.10.6 Specifying a Coding System for One Operation
----------------------------------------------------

You can specify the coding system for a specific operation by binding
the variables `coding-system-for-read' and/or `coding-system-for-write'.

 -- Variable: coding-system-for-read
     If this variable is non-`nil', it specifies the coding system to
     use for reading a file, or for input from a synchronous subprocess.

     It also applies to any asynchronous subprocess or network stream,
     but in a different way: the value of `coding-system-for-read' when
     you start the subprocess or open the network stream specifies the
     input decoding method for that subprocess or network stream.  It
     remains in use for that subprocess or network stream unless and
     until overridden.

     The right way to use this variable is to bind it with `let' for a
     specific I/O operation.  Its global value is normally `nil', and
     you should not globally set it to any other value.  Here is an
     example of the right way to use the variable:

          ;; Read the file with no character code conversion.
          ;; Assume crlf represents end-of-line.
          (let ((coding-system-for-read 'emacs-mule-dos))
            (insert-file-contents filename))

     When its value is non-`nil', this variable takes precedence over
     all other methods of specifying a coding system to use for input,
     including `file-coding-system-alist',
     `process-coding-system-alist' and `network-coding-system-alist'.

 -- Variable: coding-system-for-write
     This works much like `coding-system-for-read', except that it
     applies to output rather than input.  It affects writing to files,
     as well as sending output to subprocesses and net connections.

     When a single operation does both input and output, as do
     `call-process-region' and `start-process', both
     `coding-system-for-read' and `coding-system-for-write' affect it.

 -- Variable: inhibit-eol-conversion
     When this variable is non-`nil', no end-of-line conversion is done,
     no matter which coding system is specified.  This applies to all
     the Emacs I/O and subprocess primitives, and to the explicit
     encoding and decoding functions (*note Explicit Encoding::).


File: elisp,  Node: Explicit Encoding,  Next: Terminal I/O Encoding,  Prev: Specifying Coding Systems,  Up: Coding Systems

33.10.7 Explicit Encoding and Decoding
--------------------------------------

All the operations that transfer text in and out of Emacs have the
ability to use a coding system to encode or decode the text.  You can
also explicitly encode and decode text using the functions in this
section.

   The result of encoding, and the input to decoding, are not ordinary
text.  They logically consist of a series of byte values; that is, a
series of characters whose codes are in the range 0 through 255.  In a
multibyte buffer or string, character codes 128 through 159 are
represented by multibyte sequences, but this is invisible to Lisp
programs.

   The usual way to read a file into a buffer as a sequence of bytes, so
you can decode the contents explicitly, is with
`insert-file-contents-literally' (*note Reading from Files::);
alternatively, specify a non-`nil' RAWFILE argument when visiting a
file with `find-file-noselect'.  These methods result in a unibyte
buffer.

   The usual way to use the byte sequence that results from explicitly
encoding text is to copy it to a file or process--for example, to write
it with `write-region' (*note Writing to Files::), and suppress
encoding by binding `coding-system-for-write' to `no-conversion'.

   Here are the functions to perform explicit encoding or decoding.  The
encoding functions produce sequences of bytes; the decoding functions
are meant to operate on sequences of bytes.  All of these functions
discard text properties.

 -- Command: encode-coding-region start end coding-system
     This command encodes the text from START to END according to
     coding system CODING-SYSTEM.  The encoded text replaces the
     original text in the buffer.  The result of encoding is logically a
     sequence of bytes, but the buffer remains multibyte if it was
     multibyte before.

     This command returns the length of the encoded text.

 -- Function: encode-coding-string string coding-system &optional nocopy
     This function encodes the text in STRING according to coding
     system CODING-SYSTEM.  It returns a new string containing the
     encoded text, except when NOCOPY is non-`nil', in which case the
     function may return STRING itself if the encoding operation is
     trivial.  The result of encoding is a unibyte string.

 -- Command: decode-coding-region start end coding-system
     This command decodes the text from START to END according to
     coding system CODING-SYSTEM.  The decoded text replaces the
     original text in the buffer.  To make explicit decoding useful,
     the text before decoding ought to be a sequence of byte values,
     but both multibyte and unibyte buffers are acceptable.

     This command returns the length of the decoded text.

 -- Function: decode-coding-string string coding-system &optional nocopy
     This function decodes the text in STRING according to coding
     system CODING-SYSTEM.  It returns a new string containing the
     decoded text, except when NOCOPY is non-`nil', in which case the
     function may return STRING itself if the decoding operation is
     trivial.  To make explicit decoding useful, the contents of STRING
     ought to be a sequence of byte values, but a multibyte string is
     acceptable.

 -- Function: decode-coding-inserted-region from to filename &optional
          visit beg end replace
     This function decodes the text from FROM to TO as if it were being
     read from file FILENAME using `insert-file-contents' using the
     rest of the arguments provided.

     The normal way to use this function is after reading text from a
     file without decoding, if you decide you would rather have decoded
     it.  Instead of deleting the text and reading it again, this time
     with decoding, you can call this function.


File: elisp,  Node: Terminal I/O Encoding,  Next: MS-DOS File Types,  Prev: Explicit Encoding,  Up: Coding Systems

33.10.8 Terminal I/O Encoding
-----------------------------

Emacs can decode keyboard input using a coding system, and encode
terminal output.  This is useful for terminals that transmit or display
text using a particular encoding such as Latin-1.  Emacs does not set
`last-coding-system-used' for encoding or decoding for the terminal.

 -- Function: keyboard-coding-system
     This function returns the coding system that is in use for decoding
     keyboard input--or `nil' if no coding system is to be used.

 -- Command: set-keyboard-coding-system coding-system
     This command specifies CODING-SYSTEM as the coding system to use
     for decoding keyboard input.  If CODING-SYSTEM is `nil', that
     means do not decode keyboard input.

 -- Function: terminal-coding-system
     This function returns the coding system that is in use for encoding
     terminal output--or `nil' for no encoding.

 -- Command: set-terminal-coding-system coding-system
     This command specifies CODING-SYSTEM as the coding system to use
     for encoding terminal output.  If CODING-SYSTEM is `nil', that
     means do not encode terminal output.


File: elisp,  Node: MS-DOS File Types,  Prev: Terminal I/O Encoding,  Up: Coding Systems

33.10.9 MS-DOS File Types
-------------------------

On MS-DOS and Microsoft Windows, Emacs guesses the appropriate
end-of-line conversion for a file by looking at the file's name.  This
feature classifies files as "text files" and "binary files".  By
"binary file" we mean a file of literal byte values that are not
necessarily meant to be characters; Emacs does no end-of-line conversion
and no character code conversion for them.  On the other hand, the bytes
in a text file are intended to represent characters; when you create a
new file whose name implies that it is a text file, Emacs uses DOS
end-of-line conversion.

 -- Variable: buffer-file-type
     This variable, automatically buffer-local in each buffer, records
     the file type of the buffer's visited file.  When a buffer does
     not specify a coding system with `buffer-file-coding-system', this
     variable is used to determine which coding system to use when
     writing the contents of the buffer.  It should be `nil' for text,
     `t' for binary.  If it is `t', the coding system is
     `no-conversion'.  Otherwise, `undecided-dos' is used.

     Normally this variable is set by visiting a file; it is set to
     `nil' if the file was visited without any actual conversion.

 -- User Option: file-name-buffer-file-type-alist
     This variable holds an alist for recognizing text and binary files.
     Each element has the form (REGEXP . TYPE), where REGEXP is matched
     against the file name, and TYPE may be `nil' for text, `t' for
     binary, or a function to call to compute which.  If it is a
     function, then it is called with a single argument (the file name)
     and should return `t' or `nil'.

     When running on MS-DOS or MS-Windows, Emacs checks this alist to
     decide which coding system to use when reading a file.  For a text
     file, `undecided-dos' is used.  For a binary file, `no-conversion'
     is used.

     If no element in this alist matches a given file name, then
     `default-buffer-file-type' says how to treat the file.

 -- User Option: default-buffer-file-type
     This variable says how to handle files for which
     `file-name-buffer-file-type-alist' says nothing about the type.

     If this variable is non-`nil', then these files are treated as
     binary: the coding system `no-conversion' is used.  Otherwise,
     nothing special is done for them--the coding system is deduced
     solely from the file contents, in the usual Emacs fashion.


File: elisp,  Node: Input Methods,  Next: Locales,  Prev: Coding Systems,  Up: Non-ASCII Characters

33.11 Input Methods
===================

"Input methods" provide convenient ways of entering non-ASCII
characters from the keyboard.  Unlike coding systems, which translate
non-ASCII characters to and from encodings meant to be read by
programs, input methods provide human-friendly commands.  (*Note Input
Methods: (emacs)Input Methods, for information on how users use input
methods to enter text.)  How to define input methods is not yet
documented in this manual, but here we describe how to use them.

   Each input method has a name, which is currently a string; in the
future, symbols may also be usable as input method names.

 -- Variable: current-input-method
     This variable holds the name of the input method now active in the
     current buffer.  (It automatically becomes local in each buffer
     when set in any fashion.)  It is `nil' if no input method is
     active in the buffer now.

 -- User Option: default-input-method
     This variable holds the default input method for commands that
     choose an input method.  Unlike `current-input-method', this
     variable is normally global.

 -- Command: set-input-method input-method
     This command activates input method INPUT-METHOD for the current
     buffer.  It also sets `default-input-method' to INPUT-METHOD.  If
     INPUT-METHOD is `nil', this command deactivates any input method
     for the current buffer.

 -- Function: read-input-method-name prompt &optional default
          inhibit-null
     This function reads an input method name with the minibuffer,
     prompting with PROMPT.  If DEFAULT is non-`nil', that is returned
     by default, if the user enters empty input.  However, if
     INHIBIT-NULL is non-`nil', empty input signals an error.

     The returned value is a string.

 -- Variable: input-method-alist
     This variable defines all the supported input methods.  Each
     element defines one input method, and should have the form:

          (INPUT-METHOD LANGUAGE-ENV ACTIVATE-FUNC
           TITLE DESCRIPTION ARGS...)

     Here INPUT-METHOD is the input method name, a string; LANGUAGE-ENV
     is another string, the name of the language environment this input
     method is recommended for.  (That serves only for documentation
     purposes.)

     ACTIVATE-FUNC is a function to call to activate this method.  The
     ARGS, if any, are passed as arguments to ACTIVATE-FUNC.  All told,
     the arguments to ACTIVATE-FUNC are INPUT-METHOD and the ARGS.

     TITLE is a string to display in the mode line while this method is
     active.  DESCRIPTION is a string describing this method and what
     it is good for.

   The fundamental interface to input methods is through the variable
`input-method-function'.  *Note Reading One Event::, and *note Invoking
the Input Method::.


File: elisp,  Node: Locales,  Prev: Input Methods,  Up: Non-ASCII Characters

33.12 Locales
=============

POSIX defines a concept of "locales" which control which language to
use in language-related features.  These Emacs variables control how
Emacs interacts with these features.

 -- Variable: locale-coding-system
     This variable specifies the coding system to use for decoding
     system error messages and--on X Window system only--keyboard
     input, for encoding the format argument to `format-time-string',
     and for decoding the return value of `format-time-string'.

 -- Variable: system-messages-locale
     This variable specifies the locale to use for generating system
     error messages.  Changing the locale can cause messages to come
     out in a different language or in a different orthography.  If the
     variable is `nil', the locale is specified by environment
     variables in the usual POSIX fashion.

 -- Variable: system-time-locale
     This variable specifies the locale to use for formatting time
     values.  Changing the locale can cause messages to appear
     according to the conventions of a different language.  If the
     variable is `nil', the locale is specified by environment
     variables in the usual POSIX fashion.

 -- Function: locale-info item
     This function returns locale data ITEM for the current POSIX
     locale, if available.  ITEM should be one of these symbols:

    `codeset'
          Return the character set as a string (locale item `CODESET').

    `days'
          Return a 7-element vector of day names (locale items `DAY_1'
          through `DAY_7');

    `months'
          Return a 12-element vector of month names (locale items
          `MON_1' through `MON_12').

    `paper'
          Return a list `(WIDTH HEIGHT)' for the default paper size
          measured in millimeters (locale items `PAPER_WIDTH' and
          `PAPER_HEIGHT').

     If the system can't provide the requested information, or if ITEM
     is not one of those symbols, the value is `nil'.  All strings in
     the return value are decoded using `locale-coding-system'.  *Note
     Locales: (libc)Locales, for more information about locales and
     locale items.


File: elisp,  Node: Searching and Matching,  Next: Syntax Tables,  Prev: Non-ASCII Characters,  Up: Top

34 Searching and Matching
*************************

GNU Emacs provides two ways to search through a buffer for specified
text: exact string searches and regular expression searches.  After a
regular expression search, you can examine the "match data" to
determine which text matched the whole regular expression or various
portions of it.

* Menu:

* String Search::         Search for an exact match.
* Searching and Case::    Case-independent or case-significant searching.
* Regular Expressions::   Describing classes of strings.
* Regexp Search::         Searching for a match for a regexp.
* POSIX Regexps::         Searching POSIX-style for the longest match.
* Match Data::            Finding out which part of the text matched,
                            after a string or regexp search.
* Search and Replace::	  Commands that loop, searching and replacing.
* Standard Regexps::      Useful regexps for finding sentences, pages,...

   The `skip-chars...' functions also perform a kind of searching.
*Note Skipping Characters::.  To search for changes in character
properties, see *note Property Search::.


File: elisp,  Node: String Search,  Next: Searching and Case,  Up: Searching and Matching

34.1 Searching for Strings
==========================

These are the primitive functions for searching through the text in a
buffer.  They are meant for use in programs, but you may call them
interactively.  If you do so, they prompt for the search string; the
arguments LIMIT and NOERROR are `nil', and REPEAT is 1.

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

 -- Command: search-forward string &optional limit noerror repeat
     This function searches forward from point for an exact match for
     STRING.  If successful, it sets point to the end of the occurrence
     found, and returns the new value of point.  If no match is found,
     the value and side effects depend on NOERROR (see below).

     In the following example, point is initially at the beginning of
     the line.  Then `(search-forward "fox")' moves point after the last
     letter of `fox':

          ---------- Buffer: foo ----------
          -!-The quick brown fox jumped over the lazy dog.
          ---------- Buffer: foo ----------

          (search-forward "fox")
               => 20

          ---------- Buffer: foo ----------
          The quick brown fox-!- jumped over the lazy dog.
          ---------- Buffer: foo ----------

     The argument LIMIT specifies the upper bound to the search.  (It
     must be a position in the current buffer.)  No match extending
     after that position is accepted.  If LIMIT is omitted or `nil', it
     defaults to the end of the accessible portion of the buffer.

     What happens when the search fails depends on the value of
     NOERROR.  If NOERROR is `nil', a `search-failed' error is
     signaled.  If NOERROR is `t', `search-forward' returns `nil' and
     does nothing.  If NOERROR is neither `nil' nor `t', then
     `search-forward' moves point to the upper bound and returns `nil'.
     (It would be more consistent now to return the new position of
     point in that case, but some existing programs may depend on a
     value of `nil'.)

     The argument NOERROR only affects valid searches which fail to
     find a match.  Invalid arguments cause errors regardless of
     NOERROR.

     If REPEAT is supplied (it must be a positive number), then the
     search is repeated that many times (each time starting at the end
     of the previous time's match).  If these successive searches
     succeed, the function succeeds, moving point and returning its new
     value.  Otherwise the search fails, with results depending on the
     value of NOERROR, as described above.

 -- Command: search-backward string &optional limit noerror repeat
     This function searches backward from point for STRING.  It is just
     like `search-forward' except that it searches backwards and leaves
     point at the beginning of the match.

 -- Command: word-search-forward string &optional limit noerror repeat
     This function searches forward from point for a "word" match for
     STRING.  If it finds a match, it sets point to the end of the
     match found, and returns the new value of point.

     Word matching regards STRING as a sequence of words, disregarding
     punctuation that separates them.  It searches the buffer for the
     same sequence of words.  Each word must be distinct in the buffer
     (searching for the word `ball' does not match the word `balls'),
     but the details of punctuation and spacing are ignored (searching
     for `ball boy' does match `ball.  Boy!').

     In this example, point is initially at the beginning of the
     buffer; the search leaves it between the `y' and the `!'.

          ---------- Buffer: foo ----------
          -!-He said "Please!  Find
          the ball boy!"
          ---------- Buffer: foo ----------

          (word-search-forward "Please find the ball, boy.")
               => 35

          ---------- Buffer: foo ----------
          He said "Please!  Find
          the ball boy-!-!"
          ---------- Buffer: foo ----------

     If LIMIT is non-`nil', it must be a position in the current
     buffer; it specifies the upper bound to the search.  The match
     found must not extend after that position.

     If NOERROR is `nil', then `word-search-forward' signals an error
     if the search fails.  If NOERROR is `t', then it returns `nil'
     instead of signaling an error.  If NOERROR is neither `nil' nor
     `t', it moves point to LIMIT (or the end of the accessible portion
     of the buffer) and returns `nil'.

     If REPEAT is non-`nil', then the search is repeated that many
     times.  Point is positioned at the end of the last match.

 -- Command: word-search-backward string &optional limit noerror repeat
     This function searches backward from point for a word match to
     STRING.  This function is just like `word-search-forward' except
     that it searches backward and normally leaves point at the
     beginning of the match.


File: elisp,  Node: Searching and Case,  Next: Regular Expressions,  Prev: String Search,  Up: Searching and Matching

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

By default, searches in Emacs ignore the case of the text they are
searching through; if you specify searching for `FOO', then `Foo' or
`foo' is also considered a match.  This applies to regular expressions,
too; thus, `[aB]' would match `a' or `A' or `b' or `B'.

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

   Note that the user-level incremental search feature handles case
distinctions differently.  When given a lower case letter, it looks for
a match of either case, but when given an upper case letter, it looks
for an upper case letter only.  But this has nothing to do with the
searching functions used in Lisp code.

 -- User Option: case-replace
     This variable determines whether the higher level replacement
     functions should preserve case.  If the variable is `nil', that
     means to use the replacement text verbatim.  A non-`nil' value
     means to convert the case of the replacement text according to the
     text being replaced.

     This variable is used by passing it as an argument to the function
     `replace-match'.  *Note Replacing Match::.

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

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


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

34.3 Regular Expressions
========================

A "regular expression" ("regexp", for short) is a pattern that denotes
a (possibly infinite) set of strings.  Searching for matches for a
regexp is a very powerful operation.  This section explains how to write
regexps; the following section says how to search for them.

   For convenient interactive development of regular expressions, you
can use the `M-x re-builder' command.  It provides a convenient
interface for creating regular expressions, by giving immediate visual
feedback in a separate buffer.  As you edit the regexp, all its matches
in the target buffer are highlighted.  Each parenthesized
sub-expression of the regexp is shown in a distinct face, which makes
it easier to verify even very complex regexps.

* Menu:

* Syntax of Regexps::       Rules for writing regular expressions.
* Regexp Example::          Illustrates regular expression syntax.
* Regexp Functions::        Functions for operating on regular expressions.


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

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

Regular expressions have a syntax in which a few characters are special
constructs and the rest are "ordinary".  An ordinary character is a
simple regular expression that matches that character and nothing else.
The special characters are `.', `*', `+', `?', `[', `^', `$', and `\';
no new special characters will be defined in the future.  The character
`]' is special if it ends a character alternative (see later).  The
character `-' is special inside a character alternative.  A `[:' and
balancing `:]' enclose a character class inside a character
alternative.  Any other character appearing in a regular expression is
ordinary, unless a `\' precedes it.

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

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

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

* Menu:

* Regexp Special::      Special characters in regular expressions.
* Char Classes::        Character classes used in regular expressions.
* Regexp Backslash::    Backslash-sequences in regular expressions.


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), from which 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.

     The beginning and end of a range of multibyte characters must be in
     the same character set (*note Character Sets::).  Thus,
     `"[\x8e0-\x97c]"' is invalid because character 0x8e0 (`a' with
     grave accent) is in the Emacs character set for Latin-1 but the
     character 0x97c (`u' with diaeresis) is in the Emacs character set
     for Latin-2.  (We use Lisp string syntax to write that example,
     and a few others in the next few paragraphs, in order to include
     hex escape sequences in them.)

     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.

     You cannot always match all non-ASCII characters with the regular
     expression `"[\200-\377]"'.  This works when searching a unibyte
     buffer or string (*note Text Representations::), but not in a
     multibyte buffer or string, because many non-ASCII characters have
     codes above octal 0377.  However, the regular expression
     `"[^\000-\177]"' does match all non-ASCII characters (see below
     regarding `^'), in both multibyte and unibyte representations,
     because only the ASCII characters are excluded.

     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'.

`^'
     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::).

`[: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::).

`[: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 any ordinary, non-shy groups.

`\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.)


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: 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::.

     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
     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.

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

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

 -- 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.  This is because POSIX backtracking
conflicts with the semantics of non-greedy repetition.

 -- Function: 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.

 -- Function: 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\)'.


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))
         => (9 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'.

 -- 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.


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:

 -- Variable: 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.

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

 -- Variable: 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).

 -- Variable: 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.  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
     This function flushes the cache used by `syntax-ppss', starting at
     position BEG.

   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 character category &optional table
          reset
     This function modifies the category set of CHARACTER in category
     table TABLE (which defaults to the current buffer's category
     table).

     Normally, it modifies the 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 containing a symbol for
each abbreviation.  The symbol's name is the abbreviation; its value is
the expansion; its function definition is the hook function to do the
expansion (*note Defining Abbrevs::); its property list cell typically
contains the use count, the number of times the abbreviation has been
expanded.  Alternatively, the use count is on the `count' property and
the system-abbrev flag is on the `system-type' property.  Abbrevs with
a non-`nil' `system-type' property are called "system" abbrevs.  They
are usually defined by modes or packages, instead of by the user, and
are treated specially in certain respects.

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

   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.


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 value of the variable
`abbrev-mode'.

 -- Variable: abbrev-mode
     A non-`nil' value of this variable turns on the automatic expansion
     of abbrevs when their abbreviations are inserted into a 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.

 -- Variable: default-abbrev-mode
     This is the value of `abbrev-mode' for buffers that do not
     override it.  This is the same as `(default-value 'abbrev-mode)'.


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
     This function creates and returns a new, empty abbrev table--an
     obarray containing no symbols.  It is a vector filled with zeros.

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

 -- Function: copy-abbrev-table table
     This function returns a copy of abbrev table TABLE--a new abbrev
     table that contains the same abbrev definitions.  The only
     difference between TABLE and the returned copy is that this
     function sets the property lists of all copied abbrevs to 0.

 -- Function: define-abbrev-table tabname definitions
     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 USECOUNT SYSTEM-FLAG)'.
     If an element of DEFINITIONS has length less than five, omitted
     elements default to `nil'.  A value of `nil' for USECOUNT is
     equivalent to zero.  The return value is always `nil'.

     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 a specified abbrev table.  When major modes predefine standard
abbrevs, they should call `define-abbrev' and specify `t' for
SYSTEM-FLAG.  Be aware that any saved non-"system" abbrevs are restored
at startup, i.e. before some major modes are loaded.  Major modes
should therefore not assume that when they are first loaded their abbrev
tables are empty.

 -- Function: define-abbrev table name expansion &optional hook count
          system-flag
     This function defines an abbrev named NAME, in TABLE, to expand to
     EXPANSION and call HOOK.  The return value is NAME.

     The value of COUNT, if specified, initializes the abbrev's
     usage-count.  If COUNT is not specified or `nil', the use count is
     initialized to zero.

     The argument 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.

     If SYSTEM-FLAG is non-`nil', that marks the abbrev as a "system"
     abbrev with the `system-type' property.  Unless SYSTEM-FLAG has
     the value `force', a "system" abbrev will not overwrite an
     existing definition for a non-"system" abbrev of the same name.

     Normally the function `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 won't be 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
     to look it up in.  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.

 -- 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: pre-abbrev-expand-hook
     This is a normal hook whose functions are executed, in sequence,
     just before any expansion of an abbrev.  *Note Hooks::.  Since it
     is a normal hook, the hook functions receive no arguments.
     However, they can find the abbrev to be expanded by looking in the
     buffer before point.  Running the hook is the first thing that
     `expand-abbrev' does, and so a hook function can be used to change
     the current abbrev table before abbrev lookup happens.  (Although
     you have to do this carefully.  See the example below.)

   The following sample code shows a simple use of
`pre-abbrev-expand-hook'.  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-pre-abbrev-expand ()
       (when (save-excursion (forward-line 0) (eq (char-after) ?#))
         (let ((local-abbrev-table text-mode-abbrev-table)
     	  ;; Avoid infinite loop.
     	  (pre-abbrev-expand-hook nil))
           (expand-abbrev))
         ;; We have already called `expand-abbrev' in this hook.
         ;; Hence we want the "actual" call following this hook to be a no-op.
         (setq abbrev-start-location (point-max)
     	  abbrev-start-location-buffer (current-buffer))))

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

   Note that `foo-mode-pre-abbrev-expand' just returns `nil' without
doing anything for lines not starting with `#'.  Hence abbrevs expand
normally using `foo-mode-abbrev-table' as local abbrev table for such
lines.


File: elisp,  Node: Standard Abbrev Tables,  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.

 -- 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: 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 is a process, `nil' otherwise.

* 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.
* 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 network connections.
* 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 functions 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))

