comparison lispref/text.texi @ 21007:66d807bdc5b4

*** empty log message ***

21006:00022857f529

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/text
@node Text, Searching and Matching, Markers, Top
@chapter Text
@cindex text

  This chapter describes the functions that deal with the text in a
buffer.  Most examine, insert, or delete text in the current buffer,

the text.  See also @code{point-max} in @xref{Point}.
@end defun

@defun bolp
This function returns @code{t} if point is at the beginning of a line.
@xref{Text Lines}.  The beginning of the buffer (or its accessible
portion) always counts as the beginning of a line.
@end defun

@defun eolp
This function returns @code{t} if point is at the end of a line.  The

Here's an example of using this function to get a word to look up in an
alist:

@example
(setq flammable
      (assoc (buffer-substring start end)
             '(("wood" . t) ("paper" . t)
               ("steel" . nil) ("asbestos" . nil))))
@end example

If this were written using @code{buffer-substring} instead, it would not
work reliably; any text properties that happened to be in the word
copied from the buffer would make the comparisons fail.
@end defun

@defun buffer-string
This function returns the contents of the accessible portion of the
current buffer as a string.  This is the portion between
@code{(point-min)} and @code{(point-max)} (@pxref{Narrowing}).

@example
@group
---------- Buffer: foo ----------

(buffer-string)
     @result{} "This is the contents of buffer foo
"
@end group
@end example
@end defun

@node Comparing Text
@section Comparing Text

unless all @var{args} are either strings or characters.  The value is
@code{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.  If an overlat begins the insertion point, the
inserted text falls outside the overlay; if a nonempty overlay ends at
the insertion point, the inserted text falls inside that overlay.
@end defun

@defun insert-char character count &optional inherit

  @code{kill-region} is the usual subroutine for killing text.  Any
command that calls this function is a ``kill command'' (and should
probably have @samp{kill} in its name).  @code{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 @code{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.

@deffn Command kill-region start end
This function kills the text in the region defined by @var{start} and
@var{end}.  The text is deleted but saved in the kill ring, along with

The command does not set @code{this-command} to @code{kill-region}, so a
subsequent kill command does not append to the same kill ring entry.

Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
support Emacs 18.  For Emacs 19, it is better to use @code{kill-new} or
@code{kill-append} instead.  @xref{Low-Level Kill Ring}.
@end deffn

@node Yank Commands
@comment  node-name,  next,  previous,  up
@subsection Functions for Yanking

If the value is a function, @code{kill-new} and @code{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.
@end defvar

@node Internals of Kill Ring
@comment  node-name,  next,  previous,  up
@subsection Internals of the Kill Ring

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

@table @code
@item @var{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.

@item (@var{beg} . @var{end})
This kind of element indicates how to delete text that was inserted.
Upon insertion, the text occupied the range @var{beg}--@var{end} in the 

This variable alters the action of @code{fill-individual-paragraphs} as
described above.
@end defopt

@deffn 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
@var{justify} is non-@code{nil}.

In an interactive call, any prefix argument requests justification.

In Adaptive Fill mode, which is enabled by default, calling the function
@code{fill-region-as-paragraph} on an indented paragraph when there is

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

@defopt 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 (@pxref{Auto Filling}).

As a practical matter, if you are writing text for other people to
read, you should set @code{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.

a buffer.  This is in contrast to the function @code{sort}, which
rearranges the order of the elements of a list (@pxref{Rearrangement}).
The values returned by these functions are not meaningful.

@defun 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 @code{sort-subr} works, consider the whole accessible
portion of the buffer as being divided into disjoint pieces called
@dfn{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 @code{sort-subr} function, @var{reverse},

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

            (lambda () 
              (skip-chars-forward "\n \t\f")))
           'forward-paragraph)
@end group
@end example
@end defun

@deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
This command sorts the region between @var{start} and @var{end}
alphabetically as specified by @var{record-regexp} and @var{key-regexp}.

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 @sc{ASCII}
character set, the ordering in that set determines alphabetical order.
@c version 19 change

The value of the @var{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 @samp{^.+$}, which
matches lines with at least one character besides a newline, would make
each such line into a sort record.  @xref{Regular Expressions}, for a
description of the syntax and meaning of regular expressions.

The value of the @var{key-regexp} argument specifies what part of each
record is the sort key.  The @var{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 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 @code{ctl-arrow}, and tabs count as
occupying a number of columns that depends on the value of
@code{tab-width} and on the column where the tab begins.  @xref{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.

            This line is indented twelve spaces.
            @point{}The quick brown fox jumped.
@end group
@end example

  In this example, point is between the @samp{m} and @samp{p} of
@samp{jumped}:

@example
@group
            This line is indented twelve spaces.

@end example
@end deffn

@deffn Command indent-relative-maybe
@comment !!SourceFile indent.el
This command indents the current line like the previous nonblank line.
It calls @code{indent-relative} with @code{t} as the @var{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.
@end deffn

affect the display of tab characters in the buffer (@pxref{Usual
Display}).  Note that the @key{TAB} character as input uses this tab
stop feature only in a few major modes, such as Text mode.

@deffn Command tab-to-tab-stop
This command inserts spaces or tabs up to the next tab stop column
defined by @code{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.
@end deffn

@defopt tab-stop-list
This variable is the list of tab stop columns used by
@code{tab-to-tab-stops}.  The elements should be integers in increasing

                                  neighboring text.
* Saving Properties::           Saving text properties in files, and reading
                                  them back.
* Lazy Properties::             Computing text properties in a lazy fashion
                                  only when text is examined.
* Not Intervals::		Why text properties do not use
				  Lisp-visible text intervals.
@end menu

@node Examining Properties

between @var{start} and @var{end} in the string or buffer @var{object}.
If @var{object} is @code{nil}, it defaults to the current buffer.
@end defun

@defun add-text-properties start end props &optional object
This function modifies the text properties for the text between
@var{start} and @var{end} in the string or buffer @var{object}.  If
@var{object} is @code{nil}, it defaults to the current buffer.

The argument @var{props} specifies which properties to change.  It
should have the form of a property list (@pxref{Property Lists}): a list
whose elements include the property names followed alternately by the
corresponding values.

The return value is @code{t} if the function actually changed some
property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
its values agree with those in the text).

@example
(set-text-properties @var{start} @var{end} nil)
@end example
@end defun

See also the function @code{buffer-substring-no-properties}
(@pxref{Buffer Contents}) which copies text from the buffer
but does not copy its properties.

@node Property Search
@subsection 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 @code{eq} for
comparing property values.  In all cases, @var{object} defaults to the
current buffer.

For high performance, it's very important to use the @var{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.

@defun next-property-change pos &optional object limit
The function scans the text forward from position @var{pos} in the
string or buffer @var{object} till it finds a change in some text
property, then returns the position of the change.  In other words, it

@var{pos} instead of forward.  If the value is non-@code{nil}, it is a
position less than or equal to @var{pos}; it equals @var{pos} only if
@var{limit} equals @var{pos}.
@end defun

@defun text-property-any start end prop value &optional object
This function returns non-@code{nil} if at least one character between
@var{start} and @var{end} has a property @var{prop} whose value is
@var{value}.  More precisely, it returns the position of the first such
character.  Otherwise, it returns @code{nil}.

for @var{object} is the current buffer.
@end defun

@defun text-property-not-all start end prop value &optional object
This function returns non-@code{nil} if at least one character between
@var{start} and @var{end} has a property @var{prop} whose value differs
from @var{value}.  More precisely, it returns the position of the
first such character.  Otherwise, it returns @code{nil}.

The optional fifth argument, @var{object}, specifies the string or
buffer to scan.  Positions are relative to @var{object}.  The default
for @var{object} is the current buffer.
@end defun

@item face
@cindex face codes of text
@kindex face @r{(text property)}
You can use the property @code{face} to control the font and color of
text.  Its value is a face name or a list of face names.  @xref{Faces},
for more information.  This feature may be temporary; in the future, we
may replace it with other ways of specifying how to display text.

@item mouse-face
@kindex mouse-face @r{(text property)}
The property @code{mouse-face} is used instead of @code{face} when the
mouse is on or near the character.  For this purpose, ``near'' means

@code{mouse-face} property value.

@item local-map
@cindex keymap of character
@kindex local-map @r{(text property)}
You can specify a different keymap for a portion of the text by means of
a @code{local-map} property.  The property's value for the character
after point, if non-@code{nil}, replaces the buffer's local map.
@xref{Active Keymaps}.

@item read-only
@cindex read-only character
@kindex read-only @r{(text property)}
If a character has the property @code{read-only}, then modifying that

(which may be the same function) and/or two @code{point-entered}
functions (which may be the same function).  In any case, all the
@code{point-left} functions are called first, followed by all the
@code{point-entered} functions.

A primitive function may examine characters at various positions
without moving point to those positions.  Only an actual change in the
value of point runs these hook functions.
@end table

@defvar inhibit-point-motion-hooks
When this variable is non-@code{nil}, @code{point-left} and
@code{point-entered} hooks are not run, and the @code{intangible}
property has no effect.
@end defvar

@node Format Properties
@subsection Formatted Text Properties

Insert the strings @var{strings}, just like the function
@code{insert-before-markers}, but inherit any sticky properties from the
adjoining text.
@end defun

@node Saving Properties
@subsection Saving Text Properties in Files
@cindex text properties in files
@cindex saving text properties

  You can save text properties in files, and restore text properties
when inserting the files, using these two hooks: 

@defvar write-region-annotate-functions
This variable's value is a list of functions for @code{write-region} to
run to encode text properties in some fashion as annotations to the text
being written in the file.  @xref{Writing to Files}.

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
@code{(@var{position} . @var{string})}, where @var{position} is an
integer specifying the relative position in the text to be written, and
@var{string} is the annotation to add there.

Each list returned by one of these functions must be already sorted in
increasing order by @var{position}.  If there is more than one function,
@code{write-region} merges the lists destructively into one sorted list.

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.

@xref{Format Conversion}, for a related feature.

@c ??? In next edition, merge this info Format Conversion.

@code{buffer-access-fontify-functions} functions add this property, as
well as others, to the characters they operate on.  That way, they avoid
being called over and over for the same text.
@end defvar

@node Not Intervals
@subsection Why Text Properties are not Intervals
@cindex intervals

  Some editors that support adding attributes to text in the buffer do

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

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

  Emacs also provides explicit intervals as a presentation feature; see

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.
@c Will change in version 19

@defvar register-alist
This variable is an alist of elements of the form @code{(@var{name} .
@var{contents})}.  Normally, there is one element for each Emacs
register that has been used.

The object @var{name} is a character (an integer) identifying the
register.  The object @var{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.
@end defvar

@defun get-register reg
This function returns the contents of the register
@var{reg}, or @code{nil} if it has no contents.

data if they do anything that uses regular expressions; otherwise, they
will interfere in bizarre ways with the editing operations that call
them.

@defvar 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.
@end defvar

@defvar 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.  All three arguments are integers.  The buffer that's
about to change is always the current buffer.

difference between the first two arguments.  If you want the length
in @emph{characters} of the text before the change, you should use
a @code{before-change-functions} function that calls @code{chars-in-region}
(@pxref{Chars and Bytes}).
@end defvar

@defvar before-change-function
This obsolete variable holds one function to call before any buffer
modification (or @code{nil} for no function).  It is called just like
the functions in @code{before-change-functions}.

21007:66d807bdc5b4

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/text
@node Text, Non-ASCII Characters, Markers, Top
@chapter Text
@cindex text

  This chapter describes the functions that deal with the text in a
buffer.  Most examine, insert, or delete text in the current buffer,

the text.  See also @code{point-max} in @xref{Point}.
@end defun

@defun bolp
This function returns @code{t} if point is at the beginning of a line.
@xref{Text Lines}.  The beginning of the buffer (or of its accessible
portion) always counts as the beginning of a line.
@end defun

@defun eolp
This function returns @code{t} if point is at the end of a line.  The

Here's an example of using this function to get a word to look up in an
alist:

@example
(setq flammable
      (assoc (buffer-substring-no-properties start end)
             '(("wood" . t) ("paper" . t)
               ("steel" . nil) ("asbestos" . nil))))
@end example

If this were written using @code{buffer-substring} instead, it would not
work reliably; any text properties that happened to be in the word
copied from the buffer would make the comparisons fail.
@end defun

@defun buffer-string
This function returns the contents of the entire accessible portion of
the current buffer as a string.  This is the portion between
@code{(point-min)} and @code{(point-max)} (@pxref{Narrowing}).

@example
@group
---------- Buffer: foo ----------

(buffer-string)
     @result{} "This is the contents of buffer foo
"
@end group
@end example
@end defun

@defun thing-at-point thing
Return the @var{thing} around or next to point, as a string.

The argument @var{thing} is a symbol which specifies a kind of syntactic
entity.  Possibilities include @code{symbol}, @code{list}, @code{sexp},
@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
@code{whitespace}, @code{line}, @code{page}, and others.

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

(thing-at-point 'word)
     @result{} "Peace"
(thing-at-point 'line)
     @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
(thing-at-point 'whitespace)
     @result{} nil
@end example
@end defun

@node Comparing Text
@section Comparing Text

unless all @var{args} are either strings or characters.  The value is
@code{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.  If an overlay begins the insertion point, the
inserted text falls outside the overlay; if a nonempty overlay ends at
the insertion point, the inserted text falls inside that overlay.
@end defun

@defun insert-char character count &optional inherit

  @code{kill-region} is the usual subroutine for killing text.  Any
command that calls this function is a ``kill command'' (and should
probably have @samp{kill} in its name).  @code{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 determines automatically (using
@code{last-command}) whether the previous command was a kill command,
and if so appends the killed text to the most recent entry.

@deffn Command kill-region start end
This function kills the text in the region defined by @var{start} and
@var{end}.  The text is deleted but saved in the kill ring, along with

The command does not set @code{this-command} to @code{kill-region}, so a
subsequent kill command does not append to the same kill ring entry.

Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
support Emacs 18.  For newer Emacs versions, it is better to use
@code{kill-new} or @code{kill-append} instead.  @xref{Low-Level Kill
Ring}.
@end deffn

@node Yank Commands
@comment  node-name,  next,  previous,  up
@subsection Functions for Yanking

If the value is a function, @code{kill-new} and @code{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
from the newly killed text.
@end defvar

@node Internals of Kill Ring
@comment  node-name,  next,  previous,  up
@subsection Internals of the Kill Ring

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

@table @code
@item @var{integer}
This kind of element records a previous value of point.  Ordinary cursor
motion does not get any sort of undo record, but deletion operations use
these entries to record where point was before the command.

@item (@var{beg} . @var{end})
This kind of element indicates how to delete text that was inserted.
Upon insertion, the text occupied the range @var{beg}--@var{end} in the 

This variable alters the action of @code{fill-individual-paragraphs} as
described above.
@end defopt

@deffn Command fill-region-as-paragraph start end &optional justify
This command considers a region of text as a single 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 @var{justify} is non-@code{nil}.

In an interactive call, any prefix argument requests justification.

In Adaptive Fill mode, which is enabled by default, calling the function
@code{fill-region-as-paragraph} on an indented paragraph when there is

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

@defopt 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 (@pxref{Auto Filling}).

As a practical matter, if you are writing text for other people to
read, you should set @code{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.

a buffer.  This is in contrast to the function @code{sort}, which
rearranges the order of the elements of a list (@pxref{Rearrangement}).
The values returned by these functions are not meaningful.

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

To understand how @code{sort-subr} works, consider the whole accessible
portion of the buffer as being divided into disjoint pieces called
@dfn{sort records}.  The records may or may not be contiguous, but they
must 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 @code{sort-subr} function, @var{reverse},

@example
@group
;; @r{Note that the first two lines of doc string}
;; @r{are effectively one line when viewed by a user.}
(defun sort-lines (reverse beg end)
  "Sort lines in region alphabetically;\
 argument means descending order.
Called from a program, there are three arguments:
@end group
@group
REVERSE (non-nil means reverse order),\
 BEG and END (region to sort).
The variable `sort-fold-case' determines\
 whether alphabetic case affects
the sort order.
@end group
@group
  (interactive "P\nr")
  (save-restriction
    (narrow-to-region beg end)
    (goto-char (point-min))
    (sort-subr reverse

            (lambda () 
              (skip-chars-forward "\n \t\f")))
           'forward-paragraph)
@end group
@end example

Markers pointing into any sort records are left with no useful
position after @code{sort-subr} returns.
@end defun

@deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
This command sorts the region between @var{start} and @var{end}
alphabetically as specified by @var{record-regexp} and @var{key-regexp}.

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 character codes in the Emacs character set.

The value of the @var{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 taken
as the next record.  For example, the regular expression @samp{^.+$},
which matches lines with at least one character besides a newline, would
make each such line into a sort record.  @xref{Regular Expressions}, for
a description of the syntax and meaning of regular expressions.

The value of the @var{key-regexp} argument specifies what part of each
record is the sort key.  The @var{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 column functions convert between a character position (counting
characters from the beginning of the buffer) and a column position
(counting screen characters from the beginning of a line).

  These functions count each character according to the number of
columns it occupies on the screen.  This means control characters count
as occupying 2 or 4 columns, depending upon the value of
@code{ctl-arrow}, and tabs count as occupying a number of columns that
depends on the value of @code{tab-width} and on the column where the tab
begins.  @xref{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.

            This line is indented twelve spaces.
            @point{}The quick brown fox jumped.
@end group
@end example

  In this next example, point is between the @samp{m} and @samp{p} of
@samp{jumped}:

@example
@group
            This line is indented twelve spaces.

@end example
@end deffn

@deffn Command indent-relative-maybe
@comment !!SourceFile indent.el
This command indents the current line like the previous nonblank line,
by calling @code{indent-relative} with @code{t} as the
@var{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.
@end deffn

affect the display of tab characters in the buffer (@pxref{Usual
Display}).  Note that the @key{TAB} character as input uses this tab
stop feature only in a few major modes, such as Text mode.

@deffn Command tab-to-tab-stop
This command inserts spaces or tabs before point, up to the next tab
stop column defined by @code{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.
@end deffn

@defopt tab-stop-list
This variable is the list of tab stop columns used by
@code{tab-to-tab-stops}.  The elements should be integers in increasing

                                  neighboring text.
* Saving Properties::           Saving text properties in files, and reading
                                  them back.
* Lazy Properties::             Computing text properties in a lazy fashion
                                  only when text is examined.
* Clickable Text::              Using text properties to make regions of text
                                  do something when you click on them.
* Not Intervals::		Why text properties do not use
				  Lisp-visible text intervals.
@end menu

@node Examining Properties

between @var{start} and @var{end} in the string or buffer @var{object}.
If @var{object} is @code{nil}, it defaults to the current buffer.
@end defun

@defun add-text-properties start end props &optional object
This function adds or overrides text properties for the text between
@var{start} and @var{end} in the string or buffer @var{object}.  If
@var{object} is @code{nil}, it defaults to the current buffer.

The argument @var{props} specifies which properties to add.  It should
have the form of a property list (@pxref{Property Lists}): a list whose
elements include the property names followed alternately by the
corresponding values.

The return value is @code{t} if the function actually changed some
property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
its values agree with those in the text).

@example
(set-text-properties @var{start} @var{end} nil)
@end example
@end defun

  See also the function @code{buffer-substring-no-properties}
(@pxref{Buffer Contents}) which copies text from the buffer
but does not copy its properties.

@node Property Search
@subsection Text Property Search Functions

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

  Here are functions you can use to do this.  They use @code{eq} for
comparing property values.  In all cases, @var{object} defaults to the
current buffer.

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

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

@defun next-property-change pos &optional object limit
The function scans the text forward from position @var{pos} in the
string or buffer @var{object} till it finds a change in some text
property, then returns the position of the change.  In other words, it

@var{pos} instead of forward.  If the value is non-@code{nil}, it is a
position less than or equal to @var{pos}; it equals @var{pos} only if
@var{limit} equals @var{pos}.
@end defun

@tindex next-char-property-change
@defun next-char-property-change position &optional limit
This is like @code{next-property-change} except that it considers
overlay properties as well as text properties.  There is no @var{object}
operand because this function operates only on the current buffer.  It
returns the next address at which either kind of property changes.
@end defun

@tindex previous-char-property-change
@defun previous-char-property-change position &optional limit
This is like @code{next-char-property-change}, but scans back from
@var{position} instead of forward.
@end defun

@defun text-property-any start end prop value &optional object
This function returns non-@code{nil} if at least one character between
@var{start} and @var{end} has a property @var{prop} whose value is
@var{value}.  More precisely, it returns the position of the first such
character.  Otherwise, it returns @code{nil}.

for @var{object} is the current buffer.
@end defun

@defun text-property-not-all start end prop value &optional object
This function returns non-@code{nil} if at least one character between
@var{start} and @var{end} does not have a property @var{prop} with value
@var{value}.  More precisely, it returns the position of the first such
character.  Otherwise, it returns @code{nil}.

The optional fifth argument, @var{object}, specifies the string or
buffer to scan.  Positions are relative to @var{object}.  The default
for @var{object} is the current buffer.
@end defun

@item face
@cindex face codes of text
@kindex face @r{(text property)}
You can use the property @code{face} to control the font and color of
text.  Its value is a face name or a list of face names.  @xref{Faces},
for more information.

If the property value is a list, elements may also have the form
@code{(foreground-color . @var{color-name})} or @code{(background-color
. @var{color-name})}.  These elements specify just the foreground color
or just the background color; therefore, there is no need to create a
face for each color that you want to use.

@xref{Font Lock Mode}, for information on how to update @code{face}
properties automatically based on the contents of the text.

@item mouse-face
@kindex mouse-face @r{(text property)}
The property @code{mouse-face} is used instead of @code{face} when the
mouse is on or near the character.  For this purpose, ``near'' means

@code{mouse-face} property value.

@item local-map
@cindex keymap of character
@kindex local-map @r{(text property)}
You can specify a different keymap for some of the text in a buffer by
means of the @code{local-map} property.  The property's value for the
character after point, if non-@code{nil}, is used for key lookup instead
of the buffer's local map.  If the property value is a symbol, the
symbol's function definition is used as the keymap.  @xref{Active
Keymaps}.

@item syntax-table
The @code{syntax-table} property overrides what the syntax table says
about this particular character.  @xref{Syntax Properties}.

@item read-only
@cindex read-only character
@kindex read-only @r{(text property)}
If a character has the property @code{read-only}, then modifying that

(which may be the same function) and/or two @code{point-entered}
functions (which may be the same function).  In any case, all the
@code{point-left} functions are called first, followed by all the
@code{point-entered} functions.

It is possible using @code{char-after} to examine characters at various
positions without moving point to those positions.  Only an actual
change in the value of point runs these hook functions.
@end table

@defvar inhibit-point-motion-hooks
When this variable is non-@code{nil}, @code{point-left} and
@code{point-entered} hooks are not run, and the @code{intangible}
property has no effect.  Do not set this variable globally; bind it with
@code{let}.
@end defvar

@node Format Properties
@subsection Formatted Text Properties

Insert the strings @var{strings}, just like the function
@code{insert-before-markers}, but inherit any sticky properties from the
adjoining text.
@end defun

  @xref{Insertion}, for the ordinary insertion functions which do not
inherit.

@node Saving Properties
@subsection Saving Text Properties in Files
@cindex text properties in files
@cindex saving text properties

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

@defvar write-region-annotate-functions
This variable's value is a list of functions for @code{write-region} to
run to encode text properties in some fashion as annotations to the text
being written in the file.  @xref{Writing to Files}.

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
@code{(@var{position} . @var{string})}, where @var{position} is an
integer specifying the relative position within the text to be written,
and @var{string} is the annotation to add there.

Each list returned by one of these functions must be already sorted in
increasing order by @var{position}.  If there is more than one function,
@code{write-region} merges the lists destructively into one sorted list.

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

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

@xref{Format Conversion}, for a related feature.

@c ??? In next edition, merge this info Format Conversion.

@code{buffer-access-fontify-functions} functions add this property, as
well as others, to the characters they operate on.  That way, they avoid
being called over and over for the same text.
@end defvar

@node Clickable Text
@subsection Defining Clickable Text
@cindex clickable text

  There are two ways to set up @dfn{clickable text} in a buffer.
There are typically two parts of this: to make the text highlight
when the mouse is over it, and to make a mouse button do something
when you click it on that part of the text.

  Highlighting is done with the @code{mouse-face} text property.
Here is an example of how Dired does it:

@smallexample
(condition-case nil
    (if (dired-move-to-filename)
        (put-text-property (point)
                           (save-excursion
                             (dired-move-to-end-of-filename)
                             (point))
                           'mouse-face 'highlight))
  (error nil))
@end smallexample

@noindent
The first two arguments to @code{put-text-property} specify the
beginning and end of the text.

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

@smallexample
(defun dired-mouse-find-file-other-window (event)
  "In dired, visit the file or directory name you click on."
  (interactive "e")
  (let (file)
    (save-excursion
      (set-buffer (window-buffer (posn-window (event-end event))))
      (save-excursion
	(goto-char (posn-point (event-end event)))
	(setq file (dired-get-filename))))
    (select-window (posn-window (event-end event)))
    (find-file-other-window (file-name-sans-versions file t))))
@end smallexample

@noindent
The reason for the outer @code{save-excursion} construct is to avoid
changing the current buffer; the reason for the inner one is to avoid
permanently altering point in the buffer you click on.  In this case,
Dired uses the function @code{dired-get-filename} to determine which
file to visit, based on the position found in the event.

  Instead of defining a mouse command for the major mode, you can define
a key binding for the clickable text itself, using the @code{local-map}
text property:

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

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

@node Not Intervals
@subsection Why Text Properties are not Intervals
@cindex intervals

  Some editors that support adding attributes to text in the buffer do

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

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

  Emacs also provides explicit intervals as a presentation feature; see

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.

@defvar register-alist
This variable is an alist of elements of the form @code{(@var{name} .
@var{contents})}.  Normally, there is one element for each Emacs
register that has been used.

The object @var{name} is a character (an integer) identifying the
register.  The object @var{contents} is a string, marker, window
configuration, frame configuration, 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.
@end defvar

@defun get-register reg
This function returns the contents of the register
@var{reg}, or @code{nil} if it has no contents.

data if they do anything that uses regular expressions; otherwise, they
will interfere in bizarre ways with the editing operations that call
them.

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

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

difference between the first two arguments.  If you want the length
in @emph{characters} of the text before the change, you should use
a @code{before-change-functions} function that calls @code{chars-in-region}
(@pxref{Chars and Bytes}).
@end defvar

@tindex combine-after-change-calls
@defmac combine-after-change-calls body...
The macro executes @var{body} normally, but arranges to call the
after-change functions just once for a series of several changes---if
that seems safe.

If a program makes several text changes in the same area of the buffer,
using the macro @code{combine-after-change-calls} around that part of
the program can make it run considerably faster when after-change hooks
are in use.

@strong{Warning:} You must not alter the values of
@code{after-change-functions} and @code{after-change-function} within
the body of a @code{combine-after-change-calls} form.
@end defmac

@defvar before-change-function
This obsolete variable holds one function to call before any buffer
modification (or @code{nil} for no function).  It is called just like
the functions in @code{before-change-functions}.