-This is ../info/lispref.info, produced by makeinfo version 3.12s from
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
-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 `\<f\w*\>'. The
+ resulting expression looks like this:
+
+ (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
+ (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.
\1f
-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.
+\1f
+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))
+\1f
+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
+\1f
+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 <TAB>
+key to indent properly for the language being edited. This section
+describes the mechanism of the <TAB> 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 <TAB> (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 <TAB> does,
+ but in some text modes, where <TAB> 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 <TAB> does, but in some text modes, where <TAB>
+ inserts a tab, `reindent-then-newline-and-indent' indents to the
+ column specified by `left-margin'.
\1f
-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
-**********************
+\1f
+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.
\1f
-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 <TAB> 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).
+\1f
+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'.
+
+\1f
+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.
-\1f
-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.
-\1f
-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.
\1f
-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.
+\1f
+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.)
-\1f
-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
\1f
-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
-\1f
-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.
+\1f
+File: lispref.info, Node: Property Search, Next: Special Properties, Prev: Changing Properties, Up: Text Properties
+
+Property Search Functions
+-------------------------
+
+ In typical use of text properties, most of the time several or many
+consecutive characters have the same value for a property. Rather than
+writing your programs to examine characters one by one, it is much
+faster to process chunks of text that have the same property value.
+
+ Here are functions you can use to do this. They use `eq' for
+comparing property values. In all cases, OBJECT defaults to the
+current buffer.
+
+ For high performance, it's very important to use the LIMIT argument
+to these functions, especially the ones that search for a single
+property--otherwise, they may spend a long time scanning to the end of
+the buffer, if the property you are interested in does not change.
+
+ Remember that a position is always between two characters; the
+position returned by these functions is between two characters with
+different properties.
+
+ - Function: next-property-change pos &optional object limit
+ The function scans the text forward from position POS in the
+ string or buffer OBJECT till it finds a change in some text
+ property, then returns the position of the change. In other
+ words, it returns the position of the first character beyond POS
+ whose properties are not identical to those of the character just
+ after POS.
+
+ If LIMIT is non-`nil', then the scan ends at position LIMIT. If
+ there is no property change before that point,
+ `next-property-change' returns LIMIT.
+
+ The value is `nil' if the properties remain unchanged all the way
+ to the end of OBJECT and LIMIT is `nil'. If the value is
+ non-`nil', it is a position greater than or equal to POS. The
+ value equals POS only when LIMIT equals POS.
+
+ Here is an example of how to scan the buffer by chunks of text
+ within which all properties are constant:
+
+ (while (not (eobp))
+ (let ((plist (text-properties-at (point)))
+ (next-change
+ (or (next-property-change (point) (current-buffer))
+ (point-max))))
+ Process text from point to NEXT-CHANGE...
+ (goto-char next-change)))
+
+ - Function: next-single-property-change pos prop &optional object limit
+ The function scans the text forward from position POS in the
+ string or buffer OBJECT till it finds a change in the PROP
+ property, then returns the position of the change. In other
+ words, it returns the position of the first character beyond POS
+ whose PROP property differs from that of the character just after
+ POS.
+
+ If LIMIT is non-`nil', then the scan ends at position LIMIT. If
+ there is no property change before that point,
+ `next-single-property-change' returns LIMIT.
+
+ The value is `nil' if the property remains unchanged all the way to
+ the end of OBJECT and LIMIT is `nil'. If the value is non-`nil',
+ it is a position greater than or equal to POS; it equals POS only
+ if LIMIT equals POS.
+
+ - Function: previous-property-change pos &optional object limit
+ This is like `next-property-change', but scans 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.
+\1f
+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::.
\1f
-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.
+\1f
+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.
-\1f
-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 ----------
\1f
-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
--------------------------------
+\1f
+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.
projects / chise / xemacs-chise.git / blobdiff