X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-30;h=304d0e2692740ea21b4f59ea2d0f7113d70f5daf;hb=b5f26301ee1ad7dbc9ad1c22e5b8564b5161d9ad;hp=308e0ad0e0ae400726e2e210a9eb96604c9833dd;hpb=376658ea71d16dced8acff36c3e385ac3738d868;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-30 b/info/lispref.info-30 index 308e0ad..304d0e2 100644 --- a/info/lispref.info-30 +++ b/info/lispref.info-30 @@ -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,1126 +50,1045 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Sorting, Next: Columns, Prev: Auto Filling, Up: Text - -Sorting Text -============ - - The sorting functions described in this section all rearrange text in -a buffer. This is in contrast to the function `sort', which rearranges -the order of the elements of a list (*note Rearrangement::). The -values returned by these functions are not meaningful. - - - Function: sort-subr reverse nextrecfun endrecfun &optional - startkeyfun endkeyfun - This function is the general text-sorting routine that divides a - buffer into records and sorts them. Most of the commands in this - section use this function. - - To understand how `sort-subr' works, consider the whole accessible - portion of the buffer as being divided into disjoint pieces called - "sort records". The records may or may not be contiguous; they may - not overlap. A portion of each sort record (perhaps all of it) is - designated as the sort key. Sorting rearranges the records in - order by their sort keys. - - Usually, the records are rearranged in order of ascending sort key. - If the first argument to the `sort-subr' function, REVERSE, is - non-`nil', the sort records are rearranged in order of descending - sort key. - - The next four arguments to `sort-subr' are functions that are - called to move point across a sort record. They are called many - times from within `sort-subr'. - - 1. NEXTRECFUN is called with point at the end of a record. This - function moves point to the start of the next record. The - first record is assumed to start at the position of point - when `sort-subr' is called. Therefore, you should usually - move point to the beginning of the buffer before calling - `sort-subr'. - - This function can indicate there are no more sort records by - leaving point at the end of the buffer. - - 2. ENDRECFUN is called with point within a record. It moves - point to the end of the record. - - 3. STARTKEYFUN is called to move point from the start of a - record to the start of the sort key. This argument is - optional; if it is omitted, the whole record is the sort key. - If supplied, the function should either return a non-`nil' - value to be used as the sort key, or return `nil' to indicate - that the sort key is in the buffer starting at point. In the - latter case, ENDKEYFUN is called to find the end of the sort - key. - - 4. ENDKEYFUN is called to move point from the start of the sort - key to the end of the sort key. This argument is optional. - If STARTKEYFUN returns `nil' and this argument is omitted (or - `nil'), then the sort key extends to the end of the record. - There is no need for ENDKEYFUN if STARTKEYFUN returns a - non-`nil' value. - - As an example of `sort-subr', here is the complete function - definition for `sort-lines': - - ;; Note that the first two lines of doc string - ;; are effectively one line when viewed by a user. - (defun sort-lines (reverse beg end) - "Sort lines in region alphabetically. - Called from a program, there are three arguments: - REVERSE (non-nil means reverse order), - and BEG and END (the region to sort)." - (interactive "P\nr") - (save-restriction - (narrow-to-region beg end) - (goto-char (point-min)) - (sort-subr reverse - 'forward-line - 'end-of-line))) - - Here `forward-line' moves point to the start of the next record, - and `end-of-line' moves point to the end of record. We do not pass - the arguments STARTKEYFUN and ENDKEYFUN, because the entire record - is used as the sort key. - - The `sort-paragraphs' function is very much the same, except that - its `sort-subr' call looks like this: - - (sort-subr reverse - (function - (lambda () - (skip-chars-forward "\n \t\f"))) - 'forward-paragraph) - - - Command: sort-regexp-fields reverse record-regexp key-regexp start - end - This command sorts the region between START and END alphabetically - as specified by RECORD-REGEXP and KEY-REGEXP. If REVERSE is a - negative integer, then sorting is in reverse order. - - Alphabetical sorting means that two sort keys are compared by - comparing the first characters of each, the second characters of - each, and so on. If a mismatch is found, it means that the sort - keys are unequal; the sort key whose character is less at the - point of first mismatch is the lesser sort key. The individual - characters are compared according to their numerical values. - Since Emacs uses the ASCII character set, the ordering in that set - determines alphabetical order. - - The value of the RECORD-REGEXP argument specifies how to divide - the buffer into sort records. At the end of each record, a search - is done for this regular expression, and the text that matches it - is the next record. For example, the regular expression `^.+$', - which matches lines with at least one character besides a newline, - would make each such line into a sort record. *Note Regular - Expressions::, for a description of the syntax and meaning of - regular expressions. - - The value of the KEY-REGEXP argument specifies what part of each - record is the sort key. The KEY-REGEXP could match the whole - record, or only a part. In the latter case, the rest of the - record has no effect on the sorted order of records, but it is - carried along when the record moves to its new position. - - The KEY-REGEXP argument can refer to the text matched by a - subexpression of RECORD-REGEXP, or it can be a regular expression - on its own. - - If KEY-REGEXP is: - - `\DIGIT' - then the text matched by the DIGITth `\(...\)' parenthesis - grouping in RECORD-REGEXP is the sort key. - - `\&' - then the whole record is the sort key. - - a regular expression - then `sort-regexp-fields' searches for a match for the regular - expression within the record. If such a match is found, it - is the sort key. If there is no match for KEY-REGEXP within - a record then that record is ignored, which means its - position in the buffer is not changed. (The other records - may move around it.) - - For example, if you plan to sort all the lines in the region by the - first word on each line starting with the letter `f', you should - set RECORD-REGEXP to `^.*$' and set KEY-REGEXP to `\'. The - resulting expression looks like this: - - (sort-regexp-fields nil "^.*$" "\\" - (region-beginning) - (region-end)) - - If you call `sort-regexp-fields' interactively, it prompts for - RECORD-REGEXP and KEY-REGEXP in the minibuffer. - - - Command: sort-lines reverse start end - This command alphabetically sorts lines in the region between - START and END. If REVERSE is non-`nil', the sort is in reverse - order. - - - Command: sort-paragraphs reverse start end - This command alphabetically sorts paragraphs in the region between - START and END. If REVERSE is non-`nil', the sort is in reverse - order. - - - Command: sort-pages reverse start end - This command alphabetically sorts pages in the region between - START and END. If REVERSE is non-`nil', the sort is in reverse - order. - - - Command: sort-fields field start end - This command sorts lines in the region between START and END, - comparing them alphabetically by the FIELDth field of each line. - Fields are separated by whitespace and numbered starting from 1. - If FIELD is negative, sorting is by the -FIELDth field from the - end of the line. This command is useful for sorting tables. - - - Command: sort-numeric-fields field start end - This command sorts lines in the region between START and END, - comparing them numerically by the FIELDth field of each line. The - specified field must contain a number in each line of the region. - Fields are separated by whitespace and numbered starting from 1. - If FIELD is negative, sorting is by the -FIELDth field from the - end of the line. This command is useful for sorting tables. - - - Command: sort-columns reverse &optional beg end - This command sorts the lines in the region between BEG and END, - comparing them alphabetically by a certain range of columns. The - column positions of BEG and END bound the range of columns to sort - on. - - If REVERSE is non-`nil', the sort is in reverse order. - - One unusual thing about this command is that the entire line - containing position BEG, and the entire line containing position - END, are included in the region sorted. - - Note that `sort-columns' uses the `sort' utility program, and so - cannot work properly on text containing tab characters. Use `M-x - `untabify'' to convert tabs to spaces before sorting. - - -File: lispref.info, Node: Columns, Next: Indentation, Prev: Sorting, Up: Text - -Counting Columns -================ - - The column functions convert between a character position (counting -characters from the beginning of the buffer) and a column position -(counting screen characters from the beginning of a line). - - A character counts according to the number of columns it occupies on -the screen. This means control characters count as occupying 2 or 4 -columns, depending upon the value of `ctl-arrow', and tabs count as -occupying a number of columns that depends on the value of `tab-width' -and on the column where the tab begins. *Note Usual Display::. - - Column number computations ignore the width of the window and the -amount of horizontal scrolling. Consequently, a column value can be -arbitrarily high. The first (or leftmost) column is numbered 0. - - - Function: current-column - This function returns the horizontal position of point, measured in - columns, counting from 0 at the left margin. The column position - is the sum of the widths of all the displayed representations of - the characters between the start of the current line and point. - - For an example of using `current-column', see the description of - `count-lines' in *Note Text Lines::. - - - Function: move-to-column column &optional force - This function moves point to COLUMN in the current line. The - calculation of COLUMN takes into account the widths of the - displayed representations of the characters between the start of - the line and point. - - If column COLUMN is beyond the end of the line, point moves to the - end of the line. If COLUMN is negative, point moves to the - beginning of the line. - - If it is impossible to move to column COLUMN because that is in - the middle of a multicolumn character such as a tab, point moves - to the end of that character. However, if FORCE is non-`nil', and - COLUMN is in the middle of a tab, then `move-to-column' converts - the tab into spaces so that it can move precisely to column - COLUMN. Other multicolumn characters can cause anomalies despite - FORCE, since there is no way to split them. - - The argument FORCE also has an effect if the line isn't long - enough to reach column COLUMN; in that case, it says to add - whitespace at the end of the line to reach that column. - - If COLUMN is not an integer, an error is signaled. - - The return value is the column number actually moved to. - - -File: lispref.info, Node: Indentation, Next: Case Changes, Prev: Columns, Up: Text - -Indentation -=========== - - The indentation functions are used to examine, move to, and change -whitespace that is at the beginning of a line. Some of the functions -can also change whitespace elsewhere on a line. Columns and indentation -count from zero at the left margin. - -* Menu: - -* Primitive Indent:: Functions used to count and insert indentation. -* Mode-Specific Indent:: Customize indentation for different modes. -* Region Indent:: Indent all the lines in a region. -* Relative Indent:: Indent the current line based on previous lines. -* Indent Tabs:: Adjustable, typewriter-like tab stops. -* Motion by Indent:: Move to first non-blank character. - - -File: lispref.info, Node: Primitive Indent, Next: Mode-Specific Indent, Up: Indentation - -Indentation Primitives ----------------------- - - This section describes the primitive functions used to count and -insert indentation. The functions in the following sections use these -primitives. - - - Function: current-indentation - This function returns the indentation of the current line, which is - the horizontal position of the first nonblank character. If the - contents are entirely blank, then this is the horizontal position - of the end of the line. - - - Command: indent-to column &optional minimum - This function indents from point with tabs and spaces until COLUMN - is reached. If MINIMUM is specified and non-`nil', then at least - that many spaces are inserted even if this requires going beyond - COLUMN. Otherwise the function does nothing if point is already - beyond COLUMN. The value is the column at which the inserted - indentation ends. - - - User Option: indent-tabs-mode - If this variable is non-`nil', indentation functions can insert - tabs as well as spaces. Otherwise, they insert only spaces. - Setting this variable automatically makes it local to the current - buffer. - - -File: lispref.info, Node: Mode-Specific Indent, Next: Region Indent, Prev: Primitive Indent, Up: Indentation - -Indentation Controlled by Major Mode ------------------------------------- - - An important function of each major mode is to customize the -key to indent properly for the language being edited. This section -describes the mechanism of the key and how to control it. The -functions in this section return unpredictable values. - - - Variable: indent-line-function - This variable's value is the function to be used by (and - various commands) to indent the current line. The command - `indent-according-to-mode' does no more than call this function. - - In Lisp mode, the value is the symbol `lisp-indent-line'; in C - mode, `c-indent-line'; in Fortran mode, `fortran-indent-line'. In - Fundamental mode, Text mode, and many other modes with no standard - for indentation, the value is `indent-to-left-margin' (which is the - default value). - - - Command: indent-according-to-mode - This command calls the function in `indent-line-function' to - indent the current line in a way appropriate for the current major - mode. - - - Command: indent-for-tab-command - This command calls the function in `indent-line-function' to indent - the current line; except that if that function is - `indent-to-left-margin', it calls `insert-tab' instead. (That is - a trivial command that inserts a tab character.) - - - Command: newline-and-indent - This function inserts a newline, then indents the new line (the one - following the newline just inserted) according to the major mode. - - It does indentation by calling the current `indent-line-function'. - In programming language modes, this is the same thing does, - but in some text modes, where inserts a tab, - `newline-and-indent' indents to the column specified by - `left-margin'. - - - Command: reindent-then-newline-and-indent - This command reindents the current line, inserts a newline at - point, and then reindents the new line (the one following the - newline just inserted). - - This command does indentation on both lines according to the - current major mode, by calling the current value of - `indent-line-function'. In programming language modes, this is - the same thing does, but in some text modes, where - inserts a tab, `reindent-then-newline-and-indent' indents to the - column specified by `left-margin'. - - -File: lispref.info, Node: Region Indent, Next: Relative Indent, Prev: Mode-Specific Indent, Up: Indentation - -Indenting an Entire Region --------------------------- - - This section describes commands that indent all the lines in the -region. They return unpredictable values. - - - Command: indent-region start end to-column - This command indents each nonblank line starting between START - (inclusive) and END (exclusive). If TO-COLUMN is `nil', - `indent-region' indents each nonblank line by calling the current - mode's indentation function, the value of `indent-line-function'. - - If TO-COLUMN is non-`nil', it should be an integer specifying the - number of columns of indentation; then this function gives each - line exactly that much indentation, by either adding or deleting - whitespace. - - If there is a fill prefix, `indent-region' indents each line by - making it start with the fill prefix. - - - Variable: indent-region-function - The value of this variable is a function that can be used by - `indent-region' as a short cut. You should design the function so - that it will produce the same results as indenting the lines of the - region one by one, but presumably faster. +File: lispref.info, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text + +Inserting Text +============== + + "Insertion" means adding new text to a buffer. The inserted text +goes at point--between the character before point and the character +after point. + + Insertion relocates markers that point at positions after the +insertion point, so that they stay with the surrounding text (*note +Markers::). When a marker points at the place of insertion, insertion +normally doesn't relocate the marker, so that it points to the +beginning of the inserted text; however, certain special functions such +as `insert-before-markers' relocate such markers to point after the +inserted text. + + Some insertion functions leave point before the inserted text, while +other functions leave it after. We call the former insertion "after +point" and the latter insertion "before point". + + If a string with non-`nil' extent data is inserted, the remembered +extents will also be inserted. *Note Duplicable Extents::. + + Insertion functions signal an error if the current buffer is +read-only. + + These functions copy text characters from strings and buffers along +with their properties. The inserted characters have exactly the same +properties as the characters they were copied from. By contrast, +characters specified as separate arguments, not part of a string or +buffer, inherit their text properties from the neighboring text. + + - Function: insert &rest args + This function inserts the strings and/or characters ARGS into the + current buffer, at point, moving point forward. In other words, it + inserts the text before point. An error is signaled unless all + ARGS are either strings or characters. The value is `nil'. + + - Function: insert-before-markers &rest args + This function inserts the strings and/or characters ARGS into the + current buffer, at point, moving point forward. An error is + signaled unless all ARGS are either strings or characters. The + value is `nil'. - If the value is `nil', there is no short cut, and `indent-region' - actually works line by line. + This function is unlike the other insertion functions in that it + relocates markers initially pointing at the insertion point, to + point after the inserted text. - A short-cut function is useful in modes such as C mode and Lisp - mode, where the `indent-line-function' must scan from the - beginning of the function definition: applying it to each line - would be quadratic in time. The short cut can update the scan - information as it moves through the lines indenting them; this - takes linear time. In a mode where indenting a line individually - is fast, there is no need for a short cut. + - Function: insert-string string &optional buffer + This function inserts STRING into BUFFER before point. BUFFER + defaults to the current buffer if omitted. This function is + chiefly useful if you want to insert a string in a buffer other + than the current one (otherwise you could just use `insert'). - `indent-region' with a non-`nil' argument TO-COLUMN has a - different meaning and does not use this variable. + - Function: insert-char character &optional count ignored buffer + This function inserts COUNT instances of CHARACTER into BUFFER + before point. COUNT must be a number, and CHARACTER must be a + character. - - Command: indent-rigidly start end count - This command indents all lines starting between START (inclusive) - and END (exclusive) sideways by COUNT columns. This "preserves - the shape" of the affected region, moving it as a rigid unit. - Consequently, this command is useful not only for indenting - regions of unindented text, but also for indenting regions of - formatted code. + If optional argument BUFFER is `nil', the current buffer is + assumed. (In FSF Emacs, the third argument is called INHERIT and + refers to text properties. In XEmacs, it is always ignored.) - For example, if COUNT is 3, this command adds 3 columns of - indentation to each of the lines beginning in the region specified. + This function always returns `nil'. - In Mail mode, `C-c C-y' (`mail-yank-original') uses - `indent-rigidly' to indent the text copied from the message being - replied to. + - Function: insert-buffer-substring from-buffer-or-name &optional + start end + This function inserts a portion of buffer FROM-BUFFER-OR-NAME + (which must already exist) into the current buffer before point. + The text inserted is the region from START and END. (These + arguments default to the beginning and end of the accessible + portion of that buffer.) This function returns `nil'. - - Function: indent-code-rigidly start end columns &optional - nochange-regexp - This is like `indent-rigidly', except that it doesn't alter lines - that start within strings or comments. + In this example, the form is executed with buffer `bar' as the + current buffer. We assume that buffer `bar' is initially empty. - In addition, it doesn't alter a line if NOCHANGE-REGEXP matches at - the beginning of the line (if NOCHANGE-REGEXP is non-`nil'). + ---------- Buffer: foo ---------- + We hold these truths to be self-evident, that all + ---------- Buffer: foo ---------- + + (insert-buffer-substring "foo" 1 20) + => nil + + ---------- Buffer: bar ---------- + We hold these truth-!- + ---------- Buffer: bar ----------  -File: lispref.info, Node: Relative Indent, Next: Indent Tabs, Prev: Region Indent, Up: Indentation +File: lispref.info, Node: Commands for Insertion, Next: Deletion, Prev: Insertion, Up: Text -Indentation Relative to Previous Lines --------------------------------------- +User-Level Insertion Commands +============================= - This section describes two commands that indent the current line -based on the contents of previous lines. + This section describes higher-level commands for inserting text, +commands intended primarily for the user but useful also in Lisp +programs. - - Command: indent-relative &optional unindented-ok - This command inserts whitespace at point, extending to the same - column as the next "indent point" of the previous nonblank line. - An indent point is a non-whitespace character following - whitespace. The next indent point is the first one at a column - greater than the current column of point. For example, if point - is underneath and to the left of the first non-blank character of - a line of text, it moves to that column by inserting whitespace. + - 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'. - If the previous nonblank line has no next indent point (i.e., none - at a great enough column position), `indent-relative' either does - nothing (if UNINDENTED-OK is non-`nil') or calls - `tab-to-tab-stop'. Thus, if point is underneath and to the right - of the last column of a short line of text, this command ordinarily - moves point to the next tab stop by inserting whitespace. + - 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. - The return value of `indent-relative' is unpredictable. + In an interactive call, COUNT is the numeric prefix argument. - In the following example, point is at the beginning of the second - line: + 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 line is indented twelve spaces. - -!-The quick brown fox jumped. + 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::.) - Evaluation of the expression `(indent-relative nil)' produces the - following: + This is also responsible for calling `blink-paren-function' when + the inserted character has close parenthesis syntax (*note + Blinking::). - This line is indented twelve spaces. - -!-The quick brown fox jumped. + - Command: newline &optional count + This command inserts newlines into the current buffer before point. + If COUNT is supplied, that many newline characters are inserted. - In this example, point is between the `m' and `p' of `jumped': + This function calls `auto-fill-function' if the current column + number is greater than the value of `fill-column' and COUNT 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 COUNT is non-`nil'. - This line is indented twelve spaces. - The quick brown fox jum-!-ped. + This command indents to the left margin if that is not zero. + *Note Margins::. - Evaluation of the expression `(indent-relative nil)' produces the - following: + The value returned is `nil'. In an interactive call, COUNT is the + numeric prefix argument. - This line is indented twelve spaces. - The quick brown fox jum -!-ped. + - 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. - - Command: indent-relative-maybe - This command indents the current line like the previous nonblank - line. It calls `indent-relative' with `t' as the UNINDENTED-OK - argument. The return value is unpredictable. + Programs hardly ever use this function. - If the previous nonblank line has no indent points beyond the - current column, this command does nothing. + - 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: Indent Tabs, Next: Motion by Indent, Prev: Relative Indent, Up: Indentation - -Adjustable "Tab Stops" ----------------------- - - This section explains the mechanism for user-specified "tab stops" -and the mechanisms that use and set them. The name "tab stops" is used -because the feature is similar to that of the tab stops on a -typewriter. The feature works by inserting an appropriate number of -spaces and tab characters to reach the next tab stop column; it does not -affect the display of tab characters in the buffer (*note Usual -Display::). Note that the character as input uses this tab stop -feature only in a few major modes, such as Text mode. - - - Command: tab-to-tab-stop - This command inserts spaces or tabs up to the next tab stop column - defined by `tab-stop-list'. It searches the list for an element - greater than the current column number, and uses that element as - the column to indent to. It does nothing if no such element is - found. - - - User Option: tab-stop-list - This variable is the list of tab stop columns used by - `tab-to-tab-stops'. The elements should be integers in increasing - order. The tab stop columns need not be evenly spaced. - - Use `M-x edit-tab-stops' to edit the location of tab stops - interactively. +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'. + + - Command: 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 &optional count killp + This command deletes COUNT characters directly after point, or + before point if COUNT is negative. COUNT defaults to `1'. 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 &optional count killp + This command deletes COUNT characters directly before point, or + after point if COUNT is negative. COUNT defaults to 1. 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: Motion by Indent, Prev: Indent Tabs, Up: Indentation +File: lispref.info, Node: User-Level Deletion, Next: The Kill Ring, Prev: Deletion, Up: Text -Indentation-Based Motion Commands ---------------------------------- +User-Level Deletion Commands +============================ - These commands, primarily for interactive use, act based on the -indentation in the text. + This section describes higher-level commands for deleting text, +commands intended primarily for the user but useful also in Lisp +programs. - - Command: back-to-indentation - This command moves point to the first non-whitespace character in - the current line (which is the line in which point is located). - It returns `nil'. - - - Command: backward-to-indentation arg - This command moves point backward ARG lines and then to the first - nonblank character on that line. It returns `nil'. + - Command: delete-horizontal-space + This function deletes all spaces and tabs around point. It returns + `nil'. - - Command: forward-to-indentation arg - This command moves point forward ARG lines and then to the first - nonblank character on that line. It returns `nil'. - - -File: lispref.info, Node: Case Changes, Next: Text Properties, Prev: Indentation, Up: Text + 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. -Case Changes -============ - - The case change commands described here work on text in the current -buffer. *Note Character Case::, for case conversion commands that work -on strings and characters. *Note Case Tables::, for how to customize -which characters are upper or lower case and how to convert them. + ---------- Buffer: foo ---------- + I -!-thought + I -!- thought + We-!- thought + Yo-!-u thought + ---------- Buffer: foo ---------- + + (delete-horizontal-space) ; Four times. + => nil + + ---------- Buffer: foo ---------- + Ithought + Ithought + Wethought + You thought + ---------- Buffer: foo ---------- - - Command: capitalize-region start end - This function capitalizes all words in the region defined by START - and END. To capitalize means to convert each word's first - character to upper case and convert the rest of each word to lower - case. The function returns `nil'. + - 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'. - If one end of the region is in the middle of a word, the part of - the word within the region is treated as an entire word. + 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::. - When `capitalize-region' is called interactively, START and END - are point and the mark, with the smallest first. + 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. ---------- Buffer: foo ---------- - This is the contents of the 5th foo. + When in the course of human + -!- events, it becomes necessary ---------- Buffer: foo ---------- - (capitalize-region 1 44) - => nil + (delete-indentation) + => nil ---------- Buffer: foo ---------- - This Is The Contents Of The 5th Foo. + When in the course of human-!- events, it becomes necessary ---------- Buffer: foo ---------- - - Command: downcase-region start end - This function converts all of the letters in the region defined by - START and END to lower case. The function returns `nil'. + After the lines are joined, the function `fixup-whitespace' is + responsible for deciding whether to leave a space at the junction. - When `downcase-region' is called interactively, START and END are - point and the mark, with the smallest first. + - Command: 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'. - - Command: upcase-region start end - This function converts all of the letters in the region defined by - START and END to upper case. The function returns `nil'. + 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::. - When `upcase-region' is called interactively, START and END are - point and the mark, with the smallest first. + 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 `('. - - Command: capitalize-word count - This function capitalizes COUNT words after point, moving point - over as it does. To capitalize means to convert each word's first - character to upper case and convert the rest of each word to lower - case. If COUNT is negative, the function capitalizes the -COUNT - previous words but does not move point. The value is `nil'. - - If point is in the middle of a word, the part of the word before - point is ignored when moving forward. The rest is treated as an - entire word. - - When `capitalize-word' is called interactively, COUNT is set to - the numeric prefix argument. + ---------- 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 ---------- - - Command: downcase-word count - This function converts the COUNT words after point to all lower - case, moving point over as it does. If COUNT is negative, it - converts the -COUNT previous words but does not move point. The - value is `nil'. + - Command: just-one-space + This command replaces any spaces and tabs around point with a + single space. It returns `nil'. - When `downcase-word' is called interactively, COUNT is set to the - numeric prefix argument. + - 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. - - Command: upcase-word count - This function converts the COUNT words after point to all upper - case, moving point over as it does. If COUNT is negative, it - converts the -COUNT previous words but does not move point. The - value is `nil'. + A blank line is defined as a line containing only tabs and spaces. - When `upcase-word' is called interactively, COUNT is set to the - numeric prefix argument. + `delete-blank-lines' returns `nil'.  -File: lispref.info, Node: Text Properties, Next: Substitution, Prev: Case Changes, Up: Text +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. -Text Properties -=============== +* Menu: - Text properties are an alternative interface to extents (*note -Extents::), and are built on top of them. They are useful when you -want to view textual properties as being attached to the characters -themselves rather than to intervals of characters. The text property -interface is compatible with FSF Emacs. +* 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. - Each character position in a buffer or a string can have a "text -property list", much like the property list of a symbol (*note Property -Lists::). The properties belong to a particular character at a -particular place, such as, the letter `T' at the beginning of this -sentence or the first `o' in `foo'--if the same character occurs in two -different places, the two occurrences generally have different -properties. + +File: lispref.info, Node: Kill Ring Concepts, Next: Kill Functions, Up: The Kill Ring - Each property has a name and a value. Both of these can be any Lisp -object, but the name is normally a symbol. The usual way to access the -property list is to specify a name and ask what value corresponds to it. +Kill Ring Concepts +------------------ - Note that FSF Emacs also looks at the `category' property to find -defaults for text properties. We consider this too bogus to implement. + The kill ring records killed text as strings in a list, most recent +first. A short kill ring, for example, might look like this: - Copying text between strings and buffers preserves the properties -along with the characters; this includes such diverse functions as -`substring', `insert', and `buffer-substring'. + ("some text" "a different piece of text" "even older text") -* Menu: +When the list reaches `kill-ring-max' entries in length, adding a new +entry automatically deletes the last entry. -* Examining Properties:: Looking at the properties of one character. -* Changing Properties:: Setting the properties of a range of text. -* Property Search:: Searching for where a property changes value. -* Special Properties:: Particular properties with special meanings. -* Saving Properties:: Saving text properties in files, and reading - them back. + 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. - -File: lispref.info, Node: Examining Properties, Next: Changing Properties, Up: Text Properties + 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. -Examining Text Properties -------------------------- - - The simplest way to examine text properties is to ask for the value -of a particular property of a particular character. For that, use -`get-text-property'. Use `text-properties-at' to get the entire -property list of a character. *Note Property Search::, for functions -to examine the properties of a number of characters at once. + +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 &optional verbose + 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::. - These functions handle both strings and buffers. (Keep in mind that -positions in a string start from 0, whereas positions in a buffer start -from 1.) + +File: lispref.info, Node: Yank Commands, Next: Low-Level Kill Ring, Prev: Kill Functions, Up: The Kill Ring - - Function: get-text-property pos prop &optional object - This function returns the value of the PROP property of the - character after position POS in OBJECT (a buffer or string). The - argument OBJECT is optional and defaults to the current buffer. +Functions for Yanking +--------------------- - - Function: get-char-property pos prop &optional object - This function is like `get-text-property', except that it checks - all extents, not just text-property extents. + "Yanking" means reinserting an entry of previously killed text from +the kill ring. The text properties are copied too. + - 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. - - Function: text-properties-at position &optional object - This function returns the entire property list of the character at - POSITION in the string or buffer OBJECT. If OBJECT is `nil', it - defaults to the current buffer. + 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. - - Variable: default-text-properties - This variable holds a property list giving default values for text - properties. Whenever a character does not specify a value for a - property, the value stored in this list is used instead. Here is - an example: + If ARG is a number, then `yank' inserts the ARGth most recently + killed text--the ARGth element of the kill ring list. - (setq default-text-properties '(foo 69)) - ;; Make sure character 1 has no properties of its own. - (set-text-properties 1 2 nil) - ;; What we get, when we ask, is the default value. - (get-text-property 1 'foo) - => 69 + `yank' does not alter the contents of the kill ring or rotate it. + It returns `nil'. - -File: lispref.info, Node: Changing Properties, Next: Property Search, Prev: Examining Properties, Up: Text Properties + - Command: yank-pop arg + This command replaces the just-yanked entry from the kill ring + with a different entry from the kill ring. -Changing Text Properties ------------------------- + 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. - The primitives for changing properties apply to a specified range of -text. The function `set-text-properties' (see end of section) sets the -entire property list of the text in that range; more often, it is -useful to add, change, or delete just certain properties specified by -name. + 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. - Since text properties are considered part of the buffer's contents, -and can affect how the buffer looks on the screen, any change in the -text properties is considered a buffer modification. Buffer text -property changes are undoable (*note Undo::). + 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. - - Function: put-text-property start end prop value &optional object - This function sets the PROP property to VALUE for the text between - START and END in the string or buffer OBJECT. If OBJECT is `nil', - it defaults to the current buffer. + The value is always `nil'. - - Function: add-text-properties start end props &optional object - This function modifies the text properties for the text between - START and END in the string or buffer OBJECT. If OBJECT is `nil', - it defaults to the current buffer. + +File: lispref.info, Node: Low-Level Kill Ring, Next: Internals of Kill Ring, Prev: Yank Commands, Up: The Kill Ring - The argument PROPS specifies which properties to change. It - should have the form of a property list (*note Property Lists::): - a list whose elements include the property names followed - alternately by the corresponding values. +Low-Level Kill Ring +------------------- - The return value is `t' if the function actually changed some - property's value; `nil' otherwise (if PROPS is `nil' or its values - agree with those in the text). + 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. - For example, here is how to set the `comment' and `face' - properties of a range of text: + - Function: current-kill count &optional do-not-move + The function `current-kill' rotates the yanking pointer which + designates the "front" of the kill ring by COUNT places (from newer + kills to older ones), and returns the text at that place in the + ring. - (add-text-properties START END - '(comment t face highlight)) + If the optional second argument DO-NOT-MOVE is non-`nil', then + `current-kill' doesn't alter the yanking pointer; it just returns + the COUNTth kill, counting from the current yanking pointer. - - Function: remove-text-properties start end props &optional object - This function deletes specified text properties from the text - between START and END in the string or buffer OBJECT. If OBJECT - is `nil', it defaults to the current buffer. + If COUNT 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. - The argument PROPS specifies which properties to delete. It - should have the form of a property list (*note Property Lists::): - a list whose elements are property names alternating with - corresponding values. But only the names matter--the values that - accompany them are ignored. For example, here's how to remove the - `face' property. + - Function: kill-new string &optional replace + This function makes the text STRING the latest entry in the kill + ring, and sets `kill-ring-yank-pointer' to point to it. - (remove-text-properties START END '(face nil)) + Normally, STRING is added to the front of the kill ring as a new + entry. However, if optional argument REPLACE is non-`nil', the + entry previously at the front of the kill ring is discarded, and + STRING replaces it. - The return value is `t' if the function actually changed some - property's value; `nil' otherwise (if PROPS is `nil' or if no - character in the specified text had any of those properties). + This function runs the functions on `kill-hooks', and also invokes + the value of `interprogram-cut-function' (see below). - - Function: set-text-properties start end props &optional object - This function completely replaces the text property list for the - text between START and END in the string or buffer OBJECT. If - OBJECT is `nil', it defaults to the current buffer. + - 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). - The argument PROPS is the new property list. It should be a list - whose elements are property names alternating with corresponding - values. + - 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. - After `set-text-properties' returns, all the characters in the - specified range have identical properties. + 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. - If PROPS is `nil', the effect is to get rid of all properties from - the specified range of text. Here's an example: + 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::. - (set-text-properties START END nil) + - 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. - See also the function `buffer-substring-without-properties' (*note -Buffer Contents::) which copies text from the buffer but does not copy -its properties. + 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. - -File: lispref.info, Node: Property Search, Next: Special Properties, Prev: Changing Properties, Up: Text Properties - -Property Search Functions -------------------------- - - In typical use of text properties, most of the time several or many -consecutive characters have the same value for a property. Rather than -writing your programs to examine characters one by one, it is much -faster to process chunks of text that have the same property value. - - Here are functions you can use to do this. They use `eq' for -comparing property values. In all cases, OBJECT defaults to the -current buffer. - - For high performance, it's very important to use the LIMIT argument -to these functions, especially the ones that search for a single -property--otherwise, they may spend a long time scanning to the end of -the buffer, if the property you are interested in does not change. - - Remember that a position is always between two characters; the -position returned by these functions is between two characters with -different properties. - - - Function: next-property-change pos &optional object limit - The function scans the text forward from position POS in the - string or buffer OBJECT till it finds a change in some text - property, then returns the position of the change. In other - words, it returns the position of the first character beyond POS - whose properties are not identical to those of the character just - after POS. - - If LIMIT is non-`nil', then the scan ends at position LIMIT. If - there is no property change before that point, - `next-property-change' returns LIMIT. - - The value is `nil' if the properties remain unchanged all the way - to the end of OBJECT and LIMIT is `nil'. If the value is - non-`nil', it is a position greater than or equal to POS. The - value equals POS only when LIMIT equals POS. - - Here is an example of how to scan the buffer by chunks of text - within which all properties are constant: - - (while (not (eobp)) - (let ((plist (text-properties-at (point))) - (next-change - (or (next-property-change (point) (current-buffer)) - (point-max)))) - Process text from point to NEXT-CHANGE... - (goto-char next-change))) - - - Function: next-single-property-change pos prop &optional object limit - The function scans the text forward from position POS in the - string or buffer OBJECT till it finds a change in the PROP - property, then returns the position of the change. In other - words, it returns the position of the first character beyond POS - whose PROP property differs from that of the character just after - POS. - - If LIMIT is non-`nil', then the scan ends at position LIMIT. If - there is no property change before that point, - `next-single-property-change' returns LIMIT. - - The value is `nil' if the property remains unchanged all the way to - the end of OBJECT and LIMIT is `nil'. If the value is non-`nil', - it is a position greater than or equal to POS; it equals POS only - if LIMIT equals POS. - - - Function: previous-property-change pos &optional object limit - This is like `next-property-change', but scans back from POS - instead of forward. If the value is non-`nil', it is a position - less than or equal to POS; it equals POS only if LIMIT equals POS. - - - Function: previous-single-property-change pos prop &optional object - limit - This is like `next-single-property-change', but scans back from - POS instead of forward. If the value is non-`nil', it is a - position less than or equal to POS; it equals POS only if LIMIT - equals POS. - - - Function: text-property-any start end prop value &optional object - This function returns non-`nil' if at least one character between - START and END has a property PROP whose value is VALUE. More - precisely, it returns the position of the first such character. - Otherwise, it returns `nil'. - - The optional fifth argument, OBJECT, specifies the string or - buffer to scan. Positions are relative to OBJECT. The default - for OBJECT is the current buffer. - - - Function: text-property-not-all start end prop value &optional object - This function returns non-`nil' if at least one character between - START and END has a property PROP whose value differs from VALUE. - More precisely, it returns the position of the first such - character. Otherwise, it returns `nil'. - - The optional fifth argument, OBJECT, specifies the string or - buffer to scan. Positions are relative to OBJECT. The default - for OBJECT is the current buffer. + The normal use of this hook is to set the X server's primary + selection to the newly killed text.  -File: lispref.info, Node: Special Properties, Next: Saving Properties, Prev: Property Search, Up: Text Properties +File: lispref.info, Node: Internals of Kill Ring, Prev: Low-Level Kill Ring, Up: The Kill Ring -Properties with Special Meanings --------------------------------- +Internals of the Kill Ring +-------------------------- - The predefined properties are the same as those for extents. *Note -Extent Properties::. + 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: Saving Properties, Prev: Special Properties, Up: Text Properties - -Saving Text Properties in Files -------------------------------- - - You can save text properties in files, and restore text properties -when inserting the files, using these two hooks: - - - Variable: write-region-annotate-functions - This variable's value is a list of functions for `write-region' to - run to encode text properties in some fashion as annotations to - the text being written in the file. *Note Writing to Files::. - - Each function in the list is called with two arguments: the start - and end of the region to be written. These functions should not - alter the contents of the buffer. Instead, they should return - lists indicating annotations to write in the file in addition to - the text in the buffer. - - Each function should return a list of elements of the form - `(POSITION . STRING)', where POSITION is an integer specifying the - relative position in the text to be written, and STRING is the - annotation to add there. - - Each list returned by one of these functions must be already - sorted in increasing order by POSITION. If there is more than one - function, `write-region' merges the lists destructively into one - sorted list. - - When `write-region' actually writes the text from the buffer to the - file, it intermixes the specified annotations at the corresponding - positions. All this takes place without modifying the buffer. - - - Variable: after-insert-file-functions - This variable holds a list of functions for `insert-file-contents' - to call after inserting a file's contents. These functions should - scan the inserted text for annotations, and convert them to the - text properties they stand for. - - Each function receives one argument, the length of the inserted - text; point indicates the start of that text. The function should - scan that text for annotations, delete them, and create the text - properties that the annotations specify. The function should - return the updated length of the inserted text, as it stands after - those changes. The value returned by one function becomes the - argument to the next function. - - These functions should always return with point at the beginning of - the inserted text. - - The intended use of `after-insert-file-functions' is for converting - some sort of textual annotations into actual text properties. But - other uses may be possible. - - We invite users to write Lisp programs to store and retrieve text -properties in files, using these hooks, and thus to experiment with -various data formats and find good ones. Eventually we hope users will -produce good, general extensions we can install in Emacs. - - We suggest not trying to handle arbitrary Lisp objects as property -names or property values--because a program that general is probably -difficult to write, and slow. Instead, choose a set of possible data -types that are reasonably flexible, and not too hard to encode. - - *Note Format Conversion::, for a related feature. +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. + +`(START . END)' + This kind of element indicates how to delete text that was + inserted. Upon insertion, the text occupied the range START-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 START . END)' + This kind of element records a change in a text property. Here's + how you might undo the change: + + (put-text-property START 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: Substitution, Next: Registers, Prev: Text Properties, Up: Text +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. + + - Command: buffer-disable-undo &optional buffer + - Command: 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. -Substituting for a Character Code -================================= + +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. - The following functions replace characters within a specified region -based on their character codes. + - 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: subst-char-in-region start end old-char new-char &optional - noundo - This function replaces all occurrences of the character OLD-CHAR - with the character NEW-CHAR in the region of the current buffer - defined by START and END. + - Function: current-justification + This function returns the proper justification style to use for + filling the text around point. - If NOUNDO is non-`nil', then `subst-char-in-region' does not - record the change for undo and does not mark the buffer as - modified. This feature is used for controlling selective display - (*note Selective Display::). + - 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. - `subst-char-in-region' does not move point and returns `nil'. + 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: - ---------- Buffer: foo ---------- - This is the contents of the buffer before. - ---------- Buffer: foo ---------- - - (subst-char-in-region 1 20 ?i ?X) - => nil - - ---------- Buffer: foo ---------- - ThXs Xs the contents of the buffer before. - ---------- Buffer: foo ---------- + (let ((fill-paragraph-function nil)) + (fill-paragraph arg)) - - Function: translate-region start end table - This function applies a translation table to the characters in the - buffer between positions START and END. The translation table - TABLE can be either a string, a vector, or a char-table. + - 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. - If TABLE is a string, its Nth element is the mapping for the - character with code N. + +File: lispref.info, Node: Margins, Next: Auto Filling, Prev: Filling, Up: Text + +Margins for Filling +=================== + + - User Option: fill-prefix + This variable specifies a string of text that appears at the + beginning of normal text lines and should be disregarded when + filling them. Any line that fails to start with the fill prefix + is considered the start of a paragraph; so is any line that starts + with the fill prefix followed by additional whitespace. Lines + that start with the fill prefix but no additional whitespace are + ordinary text lines that can be filled together. The resulting + filled lines also start with the fill prefix. + + The fill prefix follows the left margin whitespace, if any. + + - User Option: fill-column + This buffer-local variable specifies the maximum width of filled + lines. Its value should be an integer, which is a number of + columns. All the filling, justification and centering commands + are affected by this variable, including Auto Fill mode (*note + Auto Filling::). + + As a practical matter, if you are writing text for other people to + read, you should set `fill-column' to no more than 70. Otherwise + the line will be too long for people to read comfortably, and this + can make the text seem clumsy. + + - Variable: default-fill-column + The value of this variable is the default value for `fill-column' + in buffers that do not override it. This is the same as + `(default-value 'fill-column)'. + + The default value for `default-fill-column' is 70. + + - Command: set-left-margin from to margin + This sets the `left-margin' property on the text from FROM to TO + to the value MARGIN. If Auto Fill mode is enabled, this command + also refills the region to fit the new margin. + + - Command: set-right-margin from to margin + This sets the `right-margin' property on the text from FROM to TO + to the value MARGIN. If Auto Fill mode is enabled, this command + also refills the region to fit the new margin. + + - Function: current-left-margin + This function returns the proper left margin value to use for + filling the text around point. The value is the sum of the + `left-margin' property of the character at the start of the + current line (or zero if none), and the value of the variable + `left-margin'. - If TABLE is a vector, its Nth element is the mapping for character - with code N. Legal mappings are characters, strings, or `nil' - (meaning don't replace.) + - 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. - If TABLE is a char-table, its elements describe the mapping - between characters and their replacements. The char-table should - be of type `char' or `generic'. + - 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. - When the TABLE is a string or vector and its length is less than - the total number of characters (256 without Mule), any characters - with codes larger than the length of TABLE are not altered by the - translation. + If FORCE is non-`nil', that says to fix the line's indentation if + that doesn't match the left margin value. - The return value of `translate-region' is the number of characters - that were actually changed by the translation. This does not - count characters that were mapped into themselves in the - translation table. + - Function: delete-to-left-margin &optional 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. - *NOTE*: Prior to XEmacs 21.2, the TABLE argument was allowed only - to be a string. This is still the case in FSF Emacs. + The arguments FROM and TO are optional; the default is the whole + buffer. - The following example creates a char-table that is passed to - `translate-region', which translates character `a' to `the letter - a', removes character `b', and translates character `c' to newline. + - 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. - ---------- Buffer: foo ---------- - Here is a sentence in the buffer. - ---------- Buffer: foo ---------- - - (let ((table (make-char-table 'generic))) - (put-char-table ?a "the letter a" table) - (put-char-table ?b "" table) - (put-char-table ?c ?\n table) - (translate-region (point-min) (point-max) table)) - => 3 - - ---------- Buffer: foo ---------- - Here is the letter a senten - e in the uffer. - ---------- Buffer: foo ---------- + - 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: Registers, Next: Transposition, Prev: Substitution, Up: Text - -Registers -========= - - A register is a sort of variable used in XEmacs editing that can -hold a marker, a string, a rectangle, a window configuration (of one -frame), or a frame configuration (of all frames). Each register is -named by a single character. All characters, including control and -meta characters (but with the exception of `C-g'), can be used to name -registers. Thus, there are 255 possible registers. A register is -designated in Emacs Lisp by a character that is its name. - - The functions in this section return unpredictable values unless -otherwise stated. - - - Variable: register-alist - This variable is an alist of elements of the form `(NAME . - CONTENTS)'. Normally, there is one element for each XEmacs - register that has been used. - - The object NAME is a character (an integer) identifying the - register. The object CONTENTS is a string, marker, or list - representing the register contents. A string represents text - stored in the register. A marker represents a position. A list - represents a rectangle; its elements are strings, one per line of - the rectangle. - - - Function: get-register reg - This function returns the contents of the register REG, or `nil' - if it has no contents. - - - Function: set-register reg value - This function sets the contents of register REG to VALUE. A - register can be set to any value, but the other register functions - expect only certain data types. The return value is VALUE. - - - Command: view-register reg - This command displays what is contained in register REG. - - - Command: insert-register reg &optional beforep - This command inserts contents of register REG into the current - buffer. - - Normally, this command puts point before the inserted text, and the - mark after it. However, if the optional second argument BEFOREP - is non-`nil', it puts the mark before and point after. You can - pass a non-`nil' second argument BEFOREP to this function - interactively by supplying any prefix argument. +File: lispref.info, Node: Auto Filling, Next: Sorting, Prev: Margins, Up: Text - If the register contains a rectangle, then the rectangle is - inserted with its upper left corner at point. This means that - text is inserted in the current line and underneath it on - successive lines. - - If the register contains something other than saved text (a - string) or a rectangle (a list), currently useless things happen. - This may be changed in the future. +Auto Filling +============ - -File: lispref.info, Node: Transposition, Next: Change Hooks, Prev: Registers, Up: Text + 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::. -Transposition of Text -===================== + Auto Fill mode also enables the functions that change the margins and +justification style to refill portions of the text. *Note Margins::. - This subroutine is used by the transposition commands. + - 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. - - Function: transpose-regions start1 end1 start2 end2 &optional - leave-markers - This function exchanges two nonoverlapping portions of the buffer. - Arguments START1 and END1 specify the bounds of one portion and - arguments START2 and END2 specify the bounds of the other portion. + 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. - Normally, `transpose-regions' relocates markers with the transposed - text; a marker previously positioned within one of the two - transposed portions moves along with that portion, thus remaining - between the same two characters in their new position. However, - if LEAVE-MARKERS is non-`nil', `transpose-regions' does not do - this--it leaves all markers unrelocated. + 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.