X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-29;h=9e728eb979ad4a4dc06bfb82d6096780d16f6fe4;hb=16d0840d3eada757f529c34fddc0c2fb8f17b9de;hp=0ea1ef61602619d125a2ba42ca9835ea757b4d9f;hpb=376658ea71d16dced8acff36c3e385ac3738d868;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-29 b/info/lispref.info-29 index 0ea1ef6..9e728eb 100644 --- a/info/lispref.info-29 +++ b/info/lispref.info-29 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 3.12s from +This is ../info/lispref.info, produced by makeinfo version 4.0b from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,947 +50,1112 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -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. - - -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'. - - -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::. + +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. + +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 + (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 ---------- - When in the course of human-!- events, it becomes necessary + This is the contents of bar + This is the contents of bar + This is the contents of foo-!- ---------- 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 `('. - - ---------- Buffer: foo ---------- - This has too many -!-spaces - This has too many spaces at the start of (-!- this list) - ---------- 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 ---------- + +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''.  -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)) + => # + + ;; Set `m1' to point between the 99th and 100th characters + ;; in the current buffer: + (set-marker m1 100) + => # + + ;; Now insert one character at the beginning of the buffer: + (goto-char (point-min)) + => 1 + (insert "Q") + => nil + + ;; `m1' is updated appropriately. + m1 + => # + + ;; Two markers that point to the same position + ;; are not `eq', but they are `equal'. + (setq m2 (copy-marker m1)) + => # + (eq m1 m2) + => nil + (equal m1 m2) + => t + + ;; When you are finished using a marker, make it point nowhere. + (set-marker m1 nil) + => #  -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. - -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.  -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) + => # + + - 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) + => # + (point-max-marker) + => # + + (narrow-to-region 100 200) + => nil + (point-min-marker) + => # + (point-max-marker) + => # + + - 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)) + => # + + (setq q (copy-marker p)) + => # + + (eq p q) + => nil + + (equal p q) + => t + + (point) + => 2139 + + (set-marker p 3000) + => # + + (point) + => 2139 + + (setq p (point-marker t)) + => # + + (set-marker p 3000) + => # + + (point) + => 3000 + + (copy-marker 0) + => # + + (copy-marker 20000) + => # - If ARG is a number, then `yank' inserts the ARGth most recently - killed text--the ARGth element of the kill ring list. + +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-position m) + => nil + (marker-buffer m) + => nil + + (set-marker m 3770 (current-buffer)) + => # + (marker-buffer m) + => # + (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.  -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)) + => # + (set-marker m 55) + => # + (setq b (get-buffer "foo")) + => # + (set-marker m 0 b) + => # + + - Function: move-marker marker position &optional buffer + This is another name for `set-marker'.  -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 '. 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)) + => # + (set-marker m 100) + => # + (mark-marker) + => # + + 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 + => (# + # + ...) + + - 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.  -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. - -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.  -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). - -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, indents to this column. This variable - automatically becomes buffer-local when set in any fashion. + +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.  -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 + " + + +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