-This is Info file ../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref/lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Internals of Kill Ring, Prev: Low-Level Kill Ring, Up: The Kill Ring
+
+Internals of the Kill Ring
+--------------------------
+
+ The variable `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.
+
+ The `kill-ring-yank-pointer' variable points to a link in the kill
+ring list, whose CAR is the text to yank next. We say it identifies
+the "front" of the ring. Moving `kill-ring-yank-pointer' to a
+different link is called "rotating the kill ring". We call the kill
+ring a "ring" because the functions that move the yank pointer wrap
+around from the end of the list to the beginning, or vice-versa.
+Rotation of the kill ring is virtual; it does not change the value of
+`kill-ring'.
+
+ Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
+whose values are normally lists. The word "pointer" in the name of the
+`kill-ring-yank-pointer' indicates that the variable's purpose is to
+identify one element of the list for use by the next yank command.
+
+ The value of `kill-ring-yank-pointer' is always `eq' to one of the
+links in the kill ring list. The element it identifies is the CAR of
+that link. Kill commands, which change the kill ring, also set this
+variable to the value of `kill-ring'. The effect is to rotate the ring
+so that the newly killed text is at the front.
+
+ Here is a diagram that shows the variable `kill-ring-yank-pointer'
+pointing to the second entry in the kill ring `("some text" "a
+different piece of text" "yet older text")'.
+
+ kill-ring kill-ring-yank-pointer
+ | |
+ | ___ ___ ---> ___ ___ ___ ___
+ --> |___|___|------> |___|___|--> |___|___|--> nil
+ | | |
+ | | |
+ | | -->"yet older text"
+ | |
+ | --> "a different piece of text"
+ |
+ --> "some text"
+
+This state of affairs might occur after `C-y' (`yank') immediately
+followed by `M-y' (`yank-pop').
+
+ - Variable: kill-ring
+ This variable holds the list of killed text sequences, most
+ recently killed first.
+
+ - Variable: kill-ring-yank-pointer
+ This variable's value indicates which element of the kill ring is
+ at the "front" of the ring for yanking. More precisely, the value
+ is a tail of the value of `kill-ring', and its CAR is the kill
+ string that `C-y' should yank.
+
+ - User Option: kill-ring-max
+ The value of this variable is the maximum length to which the kill
+ ring can grow, before elements are thrown away at the end. The
+ default value for `kill-ring-max' is 30.
+
+\1f
+File: lispref.info, Node: Undo, Next: Maintaining Undo, Prev: The Kill Ring, Up: Text
+
+Undo
+====
+
+ Most buffers have an "undo list", which records all changes made to
+the buffer's text so that they can be undone. (The buffers that don't
+have one are usually special-purpose buffers for which XEmacs assumes
+that undoing is not useful.) All the primitives that modify the text
+in the buffer automatically add elements to the front of the undo list,
+which is in the variable `buffer-undo-list'.
+
+ - Variable: buffer-undo-list
+ This variable's value is the undo list of the current buffer. A
+ value of `t' disables the recording of undo information.
+
+ Here are the kinds of elements an undo list can have:
+
+`INTEGER'
+ This kind of element records a previous value of point. Ordinary
+ cursor motion does not get any sort of undo record, but deletion
+ commands use these entries to record where point was before the
+ command.
+
+`(BEG . END)'
+ This kind of element indicates how to delete text that was
+ inserted. Upon insertion, the text occupied the range BEG-END in
+ the buffer.
+
+`(TEXT . POSITION)'
+ This kind of element indicates how to reinsert text that was
+ deleted. The deleted text itself is the string TEXT. The place to
+ reinsert it is `(abs POSITION)'.
+
+`(t HIGH . LOW)'
+ This kind of element indicates that an unmodified buffer became
+ modified. The elements HIGH and LOW are two integers, each
+ recording 16 bits of the visited file's modification time as of
+ when it was previously visited or saved. `primitive-undo' uses
+ those values to determine whether to mark the buffer as unmodified
+ once again; it does so only if the file's modification time
+ matches those numbers.
+
+`(nil PROPERTY VALUE BEG . END)'
+ This kind of element records a change in a text property. Here's
+ how you might undo the change:
+
+ (put-text-property BEG END PROPERTY VALUE)
+
+`POSITION'
+ This element indicates where point was at an earlier time.
+ Undoing this element sets point to POSITION. Deletion normally
+ creates an element of this kind as well as a reinsertion element.
+
+`nil'
+ This element is a boundary. The elements between two boundaries
+ are called a "change group"; normally, each change group
+ corresponds to one keyboard command, and undo commands normally
+ undo an entire group as a unit.
+
+ - Function: undo-boundary
+ This function places a boundary element in the undo list. The undo
+ command stops at such a boundary, and successive undo commands undo
+ to earlier and earlier boundaries. This function returns `nil'.
+
+ The editor command loop automatically creates an undo boundary
+ before each key sequence is executed. Thus, each undo normally
+ undoes the effects of one command. Self-inserting input
+ characters are an exception. The command loop makes a boundary
+ for the first such character; the next 19 consecutive
+ self-inserting input characters do not make boundaries, and then
+ the 20th does, and so on as long as self-inserting characters
+ continue.
+
+ All buffer modifications add a boundary whenever the previous
+ undoable change was made in some other buffer. This way, a
+ command that modifies several buffers makes a boundary in each
+ buffer it changes.
+
+ Calling this function explicitly is useful for splitting the
+ effects of a command into more than one unit. For example,
+ `query-replace' calls `undo-boundary' after each replacement, so
+ that the user can undo individual replacements one by one.
+
+ - Function: primitive-undo count list
+ This is the basic function for undoing elements of an undo list.
+ It undoes the first COUNT elements of LIST, returning the rest of
+ LIST. You could write this function in Lisp, but it is convenient
+ to have it in C.
+
+ `primitive-undo' adds elements to the buffer's undo list when it
+ changes the buffer. Undo commands avoid confusion by saving the
+ undo list value at the beginning of a sequence of undo operations.
+ Then the undo operations use and update the saved value. The new
+ elements added by undoing are not part of this saved value, so
+ they don't interfere with continuing to undo.
+
+\1f
+File: lispref.info, Node: Maintaining Undo, Next: Filling, Prev: Undo, Up: Text
+
+Maintaining Undo Lists
+======================
+
+ This section describes how to enable and disable undo information for
+a given buffer. It also explains how the undo list is truncated
+automatically so it doesn't get too big.
+
+ Recording of undo information in a newly created buffer is normally
+enabled to start with; but if the buffer name starts with a space, the
+undo recording is initially disabled. You can explicitly enable or
+disable undo recording with the following two functions, or by setting
+`buffer-undo-list' yourself.
+
+ - Command: buffer-enable-undo &optional buffer-or-name
+ This command enables recording undo information for buffer
+ BUFFER-OR-NAME, so that subsequent changes can be undone. If no
+ argument is supplied, then the current buffer is used. This
+ function does nothing if undo recording is already enabled in the
+ buffer. It returns `nil'.
+
+ In an interactive call, BUFFER-OR-NAME is the current buffer. You
+ cannot specify any other buffer.
+
+ - Function: buffer-disable-undo &optional buffer
+ - Function: buffer-flush-undo &optional buffer
+ This function discards the undo list of BUFFER, and disables
+ further recording of undo information. As a result, it is no
+ longer possible to undo either previous changes or any subsequent
+ changes. If the undo list of BUFFER is already disabled, this
+ function has no effect.
+
+ This function returns `nil'. It cannot be called interactively.
+
+ The name `buffer-flush-undo' is not considered obsolete, but the
+ preferred name `buffer-disable-undo' is new as of Emacs versions
+ 19.
+
+ As editing continues, undo lists get longer and longer. To prevent
+them from using up all available memory space, garbage collection trims
+them back to size limits you can set. (For this purpose, the "size" of
+an undo list measures the cons cells that make up the list, plus the
+strings of deleted text.) Two variables control the range of acceptable
+sizes: `undo-limit' and `undo-strong-limit'.
+
+ - Variable: undo-limit
+ This is the soft limit for the acceptable size of an undo list.
+ The change group at which this size is exceeded is the last one
+ kept.
+
+ - Variable: undo-strong-limit
+ This is the upper limit for the acceptable size of an undo list.
+ The change group at which this size is exceeded is discarded
+ itself (along with all older change groups). There is one
+ exception: the very latest change group is never discarded no
+ matter how big it is.
+
+\1f
+File: lispref.info, Node: Filling, Next: Margins, Prev: Maintaining Undo, Up: Text
+
+Filling
+=======
+
+ "Filling" means adjusting the lengths of lines (by moving the line
+breaks) so that they are nearly (but no greater than) a specified
+maximum width. Additionally, lines can be "justified", which means
+inserting spaces to make the left and/or right margins line up
+precisely. The width is controlled by the variable `fill-column'. For
+ease of reading, lines should be no longer than 70 or so columns.
+
+ You can use Auto Fill mode (*note Auto Filling::) to fill text
+automatically as you insert it, but changes to existing text may leave
+it improperly filled. Then you must fill the text explicitly.
+
+ Most of the commands in this section return values that are not
+meaningful. All the functions that do filling take note of the current
+left margin, current right margin, and current justification style
+(*note Margins::). If the current justification style is `none', the
+filling functions don't actually do anything.
+
+ Several of the filling functions have an argument JUSTIFY. If it is
+non-`nil', that requests some kind of justification. It can be `left',
+`right', `full', or `center', to request a specific style of
+justification. If it is `t', that means to use the current
+justification style for this part of the text (see
+`current-justification', below).
+
+ When you call the filling functions interactively, using a prefix
+argument implies the value `full' for JUSTIFY.
+
+ - Command: fill-paragraph justify
+ This command fills the paragraph at or after point. If JUSTIFY is
+ non-`nil', each line is justified as well. It uses the ordinary
+ paragraph motion commands to find paragraph boundaries. *Note
+ Paragraphs: (xemacs)Paragraphs.
+
+ - Command: fill-region start end &optional justify
+ This command fills each of the paragraphs in the region from START
+ to END. It justifies as well if JUSTIFY is non-`nil'.
+
+ The variable `paragraph-separate' controls how to distinguish
+ paragraphs. *Note Standard Regexps::.
+
+ - Command: fill-individual-paragraphs start end &optional justify
+ mail-flag
+ 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 fashion.
+
+ The first two arguments, START and END, are the beginning and end
+ of the region to be filled. The third and fourth arguments,
+ JUSTIFY and MAIL-FLAG, are optional. If JUSTIFY is non-`nil', the
+ paragraphs are justified as well as filled. If MAIL-FLAG is
+ non-`nil', it means the function is operating on a mail message
+ and therefore should not fill the header lines.
+
+ Ordinarily, `fill-individual-paragraphs' regards each change in
+ indentation as starting a new paragraph. If
+ `fill-individual-varying-indent' is non-`nil', then only separator
+ lines separate paragraphs. That mode can handle indented
+ paragraphs with additional indentation on the first line.
+
+ - User Option: fill-individual-varying-indent
+ This variable alters the action of `fill-individual-paragraphs' as
+ described above.
+
+ - Command: fill-region-as-paragraph start end &optional justify
+ This command considers a region of text as a paragraph and fills
+ it. If the region was made up of many paragraphs, the blank lines
+ between paragraphs are removed. This function justifies as well
+ as filling when JUSTIFY is non-`nil'.
+
+ In an interactive call, any prefix argument requests justification.
+
+ In Adaptive Fill mode, which is enabled by default,
+ `fill-region-as-paragraph' on an indented paragraph when there is
+ no fill prefix uses the indentation of the second line of the
+ paragraph as the fill prefix.
+
+ - Command: justify-current-line how eop nosqueeze
+ This command inserts spaces between the words of the current line
+ so that the line ends exactly at `fill-column'. It returns `nil'.
+
+ The argument HOW, if non-`nil' specifies explicitly the style of
+ justification. It can be `left', `right', `full', `center', or
+ `none'. If it is `t', that means to do follow specified
+ justification style (see `current-justification', below). `nil'
+ means to do full justification.
+
+ If EOP is non-`nil', that means do left-justification when
+ `current-justification' specifies full justification. This is used
+ for the last line of a paragraph; even if the paragraph as a whole
+ is fully justified, the last line should not be.
+
+ If NOSQUEEZE is non-`nil', that means do not change interior
+ whitespace.
+
+ - User Option: default-justification
+ This variable's value specifies the style of justification to use
+ for text that doesn't specify a style with a text property. The
+ possible values are `left', `right', `full', `center', or `none'.
+ The default value is `left'.
+
+ - Function: current-justification
+ This function returns the proper justification style to use for
+ filling the text around point.
+
+ - Variable: fill-paragraph-function
+ This variable provides a way for major modes to override the
+ filling of paragraphs. If the value is non-`nil',
+ `fill-paragraph' calls this function to do the work. If the
+ function returns a non-`nil' value, `fill-paragraph' assumes the
+ job is done, and immediately returns that value.
+
+ The usual use of this feature is to fill comments in programming
+ language modes. If the function needs to fill a paragraph in the
+ usual way, it can do so as follows:
+
+ (let ((fill-paragraph-function nil))
+ (fill-paragraph arg))
+
+ - Variable: use-hard-newlines
+ If this variable is non-`nil', the filling functions do not delete
+ newlines that have the `hard' text property. These "hard
+ newlines" act as paragraph separators.
+
+\1f
+File: lispref.info, Node: Margins, Next: Auto Filling, Prev: Filling, Up: Text
+
+Margins for Filling
+===================
+
+ - User Option: fill-prefix
+ This variable specifies a string of text that appears at the
+ beginning of normal text lines and should be disregarded when
+ filling them. Any line that fails to start with the fill prefix
+ is considered the start of a paragraph; so is any line that starts
+ with the fill prefix followed by additional whitespace. Lines
+ that start with the fill prefix but no additional whitespace are
+ ordinary text lines that can be filled together. The resulting
+ filled lines also start with the fill prefix.
+
+ The fill prefix follows the left margin whitespace, if any.
+
+ - User Option: fill-column
+ This buffer-local variable specifies the maximum width of filled
+ lines. Its value should be an integer, which is a number of
+ columns. All the filling, justification and centering commands
+ are affected by this variable, including Auto Fill mode (*note
+ Auto Filling::).
+
+ As a practical matter, if you are writing text for other people to
+ read, you should set `fill-column' to no more than 70. Otherwise
+ the line will be too long for people to read comfortably, and this
+ can make the text seem clumsy.
+
+ - Variable: default-fill-column
+ The value of this variable is the default value for `fill-column'
+ in buffers that do not override it. This is the same as
+ `(default-value 'fill-column)'.
+
+ The default value for `default-fill-column' is 70.
+
+ - Command: set-left-margin from to margin
+ This sets the `left-margin' property on the text from FROM to TO
+ to the value MARGIN. If Auto Fill mode is enabled, this command
+ also refills the region to fit the new margin.
+
+ - Command: set-right-margin from to margin
+ This sets the `right-margin' property on the text from FROM to TO
+ to the value MARGIN. If Auto Fill mode is enabled, this command
+ also refills the region to fit the new margin.
+
+ - Function: current-left-margin
+ This function returns the proper left margin value to use for
+ filling the text around point. The value is the sum of the
+ `left-margin' property of the character at the start of the
+ current line (or zero if none), and the value of the variable
+ `left-margin'.
+
+ - Function: current-fill-column
+ This function returns the proper fill column value to use for
+ filling the text around point. The value is the value of the
+ `fill-column' variable, minus the value of the `right-margin'
+ property of the character after point.
+
+ - Command: move-to-left-margin &optional n force
+ This function moves point to the left margin of the current line.
+ The column moved to is determined by calling the function
+ `current-left-margin'. If the argument N is non-`nil',
+ `move-to-left-margin' moves forward N-1 lines first.
+
+ If FORCE is non-`nil', that says to fix the line's indentation if
+ that doesn't match the left margin value.
+
+ - Function: delete-to-left-margin from to
+ This function removes left margin indentation from the text
+ between FROM and TO. The amount of indentation to delete is
+ determined by calling `current-left-margin'. In no case does this
+ function delete non-whitespace.
+
+ - Function: indent-to-left-margin
+ This is the default `indent-line-function', used in Fundamental
+ mode, Text mode, etc. Its effect is to adjust the indentation at
+ the beginning of the current line to the value specified by the
+ variable `left-margin'. This may involve either inserting or
+ deleting whitespace.
+
+ - Variable: left-margin
+ This variable specifies the base left margin column. In
+ Fundamental mode, <LFD> indents to this column. This variable
+ automatically becomes buffer-local when set in any fashion.
+
+\1f
+File: lispref.info, Node: Auto Filling, Next: Sorting, Prev: Margins, Up: Text
+
+Auto Filling
+============
+
+ Auto Fill mode is a minor mode that fills lines automatically as text
+is inserted. This section describes the hook used by Auto Fill mode.
+For a description of functions that you can call explicitly to fill and
+justify existing text, see *Note Filling::.
+
+ Auto Fill mode also enables the functions that change the margins and
+justification style to refill portions of the text. *Note Margins::.
+
+ - Variable: 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
+ `nil', in which case nothing special is done in that case.
+
+ The value of `auto-fill-function' is `do-auto-fill' when Auto-Fill
+ mode is enabled. That is a function whose sole purpose is to
+ implement the usual strategy for breaking a line.
+
+ In older Emacs versions, this variable was named
+ `auto-fill-hook', but since it is not called with the
+ standard convention for hooks, it was renamed to
+ `auto-fill-function' in version 19.
+
+\1f
File: lispref.info, Node: Sorting, Next: Columns, Prev: Auto Filling, Up: Text
Sorting Text
The sorting functions described in this section all rearrange text in
a buffer. This is in contrast to the function `sort', which rearranges
-the order of the elements of a list (*note Rearrangement::.). The
+the order of the elements of a list (*note Rearrangement::). The
values returned by these functions are not meaningful.
- - Function: sort-subr REVERSE NEXTRECFUN ENDRECFUN &optional
- STARTKEYFUN ENDKEYFUN
+ - Function: sort-subr reverse nextrecfun endrecfun &optional
+ startkeyfun endkeyfun
This function is the general text-sorting routine that divides a
buffer into records and sorts them. Most of the commands in this
section use this function.
(skip-chars-forward "\n \t\f")))
'forward-paragraph)
- - Command: sort-regexp-fields REVERSE RECORD-REGEXP KEY-REGEXP START
- END
+ - Command: sort-regexp-fields reverse record-regexp key-regexp start
+ end
This command sorts the region between START and END alphabetically
as specified by RECORD-REGEXP and KEY-REGEXP. If REVERSE is a
negative integer, then sorting is in reverse order.
If you call `sort-regexp-fields' interactively, it prompts for
RECORD-REGEXP and KEY-REGEXP in the minibuffer.
- - Command: sort-lines REVERSE START END
+ - Command: sort-lines reverse start end
This command alphabetically sorts lines in the region between
START and END. If REVERSE is non-`nil', the sort is in reverse
order.
- - Command: sort-paragraphs REVERSE START END
+ - Command: sort-paragraphs reverse start end
This command alphabetically sorts paragraphs in the region between
START and END. If REVERSE is non-`nil', the sort is in reverse
order.
- - Command: sort-pages REVERSE START END
+ - Command: sort-pages reverse start end
This command alphabetically sorts pages in the region between
START and END. If REVERSE is non-`nil', the sort is in reverse
order.
- - Command: sort-fields FIELD START END
+ - Command: sort-fields field start end
This command sorts lines in the region between START and END,
comparing them alphabetically by the FIELDth field of each line.
Fields are separated by whitespace and numbered starting from 1.
If FIELD is negative, sorting is by the -FIELDth field from the
end of the line. This command is useful for sorting tables.
- - Command: sort-numeric-fields FIELD START END
+ - Command: sort-numeric-fields field start end
This command sorts lines in the region between START and END,
comparing them numerically by the FIELDth field of each line. The
specified field must contain a number in each line of the region.
If FIELD is negative, sorting is by the -FIELDth field from the
end of the line. This command is useful for sorting tables.
- - Command: sort-columns REVERSE &optional BEG END
+ - Command: sort-columns reverse &optional beg end
This command sorts the lines in the region between BEG and END,
comparing them alphabetically by a certain range of columns. The
column positions of BEG and END bound the range of columns to sort
For an example of using `current-column', see the description of
`count-lines' in *Note Text Lines::.
- - Function: move-to-column COLUMN &optional FORCE
+ - Function: move-to-column column &optional force
This function moves point to COLUMN in the current line. The
calculation of COLUMN takes into account the widths of the
displayed representations of the characters between the start of
contents are entirely blank, then this is the horizontal position
of the end of the line.
- - Command: indent-to COLUMN &optional MINIMUM
+ - Command: indent-to column &optional minimum
This function indents from point with tabs and spaces until COLUMN
is reached. If MINIMUM is specified and non-`nil', then at least
that many spaces are inserted even if this requires going beyond
This section describes commands that indent all the lines in the
region. They return unpredictable values.
- - Command: indent-region START END TO-COLUMN
+ - Command: indent-region start end to-column
This command indents each nonblank line starting between START
(inclusive) and END (exclusive). If TO-COLUMN is `nil',
`indent-region' indents each nonblank line by calling the current
`indent-region' with a non-`nil' argument TO-COLUMN has a
different meaning and does not use this variable.
- - Command: indent-rigidly START END COUNT
+ - Command: indent-rigidly start end count
This command indents all lines starting between START (inclusive)
and END (exclusive) sideways by COUNT columns. This "preserves
the shape" of the affected region, moving it as a rigid unit.
`indent-rigidly' to indent the text copied from the message being
replied to.
- - Function: indent-code-rigidly START END COLUMNS &optional
- NOCHANGE-REGEXP
+ - Function: indent-code-rigidly start end columns &optional
+ nochange-regexp
This is like `indent-rigidly', except that it doesn't alter lines
that start within strings or comments.
This section describes two commands that indent the current line
based on the contents of previous lines.
- - Command: indent-relative &optional UNINDENTED-OK
+ - Command: indent-relative &optional unindented-ok
This command inserts whitespace at point, extending to the same
column as the next "indent point" of the previous nonblank line.
An indent point is a non-whitespace character following
typewriter. The feature works by inserting an appropriate number of
spaces and tab characters to reach the next tab stop column; it does not
affect the display of tab characters in the buffer (*note Usual
-Display::.). Note that the <TAB> character as input uses this tab stop
+Display::). Note that the <TAB> character as input uses this tab stop
feature only in a few major modes, such as Text mode.
- Command: tab-to-tab-stop
the current line (which is the line in which point is located).
It returns `nil'.
- - Command: backward-to-indentation ARG
+ - Command: backward-to-indentation arg
This command moves point backward ARG lines and then to the first
nonblank character on that line. It returns `nil'.
- - Command: forward-to-indentation ARG
+ - Command: forward-to-indentation arg
This command moves point forward ARG lines and then to the first
nonblank character on that line. It returns `nil'.
on strings and characters. *Note Case Tables::, for how to customize
which characters are upper or lower case and how to convert them.
- - Command: capitalize-region START END
+ - Command: capitalize-region start end
This function capitalizes all words in the region defined by START
and END. To capitalize means to convert each word's first
character to upper case and convert the rest of each word to lower
This Is The Contents Of The 5th Foo.
---------- Buffer: foo ----------
- - Command: downcase-region START END
+ - Command: downcase-region start end
This function converts all of the letters in the region defined by
START and END to lower case. The function returns `nil'.
When `downcase-region' is called interactively, START and END are
point and the mark, with the smallest first.
- - Command: upcase-region START END
+ - Command: upcase-region start end
This function converts all of the letters in the region defined by
START and END to upper case. The function returns `nil'.
When `upcase-region' is called interactively, START and END are
point and the mark, with the smallest first.
- - Command: capitalize-word COUNT
+ - Command: capitalize-word count
This function capitalizes COUNT words after point, moving point
over as it does. To capitalize means to convert each word's first
character to upper case and convert the rest of each word to lower
When `capitalize-word' is called interactively, COUNT is set to
the numeric prefix argument.
- - Command: downcase-word COUNT
+ - Command: downcase-word count
This function converts the COUNT words after point to all lower
case, moving point over as it does. If COUNT is negative, it
converts the -COUNT previous words but does not move point. The
When `downcase-word' is called interactively, COUNT is set to the
numeric prefix argument.
- - Command: upcase-word COUNT
+ - Command: upcase-word count
This function converts the COUNT words after point to all upper
case, moving point over as it does. If COUNT is negative, it
converts the -COUNT previous words but does not move point. The
===============
Text properties are an alternative interface to extents (*note
-Extents::.), and are built on top of them. They are useful when you
+Extents::), and are built on top of them. They are useful when you
want to view textual properties as being attached to the characters
themselves rather than to intervals of characters. The text property
interface is compatible with FSF Emacs.
Each character position in a buffer or a string can have a "text
property list", much like the property list of a symbol (*note Property
-Lists::.). The properties belong to a particular character at a
+Lists::). The properties belong to a particular character at a
particular place, such as, the letter `T' at the beginning of this
sentence or the first `o' in `foo'--if the same character occurs in two
different places, the two occurrences generally have different
* Saving Properties:: Saving text properties in files, and reading
them back.
-\1f
-File: lispref.info, Node: Examining Properties, Next: Changing Properties, Up: Text Properties
-
-Examining Text Properties
--------------------------
-
- The simplest way to examine text properties is to ask for the value
-of a particular property of a particular character. For that, use
-`get-text-property'. Use `text-properties-at' to get the entire
-property list of a character. *Note Property Search::, for functions
-to examine the properties of a number of characters at once.
-
- These functions handle both strings and buffers. (Keep in mind that
-positions in a string start from 0, whereas positions in a buffer start
-from 1.)
-
- - Function: get-text-property POS PROP &optional OBJECT
- This function returns the value of the PROP property of the
- character after position POS in OBJECT (a buffer or string). The
- argument OBJECT is optional and defaults to the current buffer.
-
- - Function: get-char-property POS PROP &optional OBJECT
- This function is like `get-text-property', except that it checks
- all extents, not just text-property extents.
-
-
- - Function: text-properties-at POSITION &optional OBJECT
- This function returns the entire property list of the character at
- POSITION in the string or buffer OBJECT. If OBJECT is `nil', it
- defaults to the current buffer.
-
- - Variable: 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, the value stored in this list is used instead. Here is
- an example:
-
- (setq default-text-properties '(foo 69))
- ;; Make sure character 1 has no properties of its own.
- (set-text-properties 1 2 nil)
- ;; What we get, when we ask, is the default value.
- (get-text-property 1 'foo)
- => 69
-
-\1f
-File: lispref.info, Node: Changing Properties, Next: Property Search, Prev: Examining Properties, Up: Text Properties
-
-Changing Text Properties
-------------------------
-
- The primitives for changing properties apply to a specified range of
-text. The function `set-text-properties' (see end of section) sets the
-entire property list of the text in that range; more often, it is
-useful to add, change, or delete just certain properties specified by
-name.
-
- Since text properties are considered part of the buffer's contents,
-and can affect how the buffer looks on the screen, any change in the
-text properties is considered a buffer modification. Buffer text
-property changes are undoable (*note Undo::.).
-
- - Function: put-text-property START END PROP VALUE &optional OBJECT
- This function sets the PROP property to VALUE for the text between
- START and END in the string or buffer OBJECT. If OBJECT is `nil',
- it defaults to the current buffer.
-
- - Function: add-text-properties START END PROPS &optional OBJECT
- This function modifies the text properties for the text between
- START and END in the string or buffer OBJECT. If OBJECT is `nil',
- it defaults to the current buffer.
-
- The argument PROPS specifies which properties to change. It
- should have the form of a property list (*note Property Lists::.):
- a list whose elements include the property names followed
- alternately by the corresponding values.
-
- The return value is `t' if the function actually changed some
- property's value; `nil' otherwise (if PROPS is `nil' or its values
- agree with those in the text).
-
- For example, here is how to set the `comment' and `face'
- properties of a range of text:
-
- (add-text-properties START END
- '(comment t face highlight))
-
- - Function: remove-text-properties START END PROPS &optional OBJECT
- This function deletes specified text properties from the text
- between START and END in the string or buffer OBJECT. If OBJECT
- is `nil', it defaults to the current buffer.
-
- The argument PROPS specifies which properties to delete. It
- should have the form of a property list (*note Property Lists::.):
- a list whose elements are property names alternating with
- corresponding values. But only the names matter--the values that
- accompany them are ignored. For example, here's how to remove the
- `face' property.
-
- (remove-text-properties START END '(face nil))
-
- The return value is `t' if the function actually changed some
- property's value; `nil' otherwise (if PROPS is `nil' or if no
- character in the specified text had any of those properties).
-
- - Function: set-text-properties START END PROPS &optional OBJECT
- This function completely replaces the text property list for the
- text between START and END in the string or buffer OBJECT. If
- OBJECT is `nil', it defaults to the current buffer.
-
- The argument PROPS is the new property list. It should be a list
- whose elements are property names alternating with corresponding
- values.
-
- After `set-text-properties' returns, all the characters in the
- specified range have identical properties.
-
- If PROPS is `nil', the effect is to get rid of all properties from
- the specified range of text. Here's an example:
-
- (set-text-properties START END nil)
-
- See also the function `buffer-substring-without-properties' (*note
-Buffer Contents::.) which copies text from the buffer but does not copy
-its properties.
-
-\1f
-File: lispref.info, Node: Property Search, Next: Special Properties, Prev: Changing Properties, Up: Text Properties
-
-Property Search Functions
--------------------------
-
- In typical use of text properties, most of the time several or many
-consecutive characters have the same value for a property. Rather than
-writing your programs to examine characters one by one, it is much
-faster to process chunks of text that have the same property value.
-
- Here are functions you can use to do this. They use `eq' for
-comparing property values. In all cases, OBJECT defaults to the
-current buffer.
-
- For high performance, it's very important to use the LIMIT argument
-to these functions, especially the ones that search for a single
-property--otherwise, they may spend a long time scanning to the end of
-the buffer, if the property you are interested in does not change.
-
- Remember that a position is always between two characters; the
-position returned by these functions is between two characters with
-different properties.
-
- - Function: next-property-change POS &optional OBJECT LIMIT
- The function scans the text forward from position POS in the
- string or buffer OBJECT till it finds a change in some text
- property, then returns the position of the change. In other
- words, it returns the position of the first character beyond POS
- whose properties are not identical to those of the character just
- after POS.
-
- If LIMIT is non-`nil', then the scan ends at position LIMIT. If
- there is no property change before that point,
- `next-property-change' returns LIMIT.
-
- The value is `nil' if the properties remain unchanged all the way
- to the end of OBJECT and LIMIT is `nil'. If the value is
- non-`nil', it is a position greater than or equal to POS. The
- value equals POS only when LIMIT equals POS.
-
- Here is an example of how to scan the buffer by chunks of text
- within which all properties are constant:
-
- (while (not (eobp))
- (let ((plist (text-properties-at (point)))
- (next-change
- (or (next-property-change (point) (current-buffer))
- (point-max))))
- Process text from point to NEXT-CHANGE...
- (goto-char next-change)))
-
- - Function: next-single-property-change POS PROP &optional OBJECT LIMIT
- The function scans the text forward from position POS in the
- string or buffer OBJECT till it finds a change in the PROP
- property, then returns the position of the change. In other
- words, it returns the position of the first character beyond POS
- whose PROP property differs from that of the character just after
- POS.
-
- If LIMIT is non-`nil', then the scan ends at position LIMIT. If
- there is no property change before that point,
- `next-single-property-change' returns LIMIT.
-
- The value is `nil' if the property remains unchanged all the way to
- the end of OBJECT and LIMIT is `nil'. If the value is non-`nil',
- it is a position greater than or equal to POS; it equals POS only
- if LIMIT equals POS.
-
- - Function: previous-property-change POS &optional OBJECT LIMIT
- This is like `next-property-change', but scans back from POS
- instead of forward. If the value is non-`nil', it is a position
- less than or equal to POS; it equals POS only if LIMIT equals POS.
-
- - Function: previous-single-property-change POS PROP &optional OBJECT
- LIMIT
- This is like `next-single-property-change', but scans back from
- POS instead of forward. If the value is non-`nil', it is a
- position less than or equal to POS; it equals POS only if LIMIT
- equals POS.
-
- - Function: text-property-any START END PROP VALUE &optional OBJECT
- This function returns non-`nil' if at least one character between
- START and END has a property PROP whose value is VALUE. More
- precisely, it returns the position of the first such character.
- Otherwise, it returns `nil'.
-
- The optional fifth argument, OBJECT, specifies the string or
- buffer to scan. Positions are relative to OBJECT. The default
- for OBJECT is the current buffer.
-
- - Function: text-property-not-all START END PROP VALUE &optional OBJECT
- This function returns non-`nil' if at least one character between
- START and END has a property PROP whose value differs from VALUE.
- More precisely, it returns the position of the first such
- character. Otherwise, it returns `nil'.
-
- The optional fifth argument, OBJECT, specifies the string or
- buffer to scan. Positions are relative to OBJECT. The default
- for OBJECT is the current buffer.
-
-\1f
-File: lispref.info, Node: Special Properties, Next: Saving Properties, Prev: Property Search, Up: Text Properties
-
-Properties with Special Meanings
---------------------------------
-
- The predefined properties are the same as those for extents. *Note
-Extent Properties::.
-
-\1f
-File: lispref.info, Node: Saving Properties, Prev: Special Properties, Up: Text Properties
-
-Saving Text Properties in Files
--------------------------------
-
- You can save text properties in files, and restore text properties
-when inserting the files, using these two hooks:
-
- - Variable: write-region-annotate-functions
- This variable's value is a list of functions for `write-region' to
- run to encode text properties in some fashion as annotations to
- the text being written in the file. *Note Writing to Files::.
-
- Each function in the list is called with two arguments: the start
- and end of the region to be written. These functions should not
- alter the contents of the buffer. Instead, they should return
- lists indicating annotations to write in the file in addition to
- the text in the buffer.
-
- Each function should return a list of elements of the form
- `(POSITION . STRING)', where POSITION is an integer specifying the
- relative position in the text to be written, and STRING is the
- annotation to add there.
-
- Each list returned by one of these functions must be already
- sorted in increasing order by POSITION. If there is more than one
- function, `write-region' merges the lists destructively into one
- sorted list.
-
- When `write-region' actually writes the text from the buffer to the
- file, it intermixes the specified annotations at the corresponding
- positions. All this takes place without modifying the buffer.
-
- - Variable: after-insert-file-functions
- This variable holds a list of functions for `insert-file-contents'
- to call after inserting a file's contents. These functions should
- scan the inserted text for annotations, and convert them to the
- text properties they stand for.
-
- Each function receives one argument, the length of the inserted
- text; point indicates the start of that text. The function should
- scan that text for annotations, delete them, and create the text
- properties that the annotations specify. The function should
- return the updated length of the inserted text, as it stands after
- those changes. The value returned by one function becomes the
- argument to the next function.
-
- These functions should always return with point at the beginning of
- the inserted text.
-
- The intended use of `after-insert-file-functions' is for converting
- some sort of textual annotations into actual text properties. But
- other uses may be possible.
-
- 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 will
-produce good, general extensions we can install in Emacs.
-
- We suggest not trying to handle arbitrary Lisp objects as property
-names or property values--because a program that general is probably
-difficult to write, and slow. Instead, choose a set of possible data
-types that are reasonably flexible, and not too hard to encode.
-
- *Note Format Conversion::, for a related feature.
-
-\1f
-File: lispref.info, Node: Substitution, Next: Registers, Prev: Text Properties, Up: Text
-
-Substituting for a Character Code
-=================================
-
- The following functions replace characters within a specified region
-based on their character codes.
-
- - Function: subst-char-in-region START END OLD-CHAR NEW-CHAR &optional
- NOUNDO
- This function replaces all occurrences of the character OLD-CHAR
- with the character NEW-CHAR in the region of the current buffer
- defined by START and END.
-
- If NOUNDO is non-`nil', then `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
- (*note Selective Display::.).
-
- `subst-char-in-region' does not move point and returns `nil'.
-
- ---------- Buffer: foo ----------
- This is the contents of the buffer before.
- ---------- Buffer: foo ----------
-
- (subst-char-in-region 1 20 ?i ?X)
- => nil
-
- ---------- Buffer: foo ----------
- ThXs Xs the contents of the buffer before.
- ---------- Buffer: foo ----------
-
- - Function: translate-region START END TABLE
- This function applies a translation table to the characters in the
- buffer between positions START and END. The translation table
- TABLE can be either a string, a vector, or a char-table.
-
- If TABLE is a string, its Nth element is the mapping for the
- character with code N.
-
- If TABLE is a vector, its Nth element is the mapping for character
- with code N. Legal mappings are characters, strings, or `nil'
- (meaning don't replace.)
-
- If TABLE is a char-table, its elements describe the mapping
- between characters and their replacements. The char-table should
- be of type `char' or `generic'.
-
- When the TABLE is a string or vector and its length is less than
- the total number of characters (256 without Mule), any characters
- with codes larger than the length of TABLE are not altered by the
- translation.
-
- The return value of `translate-region' is the number of characters
- that were actually changed by the translation. This does not
- count characters that were mapped into themselves in the
- translation table.
-
- *NOTE*: Prior to XEmacs 21.2, the TABLE argument was allowed only
- to be a string. This is still the case in FSF Emacs.
-
- The following example creates a char-table that is passed to
- `translate-region', which translates character `a' to `the letter
- a', removes character `b', and translates character `c' to newline.
-
- ---------- Buffer: foo ----------
- Here is a sentence in the buffer.
- ---------- Buffer: foo ----------
-
- (let ((table (make-char-table 'generic)))
- (put-char-table ?a "the letter a" table)
- (put-char-table ?b "" table)
- (put-char-table ?c ?\n table)
- (translate-region (point-min) (point-max) table))
- => 3
-
- ---------- Buffer: foo ----------
- Here is the letter a senten
- e in the uffer.
- ---------- Buffer: foo ----------
-
-\1f
-File: lispref.info, Node: Registers, Next: Transposition, Prev: Substitution, Up: Text
-
-Registers
-=========
-
- A register is a sort of variable used in XEmacs editing that can
-hold a marker, a string, a rectangle, a window configuration (of one
-frame), or a frame configuration (of all frames). Each register is
-named by a single character. All characters, including control and
-meta characters (but with the exception of `C-g'), can be used to name
-registers. Thus, there are 255 possible registers. A register is
-designated in Emacs Lisp by a character that is its name.
-
- The functions in this section return unpredictable values unless
-otherwise stated.
-
- - Variable: register-alist
- This variable is an alist of elements of the form `(NAME .
- CONTENTS)'. Normally, there is one element for each XEmacs
- register that has been used.
-
- The object NAME is a character (an integer) identifying the
- register. The object CONTENTS is a string, marker, or list
- representing the register contents. A string represents text
- stored in the register. A marker represents a position. A list
- represents a rectangle; its elements are strings, one per line of
- the rectangle.
-
- - Function: get-register REG
- This function returns the contents of the register REG, or `nil'
- if it has no contents.
-
- - Function: set-register REG VALUE
- This function sets the contents of register REG to VALUE. A
- register can be set to any value, but the other register functions
- expect only certain data types. The return value is VALUE.
-
- - Command: view-register REG
- This command displays what is contained in register REG.
-
- - Command: insert-register REG &optional BEFOREP
- This command inserts contents of register REG into the current
- buffer.
-
- Normally, this command puts point before the inserted text, and the
- mark after it. However, if the optional second argument BEFOREP
- is non-`nil', it puts the mark before and point after. You can
- pass a non-`nil' second argument BEFOREP to this function
- interactively by supplying any prefix argument.
-
- If the register contains a rectangle, then the rectangle is
- inserted with its upper left corner at point. This means that
- text is inserted in the current line and underneath it on
- successive lines.
-
- If the register contains something other than saved text (a
- string) or a rectangle (a list), currently useless things happen.
- This may be changed in the future.
-
-\1f
-File: lispref.info, Node: Transposition, Next: Change Hooks, Prev: Registers, Up: Text
-
-Transposition of Text
-=====================
-
- This subroutine is used by the transposition commands.
-
- - Function: transpose-regions START1 END1 START2 END2 &optional
- LEAVE-MARKERS
- This function exchanges two nonoverlapping portions of the buffer.
- Arguments START1 and END1 specify the bounds of one portion and
- arguments START2 and END2 specify the bounds of the other portion.
-
- Normally, `transpose-regions' relocates markers with the transposed
- text; a marker previously positioned within one of the two
- transposed portions moves along with that portion, thus remaining
- between the same two characters in their new position. However,
- if LEAVE-MARKERS is non-`nil', `transpose-regions' does not do
- this--it leaves all markers unrelocated.
-
projects / chise / xemacs-chise.git- / blobdiff