-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.0b 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: Commands for Insertion, Next: Deletion, Prev: Insertion, Up: Text
+File: lispref.info, Node: Skipping Characters, Prev: List Motion, Up: Motion
-User-Level Insertion Commands
-=============================
-
- This section describes higher-level commands for inserting text,
-commands intended primarily for the user but useful also in Lisp
-programs.
-
- - Command: insert-buffer FROM-BUFFER-OR-NAME
- This command inserts the entire contents of FROM-BUFFER-OR-NAME
- (which must exist) into the current buffer after point. It leaves
- the mark after the inserted text. The value is `nil'.
-
- - Command: self-insert-command COUNT
- This command inserts the last character typed; it does so COUNT
- times, before point, and returns `nil'. Most printing characters
- are bound to this command. In routine use, `self-insert-command'
- is the most frequently called function in XEmacs, but programs
- rarely use it except to install it on a keymap.
-
- In an interactive call, COUNT is the numeric prefix argument.
-
- This command calls `auto-fill-function' whenever that is non-`nil'
- and the character inserted is a space or a newline (*note Auto
- Filling::.).
-
- This command performs abbrev expansion if Abbrev mode is enabled
- and the inserted character does not have word-constituent syntax.
- (*Note Abbrevs::, and *Note Syntax Class Table::.)
-
- This is also responsible for calling `blink-paren-function' when
- the inserted character has close parenthesis syntax (*note
- Blinking::.).
-
- - Command: newline &optional NUMBER-OF-NEWLINES
- This command inserts newlines into the current buffer before point.
- If NUMBER-OF-NEWLINES is supplied, that many newline characters
- are inserted.
-
- This function calls `auto-fill-function' if the current column
- number is greater than the value of `fill-column' and
- NUMBER-OF-NEWLINES is `nil'. Typically what `auto-fill-function'
- does is insert a newline; thus, the overall result in this case is
- to insert two newlines at different places: one at point, and
- another earlier in the line. `newline' does not auto-fill if
- NUMBER-OF-NEWLINES is non-`nil'.
-
- This command indents to the left margin if that is not zero.
- *Note Margins::.
-
- The value returned is `nil'. In an interactive call, COUNT is the
- numeric prefix argument.
-
- - Command: split-line
- This command splits the current line, moving the portion of the
- line after point down vertically so that it is on the next line
- directly below where it was before. Whitespace is inserted as
- needed at the beginning of the lower line, using the `indent-to'
- function. `split-line' returns the position of point.
-
- Programs hardly ever use this function.
-
- - Variable: overwrite-mode
- This variable controls whether overwrite mode is in effect: a
- non-`nil' value enables the mode. It is automatically made
- buffer-local when set in any fashion.
-
-\1f
-File: lispref.info, Node: Deletion, Next: User-Level Deletion, Prev: Commands for Insertion, Up: Text
-
-Deleting Text
-=============
-
- Deletion means removing part of the text in a buffer, without saving
-it in the kill ring (*note The Kill Ring::.). Deleted text can't be
-yanked, but can be reinserted using the undo mechanism (*note Undo::.).
-Some deletion functions do save text in the kill ring in some special
-cases.
-
- All of the deletion functions operate on the current buffer, and all
-return a value of `nil'.
-
- - Function: erase-buffer &optional BUFFER
- This function deletes the entire text of BUFFER, leaving it empty.
- If the buffer is read-only, it signals a `buffer-read-only'
- error. Otherwise, it deletes the text without asking for any
- confirmation. It returns `nil'. BUFFER defaults to the current
- buffer if omitted.
-
- Normally, deleting a large amount of text from a buffer inhibits
- further auto-saving of that buffer "because it has shrunk".
- However, `erase-buffer' does not do this, the idea being that the
- future text is not really related to the former text, and its size
- should not be compared with that of the former text.
-
- - Command: delete-region START END &optional BUFFER
- This command deletes the text in BUFFER in the region defined by
- START and END. The value is `nil'. If optional argument BUFFER
- is `nil', the current buffer is assumed.
-
- - Command: delete-char COUNT &optional KILLP
- This command deletes COUNT characters directly after point, or
- before point if COUNT is negative. If KILLP is non-`nil', then it
- saves the deleted characters in the kill ring.
-
- In an interactive call, COUNT is the numeric prefix argument, and
- KILLP is the unprocessed prefix argument. Therefore, if a prefix
- argument is supplied, the text is saved in the kill ring. If no
- prefix argument is supplied, then one character is deleted, but
- not saved in the kill ring.
-
- The value returned is always `nil'.
-
- - Command: delete-backward-char COUNT &optional KILLP
- This command deletes COUNT characters directly before point, or
- after point if COUNT is negative. If KILLP is non-`nil', then it
- saves the deleted characters in the kill ring.
-
- In an interactive call, COUNT is the numeric prefix argument, and
- KILLP is the unprocessed prefix argument. Therefore, if a prefix
- argument is supplied, the text is saved in the kill ring. If no
- prefix argument is supplied, then one character is deleted, but
- not saved in the kill ring.
-
- The value returned is always `nil'.
-
- - Command: backward-delete-char-untabify COUNT &optional KILLP
- This command deletes COUNT characters backward, changing tabs into
- spaces. When the next character to be deleted is a tab, it is
- first replaced with the proper number of spaces to preserve
- alignment and then one of those spaces is deleted instead of the
- tab. If KILLP is non-`nil', then the command saves the deleted
- characters in the kill ring.
-
- Conversion of tabs to spaces happens only if COUNT is positive.
- If it is negative, exactly -COUNT characters after point are
- deleted.
-
- In an interactive call, COUNT is the numeric prefix argument, and
- KILLP is the unprocessed prefix argument. Therefore, if a prefix
- argument is supplied, the text is saved in the kill ring. If no
- prefix argument is supplied, then one character is deleted, but
- not saved in the kill ring.
-
- The value returned is always `nil'.
-
-\1f
-File: lispref.info, Node: User-Level Deletion, Next: The Kill Ring, Prev: Deletion, Up: Text
-
-User-Level Deletion Commands
-============================
-
- This section describes higher-level commands for deleting text,
-commands intended primarily for the user but useful also in Lisp
-programs.
-
- - Command: delete-horizontal-space
- This function deletes all spaces and tabs around point. It returns
- `nil'.
+Skipping Characters
+-------------------
- In the following examples, we call `delete-horizontal-space' four
- times, once on each line, with point between the second and third
- characters on the line each time.
+ The following two functions move point over a specified set of
+characters. For example, they are often used to skip whitespace. For
+related functions, see *Note Motion and Syntax::.
+
+ - Function: skip-chars-forward character-set &optional limit buffer
+ This function moves point in BUFFER forward, skipping over a given
+ set of characters. It examines the character following point,
+ then advances point if the character matches CHARACTER-SET. This
+ continues until it reaches a character that does not match. The
+ function returns `nil'. BUFFER defaults to the current buffer if
+ omitted.
+
+ The argument CHARACTER-SET is like the inside of a `[...]' in a
+ regular expression except that `]' is never special and `\' quotes
+ `^', `-' or `\'. Thus, `"a-zA-Z"' skips over all letters,
+ stopping before the first non-letter, and `"^a-zA-Z'" skips
+ non-letters stopping before the first letter. *Note Regular
+ Expressions::.
+
+ If LIMIT is supplied (it must be a number or a marker), it
+ specifies the maximum position in the buffer that point can be
+ skipped to. Point will stop at or before LIMIT.
+
+ In the following example, point is initially located directly
+ before the `T'. After the form is evaluated, point is located at
+ the end of that line (between the `t' of `hat' and the newline).
+ The function skips all letters and spaces, but not newlines.
---------- Buffer: foo ----------
- I -!-thought
- I -!- thought
- We-!- thought
- Yo-!-u thought
+ I read "-!-The cat in the hat
+ comes back" twice.
---------- Buffer: foo ----------
- (delete-horizontal-space) ; Four times.
+ (skip-chars-forward "a-zA-Z ")
=> nil
---------- Buffer: foo ----------
- Ithought
- Ithought
- Wethought
- You thought
+ I read "The cat in the hat-!-
+ comes back" twice.
---------- Buffer: foo ----------
- - 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 JOIN-FOLLOWING-P is non-`nil',
- `delete-indentation' joins this line to the following line
- instead. The value is `nil'.
+ - Function: skip-chars-backward character-set &optional limit buffer
+ This function moves point backward, skipping characters that match
+ CHARACTER-SET, until LIMIT. It just like `skip-chars-forward'
+ except for the direction of motion.
- If there is a fill prefix, and the second of the lines being joined
- starts with the prefix, then `delete-indentation' deletes the fill
- prefix before joining the lines. *Note Margins::.
+\1f
+File: lispref.info, Node: Excursions, Next: Narrowing, Prev: Motion, Up: Positions
+
+Excursions
+==========
+
+ It is often useful to move point "temporarily" within a localized
+portion of the program, or to switch buffers temporarily. This is
+called an "excursion", and it is done with the `save-excursion' special
+form. This construct saves the current buffer and its values of point
+and the mark so they can be restored after the completion of the
+excursion.
+
+ The forms for saving and restoring the configuration of windows are
+described elsewhere (see *Note Window Configurations:: and *note Frame
+Configurations::).
+
+ - Special Form: save-excursion forms...
+ The `save-excursion' special form saves the identity of the current
+ buffer and the values of point and the mark in it, evaluates
+ FORMS, and finally restores the buffer and its saved values of
+ point and the mark. All three saved values are restored even in
+ case of an abnormal exit via `throw' or error (*note Nonlocal
+ Exits::).
+
+ The `save-excursion' special form is the standard way to switch
+ buffers or move point within one part of a program and avoid
+ affecting the rest of the program. It is used more than 500 times
+ in the Lisp sources of XEmacs.
+
+ `save-excursion' does not save the values of point and the mark for
+ other buffers, so changes in other buffers remain in effect after
+ `save-excursion' exits.
+
+ Likewise, `save-excursion' does not restore window-buffer
+ correspondences altered by functions such as `switch-to-buffer'.
+ One way to restore these correspondences, and the selected window,
+ is to use `save-window-excursion' inside `save-excursion' (*note
+ Window Configurations::).
+
+ The value returned by `save-excursion' is the result of the last of
+ FORMS, or `nil' if no FORMS are given.
+
+ (save-excursion
+ FORMS)
+ ==
+ (let ((old-buf (current-buffer))
+ (old-pnt (point-marker))
+ (old-mark (copy-marker (mark-marker))))
+ (unwind-protect
+ (progn FORMS)
+ (set-buffer old-buf)
+ (goto-char old-pnt)
+ (set-marker (mark-marker) old-mark)))
+
+ - Special Form: save-current-buffer forms...
+ This special form is similar to `save-excursion' but it only saves
+ and restores the current buffer. Beginning with XEmacs 20.3,
+ `save-current-buffer' is a primitive.
+
+ - Special Form: with-current-buffer buffer forms...
+ This special form evaluates FORMS with BUFFER as the current
+ buffer. It returns the value of the last form.
+
+ - Special Form: with-temp-file filename forms...
+ This special form creates a new buffer, evaluates FORMS there, and
+ writes the buffer to FILENAME. It returns the value of the last
+ form evaluated.
+
+ - Special Form: save-selected-window forms...
+ This special form is similar to `save-excursion' but it saves and
+ restores the selected window and nothing else.
- In the example below, point is located on the line starting
- `events', and it makes no difference if there are trailing spaces
- in the preceding line.
+\1f
+File: lispref.info, Node: Narrowing, Prev: Excursions, Up: Positions
+
+Narrowing
+=========
+
+ "Narrowing" means limiting the text addressable by XEmacs editing
+commands to a limited range of characters in a buffer. The text that
+remains addressable is called the "accessible portion" of the buffer.
+
+ Narrowing is specified with two buffer positions which become the
+beginning and end of the accessible portion. For most editing commands
+and most Emacs primitives, these positions replace the values of the
+beginning and end of the buffer. While narrowing is in effect, no text
+outside the accessible portion is displayed, and point cannot move
+outside the accessible portion.
+
+ Values such as positions or line numbers, which usually count from
+the beginning of the buffer, do so despite narrowing, but the functions
+which use them refuse to operate on text that is inaccessible.
+
+ The commands for saving buffers are unaffected by narrowing; they
+save the entire buffer regardless of any narrowing.
+
+ - Command: narrow-to-region start end &optional buffer
+ This function sets the accessible portion of BUFFER to start at
+ START and end at END. Both arguments should be character
+ positions. BUFFER defaults to the current buffer if omitted.
+
+ In an interactive call, START and END are set to the bounds of the
+ current region (point and the mark, with the smallest first).
+
+ - Command: narrow-to-page &optional move-count
+ This function sets the accessible portion of the current buffer to
+ include just the current page. An optional first argument
+ MOVE-COUNT non-`nil' means to move forward or backward by
+ MOVE-COUNT pages and then narrow. The variable `page-delimiter'
+ specifies where pages start and end (*note Standard Regexps::).
+
+ In an interactive call, MOVE-COUNT is set to the numeric prefix
+ argument.
+
+ - Command: widen &optional buffer
+ This function cancels any narrowing in BUFFER, so that the entire
+ contents are accessible. This is called "widening". It is
+ equivalent to the following expression:
+
+ (narrow-to-region 1 (1+ (buffer-size)))
+
+ BUFFER defaults to the current buffer if omitted.
+
+ - Special Form: save-restriction body...
+ This special form saves the current bounds of the accessible
+ portion, evaluates the BODY forms, and finally restores the saved
+ bounds, thus restoring the same state of narrowing (or absence
+ thereof) formerly in effect. The state of narrowing is restored
+ even in the event of an abnormal exit via `throw' or error (*note
+ Nonlocal Exits::). Therefore, this construct is a clean way to
+ narrow a buffer temporarily.
+
+ The value returned by `save-restriction' is that returned by the
+ last form in BODY, or `nil' if no body forms were given.
+
+ *Caution:* it is easy to make a mistake when using the
+ `save-restriction' construct. Read the entire description here
+ before you try it.
+
+ If BODY changes the current buffer, `save-restriction' still
+ restores the restrictions on the original buffer (the buffer whose
+ restrictions it saved from), but it does not restore the identity
+ of the current buffer.
+
+ `save-restriction' does _not_ restore point and the mark; use
+ `save-excursion' for that. If you use both `save-restriction' and
+ `save-excursion' together, `save-excursion' should come first (on
+ the outside). Otherwise, the old point value would be restored
+ with temporary narrowing still in effect. If the old point value
+ were outside the limits of the temporary narrowing, this would
+ fail to restore it accurately.
+
+ The `save-restriction' special form records the values of the
+ beginning and end of the accessible portion as distances from the
+ beginning and end of the buffer. In other words, it records the
+ amount of inaccessible text before and after the accessible
+ portion.
+
+ This method yields correct results if BODY does further narrowing.
+ However, `save-restriction' can become confused if the body widens
+ and then make changes outside the range of the saved narrowing.
+ When this is what you want to do, `save-restriction' is not the
+ right tool for the job. Here is what you must use instead:
+
+ (let ((start (point-min-marker))
+ (end (point-max-marker)))
+ (unwind-protect
+ (progn BODY)
+ (save-excursion
+ (set-buffer (marker-buffer start))
+ (narrow-to-region start end))))
+
+ Here is a simple example of correct use of `save-restriction':
---------- Buffer: foo ----------
- When in the course of human
- -!- events, it becomes necessary
+ This is the contents of foo
+ This is the contents of foo
+ This is the contents of foo-!-
---------- Buffer: foo ----------
- (delete-indentation)
- => nil
- ---------- Buffer: foo ----------
- When in the course of human-!- events, it becomes necessary
- ---------- Buffer: foo ----------
-
- After the lines are joined, the function `fixup-whitespace' is
- responsible for deciding whether to leave a space at the junction.
-
- - Function: fixup-whitespace
- This function replaces all the white space surrounding point with
- either one space or no space, according to the context. It
- returns `nil'.
-
- At the beginning or end of a line, the appropriate amount of space
- is none. Before a character with close parenthesis syntax, or
- after a character with open parenthesis or expression-prefix
- syntax, no space is also appropriate. Otherwise, one space is
- appropriate. *Note Syntax Class Table::.
-
- In the example below, `fixup-whitespace' is called the first time
- with point before the word `spaces' in the first line. For the
- second invocation, point is directly after the `('.
-
+ (save-excursion
+ (save-restriction
+ (goto-char 1)
+ (forward-line 2)
+ (narrow-to-region 1 (point))
+ (goto-char (point-min))
+ (replace-string "foo" "bar")))
+
---------- Buffer: foo ----------
- This has too many -!-spaces
- This has too many spaces at the start of (-!- this list)
+ This is the contents of bar
+ This is the contents of bar
+ This is the contents of foo-!-
---------- Buffer: foo ----------
- (fixup-whitespace)
- => nil
- (fixup-whitespace)
- => nil
-
- ---------- Buffer: foo ----------
- This has too many spaces
- This has too many spaces at the start of (this list)
- ---------- Buffer: foo ----------
+\1f
+File: lispref.info, Node: Markers, Next: Text, Prev: Positions, Up: Top
- - Command: just-one-space
- This command replaces any spaces and tabs around point with a
- single space. It returns `nil'.
+Markers
+*******
- - Command: delete-blank-lines
- This function deletes blank lines surrounding point. If point is
- on a blank line with one or more blank lines before or after it,
- then all but one of them are deleted. If point is on an isolated
- blank line, then it is deleted. If point is on a nonblank line,
- the command deletes all blank lines following it.
+ A "marker" is a Lisp object used to specify a position in a buffer
+relative to the surrounding text. A marker changes its offset from the
+beginning of the buffer automatically whenever text is inserted or
+deleted, so that it stays with the two characters on either side of it.
- A blank line is defined as a line containing only tabs and spaces.
+* Menu:
- `delete-blank-lines' returns `nil'.
+* Overview of Markers:: The components of a marker, and how it relocates.
+* Predicates on Markers:: Testing whether an object is a marker.
+* Creating Markers:: Making empty markers or markers at certain places.
+* Information from Markers:: Finding the marker's buffer or character position.
+* Changing Markers:: Moving the marker to a new buffer or position.
+* The Mark:: How ``the mark'' is implemented with a marker.
+* The Region:: How to access ``the region''.
\1f
-File: lispref.info, Node: The Kill Ring, Next: Undo, Prev: User-Level Deletion, Up: Text
-
-The Kill Ring
-=============
-
- "Kill" functions delete text like the deletion functions, but save
-it so that the user can reinsert it by "yanking". Most of these
-functions have `kill-' in their name. By contrast, the functions whose
-names start with `delete-' normally do not save text for yanking
-(though they can still be undone); these are "deletion" functions.
-
- Most of the kill commands are primarily for interactive use, and are
-not described here. What we do describe are the functions provided for
-use in writing such commands. You can use these functions to write
-commands for killing text. When you need to delete text for internal
-purposes within a Lisp function, you should normally use deletion
-functions, so as not to disturb the kill ring contents. *Note
-Deletion::.
-
- Killed text is saved for later yanking in the "kill ring". This is
-a list that holds a number of recent kills, not just the last text
-kill. We call this a "ring" because yanking treats it as having
-elements in a cyclic order. The list is kept in the variable
-`kill-ring', and can be operated on with the usual functions for lists;
-there are also specialized functions, described in this section, that
-treat it as a ring.
-
- Some people think this use of the word "kill" is unfortunate, since
-it refers to operations that specifically *do not* destroy the entities
-"killed". This is in sharp contrast to ordinary life, in which death
-is permanent and "killed" entities do not come back to life.
-Therefore, other metaphors have been proposed. For example, the term
-"cut ring" makes sense to people who, in pre-computer days, used
-scissors and paste to cut up and rearrange manuscripts. However, it
-would be difficult to change the terminology now.
+File: lispref.info, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers
-* Menu:
+Overview of Markers
+===================
-* Kill Ring Concepts:: What text looks like in the kill ring.
-* Kill Functions:: Functions that kill text.
-* Yank Commands:: Commands that access the kill ring.
-* Low-Level Kill Ring:: Functions and variables for kill ring access.
-* Internals of Kill Ring:: Variables that hold kill-ring data.
+ A marker specifies a buffer and a position in that buffer. The
+marker can be used to represent a position in the functions that
+require one, just as an integer could be used. *Note Positions::, for
+a complete description of positions.
+
+ A marker has two attributes: the marker position, and the marker
+buffer. The marker position is an integer that is equivalent (at a
+given time) to the marker as a position in that buffer. But the
+marker's position value can change often during the life of the marker.
+Insertion and deletion of text in the buffer relocate the marker. The
+idea is that a marker positioned between two characters remains between
+those two characters despite insertion and deletion elsewhere in the
+buffer. Relocation changes the integer equivalent of the marker.
+
+ Deleting text around a marker's position leaves the marker between
+the characters immediately before and after the deleted text. Inserting
+text at the position of a marker normally leaves the marker in front of
+the new text--unless it is inserted with `insert-before-markers' (*note
+Insertion::).
+
+ Insertion and deletion in a buffer must check all the markers and
+relocate them if necessary. This slows processing in a buffer with a
+large number of markers. For this reason, it is a good idea to make a
+marker point nowhere if you are sure you don't need it any more.
+Unreferenced markers are garbage collected eventually, but until then
+will continue to use time if they do point somewhere.
+
+ Because it is common to perform arithmetic operations on a marker
+position, most of the arithmetic operations (including `+' and `-')
+accept markers as arguments. In such cases, the marker stands for its
+current position.
+
+ Note that you can use extents to achieve the same functionality, and
+more, as markers. (Markers were defined before extents, which is why
+they both continue to exist.) A zero-length extent with the
+`detachable' property removed is almost identical to a marker. (*Note
+Extent Endpoints::, for more information on zero-length extents.)
+
+ In particular:
+
+ * In order to get marker-like behavior in a zero-length extent, the
+ `detachable' property must be removed (otherwise, the extent will
+ disappear when text near it is deleted) and exactly one endpoint
+ must be closed (if both endpoints are closed, the extent will
+ expand to contain text inserted where it is located).
+
+ * If a zero-length extent has the `end-open' property but not the
+ `start-open' property (this is the default), text inserted at the
+ extent's location causes the extent to move forward, just like a
+ marker.
+
+ * If a zero-length extent has the `start-open' property but not the
+ `end-open' property, text inserted at the extent's location causes
+ the extent to remain before the text, like what happens to markers
+ when `insert-before-markers' is used.
+
+ * Markers end up after or before inserted text depending on whether
+ `insert' or `insert-before-markers' was called. These functions
+ do not affect zero-length extents differently; instead, the
+ presence or absence of the `start-open' and `end-open' extent
+ properties determines this, as just described.
+
+ * Markers are automatically removed from a buffer when they are no
+ longer in use. Extents remain around until explicitly removed
+ from a buffer.
+
+ * Many functions are provided for listing the extents in a buffer or
+ in a region of a buffer. No such functions exist for markers.
+
+ Here are examples of creating markers, setting markers, and moving
+point to markers:
+
+ ;; Make a new marker that initially does not point anywhere:
+ (setq m1 (make-marker))
+ => #<marker in no buffer>
+
+ ;; Set `m1' to point between the 99th and 100th characters
+ ;; in the current buffer:
+ (set-marker m1 100)
+ => #<marker at 100 in markers.texi>
+
+ ;; Now insert one character at the beginning of the buffer:
+ (goto-char (point-min))
+ => 1
+ (insert "Q")
+ => nil
+
+ ;; `m1' is updated appropriately.
+ m1
+ => #<marker at 101 in markers.texi>
+
+ ;; Two markers that point to the same position
+ ;; are not `eq', but they are `equal'.
+ (setq m2 (copy-marker m1))
+ => #<marker at 101 in markers.texi>
+ (eq m1 m2)
+ => nil
+ (equal m1 m2)
+ => t
+
+ ;; When you are finished using a marker, make it point nowhere.
+ (set-marker m1 nil)
+ => #<marker in no buffer>
\1f
-File: lispref.info, Node: Kill Ring Concepts, Next: Kill Functions, Up: The Kill Ring
+File: lispref.info, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers
-Kill Ring Concepts
-------------------
+Predicates on Markers
+=====================
- The kill ring records killed text as strings in a list, most recent
-first. A short kill ring, for example, might look like this:
+ You can test an object to see whether it is a marker, or whether it
+is either an integer or a marker or either an integer, a character, or a
+marker. The latter tests are useful in connection with the arithmetic
+functions that work with any of markers, integers, or characters.
- ("some text" "a different piece of text" "even older text")
+ - Function: markerp object
+ This function returns `t' if OBJECT is a marker, `nil' otherwise.
+ Note that integers are not markers, even though many functions
+ will accept either a marker or an integer.
-When the list reaches `kill-ring-max' entries in length, adding a new
-entry automatically deletes the last entry.
+ - Function: integer-or-marker-p object
+ This function returns `t' if OBJECT is an integer or a marker,
+ `nil' otherwise.
- When kill commands are interwoven with other commands, each kill
-command makes a new entry in the kill ring. Multiple kill commands in
-succession build up a single entry in the kill ring, which would be
-yanked as a unit; the second and subsequent consecutive kill commands
-add text to the entry made by the first one.
+ - Function: integer-char-or-marker-p object
+ This function returns `t' if OBJECT is an integer, a character, or
+ a marker, `nil' otherwise.
- For yanking, one entry in the kill ring is designated the "front" of
-the ring. Some yank commands "rotate" the ring by designating a
-different element as the "front." But this virtual rotation doesn't
-change the list itself--the most recent entry always comes first in the
-list.
+ - Function: number-or-marker-p object
+ This function returns `t' if OBJECT is a number (either kind) or a
+ marker, `nil' otherwise.
-\1f
-File: lispref.info, Node: Kill Functions, Next: Yank Commands, Prev: Kill Ring Concepts, Up: The Kill Ring
-
-Functions for Killing
----------------------
-
- `kill-region' is the usual subroutine for killing text. Any command
-that calls this function is a "kill command" (and should probably have
-`kill' in its name). `kill-region' puts the newly killed text in a new
-element at the beginning of the kill ring or adds it to the most recent
-element. It uses the `last-command' variable to determine whether the
-previous command was a kill command, and if so appends the killed text
-to the most recent entry.
-
- - Command: kill-region START END
- This function kills the text in the region defined by START and
- END. The text is deleted but saved in the kill ring, along with
- its text properties. The value is always `nil'.
-
- In an interactive call, START and END are point and the mark.
-
- If the buffer is read-only, `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.
-
- - Command: copy-region-as-kill START END
- This command saves the region defined by START and END on the kill
- ring (including text properties), but does not delete the text
- from the buffer. It returns `nil'. It also indicates the extent
- of the text copied by moving the cursor momentarily, or by
- displaying a message in the echo area.
-
- The command does not set `this-command' to `kill-region', so a
- subsequent kill command does not append to the same kill ring
- entry.
-
- Don't call `copy-region-as-kill' in Lisp programs unless you aim to
- support Emacs 18. For Emacs 19, it is better to use `kill-new' or
- `kill-append' instead. *Note Low-Level Kill Ring::.
+ - Function: number-char-or-marker-p object
+ This function returns `t' if OBJECT is a number (either kind), a
+ character, or a marker, `nil' otherwise.
\1f
-File: lispref.info, Node: Yank Commands, Next: Low-Level Kill Ring, Prev: Kill Functions, Up: The Kill Ring
-
-Functions for Yanking
----------------------
-
- "Yanking" means reinserting an entry of previously killed text from
-the kill ring. The text properties are copied too.
+File: lispref.info, Node: Creating Markers, Next: Information from Markers, Prev: Predicates on Markers, Up: Markers
- - Command: yank &optional ARG
- This command inserts before point the text in the first entry in
- the kill ring. It positions the mark at the beginning of that
- text, and point at the end.
+Functions That Create Markers
+=============================
- If ARG is a list (which occurs interactively when the user types
- `C-u' with no digits), then `yank' inserts the text as described
- above, but puts point before the yanked text and puts the mark
- after it.
+ When you create a new marker, you can make it point nowhere, or point
+to the present position of point, or to the beginning or end of the
+accessible portion of the buffer, or to the same place as another given
+marker.
+
+ - Function: make-marker
+ This functions returns a newly created marker that does not point
+ anywhere.
+
+ (make-marker)
+ => #<marker in no buffer>
+
+ - Function: point-marker &optional dont-copy-p buffer
+ This function returns a marker that points to the present position
+ of point in BUFFER, which defaults to the current buffer. *Note
+ Point::. For an example, see `copy-marker', below.
+
+ Internally, a marker corresponding to point is always maintained.
+ Normally the marker returned by `point-marker' is a copy; you may
+ modify it with reckless abandon. However, if optional argument
+ DONT-COPY-P is non-`nil', then the real point-marker is returned;
+ modifying the position of this marker will move point. It is
+ illegal to change the buffer of it, or make it point nowhere.
+
+ - Function: point-min-marker &optional buffer
+ This function returns a new marker that points to the beginning of
+ the accessible portion of BUFFER, which defaults to the current
+ buffer. This will be the beginning of the buffer unless narrowing
+ is in effect. *Note Narrowing::.
+
+ - Function: point-max-marker &optional buffer
+ This function returns a new marker that points to the end of the
+ accessible portion of BUFFER, which defaults to the current
+ buffer. This will be the end of the buffer unless narrowing is in
+ effect. *Note Narrowing::.
+
+ Here are examples of this function and `point-min-marker', shown in
+ a buffer containing a version of the source file for the text of
+ this chapter.
+
+ (point-min-marker)
+ => #<marker at 1 in markers.texi>
+ (point-max-marker)
+ => #<marker at 15573 in markers.texi>
+
+ (narrow-to-region 100 200)
+ => nil
+ (point-min-marker)
+ => #<marker at 100 in markers.texi>
+ (point-max-marker)
+ => #<marker at 200 in markers.texi>
+
+ - Function: copy-marker marker-or-integer &optional marker-type
+ If passed a marker as its argument, `copy-marker' returns a new
+ marker that points to the same place and the same buffer as does
+ MARKER-OR-INTEGER. If passed an integer as its argument,
+ `copy-marker' returns a new marker that points to position
+ MARKER-OR-INTEGER in the current buffer.
+
+ If passed an integer argument less than 1, `copy-marker' returns a
+ new marker that points to the beginning of the current buffer. If
+ passed an integer argument greater than the length of the buffer,
+ `copy-marker' returns a new marker that points to the end of the
+ buffer.
+
+ An error is signaled if MARKER-OR-INTEGER is neither a marker nor
+ an integer.
+
+ Optional second argument MARKER-TYPE specifies the insertion type
+ of the new marker; see `marker-insertion-type'.
+
+ (setq p (point-marker))
+ => #<marker at 2139 in markers.texi>
+
+ (setq q (copy-marker p))
+ => #<marker at 2139 in markers.texi>
+
+ (eq p q)
+ => nil
+
+ (equal p q)
+ => t
+
+ (point)
+ => 2139
+
+ (set-marker p 3000)
+ => #<marker at 3000 in markers.texi>
+
+ (point)
+ => 2139
+
+ (setq p (point-marker t))
+ => #<marker at 2139 in markers.texi>
+
+ (set-marker p 3000)
+ => #<marker at 3000 in markers.texi>
+
+ (point)
+ => 3000
+
+ (copy-marker 0)
+ => #<marker at 1 in markers.texi>
+
+ (copy-marker 20000)
+ => #<marker at 7572 in markers.texi>
- If ARG is a number, then `yank' inserts the ARGth most recently
- killed text--the ARGth element of the kill ring list.
+\1f
+File: lispref.info, Node: Information from Markers, Next: Changing Markers, Prev: Creating Markers, Up: Markers
- `yank' does not alter the contents of the kill ring or rotate it.
- It returns `nil'.
+Information from Markers
+========================
- - Command: yank-pop ARG
- This command replaces the just-yanked entry from the kill ring
- with a different entry from the kill ring.
+ This section describes the functions for accessing the components of
+a marker object.
- This is allowed only immediately after a `yank' or another
- `yank-pop'. At such a time, the region contains text that was just
- inserted by yanking. `yank-pop' deletes that text and inserts in
- its place a different piece of killed text. It does not add the
- deleted text to the kill ring, since it is already in the kill
- ring somewhere.
+ - Function: marker-position marker
+ This function returns the position that MARKER points to, or `nil'
+ if it points nowhere.
- If ARG is `nil', then the replacement text is the previous element
- of the kill ring. If ARG is numeric, the replacement is the ARGth
- previous kill. If ARG is negative, a more recent kill is the
- replacement.
+ - Function: marker-buffer marker
+ This function returns the buffer that MARKER points into, or `nil'
+ if it points nowhere.
- The sequence of kills in the kill ring wraps around, so that after
- the oldest one comes the newest one, and before the newest one
- goes the oldest.
+ (setq m (make-marker))
+ => #<marker in no buffer>
+ (marker-position m)
+ => nil
+ (marker-buffer m)
+ => nil
+
+ (set-marker m 3770 (current-buffer))
+ => #<marker at 3770 in markers.texi>
+ (marker-buffer m)
+ => #<buffer markers.texi>
+ (marker-position m)
+ => 3770
- The value is always `nil'.
+ Two distinct markers are considered `equal' (even though not `eq')
+to each other if they have the same position and buffer, or if they
+both point nowhere.
\1f
-File: lispref.info, Node: Low-Level Kill Ring, Next: Internals of Kill Ring, Prev: Yank Commands, Up: The Kill Ring
-
-Low-Level Kill Ring
--------------------
-
- These functions and variables provide access to the kill ring at a
-lower level, but still convenient for use in Lisp programs. They take
-care of interaction with X Window selections. They do not exist in
-Emacs version 18.
-
- - Function: current-kill N &optional DO-NOT-MOVE
- The function `current-kill' rotates the yanking pointer which
- designates the "front" of the kill ring by N places (from newer
- kills to older ones), and returns the text at that place in the
- ring.
-
- If the optional second argument DO-NOT-MOVE is non-`nil', then
- `current-kill' doesn't alter the yanking pointer; it just returns
- the Nth kill, counting from the current yanking pointer.
-
- If N is zero, indicating a request for the latest kill,
- `current-kill' calls the value of `interprogram-paste-function'
- (documented below) before consulting the kill ring.
-
- - Function: kill-new STRING
- This function puts the text STRING into the kill ring as a new
- entry at the front of the ring. It discards the oldest entry if
- appropriate. It also invokes the value of
- `interprogram-cut-function' (see below).
-
- - Function: kill-append STRING BEFORE-P
- This function appends the text STRING to the first entry in the
- kill ring. Normally STRING goes at the end of the entry, but if
- BEFORE-P is non-`nil', it goes at the beginning. This function
- also invokes the value of `interprogram-cut-function' (see below).
-
- - Variable: interprogram-paste-function
- This variable provides a way of transferring killed text from other
- programs, when you are using a window system. Its value should be
- `nil' or a function of no arguments.
-
- If the value is a function, `current-kill' calls it to get the
- "most recent kill". If the function returns a non-`nil' value,
- then that value is used as the "most recent kill". If it returns
- `nil', then the first element of `kill-ring' is used.
-
- The normal use of this hook is to get the X server's primary
- selection as the most recent kill, even if the selection belongs
- to another X client. *Note X Selections::.
-
- - Variable: interprogram-cut-function
- This variable provides a way of communicating killed text to other
- programs, when you are using a window system. Its value should be
- `nil' or a function of one argument.
-
- If the value is a function, `kill-new' and `kill-append' call it
- with the new first element of the kill ring as an argument.
-
- The normal use of this hook is to set the X server's primary
- selection to the newly killed text.
+File: lispref.info, Node: Changing Markers, Next: The Mark, Prev: Information from Markers, Up: Markers
+
+Changing Marker Positions
+=========================
+
+ This section describes how to change the position of an existing
+marker. When you do this, be sure you know whether the marker is used
+outside of your program, and, if so, what effects will result from
+moving it--otherwise, confusing things may happen in other parts of
+Emacs.
+
+ - Function: set-marker marker position &optional buffer
+ This function moves MARKER to POSITION in BUFFER. If BUFFER is
+ not provided, it defaults to the current buffer.
+
+ POSITION can be a marker, an integer or `nil'. If POSITION is an
+ integer, `set-marker' moves MARKER to point before the POSITIONth
+ character in BUFFER. If POSITION is `nil', MARKER is made to
+ point nowhere. Then it no longer slows down editing in any
+ buffer. If POSITION is less than 1, MARKER is moved to the
+ beginning of BUFFER. If POSITION is greater than the size of
+ BUFFER, MARKER is moved to the end of BUFFER.
+
+ The value returned is MARKER.
+
+ (setq m (point-marker))
+ => #<marker at 4714 in markers.texi>
+ (set-marker m 55)
+ => #<marker at 55 in markers.texi>
+ (setq b (get-buffer "foo"))
+ => #<buffer foo>
+ (set-marker m 0 b)
+ => #<marker at 1 in foo>
+
+ - Function: move-marker marker position &optional buffer
+ This is another name for `set-marker'.
\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.
+File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers
+
+The Mark
+========
+
+ One special marker in each buffer is designated "the mark". It
+records a position for the user for the sake of commands such as `C-w'
+and `C-x <TAB>'. Lisp programs should set the mark only to values that
+have a potential use to the user, and never for their own internal
+purposes. For example, the `replace-regexp' command sets the mark to
+the value of point before doing any replacements, because this enables
+the user to move back there conveniently after the replace is finished.
+
+ Once the mark "exists" in a buffer, it normally never ceases to
+exist. However, it may become "inactive", and usually does so after
+each command (other than simple motion commands and some commands that
+explicitly activate the mark). When the mark is active, the region
+between point and the mark is called the "active region" and is
+highlighted specially.
+
+ Many commands are designed so that when called interactively they
+operate on the text between point and the mark. Such commands work
+only when an active region exists, i.e. when the mark is active. (The
+reason for this is to prevent you from accidentally deleting or
+changing large chunks of your text.) If you are writing such a command,
+don't examine the mark directly; instead, use `interactive' with the
+`r' specification. This provides the values of point and the mark as
+arguments to the command in an interactive call, but permits other Lisp
+programs to specify arguments explicitly, and automatically signals an
+error if the command is called interactively when no active region
+exists. *Note Interactive Codes::.
+
+ Each buffer has its own value of the mark that is independent of the
+value of the mark in other buffers. (When a buffer is created, the mark
+exists but does not point anywhere. We consider this state as "the
+absence of a mark in that buffer.") However, only one active region can
+exist at a time. Activating the mark in one buffer automatically
+deactivates an active mark in any other buffer. Note that the user can
+explicitly activate a mark at any time by using the command
+`activate-region' (normally bound to `M-C-z') or by using the command
+`exchange-point-and-mark' (normally bound to `C-x C-x'), which has the
+side effect of activating the mark.
+
+ Some people do not like active regions, so they disable this behavior
+by setting the variable `zmacs-regions' to `nil'. This makes the mark
+always active (except when a buffer is just created and the mark points
+nowhere), and turns off the highlighting of the region between point
+and the mark. Commands that explicitly retrieve the value of the mark
+should make sure that they behave correctly and consistently
+irrespective of the setting of `zmacs-regions'; some primitives are
+provided to ensure this behavior.
+
+ In addition to the mark, each buffer has a "mark ring" which is a
+list of markers containing previous values of the mark. When editing
+commands change the mark, they should normally save the old value of the
+mark on the mark ring. The variable `mark-ring-max' specifies the
+maximum number of entries in the mark ring; once the list becomes this
+long, adding a new element deletes the last element.
+
+ - Function: mark &optional force buffer
+ This function returns BUFFER's mark position as an integer.
+ BUFFER defaults to the current buffer if omitted.
+
+ If the mark is inactive, `mark' normally returns `nil'. However,
+ if FORCE is non-`nil', then `mark' returns the mark position
+ anyway--or `nil', if the mark is not yet set for the buffer.
+
+ (Remember that if ZMACS-REGIONS is `nil', the mark is always
+ active as long as it exists, and the FORCE argument will have no
+ effect.)
+
+ If you are using this in an editing command, you are most likely
+ making a mistake; see the documentation of `set-mark' below.
+
+ - Function: mark-marker &optional force buffer
+ This function returns BUFFER's mark. BUFFER defaults to the
+ current buffer if omitted. This is the very marker that records
+ the mark location inside XEmacs, not a copy. Therefore, changing
+ this marker's position will directly affect the position of the
+ mark. Don't do it unless that is the effect you want.
+
+ If the mark is inactive, `mark-marker' normally returns `nil'.
+ However, if FORCE is non-`nil', then `mark-marker' returns the
+ mark anyway.
+ (setq m (mark-marker))
+ => #<marker at 3420 in markers.texi>
+ (set-marker m 100)
+ => #<marker at 100 in markers.texi>
+ (mark-marker)
+ => #<marker at 100 in markers.texi>
+
+ Like any marker, this marker can be set to point at any buffer you
+ like. We don't recommend that you make it point at any buffer
+ other than the one of which it is the mark. If you do, it will
+ yield perfectly consistent, but rather odd, results.
+
+ - Function: set-mark position &optional buffer
+ This function sets `buffer''s mark to POSITION, and activates the
+ mark. BUFFER defaults to the current buffer if omitted. The old
+ value of the mark is _not_ pushed onto the mark ring.
+
+ *Please note:* Use this function only if you want the user to see
+ that the mark has moved, and you want the previous mark position to
+ be lost. Normally, when a new mark is set, the old one should go
+ on the `mark-ring'. For this reason, most applications should use
+ `push-mark' and `pop-mark', not `set-mark'.
+
+ Novice XEmacs Lisp programmers often try to use the mark for the
+ wrong purposes. The mark saves a location for the user's
+ convenience. An editing command should not alter the mark unless
+ altering the mark is part of the user-level functionality of the
+ command. (And, in that case, this effect should be documented.)
+ To remember a location for internal use in the Lisp program, store
+ it in a Lisp variable. For example:
+
+ (let ((start (point)))
+ (forward-line 1)
+ (delete-region start (point))).
+
+ - Command: exchange-point-and-mark &optional dont-activate-region
+ This function exchanges the positions of point and the mark. It
+ is intended for interactive use. The mark is also activated
+ unless DONT-ACTIVATE-REGION is non-`nil'.
+
+ - Function: push-mark &optional position nomsg activate buffer
+ This function sets BUFFER's mark to POSITION, and pushes a copy of
+ the previous mark onto `mark-ring'. BUFFER defaults to the
+ current buffer if omitted. If POSITION is `nil', then the value
+ of point is used. `push-mark' returns `nil'.
+
+ If the last global mark pushed was not in BUFFER, also push
+ POSITION on the global mark ring (see below).
+
+ The function `push-mark' normally _does not_ activate the mark.
+ To do that, specify `t' for the argument ACTIVATE.
+
+ A `Mark set' message is displayed unless NOMSG is non-`nil'.
+
+ - Function: pop-mark
+ This function pops off the top element of `mark-ring' and makes
+ that mark become the buffer's actual mark. This does not move
+ point in the buffer, and it does nothing if `mark-ring' is empty.
+ It deactivates the mark.
+
+ The return value is not meaningful.
+
+ - Variable: mark-ring
+ The value of this buffer-local variable is the list of saved former
+ marks of the current buffer, most recent first.
+
+ mark-ring
+ => (#<marker at 11050 in markers.texi>
+ #<marker at 10832 in markers.texi>
+ ...)
+
+ - User Option: mark-ring-max
+ The value of this variable is the maximum size of `mark-ring'. If
+ more marks than this are pushed onto the `mark-ring', `push-mark'
+ discards an old mark when it adds a new one.
+
+ In additional to a per-buffer mark ring, there is a "global mark
+ring". Marks are pushed onto the global mark ring the first time you
+set a mark after switching buffers.
+
+ - Variable: global-mark-ring
+ The value of this variable is the list of saved former global
+ marks, most recent first.
+
+ - User Option: mark-ring-max
+ The value of this variable is the maximum size of
+ `global-mark-ring'. If more marks than this are pushed onto the
+ `global-mark-ring', `push-mark' discards an old mark when it adds
+ a new one.
+
+ - Command: pop-global-mark
+ This function pops a mark off the global mark ring and jumps to
+ that location.
\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.
+File: lispref.info, Node: The Region, Prev: The Mark, Up: Markers
+
+The Region
+==========
+
+ The text between point and the mark is known as "the region".
+Various functions operate on text delimited by point and the mark, but
+only those functions specifically related to the region itself are
+described here.
+
+ When `zmacs-regions' is non-`nil' (this is the default), the concept
+of an "active region" exists. The region is active when the
+corresponding mark is active. Note that only one active region at a
+time can exist--i.e. only one buffer's region is active at a time.
+*Note The Mark::, for more information about active regions.
+
+ - User Option: zmacs-regions
+ If non-`nil' (the default), active regions are used. *Note The
+ Mark::, for a detailed explanation of what this means.
+
+ A number of functions are provided for explicitly determining the
+bounds of the region and whether it is active. Few programs need to use
+these functions, however. A command designed to operate on a region
+should normally use `interactive' with the `r' specification to find
+the beginning and end of the region. This lets other Lisp programs
+specify the bounds explicitly as arguments and automatically respects
+the user's setting for ZMACS-REGIONS. (*Note Interactive Codes::.)
+
+ - Function: region-beginning &optional buffer
+ This function returns the position of the beginning of BUFFER's
+ region (as an integer). This is the position of either point or
+ the mark, whichever is smaller. BUFFER defaults to the current
+ buffer if omitted.
-\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.
+ If the mark does not point anywhere, an error is signaled. Note
+ that this function ignores whether the region is active.
+
+ - Function: region-end &optional buffer
+ This function returns the position of the end of BUFFER's region
+ (as an integer). This is the position of either point or the mark,
+ whichever is larger. BUFFER defaults to the current buffer if
+ omitted.
+
+ If the mark does not point anywhere, an error is signaled. Note
+ that this function ignores whether the region is active.
+
+ - Function: region-exists-p
+ This function is non-`nil' if the region exists. If active regions
+ are in use (i.e. `zmacs-regions' is true), this means that the
+ region is active. Otherwise, this means that the user has pushed
+ a mark in this buffer at some point in the past. If this function
+ returns `nil', a function that uses the `r' interactive
+ specification will cause an error when called interactively.
+
+ - Function: region-active-p
+ If `zmacs-regions' is true, this is equivalent to
+ `region-exists-p'. Otherwise, this function always returns false.
+ This function is used by commands such as
+ `fill-paragraph-or-region' and `capitalize-region-or-word', which
+ operate either on the active region or on something else (e.g. the
+ word or paragraph at point).
+
+ - Variable: zmacs-region-stays
+ If a command sets this variable to true, the currently active
+ region will remain activated when the command finishes. (Normally
+ the region is deactivated when each command terminates.) If
+ ZMACS-REGIONS is false, however, this has no effect. Under normal
+ circumstances, you do not need to set this; use the interactive
+ specification `_' instead, if you want the region to remain active.
+
+ - Function: zmacs-activate-region
+ This function activates the region in the current buffer (this is
+ equivalent to activating the current buffer's mark). This will
+ normally also highlight the text in the active region and set
+ ZMACS-REGION-STAYS to `t'. (If ZMACS-REGIONS is false, however,
+ this function has no effect.)
+
+ - Function: zmacs-deactivate-region
+ This function deactivates the region in the current buffer (this is
+ equivalent to deactivating the current buffer's mark). This will
+ normally also unhighlight the text in the active region and set
+ ZMACS-REGION-STAYS to `nil'. (If ZMACS-REGIONS is false, however,
+ this function has no effect.)
+
+ - Function: zmacs-update-region
+ This function updates the active region, if it's currently active.
+ (If there is no active region, this function does nothing.) This
+ has the effect of updating the highlighting on the text in the
+ region; but you should never need to call this except under rather
+ strange circumstances. The command loop automatically calls it
+ when appropriate. Calling this function will call the hook
+ `zmacs-update-region-hook', if the region is active.
+
+ - Variable: zmacs-activate-region-hook
+ This normal hook is called when a region becomes active. (Usually
+ this happens as a result of a command that activates the region,
+ such as `set-mark-command', `activate-region', or
+ `exchange-point-and-mark'.) Note that calling
+ `zmacs-activate-region' will call this hook, even if the region is
+ already active. If ZMACS-REGIONS is false, however, this hook
+ will never get called under any circumstances.
+
+ - Variable: zmacs-deactivate-region-hook
+ This normal hook is called when an active region becomes inactive.
+ (Calling `zmacs-deactivate-region' when the region is inactive will
+ _not_ cause this hook to be called.) If ZMACS-REGIONS is false,
+ this hook will never get called.
+
+ - Variable: zmacs-update-region-hook
+ This normal hook is called when an active region is "updated" by
+ `zmacs-update-region'. This normally gets called at the end of
+ each command that sets ZMACS-REGION-STAYS to `t', indicating that
+ the region should remain activated. The motion commands do this.
\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.
+File: lispref.info, Node: Text, Next: Searching and Matching, Prev: Markers, Up: Top
+
+Text
+****
+
+ 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 (*note
+Undo::).
+
+ Many text-related functions operate on a region of text defined by
+two buffer positions passed in arguments named START and END. These
+arguments should be either markers (*note Markers::) or numeric
+character positions (*note Positions::). The order of these arguments
+does not matter; it is all right for START to be the end of the region
+and END the beginning. For example, `(delete-region 1 10)' and
+`(delete-region 10 1)' are equivalent. An `args-out-of-range' error is
+signaled if either START or END is outside the accessible portion of
+the buffer. In an interactive call, point and the mark are used for
+these arguments.
+
+ Throughout this chapter, "text" refers to the characters in the
+buffer, together with their properties (when relevant).
-\1f
-File: lispref.info, Node: Margins, Next: Auto Filling, Prev: Filling, Up: Text
+* Menu:
-Margins for Filling
-===================
+* Near Point:: Examining text in the vicinity of point.
+* Buffer Contents:: Examining text in a general fashion.
+* Comparing Text:: Comparing substrings of buffers.
+* Insertion:: Adding new text to a buffer.
+* Commands for Insertion:: User-level commands to insert text.
+* Deletion:: Removing text from a buffer.
+* User-Level Deletion:: User-level commands to delete text.
+* The Kill Ring:: Where removed text sometimes is saved for later use.
+* Undo:: Undoing changes to the text of a buffer.
+* Maintaining Undo:: How to enable and disable undo information.
+ How to control how much information is kept.
+* Filling:: Functions for explicit filling.
+* Margins:: How to specify margins for filling commands.
+* Auto Filling:: How auto-fill mode is implemented to break lines.
+* Sorting:: Functions for sorting parts of the buffer.
+* Columns:: Computing horizontal positions, and using them.
+* Indentation:: Functions to insert or adjust indentation.
+* Case Changes:: Case conversion of parts of the buffer.
+* Text Properties:: Assigning Lisp property lists to text characters.
+* Substitution:: Replacing a given character wherever it appears.
+* Registers:: How registers are implemented. Accessing the text or
+ position stored in a register.
+* Transposition:: Swapping two portions of a buffer.
+* Change Hooks:: Supplying functions to be run when text is changed.
+* Transformations:: MD5 and base64 support.
- - 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: Near Point, Next: Buffer Contents, Up: Text
+
+Examining Text Near Point
+=========================
+
+ Many functions are provided to look at the characters around point.
+Several simple functions are described here. See also `looking-at' in
+*Note Regexp Search::.
+
+ Many of these functions take an optional BUFFER argument. In all
+such cases, the current buffer will be used if this argument is
+omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions
+usually did not have these optional BUFFER arguments and always
+operated on the current buffer.)
+
+ - Function: char-after &optional position buffer
+ This function returns the character in the buffer at (i.e.,
+ immediately after) position POSITION. If POSITION is out of range
+ for this purpose, either before the beginning of the buffer, or at
+ or beyond the end, then the value is `nil'. The default for
+ POSITION is point. If optional argument BUFFER is `nil', the
+ current buffer is assumed.
+
+ In the following example, assume that the first character in the
+ buffer is `@':
+
+ (char-to-string (char-after 1))
+ => "@"
+
+ - Function: char-before &optional position buffer
+ This function returns the character in the current buffer
+ immediately before position POSITION. If POSITION is out of range
+ for this purpose, either at or before the beginning of the buffer,
+ or beyond the end, then the value is `nil'. The default for
+ POSITION is point. If optional argument BUFFER is `nil', the
+ current buffer is assumed.
+
+ - Function: following-char &optional buffer
+ This function returns the character following point in the buffer.
+ This is similar to `(char-after (point))'. However, if point is at
+ the end of the buffer, then the result of `following-char' is 0.
+ If optional argument BUFFER is `nil', the current buffer is
+ assumed.
+
+ Remember that point is always between characters, and the terminal
+ cursor normally appears over the character following point.
+ Therefore, the character returned by `following-char' is the
+ character the cursor is over.
+
+ In this example, point is between the `a' and the `c'.
+
+ ---------- Buffer: foo ----------
+ Gentlemen may cry ``Pea-!-ce! Peace!,''
+ but there is no peace.
+ ---------- Buffer: foo ----------
+
+ (char-to-string (preceding-char))
+ => "a"
+ (char-to-string (following-char))
+ => "c"
+
+ - Function: preceding-char &optional buffer
+ This function returns the character preceding point in the buffer.
+ See above, under `following-char', for an example. If point is at
+ the beginning of the buffer, `preceding-char' returns 0. If
+ optional argument BUFFER is `nil', the current buffer is assumed.
+
+ - Function: bobp &optional buffer
+ This function returns `t' if point is at the beginning of the
+ buffer. If narrowing is in effect, this means the beginning of the
+ accessible portion of the text. If optional argument BUFFER is
+ `nil', the current buffer is assumed. See also `point-min' in
+ *Note Point::.
+
+ - Function: eobp &optional buffer
+ This function returns `t' if point is at the end of the buffer.
+ If narrowing is in effect, this means the end of accessible
+ portion of the text. If optional argument BUFFER is `nil', the
+ current buffer is assumed. See also `point-max' in *Note Point::.
+
+ - Function: bolp &optional buffer
+ This function returns `t' if point is at the beginning of a line.
+ If optional argument BUFFER is `nil', the current buffer is
+ assumed. *Note Text Lines::. The beginning of the buffer (or its
+ accessible portion) always counts as the beginning of a line.
+
+ - Function: eolp &optional buffer
+ This function returns `t' if point is at the end of a line. The
+ end of the buffer is always considered the end of a line. If
+ optional argument BUFFER is `nil', the current buffer is assumed.
+ The end of the buffer (or of its accessible portion) is always
+ considered the end of a line.
\1f
-File: lispref.info, Node: Auto Filling, Next: Sorting, Prev: Margins, Up: Text
+File: lispref.info, Node: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text
-Auto Filling
-============
+Examining Buffer Contents
+=========================
- 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::.
+ This section describes two functions that allow a Lisp program to
+convert any portion of the text in the buffer into a string.
- Auto Fill mode also enables the functions that change the margins and
-justification style to refill portions of the text. *Note Margins::.
+ - Function: buffer-substring start end &optional buffer
+ - Function: buffer-string start end &optional buffer
+ These functions are equivalent and return a string containing a
+ copy of the text of the region defined by positions START and END
+ in the buffer. If the arguments are not positions in the
+ accessible portion of the buffer, `buffer-substring' signals an
+ `args-out-of-range' error. If optional argument BUFFER is `nil',
+ the current buffer is assumed.
- - 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.
+ If the region delineated by START and END contains duplicable
+ extents, they will be remembered in the string. *Note Duplicable
+ Extents::.
- 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.
+ It is not necessary for START to be less than END; the arguments
+ can be given in either order. But most often the smaller argument
+ is written first.
- 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.
+ ---------- Buffer: foo ----------
+ This is the contents of buffer foo
+
+ ---------- Buffer: foo ----------
+
+ (buffer-substring 1 10)
+ => "This is t"
+ (buffer-substring (point-max) 10)
+ => "he contents of buffer foo
+ "
+
+\1f
+File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text
+
+Comparing Text
+==============
+
+ This function lets you compare portions of the text in a buffer,
+without copying them into strings first.
+
+ - Function: compare-buffer-substrings buffer1 start1 end1 buffer2
+ start2 end2
+ This function lets you compare two substrings of the same buffer
+ or two different buffers. The first three arguments specify one
+ substring, giving a buffer and two positions within the buffer.
+ The last three arguments specify the other substring in the same
+ way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for
+ the current buffer.
+
+ The value is negative if the first substring is less, positive if
+ the first is greater, and zero if they are equal. The absolute
+ value of the result is one plus the index of the first differing
+ characters within the substrings.
+
+ This function ignores case when comparing characters if
+ `case-fold-search' is non-`nil'. It always ignores text
+ properties.
+
+ Suppose the current buffer contains the text `foobarbar
+ haha!rara!'; then in this example the two substrings are `rbar '
+ and `rara!'. The value is 2 because the first substring is greater
+ at the second character.
+
+ (compare-buffer-substring nil 6 11 nil 16 21)
+ => 2
projects / chise / xemacs-chise.git- / blobdiff