X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/e9c806049cf78d59803c01290ab3df0f8e5c4d37..cc8549df68dfe45e2aed861937674f4ecc6f622d:/man/search.texi diff --git a/man/search.texi b/man/search.texi index b4e0b374c4..ea08626a6a 100644 --- a/man/search.texi +++ b/man/search.texi @@ -181,15 +181,18 @@ backward search finds matches that are entirely before the starting point, just as a forward search finds matches that begin after it. The characters @kbd{C-y} and @kbd{C-w} can be used in incremental -search to grab text from the buffer into the search string. This makes -it convenient to search for another occurrence of text at point. -@kbd{C-w} copies the word after point as part of the search string, -advancing point over that word. Another @kbd{C-s} to repeat the search -will then search for a string including that word. @kbd{C-y} is similar -to @kbd{C-w} but copies all the rest of the current line into the search -string. Both @kbd{C-y} and @kbd{C-w} convert the text they copy to -lower case if the search is currently not case-sensitive; this is so the -search remains case-insensitive. +search to grab text from the buffer into the search string. This +makes it convenient to search for another occurrence of text at point. +@kbd{C-w} copies the character or word after point as part of the +search string, advancing point over it. (The decision, whether to +copy a character or a word, is heuristic.) Another @kbd{C-s} to +repeat the search will then search for a string including that +character or word. + + @kbd{C-y} is similar to @kbd{C-w} but copies all the rest of the +current line into the search string. Both @kbd{C-y} and @kbd{C-w} +convert the text they copy to lower case if the search is currently +not case-sensitive; this is so the search remains case-insensitive. The character @kbd{M-y} copies text from the kill ring into the search string. It uses the same text that @kbd{C-y} as a command would yank. @@ -382,6 +385,11 @@ Search}. @section Syntax of Regular Expressions @cindex syntax of regexps + This manual describes regular expression features that users +typically want to use. There are additional features that are +mainly used in Lisp programs; see @ref{Regular Expressions,,, +elisp, the same manual}. + Regular expressions have a syntax in which a few characters are special constructs and the rest are @dfn{ordinary}. An ordinary character is a simple regular expression which matches that same @@ -410,14 +418,14 @@ and @samp{o} to get the regular expression @samp{fo}, which matches only the string @samp{fo}. Still trivial. To do something nontrivial, you need to use one of the special characters. Here is a list of them. -@table @kbd -@item .@: @r{(Period)} +@table @asis +@item @kbd{.}@: @r{(Period)} is a special character that matches any single character except a newline. Using concatenation, we can make regular expressions like @samp{a.b}, which matches any three-character string that begins with @samp{a} and ends with @samp{b}.@refill -@item * +@item @kbd{*} is not a construct by itself; it is a postfix operator that means to match the preceding regular expression repetitively as many times as possible. Thus, @samp{o*} matches any number of @samp{o}s (including no @@ -438,18 +446,18 @@ tries to match all three @samp{a}s; but the rest of the pattern is The next alternative is for @samp{a*} to match only two @samp{a}s. With this choice, the rest of the regexp matches successfully.@refill -@item + +@item @kbd{+} is a postfix operator, similar to @samp{*} except that it must match the preceding expression at least once. So, for example, @samp{ca+r} matches the strings @samp{car} and @samp{caaaar} but not the string @samp{cr}, whereas @samp{ca*r} matches all three strings. -@item ? +@item @kbd{?} is a postfix operator, similar to @samp{*} except that it can match the preceding expression either once or not at all. For example, @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else. -@item *?, +?, ?? +@item @kbd{*?}, @kbd{+?}, @kbd{??} @cindex non-greedy regexp matching are non-greedy variants of the operators above. The normal operators @samp{*}, @samp{+}, @samp{?} are @dfn{greedy} in that they match as @@ -463,13 +471,20 @@ the text @samp{abbb}, @samp{ab*} will match it all (the longest valid match), while @samp{ab*?} will match just @samp{a} (the shortest valid match). -@item \@{@var{n}\@} +Non-greedy operators match the shortest possible string starting at a +given starting point; in a forward search, though, the earliest +possible starting point for match is always the one chosen. Thus, if +you search for @samp{a.*?$} against the text @samp{abbab} followed by +a newline, it matches the whole string. Since it @emph{can} match +starting at the first @samp{a}, it does. + +@item @kbd{\@{@var{n}\@}} is a postfix operator that specifies repetition @var{n} times---that is, the preceding regular expression must match exactly @var{n} times in a row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} and nothing else. -@item \@{@var{n},@var{m}\@} +@item @kbd{\@{@var{n},@var{m}\@}} is a postfix operator that specifies repetition between @var{n} and @var{m} times---that is, the preceding regular expression must match at least @var{n} times, but no more than @var{m} times. If @var{m} is @@ -478,7 +493,7 @@ expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to @samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}. -@item [ @dots{} ] +@item @kbd{[ @dots{} ]} is a @dfn{character set}, which begins with @samp{[} and is terminated by @samp{]}. In the simplest case, the characters between the two brackets are what this set can match. @@ -513,7 +528,7 @@ ends of the range in upper case, or both in lower case, or both should be non-letters. The behavior of a mixed-case range such as @samp{A-z} is somewhat ill-defined, and it may change in future Emacs versions. -@item [^ @dots{} ] +@item @kbd{[^ @dots{} ]} @samp{[^} begins a @dfn{complemented character set}, which matches any character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches all characters @emph{except} ASCII letters and digits. @@ -526,17 +541,17 @@ A complemented character set can match a newline, unless newline is mentioned as one of the characters not to match. This is in contrast to the handling of regexps in programs such as @code{grep}. -@item ^ +@item @kbd{^} is a special character that matches the empty string, but only at the beginning of a line in the text being matched. Otherwise it fails to match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at the beginning of a line. -@item $ +@item @kbd{$} is similar to @samp{^} but matches only at the end of a line. Thus, @samp{x+$} matches a string of one @samp{x} or more at the end of a line. -@item \ +@item @kbd{\} has two functions: it quotes the special characters (including @samp{\}), and it introduces additional special constructs. @@ -632,12 +647,12 @@ If a particular @samp{\( @dots{} \)} construct matches more than once match is recorded. @item \` -matches the empty string, but only at the beginning -of the buffer or string being matched against. +matches the empty string, but only at the beginning of the string or +buffer (or its accessible portion) being matched against. @item \' -matches the empty string, but only at the end of -the buffer or string being matched against. +matches the empty string, but only at the end of the string or buffer +(or its accessible portion) being matched against. @item \= matches the empty string, but only at point. @@ -719,9 +734,12 @@ end-of-line, a space at the end of a line, a tab, or two spaces; and a character set matching whitespace characters, repeated any number of times. - To enter the same regexp interactively, you would type @key{TAB} to -enter a tab, and @kbd{C-j} to enter a newline. You would also type -single backslashes as themselves, instead of doubling them for Lisp syntax. + To enter the same regexp in incremental search, you would type +@key{TAB} to enter a tab, and @kbd{C-j} to enter a newline. You would +also type single backslashes as themselves, instead of doubling them +for Lisp syntax. In commands that use ordinary minibuffer input to +read a regexp, you would quote the @kbd{C-j} by preceding it with a +@kbd{C-q} to prevent @kbd{C-j} from exiting the minibuffer. @ignore @c I commented this out because it is missing vital information @@ -788,11 +806,12 @@ there is a @kbd{M-x query-replace} command which finds each occurrence of the pattern and asks you whether to replace it. The replace commands normally operate on the text from point to the -end of the buffer; however, in Transient Mark mode, when the mark is -active, they operate on the region. The replace commands all replace -one string (or regexp) with one replacement string. It is possible to -perform several replacements in parallel using the command -@code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}). +end of the buffer; however, in Transient Mark mode (@pxref{Transient +Mark}), when the mark is active, they operate on the region. The +replace commands all replace one string (or regexp) with one +replacement string. It is possible to perform several replacements in +parallel using the command @code{expand-region-abbrevs} +(@pxref{Expanding Abbrevs}). @menu * Unconditional Replace:: Replacing all matches for a string. @@ -831,6 +850,18 @@ C-@key{SPC}} to move back there. A numeric argument restricts replacement to matches that are surrounded by word boundaries. The argument's value doesn't matter. + What if you want to exchange @samp{x} and @samp{y}: replace every @samp{x} with a @samp{y} and vice versa? You can do it this way: + +@example +M-x query-replace @key{RET} x @key{RET} @@TEMP@@ @key{RET} +M-x query-replace @key{RET} y @key{RET} x @key{RET} +M-x query-replace @key{RET} @@TEMP@@ @key{RET} y @key{RET} +@end example + +@noindent +This works provided the string @samp{@@TEMP@@} does not appear +in your text. + @node Regexp Replace, Replacement and Case, Unconditional Replace, Replace @subsection Regexp Replacement @@ -1025,11 +1056,14 @@ copy, or link files by replacing regexp matches in file names. Here are some other commands that find matches for a regular expression. They all ignore case in matching, if the pattern contains no upper-case letters and @code{case-fold-search} is non-@code{nil}. -Aside from @code{occur}, all operate on the text from point to the end -of the buffer, or on the active region in Transient Mark mode. +Aside from @code{occur} and its variants, all operate on the text from +point to the end of the buffer, or on the active region in Transient +Mark mode. @findex list-matching-lines @findex occur +@findex multi-occur +@findex multi-occur-by-filename-regexp @findex how-many @findex delete-non-matching-lines @findex delete-matching-lines @@ -1045,15 +1079,27 @@ specifies that @var{n} lines of context are to be displayed before and after each matching line. @kindex RET @r{(Occur mode)} +@kindex o @r{(Occur mode)} +@kindex C-o @r{(Occur mode)} The buffer @samp{*Occur*} containing the output serves as a menu for -finding the occurrences in their original context. Click @kbd{Mouse-2} -on an occurrence listed in @samp{*Occur*}, or position point there and -type @key{RET}; this switches to the buffer that was searched and -moves point to the original of the chosen occurrence. +finding the occurrences in their original context. Click +@kbd{Mouse-2} on an occurrence listed in @samp{*Occur*}, or position +point there and type @key{RET}; this switches to the buffer that was +searched and moves point to the original of the chosen occurrence. +@kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o} +does not select it. @item M-x list-matching-lines Synonym for @kbd{M-x occur}. +@item M-x multi-occur @key{RET} @var{buffers} @key{RET} @var{regexp} @key{RET} +This function is just like @code{occur}, except it is able to search +through multiple buffers. + +@item M-x multi-occur-by-filename-regexp @key{RET} @var{bufregexp} @key{RET} @var{regexp} @key{RET} +This function is similar to @code{multi-occur}, except the buffers to +search are specified by a regexp on their filename. + @item M-x how-many @key{RET} @var{regexp} @key{RET} Print the number of matches for @var{regexp} that exist in the buffer after point. In Transient Mark mode, if the region is active, the