"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "man/lispref/searching.texi" between
xemacs-21.4.22.tar.gz and xemacs-21.4.24.tar.bz2

About: XEmacs (an alternative to GNU Emacs) is a highly customizable open source text editor and application development system (current version).

searching.texi  (xemacs-21.4.22):searching.texi  (xemacs-21.4.24.tar.bz2)
skipping to change at line 31 skipping to change at line 31
* Search and Replace:: Internals of @code{query-replace}. * Search and Replace:: Internals of @code{query-replace}.
* Match Data:: Finding out which part of the text matched * Match Data:: Finding out which part of the text matched
various parts of a regexp, after regexp search. various parts of a regexp, after regexp search.
* Searching and Case:: Case-independent or case-significant searching. * Searching and Case:: Case-independent or case-significant searching.
* Standard Regexps:: Useful regexps for finding sentences, pages,... * Standard Regexps:: Useful regexps for finding sentences, pages,...
@end menu @end menu
The @samp{skip-chars@dots{}} functions also perform a kind of searching. The @samp{skip-chars@dots{}} functions also perform a kind of searching.
@xref{Skipping Characters}. @xref{Skipping Characters}.
@node String Search @node String Search, Regular Expressions, Searching and Matching, Searching and Matching
@section Searching for Strings @section Searching for Strings
@cindex string search @cindex string search
These are the primitive functions for searching through the text in a 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 buffer. They are meant for use in programs, but you may call them
interactively. If you do so, they prompt for the search string; interactively. If you do so, they prompt for the search string;
@var{limit} and @var{noerror} are set to @code{nil}, and @var{count} @var{limit} and @var{noerror} are set to @code{nil}, and @var{count}
is set to 1. is set to 1.
@deffn Command search-forward string &optional limit noerror count buffer @deffn Command search-forward string &optional limit noerror count buffer
skipping to change at line 156 skipping to change at line 156
@var{buffer} is the buffer to search in, and defaults to the current buffer. @var{buffer} is the buffer to search in, and defaults to the current buffer.
@end deffn @end deffn
@deffn Command word-search-backward string &optional limit noerror count buffer @deffn Command word-search-backward string &optional limit noerror count buffer
This function searches backward from point for a word match to This function searches backward from point for a word match to
@var{string}. This function is just like @code{word-search-forward} @var{string}. This function is just like @code{word-search-forward}
except that it searches backward and normally leaves point at the except that it searches backward and normally leaves point at the
beginning of the match. beginning of the match.
@end deffn @end deffn
@node Regular Expressions @node Regular Expressions, Regexp Search, String Search, Searching and Matching
@section Regular Expressions @section Regular Expressions
@cindex regular expression @cindex regular expression
@cindex regexp @cindex regexp
A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
denotes a (possibly infinite) set of strings. Searching for matches for denotes a (possibly infinite) set of strings. Searching for matches for
a regexp is a very powerful operation. This section explains how to write a regexp is a very powerful operation. This section explains how to write
regexps; the following section says how to search for them. regexps; the following section says how to search for them.
To gain a thorough understanding of regular expressions and how to use To gain a thorough understanding of regular expressions and how to use
skipping to change at line 186 skipping to change at line 186
@cite{ed}, or @cite{grep}, the GNU versions of which all utilize the GNU @cite{ed}, or @cite{grep}, the GNU versions of which all utilize the GNU
@cite{regex} library. XEmacs' version of @cite{regex} has recently been @cite{regex} library. XEmacs' version of @cite{regex} has recently been
extended with some Perl--like capabilities, described in the next extended with some Perl--like capabilities, described in the next
section. section.
@menu @menu
* Syntax of Regexps:: Rules for writing regular expressions. * Syntax of Regexps:: Rules for writing regular expressions.
* Regexp Example:: Illustrates regular expression syntax. * Regexp Example:: Illustrates regular expression syntax.
@end menu @end menu
@node Syntax of Regexps @node Syntax of Regexps, Regexp Example, Regular Expressions, Regular Expression s
@subsection Syntax of Regular Expressions @subsection Syntax of Regular Expressions
Regular expressions have a syntax in which a few characters are Regular expressions have a syntax in which a few characters are
special constructs and the rest are @dfn{ordinary}. An ordinary special constructs and the rest are @dfn{ordinary}. An ordinary
character is a simple regular expression that matches that character and character is a simple regular expression that matches that character and
nothing else. The special characters are @samp{.}, @samp{*}, @samp{+}, nothing else. The special characters are @samp{.}, @samp{*}, @samp{+},
@samp{?}, @samp{[}, @samp{]}, @samp{^}, @samp{$}, and @samp{\}; no new @samp{?}, @samp{[}, @samp{]}, @samp{^}, @samp{$}, and @samp{\}; no new
special characters will be defined in the future. Any other character special characters will be defined in the future. Any other character
appearing in a regular expression is ordinary, unless a @samp{\} appearing in a regular expression is ordinary, unless a @samp{\}
precedes it. precedes it.
skipping to change at line 607 skipping to change at line 607
whitespace: whitespace:
@example @example
@group @group
(re-search-forward (re-search-forward
(concat "\\s-" (regexp-quote string) "\\s-")) (concat "\\s-" (regexp-quote string) "\\s-"))
@end group @end group
@end example @end example
@end defun @end defun
@node Regexp Example @node Regexp Example, , Syntax of Regexps, Regular Expressions
@subsection Complex Regexp Example @subsection Complex Regexp Example
Here is a complicated regexp, used by XEmacs to recognize the end of a 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 sentence together with any whitespace that follows. It is the value of
the variable @code{sentence-end}. the variable @code{sentence-end}.
First, we show the regexp as a string in Lisp syntax to distinguish 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 spaces from tab characters. The string constant begins and ends with a
double-quote. @samp{\"} stands for a double-quote as part of the double-quote. @samp{\"} stands for a double-quote as part of the
string, @samp{\\} for a backslash as part of the string, @samp{\t} for a string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
skipping to change at line 669 skipping to change at line 669
double backslashes mark the parentheses and vertical bars as regular double backslashes mark the parentheses and vertical bars as regular
expression syntax; the parentheses delimit a group and the vertical bars expression syntax; the parentheses delimit a group and the vertical bars
separate alternatives. The dollar sign is used to match the end of a separate alternatives. The dollar sign is used to match the end of a
line. line.
@item [ \t\n]* @item [ \t\n]*
Finally, the last part of the pattern matches any additional whitespace Finally, the last part of the pattern matches any additional whitespace
beyond the minimum needed to end a sentence. beyond the minimum needed to end a sentence.
@end table @end table
@node Regexp Search @node Regexp Search, POSIX Regexps, Regular Expressions, Searching and Matching
@section Regular Expression Searching @section Regular Expression Searching
@cindex regular expression searching @cindex regular expression searching
@cindex regexp searching @cindex regexp searching
@cindex searching for regexp @cindex searching for regexp
In XEmacs, you can search for the next match for a regexp either In XEmacs, you can search for the next match for a regexp either
incrementally or not. Incremental search commands are described in the incrementally or not. Incremental search commands are described in the
@cite{The XEmacs Lisp Reference Manual}. @xref{Regexp Search, , Regular Express ion @cite{The XEmacs Lisp Reference Manual}. @xref{Regexp Search, , Regular Express ion
Search, xemacs, The XEmacs Lisp Reference Manual}. Here we describe only the se arch Search, xemacs, The XEmacs Lisp Reference Manual}. Here we describe only the se arch
functions useful in programs. The principal one is functions useful in programs. The principal one is
skipping to change at line 859 skipping to change at line 859
I read "@point{}The cat in the hat I read "@point{}The cat in the hat
comes back" twice. comes back" twice.
---------- Buffer: foo ---------- ---------- Buffer: foo ----------
(looking-at "The cat in the hat$") (looking-at "The cat in the hat$")
@result{} t @result{} t
@end group @end group
@end example @end example
@end defun @end defun
@node POSIX Regexps @node POSIX Regexps, Search and Replace, Regexp Search, Searching and Matching
@section POSIX Regular Expression Searching @section POSIX Regular Expression Searching
The usual regular expression functions do backtracking when necessary The usual regular expression functions do backtracking when necessary
to handle the @samp{\|} and repetition constructs, but they continue to handle the @samp{\|} and repetition constructs, but they continue
this only until they find @emph{some} match. Then they succeed and this only until they find @emph{some} match. Then they succeed and
report the first match found. report the first match found.
This section describes alternative search functions which perform the This section describes alternative search functions which perform the
full backtracking specified by the POSIX standard for regular expression full backtracking specified by the POSIX standard for regular expression
matching. They continue backtracking until they have tried all matching. They continue backtracking until they have tried all
skipping to change at line 978 skipping to change at line 978
@end deffn @end deffn
@defopt list-matching-lines-default-context-lines @defopt list-matching-lines-default-context-lines
Default value is 0. Default value is 0.
Default number of context lines to include around a @code{list-matching-lines} Default number of context lines to include around a @code{list-matching-lines}
match. A negative number means to include that many lines before the match. match. A negative number means to include that many lines before the match.
A positive number means to include that many lines both before and after. A positive number means to include that many lines both before and after.
@end defopt @end defopt
@end ignore @end ignore
@node Search and Replace @node Search and Replace, Match Data, POSIX Regexps, Searching and Matching
@section Search and Replace @section Search and Replace
@cindex replacement @cindex replacement
@defun perform-replace from-string replacements query-flag regexp-flag delimited -flag &optional repeat-count map @defun perform-replace from-string replacements query-flag regexp-flag delimited -flag &optional repeat-count map
This function is the guts of @code{query-replace} and related commands. This function is the guts of @code{query-replace} and related commands.
It searches for occurrences of @var{from-string} and replaces some or It searches for occurrences of @var{from-string} and replaces some or
all of them. If @var{query-flag} is @code{nil}, it replaces all all of them. If @var{query-flag} is @code{nil}, it replaces all
occurrences; otherwise, it asks the user what to do about each one. occurrences; otherwise, it asks the user what to do about each one.
If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
skipping to change at line 1072 skipping to change at line 1072
Redisplay and center the window, then ask the same question again. Redisplay and center the window, then ask the same question again.
@item quit @item quit
Perform a quit right away. Only @code{y-or-n-p} and related functions Perform a quit right away. Only @code{y-or-n-p} and related functions
use this answer. use this answer.
@item help @item help
Display some help, then ask again. Display some help, then ask again.
@end table @end table
@node Match Data @node Match Data, Searching and Case, Search and Replace, Searching and Matching
@section The Match Data @section The Match Data
@cindex match data @cindex match data
XEmacs keeps track of the positions of the start and end of segments of 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, 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 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 message, and then extract parts of the match under control of the
pattern. pattern.
Because the match data normally describe the most recent search only, Because the match data normally describe the most recent search only,
skipping to change at line 1096 skipping to change at line 1096
match data around it, to prevent it from being overwritten. match data around it, to prevent it from being overwritten.
@menu @menu
* Simple Match Data:: Accessing single items of match data, * Simple Match Data:: Accessing single items of match data,
such as where a particular subexpression started. such as where a particular subexpression started.
* Replacing Match:: Replacing a substring that was matched. * Replacing Match:: Replacing a substring that was matched.
* Entire Match Data:: Accessing the entire match data at once, as a list. * Entire Match Data:: Accessing the entire match data at once, as a list.
* Saving Match Data:: Saving and restoring the match data. * Saving Match Data:: Saving and restoring the match data.
@end menu @end menu
@node Simple Match Data @node Simple Match Data, Replacing Match, Match Data, Match Data
@subsection Simple Match Data Access @subsection Simple Match Data Access
This section explains how to use the match data to find out what was This section explains how to use the match data to find out what was
matched by the last search or match operation. matched by the last search or match operation.
You can ask about the entire matching text, or about a particular You can ask about the entire matching text, or about a particular
parenthetical subexpression of a regular expression. The @var{count} parenthetical subexpression of a regular expression. The @var{count}
argument in the functions below specifies which. If @var{count} is argument in the functions below specifies which. If @var{count} is
zero, you are asking about the entire match. If @var{count} is zero, you are asking about the entire match. If @var{count} is
positive, it specifies which subexpression you want. positive, it specifies which subexpression you want.
skipping to change at line 1219 skipping to change at line 1219
^ ^ ^ ^
9 13 9 13
---------- Buffer: foo ---------- ---------- Buffer: foo ----------
@end group @end group
@end example @end example
@noindent @noindent
(In this case, the index returned is a buffer position; the first (In this case, the index returned is a buffer position; the first
character of the buffer counts as 1.) character of the buffer counts as 1.)
@node Replacing Match @node Replacing Match, Entire Match Data, Simple Match Data, Match Data
@subsection Replacing the Text That Matched @subsection Replacing the Text That Matched
This function replaces the text matched by the last search with This function replaces the text matched by the last search with
@var{replacement}. @var{replacement}.
@cindex case in replacements @cindex case in replacements
@defun replace-match replacement &optional fixedcase literal string strbuffer @defun replace-match replacement &optional fixedcase literal string strbuffer
This function replaces the text in the buffer (or in @var{string}) that This function replaces the text in the buffer (or in @var{string}) that
was matched by the last search. It replaces that text with was matched by the last search. It replaces that text with
@var{replacement}. @var{replacement}.
skipping to change at line 1282 skipping to change at line 1282
@samp{\@var{n}}, where @var{n} is a digit, stands for the text that @samp{\@var{n}}, where @var{n} is a digit, stands for the text that
matched the @var{n}th subexpression in the original regexp. matched the @var{n}th subexpression in the original regexp.
Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}. Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
@item @samp{\\} @item @samp{\\}
@cindex @samp{\} in replacement @cindex @samp{\} in replacement
@samp{\\} stands for a single @samp{\} in the replacement text. @samp{\\} stands for a single @samp{\} in the replacement text.
@end table @end table
@end defun @end defun
@node Entire Match Data @node Entire Match Data, Saving Match Data, Replacing Match, Match Data
@subsection Accessing the Entire Match Data @subsection Accessing the Entire Match Data
The functions @code{match-data} and @code{set-match-data} read or The functions @code{match-data} and @code{set-match-data} read or
write the entire match data, all at once. write the entire match data, all at once.
@defun match-data &optional integers reuse @defun match-data &optional integers reuse
This function returns a newly constructed list containing all the This function returns a newly constructed list containing all the
information on what text the last search matched. Element zero is the information on what text the last search matched. Element zero is the
position of the beginning of the match for the whole expression; element position of the beginning of the match for the whole expression; element
one is the position of the end of the match for the expression. The one is the position of the end of the match for the expression. The
skipping to change at line 1348 skipping to change at line 1348
which should be a list that was the value of a previous call to which should be a list that was the value of a previous call to
@code{match-data}. @code{match-data}.
If @var{match-list} refers to a buffer that doesn't exist, you don't get If @var{match-list} refers to a buffer that doesn't exist, you don't get
an error; that sets the match data in a meaningless but harmless way. an error; that sets the match data in a meaningless but harmless way.
@findex store-match-data @findex store-match-data
@code{store-match-data} is an alias for @code{set-match-data}. @code{store-match-data} is an alias for @code{set-match-data}.
@end defun @end defun
@node Saving Match Data @node Saving Match Data, , Entire Match Data, Match Data
@subsection Saving and Restoring the Match Data @subsection Saving and Restoring the Match Data
When you call a function that may do a search, you may need to save When you call a function that may do a search, you may need to save
and restore the match data around that call, if you want to preserve the and restore the match data around that call, if you want to preserve the
match data from an earlier search for later use. Here is an example match data from an earlier search for later use. Here is an example
that shows the problem that arises if you fail to save the match data: that shows the problem that arises if you fail to save the match data:
@example @example
@group @group
(re-search-forward "The \\(cat \\)") (re-search-forward "The \\(cat \\)")
skipping to change at line 1416 skipping to change at line 1416
(null (marker-buffer (car d))) (null (marker-buffer (car d)))
@group @group
;; @file{match-data} @r{buffer is deleted.} ;; @file{match-data} @r{buffer is deleted.}
(throw 'foo nil)) (throw 'foo nil))
(setq d (cdr d))) (setq d (cdr d)))
(set-match-data data)))) (set-match-data data))))
@end group @end group
@end smallexample @end smallexample
@end ignore @end ignore
@node Searching and Case @node Searching and Case, Standard Regexps, Match Data, Searching and Matching
@section Searching and Case @section Searching and Case
@cindex searching and case @cindex searching and case
By default, searches in Emacs ignore the case of the text they are By default, searches in Emacs ignore the case of the text they are
searching through; if you specify searching for @samp{FOO}, then searching through; if you specify searching for @samp{FOO}, then
@samp{Foo} or @samp{foo} is also considered a match. Regexps, and in @samp{Foo} or @samp{foo} is also considered a match. Regexps, and in
particular character sets, are included: thus, @samp{[aB]} would match particular character sets, are included: thus, @samp{[aB]} would match
@samp{a} or @samp{A} or @samp{b} or @samp{B}. @samp{a} or @samp{A} or @samp{b} or @samp{B}.
If you do not want this feature, set the variable If you do not want this feature, set the variable
skipping to change at line 1462 skipping to change at line 1462
case. If the variable is @code{nil} they do not ignore case; otherwise case. If the variable is @code{nil} they do not ignore case; otherwise
they do ignore case. they do ignore case.
@end defopt @end defopt
@defvar default-case-fold-search @defvar default-case-fold-search
The value of this variable is the default value for The value of this variable is the default value for
@code{case-fold-search} in buffers that do not override it. This is the @code{case-fold-search} in buffers that do not override it. This is the
same as @code{(default-value 'case-fold-search)}. same as @code{(default-value 'case-fold-search)}.
@end defvar @end defvar
@node Standard Regexps @node Standard Regexps, , Searching and Case, Searching and Matching
@section Standard Regular Expressions Used in Editing @section Standard Regular Expressions Used in Editing
@cindex regexps used standardly in editing @cindex regexps used standardly in editing
@cindex standard regexps used in editing @cindex standard regexps used in editing
This section describes some variables that hold regular expressions This section describes some variables that hold regular expressions
used for certain purposes in editing: used for certain purposes in editing:
@defvar page-delimiter @defvar page-delimiter
This is the regexp describing line-beginnings that separate pages. The This is the regexp describing line-beginnings that separate pages. The
default value is @code{"^\014"} (i.e., @code{"^^L"} or @code{"^\C-l"}); default value is @code{"^\014"} (i.e., @code{"^^L"} or @code{"^\C-l"});
 End of changes. 14 change blocks. 
14 lines changed or deleted 14 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)