X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;ds=sidebyside;f=info%2Flispref.info-31;h=ca94d67b5efea3d70c7deb2ef7a9a482b9236ec9;hb=2779fcb5d524d6b7de5a6ef9ebfd6662433a4a07;hp=138661a08f47a6f6e137f983b1c172a0cc4cbd97;hpb=7d6edaefa00e7b7e102354283824a4f6a721b71a;p=chise%2Fxemacs-chise.git- diff --git a/info/lispref.info-31 b/info/lispref.info-31 index 138661a..ca94d67 100644 --- a/info/lispref.info-31 +++ b/info/lispref.info-31 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 4.0 from +This is ../info/lispref.info, produced by makeinfo version 4.0b from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,1162 +50,1141 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Change Hooks, Next: Transformations, Prev: Transposition, Up: Text +File: lispref.info, Node: Sorting, Next: Columns, Prev: Auto Filling, Up: Text -Change Hooks +Sorting Text ============ - These hook variables let you arrange to take notice of all changes in -all buffers (or in a particular buffer, if you make them buffer-local). - - The functions you use in these hooks should save and restore the -match data if they do anything that uses regular expressions; -otherwise, they will interfere in bizarre ways with the editing -operations that call them. - - Buffer changes made while executing the following hooks don't -themselves cause any change hooks to be invoked. - - - Variable: before-change-functions - This variable holds a list of a functions to call before any buffer - modification. Each function gets two arguments, the beginning and - end of the region that is about to change, represented as - integers. The buffer that is about to change is always the - current buffer. - - - Variable: after-change-functions - This variable holds a list of a functions to call after any buffer - modification. Each function receives three arguments: the - beginning and end of the region just changed, and the length of - the text that existed before the change. (To get the current - length, subtract the region beginning from the region end.) All - three arguments are integers. The buffer that's about to change - is always the current buffer. - - - Variable: before-change-function - This obsolete variable holds one function to call before any buffer - modification (or `nil' for no function). It is called just like - the functions in `before-change-functions'. - - - Variable: after-change-function - This obsolete variable holds one function to call after any buffer - modification (or `nil' for no function). It is called just like - the functions in `after-change-functions'. - - - Variable: first-change-hook - This variable is a normal hook that is run whenever a buffer is - changed that was previously in the unmodified state. + 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 start end) + "Sort lines in region alphabetically. + Called from a program, there are three arguments: + REVERSE (non-nil means reverse order), + and START and END (the region to sort)." + (interactive "P\nr") + (save-restriction + (narrow-to-region start 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 start end + This command sorts the lines in the region between START and END, + comparing them alphabetically by a certain range of columns. The + column positions of START 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 START, 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: Transformations, Prev: Change Hooks, Up: Text +File: lispref.info, Node: Columns, Next: Indentation, Prev: Sorting, Up: Text -Textual transformations--MD5 and base64 support -=============================================== +Counting Columns +================ - Some textual operations inherently require examining each character -in turn, and performing arithmetic operations on them. Such operations -can, of course, be implemented in Emacs Lisp, but tend to be very slow -for large portions of text or data. This is why some of them are -implemented in C, with an appropriate interface for Lisp programmers. -Examples of algorithms thus provided are MD5 and base64 support. + 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). - MD5 is an algorithm for calculating message digests, as described in -rfc1321. Given a message of arbitrary length, MD5 produces an 128-bit -"fingerprint" ("message digest") corresponding to that message. It is -considered computationally infeasible to produce two messages having -the same MD5 digest, or to produce a message having a prespecified -target digest. MD5 is used heavily by various authentication schemes. + 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::. - Emacs Lisp interface to MD5 consists of a single function `md5': + 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: md5 object &optional start end - This function returns the MD5 message digest of OBJECT, a buffer - or string. + - Function: current-column &optional buffer + This function returns the horizontal position of point, measured in + columns, counting from 0 at the left margin. - Optional arguments START and END denote positions for computing - the digest of a portion of OBJECT. + This is calculated by adding together the widths of all the + displayed representations of the character between the start of + the previous line and point. (e.g. control characters will have a + width of 2 or 4, tabs will have a variable width.) - Some examples of usage: + Ignores the finite width of frame displaying the buffer, which + means that this function may return values greater than + `(frame-width)'. - ;; Calculate the digest of the entire buffer - (md5 (current-buffer)) - => "8842b04362899b1cda8d2d126dc11712" - - ;; Calculate the digest of the current line - (md5 (current-buffer) (point-at-bol) (point-at-eol)) - => "60614d21e9dee27dfdb01fa4e30d6d00" - - ;; Calculate the digest of your name and email address - (md5 (concat (format "%s <%s>" (user-full-name) user-mail-address))) - => "0a2188c40fd38922d941fe6032fce516" + Whether the line is visible (if `selective-display' is t) has no + effect; however, ^M is treated as end of line when + `selective-display' is t. - Base64 is a portable encoding for arbitrary sequences of octets, in a -form that need not be readable by humans. It uses a 65-character subset -of US-ASCII, as described in rfc2045. Base64 is used by MIME to encode -binary bodies, and to encode binary characters in message headers. + If BUFFER is nil, the current buffer is assumed. - The Lisp interface to base64 consists of four functions: + For an example of using `current-column', see the description of + `count-lines' in *Note Text Lines::. - - Function: base64-encode-region beg end &optional no-line-break - This function encodes the region between BEG and END of the - current buffer to base64 format. This means that the original - region is deleted, and replaced with its base64 equivalent. + - Function: move-to-column column &optional force buffer + 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. - Normally, encoded base64 output is multi-line, with 76-character - lines. If NO-LINE-BREAK is non-`nil', newlines will not be - inserted, resulting in single-line output. + 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. - Mule note: you should make sure that you convert the multibyte - characters (those that do not fit into 0-255 range) to something - else, because they cannot be meaningfully converted to base64. If - the `base64-encode-region' encounters such characters, it will - signal an error. + 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. - `base64-encode-region' returns the length of the encoded text. + The argument FORCE also has an effect if the line isn't long + enough to reach column COLUMN; in that case, unless the value of + FORCE is the special value `coerce', it says to add whitespace at + the end of the line to reach that column. - ;; Encode the whole buffer in base64 - (base64-encode-region (point-min) (point-max)) + If COLUMN is not a non-negative integer, an error is signaled. - The function can also be used interactively, in which case it - works on the currently active region. + The return value is the column number actually moved to. - - Function: base64-encode-string string - This function encodes STRING to base64, and returns the encoded - string. + +File: lispref.info, Node: Indentation, Next: Case Changes, Prev: Columns, Up: Text - For Mule, the same considerations apply as for - `base64-encode-region'. +Indentation +=========== - (base64-encode-string "fubar") - => "ZnViYXI=" + 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. - - Function: base64-decode-region beg end - This function decodes the region between BEG and END of the - current buffer. The region should be in base64 encoding. +* Menu: - If the region was decoded correctly, `base64-decode-region' returns - the length of the decoded region. If the decoding failed, `nil' is - returned. +* 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. - ;; Decode a base64 buffer, and replace it with the decoded version - (base64-decode-region (point-min) (point-max)) + +File: lispref.info, Node: Primitive Indent, Next: Mode-Specific Indent, Up: Indentation - - Function: base64-decode-string string - This function decodes STRING to base64, and returns the decoded - string. STRING should be valid base64-encoded text. +Indentation Primitives +---------------------- - If encoding was not possible, `nil' is returned. + This section describes the primitive functions used to count and +insert indentation. The functions in the following sections use these +primitives. + + - Function: current-indentation &optional buffer + 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 buffer + 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. If BUFFER is `nil', the current buffer is + assumed. + + - 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. - (base64-decode-string "ZnViYXI=") - => "fubar" - - (base64-decode-string "totally bogus") - => nil + +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 &optional prefix-arg + 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: Searching and Matching, Next: Syntax Tables, Prev: Text, Up: Top +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. + + If the value is `nil', there is no short cut, and `indent-region' + actually works line by line. + + 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. + + `indent-region' with a non-`nil' argument TO-COLUMN has a + different meaning and does not use this variable. + + - Command: indent-rigidly start end count + 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. + + For example, if COUNT is 3, this command adds 3 columns of + indentation to each of the lines beginning in the region specified. + + In Mail mode, `C-c C-y' (`mail-yank-original') uses + `indent-rigidly' to indent the text copied from the message being + replied to. + + - Command: 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 addition, it doesn't alter a line if NOCHANGE-REGEXP matches at + the beginning of the line (if NOCHANGE-REGEXP is non-`nil'). -Searching and Matching -********************** + +File: lispref.info, Node: Relative Indent, Next: Indent Tabs, Prev: Region Indent, Up: Indentation - XEmacs provides two ways to search through a buffer for specified -text: exact string searches and regular expression searches. After a -regular expression search, you can examine the "match data" to -determine which text matched the whole regular expression or various -portions of it. +Indentation Relative to Previous Lines +-------------------------------------- -* Menu: + This section describes two commands that indent the current line +based on the contents of previous lines. + + - 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. -* String Search:: Search for an exact match. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* POSIX Regexps:: Searching POSIX-style for the longest match. -* Search and Replace:: Internals of `query-replace'. -* Match Data:: Finding out which part of the text matched - various parts of a regexp, after regexp search. -* Searching and Case:: Case-independent or case-significant searching. -* Standard Regexps:: Useful regexps for finding sentences, pages,... + 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. - The `skip-chars...' functions also perform a kind of searching. -*Note Skipping Characters::. + The return value of `indent-relative' is unpredictable. + + In the following example, point is at the beginning of the second + line: + + This line is indented twelve spaces. + -!-The quick brown fox jumped. + + Evaluation of the expression `(indent-relative nil)' produces the + following: + + This line is indented twelve spaces. + -!-The quick brown fox jumped. + + In this example, point is between the `m' and `p' of `jumped': + + This line is indented twelve spaces. + The quick brown fox jum-!-ped. + + Evaluation of the expression `(indent-relative nil)' produces the + following: + + This line is indented twelve spaces. + The quick brown fox jum -!-ped. + + - 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. + + If the previous nonblank line has no indent points beyond the + current column, this command does nothing.  -File: lispref.info, Node: String Search, Next: Regular Expressions, Up: Searching and Matching +File: lispref.info, Node: Indent Tabs, Next: Motion by Indent, Prev: Relative Indent, Up: Indentation -Searching for Strings -===================== +Adjustable "Tab Stops" +---------------------- - These are the primitive functions for searching through the text in a -buffer. They are meant for use in programs, but you may call them -interactively. If you do so, they prompt for the search string; LIMIT -and NOERROR are set to `nil', and REPEAT is set to 1. + 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. - - Command: search-forward string &optional limit noerror repeat - This function searches forward from point for an exact match for - STRING. If successful, it sets point to the end of the occurrence - found, and returns the new value of point. If no match is found, - the value and side effects depend on NOERROR (see below). + +File: lispref.info, Node: Motion by Indent, Prev: Indent Tabs, Up: Indentation - In the following example, point is initially at the beginning of - the line. Then `(search-forward "fox")' moves point after the last - letter of `fox': +Indentation-Based Motion Commands +--------------------------------- - ---------- Buffer: foo ---------- - -!-The quick brown fox jumped over the lazy dog. - ---------- Buffer: foo ---------- - - (search-forward "fox") - => 20 - - ---------- Buffer: foo ---------- - The quick brown fox-!- jumped over the lazy dog. - ---------- Buffer: foo ---------- + These commands, primarily for interactive use, act based on the +indentation in the text. + + - 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: 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 + +Case Changes +============ - The argument LIMIT specifies the upper bound to the search. (It - must be a position in the current buffer.) No match extending - after that position is accepted. If LIMIT is omitted or `nil', it - defaults to the end of the accessible portion of the buffer. - - What happens when the search fails depends on the value of - NOERROR. If NOERROR is `nil', a `search-failed' error is - signaled. If NOERROR is `t', `search-forward' returns `nil' and - does nothing. If NOERROR is neither `nil' nor `t', then - `search-forward' moves point to the upper bound and returns `nil'. - (It would be more consistent now to return the new position of - point in that case, but some programs may depend on a value of - `nil'.) - - If REPEAT is supplied (it must be a positive number), then the - search is repeated that many times (each time starting at the end - of the previous time's match). If these successive searches - succeed, the function succeeds, moving point and returning its new - value. Otherwise the search fails. - - - Command: search-backward string &optional limit noerror repeat - This function searches backward from point for STRING. It is just - like `search-forward' except that it searches backwards and leaves - point at the beginning of the match. - - - Command: word-search-forward string &optional limit noerror repeat - This function searches forward from point for a "word" match for - STRING. If it finds a match, it sets point to the end of the - match found, and returns the new value of point. - - Word matching regards STRING as a sequence of words, disregarding - punctuation that separates them. It searches the buffer for the - same sequence of words. Each word must be distinct in the buffer - (searching for the word `ball' does not match the word `balls'), - but the details of punctuation and spacing are ignored (searching - for `ball boy' does match `ball. Boy!'). - - In this example, point is initially at the beginning of the - buffer; the search leaves it between the `y' and the `!'. + 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. + + - Command: capitalize-region start end &optional buffer + 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'. + + 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. + + When `capitalize-region' is called interactively, START and END + are point and the mark, with the smallest first. ---------- Buffer: foo ---------- - -!-He said "Please! Find - the ball boy!" + This is the contents of the 5th foo. ---------- Buffer: foo ---------- - (word-search-forward "Please find the ball, boy.") - => 35 + (capitalize-region 1 44) + => nil ---------- Buffer: foo ---------- - He said "Please! Find - the ball boy-!-!" + This Is The Contents Of The 5th Foo. ---------- Buffer: foo ---------- - If LIMIT is non-`nil' (it must be a position in the current - buffer), then it is the upper bound to the search. The match - found must not extend after that position. + - Command: downcase-region start end &optional buffer + This function converts all of the letters in the region defined by + START and END to lower case. The function returns `nil'. - If NOERROR is `nil', then `word-search-forward' signals an error - if the search fails. If NOERROR is `t', then it returns `nil' - instead of signaling an error. If NOERROR is neither `nil' nor - `t', it moves point to LIMIT (or the end of the buffer) and - returns `nil'. + When `downcase-region' is called interactively, START and END are + point and the mark, with the smallest first. - If REPEAT is non-`nil', then the search is repeated that many - times. Point is positioned at the end of the last match. + - Command: upcase-region start end &optional buffer + This function converts all of the letters in the region defined by + START and END to upper case. The function returns `nil'. - - Command: word-search-backward string &optional limit noerror repeat - This function searches backward from point for a word match to - STRING. This function is just like `word-search-forward' except - that it searches backward and normally leaves point at the - beginning of the match. + When `upcase-region' is called interactively, START and END are + point and the mark, with the smallest first. - -File: lispref.info, Node: Regular Expressions, Next: Regexp Search, Prev: String Search, Up: Searching and Matching - -Regular Expressions -=================== - - A "regular expression" ("regexp", for short) is a pattern that -denotes a (possibly infinite) set of strings. Searching for matches for -a regexp is a very powerful operation. This section explains how to -write regexps; the following section says how to search for them. - - To gain a thorough understanding of regular expressions and how to -use them to best advantage, we recommend that you study `Mastering -Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates, -1997'. (It's known as the "Hip Owls" book, because of the picture on its -cover.) You might also read the manuals to *Note (gawk)Top::, *Note -(ed)Top::, `sed', `grep', *Note (perl)Top::, *Note (regex)Top::, *Note -(rx)Top::, `pcre', and *Note (flex)Top::, which also make good use of -regular expressions. - - The XEmacs regular expression syntax most closely resembles that of -`ed', or `grep', the GNU versions of which all utilize the GNU `regex' -library. XEmacs' version of `regex' has recently been extended with -some Perl-like capabilities, described in the next section. + - Command: capitalize-word count &optional buffer + 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'. -* Menu: + 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. -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. + When `capitalize-word' is called interactively, COUNT is set to + the numeric prefix argument. - -File: lispref.info, Node: Syntax of Regexps, Next: Regexp Example, Up: Regular Expressions - -Syntax of Regular Expressions ------------------------------ - - Regular expressions have a syntax in which a few characters are -special constructs and the rest are "ordinary". An ordinary character -is a simple regular expression that matches that character and nothing -else. The special characters are `.', `*', `+', `?', `[', `]', `^', -`$', and `\'; no new special characters will be defined in the future. -Any other character appearing in a regular expression is ordinary, -unless a `\' precedes it. - - For example, `f' is not a special character, so it is ordinary, and -therefore `f' is a regular expression that matches the string `f' and -no other string. (It does _not_ match the string `ff'.) Likewise, `o' -is a regular expression that matches only `o'. - - Any two regular expressions A and B can be concatenated. The result -is a regular expression that matches a string if A matches some amount -of the beginning of that string and B matches the rest of the string. - - As a simple example, we can concatenate the regular expressions `f' -and `o' to get the regular expression `fo', which matches only the -string `fo'. Still trivial. To do something more powerful, you need -to use one of the special characters. Here is a list of them: - -`. (Period)' - is a special character that matches any single character except a - newline. Using concatenation, we can make regular expressions - like `a.b', which matches any three-character string that begins - with `a' and ends with `b'. - -`*' - is not a construct by itself; it is a quantifying suffix operator - that means to repeat the preceding regular expression as many - times as possible. In `fo*', the `*' applies to the `o', so `fo*' - matches one `f' followed by any number of `o's. The case of zero - `o's is allowed: `fo*' does match `f'. - - `*' always applies to the _smallest_ possible preceding - expression. Thus, `fo*' has a repeating `o', not a repeating `fo'. - - The matcher processes a `*' construct by matching, immediately, as - many repetitions as can be found; it is "greedy". Then it - continues with the rest of the pattern. If that fails, - backtracking occurs, discarding some of the matches of the - `*'-modified construct in case that makes it possible to match the - rest of the pattern. For example, in matching `ca*ar' against the - string `caaar', the `a*' first tries to match all three `a's; but - the rest of the pattern is `ar' and there is only `r' left to - match, so this try fails. The next alternative is for `a*' to - match only two `a's. With this choice, the rest of the regexp - matches successfully. - - Nested repetition operators can be extremely slow if they specify - backtracking loops. For example, it could take hours for the - regular expression `\(x+y*\)*a' to match the sequence - `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'. The slowness is because - Emacs must try each imaginable way of grouping the 35 `x''s before - concluding that none of them can work. To make sure your regular - expressions run fast, check nested repetitions carefully. - -`+' - is a quantifying suffix operator similar to `*' except that the - preceding expression must match at least once. It is also - "greedy". So, for example, `ca+r' matches the strings `car' and - `caaaar' but not the string `cr', whereas `ca*r' matches all three - strings. - -`?' - is a quantifying suffix operator similar to `*', except that the - preceding expression can match either once or not at all. For - example, `ca?r' matches `car' or `cr', but does not match anything - else. - -`*?' - works just like `*', except that rather than matching the longest - match, it matches the shortest match. `*?' is known as a - "non-greedy" quantifier, a regexp construct borrowed from Perl. - - This construct very useful for when you want to match the text - inside a pair of delimiters. For instance, `/\*.*?\*/' will match - C comments in a string. This could not be achieved without the - use of greedy quantifier. - - This construct has not been available prior to XEmacs 20.4. It is - not available in FSF Emacs. - -`+?' - is the `+' analog to `*?'. - -`\{n,m\}' - serves as an interval quantifier, analogous to `*' or `+', but - specifies that the expression must match at least N times, but no - more than M times. This syntax is supported by most Unix regexp - utilities, and has been introduced to XEmacs for the version 20.3. - -`[ ... ]' - `[' begins a "character set", which is terminated by a `]'. In - the simplest case, the characters between the two brackets form - the set. Thus, `[ad]' matches either one `a' or one `d', and - `[ad]*' matches any string composed of just `a's and `d's - (including the empty string), from which it follows that `c[ad]*r' - matches `cr', `car', `cdr', `caddaar', etc. - - The usual regular expression special characters are not special - inside a character set. A completely different set of special - characters exists inside character sets: `]', `-' and `^'. - - `-' is used for ranges of characters. To write a range, write two - characters with a `-' between them. Thus, `[a-z]' matches any - lower case letter. Ranges may be intermixed freely with individual - characters, as in `[a-z$%.]', which matches any lower case letter - or `$', `%', or a period. - - To include a `]' in a character set, make it the first character. - For example, `[]a]' matches `]' or `a'. To include a `-', write - `-' as the first character in the set, or put it immediately after - a range. (You can replace one individual character C with the - range `C-C' to make a place to put the `-'.) There is no way to - write a set containing just `-' and `]'. - - To include `^' in a set, put it anywhere but at the beginning of - the set. - -`[^ ... ]' - `[^' begins a "complement character set", which matches any - character except the ones specified. Thus, `[^a-z0-9A-Z]' matches - all characters _except_ letters and digits. - - `^' is not special in a character set unless it is the first - character. The character following the `^' is treated as if it - were first (thus, `-' and `]' are not special there). - - Note that a complement character set can match a newline, unless - newline is mentioned as one of the characters not to match. - -`^' - is a special character that matches the empty string, but only at - the beginning of a line in the text being matched. Otherwise it - fails to match anything. Thus, `^foo' matches a `foo' that occurs - at the beginning of a line. - - When matching a string instead of a buffer, `^' matches at the - beginning of the string or after a newline character `\n'. - -`$' - is similar to `^' but matches only at the end of a line. Thus, - `x+$' matches a string of one `x' or more at the end of a line. - - When matching a string instead of a buffer, `$' matches at the end - of the string or before a newline character `\n'. - -`\' - has two functions: it quotes the special characters (including - `\'), and it introduces additional special constructs. - - Because `\' quotes special characters, `\$' is a regular - expression that matches only `$', and `\[' is a regular expression - that matches only `[', and so on. - - Note that `\' also has special meaning in the read syntax of Lisp - strings (*note String Type::), and must be quoted with `\'. For - example, the regular expression that matches the `\' character is - `\\'. To write a Lisp string that contains the characters `\\', - Lisp syntax requires you to quote each `\' with another `\'. - Therefore, the read syntax for a regular expression matching `\' - is `"\\\\"'. - - *Please note:* For historical compatibility, special characters are -treated as ordinary ones if they are in contexts where their special -meanings make no sense. For example, `*foo' treats `*' as ordinary -since there is no preceding expression on which the `*' can act. It is -poor practice to depend on this behavior; quote the special character -anyway, regardless of where it appears. - - For the most part, `\' followed by any character matches only that -character. However, there are several exceptions: characters that, -when preceded by `\', are special constructs. Such characters are -always ordinary when encountered on their own. Here is a table of `\' -constructs: - -`\|' - specifies an alternative. Two regular expressions A and B with - `\|' in between form an expression that matches anything that - either A or B matches. - - Thus, `foo\|bar' matches either `foo' or `bar' but no other string. - - `\|' applies to the largest possible surrounding expressions. - Only a surrounding `\( ... \)' grouping can limit the grouping - power of `\|'. - - Full backtracking capability exists to handle multiple uses of - `\|'. - -`\( ... \)' - is a grouping construct that serves three purposes: - - 1. To enclose a set of `\|' alternatives for other operations. - Thus, `\(foo\|bar\)x' matches either `foox' or `barx'. - - 2. To enclose an expression for a suffix operator such as `*' to - act on. Thus, `ba\(na\)*' matches `bananana', etc., with any - (zero or more) number of `na' strings. - - 3. To record a matched substring for future reference. - - This last application is not a consequence of the idea of a - parenthetical grouping; it is a separate feature that happens to be - assigned as a second meaning to the same `\( ... \)' construct - because there is no conflict in practice between the two meanings. - Here is an explanation of this feature: - -`\DIGIT' - matches the same text that matched the DIGITth occurrence of a `\( - ... \)' construct. - - In other words, after the end of a `\( ... \)' construct. the - matcher remembers the beginning and end of the text matched by that - construct. Then, later on in the regular expression, you can use - `\' followed by DIGIT to match that same text, whatever it may - have been. - - The strings matching the first nine `\( ... \)' constructs - appearing in a regular expression are assigned numbers 1 through 9 - in the order that the open parentheses appear in the regular - expression. So you can use `\1' through `\9' to refer to the text - matched by the corresponding `\( ... \)' constructs. - - For example, `\(.*\)\1' matches any newline-free string that is - composed of two identical halves. The `\(.*\)' matches the first - half, which may be anything, but the `\1' that follows must match - the same exact text. - -`\(?: ... \)' - is called a "shy" grouping operator, and it is used just like `\( - ... \)', except that it does not cause the matched substring to be - recorded for future reference. - - This is useful when you need a lot of grouping `\( ... \)' - constructs, but only want to remember one or two. Then you can use - not want to remember them for later use with `match-string'. - - Using `\(?: ... \)' rather than `\( ... \)' when you don't need - the captured substrings ought to speed up your programs some, - since it shortens the code path followed by the regular expression - engine, as well as the amount of memory allocation and string - copying it must do. The actual performance gain to be observed - has not been measured or quantified as of this writing. - - The shy grouping operator has been borrowed from Perl, and has not - been available prior to XEmacs 20.3, nor is it available in FSF - Emacs. - -`\w' - matches any word-constituent character. The editor syntax table - determines which characters these are. *Note Syntax Tables::. - -`\W' - matches any character that is not a word constituent. - -`\sCODE' - matches any character whose syntax is CODE. Here CODE is a - character that represents a syntax code: thus, `w' for word - constituent, `-' for whitespace, `(' for open parenthesis, etc. - *Note Syntax Tables::, for a list of syntax codes and the - characters that stand for them. - -`\SCODE' - matches any character whose syntax is not CODE. - - The following regular expression constructs match the empty -string--that is, they don't use up any characters--but whether they -match depends on the context. - -`\`' - matches the empty string, but only at the beginning of the buffer - or string being matched against. - -`\'' - matches the empty string, but only at the end of the buffer or - string being matched against. - -`\=' - matches the empty string, but only at point. (This construct is - not defined when matching against a string.) - -`\b' - matches the empty string, but only at the beginning or end of a - word. Thus, `\bfoo\b' matches any occurrence of `foo' as a - separate word. `\bballs?\b' matches `ball' or `balls' as a - separate word. - -`\B' - matches the empty string, but _not_ at the beginning or end of a - word. - -`\<' - matches the empty string, but only at the beginning of a word. - -`\>' - matches the empty string, but only at the end of a word. - - Not every string is a valid regular expression. For example, a -string with unbalanced square brackets is invalid (with a few -exceptions, such as `[]]'), and so is a string that ends with a single -`\'. If an invalid regular expression is passed to any of the search -functions, an `invalid-regexp' error is signaled. - - - Function: regexp-quote string - This function returns a regular expression string that matches - exactly STRING and nothing else. This allows you to request an - exact string match when calling a function that wants a regular - expression. - - (regexp-quote "^The cat$") - => "\\^The cat\\$" - - One use of `regexp-quote' is to combine an exact string match with - context described as a regular expression. For example, this - searches for the string that is the value of `string', surrounded - by whitespace: - - (re-search-forward - (concat "\\s-" (regexp-quote string) "\\s-")) + - Command: downcase-word count &optional buffer + 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'. + + When `downcase-word' is called interactively, COUNT is set to the + numeric prefix argument. + + - Command: upcase-word count &optional buffer + 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'. + + When `upcase-word' is called interactively, COUNT is set to the + numeric prefix argument.  -File: lispref.info, Node: Regexp Example, Prev: Syntax of Regexps, Up: Regular Expressions +File: lispref.info, Node: Text Properties, Next: Substitution, Prev: Case Changes, Up: Text -Complex Regexp Example ----------------------- +Text Properties +=============== - Here is a complicated regexp, used by XEmacs to recognize the end of -a sentence together with any whitespace that follows. It is the value -of the variable `sentence-end'. + 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. - First, we show the regexp as a string in Lisp syntax to distinguish -spaces from tab characters. The string constant begins and ends with a -double-quote. `\"' stands for a double-quote as part of the string, -`\\' for a backslash as part of the string, `\t' for a tab and `\n' for -a newline. + 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. - "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*" + 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. - In contrast, if you evaluate the variable `sentence-end', you will -see the following: + Note that FSF Emacs also looks at the `category' property to find +defaults for text properties. We consider this too bogus to implement. - sentence-end - => - "[.?!][]\"')}]*\\($\\| $\\| \\| \\)[ - ]*" + Copying text between strings and buffers preserves the properties +along with the characters; this includes such diverse functions as +`substring', `insert', and `buffer-substring'. -In this output, tab and newline appear as themselves. +* Menu: - This regular expression contains four parts in succession and can be -deciphered as follows: +* 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. -`[.?!]' - The first part of the pattern is a character set that matches any - one of three characters: period, question mark, and exclamation - mark. The match must begin with one of these three characters. + +File: lispref.info, Node: Examining Properties, Next: Changing Properties, Up: Text Properties -`[]\"')}]*' - The second part of the pattern matches any closing braces and - quotation marks, zero or more of them, that may follow the period, - question mark or exclamation mark. The `\"' is Lisp syntax for a - double-quote in a string. The `*' at the end indicates that the - immediately preceding regular expression (a character set, in this - case) may be repeated zero or more times. +Examining Text Properties +------------------------- -`\\($\\| $\\|\t\\| \\)' - The third part of the pattern matches the whitespace that follows - the end of a sentence: the end of a line, or a tab, or two spaces. - The double backslashes mark the parentheses and vertical bars as - regular expression syntax; the parentheses delimit a group and the - vertical bars separate alternatives. The dollar sign is used to - match the end of a line. + 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. -`[ \t\n]*' - Finally, the last part of the pattern matches any additional - whitespace beyond the minimum needed to end a sentence. + 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: Regexp Search, Next: POSIX Regexps, Prev: Regular Expressions, Up: Searching and Matching - -Regular Expression Searching -============================ - - In XEmacs, you can search for the next match for a regexp either -incrementally or not. Incremental search commands are described in the -`The XEmacs Reference Manual'. *Note Regular Expression Search: -(emacs)Regexp Search. Here we describe only the search functions -useful in programs. The principal one is `re-search-forward'. - - - Command: re-search-forward regexp &optional limit noerror repeat - This function searches forward in the current buffer for a string - of text that is matched by the regular expression REGEXP. The - function skips over any amount of text that is not matched by - REGEXP, and leaves point at the end of the first match found. It - returns the new value of point. - - If LIMIT is non-`nil' (it must be a position in the current - buffer), then it is the upper bound to the search. No match - extending after that position is accepted. - - What happens when the search fails depends on the value of - NOERROR. If NOERROR is `nil', a `search-failed' error is - signaled. If NOERROR is `t', `re-search-forward' does nothing and - returns `nil'. If NOERROR is neither `nil' nor `t', then - `re-search-forward' moves point to LIMIT (or the end of the - buffer) and returns `nil'. - - If REPEAT is supplied (it must be a positive number), then the - search is repeated that many times (each time starting at the end - of the previous time's match). If these successive searches - succeed, the function succeeds, moving point and returning its new - value. Otherwise the search fails. - - In the following example, point is initially before the `T'. - Evaluating the search call moves point to the end of that line - (between the `t' of `hat' and the newline). + - Function: get-text-property pos prop &optional object at-flag + 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. - ---------- Buffer: foo ---------- - I read "-!-The cat in the hat - comes back" twice. - ---------- Buffer: foo ---------- - - (re-search-forward "[a-z]+" nil t 5) - => 27 - - ---------- Buffer: foo ---------- - I read "The cat in the hat-!- - comes back" twice. - ---------- Buffer: foo ---------- + - Function: get-char-property pos prop &optional object at-flag + This function is like `get-text-property', except that it checks + all extents, not just text-property extents. - - Command: re-search-backward regexp &optional limit noerror repeat - This function searches backward in the current buffer for a string - of text that is matched by the regular expression REGEXP, leaving - point at the beginning of the first text found. - - This function is analogous to `re-search-forward', but they are not - simple mirror images. `re-search-forward' finds the match whose - beginning is as close as possible to the starting point. If - `re-search-backward' were a perfect mirror image, it would find the - match whose end is as close as possible. However, in fact it - finds the match whose beginning is as close as possible. The - reason is that matching a regular expression at a given spot - always works from beginning to end, and starts at a specified - beginning position. - - A true mirror-image of `re-search-forward' would require a special - feature for matching regexps from end to beginning. It's not - worth the trouble of implementing that. - - - Function: string-match regexp string &optional start - This function returns the index of the start of the first match for - the regular expression REGEXP in STRING, or `nil' if there is no - match. If START is non-`nil', the search starts at that index in - STRING. - - For example, - - (string-match - "quick" "The quick brown fox jumped quickly.") - => 4 - (string-match - "quick" "The quick brown fox jumped quickly." 8) - => 27 - - The index of the first character of the string is 0, the index of - the second character is 1, and so on. - - After this function returns, the index of the first character - beyond the match is available as `(match-end 0)'. *Note Match - Data::. - - (string-match - "quick" "The quick brown fox jumped quickly." 8) - => 27 - - (match-end 0) - => 32 - - Function: split-string string &optional pattern - This function splits STRING to substrings delimited by PATTERN, - and returns a list of substrings. If PATTERN is omitted, it - defaults to `[ \f\t\n\r\v]+', which means that it splits STRING by - white-space. + - 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. - (split-string "foo bar") - => ("foo" "bar") - - (split-string "something") - => ("something") - - (split-string "a:b:c" ":") - => ("a" "b" "c") - - (split-string ":a::b:c" ":") - => ("" "a" "" "b" "c") - - - Function: split-path path - This function splits a search path into a list of strings. The - path components are separated with the characters specified with - `path-separator'. Under Unix, `path-separator' will normally be - `:', while under Windows, it will be `;'. - - - Function: looking-at regexp - This function determines whether the text in the current buffer - directly following point matches the regular expression REGEXP. - "Directly following" means precisely that: the search is - "anchored" and it can succeed only starting with the first - character following point. The result is `t' if so, `nil' - otherwise. - - This function does not move point, but it updates the match data, - which you can access using `match-beginning' and `match-end'. - *Note Match Data::. - - In this example, point is located directly before the `T'. If it - were anywhere else, the result would be `nil'. + - 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: - ---------- Buffer: foo ---------- - I read "-!-The cat in the hat - comes back" twice. - ---------- Buffer: foo ---------- - - (looking-at "The cat in the hat$") - => t + (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  -File: lispref.info, Node: POSIX Regexps, Next: Search and Replace, Prev: Regexp Search, Up: Searching and Matching - -POSIX Regular Expression Searching -================================== - - The usual regular expression functions do backtracking when necessary -to handle the `\|' and repetition constructs, but they continue this -only until they find _some_ match. Then they succeed and report the -first match found. - - This section describes alternative search functions which perform the -full backtracking specified by the POSIX standard for regular expression -matching. They continue backtracking until they have tried all -possibilities and found all matches, so they can report the longest -match, as required by POSIX. This is much slower, so use these -functions only when you really need the longest match. - - In Emacs versions prior to 19.29, these functions did not exist, and -the functions described above implemented full POSIX backtracking. - - - Function: posix-search-forward regexp &optional limit noerror repeat - This is like `re-search-forward' except that it performs the full - backtracking specified by the POSIX standard for regular expression - matching. - - - Function: posix-search-backward regexp &optional limit noerror repeat - This is like `re-search-backward' except that it performs the full - backtracking specified by the POSIX standard for regular expression - matching. - - - Function: posix-looking-at regexp - This is like `looking-at' except that it performs the full - backtracking specified by the POSIX standard for regular expression - matching. - - - Function: posix-string-match regexp string &optional start - This is like `string-match' except that it performs the full - backtracking specified by the POSIX standard for regular expression - matching. +File: lispref.info, Node: Changing Properties, Next: Property Search, Prev: Examining Properties, Up: Text Properties - -File: lispref.info, Node: Search and Replace, Next: Match Data, Prev: POSIX Regexps, Up: Searching and Matching +Changing Text Properties +------------------------ -Search and Replace -================== + 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. - - Function: perform-replace from-string replacements query-flag - regexp-flag delimited-flag &optional repeat-count map - This function is the guts of `query-replace' and related commands. - It searches for occurrences of FROM-STRING and replaces some or - all of them. If QUERY-FLAG is `nil', it replaces all occurrences; - otherwise, it asks the user what to do about each one. + 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::). - If REGEXP-FLAG is non-`nil', then FROM-STRING is considered a - regular expression; otherwise, it must match literally. If - DELIMITED-FLAG is non-`nil', then only replacements surrounded by - word boundaries are considered. + - 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 argument REPLACEMENTS specifies what to replace occurrences - with. If it is a string, that string is used. It can also be a - list of strings, to be used in cyclic order. + - 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. - If REPEAT-COUNT is non-`nil', it should be an integer. Then it - specifies how many times to use each of the strings in the - REPLACEMENTS list before advancing cyclicly to the next one. + 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. - Normally, the keymap `query-replace-map' defines the possible user - responses for queries. The argument MAP, if non-`nil', is a - keymap to use instead of `query-replace-map'. + 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). - - Variable: query-replace-map - This variable holds a special keymap that defines the valid user - responses for `query-replace' and related functions, as well as - `y-or-n-p' and `map-y-or-n-p'. It is unusual in two ways: + For example, here is how to set the `comment' and `face' + properties of a range of text: - * The "key bindings" are not commands, just symbols that are - meaningful to the functions that use this map. + (add-text-properties START END + '(comment t face highlight)) - * Prefix keys are not supported; each key binding must be for a - single event key sequence. This is because the functions - don't use read key sequence to get the input; instead, they - read a single event and look it up "by hand." + - 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. - Here are the meaningful "bindings" for `query-replace-map'. Several -of them are meaningful only for `query-replace' and friends. + 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. -`act' - Do take the action being considered--in other words, "yes." + (remove-text-properties START END '(face nil)) -`skip' - Do not take action for this question--in other words, "no." + 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). -`exit' - Answer this question "no," and give up on the entire series of - questions, assuming that the answers will be "no." + - 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. -`act-and-exit' - Answer this question "yes," and give up on the entire series of - questions, assuming that subsequent answers will be "no." + The argument PROPS is the new property list. It should be a list + whose elements are property names alternating with corresponding + values. -`act-and-show' - Answer this question "yes," but show the results--don't advance yet - to the next question. + After `set-text-properties' returns, all the characters in the + specified range have identical properties. -`automatic' - Answer this question and all subsequent questions in the series - with "yes," without further user interaction. + If PROPS is `nil', the effect is to get rid of all properties from + the specified range of text. Here's an example: -`backup' - Move back to the previous place that a question was asked about. + (set-text-properties START END nil) -`edit' - Enter a recursive edit to deal with this question--instead of any - other action that would normally be taken. + See also the function `buffer-substring-without-properties' (*note +Buffer Contents::) which copies text from the buffer but does not copy +its properties. -`delete-and-edit' - Delete the text being considered, then enter a recursive edit to - replace it. + +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 backward 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 backward 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. -`recenter' - Redisplay and center the window, then ask the same question again. + +File: lispref.info, Node: Special Properties, Next: Saving Properties, Prev: Property Search, Up: Text Properties -`quit' - Perform a quit right away. Only `y-or-n-p' and related functions - use this answer. +Properties with Special Meanings +-------------------------------- -`help' - Display some help, then ask again. + The predefined properties are the same as those for extents. *Note +Extent Properties::.  -File: lispref.info, Node: Match Data, Next: Searching and Case, Prev: Search and Replace, Up: Searching and Matching +File: lispref.info, Node: Saving Properties, Prev: Special Properties, Up: Text Properties -The Match Data -============== +Saving Text Properties in Files +------------------------------- - XEmacs keeps track of the positions of the start and end of segments -of text found during a regular expression search. This means, for -example, that you can search for a complex pattern, such as a date in -an Rmail message, and then extract parts of the match under control of -the pattern. + 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. - Because the match data normally describe the most recent search only, -you must be careful not to do another search inadvertently between the -search you wish to refer back to and the use of the match data. If you -can't avoid another intervening search, you must save and restore the -match data around it, to prevent it from being overwritten. + +File: lispref.info, Node: Substitution, Next: Registers, Prev: Text Properties, Up: Text -* Menu: +Substituting for a Character Code +================================= -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Replacing Match:: Replacing a substring that was matched. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. + The following functions replace characters within a specified region +based on their character codes. - -File: lispref.info, Node: Simple Match Data, Next: Replacing Match, Up: Match Data + - 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. -Simple Match Data Access ------------------------- + 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::). - This section explains how to use the match data to find out what was -matched by the last search or match operation. - - You can ask about the entire matching text, or about a particular -parenthetical subexpression of a regular expression. The COUNT -argument in the functions below specifies which. If COUNT is zero, you -are asking about the entire match. If COUNT is positive, it specifies -which subexpression you want. - - Recall that the subexpressions of a regular expression are those -expressions grouped with escaped parentheses, `\(...\)'. The COUNTth -subexpression is found by counting occurrences of `\(' from the -beginning of the whole regular expression. The first subexpression is -numbered 1, the second 2, and so on. Only regular expressions can have -subexpressions--after a simple string search, the only information -available is about the entire match. - - - Function: match-string count &optional in-string - This function returns, as a string, the text matched in the last - search or match operation. It returns the entire text if COUNT is - zero, or just the portion corresponding to the COUNTth - parenthetical subexpression, if COUNT is positive. If COUNT is - out of range, or if that subexpression didn't match anything, the - value is `nil'. + `subst-char-in-region' does not move point and returns `nil'. - If the last such operation was done against a string with - `string-match', then you should pass the same string as the - argument IN-STRING. Otherwise, after a buffer search or match, - you should omit IN-STRING or pass `nil' for it; but you should - make sure that the current buffer when you call `match-string' is - the one in which you did the searching or matching. - - - Function: match-beginning count - This function returns the position of the start of text matched by - the last regular expression searched for, or a subexpression of it. - - If COUNT is zero, then the value is the position of the start of - the entire match. Otherwise, COUNT specifies a subexpression in - the regular expression, and the value of the function is the - starting position of the match for that subexpression. - - The value is `nil' for a subexpression inside a `\|' alternative - that wasn't used in the match. - - - Function: match-end count - This function is like `match-beginning' except that it returns the - position of the end of the match, rather than the position of the - beginning. - - Here is an example of using the match data, with a comment showing -the positions within the text: - - (string-match "\\(qu\\)\\(ick\\)" - "The quick fox jumped quickly.") - ;0123456789 - => 4 - - (match-string 0 "The quick fox jumped quickly.") - => "quick" - (match-string 1 "The quick fox jumped quickly.") - => "qu" - (match-string 2 "The quick fox jumped quickly.") - => "ick" - - (match-beginning 1) ; The beginning of the match - => 4 ; with `qu' is at index 4. - - (match-beginning 2) ; The beginning of the match - => 6 ; with `ick' is at index 6. - - (match-end 1) ; The end of the match - => 6 ; with `qu' is at index 6. - - (match-end 2) ; The end of the match - => 9 ; with `ick' is at index 9. - - Here is another example. Point is initially located at the beginning -of the line. Searching moves point to between the space and the word -`in'. The beginning of the entire match is at the 9th character of the -buffer (`T'), and the beginning of the match for the first -subexpression is at the 13th character (`c'). - - (list - (re-search-forward "The \\(cat \\)") - (match-beginning 0) - (match-beginning 1)) - => (9 9 13) - - ---------- Buffer: foo ---------- - I read "The cat -!-in the hat comes back" twice. - ^ ^ - 9 13 - ---------- Buffer: foo ---------- - -(In this case, the index returned is a buffer position; the first -character of the buffer counts as 1.) + ---------- Buffer: foo ---------- + This is the contents of the buffer before. + ---------- Buffer: foo ---------- + + (subst-char-in-region 1 20 ?i ?X) + => nil + + ---------- Buffer: foo ---------- + ThXs Xs the contents of the buffer before. + ---------- Buffer: foo ---------- + + - Function: translate-region start end table + This function applies a translation table to the characters in the + buffer between positions START and END. The translation table + TABLE can be either a string, a vector, or a char-table. + + If TABLE is a string, its Nth element is the mapping for the + character with code N. + + If TABLE is a vector, its Nth element is the mapping for character + with code N. Legal mappings are characters, strings, or `nil' + (meaning don't replace.) + + If TABLE is a char-table, its elements describe the mapping + between characters and their replacements. The char-table should + be of type `char' or `generic'. + + When the TABLE is a string or vector and its length is less than + the total number of characters (256 without Mule), any characters + with codes larger than the length of TABLE are not altered by the + translation. + + The return value of `translate-region' is the number of characters + that were actually changed by the translation. This does not + count characters that were mapped into themselves in the + translation table. + + *NOTE*: Prior to XEmacs 21.2, the TABLE argument was allowed only + to be a string. This is still the case in FSF Emacs. + + The following example creates a char-table that is passed to + `translate-region', which translates character `a' to `the letter + a', removes character `b', and translates character `c' to newline. + + ---------- Buffer: foo ---------- + Here is a sentence in the buffer. + ---------- Buffer: foo ---------- + + (let ((table (make-char-table 'generic))) + (put-char-table ?a "the letter a" table) + (put-char-table ?b "" table) + (put-char-table ?c ?\n table) + (translate-region (point-min) (point-max) table)) + => 3 + + ---------- Buffer: foo ---------- + Here is the letter a senten + e in the uffer. + ---------- Buffer: foo ----------  -File: lispref.info, Node: Replacing Match, Next: Entire Match Data, Prev: Simple Match Data, Up: Match Data +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 register + This function returns the contents of the register REGISTER, or + `nil' if it has no contents. + + - Function: set-register register value + This function sets the contents of register REGISTER 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 register + This command displays what is contained in register REGISTER. + + - Command: insert-register register &optional beforep + This command inserts contents of register REGISTER into the current + buffer. + + Normally, this command puts point before the inserted text, and the + mark after it. However, if the optional second argument BEFOREP + is non-`nil', it puts the mark before and point after. You can + pass a non-`nil' second argument BEFOREP to this function + interactively by supplying any prefix argument. + + If the register contains a rectangle, then the rectangle is + inserted with its upper left corner at point. This means that + text is inserted in the current line and underneath it on + successive lines. + + If the register contains something other than saved text (a + string) or a rectangle (a list), currently useless things happen. + This may be changed in the future. -Replacing the Text That Matched -------------------------------- + +File: lispref.info, Node: Transposition, Next: Change Hooks, Prev: Registers, Up: Text - This function replaces the text matched by the last search with -REPLACEMENT. - - - Function: replace-match replacement &optional fixedcase literal - string - This function replaces the text in the buffer (or in STRING) that - was matched by the last search. It replaces that text with - REPLACEMENT. - - If you did the last search in a buffer, you should specify `nil' - for STRING. Then `replace-match' does the replacement by editing - the buffer; it leaves point at the end of the replacement text, - and returns `t'. - - If you did the search in a string, pass the same string as STRING. - Then `replace-match' does the replacement by constructing and - returning a new string. - - If FIXEDCASE is non-`nil', then the case of the replacement text - is not changed; otherwise, the replacement text is converted to a - different case depending upon the capitalization of the text to be - replaced. If the original text is all upper case, the replacement - text is converted to upper case. If the first word of the - original text is capitalized, then the first word of the - replacement text is capitalized. If the original text contains - just one word, and that word is a capital letter, `replace-match' - considers this a capitalized first word rather than all upper case. - - If `case-replace' is `nil', then case conversion is not done, - regardless of the value of FIXED-CASE. *Note Searching and Case::. - - If LITERAL is non-`nil', then REPLACEMENT is inserted exactly as - it is, the only alterations being case changes as needed. If it - is `nil' (the default), then the character `\' is treated - specially. If a `\' appears in REPLACEMENT, then it must be part - of one of the following sequences: +Transposition of Text +===================== - `\&' - `\&' stands for the entire text being replaced. + This subroutine is used by the transposition commands. - `\N' - `\N', where N is a digit, stands for the text that matched - the Nth subexpression in the original regexp. Subexpressions - are those expressions grouped inside `\(...\)'. + - 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. - `\\' - `\\' stands for a single `\' in the replacement text. + 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.