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
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
+ This construct is 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.
+ C comments in a string. This could not easily be achieved without
+ the use of a non-greedy quantifier.
This construct has not been available prior to XEmacs 20.4. It is
not available in FSF Emacs.
`+?'
- is the `+' analog to `*?'.
+ is the non-greedy version of `+'.
+
+`??'
+ is the non-greedy version of `?'.
`\{n,m\}'
serves as an interval quantifier, analogous to `*' or `+', but
more than M times. This syntax is supported by most Unix regexp
utilities, and has been introduced to XEmacs for the version 20.3.
+ Unfortunately, the non-greedy version of this quantifier does not
+ exist currently, although it does in Perl.
+
`[ ... ]'
`[' begins a "character set", which is terminated by a `]'. In
the simplest case, the characters between the two brackets form
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'.
+ constructs, but only want to remember one or two - or if you have
+ more than nine groupings and need to use backreferences to refer to
+ the groupings at the end.
Using `\(?: ... \)' rather than `\( ... \)' when you don't need
the captured substrings ought to speed up your programs some,
(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