This is ../info/lispref.info, produced by makeinfo version 4.7 from
lispref/lispref.texi.

INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* Lispref: (lispref).		XEmacs Lisp Reference Manual.
END-INFO-DIR-ENTRY

   Edition History:

   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
Copyright (C) 1995, 1996 Ben Wing.

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

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

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

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

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


File: lispref.info,  Node: Text,  Next: Searching and Matching,  Prev: Markers,  Up: Top

43 Text
*******

This chapter describes the functions that deal with the text in a
buffer.  Most examine, insert, or delete text in the current buffer,
often in the vicinity of point.  Many are interactive.  All the
functions that change the text provide for undoing the changes (*note
Undo::).

   Many text-related functions operate on a region of text defined by
two buffer positions passed in arguments named START and END.  These
arguments should be either markers (*note Markers::) or numeric
character positions (*note Positions::).  The order of these arguments
does not matter; it is all right for START to be the end of the region
and END the beginning.  For example, `(delete-region 1 10)' and
`(delete-region 10 1)' are equivalent.  An `args-out-of-range' error is
signaled if either START or END is outside the accessible portion of
the buffer.  In an interactive call, point and the mark are used for
these arguments.

   Throughout this chapter, "text" refers to the characters in the
buffer, together with their properties (when relevant).

* Menu:

* Near Point::       Examining text in the vicinity of point.
* Buffer Contents::  Examining text in a general fashion.
* Comparing Text::   Comparing substrings of buffers.
* Insertion::        Adding new text to a buffer.
* Commands for Insertion::  User-level commands to insert text.
* Deletion::         Removing text from a buffer.
* User-Level Deletion::     User-level commands to delete text.
* The Kill Ring::    Where removed text sometimes is saved for later use.
* Undo::             Undoing changes to the text of a buffer.
* Maintaining Undo:: How to enable and disable undo information.
			How to control how much information is kept.
* Filling::          Functions for explicit filling.
* Margins::          How to specify margins for filling commands.
* Auto Filling::     How auto-fill mode is implemented to break lines.
* Sorting::          Functions for sorting parts of the buffer.
* Columns::          Computing horizontal positions, and using them.
* Indentation::      Functions to insert or adjust indentation.
* Case Changes::     Case conversion of parts of the buffer.
* Text Properties::  Assigning Lisp property lists to text characters.
* Substitution::     Replacing a given character wherever it appears.
* Registers::        How registers are implemented.  Accessing the text or
                       position stored in a register.
* Transposition::    Swapping two portions of a buffer.
* Change Hooks::     Supplying functions to be run when text is changed.
* Transformations::  MD5 and base64 support.


File: lispref.info,  Node: Near Point,  Next: Buffer Contents,  Up: Text

43.1 Examining Text Near Point
==============================

Many functions are provided to look at the characters around point.
Several simple functions are described here.  See also `looking-at' in
*Note Regexp Search::.

   Many of these functions take an optional BUFFER argument.  In all
such cases, the current buffer will be used if this argument is
omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions
usually did not have these optional BUFFER arguments and always
operated on the current buffer.)

 -- Function: char-after &optional position buffer
     This function returns the character in the buffer at (i.e.,
     immediately after) position POSITION.  If POSITION is out of range
     for this purpose, either before the beginning of the buffer, or at
     or beyond the end, then the value is `nil'.  The default for
     POSITION is point.  If optional argument BUFFER is `nil', the
     current buffer is assumed.

     In the following example, assume that the first character in the
     buffer is `@':

          (char-to-string (char-after 1))
               => "@"

 -- Function: char-before &optional position buffer
     This function returns the character in the current buffer
     immediately before position POSITION.  If POSITION is out of range
     for this purpose, either at or before the beginning of the buffer,
     or beyond the end, then the value is `nil'.  The default for
     POSITION is point.  If optional argument BUFFER is `nil', the
     current buffer is assumed.

 -- Function: following-char &optional buffer
     This function returns the character following point in the buffer.
     This is similar to `(char-after (point))'.  However, if point is at
     the end of the buffer, then the result of `following-char' is 0.
     If optional argument BUFFER is `nil', the current buffer is
     assumed.

     Remember that point is always between characters, and the terminal
     cursor normally appears over the character following point.
     Therefore, the character returned by `following-char' is the
     character the cursor is over.

     In this example, point is between the `a' and the `c'.

          ---------- Buffer: foo ----------
          Gentlemen may cry ``Pea-!-ce! Peace!,''
          but there is no peace.
          ---------- Buffer: foo ----------

          (char-to-string (preceding-char))
               => "a"
          (char-to-string (following-char))
               => "c"

 -- Function: preceding-char &optional buffer
     This function returns the character preceding point in the buffer.
     See above, under `following-char', for an example.  If point is at
     the beginning of the buffer, `preceding-char' returns 0.  If
     optional argument BUFFER is `nil', the current buffer is assumed.

 -- Function: bobp &optional buffer
     This function returns `t' if point is at the beginning of the
     buffer.  If narrowing is in effect, this means the beginning of the
     accessible portion of the text.  If optional argument BUFFER is
     `nil', the current buffer is assumed.  See also `point-min' in
     *Note Point::.

 -- Function: eobp &optional buffer
     This function returns `t' if point is at the end of the buffer.
     If narrowing is in effect, this means the end of accessible
     portion of the text.  If optional argument BUFFER is `nil', the
     current buffer is assumed.  See also `point-max' in *Note Point::.

 -- Function: bolp &optional buffer
     This function returns `t' if point is at the beginning of a line.
     If optional argument BUFFER is `nil', the current buffer is
     assumed.  *Note Text Lines::.  The beginning of the buffer (or its
     accessible portion) always counts as the beginning of a line.

 -- Function: eolp &optional buffer
     This function returns `t' if point is at the end of a line.  The
     end of the buffer is always considered the end of a line.  If
     optional argument BUFFER is `nil', the current buffer is assumed.
     The end of the buffer (or of its accessible portion) is always
     considered the end of a line.


File: lispref.info,  Node: Buffer Contents,  Next: Comparing Text,  Prev: Near Point,  Up: Text

43.2 Examining Buffer Contents
==============================

This section describes two functions that allow a Lisp program to
convert any portion of the text in the buffer into a string.

 -- Function: buffer-substring start end &optional buffer
 -- Function: buffer-string start end &optional buffer
     These functions are equivalent and return a string containing a
     copy of the text of the region defined by positions START and END
     in the buffer.  If the arguments are not positions in the
     accessible portion of the buffer, `buffer-substring' signals an
     `args-out-of-range' error.  If optional argument BUFFER is `nil',
     the current buffer is assumed.

     If the region delineated by START and END contains duplicable
     extents, they will be remembered in the string.  *Note Duplicable
     Extents::.

     It is not necessary for START to be less than END; the arguments
     can be given in either order.  But most often the smaller argument
     is written first.

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

          ---------- Buffer: foo ----------

          (buffer-substring 1 10)
          => "This is t"
          (buffer-substring (point-max) 10)
          => "he contents of buffer foo
          "


File: lispref.info,  Node: Comparing Text,  Next: Insertion,  Prev: Buffer Contents,  Up: Text

43.3 Comparing Text
===================

This function lets you compare portions of the text in a buffer, without
copying them into strings first.

 -- Function: compare-buffer-substrings buffer1 start1 end1 buffer2
          start2 end2
     This function lets you compare two substrings of the same buffer
     or two different buffers.  The first three arguments specify one
     substring, giving a buffer and two positions within the buffer.
     The last three arguments specify the other substring in the same
     way.  You can use `nil' for BUFFER1, BUFFER2, or both to stand for
     the current buffer.

     The value is negative if the first substring is less, positive if
     the first is greater, and zero if they are equal.  The absolute
     value of the result is one plus the index of the first differing
     characters within the substrings.

     This function ignores case when comparing characters if
     `case-fold-search' is non-`nil'.  It always ignores text
     properties.

     Suppose the current buffer contains the text `foobarbar
     haha!rara!'; then in this example the two substrings are `rbar '
     and `rara!'.  The value is 2 because the first substring is greater
     at the second character.

          (compare-buffer-substring nil 6 11 nil 16 21)
               => 2


File: lispref.info,  Node: Insertion,  Next: Commands for Insertion,  Prev: Comparing Text,  Up: Text

43.4 Inserting Text
===================

"Insertion" means adding new text to a buffer.  The inserted text goes
at point--between the character before point and the character after
point.

   Insertion relocates markers that point at positions after the
insertion point, so that they stay with the surrounding text (*note
Markers::).  When a marker points at the place of insertion, insertion
normally doesn't relocate the marker, so that it points to the
beginning of the inserted text; however, certain special functions such
as `insert-before-markers' relocate such markers to point after the
inserted text.

   Some insertion functions leave point before the inserted text, while
other functions leave it after.  We call the former insertion "after
point" and the latter insertion "before point".

   If a string with non-`nil' extent data is inserted, the remembered
extents will also be inserted.  *Note Duplicable Extents::.

   Insertion functions signal an error if the current buffer is
read-only.

   These functions copy text characters from strings and buffers along
with their properties.  The inserted characters have exactly the same
properties as the characters they were copied from.  By contrast,
characters specified as separate arguments, not part of a string or
buffer, inherit their text properties from the neighboring text.

 -- Function: insert &rest args
     This function inserts the strings and/or characters ARGS into the
     current buffer, at point, moving point forward.  In other words, it
     inserts the text before point.  An error is signaled unless all
     ARGS are either strings or characters.  The value is `nil'.

 -- Function: insert-before-markers &rest args
     This function inserts the strings and/or characters ARGS into the
     current buffer, at point, moving point forward.  An error is
     signaled unless all ARGS are either strings or characters.  The
     value is `nil'.

     This function is unlike the other insertion functions in that it
     relocates markers initially pointing at the insertion point, to
     point after the inserted text.

 -- Function: insert-string string &optional buffer
     This function inserts STRING into BUFFER before point.  BUFFER
     defaults to the current buffer if omitted.  This function is
     chiefly useful if you want to insert a string in a buffer other
     than the current one (otherwise you could just use `insert').

 -- Function: insert-char character &optional count ignored buffer
     This function inserts COUNT instances of CHARACTER into BUFFER
     before point.  COUNT must be a number, and CHARACTER must be a
     character.

     If optional argument BUFFER is `nil', the current buffer is
     assumed. (In FSF Emacs, the third argument is called INHERIT and
     refers to text properties.  In XEmacs, it is always ignored.)

     This function always returns `nil'.

 -- Function: insert-buffer-substring from-buffer-or-name &optional
          start end
     This function inserts a portion of buffer FROM-BUFFER-OR-NAME
     (which must already exist) into the current buffer before point.
     The text inserted is the region from START and END.  (These
     arguments default to the beginning and end of the accessible
     portion of that buffer.)  This function returns `nil'.

     In this example, the form is executed with buffer `bar' as the
     current buffer.  We assume that buffer `bar' is initially empty.

          ---------- Buffer: foo ----------
          We hold these truths to be self-evident, that all
          ---------- Buffer: foo ----------

          (insert-buffer-substring "foo" 1 20)
               => nil

          ---------- Buffer: bar ----------
          We hold these truth-!-
          ---------- Buffer: bar ----------


File: lispref.info,  Node: Commands for Insertion,  Next: Deletion,  Prev: Insertion,  Up: Text

43.5 User-Level Insertion Commands
==================================

This section describes higher-level commands for inserting text,
commands intended primarily for the user but useful also in Lisp
programs.

 -- Command: insert-buffer from-buffer-or-name
     This command inserts the entire contents of FROM-BUFFER-OR-NAME
     (which must exist) into the current buffer after point.  It leaves
     the mark after the inserted text.  The value is `nil'.

 -- Command: self-insert-command count
     This command inserts the last character typed; it does so COUNT
     times, before point, and returns `nil'.  Most printing characters
     are bound to this command.  In routine use, `self-insert-command'
     is the most frequently called function in XEmacs, but programs
     rarely use it except to install it on a keymap.

     In an interactive call, COUNT is the numeric prefix argument.

     This command calls `auto-fill-function' whenever that is non-`nil'
     and the character inserted is a space or a newline (*note Auto
     Filling::).

     This command performs abbrev expansion if Abbrev mode is enabled
     and the inserted character does not have word-constituent syntax.
     (*Note Abbrevs::, and *Note Syntax Class Table::.)

     This is also responsible for calling `blink-paren-function' when
     the inserted character has close parenthesis syntax (*note
     Blinking::).

 -- Command: newline &optional count
     This command inserts newlines into the current buffer before point.
     If COUNT is supplied, that many newline characters are inserted.

     This function calls `auto-fill-function' if the current column
     number is greater than the value of `fill-column' and COUNT is
     `nil'.  Typically what `auto-fill-function' does is insert a
     newline; thus, the overall result in this case is to insert two
     newlines at different places: one at point, and another earlier in
     the line.  `newline' does not auto-fill if COUNT is non-`nil'.

     This command indents to the left margin if that is not zero.
     *Note Margins::.

     The value returned is `nil'.  In an interactive call, COUNT is the
     numeric prefix argument.

 -- Command: split-line
     This command splits the current line, moving the portion of the
     line after point down vertically so that it is on the next line
     directly below where it was before.  Whitespace is inserted as
     needed at the beginning of the lower line, using the `indent-to'
     function.  `split-line' returns the position of point.

     Programs hardly ever use this function.

 -- Variable: overwrite-mode
     This variable controls whether overwrite mode is in effect: a
     non-`nil' value enables the mode.  It is automatically made
     buffer-local when set in any fashion.


File: lispref.info,  Node: Deletion,  Next: User-Level Deletion,  Prev: Commands for Insertion,  Up: Text

43.6 Deleting Text
==================

Deletion means removing part of the text in a buffer, without saving it
in the kill ring (*note The Kill Ring::).  Deleted text can't be
yanked, but can be reinserted using the undo mechanism (*note Undo::).
Some deletion functions do save text in the kill ring in some special
cases.

   All of the deletion functions operate on the current buffer, and all
return a value of `nil'.

 -- Command: erase-buffer &optional buffer
     This function deletes the entire text of BUFFER, leaving it empty.
     If the buffer is read-only, it signals a `buffer-read-only'
     error.  Otherwise, it deletes the text without asking for any
     confirmation.  It returns `nil'.  BUFFER defaults to the current
     buffer if omitted.

     Normally, deleting a large amount of text from a buffer inhibits
     further auto-saving of that buffer "because it has shrunk".
     However, `erase-buffer' does not do this, the idea being that the
     future text is not really related to the former text, and its size
     should not be compared with that of the former text.

 -- Command: delete-region start end &optional buffer
     This command deletes the text in BUFFER in the region defined by
     START and END.  The value is `nil'.  If optional argument BUFFER
     is `nil', the current buffer is assumed.

 -- Command: delete-char &optional count killp
     This command deletes COUNT characters directly after point, or
     before point if COUNT is negative.  COUNT defaults to `1'.  If
     KILLP is non-`nil', then it saves the deleted characters in the
     kill ring.

     In an interactive call, COUNT is the numeric prefix argument, and
     KILLP is the unprocessed prefix argument.  Therefore, if a prefix
     argument is supplied, the text is saved in the kill ring.  If no
     prefix argument is supplied, then one character is deleted, but
     not saved in the kill ring.

     The value returned is always `nil'.

 -- Command: delete-backward-char &optional count killp
     This command deletes COUNT characters directly before point, or
     after point if COUNT is negative.  COUNT defaults to 1.  If KILLP
     is non-`nil', then it saves the deleted characters in the kill
     ring.

     In an interactive call, COUNT is the numeric prefix argument, and
     KILLP is the unprocessed prefix argument.  Therefore, if a prefix
     argument is supplied, the text is saved in the kill ring.  If no
     prefix argument is supplied, then one character is deleted, but
     not saved in the kill ring.

     The value returned is always `nil'.

 -- Command: backward-delete-char-untabify count &optional killp
     This command deletes COUNT characters backward, changing tabs into
     spaces.  When the next character to be deleted is a tab, it is
     first replaced with the proper number of spaces to preserve
     alignment and then one of those spaces is deleted instead of the
     tab.  If KILLP is non-`nil', then the command saves the deleted
     characters in the kill ring.

     Conversion of tabs to spaces happens only if COUNT is positive.
     If it is negative, exactly -COUNT characters after point are
     deleted.

     In an interactive call, COUNT is the numeric prefix argument, and
     KILLP is the unprocessed prefix argument.  Therefore, if a prefix
     argument is supplied, the text is saved in the kill ring.  If no
     prefix argument is supplied, then one character is deleted, but
     not saved in the kill ring.

     The value returned is always `nil'.


File: lispref.info,  Node: User-Level Deletion,  Next: The Kill Ring,  Prev: Deletion,  Up: Text

43.7 User-Level Deletion Commands
=================================

This section describes higher-level commands for deleting text,
commands intended primarily for the user but useful also in Lisp
programs.

 -- Command: delete-horizontal-space
     This function deletes all spaces and tabs around point.  It returns
     `nil'.

     In the following examples, we call `delete-horizontal-space' four
     times, once on each line, with point between the second and third
     characters on the line each time.

          ---------- Buffer: foo ----------
          I -!-thought
          I -!-     thought
          We-!- thought
          Yo-!-u thought
          ---------- Buffer: foo ----------

          (delete-horizontal-space)   ; Four times.
               => nil

          ---------- Buffer: foo ----------
          Ithought
          Ithought
          Wethought
          You thought
          ---------- Buffer: foo ----------

 -- Command: delete-indentation &optional join-following-p
     This function joins the line point is on to the previous line,
     deleting any whitespace at the join and in some cases replacing it
     with one space.  If JOIN-FOLLOWING-P is non-`nil',
     `delete-indentation' joins this line to the following line
     instead.  The value is `nil'.

     If there is a fill prefix, and the second of the lines being joined
     starts with the prefix, then `delete-indentation' deletes the fill
     prefix before joining the lines.  *Note Margins::.

     In the example below, point is located on the line starting
     `events', and it makes no difference if there are trailing spaces
     in the preceding line.

          ---------- Buffer: foo ----------
          When in the course of human
          -!-    events, it becomes necessary
          ---------- Buffer: foo ----------

          (delete-indentation)
               => nil

          ---------- Buffer: foo ----------
          When in the course of human-!- events, it becomes necessary
          ---------- Buffer: foo ----------

     After the lines are joined, the function `fixup-whitespace' is
     responsible for deciding whether to leave a space at the junction.

 -- Command: fixup-whitespace
     This function replaces all the white space surrounding point with
     either one space or no space, according to the context.  It
     returns `nil'.

     At the beginning or end of a line, the appropriate amount of space
     is none.  Before a character with close parenthesis syntax, or
     after a character with open parenthesis or expression-prefix
     syntax, no space is also appropriate.  Otherwise, one space is
     appropriate.  *Note Syntax Class Table::.

     In the example below, `fixup-whitespace' is called the first time
     with point before the word `spaces' in the first line.  For the
     second invocation, point is directly after the `('.

          ---------- Buffer: foo ----------
          This has too many     -!-spaces
          This has too many spaces at the start of (-!-   this list)
          ---------- Buffer: foo ----------

          (fixup-whitespace)
               => nil
          (fixup-whitespace)
               => nil

          ---------- Buffer: foo ----------
          This has too many spaces
          This has too many spaces at the start of (this list)
          ---------- Buffer: foo ----------

 -- Command: just-one-space
     This command replaces any spaces and tabs around point with a
     single space.  It returns `nil'.

 -- Command: delete-blank-lines
     This function deletes blank lines surrounding point.  If point is
     on a blank line with one or more blank lines before or after it,
     then all but one of them are deleted.  If point is on an isolated
     blank line, then it is deleted.  If point is on a nonblank line,
     the command deletes all blank lines following it.

     A blank line is defined as a line containing only tabs and spaces.

     `delete-blank-lines' returns `nil'.


File: lispref.info,  Node: The Kill Ring,  Next: Undo,  Prev: User-Level Deletion,  Up: Text

43.8 The Kill Ring
==================

"Kill" functions delete text like the deletion functions, but save it
so that the user can reinsert it by "yanking".  Most of these functions
have `kill-' in their name.  By contrast, the functions whose names
start with `delete-' normally do not save text for yanking (though they
can still be undone); these are "deletion" functions.

   Most of the kill commands are primarily for interactive use, and are
not described here.  What we do describe are the functions provided for
use in writing such commands.  You can use these functions to write
commands for killing text.  When you need to delete text for internal
purposes within a Lisp function, you should normally use deletion
functions, so as not to disturb the kill ring contents.  *Note
Deletion::.

   Killed text is saved for later yanking in the "kill ring".  This is
a list that holds a number of recent kills, not just the last text
kill.  We call this a "ring" because yanking treats it as having
elements in a cyclic order.  The list is kept in the variable
`kill-ring', and can be operated on with the usual functions for lists;
there are also specialized functions, described in this section, that
treat it as a ring.

   Some people think this use of the word "kill" is unfortunate, since
it refers to operations that specifically _do not_ destroy the entities
"killed".  This is in sharp contrast to ordinary life, in which death
is permanent and "killed" entities do not come back to life.
Therefore, other metaphors have been proposed.  For example, the term
"cut ring" makes sense to people who, in pre-computer days, used
scissors and paste to cut up and rearrange manuscripts.  However, it
would be difficult to change the terminology now.

* Menu:

* Kill Ring Concepts::     What text looks like in the kill ring.
* Kill Functions::         Functions that kill text.
* Yank Commands::          Commands that access the kill ring.
* Low-Level Kill Ring::	   Functions and variables for kill ring access.
* Internals of Kill Ring:: Variables that hold kill-ring data.


File: lispref.info,  Node: Kill Ring Concepts,  Next: Kill Functions,  Up: The Kill Ring

43.8.1 Kill Ring Concepts
-------------------------

The kill ring records killed text as strings in a list, most recent
first.  A short kill ring, for example, might look like this:

     ("some text" "a different piece of text" "even older text")

When the list reaches `kill-ring-max' entries in length, adding a new
entry automatically deletes the last entry.

   When kill commands are interwoven with other commands, each kill
command makes a new entry in the kill ring.  Multiple kill commands in
succession build up a single entry in the kill ring, which would be
yanked as a unit; the second and subsequent consecutive kill commands
add text to the entry made by the first one.

   For yanking, one entry in the kill ring is designated the "front" of
the ring.  Some yank commands "rotate" the ring by designating a
different element as the "front."  But this virtual rotation doesn't
change the list itself--the most recent entry always comes first in the
list.


File: lispref.info,  Node: Kill Functions,  Next: Yank Commands,  Prev: Kill Ring Concepts,  Up: The Kill Ring

43.8.2 Functions for Killing
----------------------------

`kill-region' is the usual subroutine for killing text.  Any command
that calls this function is a "kill command" (and should probably have
`kill' in its name).  `kill-region' puts the newly killed text in a new
element at the beginning of the kill ring or adds it to the most recent
element.  It uses the `last-command' variable to determine whether the
previous command was a kill command, and if so appends the killed text
to the most recent entry.

 -- Command: kill-region start end &optional verbose
     This function kills the text in the region defined by START and
     END.  The text is deleted but saved in the kill ring, along with
     its text properties.  The value is always `nil'.

     In an interactive call, START and END are point and the mark.

     If the buffer is read-only, `kill-region' modifies the kill ring
     just the same, then signals an error without modifying the buffer.
     This is convenient because it lets the user use all the kill
     commands to copy text into the kill ring from a read-only buffer.

 -- Command: copy-region-as-kill start end
     This command saves the region defined by START and END on the kill
     ring (including text properties), but does not delete the text
     from the buffer.  It returns `nil'.  It also indicates the extent
     of the text copied by moving the cursor momentarily, or by
     displaying a message in the echo area.

     The command does not set `this-command' to `kill-region', so a
     subsequent kill command does not append to the same kill ring
     entry.

     Don't call `copy-region-as-kill' in Lisp programs unless you aim to
     support Emacs 18.  For Emacs 19, it is better to use `kill-new' or
     `kill-append' instead.  *Note Low-Level Kill Ring::.


File: lispref.info,  Node: Yank Commands,  Next: Low-Level Kill Ring,  Prev: Kill Functions,  Up: The Kill Ring

43.8.3 Functions for Yanking
----------------------------

"Yanking" means reinserting an entry of previously killed text from the
kill ring.  The text properties are copied too.

 -- Command: yank &optional arg
     This command inserts before point the text in the first entry in
     the kill ring.  It positions the mark at the beginning of that
     text, and point at the end.

     If ARG is a list (which occurs interactively when the user types
     `C-u' with no digits), then `yank' inserts the text as described
     above, but puts point before the yanked text and puts the mark
     after it.

     If ARG is a number, then `yank' inserts the ARGth most recently
     killed text--the ARGth element of the kill ring list.

     `yank' does not alter the contents of the kill ring or rotate it.
     It returns `nil'.

 -- Command: yank-pop arg
     This command replaces the just-yanked entry from the kill ring
     with a different entry from the kill ring.

     This is allowed only immediately after a `yank' or another
     `yank-pop'.  At such a time, the region contains text that was just
     inserted by yanking.  `yank-pop' deletes that text and inserts in
     its place a different piece of killed text.  It does not add the
     deleted text to the kill ring, since it is already in the kill
     ring somewhere.

     If ARG is `nil', then the replacement text is the previous element
     of the kill ring.  If ARG is numeric, the replacement is the ARGth
     previous kill.  If ARG is negative, a more recent kill is the
     replacement.

     The sequence of kills in the kill ring wraps around, so that after
     the oldest one comes the newest one, and before the newest one
     goes the oldest.

     The value is always `nil'.


File: lispref.info,  Node: Low-Level Kill Ring,  Next: Internals of Kill Ring,  Prev: Yank Commands,  Up: The Kill Ring

43.8.4 Low-Level Kill Ring
--------------------------

These functions and variables provide access to the kill ring at a lower
level, but still convenient for use in Lisp programs.  They take care of
interaction with X Window selections.  They do not exist in Emacs
version 18.

 -- Function: current-kill count &optional do-not-move
     The function `current-kill' rotates the yanking pointer which
     designates the "front" of the kill ring by COUNT places (from newer
     kills to older ones), and returns the text at that place in the
     ring.

     If the optional second argument DO-NOT-MOVE is non-`nil', then
     `current-kill' doesn't alter the yanking pointer; it just returns
     the COUNTth kill, counting from the current yanking pointer.

     If COUNT is zero, indicating a request for the latest kill,
     `current-kill' calls the value of `interprogram-paste-function'
     (documented below) before consulting the kill ring.

 -- Function: kill-new string &optional replace
     This function makes the text STRING the latest entry in the kill
     ring, and sets `kill-ring-yank-pointer' to point to it.

     Normally, STRING is added to the front of the kill ring as a new
     entry.  However, if optional argument REPLACE is non-`nil', the
     entry previously at the front of the kill ring is discarded, and
     STRING replaces it.

     This function runs the functions on `kill-hooks', and also invokes
     the value of `interprogram-cut-function' (see below).

 -- Function: kill-append string before-p
     This function appends the text STRING to the first entry in the
     kill ring.  Normally STRING goes at the end of the entry, but if
     BEFORE-P is non-`nil', it goes at the beginning.  This function
     also invokes the value of `interprogram-cut-function' (see below).

 -- Variable: interprogram-paste-function
     This variable provides a way of transferring killed text from other
     programs, when you are using a window system.  Its value should be
     `nil' or a function of no arguments.

     If the value is a function, `current-kill' calls it to get the
     "most recent kill".  If the function returns a non-`nil' value,
     then that value is used as the "most recent kill".  If it returns
     `nil', then the first element of `kill-ring' is used.

     The normal use of this hook is to get the X server's primary
     selection as the most recent kill, even if the selection belongs
     to another X client.  *Note X Selections::.

 -- Variable: interprogram-cut-function
     This variable provides a way of communicating killed text to other
     programs, when you are using a window system.  Its value should be
     `nil' or a function of one argument.

     If the value is a function, `kill-new' and `kill-append' call it
     with the new first element of the kill ring as an argument.

     The normal use of this hook is to set the X server's primary
     selection to the newly killed text.


File: lispref.info,  Node: Internals of Kill Ring,  Prev: Low-Level Kill Ring,  Up: The Kill Ring

43.8.5 Internals of the Kill Ring
---------------------------------

The variable `kill-ring' holds the kill ring contents, in the form of a
list of strings.  The most recent kill is always at the front of the
list.

   The `kill-ring-yank-pointer' variable points to a link in the kill
ring list, whose CAR is the text to yank next.  We say it identifies
the "front" of the ring.  Moving `kill-ring-yank-pointer' to a
different link is called "rotating the kill ring".  We call the kill
ring a "ring" because the functions that move the yank pointer wrap
around from the end of the list to the beginning, or vice-versa.
Rotation of the kill ring is virtual; it does not change the value of
`kill-ring'.

   Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
whose values are normally lists.  The word "pointer" in the name of the
`kill-ring-yank-pointer' indicates that the variable's purpose is to
identify one element of the list for use by the next yank command.

   The value of `kill-ring-yank-pointer' is always `eq' to one of the
links in the kill ring list.  The element it identifies is the CAR of
that link.  Kill commands, which change the kill ring, also set this
variable to the value of `kill-ring'.  The effect is to rotate the ring
so that the newly killed text is at the front.

   Here is a diagram that shows the variable `kill-ring-yank-pointer'
pointing to the second entry in the kill ring `("some text" "a
different piece of text" "yet older text")'.

     kill-ring       kill-ring-yank-pointer
       |               |
       |     ___ ___    --->  ___ ___      ___ ___
        --> |___|___|------> |___|___|--> |___|___|--> nil
              |                |            |
              |                |            |
              |                |             -->"yet older text"
              |                |
              |                 --> "a different piece of text"
              |
               --> "some text"

This state of affairs might occur after `C-y' (`yank') immediately
followed by `M-y' (`yank-pop').

 -- Variable: kill-ring
     This variable holds the list of killed text sequences, most
     recently killed first.

 -- Variable: kill-ring-yank-pointer
     This variable's value indicates which element of the kill ring is
     at the "front" of the ring for yanking.  More precisely, the value
     is a tail of the value of `kill-ring', and its CAR is the kill
     string that `C-y' should yank.

 -- User Option: kill-ring-max
     The value of this variable is the maximum length to which the kill
     ring can grow, before elements are thrown away at the end.  The
     default value for `kill-ring-max' is 30.


File: lispref.info,  Node: Undo,  Next: Maintaining Undo,  Prev: The Kill Ring,  Up: Text

43.9 Undo
=========

Most buffers have an "undo list", which records all changes made to the
buffer's text so that they can be undone.  (The buffers that don't have
one are usually special-purpose buffers for which XEmacs assumes that
undoing is not useful.)  All the primitives that modify the text in the
buffer automatically add elements to the front of the undo list, which
is in the variable `buffer-undo-list'.

 -- Variable: buffer-undo-list
     This variable's value is the undo list of the current buffer.  A
     value of `t' disables the recording of undo information.

   Here are the kinds of elements an undo list can have:

`INTEGER'
     This kind of element records a previous value of point.  Ordinary
     cursor motion does not get any sort of undo record, but deletion
     commands use these entries to record where point was before the
     command.

`(START . END)'
     This kind of element indicates how to delete text that was
     inserted.  Upon insertion, the text occupied the range START-END
     in the buffer.

`(TEXT . POSITION)'
     This kind of element indicates how to reinsert text that was
     deleted.  The deleted text itself is the string TEXT.  The place to
     reinsert it is `(abs POSITION)'.

`(t HIGH . LOW)'
     This kind of element indicates that an unmodified buffer became
     modified.  The elements HIGH and LOW are two integers, each
     recording 16 bits of the visited file's modification time as of
     when it was previously visited or saved.  `primitive-undo' uses
     those values to determine whether to mark the buffer as unmodified
     once again; it does so only if the file's modification time
     matches those numbers.

`(nil PROPERTY VALUE START . END)'
     This kind of element records a change in a text property.  Here's
     how you might undo the change:

          (put-text-property START END PROPERTY VALUE)

`POSITION'
     This element indicates where point was at an earlier time.
     Undoing this element sets point to POSITION.  Deletion normally
     creates an element of this kind as well as a reinsertion element.

`nil'
     This element is a boundary.  The elements between two boundaries
     are called a "change group"; normally, each change group
     corresponds to one keyboard command, and undo commands normally
     undo an entire group as a unit.

 -- Function: undo-boundary
     This function places a boundary element in the undo list.  The undo
     command stops at such a boundary, and successive undo commands undo
     to earlier and earlier boundaries.  This function returns `nil'.

     The editor command loop automatically creates an undo boundary
     before each key sequence is executed.  Thus, each undo normally
     undoes the effects of one command.  Self-inserting input
     characters are an exception.  The command loop makes a boundary
     for the first such character; the next 19 consecutive
     self-inserting input characters do not make boundaries, and then
     the 20th does, and so on as long as self-inserting characters
     continue.

     All buffer modifications add a boundary whenever the previous
     undoable change was made in some other buffer.  This way, a
     command that modifies several buffers makes a boundary in each
     buffer it changes.

     Calling this function explicitly is useful for splitting the
     effects of a command into more than one unit.  For example,
     `query-replace' calls `undo-boundary' after each replacement, so
     that the user can undo individual replacements one by one.

 -- Function: primitive-undo count list
     This is the basic function for undoing elements of an undo list.
     It undoes the first COUNT elements of LIST, returning the rest of
     LIST.  You could write this function in Lisp, but it is convenient
     to have it in C.

     `primitive-undo' adds elements to the buffer's undo list when it
     changes the buffer.  Undo commands avoid confusion by saving the
     undo list value at the beginning of a sequence of undo operations.
     Then the undo operations use and update the saved value.  The new
     elements added by undoing are not part of this saved value, so
     they don't interfere with continuing to undo.


File: lispref.info,  Node: Maintaining Undo,  Next: Filling,  Prev: Undo,  Up: Text

43.10 Maintaining Undo Lists
============================

This section describes how to enable and disable undo information for a
given buffer.  It also explains how the undo list is truncated
automatically so it doesn't get too big.

   Recording of undo information in a newly created buffer is normally
enabled to start with; but if the buffer name starts with a space, the
undo recording is initially disabled.  You can explicitly enable or
disable undo recording with the following two functions, or by setting
`buffer-undo-list' yourself.

 -- Command: buffer-enable-undo &optional buffer-or-name
     This command enables recording undo information for buffer
     BUFFER-OR-NAME, so that subsequent changes can be undone.  If no
     argument is supplied, then the current buffer is used.  This
     function does nothing if undo recording is already enabled in the
     buffer.  It returns `nil'.

     In an interactive call, BUFFER-OR-NAME is the current buffer.  You
     cannot specify any other buffer.

 -- Command: buffer-disable-undo &optional buffer
 -- Command: buffer-flush-undo &optional buffer
     This function discards the undo list of BUFFER, and disables
     further recording of undo information.  As a result, it is no
     longer possible to undo either previous changes or any subsequent
     changes.  If the undo list of BUFFER is already disabled, this
     function has no effect.

     This function returns `nil'.  It cannot be called interactively.

     The name `buffer-flush-undo' is not considered obsolete, but the
     preferred name `buffer-disable-undo' is new as of Emacs versions
     19.

   As editing continues, undo lists get longer and longer.  To prevent
them from using up all available memory space, garbage collection trims
them back to size limits you can set.  (For this purpose, the "size" of
an undo list measures the cons cells that make up the list, plus the
strings of deleted text.)  Two variables control the range of acceptable
sizes: `undo-limit' and `undo-strong-limit'.

 -- Variable: undo-limit
     This is the soft limit for the acceptable size of an undo list.
     The change group at which this size is exceeded is the last one
     kept.

 -- Variable: undo-strong-limit
     This is the upper limit for the acceptable size of an undo list.
     The change group at which this size is exceeded is discarded
     itself (along with all older change groups).  There is one
     exception: the very latest change group is never discarded no
     matter how big it is.


File: lispref.info,  Node: Filling,  Next: Margins,  Prev: Maintaining Undo,  Up: Text

43.11 Filling
=============

"Filling" means adjusting the lengths of lines (by moving the line
breaks) so that they are nearly (but no greater than) a specified
maximum width.  Additionally, lines can be "justified", which means
inserting spaces to make the left and/or right margins line up
precisely.  The width is controlled by the variable `fill-column'.  For
ease of reading, lines should be no longer than 70 or so columns.

   You can use Auto Fill mode (*note Auto Filling::) to fill text
automatically as you insert it, but changes to existing text may leave
it improperly filled.  Then you must fill the text explicitly.

   Most of the commands in this section return values that are not
meaningful.  All the functions that do filling take note of the current
left margin, current right margin, and current justification style
(*note Margins::).  If the current justification style is `none', the
filling functions don't actually do anything.

   Several of the filling functions have an argument JUSTIFY.  If it is
non-`nil', that requests some kind of justification.  It can be `left',
`right', `full', or `center', to request a specific style of
justification.  If it is `t', that means to use the current
justification style for this part of the text (see
`current-justification', below).

   When you call the filling functions interactively, using a prefix
argument implies the value `full' for JUSTIFY.

 -- Command: fill-paragraph justify
     This command fills the paragraph at or after point.  If JUSTIFY is
     non-`nil', each line is justified as well.  It uses the ordinary
     paragraph motion commands to find paragraph boundaries.  *Note
     Paragraphs: (xemacs)Paragraphs.

 -- Command: fill-region start end &optional justify
     This command fills each of the paragraphs in the region from START
     to END.  It justifies as well if JUSTIFY is non-`nil'.

     The variable `paragraph-separate' controls how to distinguish
     paragraphs.  *Note Standard Regexps::.

 -- Command: fill-individual-paragraphs start end &optional justify
          mail-flag
     This command fills each paragraph in the region according to its
     individual fill prefix.  Thus, if the lines of a paragraph were
     indented with spaces, the filled paragraph will remain indented in
     the same fashion.

     The first two arguments, START and END, are the beginning and end
     of the region to be filled.  The third and fourth arguments,
     JUSTIFY and MAIL-FLAG, are optional.  If JUSTIFY is non-`nil', the
     paragraphs are justified as well as filled.  If MAIL-FLAG is
     non-`nil', it means the function is operating on a mail message
     and therefore should not fill the header lines.

     Ordinarily, `fill-individual-paragraphs' regards each change in
     indentation as starting a new paragraph.  If
     `fill-individual-varying-indent' is non-`nil', then only separator
     lines separate paragraphs.  That mode can handle indented
     paragraphs with additional indentation on the first line.

 -- User Option: fill-individual-varying-indent
     This variable alters the action of `fill-individual-paragraphs' as
     described above.

 -- Command: fill-region-as-paragraph start end &optional justify
     This command considers a region of text as a paragraph and fills
     it.  If the region was made up of many paragraphs, the blank lines
     between paragraphs are removed.  This function justifies as well
     as filling when JUSTIFY is non-`nil'.

     In an interactive call, any prefix argument requests justification.

     In Adaptive Fill mode, which is enabled by default,
     `fill-region-as-paragraph' on an indented paragraph when there is
     no fill prefix uses the indentation of the second line of the
     paragraph as the fill prefix.

 -- Command: justify-current-line how eop nosqueeze
     This command inserts spaces between the words of the current line
     so that the line ends exactly at `fill-column'.  It returns `nil'.

     The argument HOW, if non-`nil' specifies explicitly the style of
     justification.  It can be `left', `right', `full', `center', or
     `none'.  If it is `t', that means to do follow specified
     justification style (see `current-justification', below).  `nil'
     means to do full justification.

     If EOP is non-`nil', that means do left-justification when
     `current-justification' specifies full justification.  This is used
     for the last line of a paragraph; even if the paragraph as a whole
     is fully justified, the last line should not be.

     If NOSQUEEZE is non-`nil', that means do not change interior
     whitespace.

 -- User Option: default-justification
     This variable's value specifies the style of justification to use
     for text that doesn't specify a style with a text property.  The
     possible values are `left', `right', `full', `center', or `none'.
     The default value is `left'.

 -- Function: current-justification
     This function returns the proper justification style to use for
     filling the text around point.

 -- Variable: fill-paragraph-function
     This variable provides a way for major modes to override the
     filling of paragraphs.  If the value is non-`nil',
     `fill-paragraph' calls this function to do the work.  If the
     function returns a non-`nil' value, `fill-paragraph' assumes the
     job is done, and immediately returns that value.

     The usual use of this feature is to fill comments in programming
     language modes.  If the function needs to fill a paragraph in the
     usual way, it can do so as follows:

          (let ((fill-paragraph-function nil))
            (fill-paragraph arg))

 -- Variable: use-hard-newlines
     If this variable is non-`nil', the filling functions do not delete
     newlines that have the `hard' text property.  These "hard
     newlines" act as paragraph separators.


File: lispref.info,  Node: Margins,  Next: Auto Filling,  Prev: Filling,  Up: Text

43.12 Margins for Filling
=========================

 -- User Option: fill-prefix
     This variable specifies a string of text that appears at the
     beginning of normal text lines and should be disregarded when
     filling them.  Any line that fails to start with the fill prefix
     is considered the start of a paragraph; so is any line that starts
     with the fill prefix followed by additional whitespace.  Lines
     that start with the fill prefix but no additional whitespace are
     ordinary text lines that can be filled together.  The resulting
     filled lines also start with the fill prefix.

     The fill prefix follows the left margin whitespace, if any.

 -- User Option: fill-column
     This buffer-local variable specifies the maximum width of filled
     lines.  Its value should be an integer, which is a number of
     columns.  All the filling, justification and centering commands
     are affected by this variable, including Auto Fill mode (*note
     Auto Filling::).

     As a practical matter, if you are writing text for other people to
     read, you should set `fill-column' to no more than 70.  Otherwise
     the line will be too long for people to read comfortably, and this
     can make the text seem clumsy.

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

     The default value for `default-fill-column' is 70.

 -- Command: set-left-margin from to margin
     This sets the `left-margin' property on the text from FROM to TO
     to the value MARGIN.  If Auto Fill mode is enabled, this command
     also refills the region to fit the new margin.

 -- Command: set-right-margin from to margin
     This sets the `right-margin' property on the text from FROM to TO
     to the value MARGIN.  If Auto Fill mode is enabled, this command
     also refills the region to fit the new margin.

 -- Function: current-left-margin
     This function returns the proper left margin value to use for
     filling the text around point.  The value is the sum of the
     `left-margin' property of the character at the start of the
     current line (or zero if none), and the value of the variable
     `left-margin'.

 -- Function: current-fill-column
     This function returns the proper fill column value to use for
     filling the text around point.  The value is the value of the
     `fill-column' variable, minus the value of the `right-margin'
     property of the character after point.

 -- Command: move-to-left-margin &optional n force
     This function moves point to the left margin of the current line.
     The column moved to is determined by calling the function
     `current-left-margin'.  If the argument N is non-`nil',
     `move-to-left-margin' moves forward N-1 lines first.

     If FORCE is non-`nil', that says to fix the line's indentation if
     that doesn't match the left margin value.

 -- Function: delete-to-left-margin &optional from to
     This function removes left margin indentation from the text
     between FROM and TO.  The amount of indentation to delete is
     determined by calling `current-left-margin'.  In no case does this
     function delete non-whitespace.

     The arguments FROM and TO are optional; the default is the whole
     buffer.

 -- Function: indent-to-left-margin
     This is the default `indent-line-function', used in Fundamental
     mode, Text mode, etc.  Its effect is to adjust the indentation at
     the beginning of the current line to the value specified by the
     variable `left-margin'.  This may involve either inserting or
     deleting whitespace.

 -- Variable: left-margin
     This variable specifies the base left margin column.  In
     Fundamental mode, <LFD> indents to this column.  This variable
     automatically becomes buffer-local when set in any fashion.


File: lispref.info,  Node: Auto Filling,  Next: Sorting,  Prev: Margins,  Up: Text

43.13 Auto Filling
==================

Auto Fill mode is a minor mode that fills lines automatically as text
is inserted.  This section describes the hook used by Auto Fill mode.
For a description of functions that you can call explicitly to fill and
justify existing text, see *Note Filling::.

   Auto Fill mode also enables the functions that change the margins and
justification style to refill portions of the text.  *Note Margins::.

 -- Variable: auto-fill-function
     The value of this variable should be a function (of no arguments)
     to be called after self-inserting a space or a newline.  It may be
     `nil', in which case nothing special is done in that case.

     The value of `auto-fill-function' is `do-auto-fill' when Auto-Fill
     mode is enabled.  That is a function whose sole purpose is to
     implement the usual strategy for breaking a line.

          In older Emacs versions, this variable was named
          `auto-fill-hook', but since it is not called with the
          standard convention for hooks, it was renamed to
          `auto-fill-function' in version 19.


File: lispref.info,  Node: Sorting,  Next: Columns,  Prev: Auto Filling,  Up: Text

43.14 Sorting Text
==================

The sorting functions described in this section all rearrange text in a
buffer.  This is in contrast to the function `sort', which rearranges
the order of the elements of a list (*note Rearrangement::).  The
values returned by these functions are not meaningful.

 -- Function: sort-subr reverse nextrecfun endrecfun &optional
          startkeyfun endkeyfun
     This function is the general text-sorting routine that divides a
     buffer into records and sorts them.  Most of the commands in this
     section use this function.

     To understand how `sort-subr' works, consider the whole accessible
     portion of the buffer as being divided into disjoint pieces called
     "sort records".  The records may or may not be contiguous; they may
     not overlap.  A portion of each sort record (perhaps all of it) is
     designated as the sort key.  Sorting rearranges the records in
     order by their sort keys.

     Usually, the records are rearranged in order of ascending sort key.
     If the first argument to the `sort-subr' function, REVERSE, is
     non-`nil', the sort records are rearranged in order of descending
     sort key.

     The next four arguments to `sort-subr' are functions that are
     called to move point across a sort record.  They are called many
     times from within `sort-subr'.

       1. NEXTRECFUN is called with point at the end of a record.  This
          function moves point to the start of the next record.  The
          first record is assumed to start at the position of point
          when `sort-subr' is called.  Therefore, you should usually
          move point to the beginning of the buffer before calling
          `sort-subr'.

          This function can indicate there are no more sort records by
          leaving point at the end of the buffer.

       2. ENDRECFUN is called with point within a record.  It moves
          point to the end of the record.

       3. STARTKEYFUN is called to move point from the start of a
          record to the start of the sort key.  This argument is
          optional; if it is omitted, the whole record is the sort key.
          If supplied, the function should either return a non-`nil'
          value to be used as the sort key, or return `nil' to indicate
          that the sort key is in the buffer starting at point.  In the
          latter case, ENDKEYFUN is called to find the end of the sort
          key.

       4. ENDKEYFUN is called to move point from the start of the sort
          key to the end of the sort key.  This argument is optional.
          If STARTKEYFUN returns `nil' and this argument is omitted (or
          `nil'), then the sort key extends to the end of the record.
          There is no need for ENDKEYFUN if STARTKEYFUN returns a
          non-`nil' value.

     As an example of `sort-subr', here is the complete function
     definition for `sort-lines':

          ;; Note that the first two lines of doc string
          ;; are effectively one line when viewed by a user.
          (defun sort-lines (reverse start end)
            "Sort lines in region alphabetically.
          Called from a program, there are three arguments:
          REVERSE (non-nil means reverse order),
          and START and END (the region to sort)."
            (interactive "P\nr")
            (save-restriction
              (narrow-to-region start end)
              (goto-char (point-min))
              (sort-subr reverse
                         'forward-line
                         'end-of-line)))

     Here `forward-line' moves point to the start of the next record,
     and `end-of-line' moves point to the end of record.  We do not pass
     the arguments STARTKEYFUN and ENDKEYFUN, because the entire record
     is used as the sort key.

     The `sort-paragraphs' function is very much the same, except that
     its `sort-subr' call looks like this:

          (sort-subr reverse
                     (function
                      (lambda ()
                        (skip-chars-forward "\n \t\f")))
                     'forward-paragraph)

 -- Command: sort-regexp-fields reverse record-regexp key-regexp start
          end
     This command sorts the region between START and END alphabetically
     as specified by RECORD-REGEXP and KEY-REGEXP.  If REVERSE is a
     negative integer, then sorting is in reverse order.

     Alphabetical sorting means that two sort keys are compared by
     comparing the first characters of each, the second characters of
     each, and so on.  If a mismatch is found, it means that the sort
     keys are unequal; the sort key whose character is less at the
     point of first mismatch is the lesser sort key.  The individual
     characters are compared according to their numerical values.
     Since Emacs uses the ASCII character set, the ordering in that set
     determines alphabetical order.

     The value of the RECORD-REGEXP argument specifies how to divide
     the buffer into sort records.  At the end of each record, a search
     is done for this regular expression, and the text that matches it
     is the next record.  For example, the regular expression `^.+$',
     which matches lines with at least one character besides a newline,
     would make each such line into a sort record.  *Note Regular
     Expressions::, for a description of the syntax and meaning of
     regular expressions.

     The value of the KEY-REGEXP argument specifies what part of each
     record is the sort key.  The KEY-REGEXP could match the whole
     record, or only a part.  In the latter case, the rest of the
     record has no effect on the sorted order of records, but it is
     carried along when the record moves to its new position.

     The KEY-REGEXP argument can refer to the text matched by a
     subexpression of RECORD-REGEXP, or it can be a regular expression
     on its own.

     If KEY-REGEXP is:

    `\DIGIT'
          then the text matched by the DIGITth `\(...\)' parenthesis
          grouping in RECORD-REGEXP is the sort key.

    `\&'
          then the whole record is the sort key.

    a regular expression
          then `sort-regexp-fields' searches for a match for the regular
          expression within the record.  If such a match is found, it
          is the sort key.  If there is no match for KEY-REGEXP within
          a record then that record is ignored, which means its
          position in the buffer is not changed.  (The other records
          may move around it.)

     For example, if you plan to sort all the lines in the region by the
     first word on each line starting with the letter `f', you should
     set RECORD-REGEXP to `^.*$' and set KEY-REGEXP to `\<f\w*\>'.  The
     resulting expression looks like this:

          (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
                              (region-beginning)
                              (region-end))

     If you call `sort-regexp-fields' interactively, it prompts for
     RECORD-REGEXP and KEY-REGEXP in the minibuffer.

 -- Command: sort-lines reverse start end
     This command alphabetically sorts lines in the region between
     START and END.  If REVERSE is non-`nil', the sort is in reverse
     order.

 -- Command: sort-paragraphs reverse start end
     This command alphabetically sorts paragraphs in the region between
     START and END.  If REVERSE is non-`nil', the sort is in reverse
     order.

 -- Command: sort-pages reverse start end
     This command alphabetically sorts pages in the region between
     START and END.  If REVERSE is non-`nil', the sort is in reverse
     order.

 -- Command: sort-fields field start end
     This command sorts lines in the region between START and END,
     comparing them alphabetically by the FIELDth field of each line.
     Fields are separated by whitespace and numbered starting from 1.
     If FIELD is negative, sorting is by the -FIELDth field from the
     end of the line.  This command is useful for sorting tables.

 -- Command: sort-numeric-fields field start end
     This command sorts lines in the region between START and END,
     comparing them numerically by the FIELDth field of each line.  The
     specified field must contain a number in each line of the region.
     Fields are separated by whitespace and numbered starting from 1.
     If FIELD is negative, sorting is by the -FIELDth field from the
     end of the line.  This command is useful for sorting tables.

 -- Command: sort-columns reverse &optional start end
     This command sorts the lines in the region between START and END,
     comparing them alphabetically by a certain range of columns.  The
     column positions of START and END bound the range of columns to
     sort on.

     If REVERSE is non-`nil', the sort is in reverse order.

     One unusual thing about this command is that the entire line
     containing position START, and the entire line containing position
     END, are included in the region sorted.

     Note that `sort-columns' uses the `sort' utility program, and so
     cannot work properly on text containing tab characters.  Use `M-x
     `untabify'' to convert tabs to spaces before sorting.


File: lispref.info,  Node: Columns,  Next: Indentation,  Prev: Sorting,  Up: Text

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

   A character counts 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.

 -- Function: current-column &optional buffer
     This function returns the horizontal position of point, measured in
     columns, counting from 0 at the left margin.

     This is calculated by adding together the widths of all the
     displayed representations of the character between the start of
     the previous line and point. (e.g. control characters will have a
     width of 2 or 4, tabs will have a variable width.)

     Ignores the finite width of frame displaying the buffer, which
     means that this function may return values greater than
     `(frame-width)'.

     Whether the line is visible (if `selective-display' is t) has no
     effect; however, ^M is treated as end of line when
     `selective-display' is t.

     If BUFFER is nil, the current buffer is assumed.

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

 -- Function: move-to-column column &optional force buffer
     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; in that case, unless the value of
     FORCE is the special value `coerce', it says to add whitespace at
     the end of the line to reach that column.

     If COLUMN is not a non-negative integer, an error is signaled.

     The return value is the column number actually moved to.


File: lispref.info,  Node: Indentation,  Next: Case Changes,  Prev: Columns,  Up: Text

43.16 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: lispref.info,  Node: Primitive Indent,  Next: Mode-Specific Indent,  Up: Indentation

43.16.1 Indentation Primitives
------------------------------

This section describes the primitive functions used to count and insert
indentation.  The functions in the following sections use these
primitives.

 -- Function: current-indentation &optional buffer
     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 buffer
     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.  If BUFFER is `nil', the current buffer is
     assumed.

 -- 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 local to the current
     buffer.


File: lispref.info,  Node: Mode-Specific Indent,  Next: Region Indent,  Prev: Primitive Indent,  Up: Indentation

43.16.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'.  In
     Fundamental mode, Text mode, and many other modes with no standard
     for indentation, the value is `indent-to-left-margin' (which is the
     default value).

 -- 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 &optional prefix-arg
     This command calls the function in `indent-line-function' to indent
     the current line; except that if that function is
     `indent-to-left-margin', it calls `insert-tab' 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 reindents 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: lispref.info,  Node: Region Indent,  Next: Relative Indent,  Prev: Mode-Specific Indent,  Up: Indentation

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

 -- Command: 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: lispref.info,  Node: Relative Indent,  Next: Indent Tabs,  Prev: Region Indent,  Up: Indentation

43.16.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 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.  It calls `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: lispref.info,  Node: Indent Tabs,  Next: Motion by Indent,  Prev: Relative Indent,  Up: Indentation

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

 -- Command: tab-to-tab-stop
     This command inserts spaces or tabs 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: lispref.info,  Node: Motion by Indent,  Prev: Indent Tabs,  Up: Indentation

43.16.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 arg
     This command moves point backward ARG lines and then to the first
     nonblank character on that line.  It returns `nil'.

 -- Command: forward-to-indentation arg
     This command moves point forward ARG lines and then to the first
     nonblank character on that line.  It returns `nil'.


File: lispref.info,  Node: Case Changes,  Next: Text Properties,  Prev: Indentation,  Up: Text

43.17 Case Changes
==================

The case change commands described here work on text in the current
buffer.  *Note Character Case::, for case conversion commands 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 &optional buffer
     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 &optional buffer
     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 &optional buffer
     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 &optional buffer
     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 &optional buffer
     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 &optional buffer
     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: lispref.info,  Node: Text Properties,  Next: Substitution,  Prev: Case Changes,  Up: Text

43.18 Text Properties
=====================

Text properties are an alternative interface to extents (*note
Extents::), and are built on top of them.  They are useful when you
want to view textual properties as being attached to the characters
themselves rather than to intervals of characters.  The text property
interface is compatible with FSF Emacs.

   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 generally 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.  The usual way to access the
property list is to specify a name and ask what value corresponds to it.

   Note that FSF Emacs also looks at the `category' property to find
defaults for text properties.  We consider this too bogus to implement.

   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.
* Saving Properties::           Saving text properties in files, and reading
                                  them back.
* Fields::			Emacs-compatible text fields.


File: lispref.info,  Node: Examining Properties,  Next: Changing Properties,  Up: Text Properties

43.18.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 at-flag
     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.

 -- Function: get-char-property pos prop &optional object at-flag
     This function is like `get-text-property', except that it checks
     all extents, not just text-property extents.


 -- 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, the value stored in this list is used instead.  Here is
     an example:

          (setq default-text-properties '(foo 69))
          ;; 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: lispref.info,  Node: Changing Properties,  Next: Property Search,  Prev: Examining Properties,  Up: Text Properties

43.18.2 Changing Text Properties
--------------------------------

The primitives for changing properties apply to a specified range of
text.  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 buffer's contents,
and can affect how the buffer looks on the screen, any change in the
text properties is considered a buffer modification.  Buffer text
property changes are undoable (*note Undo::).

 -- 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 modifies the 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 change.  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).

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

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


File: lispref.info,  Node: Property Search,  Next: Special Properties,  Prev: Changing Properties,  Up: Text Properties

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

   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: next-single-property-change pos prop &optional object
          limit
     The function scans the text forward from position POS in the
     string or buffer OBJECT till it finds a change in the PROP
     property, then returns the position of the change.  In other
     words, it 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-property-change pos &optional object limit
     This is like `next-property-change', but scans backward 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: previous-single-property-change pos prop &optional object
          limit
     This is like `next-single-property-change', but scans backward 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: 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 has a property PROP whose value differs from 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: lispref.info,  Node: Special Properties,  Next: Saving Properties,  Prev: Property Search,  Up: Text Properties

43.18.4 Properties with Special Meanings
----------------------------------------

The predefined properties are the same as those for extents.  *Note
Extent Properties::.


File: lispref.info,  Node: Saving Properties,  Next: Fields,  Prev: Special Properties,  Up: Text Properties

43.18.5 Saving Text Properties in Files
---------------------------------------

You can save text properties in files, and restore text properties when
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 in 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 property
names or property 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: lispref.info,  Node: Fields,  Prev: Saving Properties,  Up: Text Properties

43.18.6 Fields
--------------

Emacs supplies a notion of a _text field_, which is a region of text
where every character has the same value of the `field' property.  It
is used to identify regions of a buffer used for communicating with an
external process, for example.  XEmacs supplies a compatible interface.
In XEmacs, the `field' property can be set as either an extent
property or a text property, mirroring the Emacs capability of using
either overlays or text properties.

   The field manipulating functions take a buffer position as the
field-identifying argument, defaulting to point.  This really means the
field containing that buffer position.  Consecutive buffer positions
with no `field' property are considered an "empty" field.  There is
some ambiguity when a specified buffer position falls at the very
beginning or the very end of a field: does it belong to the preceding or
the following field?  The answer depends on the openness or closedness
of the corresponding extents (*note Extent Endpoints::).  A buffer
position corresponds to the field whose property would be inherited by a
character inserted at that position.  If the buffer position is between
an end-open and a start-open extent, then it corresponds to an empty
field at that position, since an inserted character will belong to
neither extent.

 -- Variable: inhibit-field-text-motion
     This variable controls whether the text motion commands notice
     fields or not.  When it is nil (the default), commands such as
     beginning-of-line will try to move only within fields.

 -- Function: make-field value from to &optional buffer
     There is no Emacs counterpart to this function.  The default open
     and closedness of extents in XEmacs is opposite to the default for
     Emacs overlays.  Hence, fields based on extents in XEmacs behave
     differently from the equivalent fields based on overlays in Emacs.
     This function creates a field with value VALUE over the region
     FROM to TO in BUFFER, which defaults to the current buffer, with
     the default Emacs open and closedness.

 -- Function: find-field &optional pos merge-at-boundary beg-limit
          end-limit
     There is no (Lisp-visible) Emacs counterpart to this function.  It
     is the workhorse for the other functions.  It returns a dotted pair
     `(start . stop)' holding the endpoints of the field matching a
     specification.  If POS is non-`nil', it specifies a buffer
     position whose enclosing field should be found; otherwise, the
     value of point is used.

     If MERGE-AT-BOUNDARY is non-`nil', then two changes are made to
     the search algorithm.  First, if POS is at the very first position
     of a field, then the beginning of the previous field is returned
     instead of the beginning of POS's field.  Second, if the value of
     the `field' property at POS is the symbol `boundary', then the
     beginning of the field before the boundary field and the end of
     the field after the boundary field are returned.

     If BEG-LIMIT is a buffer position, and the start position that
     would be returned is less than BEG-LIMIT, then BEG-LIMIT is
     returned instead.  Likewise, if END-LIMIT is a buffer position,
     and the stop position that would be returned is greater than
     END-LIMIT, then END-LIMIT is returned instead.

 -- Function: delete-field &optional pos
     Delete the text of the field at POS.

 -- Function: field-string &optional pos
     Return the contents of the field at POS as a string.

 -- Function: field-string-no-properties &optional pos
     Return the contents of the field at POS as a string, without text
     properties.

 -- Function: field-beginning &optional pos escape-from-edge limit
     Return the beginning of the field at POS.  If ESCAPE-FROM-EDGE is
     non-nil and POS is at the beginning of a field, then the beginning
     of the field that ends at POS is returned instead.  If LIMIT is a
     buffer position and the returned value would be less than LIMIT,
     then LIMIT is returned instead.

 -- Function: field-end &optional pos escape-from-edge limit
     Return the end of the field at POS.  If ESCAPE-FROM-EDGE is
     non-nil and POS is at the end of a field, then the end of the
     field that begins at POS is returned instead.  If LIMIT is a
     buffer position and the returned value would be greater than
     LIMIT, then LIMIT is returned instead.

 -- Function: constrain-to-field new-pos old-pos &optional
          escape-from-edge only-in-line inhibit-capture-property
     Return the position closest to NEW-POS that is in the same field
     as OLD-POS.  If NEW-POS is `nil', then the value of point is used
     instead _and_ point is set to the value that is returned.

     If ESCAPE-FROM-EDGE is non-`nil' and OLD-POS is at the boundary of
     two fields, then the two adjacent fields are considered one field.
     Furthermore, if NEW-POS is in a field whose `field' property is
     the symbol `boundary', then the preceding field, the boundary
     field, and the following field are considered one field.

     If ONLY-IN-LINE is non-`nil' and the returned position would be on
     a different line than NEW-POS, return NEW-POS instead.

     If INHIBIT-CAPTURE-PROPERTY is non-`nil' and the character at
     OLD-POS has a property of the same name as the value of
     INHIBIT-CAPTURE-PROPERTY, then all field boundaries are ignored;
     i.e., NEW-POS is returned.

     If INHIBIT-FIELD-TEXT-MOTION is non-`nil', then all field
     boundaries are ignored and this function always returns NEW-POS.


File: lispref.info,  Node: Substitution,  Next: Registers,  Prev: Text Properties,  Up: Text

43.19 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 feature is used for controlling selective display
     (*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 can be either a string, a vector, or a char-table.

     If TABLE is a string, its Nth element is the mapping for the
     character with code N.

     If TABLE is a vector, its Nth element is the mapping for character
     with code N.  Legal mappings are characters, strings, or `nil'
     (meaning don't replace.)

     If TABLE is a char-table, its elements describe the mapping
     between characters and their replacements.  The char-table should
     be of type `char' or `generic'.

     When the TABLE is a string or vector and its length is less than
     the total number of characters (256 without Mule), 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.

     *NOTE*: Prior to XEmacs 21.2, the TABLE argument was allowed only
     to be a string.  This is still the case in FSF Emacs.

     The following example creates a char-table that is passed to
     `translate-region', which translates character `a' to `the letter
     a', removes character `b', and translates character `c' to newline.

          ---------- Buffer: foo ----------
          Here is a sentence in the buffer.
          ---------- Buffer: foo ----------

          (let ((table (make-char-table 'generic)))
            (put-char-table ?a "the letter a" table)
            (put-char-table ?b "" table)
            (put-char-table ?c ?\n table)
            (translate-region (point-min) (point-max) table))
               => 3

          ---------- Buffer: foo ----------
          Here is the letter a senten
          e in the uffer.
          ---------- Buffer: foo ----------


File: lispref.info,  Node: Registers,  Next: Transposition,  Prev: Substitution,  Up: Text

43.20 Registers
===============

A register is a sort of variable used in XEmacs editing that can hold a
marker, a string, a rectangle, a window configuration (of one frame), or
a frame configuration (of all frames).  Each register is named by a
single character.  All characters, including control and meta characters
(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 a character that is its name.

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

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

     The object NAME is a character (an integer) identifying the
     register.  The object CONTENTS is a string, marker, or list
     representing the register contents.  A string represents text
     stored in the register.  A marker represents a position.  A list
     represents a rectangle; its elements are strings, one per line of
     the rectangle.

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

 -- Function: set-register register value
     This function sets the contents of register REGISTER 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 register
     This command displays what is contained in register REGISTER.

 -- Command: insert-register register &optional beforep
     This command inserts contents of register REGISTER 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: lispref.info,  Node: Transposition,  Next: Change Hooks,  Prev: Registers,  Up: Text

43.21 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: lispref.info,  Node: Change Hooks,  Next: Transformations,  Prev: Transposition,  Up: Text

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

   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.

   Buffer changes made while executing the following hooks don't
themselves cause any change hooks to be invoked.

 -- Variable: before-change-functions
     This variable holds a list of a 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 a 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.  (To get the current
     length, subtract the region beginning from the region end.)  All
     three arguments are integers.  The buffer that's about to change
     is always the current buffer.

 -- Variable: before-change-function
     This obsolete variable holds one function to call before any buffer
     modification (or `nil' for no function).  It is called just like
     the functions in `before-change-functions'.

 -- Variable: after-change-function
     This obsolete variable holds one function to call after any buffer
     modification (or `nil' for no function).  It is called just like
     the functions in `after-change-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.


File: lispref.info,  Node: Transformations,  Prev: Change Hooks,  Up: Text

43.23 Textual transformations--MD5 and base64 support
=====================================================

Some textual operations inherently require examining each character in
turn, and performing arithmetic operations on them.  Such operations
can, of course, be implemented in Emacs Lisp, but tend to be very slow
for large portions of text or data.  This is why some of them are
implemented in C, with an appropriate interface for Lisp programmers.
Examples of algorithms thus provided are MD5 and base64 support.

   MD5 is an algorithm for calculating message digests, as described in
rfc1321.  Given a message of arbitrary length, MD5 produces a 128-bit
"fingerprint" ("message digest") corresponding to that message.  It is
considered computationally infeasible to produce two messages having
the same MD5 digest, or to produce a message having a prespecified
target digest.  MD5 is used heavily by various authentication schemes.

   Emacs Lisp interface to MD5 consists of a single function `md5':

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

     Optional arguments START and END denote positions for computing
     the digest of a portion of OBJECT.

     The optional CODING argument specifies the coding system the text
     is to be represented in while computing the digest.  If
     unspecified, it defaults to the current format of the data, or is
     guessed.

     If NOERROR is non-`nil', silently assume binary coding if the
     guesswork fails.  Normally, an error is signaled in such case.

     CODING and NOERROR arguments are meaningful only in XEmacsen with
     file-coding or Mule support.  Otherwise, they are ignored.  Some
     examples of usage:

          ;; Calculate the digest of the entire buffer
          (md5 (current-buffer))
               => "8842b04362899b1cda8d2d126dc11712"

          ;; Calculate the digest of the current line
          (md5 (current-buffer) (point-at-bol) (point-at-eol))
               => "60614d21e9dee27dfdb01fa4e30d6d00"

          ;; Calculate the digest of your name and email address
          (md5 (concat (format "%s <%s>" (user-full-name) user-mail-address)))
               => "0a2188c40fd38922d941fe6032fce516"

   Base64 is a portable encoding for arbitrary sequences of octets, in a
form that need not be readable by humans.  It uses a 65-character subset
of US-ASCII, as described in rfc2045.  Base64 is used by MIME to encode
binary bodies, and to encode binary characters in message headers.

   The Lisp interface to base64 consists of four functions:

 -- Command: base64-encode-region start end &optional no-line-break
     This function encodes the region between START and END of the
     current buffer to base64 format.  This means that the original
     region is deleted, and replaced with its base64 equivalent.

     Normally, encoded base64 output is multi-line, with 76-character
     lines.  If NO-LINE-BREAK is non-`nil', newlines will not be
     inserted, resulting in single-line output.

     Mule note: you should make sure that you convert the multibyte
     characters (those that do not fit into 0-255 range) to something
     else, because they cannot be meaningfully converted to base64.  If
     the `base64-encode-region' encounters such characters, it will
     signal an error.

     `base64-encode-region' returns the length of the encoded text.

          ;; Encode the whole buffer in base64
          (base64-encode-region (point-min) (point-max))

     The function can also be used interactively, in which case it
     works on the currently active region.

 -- Function: base64-encode-string string &optional no-line-break
     This function encodes STRING to base64, and returns the encoded
     string.

     Normally, encoded base64 output is multi-line, with 76-character
     lines.  If NO-LINE-BREAK is non-`nil', newlines will not be
     inserted, resulting in single-line output.

     For Mule, the same considerations apply as for
     `base64-encode-region'.

          (base64-encode-string "fubar")
              => "ZnViYXI="

 -- Command: base64-decode-region start end
     This function decodes the region between START and END of the
     current buffer.  The region should be in base64 encoding.

     If the region was decoded correctly, `base64-decode-region' returns
     the length of the decoded region.  If the decoding failed, `nil' is
     returned.

          ;; Decode a base64 buffer, and replace it with the decoded version
          (base64-decode-region (point-min) (point-max))

 -- Function: base64-decode-string string
     This function decodes STRING to base64, and returns the decoded
     string.  STRING should be valid base64-encoded text.

     If encoding was not possible, `nil' is returned.

          (base64-decode-string "ZnViYXI=")
              => "fubar"

          (base64-decode-string "totally bogus")
              => nil


File: lispref.info,  Node: Searching and Matching,  Next: Syntax Tables,  Prev: Text,  Up: Top

44 Searching and Matching
*************************

XEmacs 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.
* Regular Expressions::   Describing classes of strings.
* Regexp Search::         Searching for a match for a regexp.
* POSIX Regexps::         Searching POSIX-style for the longest match.
* Search and Replace::	  Internals of `query-replace'.
* Match Data::            Finding out which part of the text matched
                            various parts of a regexp, after regexp search.
* Searching and Case::    Case-independent or case-significant searching.
* Standard Regexps::      Useful regexps for finding sentences, pages,...

   The `skip-chars...' functions also perform a kind of searching.
*Note Skipping Characters::.


File: lispref.info,  Node: String Search,  Next: Regular Expressions,  Up: Searching and Matching

44.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; LIMIT
and NOERROR are set to `nil', and COUNT is set to 1.

 -- Command: search-forward string &optional limit noerror count buffer
     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 programs may depend on a value of
     `nil'.)

     If COUNT is supplied (it must be an integer), then the search is
     repeated that many times (each time starting at the end of the
     previous time's match).  If COUNT is negative, the search
     direction is backward.  If the successive searches succeed, the
     function succeeds, moving point and returning its new value.
     Otherwise the search fails.

     BUFFER is the buffer to search in, and defaults to the current
     buffer.

 -- Command: search-backward string &optional limit noerror count buffer
     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 count
          buffer
     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), then it is 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 buffer) and
     returns `nil'.

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

     BUFFER is the buffer to search in, and defaults to the current
     buffer.

 -- Command: word-search-backward string &optional limit noerror count
          buffer
     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: lispref.info,  Node: Regular Expressions,  Next: Regexp Search,  Prev: String Search,  Up: Searching and Matching

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

   To gain a thorough understanding of regular expressions and how to
use them to best advantage, we recommend that you study `Mastering
Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates,
1997'. (It's known as the "Hip Owls" book, because of the picture on its
cover.)  You might also read the manuals to *Note (gawk)Top::, *Note
(ed)Top::, `sed', `grep', *Note (perl)Top::, *Note (regex)Top::, *Note
(rx)Top::, `pcre', and *Note (flex)Top::, which also make good use of
regular expressions.

   The XEmacs regular expression syntax most closely resembles that of
`ed', or `grep', the GNU versions of which all utilize the GNU `regex'
library.  XEmacs' version of `regex' has recently been extended with
some Perl-like capabilities, described in the next section.

* Menu:

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


File: lispref.info,  Node: Syntax of Regexps,  Next: Regexp Example,  Up: Regular Expressions

44.2.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.  Any
other character appearing in a regular expression is ordinary, unless a
`\' precedes it.

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

   Any two regular expressions A and B can be concatenated.  The result
is a regular expression 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 characters.  Here is a list of them:

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

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

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

     The matcher processes a `*' construct by matching, immediately, as
     many repetitions as can be found; it is "greedy".  Then it
     continues with the rest of the pattern.  If that fails,
     backtracking occurs, discarding some of the matches of the
     `*'-modified construct in case that makes it possible to match the
     rest of the pattern.  For example, 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.

     Nested repetition operators can be extremely slow if they specify
     backtracking loops.  For example, it could take hours for the
     regular expression `\(x+y*\)*a' to match the sequence
     `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'.  The slowness is because
     Emacs must try each imaginable way of grouping the 35 `x''s before
     concluding that none of them can work.  To make sure your regular
     expressions run fast, check nested repetitions carefully.

`+'
     is a quantifying suffix operator similar to `*' except that the
     preceding expression must match at least once.  It is also
     "greedy".  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 quantifying suffix operator similar to `*', except that the
     preceding expression can match either once or not at all.  For
     example, `ca?r' matches `car' or `cr', but does not match anything
     else.

`*?'
     works just like `*', except that rather than matching the longest
     match, it matches the shortest match.  `*?' is known as a
     "non-greedy" quantifier, a regexp construct borrowed from Perl.

     This construct is very useful for when you want to match the text
     inside a pair of delimiters.  For instance, `/\*.*?\*/' will match
     C comments in a string.  This could not easily be achieved without
     the use of a non-greedy quantifier.

     This construct has not been available prior to XEmacs 20.4.  It is
     not available in FSF Emacs.

`+?'
     is the non-greedy version of `+'.

`??'
     is the non-greedy version of `?'.

`\{n,m\}'
     serves as an interval quantifier, analogous to `*' or `+', but
     specifies that the expression must match at least N times, but no
     more than M times.  This syntax is supported by most Unix regexp
     utilities, and has been introduced to XEmacs for the version 20.3.

     Unfortunately, the non-greedy version of this quantifier does not
     exist currently, although it does in Perl.

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

     The usual regular expression special characters are not special
     inside a character set.  A completely different set of special
     characters exists inside character sets: `]', `-' and `^'.

     `-' is used for ranges of characters.  To write a range, write two
     characters with a `-' between them.  Thus, `[a-z]' matches any
     lower case letter.  Ranges may be intermixed freely with individual
     characters, as in `[a-z$%.]', which matches any lower case letter
     or `$', `%', or a period.

     To include a `]' in a character set, make it the first character.
     For example, `[]a]' matches `]' or `a'.  To include a `-', write
     `-' as the first character in the set, or put it immediately after
     a range.  (You can replace one individual character C with the
     range `C-C' to make a place to put the `-'.)  There is no way to
     write a set containing just `-' and `]'.

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

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

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

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

`^'
     is a special character that matches the empty string, but only at
     the beginning of a line in the text being matched.  Otherwise it
     fails to match anything.  Thus, `^foo' matches a `foo' 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 `\n'.

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

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

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

     Because `\' quotes special characters, `\$' is a regular
     expression 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.

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

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

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

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

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

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

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

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

       3. To record a matched substring for future reference.

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

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

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

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

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

`\(?: ... \)'
     is called a "shy" grouping operator, and it is used just like `\(
     ... \)', except that it does not cause the matched substring to be
     recorded for future reference.

     This is useful when you need a lot of grouping `\( ... \)'
     constructs, but only want to remember one or two - or if you have
     more than nine groupings and need to use backreferences to refer to
     the groupings at the end.  It also allows construction of regular
     expressions from variable subexpressions that contain varying
     numbers of non-capturing subexpressions, without disturbing the
     group counts for the main expression.  For example

          (let ((sre (if foo "\\(?:bar\\|baz\\)" "quux")))
            (re-search-forward (format "a\\(b+ %s c+\\) d" sre) nil t)
            (match-string 1))

     It is very tedious to write this kind of code without shy groups,
     even if you know what all the alternative subexpressions will look
     like.

     Using `\(?: ... \)' rather than `\( ... \)' should give little
     performance gain, as the start of each group must be recorded for
     the purpose of back-tracking in any case, and no string copying is
     done until `match-string' is called.

     The shy grouping operator has been borrowed from Perl, and was not
     available prior to XEmacs 20.3, and has only been available in GNU
     Emacs since version 21.

`\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.
     *Note Syntax Tables::, for a list of syntax codes and the
     characters that stand for them.

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

`\cCATEGORY'
     matches any character in CATEGORY. Only available under Mule,
     categories, and category tables, are further described in *Note
     Category Tables::. They are a mechanism for constructing classes
     of characters that can be local to a buffer, and that do not
     require complicated [] expressions every time they are referenced.

`\CCATEGORY'
     matches any character outside CATEGORY. *Note Category Tables::,
     again, and note that this is only available under Mule.

   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.

`\`'
     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 the empty string, but _not_ at the beginning or end of a
     word.

`\<'
     matches the empty string, but only at the beginning of a word.

`\>'
     matches the empty string, but only at the end of a word.

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

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

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

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

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


File: lispref.info,  Node: Regexp Example,  Prev: Syntax of Regexps,  Up: Regular Expressions

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

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

   First, we show the regexp as a string in Lisp syntax to 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 the variable `sentence-end', you will
see the following:

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

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 set that matches any
     one of three characters: period, question mark, and exclamation
     mark.  The match must begin with one of these three characters.

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

`\\($\\| $\\|\t\\|  \\)'
     The third part of the pattern matches the whitespace that follows
     the end of a sentence: the end of a line, or a tab, or two spaces.
     The double backslashes 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: lispref.info,  Node: Regexp Search,  Next: POSIX Regexps,  Prev: Regular Expressions,  Up: Searching and Matching

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

In XEmacs, you can search for the next match for a regexp either
incrementally or not.  Incremental search commands are described in the
`The XEmacs Lisp Reference Manual'.  *Note Regular Expression Search:
(xemacs)Regexp Search.  Here we describe only the search functions
useful in programs.  The principal one is `re-search-forward'.

 -- Command: re-search-forward regexp &optional limit noerror count
          buffer
     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), then it is the upper bound to the search.  No match
     extending after that position is accepted.

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

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

     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 count
          buffer
     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.  The
     reason 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 regexps from end to beginning.  It's not
     worth the trouble of implementing that.

 -- Function: string-match regexp string &optional start buffer
     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.

     Optional arg BUFFER controls how case folding is done (according
     to the value of `case-fold-search' in BUFFER and BUFFER's case
     tables) and defaults to the current buffer.

     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

   The function `split-string' can be used to parse a string into
components delimited by text matching a regular expression.

 -- Variable: split-string-default-separators
     The default value of SEPARATORS for `split-string', initially `"[
     \f\t\n\r\v]+"'.

 -- Function: split-string string &optional separators omit-nulls
     This function splits STRING into substrings delimited by matches
     for the regular expression SEPARATORS.  Each match for SEPARATORS
     defines a splitting point; the substrings between the splitting
     points are made into a list, which is the value returned by
     `split-string'.  If OMIT-NULLS is `t', null strings will be
     removed from the result list.  Otherwise, null strings are left in
     the result.  If SEPARATORS is `nil' (or omitted), the default is
     the value of `split-string-default-separators'.

     As a special case, when SEPARATORS is `nil' (or omitted), null
     strings are always omitted from the result.  Thus:

          (split-string "  two words ")
               => ("two" "words")

     The result is not `("" "two" "words" "")', which would rarely be
     useful.  If you need such a result, use an explict value for
     SEPARATORS:

          (split-string "  two words " split-string-default-separators)
               => ("" "two" "words" "")

     A few examples (there are more in the regression tests):

          (split-string "foo" "")
               => ("" "f" "o" "o" "")
          (split-string "foo" "^")
               => ("" "foo")
          (split-string "foo" "$")
               => ("foo" ""))
          (split-string "foo,bar" ",")
               => ("foo" "bar")
          (split-string ",foo,bar," ",")
               => ("" "foo" "bar" "")
          (split-string ",foo,bar," "^,")
               => ("" "foo,bar,")
          (split-string "foo,bar" "," t)
               => ("foo" "bar")
          (split-string ",foo,bar," "," t)
               => ("foo" "bar")

 -- Function: split-path path
     This function splits a search path into a list of strings.  The
     path components are separated with the characters specified with
     `path-separator'.  Under Unix, `path-separator' will normally be
     `:', while under Windows, it will be `;'.

 -- Function: looking-at regexp &optional buffer
     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


File: lispref.info,  Node: POSIX Regexps,  Next: Search and Replace,  Prev: Regexp Search,  Up: Searching and Matching

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

   In Emacs versions prior to 19.29, these functions did not exist, and
the functions described above implemented full POSIX backtracking.

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

 -- Command: posix-search-backward regexp &optional limit noerror count
          buffer
     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 &optional buffer
     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 buffer
     This is like `string-match' except that it performs the full
     backtracking specified by the POSIX standard for regular expression
     matching.

     Optional arg BUFFER controls how case folding is done (according
     to the value of `case-fold-search' in BUFFER and BUFFER's case
     tables) and defaults to the current buffer.


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

44.5 Search and Replace
=======================

 -- Function: perform-replace from-string replacements query-flag
          regexp-flag delimited-flag &optional repeat-count map
     This function is the guts of `query-replace' and related commands.
     It searches for occurrences of FROM-STRING and replaces some or
     all of them.  If QUERY-FLAG is `nil', it replaces all occurrences;
     otherwise, it asks the user what to do about each one.

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

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

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

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

 -- Variable: query-replace-map
     This variable holds a special keymap that defines the valid user
     responses for `query-replace' and related functions, as well as
     `y-or-n-p' and `map-y-or-n-p'.  It is 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: lispref.info,  Node: Match Data,  Next: Searching and Case,  Prev: Search and Replace,  Up: Searching and Matching

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

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

   Because the match data normally describe the most recent successful
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.

   To make it possible to write iterative or recursive code that
repeatedly searches, and uses the data from the last successful search
when no more matches can be found, a search or match which fails will
preserve the match data from the last successful search.  (You must not
depend on match data being preserved in case the search or match
signals an error.)  If for some reason you need to clear the match
data, you may use `(store-match-data nil)'.

* Menu:

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


File: lispref.info,  Node: Simple Match Data,  Next: Replacing Match,  Up: Match Data

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

   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.

 -- 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 COUNT is
     out of range, or if that subexpression didn't match anything, the
     value is `nil'.

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

 -- 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 in the match.

 -- 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: lispref.info,  Node: Replacing Match,  Next: Entire Match Data,  Prev: Simple Match Data,  Up: Match Data

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

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

 -- Function: replace-match replacement &optional fixedcase literal
          string strbuffer
     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.  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 the fourth argument STRING is a string, fifth argument
     STRBUFFER specifies the buffer to be used for syntax-table and
     case-table lookup and defaults to the current buffer.  When STRING
     is not a string, the buffer that the match occurred in has
     automatically been remembered and you do not need to specify it.

     If FIXEDCASE is non-`nil', then the case of the replacement text
     is not changed; otherwise, the replacement text is converted to a
     different case depending upon the capitalization of the text to be
     replaced.  If the original text is all upper case, the replacement
     text is converted to upper case.  If the first word of the
     original text is capitalized, then the first word of the
     replacement text is capitalized.  If the original text contains
     just one word, and that word is a capital letter, `replace-match'
     considers this a capitalized first word rather than all upper case.

     If `case-replace' is `nil', then case conversion is not done,
     regardless of the value of FIXEDCASE.  *Note Searching and Case::.

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

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


File: lispref.info,  Node: Entire Match Data,  Next: Saving Match Data,  Prev: Replacing Match,  Up: Match Data

44.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
     This function returns a newly constructed list containing all the
     information on what text the last search matched.  Element zero is
     the position of the beginning of the match for the whole
     expression; element one is the position of the end of the match
     for the expression.  The next two elements are the positions of
     the beginning and end of the match for the first subexpression,
     and so on.  In general, element number 2N corresponds to
     `(match-beginning N)'; and element number 2N + 1 corresponds to
     `(match-end N)'.

     All the elements are markers or `nil' if matching was done on a
     buffer, and all are integers or `nil' if matching was done on a
     string with `string-match'.  However, if the optional first
     argument INTEGERS is non-`nil', always use integers (rather than
     markers) to represent buffer positions.

     If the optional second argument REUSE is a list, reuse it as part
     of the value.  If REUSE is long enough to hold all the values, and
     if INTEGERS is non-`nil', no new lisp objects are created.

     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
     This function sets the match data from the elements of MATCH-LIST,
     which should be a list that was the value of a previous call to
     `match-data'.

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

     `store-match-data' is an alias for `set-match-data'.


File: lispref.info,  Node: Saving Match Data,  Prev: Entire Match Data,  Up: Match Data

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

 -- Special Form: save-match-data body...
     This special form executes BODY, saving and restoring the match
     data around it.

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

     (let ((data (match-data)))
       (unwind-protect
           ...   ; May change the original match data.
         (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: lispref.info,  Node: Searching and Case,  Next: Standard Regexps,  Prev: Match Data,  Up: Searching and Matching

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

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

   If you do not want this feature, set the variable `case-fold-search'
to `nil'.  Then all letters must match exactly, including case.  This
is a 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 Lisp functions use.

 -- User Option: case-replace
     This variable determines whether the 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.

     The function `replace-match' is where this variable actually has
     its effect.  *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: lispref.info,  Node: Standard Regexps,  Prev: Searching and Case,  Up: Searching and Matching

44.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 regexp 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
     `"[ \t\n\f]"', which matches a line starting with a space, tab,
     newline, or form feed (after its left margin).

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

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

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

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


File: lispref.info,  Node: Syntax Tables,  Next: Abbrevs,  Prev: Searching and Matching,  Up: Top

45 Syntax Tables
****************

A "syntax table" specifies the syntactic textual function of each
character.  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.

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


File: lispref.info,  Node: Syntax Basics,  Next: Syntax Descriptors,  Up: Syntax Tables

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

Under XEmacs 20 and later, a syntax table is a particular subtype of the
primitive char table type (*note Char Tables::), and each element of the
char table is an integer that encodes the syntax of the character in
question, or a cons of such an integer and a matching character (for
characters with parenthesis syntax).

   Under XEmacs 19, a syntax table is a vector of 256 elements; it
contains one entry for each of the 256 possible characters in an 8-bit
byte.  Each element is an integer that encodes the syntax of the
character in question. (The matching character, if any, is embedded in
the bits of this integer.)

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

   Each buffer has its own major mode, and each major mode has its own
idea of the syntactic class of various characters.  For example, in Lisp
mode, the character `;' begins a comment, but in C mode, it terminates
a statement.  To support these variations, XEmacs 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."  Most major modes' syntax tables inherit the
syntax of character codes 0 through 31 and 128 through 255.  This is
useful with character sets such as ISO Latin-1 that have additional
alphabetic characters in the range 128 to 255.  Just changing the
standard syntax for these characters affects all major modes.

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


File: lispref.info,  Node: Syntax Descriptors,  Next: Syntax Table Functions,  Prev: Syntax Basics,  Up: Syntax Tables

45.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 desired syntax.

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

   Each class is designated by a mnemonic character, which serves as the
name of the class when you need to specify a class.  Usually the
designator character is one that is frequently in that class; however,
its meaning as a designator is unvarying and independent of what syntax
that character 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 descriptor for the character `*' in C mode is
`. 23' (i.e., punctuation, matching character slot unused, second
character of a comment-starter, first character of an comment-ender),
and the entry for `/' is `. 14' (i.e., punctuation, matching character
slot unused, first character of a comment-starter, second character of
a comment-ender).

* Menu:

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


File: lispref.info,  Node: Syntax Class Table,  Next: Syntax Flags,  Up: Syntax Descriptors

45.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 with `-') 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 almost always classified as whitespace.  (The
     designator ` ' is accepted for backwards compatibility with older
     versions of XEmacs, but is deprecated.  It is invalid in GNU
     Emacs.)

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

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

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

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

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

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

 -- Syntax class: string quote
     "String quote characters" (designated with `"') 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 XEmacs 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 XEmacs Lisp, but it is
     used in Common Lisp.  C also has two string quote characters:
     double-quote for strings, and single-quote (`'') for character
     constants.

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

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

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

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

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

     This class is used for backslash in TeX mode.

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

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

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

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

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


File: lispref.info,  Node: Syntax Flags,  Prev: Syntax Class Table,  Up: Syntax Descriptors

45.2.2 Syntax Flags
-------------------

In addition to the classes, entries for characters in a syntax table
can include flags.  There are eleven possible flags, represented by the
digits `1'-`8', and the lowercase letters `a', `b', and `p'.

   All the flags except `p' are used to describe comment delimiters.
The digit flags indicate that a character can _also_ be part of a
multi-character comment sequence, in addition to the syntactic
properties associated with its character class.  The flags must be
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 (`*/').

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

   As an extension to GNU Emacs 19 and 20, XEmacs supports two arbitrary
comment-start sequences and two arbitrary comment-end sequences.  (Thus
the need for 8 flags.)  GNU Emacs restricts the comment-start sequences
to start with the same character, XEmacs does not.  This means that for
two-character sequences, where GNU Emacs uses the `b' flag, XEmacs uses
the digit flags `5'-`8'.

   A one character comment-end sequence applies to the "b" style if its
first character has the `b' flag set; otherwise, it applies to the "a"
style.  The `a' flag is optional.  These flags have no effect on
non-comment characters; two-character styles are determined by the
digit flags.

   The flags for a character C are:

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

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

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

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

   * `5' means C is the start of a two-character comment-start sequence
     of style "b".

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

   * `7' means C is the start of a two-character comment-end sequence
     of style "b".

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

   * `a' means that C as a comment delimiter belongs to the default "a"
     comment style.  (This flag is optional.)

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

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

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

   Lisp (as you would expect) has a simple comment syntax.

`;'
     `<'

newline
     `>'

   Note that no flags are used.  This defines two comment-delimiting
sequences:

`;'
     This is a single-character comment-start sequence because the
     syntax class is `<'.

newline
     This is a single character comment-end sequence because the syntax
     class is `>' and the `b' flag is not set.

   C++ (again, as you would expect) has a baroque, overrich, and
excessively complex comment syntax.

`/'
     `1456'

`*'
     `23'

newline
     `>b'

   Note that the "b" style mixes one-character and two-character
sequences.  The table above defines four comment-delimiting sequences:

`/*'
     This is a comment-start sequence for "a" style because the `1'
     flag is set on `/' and the `2' flag is set on `*'.

`//'
     This is a comment-start sequence for "b" style because both the `5'
     and the `6' flags are set on `/'.

`*/'
     This is a comment-end sequence for "a" style because the `3' flag
     is set on `*' and the `4' flag is set on `/'.

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


File: lispref.info,  Node: Syntax Table Functions,  Next: Motion and Syntax,  Prev: Syntax Descriptors,  Up: Syntax Tables

45.3 Syntax Table Functions
===========================

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

 -- Function: make-syntax-table &optional oldtable
     This function creates a new syntax table.  Character codes 0
     through 31 and 128 through 255 are set up to inherit from the
     standard syntax table.  The other character codes are set up by
     copying what the standard syntax table says about them.

     Most major mode syntax tables are created in this way.

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

 -- Command: modify-syntax-entry char-range syntax-descriptor &optional
          syntax-table
     This function sets the syntax entry for CHAR-RANGE according to
     SYNTAX-DESCRIPTOR.  CHAR-RANGE is either a single character or a
     range of characters, as used with `put-char-table'. The syntax is
     changed only for SYNTAX-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 CHAR-RANGE is discarded.

     An error is signaled if the first character of the syntax
     descriptor is not one of the twelve syntax class designator
     characters.

     Examples:

          ;; Put the space character in class whitespace.
          (modify-syntax-entry ?\  " ")
               => 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 &optional syntax-table
     This function returns the syntax class of CHARACTER, represented
     by its mnemonic designator character.  This _only_ returns the
     class, not any matching parenthesis or flags.

     An error is signaled if CHARACTER is not a character.

     The characters that correspond to various syntax codes are listed
     in the documentation of `modify-syntax-entry'.

     Optional second argument SYNTAX-TABLE is the syntax table to be
     used, and defaults to the current buffer's syntax table.

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

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

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

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

 -- Function: set-syntax-table syntax-table &optional buffer
     This function makes SYNTAX-TABLE the syntax table for BUFFER, which
     defaults to the current buffer if omitted.  It returns
     SYNTAX-TABLE.

 -- Function: syntax-table &optional buffer
     This function returns the syntax table for BUFFER, which defaults
     to the current buffer if omitted.


File: lispref.info,  Node: Motion and Syntax,  Next: Parsing Expressions,  Prev: Syntax Table Functions,  Up: Syntax Tables

45.4 Motion and Syntax
======================

This section describes functions for moving across characters in
certain syntax classes.  None of these functions exists in Emacs
version 18 or earlier.

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

 -- Function: skip-syntax-backward syntaxes &optional limit buffer
     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.  Optional argument BUFFER
     defaults to the current buffer if omitted.


 -- Function: backward-prefix-chars &optional buffer
     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.  Optional argument BUFFER defaults to the current buffer if
     omitted.


File: lispref.info,  Node: Parsing Expressions,  Next: Standard Syntax Tables,  Prev: Motion and Syntax,  Up: Syntax Tables

45.5 Parsing Balanced Expressions
=================================

Here are several functions for parsing and scanning balanced
expressions, also known as "sexps", in which parentheses match in
pairs.  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.

 -- Function: parse-partial-sexp start limit &optional target-depth
          stop-before state stop-comment buffer
     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 value describing
     the status of the parse at the point where it stops.

     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.

     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.

     The fifth argument STATE is an eight-element list of the same form
     as the value of this function, described below.  The return value
     of one call may be used to initialize the state of the parse on
     another call to `parse-partial-sexp'.

     The result is a list of eight elements describing the final state
     of the parse:

       0. The depth in parentheses, counting from 0.

       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.

       4. `t' if inside a comment (of either style).

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

       6. The minimum parenthesis depth encountered during this scan.

       7. `t' if inside a comment of style "b".

     Elements 0, 3, 4, 5 and 7 are significant in the argument STATE.

     This function is most often used to compute indentation for
     languages that have nested parentheses.

 -- Function: scan-lists from count depth &optional buffer noerror
     This function scans forward COUNT balanced parenthetical groupings
     from character number FROM.  It returns the character position
     where the scan stops.

     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.

     If optional arg BUFFER is non-`nil', scanning occurs in that
     buffer instead of in the current buffer.

     If optional arg NOERROR is non-`nil', `scan-lists' will return
     `nil' instead of signalling an error.

 -- Function: scan-sexps from count &optional buffer noerror
     This function scans forward COUNT sexps from character position
     FROM.  It returns the character position where the scan stops.

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

     If optional arg BUFFER is non-`nil', scanning occurs in that
     buffer instead of in the current buffer.

     If optional arg NOERROR is non-`nil', `scan-sexps' will return nil
     instead of signalling an error.

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

     In older Emacs versions, this feature worked only when the comment
     terminator is something like `*/', and appears only to end a
     comment.  In languages where newlines terminate comments, it was
     necessary make this variable `nil', since not every newline is the
     end of a comment.  This limitation no longer exists.

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

 -- Function: forward-comment &optional count buffer
     This function moves point forward across COUNT comments (backward,
     if COUNT is negative).  If it finds anything other than a comment
     or whitespace, it stops, leaving point at the place where it
     stopped.  It also stops after satisfying COUNT.  COUNT defaults to
     `1'.

     Optional argument BUFFER defaults to the current buffer.

   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: lispref.info,  Node: Standard Syntax Tables,  Next: Syntax Table Internals,  Prev: Parsing Expressions,  Up: Syntax Tables

45.6 Some Standard Syntax Tables
================================

Most of the major modes in XEmacs 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: lispref.info,  Node: Syntax Table Internals,  Prev: Standard Syntax Tables,  Up: Syntax Tables

45.7 Syntax Table Internals
===========================

Each element of a syntax table is an integer that encodes the syntax of
one character: the syntax class, possible matching character, and
flags.  Lisp programs don't usually work with the elements directly; the
Lisp-level syntax table functions usually work with syntax descriptors
(*note Syntax Descriptors::).

   The low 8 bits of each element of a syntax table indicate the syntax
class.

Integer
     Class

0
     whitespace

1
     punctuation

2
     word

3
     symbol

4
     open parenthesis

5
     close parenthesis

6
     expression prefix

7
     string quote

8
     paired delimiter

9
     escape

10
     character quote

11
     comment-start

12
     comment-end

13
     inherit

   The next 8 bits are the matching opposite parenthesis (if the
character has parenthesis syntax); otherwise, they are not meaningful.
The next 6 bits are the flags.


File: lispref.info,  Node: Abbrevs,  Next: Extents,  Prev: Syntax Tables,  Up: Top

46 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 contains
the use count, the number of times the abbreviation has been expanded.
Because these symbols 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:
(xemacs)Abbrevs.

* Menu:

* Abbrev Mode::                 Setting up XEmacs 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: lispref.info,  Node: Abbrev Mode,  Next: Abbrev Tables,  Up: Abbrevs

46.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 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: lispref.info,  Node: Abbrev Tables,  Next: Defining Abbrevs,  Prev: Abbrev Mode,  Up: Abbrevs

46.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.  The function returns `nil'.

 -- Function: define-abbrev-table table-name definitions
     This function defines TABLE-NAME (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)'.  The
     value is always `nil'.

 -- 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 value is always `nil'.

     If HUMAN is non-`nil', the description is human-oriented.
     Otherwise the description is a Lisp expression--a call to
     `define-abbrev-table' that would define NAME exactly as it is
     currently defined.


File: lispref.info,  Node: Defining Abbrevs,  Next: Abbrev Files,  Prev: Abbrev Tables,  Up: Abbrevs

46.3 Defining Abbrevs
=====================

These functions define an abbrev in a specified abbrev table.
`define-abbrev' is the low-level basic function, while `add-abbrev' is
used by commands that ask for information from the user.

 -- Function: add-abbrev table type arg
     This function adds an abbreviation to abbrev table TABLE based on
     information from the user.  The argument TYPE is a string
     describing in English the kind of abbrev this will be (typically,
     `"global"' or `"mode-specific"'); this is used in prompting the
     user.  The argument ARG is the number of words in the expansion.

     The return value is the symbol that internally represents the new
     abbrev, or `nil' if the user declines to confirm redefining an
     existing abbrev.

 -- Function: define-abbrev table name &optional expansion hook count
     This function defines an abbrev in TABLE named NAME, to expand to
     EXPANSION, and call HOOK.  The return value is an uninterned
     symbol that represents the abbrev inside XEmacs; its name is NAME.

     The argument NAME should be a string.  The argument EXPANSION
     should be a string, or `nil' to undefine the abbrev.

     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.

     The use count of the abbrev is initialized to zero.

 -- 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: lispref.info,  Node: Abbrev Files,  Next: Abbrev Expansion,  Prev: Defining Abbrevs,  Up: Abbrevs

46.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
     `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-abbrev' means that XEmacs should save
     abbrevs when files are saved.  `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.  This serves as a flag for various XEmacs commands to
     offer to save your abbrevs.

 -- Command: write-abbrev-file filename
     Save all abbrev definitions, in all abbrev tables, in the file
     FILENAME, in the form of a Lisp program that when loaded will
     define the same abbrevs.  This function returns `nil'.


File: lispref.info,  Node: Abbrev Expansion,  Next: Standard Abbrev Tables,  Prev: Abbrev Files,  Up: Abbrevs

46.5 Looking Up and Expanding Abbreviations
===========================================

Abbrevs are usually expanded by commands for interactive use, including
`self-insert-command'.  This section describes the subroutines used in
writing such functions, 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).  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 `t' if it did expansion, `nil' otherwise.

 -- Command: abbrev-prefix-mark &optional arg
     Mark current 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.

 -- 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
     This is the buffer position for `expand-abbrev' to use as the start
     of the next abbrev to be expanded.  (`nil' means 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 last abbrev expanded.  This
     information is left by `expand-abbrev' for the sake of the
     `unexpand-abbrev' command.

 -- Variable: last-abbrev-location
     This is the location of the last 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 last 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.

   The following sample code shows a simple use of
`pre-abbrev-expand-hook'.  If the user terminates an abbrev with a
punctuation character, the hook function asks for confirmation.  Thus,
this hook allows the user to decide whether to expand the abbrev, and
aborts expansion if it is not confirmed.

     (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)

     ;; This is the function invoked by `pre-abbrev-expand-hook'.

     ;; If the user terminated the abbrev with a space, the function does
     ;; nothing (that is, it returns so that the abbrev can expand).  If the
     ;; user entered some other character, this function asks whether
     ;; expansion should continue.

     ;; If the user answers the prompt with `y', the function returns
     ;; `nil' (because of the `not' function), but that is
     ;; acceptable; the return value has no effect on expansion.

     (defun query-if-not-space ()
       (if (/= ?\  (preceding-char))
           (if (not (y-or-n-p "Do you want to expand this abbrev? "))
               (error "Not expanding this abbrev"))))


File: lispref.info,  Node: Standard Abbrev Tables,  Prev: Abbrev Expansion,  Up: Abbrevs

46.6 Standard Abbrev Tables
===========================

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

 -- 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: c-mode-abbrev-table
     This is the local abbrev table used in C mode.

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


File: lispref.info,  Node: Extents,  Next: Specifiers,  Prev: Abbrevs,  Up: Top

47 Extents
**********

An "extent" is a region of text (a start position and an end position)
that is displayed in a particular face and can have certain other
properties such as being read-only.  Extents can overlap each other.
XEmacs efficiently handles buffers with large numbers of extents in
them.

 -- Function: extentp object
     This returns `t' if OBJECT is an extent.

* Menu:

* Intro to Extents::	   Extents are regions over a buffer or string.
* Creating and Modifying Extents::
			   Basic extent functions.
* Extent Endpoints::	   Accessing and setting the bounds of an extent.
* Finding Extents::	   Determining which extents are in an object.
* Mapping Over Extents::   More sophisticated functions for extent scanning.
* Extent Properties::	   Extents have built-in and user-definable properties.
* Detached Extents::	   Extents that are not in a buffer.
* Extent Parents::         Inheriting properties from another extent.
* Duplicable Extents::	   Extents can be marked to be copied into strings.
* Extents and Events::	   Extents can interact with the keyboard and mouse.
* Atomic Extents::	   Treating a block of text as a single entity.


File: lispref.info,  Node: Intro to Extents,  Next: Creating and Modifying Extents,  Up: Extents

47.1 Introduction to Extents
============================

An extent is a region of text within a buffer or string that has
certain properties associated with it.  The properties of an extent
primarily affect the way the text contained in the extent is displayed.
Extents can freely overlap each other in a buffer or string.  Extents
are invisible to functions that merely examine the text of a buffer or
string.

   _Please note:_ An alternative way to add properties to a buffer or
string is to use text properties.  *Note Text Properties::.

   An extent is logically a Lisp object consisting of a start position,
an end position, a buffer or string to which these positions refer, and
a property list.  As text is inserted into a buffer, the start and end
positions of the extent are automatically adjusted as necessary to keep
the extent referring to the same text in the buffer.  If text is
inserted at the boundary of an extent, the extent's `start-open' and
`end-open' properties control whether the text is included as part of
the extent.  If the text bounded by an extent is deleted, the extent
becomes "detached"; its start and end positions are no longer
meaningful, but it maintains all its other properties and can later be
reinserted into a buffer. (None of these considerations apply to
strings, because text cannot be inserted into or deleted from a string.)

   Each extent has a face or list of faces associated with it, which
controls the way in which the text bounded by the extent is displayed.
If an extent's face is `nil' or its properties are partially undefined,
the corresponding properties from the default face for the frame is
used.  If two or more extents overlap, or if a list of more than one
face is specified for a particular extent, the corresponding faces are
merged to determine the text's displayed properties.  Every extent has
a "priority" that determines which face takes precedence if the faces
conflict. (If two extents have the same priority, the one that comes
later in the display order takes precedence.  *Note display order:
Extent Endpoints.) Higher-numbered priority values correspond to a
higher priority, and priority values can be negative.  Every extent is
created with a priority of 0, but this can be changed with
`set-extent-priority'.  Within a single extent with a list of faces,
faces earlier in the list have a higher priority than faces later in
the list.

   Extents can be set to respond specially to key and mouse events
within the extent.  An extent's `keymap' property controls the effect of
key and mouse strokes within the extent's text, and the `mouse-face'
property controls whether the extent is highlighted when the mouse moves
over it.  *Note Extents and Events::.

   An extent can optionally have a "begin-glyph" or "end-glyph"
associated with it.  A begin-glyph or end-glyph is a pixmap or string
that will be displayed either at the start or end of an extent or in the
margin of the line that the start or end of the extent lies in,
depending on the extent's layout policy.  Begin-glyphs and end-glyphs
are used to implement annotations, and you should use the annotation API
functions in preference to the lower-level extent functions.  For more
information, *Note Annotations::.

   If an extent has its `detachable' property set, it will become
"detached" (i.e. no longer in the buffer) when all its text is deleted.
Otherwise, it will simply shrink down to zero-length and sit in the
same place in the buffer.  By default, the `detachable' property is set
on newly-created extents.  *Note Detached Extents::.

   If an extent has its `duplicable' property set, it will be
remembered when a string is created from text bounded by the extent.
When the string is re-inserted into a buffer, the extent will also be
re-inserted.  This mechanism is used in the kill, yank, and undo
commands.  *Note Duplicable Extents::.


File: lispref.info,  Node: Creating and Modifying Extents,  Next: Extent Endpoints,  Prev: Intro to Extents,  Up: Extents

47.2 Creating and Modifying Extents
===================================

 -- Function: make-extent from to &optional buffer-or-string
     This function makes an extent for the range [FROM, TO) in
     BUFFER-OR-STRING (a buffer or string).  BUFFER-OR-STRING defaults
     to the current buffer.  Insertions at point TO will be outside of
     the extent; insertions at FROM will be inside the extent, causing
     the extent to grow (*note Extent Endpoints::).  This is the same
     way that markers behave.  The extent is initially detached if both
     FROM and TO are `nil', and in this case BUFFER-OR-STRING defaults
     to `nil', meaning the extent is in no buffer or string (*note
     Detached Extents::).

 -- Function: delete-extent extent
     This function removes EXTENT from its buffer and destroys it.
     This does not modify the buffer's text, only its display
     properties.  The extent cannot be used thereafter.  To remove an
     extent in such a way that it can be re-inserted later, use
     `detach-extent'.  *Note Detached Extents::.

 -- Function: extent-object extent
     This function returns the buffer or string that EXTENT is in.  If
     the return value is `nil', this means that the extent is detached;
     however, a detached extent will not necessarily return a value of
     `nil'.

 -- Function: extent-live-p object
     This function returns `t' if OBJECT is an extent that has not been
     deleted, and `nil' otherwise.


File: lispref.info,  Node: Extent Endpoints,  Next: Finding Extents,  Prev: Creating and Modifying Extents,  Up: Extents

47.3 Extent Endpoints
=====================

Every extent has a start position and an end position, and logically
affects the characters between those positions.  Normally the start and
end positions must both be valid positions in the extent's buffer or
string.  However, both endpoints can be `nil', meaning the extent is
detached.  *Note Detached Extents::.

   Whether the extent overlaps its endpoints is governed by its
`start-open' and `end-open' properties.  Insertion of a character at a
closed endpoint will expand the extent to include that character;
insertion at an open endpoint will not.  Similarly, functions such as
`extent-at' that scan over all extents overlapping a particular
position will include extents with a closed endpoint at that position,
but not extents with an open endpoint.

   Note that the `start-closed' and `end-closed' properties are
equivalent to `start-open' and `end-open' with the opposite sense.

   Both endpoints can be equal, in which case the extent includes no
characters but still exists in the buffer or string.  Zero-length
extents are used to represent annotations (*note Annotations::) and can
be used as a more powerful form of a marker.  Deletion of all the
characters in an extent may or may not result in a zero-length extent;
this depends on the `detachable' property (*note Detached Extents::).
Insertion at the position of a zero-length extent expands the extent if
both endpoints are closed; goes before the extent if it has the
`start-open' property; and goes after the extent if it has the
`end-open' property.  Zero-length extents with both the `start-open'
and `end-open' properties are treated as if their starting point were
closed.  Deletion of a character on a side of a zero-length extent
whose corresponding endpoint is closed causes the extent to be detached
if its `detachable' property is set; if the corresponding endpoint is
open, the extent remains in the buffer, moving as necessary.

   Extents are ordered within a buffer or string by increasing start
position, and then by decreasing end position (this is called the
"display order").

 -- Function: extent-start-position extent
     This function returns the start position of EXTENT.

 -- Function: extent-end-position extent
     This function returns the end position of EXTENT.

 -- Function: extent-length extent
     This function returns the length of EXTENT in characters.  If the
     extent is detached, this returns `0'.  If the extent is not
     detached, this is equivalent to
          (- (extent-end-position EXTENT) (extent-start-position EXTENT))

 -- Function: set-extent-endpoints extent start end &optional
          buffer-or-string
     This function sets the start and end position of EXTENT to START
     and END.  If both are `nil', this is equivalent to `detach-extent'.

     BUFFER-OR-STRING specifies the new buffer or string that the
     extent should be in, and defaults to EXTENT's buffer or string.
     (If `nil', and EXTENT is in no buffer and no string, it defaults
     to the current buffer.)

     See documentation on `detach-extent' for a discussion of undo
     recording.


File: lispref.info,  Node: Finding Extents,  Next: Mapping Over Extents,  Prev: Extent Endpoints,  Up: Extents

47.4 Finding Extents
====================

The following functions provide a simple way of determining the extents
in a buffer or string.  A number of more sophisticated primitives for
mapping over the extents in a range of a buffer or string are also
provided (*note Mapping Over Extents::).  When reading through this
section, keep in mind the way that extents are ordered (*note Extent
Endpoints::).

 -- Function: extent-list &optional buffer-or-string from to flags
          property value
     This function returns a list of the extents in BUFFER-OR-STRING.
     BUFFER-OR-STRING defaults to the current buffer if omitted.  FROM
     and TO can be used to limit the range over which extents are
     returned; if omitted, all extents in the buffer or string are
     returned.

     More specifically, if a range is specified using FROM and TO, only
     extents that overlap the range (i.e. begin or end inside of the
     range) are included in the list.  FROM and TO default to the
     beginning and end of BUFFER-OR-STRING, respectively.

     FLAGS controls how end cases are treated.  For a discussion of
     this, and exactly what "overlap" means, see `map-extents'.

     The optional arguments PROPERTY and VALUE can be used to further
     restrict which extents are returned.  They have the same meaning
     as for `map-extents'.

     If you want to map a function over the extents in a buffer or
     string, consider using `map-extents' or `mapcar-extents' instead.

     See also the function `extents-at'.

   Functions that create extents must be prepared for the possibility
that there are other extents in the same area, created by other
functions.  To deal with this, functions typically mark their own
extents by setting a particular property on them.  The following
function makes it easier to locate those extents.

 -- Function: extent-at pos &optional object property before at-flag
     This function finds the "smallest" extent (i.e., the last one in
     the display order) at (i.e., overlapping) POS in OBJECT (a buffer
     or string) having PROPERTY set.  OBJECT defaults to the current
     buffer.  PROPERTY defaults to `nil', meaning that any extent will
     do.  Returns `nil' if there is no matching extent at POS.  If the
     fourth argument BEFORE is not `nil', it must be an extent; any
     returned extent will precede that extent.  This feature allows
     `extent-at' to be used by a loop over extents.

     AT-FLAG controls how end cases are handled (i.e. what "at" really
     means), and should be one of:

    `nil'

    `after'
          An extent is at POS if it covers the character after POS.
          This is consistent with the way that text properties work.

    `before'
          An extent is at POS if it covers the character before POS.

    `at'
          An extent is at POS if it overlaps or abuts POS.  This
          includes all zero-length extents at POS.

     Note that in all cases, the start-openness and end-openness of the
     extents considered is ignored.  If you want to pay attention to
     those properties, you should use `map-extents', which gives you
     more control.

   The following low-level functions are provided for explicitly
traversing the extents in a buffer according to the display order.
These functions are mostly intended for debugging--in normal operation,
you should probably use `mapcar-extents' or `map-extents', or loop
using the BEFORE argument to `extent-at', rather than creating a loop
using `next-extent'.

 -- Function: next-extent extent
     Given an extent EXTENT, this function returns the next extent in
     the buffer or string's display order.  If EXTENT is a buffer or
     string, this returns the first extent in the buffer or string.

 -- Function: previous-extent extent
     Given an extent EXTENT, this function returns the previous extent
     in the buffer or string's display order.  If EXTENT is a buffer or
     string, this returns the last extent in the buffer or string.


File: lispref.info,  Node: Mapping Over Extents,  Next: Extent Properties,  Prev: Finding Extents,  Up: Extents

47.5 Mapping Over Extents
=========================

The most basic and general function for mapping over extents is called
`map-extents'.  You should read through the definition of this function
to familiarize yourself with the concepts and optional arguments
involved.  However, in practice you may find it more convenient to use
the function `mapcar-extents' or to create a loop using the `before'
argument to `extent-at' (*note Finding Extents::).

 -- Function: map-extents function &optional object from to maparg
          flags property value
     This function maps FUNCTION over the extents which overlap a
     region in OBJECT.  OBJECT is normally a buffer or string but could
     be an extent (see below).  The region is normally bounded by
     [FROM, TO) (i.e. the beginning of the region is closed and the end
     of the region is open), but this can be changed with the FLAGS
     argument (see below for a complete discussion).

     FUNCTION is called with the arguments (extent, MAPARG).  The
     arguments OBJECT, FROM, TO, MAPARG, and FLAGS are all optional and
     default to the current buffer, the beginning of OBJECT, the end of
     OBJECT, `nil', and `nil', respectively.  `map-extents' returns the
     first non-`nil' result produced by FUNCTION, and no more calls to
     FUNCTION are made after it returns non-`nil'.

     If OBJECT is an extent, FROM and TO default to the extent's
     endpoints, and the mapping omits that extent and its predecessors.
     This feature supports restarting a loop based on `map-extents'.
     Note: OBJECT must be attached to a buffer or string, and the
     mapping is done over that buffer or string.

     An extent overlaps the region if there is any point in the extent
     that is also in the region. (For the purpose of overlap,
     zero-length extents and regions are treated as closed on both ends
     regardless of their endpoints' specified open/closedness.) Note
     that the endpoints of an extent or region are considered to be in
     that extent or region if and only if the corresponding end is
     closed.  For example, the extent [5,7] overlaps the region [2,5]
     because 5 is in both the extent and the region.  However, (5,7]
     does not overlap [2,5] because 5 is not in the extent, and neither
     [5,7] nor (5,7] overlaps the region [2,5) because 5 is not in the
     region.

     The optional FLAGS can be a symbol or a list of one or more
     symbols, modifying the behavior of `map-extents'.  Allowed symbols
     are:

    `end-closed'
          The region's end is closed.

    `start-open'
          The region's start is open.

    `all-extents-closed'
          Treat all extents as closed on both ends for the purpose of
          determining whether they overlap the region, irrespective of
          their actual open- or closedness.

    `all-extents-open'
          Treat all extents as open on both ends.

    `all-extents-closed-open'
          Treat all extents as start-closed, end-open.

    `all-extents-open-closed'
          Treat all extents as start-open, end-closed.

    `start-in-region'
          In addition to the above conditions for extent overlap, the
          extent's start position must lie within the specified region.
          Note that, for this condition, open start positions are
          treated as if 0.5 was added to the endpoint's value, and open
          end positions are treated as if 0.5 was subtracted from the
          endpoint's value.

    `end-in-region'
          The extent's end position must lie within the region.

    `start-and-end-in-region'
          Both the extent's start and end positions must lie within the
          region.

    `start-or-end-in-region'
          Either the extent's start or end position must lie within the
          region.

    `negate-in-region'
          The condition specified by a `*-in-region' flag must _not_
          hold for the extent to be considered.

     At most one of `all-extents-closed', `all-extents-open',
     `all-extents-closed-open', and `all-extents-open-closed' may be
     specified.

     At most one of `start-in-region', `end-in-region',
     `start-and-end-in-region', and `start-or-end-in-region' may be
     specified.

     If optional arg PROPERTY is non-`nil', only extents with that
     property set on them will be visited.  If optional arg VALUE is
     non-`nil', only extents whose value for that property is `eq' to
     VALUE will be visited.

   If you want to map over extents and accumulate a list of results,
the following function may be more convenient than `map-extents'.

 -- Function: mapcar-extents function &optional predicate
          buffer-or-string from to flags property value
     This function applies FUNCTION to all extents which overlap a
     region in BUFFER-OR-STRING.  The region is delimited by FROM and
     TO.  FUNCTION is called with one argument, the extent.  A list of
     the values returned by FUNCTION is returned.  An optional
     PREDICATE may be used to further limit the extents over which
     FUNCTION is mapped.  The optional arguments FLAGS, PROPERTY, and
     VALUE may also be used to control the extents passed to PREDICATE
     or FUNCTION, and have the same meaning as in `map-extents'.

 -- Function: map-extent-children function &optional object from to
          maparg flags property value
     This function is similar to `map-extents', but differs in that:

        * It only visits extents which start in the given region.

        * After visiting an extent E, it skips all other extents which
          start inside E but end before E's end.

     Thus, this function may be used to walk a tree of extents in a
     buffer:
          (defun walk-extents (buffer &optional ignore)
            (map-extent-children 'walk-extents buffer))

 -- Function: extent-in-region-p extent &optional from to flags
     This function returns `t' if `map-extents' would visit EXTENT if
     called with the given arguments.


File: lispref.info,  Node: Extent Properties,  Next: Detached Extents,  Prev: Mapping Over Extents,  Up: Extents

47.6 Properties of Extents
==========================

Each extent has a property list associating property names with values.
Some property names have predefined meanings, and can usually only
assume particular values.  Assigning other values to such a property
either cause the value to be converted into a legal value (e.g.,
assigning anything but `nil' to a Boolean property will cause the value
of `t' to be assigned to the property) or will cause an error.
Property names without predefined meanings can be assigned any value.
An undefined property is equivalent to a property with a value of
`nil', or with a particular default value in the case of properties
with predefined meanings.  Note that, when an extent is created, the
`end-open' and `detachable' properties are set on it.

   If an extent has a parent, all of its properties actually derive
from that parent (or from the root ancestor if the parent in turn has a
parent), and setting a property of the extent actually sets that
property on the parent.  *Note Extent Parents::.

 -- Function: extent-property extent property &optional default
     This function returns EXTENT's value for PROPERTY, or DEFAULT if
     no such property exists.

 -- Function: extent-properties extent
     This function returns a list of all of EXTENT's properties that do
     not have the value of `nil' (or the default value, for properties
     with predefined meanings).

 -- Function: set-extent-property extent property value
     This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a
     predefined meaning, only certain values are allowed, and some
     values may be converted to others before being stored.)

 -- Function: set-extent-properties extent plist
     Change some properties of EXTENT.  PLIST is a property list.  This
     is useful to change many extent properties at once.

   The following table lists the properties with predefined meanings,
along with their allowable values.

`detached'
     (Boolean) Whether the extent is detached.   Setting this is the
     same as calling `detach-extent'.  *Note Detached Extents::.

`destroyed'
     (Boolean) Whether the extent has been deleted.  Setting this is
     the same as calling `delete-extent'.

`priority'
     (integer) The extent's redisplay priority.  Defaults to 0.  *Note
     priority: Intro to Extents.  This property can also be set with
     `set-extent-priority' and accessed with `extent-priority'.

`start-open'
     (Boolean) Whether the start position of the extent is open,
     meaning that characters inserted at that position go outside of
     the extent.  *Note Extent Endpoints::.

`start-closed'
     (Boolean) Same as `start-open' but with the opposite sense.
     Setting this property clears `start-open' and vice-versa.

`end-open'
     (Boolean) Whether the end position of the extent is open, meaning
     that characters inserted at that position go outside of the
     extent.  This is `t' by default.  *Note Extent Endpoints::.

`end-closed'
     (Boolean) Same as `end-open' but with the opposite sense.  Setting
     this property clears `end-open' and vice-versa.

`read-only'
     (Boolean) Whether text within this extent will be unmodifiable.

`face'
     (face, face name, list of faces or face names, or `nil') The face
     in which to display the extent's text.  This property can also be
     set with `set-extent-face' and accessed with `extent-face'.  Note
     that if a list of faces is specified, the faces are merged
     together, with faces earlier in the list having priority over
     faces later in the list.

`mouse-face'
     (face, face name, list of faces or face names, or `nil') The face
     used to display the extent when the mouse moves over it.  This
     property can also be set with `set-extent-mouse-face' and accessed
     with `extent-mouse-face'.  Note that if a list of faces is
     specified, the faces are merged together, with faces earlier in
     the list having priority over faces later in the list.  *Note
     Extents and Events::.

`pointer'
     (pointer glyph)  The glyph used as the pointer when the mouse
     moves over the extent.  This takes precedence over the
     `text-pointer-glyph' and `nontext-pointer-glyph' variables.  If
     for any reason this glyph is an invalid pointer, the standard
     glyphs will be used as fallbacks.  *Note External Glyphs::.

`detachable'
     (Boolean) Whether this extent becomes detached when all of the
     text it covers is deleted.  This is `t' by default.  *Note
     Detached Extents::.

`duplicable'
     (Boolean) Whether this extent should be copied into strings, so
     that kill, yank, and undo commands will restore or copy it.  *Note
     Duplicable Extents::.

`unique'
     (Boolean) Meaningful only in conjunction with `duplicable'.  When
     this is set, there may be only one instance of this extent
     attached at a time.  *Note Duplicable Extents::.

`invisible'
     (Boolean) If `t', text under this extent will not be displayed -
     it will look as if the text and the begin-glyph is not there at
     all.  The end-glyph will still be displayed.

`keymap'
     (keymap or `nil') This keymap is consulted for mouse clicks on this
     extent or keypresses made while `point' is within the extent.
     *Note Extents and Events::.

`copy-function'
     This is a hook that is run when a duplicable extent is about to be
     copied from a buffer to a string (or the kill ring).  *Note
     Duplicable Extents::.

`paste-function'
     This is a hook that is run when a duplicable extent is about to be
     copied from a string (or the kill ring) into a buffer.  *Note
     Duplicable Extents::.

`begin-glyph'
     (glyph or `nil') This extent's begin glyph.  *Note Annotations::.

`end-glyph'
     (glyph or `nil') This extent's end glyph.  *Note Annotations::.

`begin-glyph-layout'
     (`text', `whitespace', `inside-margin', or `outside-margin') The
     layout policy for this extent's begin glyph.  Defaults to `text'.
     *Note Annotations::.

`end-glyph-layout'
     (`text', `whitespace', `inside-margin', or `outside-margin') The
     layout policy for this extent's end glyph.  Defaults to `text'.
     *Note Annotations::.

`initial-redisplay-function'
     (any funcallable object) The function to be called the first time
     (a part of) the extent is redisplayed.  It will be called with the
     extent as its argument.

     This is used by `lazy-shot' to implement lazy font-locking.  The
     functionality is still experimental, and may change without further
     notice.

   The following convenience functions are provided for accessing
particular properties of an extent.

 -- Function: extent-face extent
     This function returns the `face' property of EXTENT.  This might
     also return a list of face names.  Do not modify this list
     directly!  Instead, use `set-extent-face'.

     Note that you can use `eq' to compare lists of faces as returned
     by `extent-face'.  In other words, if you set the face of two
     different extents to two lists that are `equal' but not `eq', then
     the return value of `extent-face' on the two extents will return
     the identical list.

 -- Function: extent-mouse-face extent
     This function returns the `mouse-face' property of EXTENT.  This
     might also return a list of face names.  Do not modify this list
     directly!  Instead, use `set-extent-mouse-face'.

     Note that you can use `eq' to compare lists of faces as returned
     by `extent-mouse-face', just like for `extent-face'.

 -- Function: extent-priority extent
     This function returns the `priority' property of EXTENT.

 -- Function: extent-keymap extent
     This function returns the `keymap' property of EXTENT.

 -- Function: extent-begin-glyph-layout extent
     This function returns the `begin-glyph-layout' property of EXTENT,
     i.e. the layout policy associated with the EXTENT's begin glyph.

 -- Function: extent-end-glyph-layout extent
     This function returns the `end-glyph-layout' property of EXTENT,
     i.e. the layout policy associated with the EXTENT's end glyph.

 -- Function: extent-begin-glyph extent
     This function returns the `begin-glyph' property of EXTENT, i.e.
     the glyph object displayed at the beginning of EXTENT.  If there
     is none, `nil' is returned.

 -- Function: extent-end-glyph extent
     This function returns the `end-glyph' property of EXTENT, i.e. the
     glyph object displayed at the end of EXTENT.  If there is none,
     `nil' is returned.

   The following convenience functions are provided for setting
particular properties of an extent.

 -- Function: set-extent-priority extent priority
     This function sets the `priority' property of EXTENT to PRIORITY.

 -- Function: set-extent-face extent face
     This function sets the `face' property of EXTENT to FACE.

 -- Function: set-extent-mouse-face extent face
     This function sets the `mouse-face' property of EXTENT to FACE.

 -- Function: set-extent-keymap extent keymap
     This function sets the `keymap' property of EXTENT to KEYMAP.
     KEYMAP must be either a keymap object, or `nil'.

 -- Function: set-extent-begin-glyph-layout extent layout
     This function sets the `begin-glyph-layout' property of EXTENT to
     LAYOUT.

 -- Function: set-extent-end-glyph-layout extent layout
     This function sets the `end-glyph-layout' property of EXTENT to
     LAYOUT.

 -- Function: set-extent-begin-glyph extent begin-glyph &optional layout
     This function sets the `begin-glyph' and `glyph-layout' properties
     of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT
     defaults to `text' if not specified.)

 -- Function: set-extent-end-glyph extent end-glyph &optional layout
     This function sets the `end-glyph' and `glyph-layout' properties
     of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults
     to `text' if not specified.)

 -- Function: set-extent-initial-redisplay-function extent function
     This function sets the `initial-redisplay-function' property of the
     extent to FUNCTION.


File: lispref.info,  Node: Detached Extents,  Next: Extent Parents,  Prev: Extent Properties,  Up: Extents

47.7 Detached Extents
=====================

A detached extent is an extent that is not attached to a buffer or
string but can be re-inserted.  Detached extents have a start position
and end position of `nil'.  Extents can be explicitly detached using
`detach-extent'.  An extent is also detached when all of its characters
are all killed by a deletion, if its `detachable' property is set; if
this property is not set, the extent becomes a zero-length extent.
(Zero-length extents with the `detachable' property set behave
specially.  *Note zero-length extents: Extent Endpoints.)

 -- Function: detach-extent extent
     This function detaches EXTENT from its buffer or string.  If
     EXTENT has the `duplicable' property, its detachment is tracked by
     the undo mechanism.  *Note Duplicable Extents::.

 -- Function: extent-detached-p extent
     This function returns `nil' if EXTENT is detached, and `t'
     otherwise.

 -- Function: copy-extent extent &optional object
     This function makes a copy of EXTENT.  It is initially detached.
     Optional argument OBJECT defaults to EXTENT's object (normally a
     buffer or string, but could be `nil').

 -- Function: insert-extent extent &optional start end no-hooks object
     This function inserts EXTENT from START to END in OBJECT (a buffer
     or string).  If EXTENT is detached from a different buffer or
     string, or in most cases when EXTENT is already attached, the
     extent will first be copied as if with `copy-extent'.  This
     function operates the same as if `insert' were called on a string
     whose extent data calls for EXTENT to be inserted, except that if
     NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be
     invoked.  *Note Duplicable Extents::.


File: lispref.info,  Node: Extent Parents,  Next: Duplicable Extents,  Prev: Detached Extents,  Up: Extents

47.8 Extent Parents
===================

An extent can have a parent extent set for it.  If this is the case,
the extent derives all its properties from that extent and has no
properties of its own.  The only "properties" that the extent keeps are
the buffer or string it refers to and the start and end points.  (More
correctly, the extent's own properties are shadowed.  If you later
change the extent to have no parent, its own properties will become
visible again.)

   It is possible for an extent's parent to itself have a parent, and
so on.  Through this, a whole tree of extents can be created, all
deriving their properties from one root extent.  Note, however, that
you cannot create an inheritance loop--this is explicitly disallowed.

   Parent extents are used to implement the extents over the modeline.

 -- Function: set-extent-parent extent parent
     This function sets the parent of EXTENT to PARENT.  If PARENT is
     `nil', the extent is set to have no parent.

 -- Function: extent-parent extent
     This function return the parents (if any) of EXTENT, or `nil'.

 -- Function: extent-children extent
     This function returns a list of the children (if any) of EXTENT.
     The children of an extent are all those extents whose parent is
     that extent.  This function does not recursively trace children of
     children.

 -- Function: extent-descendants extent
     This function returns a list of all descendants of EXTENT,
     including EXTENT.  This recursively applies `extent-children' to
     any children of EXTENT, until no more children can be found.


File: lispref.info,  Node: Duplicable Extents,  Next: Extents and Events,  Prev: Extent Parents,  Up: Extents

47.9 Duplicable Extents
=======================

If an extent has the `duplicable' property, it will be copied into
strings, so that kill, yank, and undo commands will restore or copy it.

   Specifically:

   * When a string is created using `buffer-substring' or
     `buffer-string', any duplicable extents in the region corresponding
     to the string will be copied into the string (*note Buffer
     Contents::).  When the string is inserted into a buffer using
     `insert', `insert-before-markers', `insert-buffer' or
     `insert-buffer-substring', the extents in the string will be copied
     back into the buffer (*note Insertion::).  The extents in a string
     can, of course, be retrieved explicitly using the standard extent
     primitives over the string.

   * Similarly, when text is copied or cut into the kill ring, any
     duplicable extents will be remembered and reinserted later when
     the text is pasted back into a buffer.

   * When `concat' is called on strings, the extents in the strings are
     copied into the resulting string.

   * When `substring' is called on a string, the relevant extents are
     copied into the resulting string.

   * When a duplicable extent is detached by `detach-extent' or string
     deletion, or inserted by `insert-extent' or string insertion, the
     action is recorded by the undo mechanism so that it can be undone
     later.  Note that if an extent gets detached and then a later undo
     causes the extent to get reinserted, the new extent will not be
     `eq' to the original extent.

   * Extent motion, face changes, and attachment via `make-extent' are
     not recorded by the undo mechanism.  This means that extent changes
     which are to be undo-able must be performed by character editing,
     or by insertion and detachment of duplicable extents.

   * A duplicable extent's `copy-function' property, if non-`nil',
     should be a function, and will be run when a duplicable extent is
     about to be copied from a buffer to a string (or the kill ring).
     It is called with three arguments: the extent and the buffer
     positions within it which are being copied.  If this function
     returns `nil', then the extent will not be copied; otherwise it
     will.

   * A duplicable extent's `paste-function' property, if non-`nil',
     should be a function, and will be run when a duplicable extent is
     about to be copied from a string (or the kill ring) into a buffer.
     It is called with three arguments: the original extent and the
     buffer positions which the copied extent will occupy. (This hook
     is run after the corresponding text has already been inserted into
     the buffer.) Note that the extent argument may be detached when
     this function is run.  If this function returns `nil', no extent
     will be inserted.  Otherwise, there will be an extent covering the
     range in question.

     Note: if the extent to be copied is already attached to the buffer
     and overlaps the new range, the extent will simply be extended and
     the `paste-function' will not be called.


File: lispref.info,  Node: Extents and Events,  Next: Atomic Extents,  Prev: Duplicable Extents,  Up: Extents

47.10 Interaction of Extents with Keyboard and Mouse Events
===========================================================

If an extent has the `mouse-face' property set, it will be highlighted
when the mouse passes over it.  This includes the begin-glyph, but not
the end-glyph.  Highlighting is accomplished by merging the extent's
face with the face or faces specified by the `mouse-face' property.
The effect is as if a pseudo-extent with the `mouse-face' face were
inserted after the extent in the display order (*note Extent
Endpoints::, display order).

 -- Variable: mouse-highlight-priority
     This variable holds the priority to use when merging in the
     highlighting pseudo-extent.  The default is 1000.  This is
     purposely set very high so that the highlighting pseudo-extent
     shows up even if there are other extents with various priorities
     at the same location.

   You can also explicitly cause an extent to be highlighted.  Only one
extent at a time can be highlighted in this fashion, and any other
highlighted extent will be de-highlighted.

 -- Function: highlight-extent extent &optional highlight-p
     This function highlights (if HIGHLIGHT-P is non-`nil') or
     de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the
     `mouse-face' property. (Nothing happens if EXTENT does not have
     the `mouse-face' property.)

 -- Function: force-highlight-extent extent &optional highlight-p
     This function is similar to `highlight-extent' but highlights or
     de-highlights the extent regardless of whether it has the
     `mouse-face' property.

   If an extent has a `keymap' property, this keymap will be consulted
for mouse clicks on the extent and keypresses made while `point' is
within the extent.  The behavior of mouse clicks and keystrokes not
defined in the keymap is as normal for the buffer.


File: lispref.info,  Node: Atomic Extents,  Prev: Extents and Events,  Up: Extents

47.11 Atomic Extents
====================

If the Lisp file `atomic-extents' is loaded, then the atomic extent
facility is available.  An "atomic extent" is an extent for which
`point' cannot be positioned anywhere within it.  This ensures that
when selecting text, either all or none of the extent is selected.

   To make an extent atomic, set its `atomic' property.


File: lispref.info,  Node: Specifiers,  Next: Faces and Window-System Objects,  Prev: Extents,  Up: Top

48 Specifiers
*************

A specifier is an object used to keep track of a property whose value
should vary according to _display context_, a window, a frame, or
device.  The value of many built-in properties, such as the font,
foreground, background, and such properties of a face and variables
such as `modeline-shadow-thickness' and `top-toolbar-height', is
actually a specifier object.  The specifier object, in turn, is
"instanced" in a particular situation to yield the real value of the
property in the current context.

 -- Function: specifierp object
     This function returns non-`nil' if OBJECT is a specifier.

* Menu:

* Introduction to Specifiers::  Specifiers provide a clean way for
                                display and other properties to vary
                                (under user control) in a wide variety
                                of contexts.
* Simple Specifier Usage::      Getting started with specifiers.
* Specifiers In-Depth::         Gory details about specifier innards.
* Specifier Instancing::        Instancing means obtaining the ``value'' of
                                a specifier in a particular context.
* Specifier Types::             Specifiers come in different flavors.
* Adding Specifications::       Specifications control a specifier's ``value''
                                by giving conditions under which a
                                particular value is valid.
* Retrieving Specifications::   Querying a specifier's specifications.
* Specifier Tag Functions::     Working with specifier tags.
* Specifier Instancing Functions::
                                Functions to instance a specifier.
* Specifier Examples::          Making all this stuff clearer.
* Creating Specifiers::         Creating specifiers for your own use.
* Specifier Validation Functions::
                                Validating the components of a specifier.
* Other Specification Functions::
                                Other ways of working with specifications.
* Specifier Compatibility Notes::
                                Backward compatibility and GNU Emacs.


File: lispref.info,  Node: Introduction to Specifiers,  Next: Simple Specifier Usage,  Up: Specifiers

48.1 Introduction to Specifiers
===============================

Perhaps the most useful way to explain specifiers is via an analogy.
Emacs Lisp programmers are used to _buffer-local variables_ *Note
Buffer-Local Variables::. For example, the variable `modeline-format',
which controls the format of the modeline, can have different values
depending on the particular buffer being edited.  The variable has a
default value which most modes will use, but a specialized package such
as Calendar might change the variable so as to tailor the modeline to
its own purposes. Other variables are perhaps best thought of as "mode
local," such as font-lock keywords, but they are implemented as buffer
locals.

   Other properties (such as those that can be changed by the
`modify-frame-parameters' function, for example the color of the text
cursor) can have frame-local values, although it might also make sense
for them to have buffer-local values.  In other cases, you might want
the property to vary depending on the particular window within the
frame that applies (e.g. the top or bottom window in a split frame), the
device type that that frame appears on (X or tty), etc.  Perhaps you can
envision some more complicated scenario where you want a particular
value in a specified buffer, another value in all other buffers
displayed on a particular frame, another value in all other buffers
displayed in all other frames on any mono (two-color, e.g. black and
white only) displays, and a default value in all other circumstances.

   Specifiers generalize both buffer- and frame-local properties.
Specifiers vary according to the _display_ context.  Font-lock keywords
in a buffer will be the same no matter which window the buffer is
displayed in, but windows on TTY devices will simply not be capable of
the flexibility that windows on modern GUI devices are.  Specifiers
provide a way for the programmer to _declare_ that an emphasized text
should be italic on GUI devices and inverse video on TTYs.  They also
provide a way for the programmer to declare fallbacks, so that a color
specified as "chartreuse" where possible can fall back to "yellow" on
devices where only ANSI (4-bit) color is available.  The complex
calculations and device querying are transparent to both user and
programmer.  You ask for what you want; it's up to XEmacs to provide
it, or a reasonable approximation.

   We call such a declaration a "specification".  A "specification"
applies in a particular "locale", which is a window, buffer, frame,
device, or the global locale.  The value part of the specification is
called an "instantiator".  The process of determining the value in a
particular context, or "domain", is called "instantiation" or
"instancing".  A domain is a window, frame, or device.

   The difference between "locale" and "domain" is somewhat subtle.
You may think of a locale as a class of domains, which may span
different devices.  Since the specification is abstract (a Lisp form),
you can state it without reference to a device.  On the other hand, when
you instantiate a specification, you must know the type of the device.
It is useless to specify that "blue means emphasis" on a monochrome
device.  Thus instantiation requires specification of the device on
which it will be rendered.

   Thus a "specifier" allows a great deal of flexibility in controlling
exactly what value a property has in which circumstances.  Specifiers
are most commonly used for display properties, such as an image or the
foreground color of a face.  As a simple example, you can specify that
the foreground of the default face be

   * blue for a particular buffer

   * green for all other buffers

   As a more complicated example, you could specify that the foreground
of the default face be

   * forest green for all buffers displayed in a particular Emacs
     window, or green if the X server doesn't recognize the color
     `forest green'

   * blue for all buffers displayed in a particular frame

   * red for all other buffers displayed on a color device

   * white for all other buffers


File: lispref.info,  Node: Simple Specifier Usage,  Next: Specifiers In-Depth,  Prev: Introduction to Specifiers,  Up: Specifiers

48.2 Simple Specifier Usage
===========================

A useful specifier application is adding a button to a toolbar.  XEmacs
provides several toolbars, one along each edge of the frame.  Normally
only one is used at a time, the default.  The default toolbar is
actually a specifier object which is the value of `default-toolbar'.
*Note Toolbar Intro::.

   The specification of a toolbar is simple:  it is a list of buttons.
Each button is a vector with four elements:  an icon, a command, the
enabled flag, and a help string.  Let's retrieve the instance of the
toolbar you see in the selected frame.

     (specifier-instance default-toolbar)

   The value returned is, as promised, a list of vectors.  Now let's
build up a button, and add it to the toolbar.  Our button will invoke
the last defined keyboard macro.  This is an alternative to
`name-last-kbd-macro' for creating a persistent macro, rather than an
alias for `C-x e'.

   A toolbar button icon can be quite sophisticated, with different
images for button up, button down, and disabled states, and a similar
set with captions.  We'll use a very simple icon, but we have to jump
through a few non-obvious hoops designed to support the sophisticated
applications.  The rest of the button descriptor is straightforward.

     (setq toolbar-my-kbd-macro-button
       `[ (list (make-glyph "MyKbdMac"))
          (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
          t
          "Execute a previously defined keyboard macro." ])

     (set-specifier default-toolbar
                    (cons toolbar-my-kbd-macro-button
                          (specifier-specs default-toolbar 'global))
                    'global)

   To remove the button, just substitute the function `delete' for the
`cons' above.

   What is the difference between `specifier-instance', which we used
in the example of retrieving the toolbar descriptor, and
`specifier-specs', which was used in the toolbar manipulating code?
`specifier-specs' retrieves a copy of the instantiator, which is
abstract and does not depend on context.  `specifier-instance', on the
other hand, actually instantiates the specification, and returns the
result for the given context.  Another way to express this is:
`specifier-specs' takes a _locale_ as an argument, while
`specifier-instance' takes a _domain_.  The reason for providing
`specifier-instance' is that sometimes you wish to see the object that
XEmacs will actually use.  `specifier-specs', on the other hand, shows
you what the programmer (or user) requested.  When a program
manipulates specifications, clearly it's the latter that is desirable.

   In the case of the toolbar descriptor, it turns out that these are
the same:  the instancing process is trivial.  However, many
specifications have non-trivial instancing.  Compare the results of the
following forms on my system.  (The `(cdr (first ...))' form is due to
my use of Mule.  On non-Mule XEmacsen, just use `specifier-specs'.)

     (cdr (first (specifier-specs (face-font 'default) 'global)))
     => "-*--14-*jisx0208*-0"

     (specifier-instance (face-font 'default))
     #<font-instance "-*--14-*jisx0208*-0" on #<x-device on ":0.0" 0x970> 0xe0028b 0x176b>

   In this case, `specifier-instance' returns an opaque object;
programs can't work on it, they can only pass it around.  Worse, in some
environments the instantiation will fail, resulting in a different value
(when another instantiation succeeds), or worse yet, an error, if all
attempts to instance the specifier fail.  `specifier-instance' is
context-dependent, even for the exact same specification.
`specifier-specs' is deterministic, and only depends on the
specifications.

   Note that in the toolbar-changing code we operate in the global
locale.  This means that narrower locales, if they have specifications,
will shadow our changes.  (Specifier instancing does not merge
specifications.  It selects the "highest-priority successful
specification" and instances that.)

   In fact, in our example, it seems pretty likely that different
buffers _should_ have different buttons.  (The icon can be the same, but
the keyboard macro you create in a Dired buffer is highly unlikely to be
useful in a LaTeX buffer!)  Here's one way to implement this:

     (setq toolbar-my-kbd-macro-button
       `[ (list (make-glyph "MyKbdMac"))
          (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
          t
          "Execute a previously defined keyboard macro." ])

     (set-specifier default-toolbar
                    (cons toolbar-my-kbd-macro-button
                          (cond ((specifier-specs default-toolbar
                                                  (current-buffer)))
                                ((specifier-specs default-toolbar
                                                  'global)))
                    (current-buffer))

   Finally, a cautionary note: the use of `specifier-specs' in the code
above is for expository purposes.  Don't use it in production code.  In
fact, the `set-specifier' form above is likely to fail occasionally,
because you can add many specifications for the same locale.

   In these cases, `specifier-specs' will return a list.  A further
refinement is that a specification may be associated with a set of
"specifier tags".  If the list of specifier tags is non-nil, then
`specifier-specs' will return a cons of the tag set and the
instantiator.  Evidently `specifier-specs' is a bit unreliable.  (For
toolbars, the code above should work 99% of the time, because toolbars
are rarely changed.  Since instantiation is trivial, multiple specs are
not useful--the first one always succeeds.)

   In fact, `specifier-specs' is intended to be used to display specs
to humans with a minimum of clutter. The robust way to access
specifications is via `specifier-spec-list'. *Note Adding
Specifications::, for the definition of "spec-list". *Note Retrieving
Specifications::, for documentation of `specifier-specs' and
`specifier-spec-list'. To get the desired effect, replace the form
`(specifier-spec default-toolbar 'global)' with

     (cdr (second (first (specifier-spec-list default-toolbar 'global))))

   (It should be obvious why the example uses the lazy unreliable
method!)


File: lispref.info,  Node: Specifiers In-Depth,  Next: Specifier Instancing,  Prev: Simple Specifier Usage,  Up: Specifiers

48.3 In-Depth Overview of a Specifier
=====================================

Having variables vary according the editing context is very useful, and
the buffer is the natural "atomic" unit of editing context.  In a GUI
environment, it can be similarly useful to have variables whose values
vary according to display context.  The atomic unit of display context
is the Emacs window.  Buffers are cleanly grouped by modes, but windows
are not so easily pigeonholed.  On the one hand, a window displays a
buffer, and thus one possible hierarchy is window, buffer, mode.  On the
other, a window is a component of a frame.  This generates the window,
frame, device hierarchy.  Finally, there are objects such as toolbars
whose properties are described by specifiers.  These do not fit
naturally into either hierarchy.  This problem is as yet not cleanly
solved.

   Another potential source of conceptual confusion is the instantiation
process.  Instantiating a buffer-local variable is simple: at any given
point in time there is a current buffer, and its local values are used
and set whenever the variable is accessed, unless the programmer goes to
some special effort (uses `default-value' and `set-default'.  However,
a specifier object encapsulates a set of "specifications", each of
which says what its value should be if a particular condition applies.
Several such conditions might apply simultaneously in a given window.

   For example, one specification might be "The value should be
darkseagreen2 on X devices" another might be "The value should be blue
in the *Help* buffer".  So what do we do for "the *Help* buffer on an X
device"?  The answer is simple: give each type of locale a priority and
check them in priority order, returning the first instantiator that
successfully instantiates a value.

   Given a specifier, a logical question is "What is its value in a
particular situation?" This involves looking through the specifications
to see which ones apply to this particular situation, and perhaps
preferring one over another if more than one applies.  In specifier
terminology, a "particular situation" is called a "domain", and
determining its value in a particular domain is called "instancing".
Most of the time, a domain is identified by a particular window.  For
example, if the redisplay engine is drawing text in the default face in
a particular window, it retrieves the specifier for the foreground color
of the default face and "instances" it in the domain given by that
window; in other words, it asks the specifier, "What is your value in
this window?".

   Note that the redisplay example is in a sense canonical.  That is,
specifiers are designed to present a uniform and _efficient_ API to
redisplay.  It is the efficiency constraint that motivates the
introduction of specifier tags, and many restrictions on access (for
example, a buffer is not a domain, and you cannot instantiate a
specifier over a buffer).

   More specifically, a specifier contains a set of "specifications",
each of which associates a "locale" (a window object, a buffer object,
a frame object, a device object, or the symbol `global') with an
"inst-list", which is a list of one or more "inst-pairs". (For each
possible locale, there can be at most one specification containing that
locale.) Each inst-pair is a cons of a "tag set" (an unordered list of
zero or more symbols, or "tags") and an "instantiator" (the allowed
form of this varies depending on the type of specifier).  In a given
specification, there may be more than one inst-pair with the same tag
set; this is unlike for locales.

   The tag set is used to restrict the sorts of devices over which the
instantiator is valid and to uniquely identify instantiators added by a
particular application, so that different applications can work on the
same specifier and not interfere with each other.  Each tag can have a
"predicate" associated with it, which is a function of one argument (a
device) that specifies whether the tag matches that particular device.
(If a tag does not have a predicate, it matches all devices.)  All tags
in a tag set must match a device for the associated inst-pair to be
instantiable over that device.  (A null tag set is perfectly valid, and
trivially matches all devices.)

   The valid device types (normally `x', `tty', and `stream') and
device classes (normally `color', `grayscale', and `mono') can always
be used as tags, and match devices of the associated type or class
(*note Consoles and Devices::).  User-defined tags may be defined, with
an optional predicate specified.  An application can create its own
tag, use it to mark all its instantiators, and be fairly confident that
it will not interfere with other applications that modify the same
specifier--Functions that add a specification to a specifier usually
only overwrite existing inst-pairs with the same tag set as was given,
and a particular tag or tag set can be specified when removing
instantiators.

   When a specifier is instanced in a domain, both the locale and the
tag set can be viewed as specifying necessary conditions that must
apply in that domain for an instantiator to be considered as a possible
result of the instancing.  More specific locales always override more
general locales (thus, there is no particular ordering of the
specifications in a specifier); however, the tag sets are simply
considered in the order that the inst-pairs occur in the
specification's inst-list.

   Note also that the actual object that results from the instancing
(called an "instance object") may not be the same as the instantiator
from which it was derived.  For some specifier types (such as integer
specifiers and boolean specifiers), the instantiator will be returned
directly as the instance object.  For other types, however, this is not
the case.  For example, for font specifiers, the instantiator is a
font-description string and the instance object is a font-instance
object, which describes how the font is displayed on a particular
device.  A font-instance object encapsulates such things as the actual
font name used to display the font on that device (a font-description
string under X is usually a wildcard specification that may resolve to
different font names, with possibly different foundries, widths, etc.,
on different devices), the extra properties of that font on that
device, etc.  Furthermore, this conversion (called "instantiation")
might fail--a font or color might not exist on a particular device, for
example.


File: lispref.info,  Node: Specifier Instancing,  Next: Specifier Types,  Prev: Specifiers In-Depth,  Up: Specifiers

48.4 How a Specifier Is Instanced
=================================

Instancing of a specifier in a particular window domain proceeds as
follows:

   * First, XEmacs searches for a specification whose locale is the
     same as the window.  If that fails, the search is repeated,
     looking for a locale that is the same as the window's buffer.  If
     that fails, the search is repeated using the window's frame, then
     using the device that frame is on.  Finally, the specification
     whose locale is the symbol `global' (if there is such a
     specification) is considered.

   * The inst-pairs contained in the specification that was found are
     considered in their order in the inst-list, looking for one whose
     tag set matches the device that is derived from the window domain.
     (The tag set is an unordered list of zero or more tag symbols.
     For all tags that have predicates associated with them, the
     predicate must match the device.)

   * If a matching tag set is found, the corresponding instantiator is
     passed to the specifier's instantiation method, which is specific
     to the type of the specifier.  If it succeeds, the resulting
     instance object is returned as the result of the instancing and
     the instancing is done.  Otherwise, the operation continues,
     looking for another matching inst-pair in the current
     specification.

   * When there are no more inst-pairs to be considered in the current
     specification, the search starts over, looking for another
     specification as in the first step above.

   * If all specifications are exhausted and no instance object can be
     derived, the instancing fails. (Actually, this is not completely
     true.  Some specifier objects for built-in properties have a
     "fallback" value, which is either an inst-list or another
     specifier object, that is consulted if the instancing is about to
     fail.  If it is an inst-list, the searching proceeds using the
     inst-pairs in that list.  If it is a specifier, the entire
     instancing starts over using that specifier instead of the given
     one.  Fallback values are set by the C code and cannot be
     modified, except perhaps indirectly, using any Lisp functions.
     The purpose of them is to supply some values to make sure that
     instancing of built-in properties can't fail and to implement some
     basic specifier inheritance, such as the fact that faces inherit
     their properties from the `default' face.)

   It is also possible to instance a specifier over a frame domain or
device domain instead of over a window domain.  The C code, for example,
instances the `top-toolbar-height' variable over a frame domain in
order to determine the height of a frame's top toolbar.  Instancing over
a frame or device is similar to instancing over a window except that
specifications for locales that cannot be derived from the domain are
ignored.  Specifically, instancing over a frame looks first for frame
locales, then device locales, then the `global' locale.  Instancing
over a device domain looks only for device locales and the `global'
locale.

   Note that specifiers are instanced on _every_ redisplay.  (This is
the concept; of course the implementation keeps track of changes and
doesn't reinstance unchanged specifiers.)  That means that changes in
specifiers controlling appearance are reflected immediately in the UI.
Also, since specifiers are instanced completely, removing a
specification can be just as effective as adding one.

   _E.g._, Giacomo Boffi wanted a modeline that indicates whether the
frame containing it is selected or not.  The first proposed
implementation is natural in a world of "local" variables.  The later
implementations apply the power of specifiers.

   (The copyright notice and permission statement below apply to the
code in example format, up to the "`;;; end of neon-modeline.el'"
comment.)

     ;;; neon-modeline.el

     ;; Copyright (c) 2004  Stephen J. Turnbull <stephen@xemacs.org>

     ;; Based on a suggestion by Giacomo Boffi

     ;; This code may be used and redistributed under the GNU GPL, v.2 or any
     ;; later version as published by the FSF, or under the license used for
     ;; XEmacs Texinfo manuals, at your option.

   A few customizations:

     ;; Placate the specifier and Customize gods.

     (unless (valid-specifier-tag-p 'modeline-background)
       (define-specifier-tag 'modeline-background))

     (defgroup lisp-demos nil "Demos for Lisp programming techniques.")

     (defgroup neon-modeline nil "Neon modeline identifies selected frame."
       :group 'lisp-demos)

     (defcustom neon-modeline-selected-background "LemonChiffon"
       "Background color for modeline in selected frames."
       :type 'color
       :group 'neon-modeline)

     (defcustom neon-modeline-deselected-background "Wheat"
       "Background color for modeline in unselected frames."
       :type 'color
       :group 'neon-modeline)

   Our first try uses three functions, a setup and two hook functions.
Separate hooks are defined for entry into a frame and exit from it.
Since we're using hooks, it's a fairly natural approach: we operate on
the background on each event corresponding to an appearance change we
want to make.  This doesn't depend on the specifier API, "frame-local"
variables would serve as well.

     (defun select-modeline ()
       (set-face-background 'modeline neon-modeline-selected-background
     		       (selected-frame)))

     (defun deselect-modeline ()
       (set-face-background 'modeline neon-modeline-deselected-background
     		       (selected-frame)))

   Note that the initialization removes no specifications, and
therefore is not idempotent.  Cruft will accumulate in the specifier if
the `-setup' function is called repeatedly.  This shouldn't cause a
performance problem; specifiers are quite efficient for their purpose.
But it's ugly, and wastes a small amount of space.

     (defun neon-modeline-setup ()
       (interactive)
       (set-face-background 'modeline neon-modeline-deselected-background)
       ;; Add the distinguished background on pointer entry to the frame;
       (add-hook 'select-frame-hook 'select-modeline)
       ;; restore the ordinary background on pointer exit from the frame.
       (add-hook 'deselect-frame-hook 'deselect-modeline)

   This approach causes a decided flicker on Boffi's platform, because
the two hook functions are executed in response to separate GUI events.

   The following code should be an improvement.  First, the hook
function.

     (defun neon-modeline-reselect ()
       (set-face-background 'modeline neon-modeline-deselected-background
     		       (selected-frame) '(modeline-background)
     		       'remove-locale-type))

   Only one event triggers the configuration change, which should reduce
flicker.  Because this is implemented as a specifier, we can use the
specifier API to reset all frame-local specifications (the
`remove-locale-type' argument).  This leaves the `global' specification
alone, but removes all existing frame-local specifications.  Then it
adds the selected-frame background specification for the newly selected
frame.  _I.e._, this effectively implements a "move specification from
frame to frame" operation.

   Why does it give the desired result?  By ensuring that only one frame
has the selected-frame modeline background.  Frame-local specifications
have precedence over global ones, so when the modeline background is
instantiated in the selected frame, it matches the specification set up
for it and gets the right color.  On the other hand, in any other frame,
it does not match the selected frame, so it falls through the
frame-local specifications and picks up the global specification.  Again
we get the desired color, in this case for unselected frames.

   Here the `modeline-background' tag is simply good practice
(identifying an application's specifications allows it to avoid
interfering with other applications, and other well-behaved applications
and Customize should not munge specifications with our tag on them).
However, an alternative implementation of this functionality would be

     (defun neon-modeline-reselect-2 ()
       (set-face-background 'modeline neon-modeline-deselected-background
     		       (selected-frame) '(modeline-background)
     		       'remove-tag-set-prepend))

   `neon-modeline-reselect' may be a preferable implementation here, if
we really want only one frame to have a local specification.  The
`neon-modeline-reselect-2' style would be useful if we had groups of
frames which have _different_ modeline backgrounds when deselected.

   Here's the initialization function, with different semantics from
above.  Note that it is destructive, unless the user saves off the
state of the modeline face before invoking the function.  This is only
a problem if you remove specifications and expect the older ones to
persist.  In this example it should not be an issue.  We use the
customizations defined above.

     (defun neon-modeline-modified-setup ()
       (interactive)
       (set-face-background 'modeline neon-modeline-selected-background
     		       'global nil 'remove-all)
       (add-hook 'select-frame-hook 'neon-modeline-reselect)

     ;;; end of neon-modeline.el

   Note the use of `'remove-all' to clear out stale specifications.
Thus it will be idempotent.


File: lispref.info,  Node: Specifier Types,  Next: Adding Specifications,  Prev: Specifier Instancing,  Up: Specifiers

48.5 Specifier Types
====================

There are various different types of specifiers.  The type of a
specifier controls what sorts of instantiators are valid, how an
instantiator is instantiated, etc.  Here is a list of built-in specifier
types:

`boolean'
     The valid instantiators are the symbols `t' and `nil'.  Instance
     objects are the same as instantiators so no special instantiation
     function is needed.

`integer'
     The valid instantiators are integers.  Instance objects are the
     same as instantiators so no special instantiation function is
     needed.  `modeline-shadow-thickness' is an example of an integer
     specifier (negative thicknesses indicate that the shadow is drawn
     recessed instead of raised).

`natnum'
     The valid instantiators are natnums (non-negative integers).
     Instance objects are the same as instantiators so no special
     instantiation function is needed.  Natnum specifiers are used for
     dimension variables such as `top-toolbar-height'.

`generic'
     All Lisp objects are valid instantiators.  Instance objects are
     the same as instantiators so no special instantiation function is
     needed.

`font'
     The valid instantiators are strings describing fonts or vectors
     indicating inheritance from the font of some face.  Instance
     objects are font-instance objects, which are specific to a
     particular device.  The instantiation method for font specifiers
     can fail, unlike for integer, natnum, boolean, and generic
     specifiers.

`color'
     The valid instantiators are strings describing colors or vectors
     indicating inheritance from the foreground or background of some
     face.  Instance objects are color-instance objects, which are
     specific to a particular device.  The instantiation method for
     color specifiers can fail, as for font specifiers.

`image'
     Images are perhaps the most complicated type of built-in
     specifier.  The valid instantiators are strings (a filename,
     inline data for a pixmap, or text to be displayed in a text glyph)
     or vectors describing inline data of various sorts or indicating
     inheritance from the background-pixmap property of some face.
     Instance objects are either strings (for text images),
     image-instance objects (for pixmap images), or subwindow objects
     (for subwindow images).  The instantiation method for image
     specifiers can fail, as for font and color specifiers.

`face-boolean'
     The valid instantiators are the symbols `t' and `nil' and vectors
     indicating inheritance from a boolean property of some face.
     Specifiers of this sort are used for all of the built-in boolean
     properties of faces.  Instance objects are either the symbol `t'
     or the symbol `nil'.

`toolbar'
     The valid instantiators are toolbar descriptors, which are lists
     of toolbar-button descriptors (each of which is a vector of two or
     four elements).  *Note Toolbar::, for more information.

   Color and font instance objects can also be used in turn as
instantiators for a new color or font instance object.  Since these
instance objects are device-specific, the instantiator can be used
directly as the new instance object, but only if they are of the same
device.  If the devices differ, the base color or font of the
instantiating object is effectively used instead as the instantiator.

   *Note Faces and Window-System Objects::, for more information on
fonts, colors, and face-boolean specifiers.  *Note Glyphs::, for more
information about image specifiers.  *Note Toolbar::, for more
information on toolbar specifiers.

 -- Function: specifier-type specifier
     This function returns the type of SPECIFIER.  The returned value
     will be a symbol: one of `integer', `boolean', etc., as listed in
     the above table.

   Functions are also provided to query whether an object is a
particular kind of specifier:

 -- Function: boolean-specifier-p object
     This function returns non-`nil' if OBJECT is a boolean specifier.

 -- Function: integer-specifier-p object
     This function returns non-`nil' if OBJECT is an integer specifier.

 -- Function: natnum-specifier-p object
     This function returns non-`nil' if OBJECT is a natnum specifier.

 -- Function: generic-specifier-p object
     This function returns non-`nil' if OBJECT is a generic specifier.

 -- Function: face-boolean-specifier-p object
     This function returns non-`nil' if OBJECT is a face-boolean
     specifier.

 -- Function: toolbar-specifier-p object
     This function returns non-`nil' if OBJECT is a toolbar specifier.

 -- Function: font-specifier-p object
     This function returns non-`nil' if OBJECT is a font specifier.

 -- Function: color-specifier-p object
     This function returns non-`nil' if OBJECT is a color specifier.

 -- Function: image-specifier-p object
     This function returns non-`nil' if OBJECT is an image specifier.

