@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 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/text
@node Text, Non-ASCII Characters, Markers, Top
This chapter describes the functions that deal with the text in a
buffer. Most examine, insert, or delete text in the current buffer,
-often in the vicinity of point. Many are interactive. All the
-functions that change the text provide for undoing the changes
-(@pxref{Undo}).
+often operating at point or on text adjacent to point. Many are
+interactive. All the functions that change the text provide for undoing
+the changes (@pxref{Undo}).
Many text-related functions operate on a region of text defined by two
buffer positions passed in arguments named @var{start} and @var{end}.
@cindex buffer contents
Throughout this chapter, ``text'' refers to the characters in the
-buffer, together with their properties (when relevant).
+buffer, together with their properties (when relevant). Keep in mind
+that point is always between two characters, and the cursor appears on
+the character after point.
@menu
* Near Point:: Examining text in the vicinity of point.
* 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
@defun char-before &optional 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
+this purpose, either at or before the beginning of the buffer, or beyond
the end, then the value is @code{nil}. The default for
@var{position} is point.
@end defun
@end example
@end defun
+@tindex current-word
+@defun current-word &optional strict really-word
+This function returns the symbol (or word) at or near point, as a string.
+The return value includes no text properties.
+
+The optional argument @var{really-word} is non-@code{nil}, it finds a
+word; otherwise, it finds a symbol (which includes word characters and
+both symbol constituent characters).
+
+If the optional argument @var{strict} is non-@code{nil}, then point
+must be in or next to the symbol or word---if no symbol or word is
+there, the function returns @code{nil}. Otherwise, a nearby symbol or
+word on the same line is acceptable.
+@end defun
+
@defun thing-at-point thing
Return the @var{thing} around or next to point, as a string.
at the second character.
@example
-(compare-buffer-substring nil 6 11 nil 16 21)
+(compare-buffer-substrings nil 6 11 nil 16 21)
@result{} 2
@end example
@end defun
type.
Insertion functions signal an error if the current buffer is
-read-only.
+read-only or if they insert within read-only text.
These functions copy text characters from strings and buffers along
with their properties. The inserted characters have exactly the same
the insertion point, the inserted text falls inside that overlay.
@end defun
-@defun insert-char character &optional count inherit
+@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} should be a
number (@code{nil} means 1), and @var{character} must be a character.
In an interactive call, @var{count} is the numeric prefix argument.
This command calls @code{auto-fill-function} whenever that is
-non-@code{nil} and the character inserted is a space or a newline
-(@pxref{Auto Filling}).
+non-@code{nil} and the character inserted is in the table
+@code{auto-fill-chars} (@pxref{Auto Filling}).
@c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
This command performs abbrev expansion if Abbrev mode is enabled and
This is also responsible for calling @code{blink-paren-function} when
the inserted character has close parenthesis syntax (@pxref{Blinking}).
+
+Do not try substituting your own definition of
+@code{self-insert-command} for the standard one. The editor command
+loop handles this function specially.
@end deffn
-@deffn Command newline &optional number-of-newlines
+@deffn Command newline &optional number-of-newlines
This command inserts newlines into the current buffer before point.
If @var{number-of-newlines} is supplied, that many newline characters
are inserted.
@deffn Command erase-buffer
This function deletes the entire text of the current buffer, leaving it
empty. If the buffer is read-only, it signals a @code{buffer-read-only}
-error. Otherwise, it deletes the text without asking for any
-confirmation. It returns @code{nil}.
+error; if some of the text in it is read-only, it signals a
+@code{text-read-only} error. Otherwise, it deletes the text without
+asking for any confirmation. It returns @code{nil}.
Normally, deleting a large amount of text from a buffer inhibits further
auto-saving of that buffer ``because it has shrunk''. However,
@end deffn
@deffn Command delete-region start end
-This command deletes the text in the current buffer in the region
-defined by @var{start} and @var{end}. The value is @code{nil}. If
-point was inside the deleted region, its value afterward is @var{start}.
+This command deletes the text between positions @var{start} and
+@var{end} in the current buffer, and returns @code{nil}. If point was
+inside the deleted region, its value afterward is @var{start}.
Otherwise, point relocates with the surrounding text, as markers do.
@end deffn
+@defun delete-and-extract-region start end
+@tindex delete-and-extract-region
+This function deletes the text between positions @var{start} and
+@var{end} in the current buffer, and returns a string containing the
+text just deleted.
+
+If point was inside the deleted region, its value afterward is
+@var{start}. Otherwise, point relocates with the surrounding text, as
+markers do.
+@end defun
+
@deffn Command delete-char count &optional killp
This command deletes @var{count} characters directly after point, or
before point if @var{count} is negative. If @var{killp} is
@end deffn
@defopt backward-delete-char-untabify-method
-@tindex 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;
@end example
@end deffn
-@deffn Command delete-indentation &optional join-following-p
+@deffn Command delete-indentation &optional join-following-p
This function joins the line point is on to the previous line, deleting
any whitespace at the join and in some cases replacing it with one
space. If @var{join-following-p} is non-@code{nil},
the mark.
@c Emacs 19 feature
-If the buffer 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 all the kill commands to copy
-text into the kill ring from a read-only buffer.
+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 get an
-error if the buffer is read-only. Instead, it simply returns, updating
-the kill ring but not changing the buffer.
+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,
+updating the kill ring but not changing the buffer.
@end defopt
@deffn Command copy-region-as-kill start end
The variable @code{kill-ring} holds the kill ring contents, in the
form of a list of strings. The most recent kill is always at the front
-of the list.
+of the list.
The @code{kill-ring-yank-pointer} variable points to a link in the
kill ring list, whose @sc{car} is the text to yank next. We say it
Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
pointing to the second entry in the kill ring @code{("some text" "a
-different piece of text" "yet older text")}.
+different piece of text" "yet older text")}.
@example
@group
| --- --- --- --- --- ---
--> | | |------> | | |--> | | |--> nil
--- --- --- --- --- ---
- | | |
- | | |
- | | -->"yet older text"
+ | | |
+ | | |
+ | | -->"yet older text"
| |
- | --> "a different piece of text"
+ | --> "a different piece of text"
|
--> "some text"
@end group
@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
+Upon insertion, the text occupied the range @var{beg}--@var{end} in the
buffer.
@item (@var{text} . @var{position})
This command fills the paragraph at or after point. If
@var{justify} is non-@code{nil}, each line is justified as well.
It uses the ordinary paragraph motion commands to find paragraph
-boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}.
+boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}.
@end deffn
-@deffn Command fill-region start end &optional justify nosqueeze
+@deffn Command fill-region start end &optional justify nosqueeze to-eop
This command fills each of the paragraphs in the region from @var{start}
to @var{end}. It justifies as well if @var{justify} is
non-@code{nil}.
paragraphs. @xref{Standard Regexps}.
@end deffn
-@deffn Command fill-individual-paragraphs start end &optional justify mail-flag
+@deffn Command fill-individual-paragraphs start end &optional justify citation-regexp
This command fills each paragraph in the region according to its
individual fill prefix. Thus, if the lines of a paragraph were indented
with spaces, the filled paragraph will remain indented in the same
The first two arguments, @var{start} and @var{end}, are the beginning
and end of the region to be filled. The third and fourth arguments,
-@var{justify} and @var{mail-flag}, are optional. If
+@var{justify} and @var{citation-regexp}, are optional. If
@var{justify} is non-@code{nil}, the paragraphs are justified as
-well as filled. If @var{mail-flag} is non-@code{nil}, it means the
+well as filled. If @var{citation-regexp} is non-@code{nil}, it means the
function is operating on a mail message and therefore should not fill
-the header lines.
+the header lines. If @var{citation-regexp} is a string, it is used as
+a regular expression; if it matches the beginning of a line, that line
+is treated as a citation marker.
Ordinarily, @code{fill-individual-paragraphs} regards each change in
indentation as starting a new paragraph. If
choose a fill prefix by default. @xref{Adaptive Fill}.
@end deffn
-@deffn Command justify-current-line how eop nosqueeze
+@deffn Command justify-current-line &optional how eop nosqueeze
This command inserts spaces between the words of the current line so
that the line ends exactly at @code{fill-column}. It returns
@code{nil}.
indentation if that doesn't match the left margin value.
@end deffn
-@defun delete-to-left-margin from to
-This function removes left margin indentation from the text
-between @var{from} and @var{to}. The amount of indentation
-to delete is determined by calling @code{current-left-margin}.
-In no case does this function delete non-whitespace.
+@defun delete-to-left-margin &optional from to
+This function removes left margin indentation from the text between
+@var{from} and @var{to}. The amount of indentation to delete is
+determined by calling @code{current-left-margin}. In no case does this
+function delete non-whitespace. If @var{from} and @var{to} are omitted,
+they default to the whole buffer.
@end defun
@defun indent-to-left-margin
@end defvar
@defvar fill-nobreak-predicate
-@tindex 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
fill prefix based on the text between @var{from} and @var{to}. It does
this by looking at the first two lines of the paragraph, based on the
variables described below.
+@c The optional argument first-line-regexp is not documented
+@c because it exists for internal purposes and might be eliminated
+@c in the future.
@end defun
@defopt adaptive-fill-regexp
@defvar auto-fill-function
The value of this variable should be a function (of no arguments) to be
-called after self-inserting a space or a newline. It may be @code{nil},
-in which case nothing special is done in that case.
+called after self-inserting a character from the table
+@code{auto-fill-chars}. It may be @code{nil}, in which case nothing
+special is done in that case.
The value of @code{auto-fill-function} is @code{do-auto-fill} when
Auto-Fill mode is enabled. That is a function whose sole purpose is to
Fill works.
@end defvar
+@defvar auto-fill-chars
+A char table of characters which invoke @code{auto-fill-function} when
+self-inserted---space and newline in most language environments. They
+have an entry @code{t} in the table.
+@end defvar
+
@node Sorting
@section Sorting Text
@cindex sorting text
@var{force}, since there is no way to split them.
The argument @var{force} also has an effect if the line isn't long
-enough to reach column @var{column}; in that case, it says to add
-whitespace at the end of the line to reach that column.
+enough to reach column @var{column}; if it is @code{t}, that means to
+add whitespace at the end of the line to reach that column.
If @var{column} is not an integer, an error is signaled.
These commands, primarily for interactive use, act based on the
indentation in the text.
-@deffn Command back-to-indentation
+@deffn Command back-to-indentation
@comment !!SourceFile simple.el
This command moves point to the first non-whitespace character in the
current line (which is the line in which point is located). It returns
@code{substring}, @code{insert}, and @code{buffer-substring}.
@menu
-* Examining Properties:: Looking at the properties of one character.
-* Changing Properties:: Setting the properties of a range of text.
-* Property Search:: Searching for where a property changes value.
-* Special Properties:: Particular properties with special meanings.
-* Format Properties:: Properties for representing formatting of text.
-* Sticky Properties:: How inserted text gets properties from
- 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.
+* Examining Properties:: Looking at the properties of one character.
+* Changing Properties:: Setting the properties of a range of text.
+* Property Search:: Searching for where a property changes value.
+* Special Properties:: Particular properties with special meanings.
+* Format Properties:: Properties for representing formatting of text.
+* Sticky Properties:: How inserted text gets properties from
+ 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.
+* Fields:: The @code{field} property defines
+ fields within the buffer.
+* Not Intervals:: Why text properties do not use
+ Lisp-visible text intervals.
@end menu
@node Examining Properties
overlays.
@end defun
+@defvar char-property-alias-alist
+This variable holds an alist which maps property names to a list of
+alternative property names. If a character does not specify a direct
+value for a property, the alternative property names are consulted in
+order; the first non-@code{nil} value is used. This variable takes
+precedence over @code{default-text-properties}, and @code{category}
+properties take precedence over this variable.
+@end defvar
+
@defun text-properties-at position &optional object
This function returns the entire property list of the character at
@var{position} in the string or buffer @var{object}. If @var{object} is
@defvar default-text-properties
This variable holds a property list giving default values for text
properties. Whenever a character does not specify a value for a
-property, neither directly nor through a category symbol, the value
-stored in this list is used instead. Here is an example:
+property, neither directly, through a category symbol, or through
+@code{char-property-alias-alist}, the value stored in this list is
+used instead. Here is an example:
@example
-(setq default-text-properties '(foo 69))
+(setq default-text-properties '(foo 69)
+ char-property-alias-alist nil)
;; @r{Make sure character 1 has no properties of its own.}
(set-text-properties 1 2 nil)
;; @r{What we get, when we ask, is the default value.}
properties specified by name.
Since text properties are considered part of the contents of the
-buffer (or string), and can affect how a buffer looks on the screen, any
-change in buffer text properties mark the buffer as modified. Buffer
-text property changes are undoable also (@pxref{Undo}).
+buffer (or string), and can affect how a buffer looks on the screen,
+any change in buffer text properties marks the buffer as modified.
+Buffer text property changes are undoable also (@pxref{Undo}).
+Positions in a string start from 0, whereas positions in a buffer
+start from 1.
@defun put-text-property start end prop value &optional object
This function sets the @var{prop} property to @var{value} for the text
@example
(set-text-properties @var{start} @var{end} nil)
@end example
+@end defun
+
+ The easiest way to make a string with text properties
+is with @code{propertize}:
+
+@defun propertize string &rest properties
+@tindex propertize
+This function returns a copy of @var{string} which has the text
+properties @var{properties}. These properties apply to all the
+characters in the string that is returned. Here is an example that
+constructs a string with a @code{face} property and a @code{mouse-face}
+property:
+
+@smallexample
+(propertize "foo" 'face 'italic
+ 'mouse-face 'bold-italic)
+ @result{} #("foo" 0 3 (mouse-face bold-italic face italic))
+@end smallexample
+
+To put different properties on various parts of a string, you can
+construct each part with @code{propertize} and then combine them with
+@code{concat}:
+
+@smallexample
+(concat
+ (propertize "foo" 'face 'italic
+ 'mouse-face 'bold-italic)
+ " and "
+ (propertize "bar" 'face 'italic
+ 'mouse-face 'bold-italic))
+ @result{} #("foo and bar"
+ 0 3 (face italic mouse-face bold-italic)
+ 3 8 nil
+ 8 11 (face italic mouse-face bold-italic))
+@end smallexample
@end defun
See also the function @code{buffer-substring-no-properties}
@var{pos}.
If @var{limit} is non-@code{nil}, then the scan ends at position
-@var{limit}. If there is no property change before that point,
+@var{limit}. If there is no property change before that point,
@code{next-property-change} returns @var{limit}.
The value is @code{nil} if the properties remain unchanged all the way
@var{pos}.
If @var{limit} is non-@code{nil}, then the scan ends at position
-@var{limit}. If there is no property change before that point,
+@var{limit}. If there is no property change before that point,
@code{next-single-property-change} returns @var{limit}.
The value is @code{nil} if the property remains unchanged all the way to
@var{limit} equals @var{pos}.
@end defun
-@defun next-char-property-change position &optional limit
-@tindex next-char-property-change
+@defun next-char-property-change pos &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.
+overlay properties as well as text properties, and if no change is
+found before the end of the buffer, it returns the maximum buffer
+position rather than @code{nil} (in this sense, it resembles the
+corresponding overlay function @code{next-overlay-change}, rather than
+@code{next-property-change}). 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
-@defun previous-char-property-change position &optional limit
-@tindex previous-char-property-change
+@defun previous-char-property-change pos &optional limit
This is like @code{next-char-property-change}, but scans back from
-@var{position} instead of forward.
+@var{pos} instead of forward, and returns the minimum buffer
+position if no change is found.
+@end defun
+
+@defun next-single-char-property-change pos prop &optional object limit
+@tindex next-single-char-property-change
+This is like @code{next-single-property-change} except that it
+considers overlay properties as well as text properties, and if no
+change is found before the end of the @var{object}, it returns the
+maximum valid position in @var{object} rather than @code{nil}. Unlike
+@code{next-char-property-change}, this function @emph{does} have an
+@var{object} operand; if @var{object} is not a buffer, only
+text-properties are considered.
+@end defun
+
+@defun previous-single-char-property-change pos prop &optional object limit
+@tindex previous-single-char-property-change
+This is like @code{next-single-char-property-change}, but scans back
+from @var{pos} instead of forward, and returns the minimum valid
+position in @var{object} if no change is found.
@end defun
@defun text-property-any start end prop value &optional object
@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.
+text. @xref{Faces}, for more information.
+
+In the simplest case, the value is a face name. It can also be a list;
+then each element can be any of these possibilities;
+
+@itemize @bullet
+@item
+A face name (a symbol or string).
+
+@item
+Starting in Emacs 21, a property list of face attributes. This has the
+form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
+face attribute name and @var{value} is a meaningful value for that
+attribute. With this feature, you do not need to create a face each
+time you want to specify a particular attribute for certain text.
+@xref{Face Attributes}.
+
+@item
+A cons cell of 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.
+
+@code{(foreground-color . @var{color-name})} is equivalent to
+@code{(:foreground @var{color-name})}, and likewise for the background.
+@end itemize
-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.
+You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically
+update @code{face} properties based on the contents of the text.
-@xref{Font Lock Mode}, for information on how to update @code{face}
-properties automatically based on the contents of the text.
+@item font-lock-face
+@kindex font-lock-face @r{(text property)}
+The @code{font-lock-face} property is the same in all respects as the
+@code{face} property, but its state of activation is controlled by
+@code{font-lock-mode}. This can be advantageous for special buffers
+which are not intended to be user-editable, or for static areas of
+text which are always fontified in the same way.
+@xref{Precalculated Fontification}.
+
+Strictly speaking, @code{font-lock-face} is not a built-in text
+property; rather, it is implemented in Font Lock mode using
+@code{char-property-alias-alist}. @xref{Examining Properties}.
+
+This property is new in Emacs 21.4.
@item mouse-face
@kindex mouse-face @r{(text property)}
that all text between the character and where the mouse is have the same
@code{mouse-face} property value.
-@item local-map
+@item fontified
+@kindex fontified @r{(text property)}
+This property, if non-@code{nil}, says that text in the buffer has
+had faces assigned automatically by a feature such as Font-Lock mode.
+@xref{Auto Faces}.
+
+@item display
+@kindex display @r{(text property)}
+This property activates various features that change the
+way text is displayed. For example, it can make text appear taller
+or shorter, higher or lower, wider or narrow, or replaced with an image.
+@xref{Display Property}.
+
+@item help-echo
+@kindex help-echo @r{(text property)}
+@cindex tooltip
+@anchor{Text help-echo}
+If text has a string as its @code{help-echo} property, then when you
+move the mouse onto that text, Emacs displays that string in the echo
+area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs
+Manual}).
+
+If the value of the @code{help-echo} property is a function, that
+function is called with three arguments, @var{window}, @var{object} and
+@var{position} and should return a help string or @var{nil} for
+none. The first argument, @var{window} is the window in which
+the help was found. The second, @var{object}, is the buffer, overlay or
+string which had the @code{help-echo} property. The @var{position}
+argument is as follows:
+
+@itemize @bullet{}
+@item
+If @var{object} is a buffer, @var{pos} is the position in the buffer
+where the @code{help-echo} text property was found.
+@item
+If @var{object} is an overlay, that overlay has a @code{help-echo}
+property, and @var{pos} is the position in the overlay's buffer under
+the mouse.
+@item
+If @var{object} is a string (an overlay string or a string displayed
+with the @code{display} property), @var{pos} is the position in that
+string under the mouse.
+@end itemize
+
+If the value of the @code{help-echo} property is neither a function nor
+a string, it is evaluated to obtain a help string.
+
+You can alter the way help text is displayed by setting the variable
+@code{show-help-function} (@pxref{Help display}).
+
+This feature is used in the mode line and for other active text.
+
+@item keymap
@cindex keymap of character
+@kindex keymap @r{(text property)}
+The @code{keymap} property specifies an additional keymap for
+commands. The property's value for the character before point applies
+if it is non-@code{nil} and rear-sticky, and the property's value for
+the character after point applies if it is non-@code{nil} and
+front-sticky. When the value applies, it is used for key lookup
+before the buffer's local map. (For mouse clicks, the position of the
+click is used instead of the position of point.) If the property
+value is a symbol, the symbol's function definition is used as the
+keymap. @xref{Active Keymaps}.
+
+@item local-map
@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}.
+This property works like @code{keymap} except that it specifies a
+keymap to use @emph{instead of} the buffer's local map. For most
+purposes (perhaps all purposes), the @code{keymap} is superior.
@item syntax-table
The @code{syntax-table} property overrides what the syntax table says
@cindex read-only character
@kindex read-only @r{(text property)}
If a character has the property @code{read-only}, then modifying that
-character is not allowed. Any command that would do so gets an error.
+character is not allowed. Any command that would do so gets an error,
+@code{text-read-only}.
Insertion next to a read-only character is an error if inserting
ordinary text there would inherit the @code{read-only} property due to
When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
the @code{intangible} property is ignored.
+@item field
+@kindex field @r{(text property)}
+Consecutive characters with the same @code{field} property constitute a
+@dfn{field}. Some motion functions including @code{forward-word} and
+@code{beginning-of-line} stop moving at a field boundary.
+@xref{Fields}.
+
@item modification-hooks
@cindex change hooks for a character
@cindex hooks for changing a character
@code{let}.
@end defvar
+@defvar show-help-function
+@tindex show-help-function
+@anchor{Help display} If this variable is non-@code{nil}, it specifies a
+function called to display help strings. These may be @code{help-echo}
+properties, menu help strings (@pxref{Simple Menu Items},
+@pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
+Bar}). The specified function is called with one argument, the help
+string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs
+Manual}) provides an example.
+@end defvar
+
@node Format Properties
@subsection Formatted Text Properties
using these primitives.
When you do insertion with inheritance, @emph{which} properties are
-inherited depends on two specific properties: @code{front-sticky} and
-@code{rear-nonsticky}.
-
- Insertion after a character inherits those of its properties that are
+inherited, and from where, depends on which properties are @dfn{sticky}.
+Insertion after a character inherits those of its properties that are
@dfn{rear-sticky}. Insertion before a character inherits those of its
-properties that are @dfn{front-sticky}. By default, a text property is
-rear-sticky but not front-sticky. Thus, the default is to inherit all
-the properties of the preceding character, and nothing from the
-following character. You can request different behavior by specifying
-the stickiness of certain properties.
+properties that are @dfn{front-sticky}. When both sides offer different
+sticky values for the same property, the previous character's value
+takes precedence.
+
+ By default, a text property is rear-sticky but not front-sticky; thus,
+the default is to inherit all the properties of the preceding character,
+and nothing from the following character.
+
+ You can control the stickiness of various text properties with two
+specific text properties, @code{front-sticky} and @code{rear-nonsticky},
+and with the variable @code{text-property-default-nonsticky}. You can
+use the variable to specify a different default for a given property.
+You can use those two text properties to make any specific properties
+sticky or nonsticky in any particular part of the text.
If a character's @code{front-sticky} property is @code{t}, then all
its properties are front-sticky. If the @code{front-sticky} property is
then insertion before the character can inherit its @code{face} property
and its @code{read-only} property, but no others.
- The @code{rear-nonsticky} works the opposite way. Every property is
-rear-sticky by default, so the @code{rear-nonsticky} property says which
-properties are @emph{not} rear-sticky. If a character's
-@code{rear-nonsticky} property is @code{t}, then none of its properties
-are rear-sticky. If the @code{rear-nonsticky} property is a list,
-properties are rear-sticky @emph{unless} their names are in the list.
+ The @code{rear-nonsticky} property works the opposite way. Most
+properties are rear-sticky by default, so the @code{rear-nonsticky}
+property says which properties are @emph{not} rear-sticky. If a
+character's @code{rear-nonsticky} property is @code{t}, then none of its
+properties are rear-sticky. If the @code{rear-nonsticky} property is a
+list, properties are rear-sticky @emph{unless} their names are in the
+list.
- When you insert text with inheritance, it inherits all the rear-sticky
-properties of the preceding character, and all the front-sticky
-properties of the following character. The previous character's
-properties take precedence when both sides offer different sticky values
-for the same property.
+@defvar text-property-default-nonsticky
+@tindex text-property-default-nonsticky
+This variable holds an alist which defines the default rear-stickiness
+of various text properties. Each element has the form
+@code{(@var{property} . @var{nonstickiness})}, and it defines the
+stickiness of a particular text property, @var{property}.
+
+If @var{nonstickiness} is non-@code{nil}, this means that the property
+@var{property} is rear-nonsticky by default. Since all properties are
+front-nonsticky by default, this makes @var{property} nonsticky in both
+directions by default.
+
+The text properties @code{front-sticky} and @code{rear-nonsticky}, when
+used, take precedence over the default @var{nonstickiness} specified in
+@code{text-property-default-nonsticky}.
+@end defvar
Here are the functions that insert text with inheritance of properties:
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
+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
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}
+a key binding for the clickable text itself, using the @code{keymap}
text property:
@example
(let ((map (make-sparse-keymap)))
- (define-key-binding map [mouse-2] 'operate-this-button)
+ (define-key map [mouse-2] 'operate-this-button)
(put-text-property (point)
(save-excursion
(dired-move-to-end-of-filename)
(point))
- 'local-map map))
+ 'keymap map))
@end example
@noindent
global definition) remains available for the rest of the text in the
buffer.
+@node Fields
+@subsection Defining and Using Fields
+@cindex fields
+
+ A field is a range of consecutive characters in the buffer that are
+identified by having the same value (comparing with @code{eq}) of the
+@code{field} property (either a text-property or an overlay property).
+This section describes special functions that are available for
+operating on fields.
+
+ You specify a field with a buffer position, @var{pos}. We think of
+each field as containing a range of buffer positions, so the position
+you specify stands for the field containing that position.
+
+ When the characters before and after @var{pos} are part of the same
+field, there is no doubt which field contains @var{pos}: the one those
+characters both belong to. When @var{pos} is at a boundary between
+fields, which field it belongs to depends on the stickiness of the
+@code{field} properties of the two surrounding characters (@pxref{Sticky
+Properties}). The field whose property would be inherited by text
+inserted at @var{pos} is the field that contains @var{pos}.
+
+ There is an anomalous case where newly inserted text at @var{pos}
+would not inherit the @code{field} property from either side. This
+happens if the previous character's @code{field} property is not
+rear-sticky, and the following character's @code{field} property is not
+front-sticky. In this case, @var{pos} belongs to neither the preceding
+field nor the following field; the field functions treat it as belonging
+to an empty field whose beginning and end are both at @var{pos}.
+
+ In all of these functions, if @var{pos} is omitted or @code{nil}, the
+value of point is used by default.
+
+@defun field-beginning &optional pos escape-from-edge limit
+@tindex field-beginning
+This function returns the beginning of the field specified by @var{pos}.
+
+If @var{pos} is at the beginning of its field, and
+@var{escape-from-edge} is non-@code{nil}, then the return value is
+always the beginning of the preceding field that @emph{ends} at @var{pos},
+regardless of the stickiness of the @code{field} properties around
+@var{pos}.
+
+If @var{limit} is non-@code{nil}, it is a buffer position; if the
+beginning of the field is before @var{limit}, then @var{limit} will be
+returned instead.
+@end defun
+
+@defun field-end &optional pos escape-from-edge limit
+@tindex field-end
+This function returns the end of the field specified by @var{pos}.
+
+If @var{pos} is at the end of its field, and @var{escape-from-edge} is
+non-@code{nil}, then the return value is always the end of the following
+field that @emph{begins} at @var{pos}, regardless of the stickiness of
+the @code{field} properties around @var{pos}.
+
+If @var{limit} is non-@code{nil}, it is a buffer position; if the end
+of the field is after @var{limit}, then @var{limit} will be returned
+instead.
+@end defun
+
+@defun field-string &optional pos
+@tindex field-string
+This function returns the contents of the field specified by @var{pos},
+as a string.
+@end defun
+
+@defun field-string-no-properties &optional pos
+@tindex field-string-no-properties
+This function returns the contents of the field specified by @var{pos},
+as a string, discarding text properties.
+@end defun
+
+@defun delete-field &optional pos
+@tindex delete-field
+This function deletes the text of the field specified by @var{pos}.
+@end defun
+
+@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
+@tindex constrain-to-field
+This function ``constrains'' @var{new-pos} to the field that
+@var{old-pos} belongs to---in other words, it returns the position
+closest to @var{new-pos} that is in the same field as @var{old-pos}.
+
+If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
+the value of point instead, and moves point to the resulting position.
+
+If @var{old-pos} is at the boundary of two fields, then the acceptable
+positions for @var{new-pos} depend on the value of the optional argument
+@var{escape-from-edge}. If @var{escape-from-edge} is @code{nil}, then
+@var{new-pos} is constrained to the field that has the same @code{field}
+property (either a text-property or an overlay property) that new
+characters inserted at @var{old-pos} would get. (This depends on the
+stickiness of the @code{field} property for the characters before and
+after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil},
+@var{new-pos} is constrained to the union of the two adjacent fields.
+Additionally, if two fields are separated by another field with the
+special value @code{boundary}, then any point within this special field
+is also considered to be ``on the boundary.''
+
+If the optional argument @var{only-in-line} is non-@code{nil}, and
+constraining @var{new-pos} in the usual way would move it to a different
+line, @var{new-pos} is returned unconstrained. This used in commands
+that move by line, such as @code{next-line} and
+@code{beginning-of-line}, so that they respect field boundaries only in
+the case where they can still move to the right line.
+
+If the optional argument @var{inhibit-capture-property} is
+non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that
+name, then any field boundaries are ignored.
+
+You can cause @code{constrain-to-field} to ignore all field boundaries
+(and so never constrain anything) by binding the variable
+@code{inhibit-field-text-motion} to a non-@code{nil} value.
+@end defun
+
@node Not Intervals
@subsection Why Text Properties are not Intervals
@cindex intervals
with the character @var{new-char} in the region of the current buffer
defined by @var{start} and @var{end}.
-@cindex Outline mode
@cindex undo avoidance
If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
not record the change for undo and does not mark the buffer as modified.
-This feature is used for controlling selective display (@pxref{Selective
-Display}).
+This was useful for controlling the old selective display feature
+(@pxref{Selective Display}).
@code{subst-char-in-region} does not move point and returns
@code{nil}.
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.
+single character. All @sc{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} .
all markers unrelocated.
@end defun
+@node Base 64
+@section Base 64 Encoding
+@cindex base 64 encoding
+
+ Base 64 code is used in email to encode a sequence of 8-bit bytes as
+a longer sequence of @sc{ascii} graphic characters. It is defined in
+Internet RFC@footnote{
+An RFC, an acronym for @dfn{Request for Comments}, is a numbered
+Internet informational document describing a standard. RFCs are
+usually written by technical experts acting on their own initiative,
+and are traditionally written in a pragmatic, experience-driven
+manner.
+}2045. This section describes the functions for
+converting to and from this code.
+
+@defun base64-encode-region beg end &optional no-line-break
+@tindex base64-encode-region
+This function converts the region from @var{beg} to @var{end} into base
+64 code. It returns the length of the encoded text. An error is
+signaled if a character in the region is multibyte, i.e.@: in a
+multibyte buffer the region must contain only characters from the
+charsets @code{ascii}, @code{eight-bit-control} and
+@code{eight-bit-graphic}.
+
+Normally, this function inserts newline characters into the encoded
+text, to avoid overlong lines. However, if the optional argument
+@var{no-line-break} is non-@code{nil}, these newlines are not added, so
+the output is just one long line.
+@end defun
+
+@defun base64-encode-string string &optional no-line-break
+@tindex base64-encode-string
+This function converts the string @var{string} into base 64 code. It
+returns a string containing the encoded text. As for
+@code{base64-encode-region}, an error is signaled if a character in the
+string is multibyte.
+
+Normally, this function inserts newline characters into the encoded
+text, to avoid overlong lines. However, if the optional argument
+@var{no-line-break} is non-@code{nil}, these newlines are not added, so
+the result string is just one long line.
+@end defun
+
+@defun base64-decode-region beg end
+@tindex base64-decode-region
+This function converts the region from @var{beg} to @var{end} from base
+64 code into the corresponding decoded text. It returns the length of
+the decoded text.
+
+The decoding functions ignore newline characters in the encoded text.
+@end defun
+
+@defun base64-decode-string string
+@tindex base64-decode-string
+This function converts the string @var{string} from base 64 code into
+the corresponding decoded text. It returns a unibyte string containing the
+decoded text.
+
+The decoding functions ignore newline characters in the encoded text.
+@end defun
+
+@node MD5 Checksum
+@section MD5 Checksum
+@cindex MD5 checksum
+@cindex message digest computation
+
+ MD5 cryptographic checksums, or @dfn{message digests}, are 128-bit
+``fingerprints'' of a document or program. They are used to verify
+that you have an exact and unaltered copy of the data. The algorithm
+to calculate the MD5 message digest is defined in Internet
+RFC@footnote{
+For an explanation of what is an RFC, see the footnote in @ref{Base
+64}.
+}1321. This section describes the Emacs facilities for computing
+message digests.
+
+@defun md5 object &optional start end coding-system noerror
+This function returns the MD5 message digest of @var{object}, which
+should be a buffer or a string.
+
+The two optional arguments @var{start} and @var{end} are character
+positions specifying the portion of @var{object} to compute the
+message digest for. If they are @code{nil} or omitted, the digest is
+computed for the whole of @var{object}.
+
+The function @code{md5} does not compute the message digest directly
+from the internal Emacs representation of the text (@pxref{Text
+Representations}). Instead, it encodes the text using a coding
+system, and computes the message digest from the encoded text. The
+optional fourth argument @var{coding-system} specifies which coding
+system to use for encoding the text. It should be the same coding
+system that you used to read the text, or that you used or will use
+when saving or sending the text. @xref{Coding Systems}, for more
+information about coding systems.
+
+If @var{coding-system} is @code{nil} or omitted, the default depends
+on @var{object}. If @var{object} is a buffer, the default for
+@var{coding-system} is whatever coding system would be chosen by
+default for writing this text into a file. If @var{object} is a
+string, the user's most preferred coding system (@pxref{Recognize
+Coding, prefer-coding-system, the description of
+@code{prefer-coding-system}, emacs, GNU Emacs Manual}) is used.
+
+Normally, @code{md5} signals an error if the text can't be encoded
+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
arguments.
@end defvar
+ Output of messges into the @samp{*Messages*} buffer does not
+call these functions.
+
@defmac combine-after-change-calls body...
-@tindex combine-after-change-calls
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.
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
+@code{after-change-functions} within
the body of a @code{combine-after-change-calls} form.
@strong{Note:} If the changes you combine occur in widely scattered
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
-the functions in @code{before-change-functions}.
-@end defvar
-
-@defvar after-change-function
-This obsolete variable holds one function to call after any buffer modification
-(or @code{nil} for no function). It is called just like the functions in
-@code{after-change-functions}.
-@end defvar
-
-The four variables above are temporarily bound to @code{nil} during the
+The two variables above are temporarily bound to @code{nil} during the
time that any of these functions is running. This means that if one of
these functions changes the buffer, that change won't run these
functions. If you do want a hook function to make changes that run
This variable is a normal hook that is run whenever a buffer is changed
that was previously in the unmodified state.
@end defvar
+
+@defvar inhibit-modification-hooks
+@tindex inhibit-modification-hooks
+If this variable is non-@code{nil}, all of the change hooks are
+disabled; none of them run. This affects all the hook variables
+described above in this section, as well as the hooks attached to
+certain special text properties (@pxref{Special Properties}) and overlay
+properties (@pxref{Overlay Properties}).
+
+This variable is available starting in Emacs 21.
+@end defvar