-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Examining Properties, Next: Changing Properties, Up: Text Properties
+
+Examining Text Properties
+-------------------------
+
+ The simplest way to examine text properties is to ask for the value
+of a particular property of a particular character. For that, use
+`get-text-property'. Use `text-properties-at' to get the entire
+property list of a character. *Note Property Search::, for functions
+to examine the properties of a number of characters at once.
+
+ 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.)
+
+ - Function: get-text-property pos prop &optional object
+ This function returns the value of the PROP property of the
+ character after position POS in OBJECT (a buffer or string). The
+ argument OBJECT is optional and defaults to the current buffer.
+
+ - Function: get-char-property pos prop &optional object
+ This function is like `get-text-property', except that it checks
+ all extents, not just text-property extents.
+
+
+ - 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.
+
+ - 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:
+
+ (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: Changing Properties, Next: Property Search, Prev: Examining Properties, Up: Text Properties
+
+Changing Text Properties
+------------------------
+
+ 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.
+
+ 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::).
+
+ - 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.
+
+ - 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.
+
+ 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.
+
+ 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).
+
+ For example, here is how to set the `comment' and `face'
+ properties of a range of text:
+
+ (add-text-properties START END
+ '(comment t face highlight))
+
+ - 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.
+
+ 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.
+
+ (remove-text-properties START END '(face nil))
+
+ 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).
+
+ - 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.
+
+ The argument PROPS is the new property list. It should be a list
+ whose elements are property names alternating with corresponding
+ values.
+
+ After `set-text-properties' returns, all the characters in the
+ specified range have identical properties.
+
+ If PROPS is `nil', the effect is to get rid of all properties from
+ the specified range of text. Here's an example:
+
+ (set-text-properties START END nil)
+
+ See also the function `buffer-substring-without-properties' (*note
+Buffer Contents::) which copies text from the buffer but does not copy
+its properties.
+
+\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 back from POS
+ instead of forward. If the value is non-`nil', it is a position
+ less than or equal to POS; it equals POS only if LIMIT equals POS.
+
+ - Function: previous-single-property-change pos prop &optional object
+ limit
+ This is like `next-single-property-change', but scans back from
+ POS instead of forward. If the value is non-`nil', it is a
+ position less than or equal to POS; it equals POS only if LIMIT
+ equals POS.
+
+ - Function: text-property-any start end prop value &optional object
+ This function returns non-`nil' if at least one character between
+ START and END has a property PROP whose value is VALUE. More
+ precisely, it returns the position of the first such character.
+ Otherwise, it returns `nil'.
+
+ The optional fifth argument, OBJECT, specifies the string or
+ buffer to scan. Positions are relative to OBJECT. The default
+ for OBJECT is the current buffer.
+
+ - Function: text-property-not-all start end prop value &optional object
+ This function returns non-`nil' if at least one character between
+ START and END has a property PROP whose value differs from VALUE.
+ More precisely, it returns the position of the first such
+ character. Otherwise, it returns `nil'.
+
+ The optional fifth argument, OBJECT, specifies the string or
+ buffer to scan. Positions are relative to OBJECT. The default
+ for OBJECT is the current buffer.
+
+\1f
+File: lispref.info, Node: Special Properties, Next: Saving Properties, Prev: Property Search, Up: Text Properties
+
+Properties with Special Meanings
+--------------------------------
+
+ The predefined properties are the same as those for extents. *Note
+Extent Properties::.
+
+\1f
+File: lispref.info, Node: Saving Properties, Prev: Special Properties, Up: Text Properties
+
+Saving Text Properties in Files
+-------------------------------
+
+ You can save text properties in files, and restore text properties
+when inserting the files, using these two hooks:
+
+ - Variable: write-region-annotate-functions
+ This variable's value is a list of functions for `write-region' to
+ run to encode text properties in some fashion as annotations to
+ the text being written in the file. *Note Writing to Files::.
+
+ Each function in the list is called with two arguments: the start
+ and end of the region to be written. These functions should not
+ alter the contents of the buffer. Instead, they should return
+ lists indicating annotations to write in the file in addition to
+ the text in the buffer.
+
+ Each function should return a list of elements of the form
+ `(POSITION . STRING)', where POSITION is an integer specifying the
+ relative position in the text to be written, and STRING is the
+ annotation to add there.
+
+ Each list returned by one of these functions must be already
+ sorted in increasing order by POSITION. If there is more than one
+ function, `write-region' merges the lists destructively into one
+ sorted list.
+
+ When `write-region' actually writes the text from the buffer to the
+ file, it intermixes the specified annotations at the corresponding
+ positions. All this takes place without modifying the buffer.
+
+ - Variable: after-insert-file-functions
+ This variable holds a list of functions for `insert-file-contents'
+ to call after inserting a file's contents. These functions should
+ scan the inserted text for annotations, and convert them to the
+ text properties they stand for.
+
+ Each function receives one argument, the length of the inserted
+ text; point indicates the start of that text. The function should
+ scan that text for annotations, delete them, and create the text
+ properties that the annotations specify. The function should
+ return the updated length of the inserted text, as it stands after
+ those changes. The value returned by one function becomes the
+ argument to the next function.
+
+ These functions should always return with point at the beginning of
+ the inserted text.
+
+ The intended use of `after-insert-file-functions' is for converting
+ some sort of textual annotations into actual text properties. But
+ other uses may be possible.
+
+ We invite users to write Lisp programs to store and retrieve text
+properties in files, using these hooks, and thus to experiment with
+various data formats and find good ones. Eventually we hope users will
+produce good, general extensions we can install in Emacs.
+
+ We suggest not trying to handle arbitrary Lisp objects as property
+names or property values--because a program that general is probably
+difficult to write, and slow. Instead, choose a set of possible data
+types that are reasonably flexible, and not too hard to encode.
+
+ *Note Format Conversion::, for a related feature.
+
+\1f
+File: lispref.info, Node: Substitution, Next: Registers, Prev: Text Properties, Up: Text
+
+Substituting for a Character Code
+=================================
+
+ The following functions replace characters within a specified region
+based on their character codes.
+
+ - 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.
+
+ 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::).
+
+ `subst-char-in-region' does not move point and returns `nil'.
+
+ ---------- 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: Registers, Next: Transposition, Prev: Substitution, Up: Text
+
+Registers
+=========
+
+ A register is a sort of variable used in XEmacs editing that can
+hold a marker, a string, a rectangle, a window configuration (of one
+frame), or a frame configuration (of all frames). Each register is
+named by a single character. All characters, including control and
+meta characters (but with the exception of `C-g'), can be used to name
+registers. Thus, there are 255 possible registers. A register is
+designated in Emacs Lisp by a character that is its name.
+
+ The functions in this section return unpredictable values unless
+otherwise stated.
+
+ - Variable: register-alist
+ This variable is an alist of elements of the form `(NAME .
+ CONTENTS)'. Normally, there is one element for each XEmacs
+ register that has been used.
+
+ The object NAME is a character (an integer) identifying the
+ register. The object CONTENTS is a string, marker, or list
+ representing the register contents. A string represents text
+ stored in the register. A marker represents a position. A list
+ represents a rectangle; its elements are strings, one per line of
+ the rectangle.
+
+ - Function: get-register reg
+ This function returns the contents of the register REG, or `nil'
+ if it has no contents.
+
+ - Function: set-register reg value
+ This function sets the contents of register REG to VALUE. A
+ register can be set to any value, but the other register functions
+ expect only certain data types. The return value is VALUE.
+
+ - Command: view-register reg
+ This command displays what is contained in register REG.
+
+ - Command: insert-register reg &optional beforep
+ This command inserts contents of register REG into the current
+ buffer.
+
+ Normally, this command puts point before the inserted text, and the
+ mark after it. However, if the optional second argument BEFOREP
+ is non-`nil', it puts the mark before and point after. You can
+ pass a non-`nil' second argument BEFOREP to this function
+ interactively by supplying any prefix argument.
+
+ 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.
+
+\1f
+File: lispref.info, Node: Transposition, Next: Change Hooks, Prev: Registers, Up: Text
+
+Transposition of Text
+=====================
+
+ This subroutine is used by the transposition commands.
+
+ - 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.
+
+ 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.
+
+\1f
File: lispref.info, Node: Change Hooks, Next: Transformations, Prev: Transposition, Up: Text
Change Hooks
Emacs Lisp interface to MD5 consists of a single function `md5':
- - Function: md5 OBJECT &optional START END
+ - Function: md5 object &optional start end
This function returns the MD5 message digest of OBJECT, a buffer
or string.
The Lisp interface to base64 consists of four functions:
- - Function: base64-encode-region BEG END &optional NO-LINE-BREAK
+ - 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.
The function can also be used interactively, in which case it
works on the currently active region.
- - Function: base64-encode-string STRING
+ - Function: base64-encode-string string
This function encodes STRING to base64, and returns the encoded
string.
(base64-encode-string "fubar")
=> "ZnViYXI="
- - Function: base64-decode-region BEG END
+ - 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.
;; Decode a base64 buffer, and replace it with the decoded version
(base64-decode-region (point-min) (point-max))
- - Function: base64-decode-string STRING
+ - Function: base64-decode-string string
This function decodes STRING to base64, and returns the decoded
string. STRING should be valid base64-encoded text.
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
+ - 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,
succeed, the function succeeds, moving point and returning its new
value. Otherwise the search fails.
- - Command: search-backward STRING &optional LIMIT NOERROR REPEAT
+ - 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
+ - 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.
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
+ - 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
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'
+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
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
+ `*' 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
`[^ ... ]'
`[^' 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.
+ 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
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
+ 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 `\'.
separate word.
`\B'
- matches the empty string, but *not* at the beginning or end of a
+ matches the empty string, but _not_ at the beginning or end of a
word.
`\<'
`\'. If an invalid regular expression is passed to any of the search
functions, an `invalid-regexp' error is signaled.
- - Function: regexp-quote STRING
+ - 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
(re-search-forward
(concat "\\s-" (regexp-quote string) "\\s-"))
-\1f
-File: lispref.info, Node: Regexp Example, Prev: Syntax of Regexps, Up: Regular Expressions
-
-Complex Regexp Example
-----------------------
-
- 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'.
-
- 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.
-
- "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
-
- In contrast, if you evaluate the variable `sentence-end', you will
-see the following:
-
- sentence-end
- =>
- "[.?!][]\"')}]*\\($\\| $\\| \\| \\)[
- ]*"
-
-In this output, tab and newline appear as themselves.
-
- This regular expression contains four parts in succession and can be
-deciphered as follows:
-
-`[.?!]'
- 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.
-
-`[]\"')}]*'
- 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.
-
-`\\($\\| $\\|\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.
-
-`[ \t\n]*'
- Finally, the last part of the pattern matches any additional
- whitespace beyond the minimum needed to end a sentence.
-
-\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).
-
- ---------- 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 ----------
-
- - 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.
-
- (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'.
-
- ---------- Buffer: foo ----------
- I read "-!-The cat in the hat
- comes back" twice.
- ---------- Buffer: foo ----------
-
- (looking-at "The cat in the hat$")
- => t
-
-\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.
-
-\1f
-File: lispref.info, Node: Search and Replace, Next: Match Data, Prev: POSIX Regexps, Up: Searching and Matching
-
-Search and Replace
-==================
-
- - 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.
-
- 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.
-
- 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.
-
- 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.
-
- 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'.
-
- - 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:
-
- * The "key bindings" are not commands, just symbols that are
- meaningful to the functions that use this map.
-
- * 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."
-
- Here are the meaningful "bindings" for `query-replace-map'. Several
-of them are meaningful only for `query-replace' and friends.
-
-`act'
- Do take the action being considered--in other words, "yes."
-
-`skip'
- Do not take action for this question--in other words, "no."
-
-`exit'
- Answer this question "no," and give up on the entire series of
- questions, assuming that the answers will be "no."
-
-`act-and-exit'
- Answer this question "yes," and give up on the entire series of
- questions, assuming that subsequent answers will be "no."
-
-`act-and-show'
- Answer this question "yes," but show the results--don't advance yet
- to the next question.
-
-`automatic'
- Answer this question and all subsequent questions in the series
- with "yes," without further user interaction.
-
-`backup'
- Move back to the previous place that a question was asked about.
-
-`edit'
- Enter a recursive edit to deal with this question--instead of any
- other action that would normally be taken.
-
-`delete-and-edit'
- Delete the text being considered, then enter a recursive edit to
- replace it.
-
-`recenter'
- Redisplay and center the window, then ask the same question again.
-
-`quit'
- Perform a quit right away. Only `y-or-n-p' and related functions
- use this answer.
-
-`help'
- Display some help, then ask again.
-
-\1f
-File: lispref.info, Node: Match Data, Next: Searching and Case, Prev: Search and Replace, Up: Searching and Matching
-
-The Match Data
-==============
-
- 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.
-
- 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.
-
-* Menu:
-
-* 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.
-
-\1f
-File: lispref.info, Node: Simple Match Data, Next: Replacing Match, Up: Match Data
-
-Simple Match Data Access
-------------------------
-
- 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'.
-
- 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.)
-
-\1f
-File: lispref.info, Node: Replacing Match, Next: Entire Match Data, Prev: Simple Match Data, Up: Match Data
-
-Replacing the Text That Matched
--------------------------------
-
- 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:
-
- `\&'
- `\&' stands for the entire text being replaced.
-
- `\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 `\(...\)'.
-
- `\\'
- `\\' stands for a single `\' in the replacement text.
-
projects / chise / xemacs-chise.git / blobdiff