comparison lispref/text.texi @ 21682:90da2489c498

*** empty log message ***

21681:11eafe90b842

     @result{} "@@"
@end group
@end example
@end defun

@defun following-char
This function returns the character following point in the current
buffer.  This is similar to @code{(char-after (point))}.  However, if
point is at the end of the buffer, then @code{following-char} returns 0.

@end defun

@defun buffer-substring-no-properties start end
This is like @code{buffer-substring}, except that it does not copy text
properties, just the characters themselves.  @xref{Text Properties}.
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

@node Insertion
@section Inserting Text
@cindex insertion of text
@cindex text insertion

  @dfn{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
(@pxref{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 @code{insert-before-markers} relocate such markers to point after the
inserted text.

@cindex insertion before point
@cindex before point, insertion
  Some insertion functions leave point before the inserted text, while
other functions leave it after.  We call the former insertion @dfn{after
point} and the latter insertion @dfn{before point}.

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

  These functions copy text characters from strings and buffers along

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
This function inserts @var{count} instances of @var{character} into the
current buffer before point.  The argument @var{count} must be a number,
and @var{character} must be a character.  The value is @code{nil}.
@c It's unfortunate that count comes second.  Not like make-string, etc.

If @var{inherit} is non-@code{nil}, then the inserted characters inherit
sticky text properties from the two characters before and after the
insertion point.  @xref{Sticky Properties}.
@end defun

argument is supplied, then one character is deleted, but not saved in
the kill ring.

The value returned is always @code{nil}.
@end deffn

@node User-Level Deletion
@section User-Level Deletion Commands

  This section describes higher-level commands for deleting text,

@node The Kill Ring
@section The Kill Ring
@cindex kill ring

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

@end deffn

@node Low-Level Kill Ring
@subsection 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.

@defun current-kill n &optional do-not-move
The function @code{current-kill} rotates the yanking pointer which
designates the ``front'' of the kill ring by @var{n} places (from newer
kills to older ones), and returns the text at that place in the ring.

If the value is a function, @code{current-kill} calls it to get the
``most recent kill''.  If the function returns a non-@code{nil} value,
then that value is used as the ``most recent kill''.  If it returns
@code{nil}, then the first element of @code{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.  @xref{X Selections}.
@end defvar

@defvar 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
@code{nil} or a function of one argument.

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

pointing to the second entry in the kill ring @code{("some text" "a
different piece of text" "yet older text")}.  

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

has no effect.

This function returns @code{nil}.  It cannot be called interactively.

The name @code{buffer-flush-undo} is not considered obsolete, but the
preferred name @code{buffer-disable-undo} is new as of Emacs versions
19.
@end defun

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

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

  When you call the filling functions interactively, using a prefix
argument implies the value @code{full} for @var{justify}.

@deffn Command fill-paragraph justify

whitespace.
@end defun

@defvar left-margin
This variable specifies the base left margin column.  In Fundamental
mode, @key{LFD} indents to this column.  This variable automatically
becomes buffer-local when set in any fashion.
@end defvar

@node Auto Filling
@comment  node-name,  next,  previous,  up
@section Auto Filling

@end defvar

@defvar normal-auto-fill-function
This variable specifies the function to use for
@code{auto-fill-function}, if and when Auto Fill is turned on.  Major
modes can set this locally to alter how Auto Fill works.
@end defvar

@node Sorting
@section Sorting Text
@cindex sorting text

@group
  (interactive "P\nr")
  (save-restriction
    (narrow-to-region beg end)
    (goto-char (point-min))
    (sort-subr reverse
               'forward-line
               'end-of-line)))
@end group
@end example

Here @code{forward-line} moves point to the start of the next record,
and @code{end-of-line} moves point to the end of record.  We do not pass

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

Markers pointing into any sort records are left with no useful

containing position @var{beg}, and the entire line containing position
@var{end}, are included in the region sorted.

Note that @code{sort-columns} uses the @code{sort} utility program,
and so cannot work properly on text containing tab characters.  Use
@kbd{M-x @code{untabify}} to convert tabs to spaces before sorting.
@end deffn

@node Columns
@comment  node-name,  next,  previous,  up
@section Counting Columns

@node Primitive Indent
@subsection Indentation Primitives

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

@defun current-indentation
@comment !!Type Primitive Function
@comment !!SourceFile indent.c
This function returns the indentation of the current line, which is

@defopt indent-tabs-mode
@comment !!SourceFile indent.c
If this variable is non-@code{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.
@end defopt

@node Mode-Specific Indent
@subsection Indentation Controlled by Major Mode

@end deffn

@node Case Changes
@comment  node-name,  next,  previous,  up
@section Case Changes
@cindex case changes

  The case change commands described here work on text in the current
buffer.  @xref{Character Case}, for case conversion commands that work
on strings and characters.  @xref{Case Table}, for how to customize
which characters are upper or lower case and how to convert them.

@deffn Command capitalize-region start end
This function capitalizes all words in the region defined by
@var{start} and @var{end}.  To capitalize means to convert each word's

@node Special Properties
@subsection Properties with Special Meanings

  Here is a table of text property names that have special built-in
meanings.  The following section lists a few more special property names
that are used to control filling.  All other names have no standard
meaning, and you can use them as you like.

@table @code
@cindex category of text character
@kindex category @r{(text property)}
@item category

  (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

@node Registers
@section Registers
@cindex registers

  A register is a sort of variable used in Emacs 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 @kbd{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.

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

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

(defun indirect-after-change-function (beg end len)
  (let ((list my-own-after-change-functions))
    (while list
      (funcall (car list) beg end len)
      (setq list (cdr list)))))
(add-hooks 'after-change-functions
           'indirect-after-change-function)
@end example

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

21682:90da2489c498

     @result{} "@@"
@end group
@end example
@end defun

@defun char-before position
This function returns the character in the current buffer immediately
before position @var{position}.  If @var{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 @code{nil}.
@end defun

@defun following-char
This function returns the character following point in the current
buffer.  This is similar to @code{(char-after (point))}.  However, if
point is at the end of the buffer, then @code{following-char} returns 0.

@end defun

@defun buffer-substring-no-properties start end
This is like @code{buffer-substring}, except that it does not copy text
properties, just the characters themselves.  @xref{Text Properties}.
@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

@node Insertion
@section Inserting Text
@cindex insertion of text
@cindex text insertion

@cindex insertion before point
@cindex before point, insertion
  @dfn{Insertion} means adding new text to a buffer.  The inserted text
goes at point---between the character before point and the character
after point.  Some insertion functions leave point before the inserted
text, while other functions leave it after.  We call the former
insertion @dfn{after point} and the latter insertion @dfn{before point}.

  Insertion relocates markers that point at positions after the
insertion point, so that they stay with the surrounding text
(@pxref{Markers}).  When a marker points at the place of insertion,
insertion may or may not relocate the marker, depending on the marker's
insertion type (@pxref{Marker Insertion Types}).  Certain special
functions such as @code{insert-before-markers} relocate all such markers
to point after the inserted text, regardless of the markers' insertion
type.

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

  These functions copy text characters from strings and buffers along

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 &optional count inherit
This function inserts @var{count} instances of @var{character} into the
current buffer before point.  The argument @var{count} should be a
number (@code{nil} means 1), and @var{character} must be a character.
The value is @code{nil}.

If @var{inherit} is non-@code{nil}, then the inserted characters inherit
sticky text properties from the two characters before and after the
insertion point.  @xref{Sticky Properties}.
@end defun

argument is supplied, then one character is deleted, but not saved in
the kill ring.

The value returned is always @code{nil}.
@end deffn

@tindex backward-delete-char-untabify-method
@defopt backward-delete-char-untabify-method
This option specifies how @code{backward-delete-char-untabify} should
deal with whitespace.  Possible values include @code{untabify}, the
default, meaning convert a tab to many spaces and delete one;
@code{hungry}, meaning delete all the whitespace characters before point
with one command, and @code{nil}, meaning do nothing special for
whitespace characters.
@end defopt

@node User-Level Deletion
@section User-Level Deletion Commands

  This section describes higher-level commands for deleting text,

@node The Kill Ring
@section The Kill Ring
@cindex kill ring

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

@end deffn

@node Low-Level Kill Ring
@subsection 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, because they
take care of interaction with window system selections
(@pxref{Window System Selections}).

@defun current-kill n &optional do-not-move
The function @code{current-kill} rotates the yanking pointer which
designates the ``front'' of the kill ring by @var{n} places (from newer
kills to older ones), and returns the text at that place in the ring.

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

The normal use of this hook is to get the window system's primary
selection as the most recent kill, even if the selection belongs to
another application.  @xref{Window System Selections}.
@end defvar

@defvar 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
@code{nil} or a function of one argument.

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 window system's primary
selection from the newly killed text.  @xref{Window System Selections}.
@end defvar

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

pointing to the second entry in the kill ring @code{("some text" "a
different piece of text" "yet older text")}.  

@example
@group
kill-ring                  ---- kill-ring-yank-pointer
  |                       |
  |                       v
  |     --- ---          --- ---      --- ---
   --> |   |   |------> |   |   |--> |   |   |--> nil
        --- ---          --- ---      --- ---
         |                |            |            
         |                |            |            
         |                |             -->"yet older text" 
         |                |
         |                 --> "a different piece of text" 

has no effect.

This function returns @code{nil}.  It cannot be called interactively.

The name @code{buffer-flush-undo} is not considered obsolete, but the
preferred name is @code{buffer-disable-undo}.
@end defun

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

  Several of the filling functions have an argument @var{justify}.
If it is non-@code{nil}, that requests some kind of justification.  It
can be @code{left}, @code{right}, @code{full}, or @code{center}, to
request a specific style of justification.  If it is @code{t}, that
means to use the current justification style for this part of the text
(see @code{current-justification}, below).  Any other value is treated
as @code{full}.

  When you call the filling functions interactively, using a prefix
argument implies the value @code{full} for @var{justify}.

@deffn Command fill-paragraph justify

whitespace.
@end defun

@defvar left-margin
This variable specifies the base left margin column.  In Fundamental
mode, @kbd{C-j} indents to this column.  This variable automatically
becomes buffer-local when set in any fashion.
@end defvar

@tindex fill-nobreak-predicate
@defvar fill-nobreak-predicate
This variable gives major modes a way to specify not to break a line at
certain places.  Its value should be a function.  This function is
called during filling, with no arguments and with point located at the
place where a break is being considered.  If the function returns
non-@code{nil}, then the line won't be broken there.
@end defvar

@node Auto Filling
@comment  node-name,  next,  previous,  up
@section Auto Filling

@end defvar

@defvar normal-auto-fill-function
This variable specifies the function to use for
@code{auto-fill-function}, if and when Auto Fill is turned on.  Major
modes can set buffer-local values for this variable to alter how Auto
Fill works.
@end defvar

@node Sorting
@section Sorting Text
@cindex sorting text

@group
  (interactive "P\nr")
  (save-restriction
    (narrow-to-region beg end)
    (goto-char (point-min))
    (sort-subr reverse 'forward-line 'end-of-line)))
@end group
@end example

Here @code{forward-line} moves point to the start of the next record,
and @code{end-of-line} moves point to the end of record.  We do not pass

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

Markers pointing into any sort records are left with no useful

containing position @var{beg}, and the entire line containing position
@var{end}, are included in the region sorted.

Note that @code{sort-columns} uses the @code{sort} utility program,
and so cannot work properly on text containing tab characters.  Use
@kbd{M-x untabify} to convert tabs to spaces before sorting.
@end deffn

@node Columns
@comment  node-name,  next,  previous,  up
@section Counting Columns

@node Primitive Indent
@subsection Indentation Primitives

  This section describes the primitive functions used to count and
insert indentation.  The functions in the following sections use these
primitives.  @xref{Width}, for related functions.

@defun current-indentation
@comment !!Type Primitive Function
@comment !!SourceFile indent.c
This function returns the indentation of the current line, which is

@defopt indent-tabs-mode
@comment !!SourceFile indent.c
If this variable is non-@code{nil}, indentation functions can insert
tabs as well as spaces.  Otherwise, they insert only spaces.  Setting
this variable automatically makes it buffer-local in the current buffer.
@end defopt

@node Mode-Specific Indent
@subsection Indentation Controlled by Major Mode

@end deffn

@node Case Changes
@comment  node-name,  next,  previous,  up
@section Case Changes
@cindex case conversion in buffers

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

@deffn Command capitalize-region start end
This function capitalizes all words in the region defined by
@var{start} and @var{end}.  To capitalize means to convert each word's

@node Special Properties
@subsection Properties with Special Meanings

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

@table @code
@cindex category of text character
@kindex category @r{(text property)}
@item category

  (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

@node Registers
@section Registers
@cindex registers

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

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

  The @var{contents} of a register can have several possible types:

@table @asis
@item a number
A number stands for itself.  If @code{insert-register} finds a number
in the register, it converts the number to decimal.

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

@item a string
A string is text saved in the register.

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

@item @code{(@var{window-configuration} @var{position})}
This represents a window configuration to restore in one frame, and a
position to jump to in the current buffer.

@item @code{(@var{frame-configuration} @var{position})}
This represents a frame configuration to restore, and a position
to jump to in the current buffer.

@item (file @var{filename})
This represents a file to visit; jumping to this value visits file
@var{filename}.

@item (file-query @var{filename} @var{position})
This represents a file to visit and a position in it; jumping to this
value visits file @var{filename} and goes to buffer position
@var{position}.  Restoring this type of position asks the user for
confirmation first.
@end table

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

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

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.  When the after-change hooks are ultimately called, the
arguments specify a portion of the buffer including all of the changes
made within the @code{combine-after-change-calls} body.

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

@strong{Note:} If the changes you combine occur in widely scattered
parts of the buffer, this will still work, but it is not advisable,
because it may lead to inefficient behavior for some change hook
functions.
@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

(defun indirect-after-change-function (beg end len)
  (let ((list my-own-after-change-functions))
    (while list
      (funcall (car list) beg end len)
      (setq list (cdr list)))))

@group
(add-hooks 'after-change-functions
           'indirect-after-change-function)
@end group
@end example

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