comparison lispref/text.texi @ 88123:375f2633d815

New directory

52428:27bc8b966642

* Transposition::    Swapping two portions of a buffer.
* Registers::        How registers are implemented.  Accessing the text or
                       position stored in a register.
* Base 64::          Conversion to or from base 64 encoding.
* MD5 Checksum::     Compute the MD5 ``message digest''/``checksum''.
* Atomic Changes::   Installing several buffer changs ``atomically''.
* Change Hooks::     Supplying functions to be run when text is changed.
@end menu

@node Near Point
@section Examining Text Near Point

---------- Buffer: bar ----------
@end group
@end example
@end defun

@defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
This is like @code{insert-buffer-substring} except that it does not
copy any text properties.
@end defun

  @xref{Sticky Properties}, for other insertion functions that inherit
text properties from the nearby text in addition to inserting it.
Whitespace inserted by indentation functions also inherits text
properties.

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.
* Yanking::                How yanking is done.
* 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.
@end menu

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 &optional yank-handler
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
its text properties.  The value is always @code{nil}.

In an interactive call, @var{start} and @var{end} are point and

@c Emacs 19 feature
If the buffer or text is read-only, @code{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 a series of kill
commands to copy text from a read-only buffer into the kill ring.

If @var{yank-handler} is non-@code{nil}, this puts that value onto
the string of killed text, as a @code{yank-handler} property.
@xref{Yanking}.
@end deffn

@defopt kill-read-only-ok
If this option is non-@code{nil}, @code{kill-region} does not signal an
error if the buffer or text is read-only.  Instead, it simply returns,

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 Yanking
@subsection Yanking

  Yanking means inserting text from the kill ring, but it does
not insert the text blindly.  Yank commands and some other commands
use @code{insert-for-yank} to perform special processing on the
text that they copy into the buffer.

@defun insert-for-yank string
This function normally works like @code{insert} except that it doesn't
insert the text properties in the @code{yank-excluded-properties}
list.  However, if the first character of @var{string} has a
non-@code{nil}@code{yank-handler} text property, that property
can do various special processing on the text being inserted.
@end defun

@defun insert-buffer-substring-as-yank buf &optional start end
This function resembles @code{insert-buffer-substring} except that it
doesn't insert the text properties in the
@code{yank-excluded-properties} list.
@end defun

  You can put a @code{yank-handler} text property on the text to
control how it will be inserted if it is yanked.  The
@code{insert-for-yank} function looks for a @code{yank-handler}
property on the first character in its @var{string} argument.  The
property value must be a list of one to four elements, with the
following format (where elements after the first may be omitted):

@example
(@var{function} @var{param} @var{noexclude} @var{undo})
@end example

  Here is what the elements do:

@table @var
@item function
When @var{function} is present and non-nil, it is called instead of
@code{insert} to insert the string.  @var{function} takes one
argument---the string to insert.

@item param
If @var{param} is present and non-@code{nil}, it replaces @var{string}
as the object passed to @var{function} (or @code{insert}); for
example, if @var{function} is @code{yank-rectangle}, @var{param}
should be a list of strings to insert as a rectangle.

@item noexclude
If @var{noexclude} is present and non-@code{nil}, the normal removal of the
yank-excluded-properties is not performed; instead @var{function} is
responsible for removing those properties.  This may be necessary
if @var{function} adjusts point before or after inserting the object.

@item undo
If @var{undo} is present and non-nil, it is a function that will be
called by @code{yank-pop} to undo the insertion of the current object.
It is called with two arguments, the start and end of the current
region.  @var{function} can set @code{yank-undo-function} to override
the @var{undo} value.
@end table

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

  @dfn{Yanking} means reinserting an entry of previously killed text

oldest.

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

@defvar yank-undo-function
If this variable is non-@code{nil}, the function @code{yank-pop} uses
its value instead of @code{delete-region} to delete the text
inserted by the previous @code{yank} or
@code{yank-pop} command.

The function @code{insert-for-yank} automatically sets this variable
according to the @var{undo} element of the @code{yank-handler}
text property, if there is one.
@end defvar

@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

@code{current-kill} calls the value of
@code{interprogram-paste-function} (documented below) before consulting
the kill ring.
@end defun

@defun kill-new string &optional yank-handler
This function puts the text @var{string} into the kill ring as a new
entry at the front of the ring.  It discards the oldest entry if
appropriate.  It also invokes the value of
@code{interprogram-cut-function} (see below).

If @var{yank-handler} is non-@code{nil}, this puts that value onto
the string of killed text, as a @code{yank-handler} property.
@xref{Yanking}.
@end defun

@defun kill-append string before-p &optional yank-handler
This function appends the text @var{string} to the first entry in the
kill ring.  Normally @var{string} goes at the end of the entry, but if
@var{before-p} is non-@code{nil}, it goes at the beginning.  This
function also invokes the value of @code{interprogram-cut-function} (see
below).  This handles @var{yank-handler} just like @code{kill-new}.
@end defun

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

To remove all text properties from certain text, use
@code{set-text-properties} and specify @code{nil} for the new property
list.
@end defun

@defun remove-list-of-text-properties start end list-of-properties &optional object
Like @code{remove-list-properties} except that
@var{list-of-properties} is a list property names only, not an
alternating list of property values.
@end defun

@defun set-text-properties start end props &optional object
This function completely replaces the text property list 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.

using the specified or chosen coding system.  However, if
@var{noerror} is non-@code{nil}, it silently uses @code{raw-text}
coding instead.
@end defun

@node Atomic Changes
@section Atomic Change Groups
@cindex atomic changes

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

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

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

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

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

@defun prepare-change-group &optional buffer
This function sets up a change group for buffer @var{buffer}, which
defaults to the current buffer.  It returns a ``handle'' that
represents the change group.  You must use this handle to activate the
change group and subsequently to finish it.
@end defun

  To use the change group, you must @dfn{activate} it.  You must do
this before making any changes in the text of @var{buffer}.

@defun activate-change-group handle
This function activates the change group that @var{handle} designates.
@end defun

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

@defun accept-change-group handle
This function accepts all the changes in the change group specified by
@var{handle}, making them final.
@end defun

@defun cancel-change-group handle
This function cancels and undoes all the changes in the change group
specified by @var{handle}.
@end defun

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

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

@example
(nconc (prepare-change-group buffer-1)
       (prepare-change-group buffer-2))
@end example

You can then activate the multibuffer change group with a single call
to @code{activate-change-group}, and finish it with a single call to
@code{accept-change-group} or @code{cancel-change-group}.

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

@node Change Hooks
@section Change Hooks
@cindex change hooks
@cindex hooks for text changes

certain special text properties (@pxref{Special Properties}) and overlay
properties (@pxref{Overlay Properties}).

This variable is available starting in Emacs 21.
@end defvar

@ignore
   arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b
@end ignore

88123:375f2633d815

* Transposition::    Swapping two portions of a buffer.
* Registers::        How registers are implemented.  Accessing the text or
                       position stored in a register.
* Base 64::          Conversion to or from base 64 encoding.
* MD5 Checksum::     Compute the MD5 ``message digest''/``checksum''.
* Change Hooks::     Supplying functions to be run when text is changed.
@end menu

@node Near Point
@section Examining Text Near Point

---------- Buffer: bar ----------
@end group
@end example
@end defun

  @xref{Sticky Properties}, for other insertion functions that inherit
text properties from the nearby text in addition to inserting it.
Whitespace inserted by indentation functions also inherits text
properties.

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

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
its text properties.  The value is always @code{nil}.

In an interactive call, @var{start} and @var{end} are point and

@c Emacs 19 feature
If the buffer or text is read-only, @code{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 a series of kill
commands to copy text from a read-only buffer into the kill ring.
@end deffn

@defopt kill-read-only-ok
If this option is non-@code{nil}, @code{kill-region} does not signal an
error if the buffer or text is read-only.  Instead, it simply returns,

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

  @dfn{Yanking} means reinserting an entry of previously killed text

oldest.

The return value is always @code{nil}.
@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

@code{current-kill} calls the value of
@code{interprogram-paste-function} (documented below) before consulting
the kill ring.
@end defun

@defun kill-new string
This function puts the text @var{string} into the kill ring as a new
entry at the front of the ring.  It discards the oldest entry if
appropriate.  It also invokes the value of
@code{interprogram-cut-function} (see below).
@end defun

@defun kill-append string before-p
This function appends the text @var{string} to the first entry in the
kill ring.  Normally @var{string} goes at the end of the entry, but if
@var{before-p} is non-@code{nil}, it goes at the beginning.  This
function also invokes the value of @code{interprogram-cut-function} (see
below).
@end defun

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

To remove all text properties from certain text, use
@code{set-text-properties} and specify @code{nil} for the new property
list.
@end defun

@defun set-text-properties start end props &optional object
This function completely replaces the text property list 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.

using the specified or chosen coding system.  However, if
@var{noerror} is non-@code{nil}, it silently uses @code{raw-text}
coding instead.
@end defun

@node Change Hooks
@section Change Hooks
@cindex change hooks
@cindex hooks for text changes

certain special text properties (@pxref{Special Properties}) and overlay
properties (@pxref{Overlay Properties}).

This variable is available starting in Emacs 21.
@end defvar