procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Doc and lispref updates related to searching

Browse source 
* doc/lispref/searching.texi (Regexp Functions, Regexp Search):
(Simple Match Data, Saving Match Data, Standard Regexps): Copyedits.
(Regexp Functions): Mention regexp-opt is not guaranteed.
Mention regexp-opt-charset.
(Regexp Search): Recommend against looking-back.
(Search and Replace): Use Texinfo recommended quote convention.
Add more query-replace-map items.  List multi-query-replace-map items.

* lisp/replace.el (query-replace-map): Doc fix.

* admin/FOR-RELEASE: Related markup.
This commit is contained in:
Glenn Morris 2012-03-28 12:30:12 -07:00
parent e8fc049ff7
commit fee88ca0e8
5 changed files with 90 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
admin/FOR-RELEASE
View file

@ -220,7 +220,7 @@ os.texi cyd
package.texi rgm
positions.texi cyd
processes.texi
searching.texi
searching.texi rgm
sequences.texi cyd
streams.texi cyd
strings.texi cyd

8
doc/lispref/ChangeLog
View file

@ -1,9 +1,15 @@
2012-03-28 Glenn Morris <rgm@gnu.org>
* searching.texi (Regular Expressions, Regexp Special):
(Regexp Backslash, Regexp Example): Copyedits.
(Regexp Backslash, Regexp Example, Regexp Functions, Regexp Search):
(Simple Match Data, Saving Match Data, Standard Regexps): Copyedits.
(Regexp Special): Mention collation.
Clarify char classes with an example.
(Regexp Functions): Mention regexp-opt is not guaranteed.
Mention regexp-opt-charset.
(Regexp Search): Recommend against looking-back.
(Search and Replace): Use Texinfo recommended quote convention.
Add more query-replace-map items. List multi-query-replace-map items.
2012-03-27 Martin Rudalics <rudalics@gmx.at>

108
doc/lispref/searching.texi
View file

@ -902,7 +902,7 @@ This function returns a regular expression whose only exact match is
@var{string}. Using this regular expression in @code{looking-at} will
succeed only if the next characters in the buffer are @var{string};
using it in a search function will succeed if the text being searched
contains @var{string}.
contains @var{string}. @xref{Regexp Search}.
This allows you to request an exact string match or search when calling
a function that wants a regular expression.
@ -931,7 +931,11 @@ whitespace:
This function returns an efficient regular expression that will match
any of the strings in the list @var{strings}. This is useful when you
need to make matching or searching as fast as possible---for example,
for Font Lock mode.
for Font Lock mode@footnote{Note that @code{regexp-opt} does not
guarantee that its result is absolutely the most efficient form
possible. A hand-tuned regular expression can sometimes be slightly
more efficient, but is almost never worth the effort.}.
@c See eg http://debbugs.gnu.org/2816
If the optional argument @var{paren} is non-@code{nil}, then the
returned regular expression is always enclosed by at least one
@ -947,7 +951,7 @@ regular expression which is equivalent to the actual value
(but not as efficient):
@example
(defun regexp-opt (strings paren)
(defun regexp-opt (strings &optional paren)
(let ((open-paren (if paren "\\(" ""))
(close-paren (if paren "\\)" "")))
(concat open-paren
@ -962,6 +966,19 @@ This function returns the total number of grouping constructs
shy groups (@pxref{Regexp Backslash}).
@end defun
@c Supposedly an internal regexp-opt function, but table.el uses it at least.
@defun regexp-opt-charset chars
This function returns a regular expression matching a character in the
list of characters @var{chars}.
@example
(regexp-opt-charset '(?a ?b ?c ?d ?e))
@result{} "[a-e]"
@end example
@end defun
@c Internal functions: regexp-opt-group
@node Regexp Search
@section Regular Expression Searching
@cindex regular expression searching
@ -1104,8 +1121,7 @@ following'' means precisely that: the search is ``anchored'' and it can
succeed only starting with the first character following point. The
result is @code{t} if so, @code{nil} otherwise.
This function does not move point, but it updates the match data, which
you can access using @code{match-beginning} and @code{match-end}.
This function does not move point, but it does update the match data.
@xref{Match Data}. If you need to test for a match without modifying
the match data, use @code{looking-at-p}, described below.
@ -1126,8 +1142,8 @@ comes back" twice.
@end defun
@defun looking-back regexp &optional limit greedy
This function returns @code{t} if @var{regexp} matches text before
point, ending at point, and @code{nil} otherwise.
This function returns @code{t} if @var{regexp} matches the text
immediately before point (i.e., ending at point), and @code{nil} otherwise.
Because regular expression matching works only going forward, this is
implemented by searching backwards from point for a match that ends at
@ -1155,6 +1171,11 @@ comes back" twice.
@result{} nil
@end group
@end example
@c http://debbugs.gnu.org/5689
As a general recommendation, try to avoid using @code{looking-back}
wherever possible, since it is slow. For this reason, there are no
plans to add a @code{looking-back-p} function.
@end defun
@defun looking-at-p regexp
@ -1178,6 +1199,7 @@ a part of the code.
@node POSIX Regexps
@section POSIX Regular Expression Searching
@cindex backtracking and POSIX regular expressions
The usual regular expression functions do backtracking when necessary
to handle the @samp{\|} and repetition constructs, but they continue
this only until they find @emph{some} match. Then they succeed and
@ -1350,12 +1372,16 @@ only information available is about the entire match.
query the match data immediately after searching, before calling any
other function that might perform another search. Alternatively, you
may save and restore the match data (@pxref{Saving Match Data}) around
the call to functions that could perform another search.
the call to functions that could perform another search. Or use the
functions that explicitly do not modify the match data;
e.g. @code{string-match-p}.
@c This is an old comment and presumably there is no prospect of this
@c changing now. But still the advice stands.
A search which fails may or may not alter the match data. In the
past, a failing search did not do this, but we may change it in the
future. So don't try to rely on the value of the match data after
a failing search.
current implementation, it does not, but we may change it in the
future. Don't try to rely on the value of the match data after a
failing search.
@defun match-string count &optional in-string
This function returns, as a string, the text matched in the last search
@ -1369,7 +1395,7 @@ argument @var{in-string}. After a buffer search or match,
you should omit @var{in-string} or pass @code{nil} for it; but you
should make sure that the current buffer when you call
@code{match-string} is the one in which you did the searching or
matching.
matching. Failure to follow this advice will lead to incorrect results.
The value is @code{nil} if @var{count} is out of range, or for a
subexpression inside a @samp{\|} alternative that wasn't used or a
@ -1382,7 +1408,7 @@ has no text properties.
@end defun
@defun match-beginning count
This function returns the position of the start of text matched by the
This function returns the position of the start of the text matched by the
last regular expression searched for, or a subexpression of it.
If @var{count} is zero, then the value is the position of the start of
@ -1475,7 +1501,7 @@ write the entire match data, all at once.
@defun match-data &optional integers reuse reseat
This function returns a list of positions (markers or integers) that
record all the information on what text the last search matched.
record all the information on the text that the last search matched.
Element zero is the 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 next two elements are the positions of the
@ -1544,6 +1570,7 @@ an error; that sets the match data in a meaningless but harmless way.
If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list
are reseated to point to nowhere.
@c TODO Make it properly obsolete.
@findex store-match-data
@code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
@end defun
@ -1551,7 +1578,7 @@ are reseated to point to nowhere.
@node Saving 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 search, you may need to save
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
that shows the problem that arises if you fail to save the match data:
@ -1560,8 +1587,7 @@ that shows the problem that arises if you fail to save the match data:
@group
(re-search-forward "The \\(cat \\)")
@result{} 48
(foo) ; @r{Perhaps @code{foo} does}
; @r{more searching.}
(foo) ; @r{@code{foo} does more searching.}
(match-end 0)
@result{} 61 ; @r{Unexpected result---not 48!}
@end group
@ -1654,7 +1680,7 @@ Instead of a string, @var{rep} can be a function. In that case,
@code{replace-regexp-in-string} calls @var{rep} for each match,
passing the text of the match as its sole argument. It collects the
value @var{rep} returns and passes that to @code{replace-match} as the
replacement string. The match-data at this point are the result
replacement string. The match data at this point are the result
of matching @var{regexp} against a substring of @var{string}.
@end defun
@ -1692,7 +1718,7 @@ it specifies how many times to use each of the strings in the
If @var{from-string} contains upper-case letters, then
@code{perform-replace} binds @code{case-fold-search} to @code{nil}, and
it uses the @code{replacements} without altering the case of them.
it uses the @var{replacements} without altering their case.
Normally, the keymap @code{query-replace-map} defines the possible
user responses for queries. The argument @var{map}, if
@ -1722,7 +1748,7 @@ 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
@code{read-key-sequence} to get the input; instead, they read a single
event and look it up ``by hand.''
event and look it up ``by hand''.
@end itemize
@end defvar
@ -1732,26 +1758,30 @@ friends.
@table @code
@item act
Do take the action being considered---in other words, ``yes.''
Do take the action being considered---in other words, ``yes''.
@item skip
Do not take action for this question---in other words, ``no.''
Do not take action for this question---in other words, ``no''.
@item exit
Answer this question ``no,'' and give up on the entire series of
questions, assuming that the answers will be ``no.''
Answer this question ``no'', and give up on the entire series of
questions, assuming that the answers will be ``no''.
@item exit-prefix
Like @code{exit}, but add the key that was pressed to
@code{unread-comment-events}.
@item act-and-exit
Answer this question ``yes,'' and give up on the entire series of
questions, assuming that subsequent answers will be ``no.''
Answer this question ``yes'', and give up on the entire series of
questions, assuming that subsequent answers will be ``no''.
@item act-and-show
Answer this question ``yes,'' but show the results---don't advance yet
Answer this question ``yes'', but show the results---don't advance yet
to the next question.
@item automatic
Answer this question and all subsequent questions in the series with
``yes,'' without further user interaction.
``yes'', without further user interaction.
@item backup
Move back to the previous place that a question was asked about.
@ -1760,6 +1790,9 @@ Move back to the previous place that a question was asked about.
Enter a recursive edit to deal with this question---instead of any
other action that would normally be taken.
@item edit-replacement
Edit the replacement for this question in the minibuffer.
@item delete-and-edit
Delete the text being considered, then enter a recursive edit to replace
it.
@ -1778,7 +1811,18 @@ Display some help, then ask again.
@defvar multi-query-replace-map
This variable holds a keymap that extends @code{query-replace-map} by
providing additional keybindings that are useful in multi-buffer
replacements.
replacements. The additional ``bindings'' are:
@table @code
@item automatic-all
Answer this question and all subsequent questions in the series with
``yes'', without further user interaction, for all remaining buffers.
@item exit-current
Answer this question ``no'', and give up on the entire series of
questions for the current buffer. Continue to the next buffer in the
sequence.
@end table
@end defvar
@defvar replace-search-function
@ -1841,8 +1885,8 @@ If non-@code{nil}, the value should be a regular expression describing
the end of a sentence, including the whitespace following the
sentence. (All paragraph boundaries also end sentences, regardless.)
If the value is @code{nil}, the default, then the function
@code{sentence-end} has to construct the regexp. That is why you
If the value is @code{nil}, as it is by default, then the function
@code{sentence-end} constructs the regexp. That is why you
should always call the function @code{sentence-end} to obtain the
regexp to be used to recognize the end of a sentence.
@end defopt
@ -1852,6 +1896,6 @@ This function returns the value of the variable @code{sentence-end},
if non-@code{nil}. Otherwise it returns a default value based on the
values of the variables @code{sentence-end-double-space}
(@pxref{Definition of sentence-end-double-space}),
@code{sentence-end-without-period} and
@code{sentence-end-without-period}, and
@code{sentence-end-without-space}.
@end defun

4
lisp/ChangeLog
View file

@ -1,3 +1,7 @@
2012-03-28 Glenn Morris <rgm@gnu.org>
* replace.el (query-replace-map): Doc fix.
2012-03-28 Andreas Schwab <schwab@linux-m68k.org>
* vc/vc-git.el (vc-git-state): Don't try to match all of the diff

4
lisp/replace.el
View file

@ -1594,8 +1594,8 @@ E to edit the replacement string"
"Keymap that defines the responses to questions in `query-replace'.
The \"bindings\" in this map are not commands; they are answers.
The valid answers include `act', `skip', `act-and-show',
`exit', `act-and-exit', `edit', `delete-and-edit', `recenter',
`automatic', `backup', `exit-prefix', and `help'.")
`exit', `act-and-exit', `edit', `edit-replacement', `delete-and-edit',
`recenter', `automatic', `backup', `exit-prefix', `quit', and `help'.")
(defvar multi-query-replace-map
(let ((map (make-sparse-keymap)))