@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001
-@c Free Software Foundation, Inc.
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/text
@node Text, Non-ASCII Characters, Markers, Top
@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.
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.
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.
@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 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})
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
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 marks 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
@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
@code{(:foreground @var{color-name})}, and likewise for the background.
@end itemize
-@xref{Font Lock Mode}, for information on how to update @code{face}
-properties automatically based on the contents of the text.
+You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically
+update @code{face} properties 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)}
@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.
+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
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. It is
-available starting in Emacs 21.
+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 after point, if
-non-@code{nil}, is used for key lookup before the buffer's local map.
-(For mouse clicks, the @code{keymap} property of the character clicked
-on is the one used.) If the property value is a symbol, the symbol's
-function definition is used as the keymap. @xref{Active Keymaps}.
+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)}
-This property specifies a keymap to use @emph{instead of} the buffer's
-local map. If the property value is a symbol, the symbol's function
-definition is used as the keymap. For most purposes (perhaps all
-purposes), the @code{keymap} is superior.
+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
directions by default.
The text properties @code{front-sticky} and @code{rear-nonsticky}, when
-used, take precedence over the default @var{nonstickiness} specifed in
+used, take precedence over the default @var{nonstickiness} specified in
@code{text-property-default-nonsticky}.
@end defvar
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
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-nil value.
+@code{inhibit-field-text-motion} to a non-@code{nil} value.
@end defun
@node Not Intervals
@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 string containing the
+the corresponding decoded text. It returns a unibyte string containing the
decoded text.
The decoding functions ignore newline characters in the encoded text.
arguments.
@end defvar
+ Output of messges into the @samp{*Messages*} buffer does not
+call these functions.
+
@defmac combine-after-change-calls body...
The macro executes @var{body} normally, but arranges to call the
after-change functions just once for a series of several changes---if