/[emacs]/emacs/lispref/text.texi
ViewVC logotype

Diff of /emacs/lispref/text.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.56.2.1 by miles, Fri Apr 4 06:20:42 2003 UTC revision 1.56.2.2 by miles, Tue Oct 14 23:10:12 2003 UTC
# Line 58  the character after point. Line 58  the character after point.
58                         position stored in a register.                         position stored in a register.
59  * Base 64::          Conversion to or from base 64 encoding.  * Base 64::          Conversion to or from base 64 encoding.
60  * MD5 Checksum::     Compute the MD5 ``message digest''/``checksum''.  * MD5 Checksum::     Compute the MD5 ``message digest''/``checksum''.
61    * Atomic Changes::   Installing several buffer changs ``atomically''.
62  * Change Hooks::     Supplying functions to be run when text is changed.  * Change Hooks::     Supplying functions to be run when text is changed.
63  @end menu  @end menu
64    
# Line 89  }: Line 90  }:
90  @defun char-before &optional position  @defun char-before &optional position
91  This function returns the character in the current buffer immediately  This function returns the character in the current buffer immediately
92  before position @var{position}.  If @var{position} is out of range for  before position @var{position}.  If @var{position} is out of range for
93  this purpose, either before the beginning of the buffer, or at or beyond  this purpose, either at or before the beginning of the buffer, or beyond
94  the end, then the value is @code{nil}.  The default for  the end, then the value is @code{nil}.  The default for
95  @var{position} is point.  @var{position} is point.
96  @end defun  @end defun
# Line 224  This is the contents of buffer foo Line 225  This is the contents of buffer foo
225  @end example  @end example
226  @end defun  @end defun
227    
228    @tindex current-word
229    @defun current-word &optional strict really-word
230    This function returns the symbol (or word) at or near point, as a string.
231    The return value includes no text properties.
232    
233    The optional argument @var{really-word} is non-@code{nil}, it finds a
234    word; otherwise, it finds a symbol (which includes word characters and
235    both symbol constituent characters).
236    
237    If the optional argument @var{strict} is non-@code{nil}, then point
238    must be in or next to the symbol or word---if no symbol or word is
239    there, the function returns @code{nil}.  Otherwise, a nearby symbol or
240    word on the same line is acceptable.
241    @end defun
242    
243  @defun thing-at-point thing  @defun thing-at-point thing
244  Return the @var{thing} around or next to point, as a string.  Return the @var{thing} around or next to point, as a string.
245    
# Line 383  We hold these truth@point{} Line 399  We hold these truth@point{}
399  @end example  @end example
400  @end defun  @end defun
401    
402    @defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
403    This is like @code{insert-buffer-substring} except that it does not
404    copy any text properties.
405    @end defun
406    
407    @xref{Sticky Properties}, for other insertion functions that inherit    @xref{Sticky Properties}, for other insertion functions that inherit
408  text properties from the nearby text in addition to inserting it.  text properties from the nearby text in addition to inserting it.
409  Whitespace inserted by indentation functions also inherits text  Whitespace inserted by indentation functions also inherits text
# Line 746  would be difficult to change the termino Line 767  would be difficult to change the termino
767  @menu  @menu
768  * Kill Ring Concepts::     What text looks like in the kill ring.  * Kill Ring Concepts::     What text looks like in the kill ring.
769  * Kill Functions::         Functions that kill text.  * Kill Functions::         Functions that kill text.
770    * Yanking::                How yanking is done.
771  * Yank Commands::          Commands that access the kill ring.  * Yank Commands::          Commands that access the kill ring.
772  * Low-Level Kill Ring::    Functions and variables for kill ring access.  * Low-Level Kill Ring::    Functions and variables for kill ring access.
773  * Internals of Kill Ring:: Variables that hold kill-ring data.  * Internals of Kill Ring:: Variables that hold kill-ring data.
# Line 790  adds it to the most recent element.  It Line 812  adds it to the most recent element.  It
812  @code{last-command}) whether the previous command was a kill command,  @code{last-command}) whether the previous command was a kill command,
813  and if so appends the killed text to the most recent entry.  and if so appends the killed text to the most recent entry.
814    
815  @deffn Command kill-region start end  @deffn Command kill-region start end &optional yank-handler
816  This function kills the text in the region defined by @var{start} and  This function kills the text in the region defined by @var{start} and
817  @var{end}.  The text is deleted but saved in the kill ring, along with  @var{end}.  The text is deleted but saved in the kill ring, along with
818  its text properties.  The value is always @code{nil}.  its text properties.  The value is always @code{nil}.
# Line 803  If the buffer or text is read-only, @cod Line 825  If the buffer or text is read-only, @cod
825  ring just the same, then signals an error without modifying the buffer.  ring just the same, then signals an error without modifying the buffer.
826  This is convenient because it lets the user use a series of kill  This is convenient because it lets the user use a series of kill
827  commands to copy text from a read-only buffer into the kill ring.  commands to copy text from a read-only buffer into the kill ring.
828    
829    If @var{yank-handler} is non-@code{nil}, this puts that value onto
830    the string of killed text, as a @code{yank-handler} property.
831    @xref{Yanking}.
832  @end deffn  @end deffn
833    
834  @defopt kill-read-only-ok  @defopt kill-read-only-ok
# Line 827  support Emacs 18.  For newer Emacs versi Line 853  support Emacs 18.  For newer Emacs versi
853  Ring}.  Ring}.
854  @end deffn  @end deffn
855    
856    @node Yanking
857    @subsection Yanking
858    
859      Yanking means inserting text from the kill ring, but it does
860    not insert the text blindly.  Yank commands and some other commands
861    use @code{insert-for-yank} to perform special processing on the
862    text that they copy into the buffer.
863    
864    @defun insert-for-yank string
865    This function normally works like @code{insert} except that it doesn't
866    insert the text properties in the @code{yank-excluded-properties}
867    list.  However, if the first character of @var{string} has a
868    non-@code{nil}@code{yank-handler} text property, that property
869    can do various special processing on the text being inserted.
870    @end defun
871    
872    @defun insert-buffer-substring-as-yank buf &optional start end
873    This function resembles @code{insert-buffer-substring} except that it
874    doesn't insert the text properties in the
875    @code{yank-excluded-properties} list.
876    @end defun
877    
878      You can put a @code{yank-handler} text property on the text to
879    control how it will be inserted if it is yanked.  The
880    @code{insert-for-yank} function looks for a @code{yank-handler}
881    property on the first character in its @var{string} argument.  The
882    property value must be a list of one to four elements, with the
883    following format (where elements after the first may be omitted):
884    
885    @example
886    (@var{function} @var{param} @var{noexclude} @var{undo})
887    @end example
888    
889      Here is what the elements do:
890    
891    @table @var
892    @item function
893    When @var{function} is present and non-nil, it is called instead of
894    @code{insert} to insert the string.  @var{function} takes one
895    argument---the string to insert.
896    
897    @item param
898    If @var{param} is present and non-@code{nil}, it replaces @var{string}
899    as the object passed to @var{function} (or @code{insert}); for
900    example, if @var{function} is @code{yank-rectangle}, @var{param}
901    should be a list of strings to insert as a rectangle.
902    
903    @item noexclude
904    If @var{noexclude} is present and non-@code{nil}, the normal removal of the
905    yank-excluded-properties is not performed; instead @var{function} is
906    responsible for removing those properties.  This may be necessary
907    if @var{function} adjusts point before or after inserting the object.
908    
909    @item undo
910    If @var{undo} is present and non-nil, it is a function that will be
911    called by @code{yank-pop} to undo the insertion of the current object.
912    It is called with two arguments, the start and end of the current
913    region.  @var{function} can set @code{yank-undo-function} to override
914    the @var{undo} value.
915    @end table
916    
917  @node Yank Commands  @node Yank Commands
918  @comment  node-name,  next,  previous,  up  @comment  node-name,  next,  previous,  up
919  @subsection Functions for Yanking  @subsection Functions for Yanking
# Line 874  oldest. Line 961  oldest.
961  The return value is always @code{nil}.  The return value is always @code{nil}.
962  @end deffn  @end deffn
963    
964    @defvar yank-undo-function
965    If this variable is non-@code{nil}, the function @code{yank-pop} uses
966    its value instead of @code{delete-region} to delete the text
967    inserted by the previous @code{yank} or
968    @code{yank-pop} command.
969    
970    The function @code{insert-for-yank} automatically sets this variable
971    according to the @var{undo} element of the @code{yank-handler}
972    text property, if there is one.
973    @end defvar
974    
975  @node Low-Level Kill Ring  @node Low-Level Kill Ring
976  @subsection Low-Level Kill Ring  @subsection Low-Level Kill Ring
977    
# Line 897  If @var{n} is zero, indicating a request Line 995  If @var{n} is zero, indicating a request
995  the kill ring.  the kill ring.
996  @end defun  @end defun
997    
998  @defun kill-new string  @defun kill-new string &optional yank-handler
999  This function puts the text @var{string} into the kill ring as a new  This function puts the text @var{string} into the kill ring as a new
1000  entry at the front of the ring.  It discards the oldest entry if  entry at the front of the ring.  It discards the oldest entry if
1001  appropriate.  It also invokes the value of  appropriate.  It also invokes the value of
1002  @code{interprogram-cut-function} (see below).  @code{interprogram-cut-function} (see below).
1003    
1004    If @var{yank-handler} is non-@code{nil}, this puts that value onto
1005    the string of killed text, as a @code{yank-handler} property.
1006    @xref{Yanking}.
1007  @end defun  @end defun
1008    
1009  @defun kill-append string before-p  @defun kill-append string before-p &optional yank-handler
1010  This function appends the text @var{string} to the first entry in the  This function appends the text @var{string} to the first entry in the
1011  kill ring.  Normally @var{string} goes at the end of the entry, but if  kill ring.  Normally @var{string} goes at the end of the entry, but if
1012  @var{before-p} is non-@code{nil}, it goes at the beginning.  This  @var{before-p} is non-@code{nil}, it goes at the beginning.  This
1013  function also invokes the value of @code{interprogram-cut-function} (see  function also invokes the value of @code{interprogram-cut-function} (see
1014  below).  below).  This handles @var{yank-handler} just like @code{kill-new}.
1015  @end defun  @end defun
1016    
1017  @defvar interprogram-paste-function  @defvar interprogram-paste-function
# Line 2130  current line (which is the line in which Line 2232  current line (which is the line in which
2232  @code{nil}.  @code{nil}.
2233  @end deffn  @end deffn
2234    
2235  @deffn Command backward-to-indentation arg  @deffn Command backward-to-indentation &optional arg
2236  @comment !!SourceFile simple.el  @comment !!SourceFile simple.el
2237  This command moves point backward @var{arg} lines and then to the  This command moves point backward @var{arg} lines and then to the
2238  first nonblank character on that line.  It returns @code{nil}.  first nonblank character on that line.  It returns @code{nil}.
2239    If @var{arg} is omitted or @code{nil}, it defaults to 1.
2240  @end deffn  @end deffn
2241    
2242  @deffn Command forward-to-indentation arg  @deffn Command forward-to-indentation &optional arg
2243  @comment !!SourceFile simple.el  @comment !!SourceFile simple.el
2244  This command moves point forward @var{arg} lines and then to the first  This command moves point forward @var{arg} lines and then to the first
2245  nonblank character on that line.  It returns @code{nil}.  nonblank character on that line.  It returns @code{nil}.
2246    If @var{arg} is omitted or @code{nil}, it defaults to 1.
2247  @end deffn  @end deffn
2248    
2249  @node Case Changes  @node Case Changes
# Line 2322  overlays. Line 2426  overlays.
2426  This variable holds an alist which maps property names to a list of  This variable holds an alist which maps property names to a list of
2427  alternative property names.  If a character does not specify a direct  alternative property names.  If a character does not specify a direct
2428  value for a property, the alternative property names are consulted in  value for a property, the alternative property names are consulted in
2429  order; the first non-nil value is used.  This variable takes  order; the first non-@code{nil} value is used.  This variable takes
2430  precedence over @code{default-text-properties}, and @code{category}  precedence over @code{default-text-properties}, and @code{category}
2431  properties take precedence over this variable.  properties take precedence over this variable.
2432  @end defvar  @end defvar
# Line 2420  To remove all text properties from certa Line 2524  To remove all text properties from certa
2524  list.  list.
2525  @end defun  @end defun
2526    
2527    @defun remove-list-of-text-properties start end list-of-properties &optional object
2528    Like @code{remove-list-properties} except that
2529    @var{list-of-properties} is a list property names only, not an
2530    alternating list of property values.
2531    @end defun
2532    
2533  @defun set-text-properties start end props &optional object  @defun set-text-properties start end props &optional object
2534  This function completely replaces the text property list for the text  This function completely replaces the text property list for the text
2535  between @var{start} and @var{end} in the string or buffer @var{object}.  between @var{start} and @var{end} in the string or buffer @var{object}.
# Line 2747  This feature is used in the mode line an Line 2857  This feature is used in the mode line an
2857  @cindex keymap of character  @cindex keymap of character
2858  @kindex keymap @r{(text property)}  @kindex keymap @r{(text property)}
2859  The @code{keymap} property specifies an additional keymap for  The @code{keymap} property specifies an additional keymap for
2860  commands.  The property's value for the character after point, if  commands.  The property's value for the character before point applies
2861  non-@code{nil}, is used for key lookup before the buffer's local map.  if it is non-@code{nil} and rear-sticky, and the property's value for
2862  (For mouse clicks, the @code{keymap} property of the character clicked  the character after point applies if it is non-@code{nil} and
2863  on is the one used.)  If the property value is a symbol, the symbol's  front-sticky.  When the value applies, it is used for key lookup
2864  function definition is used as the keymap.  @xref{Active Keymaps}.  before the buffer's local map.  (For mouse clicks, the position of the
2865    click is used instead of the position of point.)  If the property
2866    value is a symbol, the symbol's function definition is used as the
2867    keymap.  @xref{Active Keymaps}.
2868    
2869  @item local-map  @item local-map
2870  @kindex local-map @r{(text property)}  @kindex local-map @r{(text property)}
2871  This property specifies a keymap to use @emph{instead of} the buffer's  This property works like @code{keymap} except that it specifies a
2872  local map.  If the property value is a symbol, the symbol's function  keymap to use @emph{instead of} the buffer's local map.  For most
2873  definition is used as the keymap.  For most purposes (perhaps all  purposes (perhaps all purposes), the @code{keymap} is superior.
 purposes), the @code{keymap} is superior.  
2874    
2875  @item syntax-table  @item syntax-table
2876  The @code{syntax-table} property overrides what the syntax table says  The @code{syntax-table} property overrides what the syntax table says
# Line 3296  name, then any field boundaries are igno Line 3408  name, then any field boundaries are igno
3408    
3409  You can cause @code{constrain-to-field} to ignore all field boundaries  You can cause @code{constrain-to-field} to ignore all field boundaries
3410  (and so never constrain anything) by binding the variable  (and so never constrain anything) by binding the variable
3411  @code{inhibit-field-text-motion} to a non-nil value.  @code{inhibit-field-text-motion} to a non-@code{nil} value.
3412  @end defun  @end defun
3413    
3414  @node Not Intervals  @node Not Intervals
# Line 3626  The decoding functions ignore newline ch Line 3738  The decoding functions ignore newline ch
3738  @defun base64-decode-string string  @defun base64-decode-string string
3739  @tindex base64-decode-string  @tindex base64-decode-string
3740  This function converts the string @var{string} from base 64 code into  This function converts the string @var{string} from base 64 code into
3741  the corresponding decoded text.  It returns a string containing the  the corresponding decoded text.  It returns a unibyte string containing the
3742  decoded text.  decoded text.
3743    
3744  The decoding functions ignore newline characters in the encoded text.  The decoding functions ignore newline characters in the encoded text.
# Line 3680  using the specified or chosen coding sys Line 3792  using the specified or chosen coding sys
3792  coding instead.  coding instead.
3793  @end defun  @end defun
3794    
3795    @node Atomic Changes
3796    @section Atomic Change Groups
3797    @cindex atomic changes
3798    
3799      In data base terminology, an @dfn{atomic} change is an indivisible
3800    change---it can succeed entirely or it can fail entirely, but it
3801    cannot partly succeed.  A Lisp program can make a series of changes to
3802    one or several buffers as an @dfn{atomic change group}, meaning that
3803    either the entire series of changes will be installed in their buffers
3804    or, in case of an error, none of them will be.
3805    
3806      To do this for one buffer, the one already current, simply write a
3807    call to @code{atomic-change-group} around the code that makes the
3808    changes, like this:
3809    
3810    @example
3811    (atomic-change-group
3812      (insert foo)
3813      (delete-region x y))
3814    @end example
3815    
3816    @noindent
3817    If an error (or other nonlocal exit) occurs inside the body of
3818    @code{atomic-change-group}, it unmakes all the changes in that buffer
3819    that were during the execution of the body.  This kind of change group
3820    has no effect on any other buffers--any such changes remain.
3821    
3822      If you need something more sophisticated, such as to make changes in
3823    various buffers constitute one atomic group, you must directly call
3824    lower-level functions that @code{atomic-change-group} uses.
3825    
3826    @defun prepare-change-group &optional buffer
3827    This function sets up a change group for buffer @var{buffer}, which
3828    defaults to the current buffer.  It returns a ``handle'' that
3829    represents the change group.  You must use this handle to activate the
3830    change group and subsequently to finish it.
3831    @end defun
3832    
3833      To use the change group, you must @dfn{activate} it.  You must do
3834    this before making any changes in the text of @var{buffer}.
3835    
3836    @defun activate-change-group handle
3837    This function activates the change group that @var{handle} designates.
3838    @end defun
3839    
3840      After you activate the change group, any changes you make in that
3841    buffer become part of it.  Once you have made all the desired changes
3842    in the buffer, you must @dfn{finish} the change group.  There are two
3843    ways to do this: you can either accept (and finalize) all the changes,
3844    or cancel them all.
3845    
3846    @defun accept-change-group handle
3847    This function accepts all the changes in the change group specified by
3848    @var{handle}, making them final.
3849    @end defun
3850    
3851    @defun cancel-change-group handle
3852    This function cancels and undoes all the changes in the change group
3853    specified by @var{handle}.
3854    @end defun
3855    
3856      Your code should use @code{unwind-protect} to make sure the group is
3857    always finished.  The call to @code{activate-change-group} should be
3858    inside the @code{unwind-protect}, in case the user types @kbd{C-g}
3859    just after it runs.  (This is one reason why
3860    @code{prepare-change-group} and @code{activate-change-group} are
3861    separate functions, because normally you would call
3862    @code{prepare-change-group} before the start of that
3863    @code{unwind-protect}.)  Once you finish the group, don't use the
3864    handle again---in particular, don't try to finish the same group
3865    twice.
3866    
3867      To make a multibuffer change group, call @code{prepare-change-group}
3868    once for each buffer you want to cover, then use @code{nconc} to
3869    combine the returned values, like this:
3870    
3871    @example
3872    (nconc (prepare-change-group buffer-1)
3873           (prepare-change-group buffer-2))
3874    @end example
3875    
3876    You can then activate the multibuffer change group with a single call
3877    to @code{activate-change-group}, and finish it with a single call to
3878    @code{accept-change-group} or @code{cancel-change-group}.
3879    
3880      Nested use of several change groups for the same buffer works as you
3881    would expect.  Non-nested use of change groups for the same buffer
3882    will get Emacs confused, so don't let it happen; the first change
3883    group you start for any given buffer should be the last one finished.
3884    
3885  @node Change Hooks  @node Change Hooks
3886  @section Change Hooks  @section Change Hooks
3887  @cindex change hooks  @cindex change hooks
# Line 3715  changed text, its length is simply the d Line 3917  changed text, its length is simply the d
3917  arguments.  arguments.
3918  @end defvar  @end defvar
3919    
3920      Output of messges into the @samp{*Messages*} buffer does not
3921    call these functions.
3922    
3923  @defmac combine-after-change-calls body...  @defmac combine-after-change-calls body...
3924  The macro executes @var{body} normally, but arranges to call the  The macro executes @var{body} normally, but arranges to call the
3925  after-change functions just once for a series of several changes---if  after-change functions just once for a series of several changes---if
# Line 3731  made within the @code{combine-after-chan Line 3936  made within the @code{combine-after-chan
3936  @code{after-change-functions} within  @code{after-change-functions} within
3937  the body of a @code{combine-after-change-calls} form.  the body of a @code{combine-after-change-calls} form.
3938    
3939  @strong{Note:} If the changes you combine occur in widely scattered  @strong{Warning:} if the changes you combine occur in widely scattered
3940  parts of the buffer, this will still work, but it is not advisable,  parts of the buffer, this will still work, but it is not advisable,
3941  because it may lead to inefficient behavior for some change hook  because it may lead to inefficient behavior for some change hook
3942  functions.  functions.
# Line 3781  properties (@pxref{Overlay Properties}). Line 3986  properties (@pxref{Overlay Properties}).
3986    
3987  This variable is available starting in Emacs 21.  This variable is available starting in Emacs 21.
3988  @end defvar  @end defvar
3989    
3990    @ignore
3991       arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b
3992    @end ignore

Legend:
Removed from v.1.56.2.1  
changed lines
  Added in v.1.56.2.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26