-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Sorting, Next: Columns, Prev: Auto Filling, Up: Text
+
+Sorting Text
+============
+
+ The sorting functions described in this section all rearrange text in
+a buffer. This is in contrast to the function `sort', which rearranges
+the order of the elements of a list (*note Rearrangement::). The
+values returned by these functions are not meaningful.
+
+ - Function: sort-subr reverse nextrecfun endrecfun &optional
+ startkeyfun endkeyfun
+ This function is the general text-sorting routine that divides a
+ buffer into records and sorts them. Most of the commands in this
+ section use this function.
+
+ To understand how `sort-subr' works, consider the whole accessible
+ portion of the buffer as being divided into disjoint pieces called
+ "sort records". The records may or may not be contiguous; they may
+ not overlap. A portion of each sort record (perhaps all of it) is
+ designated as the sort key. Sorting rearranges the records in
+ order by their sort keys.
+
+ Usually, the records are rearranged in order of ascending sort key.
+ If the first argument to the `sort-subr' function, REVERSE, is
+ non-`nil', the sort records are rearranged in order of descending
+ sort key.
+
+ The next four arguments to `sort-subr' are functions that are
+ called to move point across a sort record. They are called many
+ times from within `sort-subr'.
+
+ 1. NEXTRECFUN is called with point at the end of a record. This
+ function moves point to the start of the next record. The
+ first record is assumed to start at the position of point
+ when `sort-subr' is called. Therefore, you should usually
+ move point to the beginning of the buffer before calling
+ `sort-subr'.
+
+ This function can indicate there are no more sort records by
+ leaving point at the end of the buffer.
+
+ 2. ENDRECFUN is called with point within a record. It moves
+ point to the end of the record.
+
+ 3. STARTKEYFUN is called to move point from the start of a
+ record to the start of the sort key. This argument is
+ optional; if it is omitted, the whole record is the sort key.
+ If supplied, the function should either return a non-`nil'
+ value to be used as the sort key, or return `nil' to indicate
+ that the sort key is in the buffer starting at point. In the
+ latter case, ENDKEYFUN is called to find the end of the sort
+ key.
+
+ 4. ENDKEYFUN is called to move point from the start of the sort
+ key to the end of the sort key. This argument is optional.
+ If STARTKEYFUN returns `nil' and this argument is omitted (or
+ `nil'), then the sort key extends to the end of the record.
+ There is no need for ENDKEYFUN if STARTKEYFUN returns a
+ non-`nil' value.
+
+ As an example of `sort-subr', here is the complete function
+ definition for `sort-lines':
+
+ ;; Note that the first two lines of doc string
+ ;; are effectively one line when viewed by a user.
+ (defun sort-lines (reverse 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: Columns, Next: Indentation, Prev: Sorting, Up: Text
+
+Counting Columns
+================
+
+ The column functions convert between a character position (counting
+characters from the beginning of the buffer) and a column position
+(counting screen characters from the beginning of a line).
+
+ A character counts according to the number of columns it occupies on
+the screen. This means control characters count as occupying 2 or 4
+columns, depending upon the value of `ctl-arrow', and tabs count as
+occupying a number of columns that depends on the value of `tab-width'
+and on the column where the tab begins. *Note Usual Display::.
+
+ Column number computations ignore the width of the window and the
+amount of horizontal scrolling. Consequently, a column value can be
+arbitrarily high. The first (or leftmost) column is numbered 0.
+
+ - Function: current-column &optional buffer
+ This function returns the horizontal position of point, measured in
+ columns, counting from 0 at the left margin.
+
+ 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.)
+
+ Ignores the finite width of frame displaying the buffer, which
+ means that this function may return values greater than
+ `(frame-width)'.
+
+ 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.
+
+ If BUFFER is nil, the current buffer is assumed.
+
+ For an example of using `current-column', see the description of
+ `count-lines' in *Note Text Lines::.
+
+ - 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.
+
+ If column COLUMN is beyond the end of the line, point moves to the
+ end of the line. If COLUMN is negative, point moves to the
+ beginning of the line.
+
+ If it is impossible to move to column COLUMN because that is in
+ the middle of a multicolumn character such as a tab, point moves
+ to the end of that character. However, if FORCE is non-`nil', and
+ COLUMN is in the middle of a tab, then `move-to-column' converts
+ the tab into spaces so that it can move precisely to column
+ COLUMN. Other multicolumn characters can cause anomalies despite
+ FORCE, since there is no way to split them.
+
+ The argument FORCE also has an effect if the line isn't long
+ enough to reach column COLUMN; in that case, 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.
+
+ If COLUMN is not a non-negative integer, an error is signaled.
+
+ The return value is the column number actually moved to.
+
+\1f
+File: lispref.info, Node: Indentation, Next: Case Changes, Prev: Columns, Up: Text
+
+Indentation
+===========
+
+ The indentation functions are used to examine, move to, and change
+whitespace that is at the beginning of a line. Some of the functions
+can also change whitespace elsewhere on a line. Columns and indentation
+count from zero at the left margin.
+
+* Menu:
+
+* Primitive Indent:: Functions used to count and insert indentation.
+* Mode-Specific Indent:: Customize indentation for different modes.
+* Region Indent:: Indent all the lines in a region.
+* Relative Indent:: Indent the current line based on previous lines.
+* Indent Tabs:: Adjustable, typewriter-like tab stops.
+* Motion by Indent:: Move to first non-blank character.
+
+\1f
+File: lispref.info, Node: Primitive Indent, Next: Mode-Specific Indent, Up: Indentation
+
+Indentation Primitives
+----------------------
+
+ This section describes the primitive functions used to count and
+insert indentation. The functions in the following sections use these
+primitives.
+
+ - Function: current-indentation &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.
+
+\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: 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').
+
+\1f
+File: lispref.info, Node: Relative Indent, Next: Indent Tabs, Prev: Region Indent, Up: Indentation
+
+Indentation Relative to Previous Lines
+--------------------------------------
+
+ 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.
+
+ 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 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: Indent Tabs, Next: Motion by Indent, Prev: Relative Indent, Up: Indentation
+
+Adjustable "Tab Stops"
+----------------------
+
+ This section explains the mechanism for user-specified "tab stops"
+and the mechanisms that use and set them. The name "tab stops" is used
+because the feature is similar to that of the tab stops on a
+typewriter. The feature works by inserting an appropriate number of
+spaces and tab characters to reach the next tab stop column; it does not
+affect the display of tab characters in the buffer (*note Usual
+Display::). Note that the <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.
+
+\1f
+File: lispref.info, Node: Motion by Indent, Prev: Indent Tabs, Up: Indentation
+
+Indentation-Based Motion Commands
+---------------------------------
+
+ 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 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 ----------
+ This is the contents of the 5th foo.
+ ---------- Buffer: foo ----------
+
+ (capitalize-region 1 44)
+ => nil
+
+ ---------- Buffer: foo ----------
+ This Is The Contents Of The 5th Foo.
+ ---------- Buffer: foo ----------
+
+ - 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'.
+
+ When `downcase-region' is called interactively, START and END are
+ point and the mark, with the smallest first.
+
+ - 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'.
+
+ When `upcase-region' is called interactively, START and END are
+ point and the mark, with the smallest first.
+
+ - 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'.
+
+ If point is in the middle of a word, the part of the word before
+ point is ignored when moving forward. The rest is treated as an
+ entire word.
+
+ When `capitalize-word' is called interactively, COUNT is set to
+ the numeric prefix argument.
+
+ - 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: Text Properties, Next: Substitution, Prev: Case Changes, Up: Text
+
+Text Properties
+===============
+
+ 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.
+
+ 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.
+
+ 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.
+
+ Note that FSF Emacs also looks at the `category' property to find
+defaults for text properties. We consider this too bogus to implement.
+
+ Copying text between strings and buffers preserves the properties
+along with the characters; this includes such diverse functions as
+`substring', `insert', and `buffer-substring'.
+
+* Menu:
+
+* 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.
+
+\1f
File: lispref.info, Node: Examining Properties, Next: Changing Properties, Up: Text Properties
Examining Text Properties
positions in a string start from 0, whereas positions in a buffer start
from 1.)
- - Function: get-text-property pos prop &optional object
+ - 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.
- - Function: get-char-property pos prop &optional object
+ - 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.
if LIMIT equals POS.
- Function: previous-property-change pos &optional object limit
- This is like `next-property-change', but scans back from POS
+ 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 back from
+ 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.
represents a rectangle; its elements are strings, one per line of
the rectangle.
- - Function: get-register reg
- This function returns the contents of the register REG, or `nil'
- if it has no contents.
+ - Function: get-register register
+ This function returns the contents of the register REGISTER, or
+ `nil' if it has no contents.
- - Function: set-register reg value
- This function sets the contents of register REG to VALUE. A
+ - 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 reg
- This command displays what is contained in register REG.
+ - Command: view-register register
+ This command displays what is contained in register REGISTER.
- - Command: insert-register reg &optional beforep
- This command inserts contents of register REG into the current
+ - 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
if LEAVE-MARKERS is non-`nil', `transpose-regions' does not do
this--it leaves all markers unrelocated.
-\1f
-File: lispref.info, Node: Change Hooks, Next: Transformations, Prev: Transposition, Up: Text
-
-Change Hooks
-============
-
- 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.
-
-\1f
-File: lispref.info, Node: Transformations, Prev: Change Hooks, Up: Text
-
-Textual transformations--MD5 and base64 support
-===============================================
-
- 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.
-
- 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.
-
- Emacs Lisp interface to MD5 consists of a single function `md5':
-
- - Function: md5 object &optional start end
- This function returns the MD5 message digest of OBJECT, a buffer
- or string.
-
- Optional arguments START and END denote positions for computing
- the digest of a portion of OBJECT.
-
- Some examples of usage:
-
- ;; 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"
-
- 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.
-
- The Lisp interface to base64 consists of four functions:
-
- - 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.
-
- 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.
-
- 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.
-
- `base64-encode-region' returns the length of the encoded text.
-
- ;; Encode the whole buffer in base64
- (base64-encode-region (point-min) (point-max))
-
- The function can also be used interactively, in which case it
- works on the currently active region.
-
- - Function: base64-encode-string string
- This function encodes STRING to base64, and returns the encoded
- string.
-
- For Mule, the same considerations apply as for
- `base64-encode-region'.
-
- (base64-encode-string "fubar")
- => "ZnViYXI="
-
- - 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.
-
- If the region was decoded correctly, `base64-decode-region' returns
- the length of the decoded region. If the decoding failed, `nil' is
- returned.
-
- ;; Decode a base64 buffer, and replace it with the decoded version
- (base64-decode-region (point-min) (point-max))
-
- - Function: base64-decode-string string
- This function decodes STRING to base64, and returns the decoded
- string. STRING should be valid base64-encoded text.
-
- If encoding was not possible, `nil' is returned.
-
- (base64-decode-string "ZnViYXI=")
- => "fubar"
-
- (base64-decode-string "totally bogus")
- => nil
-
-\1f
-File: lispref.info, Node: Searching and Matching, Next: Syntax Tables, Prev: Text, Up: Top
-
-Searching and Matching
-**********************
-
- 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.
-
-* Menu:
-
-* 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,...
-
- The `skip-chars...' functions also perform a kind of searching.
-*Note Skipping Characters::.
-
-\1f
-File: lispref.info, Node: String Search, Next: Regular Expressions, Up: Searching and Matching
-
-Searching for Strings
-=====================
-
- 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.
-
- - 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).
-
- 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':
-
- ---------- 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 ----------
-
- 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 `!'.
-
- ---------- Buffer: foo ----------
- -!-He said "Please! Find
- the ball boy!"
- ---------- Buffer: foo ----------
-
- (word-search-forward "Please find the ball, boy.")
- => 35
-
- ---------- Buffer: foo ----------
- He said "Please! Find
- the ball boy-!-!"
- ---------- 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.
-
- 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'.
-
- If REPEAT is non-`nil', then the search is repeated that many
- times. Point is positioned at the end of the last match.
-
- - 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.
-
-\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.
-
-* Menu:
-
-* Syntax of Regexps:: Rules for writing regular expressions.
-* Regexp Example:: Illustrates regular expression syntax.
-
-\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-"))
-
projects / chise / xemacs-chise.git / blobdiff