0001: @c -*- coding: utf-8 -*-
0002: @c This is part of the Emacs manual.
0003: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software
0004: @c Foundation, Inc.
0005: @c See file emacs.texi for copying conditions.
0006: @node Search
0007: @chapter Searching and Replacement
0008: @cindex searching
0009: @cindex finding strings within text
0010: 
0011:   Like other editors, Emacs has commands to search for occurrences of
0012: a string.  Emacs also has commands to replace occurrences of a string
0013: with a different string.  There are also commands that do the same
0014: thing, but search for patterns instead of fixed strings.
0015: 
0016:   You can also search multiple files under the control of @code{xref}
0017: (@pxref{Identifier Search}) or through the Dired @kbd{A} command
0018: (@pxref{Operating on Files}), or ask the @code{grep} program to do it
0019: (@pxref{Grep Searching}).
0020: 
0021: @menu
0022: * Incremental Search::        Search happens as you type the string.
0023: * Nonincremental Search::     Specify entire string and then search.
0024: * Word Search::               Search for sequence of words.
0025: * Symbol Search::             Search for a source code symbol.
0026: * Regexp Search::             Search for match for a regexp.
0027: * Regexps::                   Syntax of regular expressions.
0028: * Regexp Backslash::          Regular expression constructs starting with `\'.
0029: * Regexp Example::            A complex regular expression explained.
0030: * Lax Search::                Search ignores some distinctions among
0031:                                 similar characters, like letter-case.
0032: * Replace::                   Search, and replace some or all matches.
0033: * Other Repeating Search::    Operating on all matches for some regexp.
0034: * Search Customizations::     Various search customizations.
0035: @end menu
0036: 
0037: @node Incremental Search
0038: @section Incremental Search
0039: @cindex incremental search
0040: @cindex isearch
0041: 
0042:   The principal search command in Emacs is @dfn{incremental}: it
0043: begins searching as soon as you type the first character of the search
0044: string.  As you type in the search string, Emacs shows you where the
0045: string (as you have typed it so far) would be found.  When you have
0046: typed enough characters to identify the place you want, you can stop.
0047: Depending on what you plan to do next, you may or may not need to
0048: terminate the search explicitly with @key{RET}.
0049: 
0050: @table @kbd
0051: @item C-s
0052: Incremental search forward (@code{isearch-forward}).
0053: @item C-r
0054: Incremental search backward (@code{isearch-backward}).
0055: @end table
0056: 
0057: You can also invoke incremental search from the menu bar's
0058: @samp{Edit->Search} menu.
0059: 
0060: @menu
0061: * Basic Isearch::        Basic incremental search commands.
0062: * Repeat Isearch::       Searching for the same string again.
0063: * Isearch Yank::         Commands that grab text into the search string
0064:                            or else edit the search string.
0065: * Error in Isearch::     When your string is not found.
0066: * Special Isearch::      Special input in incremental search.
0067: * Not Exiting Isearch::  Prefix argument and scrolling commands.
0068: * Isearch Minibuffer::   Incremental search of the minibuffer history.
0069: @end menu
0070: 
0071: @node Basic Isearch
0072: @subsection Basics of Incremental Search
0073: 
0074: @table @kbd
0075: @item C-s
0076: Begin incremental search (@code{isearch-forward}).
0077: @item C-r
0078: Begin reverse incremental search (@code{isearch-backward}).
0079: @end table
0080: 
0081: @kindex C-s
0082: @findex isearch-forward
0083:   @kbd{C-s} (@code{isearch-forward}) starts a forward incremental
0084: search.  It reads characters from the keyboard, and moves point just
0085: past the end of the next occurrence of those characters in the buffer.
0086: 
0087:   For instance, if you type @kbd{C-s} and then @kbd{F}, that puts the
0088: cursor after the first @samp{F} that occurs in the buffer after the
0089: starting point.  If you then type @kbd{O}, the cursor moves to just
0090: after the first @samp{FO}; the @samp{F} in that @samp{FO} might not be
0091: the first @samp{F} previously found.  After another @kbd{O}, the
0092: cursor moves to just after the first @samp{FOO}.
0093: 
0094: @cindex faces for highlighting search matches
0095: @cindex @code{isearch} face
0096:   At each step, Emacs highlights the @dfn{current match}---the buffer
0097: text that matches the search string---using the @code{isearch} face
0098: (@pxref{Faces}).  @xref{Search Customizations}, for various options
0099: that customize this highlighting.  The current search string is also
0100: displayed in the echo area.
0101: 
0102: @cindex isearch input item
0103: @cindex input item, isearch
0104: @findex isearch-delete-char
0105: @kindex DEL @r{(Incremental search)}
0106:   If you make a mistake typing the search string, type @key{DEL}
0107: (@code{isearch-delete-char}).  Each @key{DEL} cancels the last input
0108: item entered during the search.  Emacs records a new @dfn{input item}
0109: whenever you type a command that changes the search string, the
0110: position of point, the success or failure of the search, the direction
0111: of the search, the position of the other end of the current search
0112: result, or the ``wrappedness'' of the search.  @xref{Error in
0113: Isearch}, for more about dealing with unsuccessful search.
0114: 
0115: @cindex exit incremental search
0116: @cindex incremental search, exiting
0117: @findex isearch-exit
0118: @kindex RET @r{(Incremental search)}
0119:   When you are satisfied with the place you have reached, type
0120: @key{RET} (@code{isearch-exit}).  This stops searching, leaving the
0121: cursor where the search brought it.  Also, any command not specially
0122: meaningful in searches stops the searching and is then executed.
0123: Thus, typing @kbd{C-a} exits the search and then moves to the
0124: beginning of the line; typing one of the arrow keys exits the search
0125: and performs the respective movement command; etc.  @key{RET} is
0126: necessary only if the next command you want to type is a printing
0127: character, @key{DEL}, @key{RET}, or another character that is special
0128: within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s},
0129: @kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some others
0130: described below).  You can fine-tune the commands that exit the
0131: search; see @ref{Not Exiting Isearch}.
0132: 
0133:   As a special exception, entering @key{RET} when the search string is
0134: empty launches nonincremental search (@pxref{Nonincremental Search}).
0135: (This can be customized; see @ref{Search Customizations}.)
0136: 
0137: @findex isearch-abort
0138: @findex isearch-cancel
0139: @kindex C-g C-g @r{(Incremental Search)}
0140: @kindex ESC ESC ESC @r{(Incremental Search)}
0141:   To abandon the search and return to the place where you started,
0142: type @kbd{@key{ESC} @key{ESC} @key{ESC}} (@code{isearch-cancel}) or
0143: @kbd{C-g C-g} (@code{isearch-abort}).
0144: 
0145:   When you exit the incremental search, it adds the original value of
0146: point to the mark ring, without activating the mark; you can thus use
0147: @kbd{C-u C-@key{SPC}} or @kbd{C-x C-x} to return to where you were
0148: before beginning the search.  @xref{Mark Ring}.  (Emacs only does this
0149: if the mark was not already active; if the mark was active when you
0150: started the search, both @kbd{C-u C-@key{SPC}} and @kbd{C-x C-x} will
0151: go to the mark.)
0152: 
0153: @kindex C-r
0154: @findex isearch-backward
0155:   To search backwards, use @kbd{C-r} (@code{isearch-backward}) instead
0156: of @kbd{C-s} to start the search.  A backward search finds matches
0157: that end before the starting point, just as a forward search finds
0158: matches that begin after it.
0159: 
0160: @node Repeat Isearch
0161: @subsection Repeating Incremental Search
0162: 
0163: @kindex C-s @r{(Incremental Search)}
0164: @kindex C-r @r{(Incremental Search)}
0165: @findex isearch-repeat-forward
0166: @findex isearch-repeat-backward
0167:   Suppose you search forward for @samp{FOO} and find a match, but not
0168: the one you expected to find: the @samp{FOO} you were aiming for
0169: occurs later in the buffer.  In this event, type another @kbd{C-s}
0170: (@code{isearch-repeat-forward}) to move to the next occurrence of the
0171: search string.  You can repeat this any number of times.  If you
0172: overshoot, you can cancel some @kbd{C-s} commands with @key{DEL}.
0173: Similarly, each @kbd{C-r} (@code{isearch-repeat-backward}) in a
0174: backward incremental search repeats the backward search.
0175: 
0176: @cindex lazy search highlighting
0177:   If you pause for a little while during incremental search, Emacs
0178: highlights all the other possible matches for the search string that
0179: are present on the screen.  This helps you anticipate where you can
0180: get to by typing @kbd{C-s} or @kbd{C-r} to repeat the search.  The
0181: other matches are highlighted differently from the current match,
0182: using the customizable face @code{lazy-highlight} (@pxref{Faces}).  If
0183: you don't like this feature, you can disable it by setting
0184: @code{isearch-lazy-highlight} to @code{nil}.  For other customizations
0185: related to highlighting matches, see @ref{Search Customizations}.
0186: 
0187:   After exiting a search, you can search for the same string again by
0188: typing just @kbd{C-s C-s}.  The first @kbd{C-s} is the key that
0189: invokes incremental search, and the second @kbd{C-s} means to search
0190: again for the last search string.  Similarly, @kbd{C-r C-r} searches
0191: backward for the last search string.  In determining the last search
0192: string, it doesn't matter whether that string was searched for with
0193: @kbd{C-s} or @kbd{C-r}.
0194: 
0195:   If you are searching forward but you realize you were looking for
0196: something before the starting point, type @kbd{C-r} to switch to a
0197: backward search, leaving the search string unchanged.  Similarly,
0198: @kbd{C-s} in a backward search switches to a forward search.
0199: 
0200: @cindex search, wrapping around
0201: @cindex search, overwrapped
0202: @cindex wrapped search
0203: @cindex overwrapped search
0204:   If a search is failing and you ask to repeat it by typing another
0205: @kbd{C-s}, it starts again from the beginning of the buffer.
0206: Repeating a failing reverse search with @kbd{C-r} starts again from
0207: the end.  This is called @dfn{wrapping around}, and @samp{Wrapped}
0208: appears in the search prompt once this has happened.  If you keep on
0209: going past the original starting point of the search, it changes to
0210: @samp{Overwrapped}, which means that you are revisiting matches that
0211: you have already seen.
0212: 
0213: @cindex search ring
0214: @findex isearch-ring-advance
0215: @findex isearch-ring-retreat
0216: @kindex M-n @r{(Incremental search)}
0217: @kindex M-p @r{(Incremental search)}
0218: @vindex search-ring-max
0219:   To reuse earlier search strings, use the @dfn{search ring}.  The
0220: commands @kbd{M-p} (@code{isearch-ring-retreat}) and @kbd{M-n}
0221: (@code{isearch-ring-advance}) move through the ring to pick a search
0222: string to reuse.  These commands leave the selected search ring
0223: element in the minibuffer, where you can edit it.  Type
0224: @kbd{C-s}/@kbd{C-r} or @key{RET} to accept the string and start
0225: searching for it.  The number of most recently used search strings
0226: saved in the search ring is specified by the variable
0227: @code{search-ring-max}, 16 by default.
0228: 
0229: @cindex incremental search, edit search string
0230: @cindex interactively edit search string
0231: @findex isearch-edit-string
0232: @kindex M-e @r{(Incremental search)}
0233: @kindex mouse-1 @r{in the minibuffer (Incremental Search)}
0234:   To edit the current search string in the minibuffer without
0235: replacing it with items from the search ring, type @kbd{M-e}
0236: (@code{isearch-edit-string}) or click @kbd{mouse-1} in the minibuffer.
0237: Type @key{RET}, @kbd{C-s} or @kbd{C-r} to finish editing the string
0238: and search for it.  Type @kbd{C-f} or @kbd{@key{RIGHT}} to add to the
0239: search string characters following point from the buffer from which
0240: you started the search.
0241: 
0242: @node Isearch Yank
0243: @subsection Isearch Yanking
0244: 
0245:   In many cases, you will want to use text at or near point as your
0246: search string.  The commands described in this subsection let you do
0247: that conveniently.
0248: 
0249: @kindex C-w @r{(Incremental search)}
0250: @findex isearch-yank-word-or-char
0251:   @kbd{C-w} (@code{isearch-yank-word-or-char}) appends the next
0252: character or word at point to the search string.  This is an easy way
0253: to search for another occurrence of the text at point.  (The decision
0254: of whether to copy a character or a word is heuristic.)
0255: 
0256: @kindex C-M-w @r{(Incremental search)}
0257: @findex isearch-yank-symbol-or-char
0258:   @kbd{C-M-w} (@code{isearch-yank-symbol-or-char}) appends the next
0259: character or symbol at point to the search string.  This is an easy way
0260: to search for another occurrence of the symbol at point.  (The decision
0261: of whether to copy a character or a symbol is heuristic.)
0262: 
0263: @kindex M-s C-e @r{(Incremental search)}
0264: @findex isearch-yank-line
0265:   Similarly, @kbd{M-s C-e} (@code{isearch-yank-line}) appends the rest
0266: of the current line to the search string.  If point is already at the
0267: end of a line, it appends the next line.  With a prefix argument
0268: @var{n}, it appends the next @var{n} lines.
0269: 
0270: @kindex C-y @r{(Incremental search)}
0271: @kindex M-y @r{(Incremental search)}
0272: @kindex mouse-2 @r{in the minibuffer (Incremental search)}
0273: @findex isearch-yank-kill
0274: @findex isearch-yank-pop
0275: @findex isearch-yank-x-selection
0276:   Within incremental search, @kbd{C-y} (@code{isearch-yank-kill})
0277: appends the current kill to the search string.  @kbd{M-y}
0278: (@code{isearch-yank-pop}), if called after @kbd{C-y}, replaces that
0279: appended text with an earlier kill, similar to the usual @kbd{M-y}
0280: (@code{yank-pop}) command (@pxref{Yanking}).  Clicking @kbd{mouse-2}
0281: in the echo area appends the current X selection (@pxref{Primary
0282: Selection}) to the search string (@code{isearch-yank-x-selection}).
0283: 
0284: @kindex C-M-d @r{(Incremental search)}
0285: @kindex C-M-y @r{(Incremental search)}
0286: @findex isearch-del-char
0287: @findex isearch-yank-char
0288:   @kbd{C-M-d} (@code{isearch-del-char}) deletes the last character
0289: from the search string, and @kbd{C-M-y} (@code{isearch-yank-char})
0290: appends the character after point to the search string.  An
0291: alternative method to add the character after point is to enter the
0292: minibuffer with @kbd{M-e} (@pxref{Repeat Isearch}) and type @kbd{C-f}
0293: or @kbd{@key{RIGHT}} at the end of the search string in the
0294: minibuffer.  Each @kbd{C-f} or @kbd{@key{RIGHT}} you type adds another
0295: character following point to the search string.
0296: 
0297:   Normally, when the search is case-insensitive, text yanked into the
0298: search string is converted to lower case, so that the search remains
0299: case-insensitive (@pxref{Lax Search, case folding}).  However, if the
0300: value of the variable @code{search-upper-case} (@pxref{Lax Search,
0301: search-upper-case}) is other than @code{not-yanks}, that disables this
0302: down-casing.
0303: 
0304: @node Error in Isearch
0305: @subsection Errors in Incremental Search
0306: 
0307: @cindex @code{isearch-fail} face
0308:   If your string is not found at all, the echo area says @samp{Failing
0309: I-Search}, and the cursor moves past the place where Emacs found as
0310: much of your string as it could.  Thus, if you search for @samp{FOOT},
0311: and there is no @samp{FOOT}, you might see the cursor after the
0312: @samp{FOO} in @samp{FOOL}.  In the echo area, the part of the search
0313: string that failed to match is highlighted using the face
0314: @code{isearch-fail}.
0315: 
0316:   At this point, there are several things you can do.  If your string
0317: was mistyped, use @key{DEL} to cancel a previous input item
0318: (@pxref{Basic Isearch}), @kbd{C-M-d} to erase one character at a time,
0319: or @kbd{M-e} to edit it.  If you like the place you have found, you
0320: can type @key{RET} to remain there.  Or you can type @kbd{C-g}, which
0321: removes from the search string the characters that could not be found
0322: (the @samp{T} in @samp{FOOT}), leaving those that were found (the
0323: @samp{FOO} in @samp{FOOT}).  A second @kbd{C-g} at that point cancels
0324: the search entirely, returning point to where it was when the search
0325: started.
0326: 
0327: @cindex quitting (in search)
0328: @kindex C-g @r{(Incremental search)}
0329:   The quit command, @kbd{C-g}, does special things during searches;
0330: just what it does depends on the status of the search.  If the search
0331: has found what you specified and is waiting for input, @kbd{C-g}
0332: cancels the entire search, moving the cursor back to where you started
0333: the search.  If @kbd{C-g} is typed when there are characters in the
0334: search string that have not been found---because Emacs is still
0335: searching for them, or because it has failed to find them---then the
0336: search string characters which have not been found are discarded from
0337: the search string.  With them gone, the search is now successful and
0338: waiting for more input, so a second @kbd{C-g} will cancel the entire
0339: search.
0340: 
0341: @node Special Isearch
0342: @subsection Special Input for Incremental Search
0343: 
0344:   In addition to characters described in the previous subsections,
0345: some of the other characters you type during incremental search have
0346: special effects.  They are described here.
0347: 
0348:   To toggle lax space matching (@pxref{Lax Search, lax space
0349: matching}), type @kbd{M-s @key{SPC}}.
0350: 
0351:   To toggle case sensitivity of the search, type @kbd{M-c} or
0352: @kbd{M-s c}.  @xref{Lax Search, case folding}.  If the search string
0353: includes upper-case letters, the search is case-sensitive by default.
0354: 
0355:   To toggle whether or not the search will consider similar and
0356: equivalent characters as a match, type @kbd{M-s '}.  @xref{Lax Search,
0357: character folding}.  If the search string includes accented
0358: characters, that disables character folding during that search.
0359: 
0360: @cindex invisible text, searching for
0361: @kindex M-s i @r{(Incremental search)}
0362: @findex isearch-toggle-invisible
0363:   To toggle whether or not invisible text is searched, type
0364: @kbd{M-s i} (@code{isearch-toggle-invisible}).  @xref{Outline Search}.
0365: 
0366: @kindex M-r @r{(Incremental Search)}
0367: @kindex M-s r @r{(Incremental Search)}
0368: @findex isearch-toggle-regexp
0369:   To toggle between non-regexp and regexp incremental search, type
0370: @kbd{M-r} or @kbd{M-s r} (@code{isearch-toggle-regexp}).
0371: @xref{Regexp Search}.
0372: 
0373:   To toggle symbol mode, type @kbd{M-s _}.  @xref{Symbol Search}.
0374: 
0375:   To search for a newline character, type @kbd{C-j} as part of the
0376: search string.
0377: 
0378:   To search for non-@acronym{ASCII} characters, use one of the
0379: following methods:
0380: 
0381: @itemize @bullet
0382: @item
0383: @findex isearch-quote-char
0384: @kindex C-q @r{(Incremental Search)}
0385: Type @kbd{C-q} (@code{isearch-quote-char}), followed by a non-graphic
0386: character or a sequence of octal digits.  This adds a character to the
0387: search string, similar to inserting into a buffer using @kbd{C-q}
0388: (@pxref{Inserting Text}).  For example, @kbd{C-q C-s} during
0389: incremental search adds the @samp{control-S} character to the search
0390: string.
0391: 
0392: @item
0393: @findex isearch-char-by-name
0394: @kindex C-x 8 RET @r{(Incremental Search)}
0395: Type @kbd{C-x 8 @key{RET}} (@code{isearch-char-by-name}), followed by
0396: a Unicode name or code-point in hex.  This adds the specified
0397: character into the search string, similar to the usual
0398: @code{insert-char} command (@pxref{Inserting Text}).
0399: 
0400: @item
0401: @kindex C-^ @r{(Incremental Search)}
0402: @findex isearch-toggle-input-method
0403: @findex isearch-toggle-specified-input-method
0404: Use an input method (@pxref{Input Methods}).  If an input method is
0405: enabled in the current buffer when you start the search, the same
0406: method will be active in the minibuffer when you type the search
0407: string.  While typing the search string, you can toggle the input
0408: method with @kbd{C-\} (@code{isearch-toggle-input-method}).  You can
0409: also turn on a non-default input method with @kbd{C-^}
0410: (@code{isearch-toggle-specified-input-method}), which prompts for the
0411: name of the input method.  When an input method is active during
0412: incremental search, the search prompt includes the input method
0413: mnemonic, like this:
0414: 
0415: @example
0416: I-search [@var{im}]:
0417: @end example
0418: 
0419: @noindent
0420: where @var{im} is the mnemonic of the active input method.  Any input
0421: method you enable during incremental search remains enabled in the
0422: current buffer afterwards.
0423: @end itemize
0424: 
0425: @kindex M-s o @r{(Incremental Search)}
0426: @findex isearch-occur
0427:   Typing @kbd{M-s o} in incremental search invokes
0428: @code{isearch-occur}, which runs @code{occur} with the current search
0429: string.  @xref{Other Repeating Search, occur}.
0430: 
0431: @findex isearch-query-replace
0432: @findex isearch-query-replace-regexp
0433: @kindex M-% @r{(Incremental search)}
0434: @kindex C-M-% @r{(Incremental search)}
0435:   Typing @kbd{M-%} (@code{isearch-query-replace}) in incremental
0436: search invokes @code{query-replace} or @code{query-replace-regexp}
0437: (depending on search mode) with the current search string used as the
0438: string to replace.  A negative prefix argument means to replace
0439: backward.  @xref{Query Replace}.  Typing @kbd{C-M-%}
0440: (@code{isearch-query-replace-regexp}) invokes
0441: @code{query-replace-regexp} with the current search string used as the
0442: regexp to replace.
0443: 
0444: @findex isearch-complete
0445: @kindex M-TAB @r{(Incremental search)}
0446:   Typing @kbd{M-@key{TAB}} in incremental search invokes
0447: @code{isearch-complete}, which attempts to complete the search string
0448: using the search ring (the previous search strings you used) as a list
0449: of completion alternatives.  @xref{Completion}.  In many operating
0450: systems, the @kbd{M-@key{TAB}} key sequence is captured by the window
0451: manager; you then need to rebind @code{isearch-complete} to another
0452: key sequence if you want to use it (@pxref{Rebinding}).
0453: 
0454: @kindex M-s h r @r{(Incremental Search)}
0455: @findex isearch-highlight-regexp
0456:   You can exit the search while leaving the matches for the last
0457: search string highlighted on display.  To this end, type @kbd{M-s h r}
0458: (@code{isearch-highlight-regexp}), which will run
0459: @code{highlight-regexp} (@pxref{Highlight Interactively}) passing
0460: it the regexp derived from the last search string and prompting you
0461: for the face to use for highlighting.  To remove the highlighting,
0462: type @kbd{M-s h u} (@code{unhighlight-regexp}).
0463: 
0464: @cindex incremental search, help on special keys
0465: @kindex C-h C-h @r{(Incremental Search)}
0466: @findex isearch-help-map
0467: @vindex isearch-mode-map
0468:   When incremental search is active, you can type @kbd{C-h C-h}
0469: (@code{isearch-help-map}) to access interactive help options,
0470: including a list of special key bindings.  These key bindings are part
0471: of the keymap @code{isearch-mode-map} (@pxref{Keymaps}).
0472: 
0473: @node Not Exiting Isearch
0474: @subsection Not Exiting Incremental Search
0475: 
0476: This subsection describes how to control whether typing a command not
0477: specifically meaningful in searches exits the search before executing
0478: the command.  It also describes three categories of commands which you
0479: can type without exiting the current incremental search, even though
0480: they are not themselves part of incremental search.
0481: 
0482: @vindex search-exit-option
0483:   Normally, typing a command that is not bound by the incremental
0484: search exits the search before executing the command.  Thus, the
0485: command operates on the buffer from which you invoked the search.
0486: However, if you customize the variable @code{search-exit-option} to
0487: @code{append}, the characters which you type that are not interpreted by
0488: the incremental search are simply appended to the search string.  This
0489: is so you could include in the search string control characters, such
0490: as @kbd{C-a}, that would normally exit the search and invoke the
0491: command bound to them on the buffer.
0492: 
0493: @table @asis
0494: @item Prefix Arguments
0495: @cindex prefix argument commands, during incremental search
0496: @vindex isearch-allow-prefix
0497:   In incremental search, when you type a command that specifies a
0498: prefix argument (@pxref{Arguments}), by default it will apply either
0499: to the next action in the search or to the command that exits the
0500: search.  In other words, entering a prefix argument will not by itself
0501: terminate the search.
0502: 
0503:   In previous versions of Emacs, entering a prefix argument always
0504: terminated the search.  You can revert to this behavior by setting the
0505: variable @code{isearch-allow-prefix} to @code{nil}.
0506: 
0507:   When @code{isearch-allow-scroll} is non-@code{nil} (see below),
0508: prefix arguments always have the default behavior described above,
0509: i.e., they don't terminate the search, even if
0510: @code{isearch-allow-prefix} is @code{nil}.
0511: 
0512: @item Scrolling Commands
0513: @cindex scrolling commands, during incremental search
0514: @vindex isearch-allow-scroll
0515:   Normally, scrolling commands exit incremental search.  If you change
0516: the variable @code{isearch-allow-scroll} to a non-@code{nil} value,
0517: that enables the use of the scroll-bar, as well as keyboard scrolling
0518: commands like @kbd{C-v}, @kbd{M-v}, and @kbd{C-l} (@pxref{Scrolling}).
0519: This applies only to calling these commands via their bound key
0520: sequences---typing @kbd{M-x} will still exit the search.  You can give
0521: prefix arguments to these commands in the usual way.  This feature
0522: won't let you scroll the current match out of visibility, however.
0523: 
0524:   The @code{isearch-allow-scroll} feature also affects some other
0525: commands, such as @kbd{C-x 2} (@code{split-window-below}) and
0526: @kbd{C-x ^} (@code{enlarge-window}), which don't exactly scroll but do
0527: affect where the text appears on the screen.  It applies to any
0528: command whose name has a non-@code{nil} @code{isearch-scroll}
0529: property.  So you can control which commands are affected by changing
0530: these properties.
0531: 
0532: @cindex prevent commands from exiting incremental search
0533:   For example, to make @kbd{C-h l} usable within an incremental search
0534: in all future Emacs sessions, use @kbd{C-h c} to find what command it
0535: runs (@pxref{Key Help}), which is @code{view-lossage}.  Then you can
0536: put the following line in your init file (@pxref{Init File}):
0537: 
0538: @example
0539: (put 'view-lossage 'isearch-scroll t)
0540: @end example
0541: 
0542: @noindent
0543: This feature can be applied to any command that doesn't permanently
0544: change point, the buffer contents, the match data, the current buffer,
0545: or the selected window and frame.  The command must not itself attempt
0546: an incremental search.  This feature is disabled if
0547: @code{isearch-allow-scroll} is @code{nil} (which it is by default).
0548: 
0549: @item Motion Commands
0550: @cindex motion commands, during incremental search
0551: When @code{isearch-yank-on-move} is customized to @code{shift},
0552: you can extend the search string by holding down the shift key while
0553: typing cursor motion commands.  It will yank text that ends at the new
0554: position after moving point in the current buffer.
0555: 
0556: When @code{isearch-yank-on-move} is @code{t}, you can extend the
0557: search string without using the shift key for cursor motion commands,
0558: but it applies only for certain motion command that have the
0559: @code{isearch-move} property on their symbols.
0560: @end table
0561: 
0562: @node Isearch Minibuffer
0563: @subsection Searching the Minibuffer
0564: @cindex minibuffer history, searching
0565: 
0566: If you start an incremental search while the minibuffer is active,
0567: Emacs searches the contents of the minibuffer.  Unlike searching an
0568: ordinary buffer, the search string is not shown in the echo area,
0569: because that is used to display the minibuffer.
0570: 
0571: If an incremental search fails in the minibuffer, it tries searching
0572: the minibuffer history.  @xref{Minibuffer History}.  You can visualize
0573: the minibuffer and its history as a series of pages, with the
0574: earliest history element on the first page and the current minibuffer
0575: on the last page.  A forward search, @kbd{C-s}, searches forward to
0576: later pages; a reverse search, @kbd{C-r}, searches backwards to
0577: earlier pages.  Like in ordinary buffer search, a failing search can
0578: wrap around, going from the last page to the first page or vice versa.
0579: 
0580: When the current match is on a history element, that history element
0581: is pulled into the minibuffer.  If you exit the incremental search
0582: normally (e.g., by typing @key{RET}), it remains in the minibuffer
0583: afterwards.  Canceling the search, with @kbd{C-g}, restores the
0584: contents of the minibuffer when you began the search.
0585: 
0586: @node Nonincremental Search
0587: @section Nonincremental Search
0588: @cindex nonincremental search
0589: 
0590:   Emacs also has conventional nonincremental search commands, which require
0591: you to type the entire search string before searching begins.
0592: 
0593: @table @kbd
0594: @item C-s @key{RET} @var{string} @key{RET}
0595: Search for @var{string}.
0596: @item C-r @key{RET} @var{string} @key{RET}
0597: Search backward for @var{string}.
0598: @end table
0599: 
0600:   To start a nonincremental search, first type @kbd{C-s @key{RET}}.
0601: This enters the minibuffer to read the search string; terminate the
0602: string with @key{RET}, and then the search takes place.  If the string
0603: is not found, the search command signals an error.
0604: 
0605:   When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental
0606: search as usual.  That command is specially programmed to invoke the
0607: command for nonincremental search, if the string you specify is empty.
0608: (Such an empty argument would otherwise be useless.)  @kbd{C-r
0609: @key{RET}} does likewise, invoking the nonincremental
0610: backward-searching command.
0611: 
0612:   Nonincremental search can also be invoked from the menu bar's
0613: @samp{Edit->Search} menu.
0614: 
0615: @findex search-forward
0616: @findex search-backward
0617:   You can also use two simpler commands, @kbd{M-x search-forward} and
0618: @kbd{M-x search-backward}.  These commands look for the literal
0619: strings you specify, and don't support any of the lax-search features
0620: (@pxref{Lax Search}) except case folding.
0621: 
0622: @node Word Search
0623: @section Word Search
0624: @cindex word search
0625: 
0626:   A @dfn{word search} finds a sequence of words without regard to the
0627: type of punctuation between them.  For instance, if you enter a search
0628: string that consists of two words separated by a single space, the
0629: search matches any sequence of those two words separated by one or
0630: more spaces, newlines, or other punctuation characters.  This is
0631: particularly useful for searching text documents, because you don't
0632: have to worry whether the words you are looking for are separated by
0633: newlines or spaces.  Note that major modes for programming languages
0634: or other specialized modes can modify the definition of a word to suit
0635: their syntactic needs.
0636: 
0637: @table @kbd
0638: @item M-s w
0639:   If incremental search is active, toggle word search mode
0640: (@code{isearch-toggle-word}); otherwise, begin an incremental forward
0641: word search (@code{isearch-forward-word}).
0642: @item M-s w @key{RET} @var{words} @key{RET}
0643: Search for @var{words}, using a forward nonincremental word search.
0644: @item M-s w C-r @key{RET} @var{words} @key{RET}
0645: Search backward for @var{words}, using a nonincremental word search.
0646: @item M-s M-w
0647: Search the Web for the text in region.
0648: @end table
0649: 
0650: @findex isearch-forward-word
0651: @findex isearch-toggle-word
0652: @kindex M-s w
0653:   To begin a forward incremental word search, type @kbd{M-s w}.  If
0654: incremental search is not already active, this runs the command
0655: @code{isearch-forward-word}.  If incremental search is already active
0656: (whether a forward or backward search), @kbd{M-s w} runs the command
0657: @code{isearch-toggle-word}, which switches to a word search while
0658: keeping the direction of the search and the current search string
0659: unchanged.  You can toggle word search back off by typing @kbd{M-s w}
0660: again.
0661: 
0662: @findex word-search-forward
0663: @findex word-search-backward
0664:   To begin a nonincremental word search, type @kbd{M-s w @key{RET}}
0665: for a forward search, or @kbd{M-s w C-r @key{RET}} for a backward search.
0666: These run the commands @code{word-search-forward} and
0667: @code{word-search-backward} respectively.
0668: 
0669:   Incremental and nonincremental word searches differ slightly in the
0670: way they find a match.  In a nonincremental word search, each word in
0671: the search string must exactly match a whole word.  In an incremental
0672: word search, the matching is more lax: while you are typing the search
0673: string, its first and last words need not match whole words.  This is
0674: so that the matching can proceed incrementally as you type.  This
0675: additional laxity does not apply to the lazy highlight
0676: (@pxref{Incremental Search}), which always matches whole words.
0677: While you are typing the search string, @samp{Pending} appears in the
0678: search prompt until you use a search repeating key like @kbd{C-s}.
0679: 
0680:   The word search commands don't perform character folding, and
0681: toggling lax whitespace matching (@pxref{Lax Search, lax space
0682: matching}) has no effect on them.
0683: 
0684: @kindex M-s M-w
0685: @findex eww-search-words
0686: @vindex eww-search-prefix
0687: @cindex Internet search
0688: @cindex search Internet for keywords
0689:   To search the Web for the text in region, type @kbd{M-s M-w}.  This
0690: command performs an Internet search for the words in region using the
0691: search engine whose @acronym{URL} is specified by the variable
0692: @code{eww-search-prefix} (@pxref{Basics, EWW, , eww, The Emacs Web
0693: Wowser Manual}).  If the region is not active, or doesn't contain any
0694: words, this command prompts the user for a URL or keywords to search.
0695: 
0696: 
0697: @node Symbol Search
0698: @section Symbol Search
0699: @cindex symbol search
0700: 
0701:   A @dfn{symbol search} is much like an ordinary search, except that
0702: the boundaries of the search must match the boundaries of a symbol.
0703: The meaning of @dfn{symbol} in this context depends on the major mode,
0704: and usually refers to a source code token, such as a Lisp symbol in
0705: Emacs Lisp mode.  For instance, if you perform an incremental symbol
0706: search for the Lisp symbol @code{forward-word}, it would not match
0707: @code{isearch-forward-word}.  This feature is thus mainly useful for
0708: searching source code.
0709: 
0710: @table @kbd
0711: @item M-s _
0712: @findex isearch-toggle-symbol
0713: If incremental search is active, toggle symbol search mode
0714: (@code{isearch-toggle-symbol}); otherwise, begin an incremental
0715: forward symbol search (@code{isearch-forward-symbol}).
0716: @item M-s .
0717: Start a symbol incremental search forward with the symbol found near
0718: point added to the search string initially.
0719: @item M-s _ @key{RET} @var{symbol} @key{RET}
0720: Search forward for @var{symbol}, nonincrementally.
0721: @item M-s _ C-r @key{RET} @var{symbol} @key{RET}
0722: Search backward for @var{symbol}, nonincrementally.
0723: @end table
0724: 
0725: @kindex M-s _
0726: @kindex M-s .
0727: @findex isearch-forward-symbol
0728: @findex isearch-forward-symbol-at-point
0729:   To begin a forward incremental symbol search, type @kbd{M-s _} (or
0730: @kbd{M-s .} if the symbol to search is near point).  If incremental
0731: search is not already active, this runs the command
0732: @code{isearch-forward-symbol}.  If incremental search is already
0733: active, @kbd{M-s _} switches to a symbol search, preserving the
0734: direction of the search and the current search string; you can disable
0735: symbol search by typing @kbd{M-s _} again.  In incremental symbol
0736: search, while you are typing the search string, only the beginning
0737: of the search string is required to match the beginning of a symbol,
0738: and @samp{Pending} appears in the search prompt until you use a search
0739: repeating key like @kbd{C-s}.
0740: 
0741:   To begin a nonincremental symbol search, type @kbd{M-s _ @key{RET}}
0742: for a forward search, or @kbd{M-s _ C-r @key{RET}} or a backward
0743: search.  In nonincremental symbol searches, the beginning and end of
0744: the search string are required to match the beginning and end of a
0745: symbol, respectively.
0746: 
0747:   The symbol search commands don't perform character folding, and
0748: toggling lax whitespace matching (@pxref{Lax Search, lax space
0749: matching}) has no effect on them.
0750: 
0751: @node Regexp Search
0752: @section Regular Expression Search
0753: @cindex regexp search
0754: @cindex search for a regular expression
0755: 
0756:   A @dfn{regular expression} (or @dfn{regexp} for short) is a pattern
0757: that denotes a class of alternative strings to match.  Emacs
0758: provides both incremental and nonincremental ways to search for a
0759: match for a regexp.  The syntax of regular expressions is explained in
0760: the next section.
0761: 
0762: @table @kbd
0763: @item C-M-s
0764: Begin incremental regexp search (@code{isearch-forward-regexp}).
0765: @item C-M-r
0766: Begin reverse incremental regexp search (@code{isearch-backward-regexp}).
0767: @end table
0768: 
0769: @kindex C-M-s
0770: @findex isearch-forward-regexp
0771: @kindex C-M-r
0772: @findex isearch-backward-regexp
0773:   Incremental search for a regexp is done by typing @kbd{C-M-s}
0774: (@code{isearch-forward-regexp}), by invoking @kbd{C-s} with a
0775: prefix argument (whose value does not matter), or by typing @kbd{M-r}
0776: within a forward incremental search.  This command reads a
0777: search string incrementally just like @kbd{C-s}, but it treats the
0778: search string as a regexp rather than looking for an exact match
0779: against the text in the buffer.  Each time you add text to the search
0780: string, you make the regexp longer, and the new regexp is searched
0781: for.  To search backward for a regexp, use @kbd{C-M-r}
0782: (@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument,
0783: or @kbd{M-r} within a backward incremental search.
0784: 
0785: @vindex regexp-search-ring-max
0786:   All of the special key sequences in an ordinary incremental search
0787: (@pxref{Special Isearch}) do similar things in an incremental regexp
0788: search.  For instance, typing @kbd{C-s} immediately after starting the
0789: search retrieves the last incremental search regexp used and searches
0790: forward for it.  Incremental regexp and non-regexp searches have
0791: independent defaults.  They also have separate search rings, which you
0792: can access with @kbd{M-p} and @kbd{M-n}.  The maximum number of search
0793: regexps saved in the search ring is determined by the value of
0794: @code{regexp-search-ring-max}, 16 by default.
0795: 
0796:   Unlike ordinary incremental search, incremental regexp search
0797: does not use lax space matching by default.  To toggle this feature
0798: use @kbd{M-s @key{SPC}} (@code{isearch-toggle-lax-whitespace}).
0799: Then any @key{SPC} typed in incremental regexp search will match
0800: any sequence of one or more whitespace characters.  The variable
0801: @code{search-whitespace-regexp} specifies the regexp for the lax
0802: space matching.  @xref{Special Isearch}.
0803: 
0804:   Also unlike ordinary incremental search, incremental regexp search
0805: cannot use character folding (@pxref{Lax Search}).  (If you toggle
0806: character folding during incremental regexp search with @kbd{M-s '},
0807: the search becomes a non-regexp search and the search pattern you
0808: typed is interpreted as a literal string.)
0809: 
0810:   In some cases, adding characters to the regexp in an incremental
0811: regexp search can make the cursor move back and start again.  For
0812: example, if you have searched for @samp{foo} and you add @samp{\|bar},
0813: the cursor backs up in case the first @samp{bar} precedes the first
0814: @samp{foo}.  @xref{Regexps}.
0815: 
0816:   Forward and backward regexp search are not symmetrical, because
0817: regexp matching in Emacs always operates forward, starting with the
0818: beginning of the regexp.  Thus, forward regexp search scans forward,
0819: trying a forward match at each possible starting position.  Backward
0820: regexp search scans backward, trying a forward match at each possible
0821: starting position.  These search methods are not mirror images.
0822: 
0823: @findex re-search-forward
0824: @findex re-search-backward
0825:   Nonincremental search for a regexp is done with the commands
0826: @code{re-search-forward} and @code{re-search-backward}.  You can
0827: invoke these with @kbd{M-x}, or by way of incremental regexp search
0828: with @kbd{C-M-s @key{RET}} and @kbd{C-M-r @key{RET}}.  When you invoke
0829: these commands with @kbd{M-x}, they search for the exact regexp you
0830: specify, and thus don't support any lax-search features (@pxref{Lax
0831: Search}) except case folding.
0832: 
0833:   If you use the incremental regexp search commands with a prefix
0834: argument, they perform ordinary string search, like
0835: @code{isearch-forward} and @code{isearch-backward}.  @xref{Incremental
0836: Search}.
0837: 
0838: @node Regexps
0839: @section Syntax of Regular Expressions
0840: @cindex syntax of regexps
0841: @cindex regular expression
0842: @cindex regexp
0843: 
0844:   This section (and this manual in general) describes regular
0845: expression features that users typically use.  @xref{Regular
0846: Expressions,,, elisp, The Emacs Lisp Reference Manual}, for additional
0847: features used mainly in Lisp programs.
0848: 
0849:   Regular expressions have a syntax in which a few characters are
0850: special constructs and the rest are @dfn{ordinary}.  An ordinary
0851: character matches that same character and nothing else.  The special
0852: characters are @samp{$^.*+?[\}.  The character @samp{]} is special if
0853: it ends a character alternative (see below).  The character @samp{-}
0854: is special inside a character alternative.  Any other character
0855: appearing in a regular expression is ordinary, unless a @samp{\}
0856: precedes it.  (When you use regular expressions in a Lisp program,
0857: each @samp{\} must be doubled, see the example near the end of this
0858: section.)
0859: 
0860:   For example, @samp{f} is not a special character, so it is ordinary, and
0861: therefore @samp{f} is a regular expression that matches the string
0862: @samp{f} and no other string.  (It does @emph{not} match the string
0863: @samp{ff}.)  Likewise, @samp{o} is a regular expression that matches
0864: only @samp{o}.  (When case distinctions are being ignored, these regexps
0865: also match @samp{F} and @samp{O}, but we consider this a generalization
0866: of ``the same string'', rather than an exception.)
0867: 
0868:   Any two regular expressions @var{a} and @var{b} can be concatenated.
0869: The result is a regular expression which matches a string if @var{a}
0870: matches some amount of the beginning of that string and @var{b}
0871: matches the rest of the string.  As a trivial example, concatenating
0872: the regular expressions @samp{f} and @samp{o} gives the regular
0873: expression @samp{fo}, which matches only the string @samp{fo}.  To do
0874: something less trivial, you need to use one of the special characters.
0875: Here is a list of them.
0876: 
0877: @table @asis
0878: @item @kbd{.}@: @r{(Period)}
0879: is a special character that matches any single character except a
0880: newline.  For example, the regular expressions @samp{a.b} matches any
0881: three-character string that begins with @samp{a} and ends with
0882: @samp{b}.
0883: 
0884: @item @kbd{*}
0885: is not a construct by itself; it is a postfix operator that means to
0886: match the preceding regular expression repetitively any number of
0887: times, as many times as possible.  Thus, @samp{o*} matches any number
0888: of @samp{o}s, including no @samp{o}s.
0889: 
0890: @samp{*} always applies to the @emph{smallest} possible preceding
0891: expression.  Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
0892: @samp{fo}.  It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
0893: 
0894: The matcher processes a @samp{*} construct by matching, immediately,
0895: as many repetitions as can be found.  Then it continues with the rest
0896: of the pattern.  If that fails, backtracking occurs, discarding some
0897: of the matches of the @samp{*}-modified construct in case that makes
0898: it possible to match the rest of the pattern.  For example, in matching
0899: @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
0900: tries to match all three @samp{a}s; but the rest of the pattern is
0901: @samp{ar} and there is only @samp{r} left to match, so this try fails.
0902: The next alternative is for @samp{a*} to match only two @samp{a}s.
0903: With this choice, the rest of the regexp matches successfully.
0904: 
0905: @item @kbd{+}
0906: is a postfix operator, similar to @samp{*} except that it must match
0907: the preceding expression at least once.  Thus, @samp{ca+r} matches the
0908: strings @samp{car} and @samp{caaaar} but not the string @samp{cr},
0909: whereas @samp{ca*r} matches all three strings.
0910: 
0911: @item @kbd{?}
0912: is a postfix operator, similar to @samp{*} except that it can match
0913: the preceding expression either once or not at all.  Thus, @samp{ca?r}
0914: matches @samp{car} or @samp{cr}, and nothing else.
0915: 
0916: @item @kbd{*?}, @kbd{+?}, @kbd{??}
0917: @cindex non-greedy regexp matching
0918: are non-@dfn{greedy} variants of the operators above.  The normal
0919: operators @samp{*}, @samp{+}, @samp{?} match as much as they can, as
0920: long as the overall regexp can still match.  With a following
0921: @samp{?}, they will match as little as possible.
0922: 
0923: Thus, both @samp{ab*} and @samp{ab*?} can match the string @samp{a}
0924: and the string @samp{abbbb}; but if you try to match them both against
0925: the text @samp{abbb}, @samp{ab*} will match it all (the longest valid
0926: match), while @samp{ab*?}  will match just @samp{a} (the shortest
0927: valid match).
0928: 
0929: Non-greedy operators match the shortest possible string starting at a
0930: given starting point; in a forward search, though, the earliest
0931: possible starting point for match is always the one chosen.  Thus, if
0932: you search for @samp{a.*?$} against the text @samp{abbab} followed by
0933: a newline, it matches the whole string.  Since it @emph{can} match
0934: starting at the first @samp{a}, it does.
0935: 
0936: @item @kbd{\@{@var{n}\@}}
0937: is a postfix operator specifying @var{n} repetitions---that is, the
0938: preceding regular expression must match exactly @var{n} times in a
0939: row.  For example, @samp{x\@{4\@}} matches the string @samp{xxxx} and
0940: nothing else.
0941: 
0942: @item @kbd{\@{@var{n},@var{m}\@}}
0943: is a postfix operator specifying between @var{n} and @var{m}
0944: repetitions---that is, the preceding regular expression must match at
0945: least @var{n} times, but no more than @var{m} times.  If @var{m} is
0946: omitted, then there is no upper limit, but the preceding regular
0947: expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is
0948: equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to
0949: @samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}.
0950: 
0951: @item @kbd{[ @dots{} ]}
0952: is a @dfn{character set}, beginning with @samp{[} and terminated by
0953: @samp{]}.
0954: 
0955: In the simplest case, the characters between the two brackets are what
0956: this set can match.  Thus, @samp{[ad]} matches either one @samp{a} or
0957: one @samp{d}, and @samp{[ad]*} matches any string composed of just
0958: @samp{a}s and @samp{d}s (including the empty string).  It follows that
0959: @samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr},
0960: @samp{caddaar}, etc.
0961: 
0962: You can also include character ranges in a character set, by writing the
0963: starting and ending characters with a @samp{-} between them.  Thus,
0964: @samp{[a-z]} matches any lower-case @acronym{ASCII} letter.  Ranges may be
0965: intermixed freely with individual characters, as in @samp{[a-z$%.]},
0966: which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or
0967: period.  As another example, @samp{[α-ωί]} matches all lower-case
0968: Greek letters.
0969: 
0970: You can also include certain special @dfn{character classes} in a
0971: character set.  A @samp{[:} and balancing @samp{:]} enclose a
0972: character class inside a character alternative.  For instance,
0973: @samp{[[:alnum:]]} matches any letter or digit.  @xref{Char Classes,,,
0974: elisp, The Emacs Lisp Reference Manual}, for a list of character
0975: classes.
0976: 
0977: To include a @samp{]} in a character set, you must make it the first character.
0978: For example, @samp{[]a]} matches @samp{]} or @samp{a}.  To include a @samp{-},
0979: write @samp{-} as the last character of the set, tho you can also put it first
0980: or after a range.  Thus, @samp{[]-]} matches both @samp{]} and @samp{-}.
0981: 
0982: To include @samp{^} in a set, put it anywhere but at the beginning of
0983: the set.  (At the beginning, it complements the set---see below.)
0984: 
0985: When you use a range in case-insensitive search, you should write both
0986: ends of the range in upper case, or both in lower case, or both should
0987: be non-letters.  The behavior of a mixed-case range such as @samp{A-z}
0988: is somewhat ill-defined, and it may change in future Emacs versions.
0989: 
0990: @item @kbd{[^ @dots{} ]}
0991: @samp{[^} begins a @dfn{complemented character set}, which matches any
0992: character except the ones specified.  Thus, @samp{[^a-z0-9A-Z]} matches
0993: all characters @emph{except} @acronym{ASCII} letters and digits.
0994: 
0995: @samp{^} is not special in a character set unless it is the first
0996: character.  The character following the @samp{^} is treated as if it
0997: were first (in other words, @samp{-} and @samp{]} are not special there).
0998: 
0999: A complemented character set can match a newline, unless newline is
1000: mentioned as one of the characters not to match.  This is in contrast to
1001: the handling of regexps in programs such as @code{grep}.
1002: 
1003: @item @kbd{^}
1004: is a special character that matches the empty string, but only at the
1005: beginning of a line in the text being matched.  Otherwise it fails to
1006: match anything.  Thus, @samp{^foo} matches a @samp{foo} that occurs at
1007: the beginning of a line.
1008: 
1009: For historical compatibility reasons, @samp{^} can be used with this
1010: meaning only at the beginning of the regular expression, or after
1011: @samp{\(} or @samp{\|}.
1012: 
1013: @item @kbd{$}
1014: is similar to @samp{^} but matches only at the end of a line.  Thus,
1015: @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
1016: 
1017: For historical compatibility reasons, @samp{$} can be used with this
1018: meaning only at the end of the regular expression, or before @samp{\)}
1019: or @samp{\|}.
1020: 
1021: @item @kbd{\}
1022: has two functions: it quotes the special characters (including
1023: @samp{\}), and it introduces additional special constructs.
1024: 
1025: Because @samp{\} quotes special characters, @samp{\$} is a regular
1026: expression that matches only @samp{$}, and @samp{\[} is a regular
1027: expression that matches only @samp{[}, and so on.
1028: 
1029: See the following section for the special constructs that begin
1030: with @samp{\}.
1031: @end table
1032: 
1033:   Note: for historical compatibility, special characters are treated as
1034: ordinary ones if they are in contexts where their special meanings make no
1035: sense.  For example, @samp{*foo} treats @samp{*} as ordinary since there is
1036: no preceding expression on which the @samp{*} can act.  It is poor practice
1037: to depend on this behavior; it is better to quote the special character anyway,
1038: regardless of where it appears.
1039: 
1040: As a @samp{\} is not special inside a character alternative, it can
1041: never remove the special meaning of @samp{-} or @samp{]}.  So you
1042: should not quote these characters when they have no special meaning
1043: either.  This would not clarify anything, since backslashes can
1044: legitimately precede these characters where they @emph{have} special
1045: meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax),
1046: which matches any single character except a backslash.
1047: 
1048: @node Regexp Backslash
1049: @section Backslash in Regular Expressions
1050: 
1051:   For the most part, @samp{\} followed by any character matches only
1052: that character.  However, there are several exceptions: two-character
1053: sequences starting with @samp{\} that have special meanings.  The
1054: second character in the sequence is always an ordinary character when
1055: used on its own.  Here is a table of @samp{\} constructs.
1056: 
1057: @table @kbd
1058: @item \|
1059: specifies an alternative.  Two regular expressions @var{a} and @var{b}
1060: with @samp{\|} in between form an expression that matches some text if
1061: either @var{a} matches it or @var{b} matches it.  It works by trying to
1062: match @var{a}, and if that fails, by trying to match @var{b}.
1063: 
1064: Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
1065: but no other string.
1066: 
1067: @samp{\|} applies to the largest possible surrounding expressions.  Only a
1068: surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
1069: @samp{\|}.
1070: 
1071: Full backtracking capability exists to handle multiple uses of @samp{\|}.
1072: 
1073: @item \( @dots{} \)
1074: is a grouping construct that serves three purposes:
1075: 
1076: @enumerate
1077: @item
1078: To enclose a set of @samp{\|} alternatives for other operations.
1079: Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
1080: 
1081: @item
1082: To enclose a complicated expression for the postfix operators @samp{*},
1083: @samp{+} and @samp{?} to operate on.  Thus, @samp{ba\(na\)*} matches
1084: @samp{bananana}, etc., with any (zero or more) number of @samp{na}
1085: strings.
1086: 
1087: @item
1088: To record a matched substring for future reference.
1089: @end enumerate
1090: 
1091: This last application is not a consequence of the idea of a
1092: parenthetical grouping; it is a separate feature that is assigned as a
1093: second meaning to the same @w{@samp{\( @dots{} \)}} construct.  In practice
1094: there is usually no conflict between the two meanings; when there is
1095: a conflict, you can use a shy group, described below.
1096: 
1097: @item \(?: @dots{} \)
1098: @cindex shy group, in regexp
1099: specifies a @dfn{shy group} that does not record the matched substring;
1100: you can't refer back to it with @samp{\@var{d}} (see below).  This is
1101: useful in mechanically combining regular expressions, so that you can
1102: add groups for syntactic purposes without interfering with the
1103: numbering of the groups that are meant to be referred to.
1104: 
1105: @item \@var{d}
1106: @cindex back reference, in regexp
1107: matches the same text that matched the @var{d}th occurrence of a
1108: @samp{\( @dots{} \)} construct.  This is called a @dfn{back
1109: reference}.
1110: 
1111: After the end of a @samp{\( @dots{} \)} construct, the matcher remembers
1112: the beginning and end of the text matched by that construct.  Then,
1113: later on in the regular expression, you can use @samp{\} followed by the
1114: digit @var{d} to mean ``match the same text matched the @var{d}th time
1115: by the @samp{\( @dots{} \)} construct''.
1116: 
1117: The strings matching the first nine @samp{\( @dots{} \)} constructs
1118: appearing in a regular expression are assigned numbers 1 through 9 in
1119: the order that the open-parentheses appear in the regular expression.
1120: So you can use @samp{\1} through @samp{\9} to refer to the text matched
1121: by the corresponding @samp{\( @dots{} \)} constructs.
1122: 
1123: For example, @samp{\(.*\)\1} matches any newline-free string that is
1124: composed of two identical halves.  The @samp{\(.*\)} matches the first
1125: half, which may be anything, but the @samp{\1} that follows must match
1126: the same exact text.
1127: 
1128: If a particular @samp{\( @dots{} \)} construct matches more than once
1129: (which can easily happen if it is followed by @samp{*}), only the last
1130: match is recorded.
1131: 
1132: @item \`
1133: matches the empty string, but only at the beginning of the string or
1134: buffer (or its accessible portion) being matched against.
1135: 
1136: @item \'
1137: matches the empty string, but only at the end of the string or buffer
1138: (or its accessible portion) being matched against.
1139: 
1140: @item \=
1141: matches the empty string, but only at point.
1142: 
1143: @item \b
1144: matches the empty string, but only at the beginning or
1145: end of a word.  Thus, @samp{\bfoo\b} matches any occurrence of
1146: @samp{foo} as a separate word.  @samp{\bballs?\b} matches
1147: @samp{ball} or @samp{balls} as a separate word.
1148: 
1149: @samp{\b} matches at the beginning or end of the buffer
1150: regardless of what text appears next to it.
1151: 
1152: @item \B
1153: matches the empty string, but @emph{not} at the beginning or
1154: end of a word.
1155: 
1156: @item \<
1157: matches the empty string, but only at the beginning of a word.
1158: @samp{\<} matches at the beginning of the buffer only if a
1159: word-constituent character follows.
1160: 
1161: @item \>
1162: matches the empty string, but only at the end of a word.  @samp{\>}
1163: matches at the end of the buffer only if the contents end with a
1164: word-constituent character.
1165: 
1166: @item \w
1167: matches any word-constituent character.  The syntax table determines
1168: which characters these are.  @xref{Syntax Tables,, Syntax Tables,
1169: elisp, The Emacs Lisp Reference Manual}.
1170: 
1171: @item \W
1172: matches any character that is not a word-constituent.
1173: 
1174: @item \_<
1175: matches the empty string, but only at the beginning of a symbol.
1176: A symbol is a sequence of one or more symbol-constituent characters.
1177: A symbol-constituent character is a character whose syntax is either
1178: @samp{w} or @samp{_}.  @samp{\_<} matches at the beginning of the
1179: buffer only if a symbol-constituent character follows.  As with words,
1180: the syntax table determines which characters are symbol-constituent.
1181: 
1182: @item \_>
1183: matches the empty string, but only at the end of a symbol.  @samp{\_>}
1184: matches at the end of the buffer only if the contents end with a
1185: symbol-constituent character.
1186: 
1187: @item \s@var{c}
1188: matches any character whose syntax is @var{c}.  Here @var{c} is a
1189: character that designates a particular syntax class: thus, @samp{w}
1190: for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.}
1191: for ordinary punctuation, etc.  @xref{Syntax Tables,, Syntax Tables,
1192: elisp, The Emacs Lisp Reference Manual}.
1193: 
1194: @item \S@var{c}
1195: matches any character whose syntax is not @var{c}.
1196: 
1197: @cindex categories of characters
1198: @cindex characters which belong to a specific language
1199: @findex describe-categories
1200: @item \c@var{c}
1201: matches any character that belongs to the category @var{c}.  For
1202: example, @samp{\cc} matches Chinese characters, @samp{\cg} matches
1203: Greek characters, etc.  For the description of the known categories,
1204: type @kbd{M-x describe-categories @key{RET}}.
1205: 
1206: @item \C@var{c}
1207: matches any character that does @emph{not} belong to category
1208: @var{c}.
1209: @end table
1210: 
1211:   The constructs that pertain to words and syntax are controlled by
1212: the setting of the syntax table.  @xref{Syntax Tables,, Syntax Tables,
1213: elisp, The Emacs Lisp Reference Manual}.
1214: 
1215: @node Regexp Example
1216: @section Regular Expression Example
1217: 
1218:   Here is an example of a regexp---similar to the regexp that Emacs
1219: uses, by default, to recognize the end of a sentence, not including
1220: the following space (i.e., the variable @code{sentence-end-base}):
1221: 
1222: @example
1223: @verbatim
1224: [.?!][]\"')}]*
1225: @end verbatim
1226: @end example
1227: 
1228: @noindent
1229: This contains two parts in succession: a character set matching
1230: period, @samp{?}, or @samp{!}, and a character set matching
1231: close-brackets, quotes, or parentheses, repeated zero or more times.
1232: 
1233: @node Lax Search
1234: @section Lax Matching During Searching
1235: 
1236: @cindex lax search
1237: @cindex character equivalence in search
1238:   Normally, you'd want search commands to disregard certain minor
1239: differences between the search string you type and the text being
1240: searched.  For example, sequences of whitespace characters of
1241: different length are usually perceived as equivalent; letter-case
1242: differences usually don't matter; etc.  This is known as
1243: @dfn{character equivalence}.
1244: 
1245:   This section describes the Emacs lax search features, and how to
1246: tailor them to your needs.
1247: 
1248: @cindex lax space matching in search
1249: @kindex M-s SPC @r{(Incremental search)}
1250: @kindex SPC @r{(Incremental search)}
1251: @findex isearch-toggle-lax-whitespace
1252: @vindex search-whitespace-regexp
1253:   By default, search commands perform @dfn{lax space matching}:
1254: each space, or sequence of spaces, matches any sequence of one or more
1255: whitespace characters in the text.  (Incremental regexp search has a
1256: separate default; see @ref{Regexp Search}.)  Hence, @w{@samp{foo bar}}
1257: matches @w{@samp{foo bar}}, @w{@samp{foo@ @ bar}},
1258: @w{@samp{foo@ @ @ bar}}, and so on (but not @samp{foobar}).  More
1259: precisely, Emacs matches each sequence of space characters in the
1260: search string to a regular expression specified by the variable
1261: @code{search-whitespace-regexp}.  For example, to make spaces match
1262: sequences of newlines as well as spaces, set it to
1263: @samp{"[[:space:]\n]+"}.  The default value of this variable depends
1264: on the buffer's major mode; most major modes classify spaces, tabs,
1265: and formfeed characters as whitespace.
1266: 
1267:   If you want whitespace characters to match exactly, you can turn lax
1268: space matching off by typing @kbd{M-s @key{SPC}}
1269: (@code{isearch-toggle-lax-whitespace}) within an incremental search.
1270: Another @kbd{M-s @key{SPC}} turns lax space matching back on.  To
1271: disable lax whitespace matching for all searches, change
1272: @code{search-whitespace-regexp} to @code{nil}; then each space in the
1273: search string matches exactly one space.
1274: 
1275: @cindex case folding in search
1276: @cindex case-sensitivity and search
1277:   Searches in Emacs by default ignore the case of the text they are
1278: searching through, if you specify the search string in lower case.
1279: Thus, if you specify searching for @samp{foo}, then @samp{Foo} and
1280: @samp{fOO} also match.  Regexps, and in particular character sets,
1281: behave likewise: @samp{[ab]} matches @samp{a} or @samp{A} or @samp{b}
1282: or @samp{B}.  This feature is known as @dfn{case folding}, and it is
1283: supported in both incremental and non-incremental search modes.
1284: 
1285: @vindex search-upper-case
1286:   An upper-case letter anywhere in the search string makes the search
1287: case-sensitive.  Thus, searching for @samp{Foo} does not find
1288: @samp{foo} or @samp{FOO}.  This applies to regular expression search
1289: as well as to literal string search.  The effect ceases if you delete
1290: the upper-case letter from the search string.  The variable
1291: @code{search-upper-case} controls this: if it is non-@code{nil} (the
1292: default), an upper-case character in the search string makes the
1293: search case-sensitive; setting it to @code{nil} disables this effect
1294: of upper-case characters.
1295: 
1296: @vindex case-fold-search
1297:   If you set the variable @code{case-fold-search} to @code{nil}, then
1298: all letters must match exactly, including case.  This is a per-buffer
1299: variable; altering the variable normally affects only the current buffer,
1300: unless you change its default value.  @xref{Locals}.
1301: This variable applies to nonincremental searches also, including those
1302: performed by the replace commands (@pxref{Replace}) and the minibuffer
1303: history matching commands (@pxref{Minibuffer History}).
1304: 
1305: @kindex M-c @r{(Incremental search)}
1306: @kindex M-s c @r{(Incremental search)}
1307: @findex isearch-toggle-case-fold
1308:   Typing @kbd{M-c} or @kbd{M-s c} (@code{isearch-toggle-case-fold})
1309: within an incremental search toggles the case sensitivity of that
1310: search.  The effect does not extend beyond the current incremental
1311: search, but it does override the effect of adding or removing an
1312: upper-case letter in the current search.
1313: 
1314:   Several related variables control case-sensitivity of searching and
1315: matching for specific commands or activities.  For instance,
1316: @code{tags-case-fold-search} controls case sensitivity for
1317: @code{find-tag}.  To find these variables, do @kbd{M-x
1318: apropos-variable @key{RET} case-fold-search @key{RET}}.
1319: 
1320: @cindex character folding in search
1321: @cindex equivalent character sequences
1322:   Case folding disregards case distinctions among characters, making
1323: upper-case characters match lower-case variants, and vice versa.  A
1324: generalization of case folding is @dfn{character folding}, which
1325: disregards wider classes of distinctions among similar characters.
1326: For instance, under character folding the letter @code{a} matches all
1327: of its accented cousins like @code{@"a} and @code{@'a}, i.e., the
1328: match disregards the diacritics that distinguish these
1329: variants.  In addition, @code{a} matches other characters that
1330: resemble it, or have it as part of their graphical representation,
1331: such as @sc{u+249c parenthesized latin small letter a} and @sc{u+2100
1332: account of} (which looks like a small @code{a} over @code{c}).
1333: Similarly, the @acronym{ASCII} double-quote character @code{"} matches
1334: all the other variants of double quotes defined by the Unicode
1335: standard.  Finally, character folding can make a sequence of one or
1336: more characters match another sequence of a different length: for
1337: example, the sequence of two characters @code{ff} matches @sc{u+fb00
1338: latin small ligature ff}.  Character sequences that are not identical,
1339: but match under character folding are known as @dfn{equivalent
1340: character sequences}.
1341: 
1342: @kindex M-s ' @r{(Incremental Search)}
1343: @findex isearch-toggle-char-fold
1344:   Generally, search commands in Emacs do not by default perform
1345: character folding in order to match equivalent character sequences.
1346: You can enable this behavior by customizing the variable
1347: @code{search-default-mode} to @code{char-fold-to-regexp}.
1348: @xref{Search Customizations}.  Within an incremental search, typing
1349: @kbd{M-s '} (@code{isearch-toggle-char-fold}) toggles character
1350: folding, but only for that search.  (Replace commands have a different
1351: default, controlled by a separate option; see @ref{Replacement and Lax
1352: Matches}.)
1353: 
1354:   Like with case folding, typing an explicit variant of a character,
1355: such as @code{@"a}, as part of the search string disables character
1356: folding for that search.  If you delete such a character from the
1357: search string, this effect ceases.
1358: 
1359: @node Replace
1360: @section Replacement Commands
1361: @cindex replacement
1362: @cindex search-and-replace commands
1363: @cindex string substitution
1364: @cindex global substitution
1365: 
1366:   Emacs provides several commands for performing search-and-replace
1367: operations.  In addition to the simple @kbd{M-x replace-string}
1368: command, there is @kbd{M-%} (@code{query-replace}), which presents
1369: each occurrence of the search pattern and asks you whether to replace
1370: it.
1371: 
1372:   The replace commands normally operate on the text from point to the
1373: end of the buffer.  When the region is active, they operate on it
1374: instead (@pxref{Mark}).  The basic replace commands replace one
1375: @dfn{search string} (or regexp) with one @dfn{replacement string}.  It
1376: is possible to perform several replacements in parallel, using the
1377: command @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}).
1378: 
1379: @menu
1380: * Unconditional Replace::   Replacing all matches for a string.
1381: * Regexp Replace::          Replacing all matches for a regexp.
1382: * Replacement and Lax Matches::
1383:                             Lax searching for text to replace.
1384: * Query Replace::           How to use querying.
1385: @end menu
1386: 
1387: @node Unconditional Replace
1388: @subsection Unconditional Replacement
1389: @findex replace-string
1390: 
1391: @table @kbd
1392: @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
1393: Replace every occurrence of @var{string} with @var{newstring}.
1394: @end table
1395: 
1396:   To replace every instance of @samp{foo} after point with @samp{bar},
1397: use the command @kbd{M-x replace-string} with the two arguments
1398: @samp{foo} and @samp{bar}.  Replacement happens only in the text after
1399: point, so if you want to cover the whole buffer you must go to the
1400: beginning first.  All occurrences up to the end of the buffer are
1401: replaced; to limit replacement to part of the buffer, activate the
1402: region around that part.  When the region is active, replacement is
1403: limited to the region (@pxref{Mark}).
1404: 
1405:   When @code{replace-string} exits, it leaves point at the last
1406: occurrence replaced.  It adds the prior position of point (where the
1407: @code{replace-string} command was issued) to the mark ring, without
1408: activating the mark; use @kbd{C-u C-@key{SPC}} to move back there.
1409: @xref{Mark Ring}.
1410: 
1411:   A prefix argument restricts replacement to matches that are
1412: surrounded by word boundaries.
1413: 
1414:   @xref{Replacement and Lax Matches}, for details about
1415: case-sensitivity and character folding in replace commands.
1416: 
1417: @node Regexp Replace
1418: @subsection Regexp Replacement
1419: @findex replace-regexp
1420: 
1421:   The @kbd{M-x replace-string} command replaces exact matches for a
1422: single string.  The similar command @kbd{M-x replace-regexp} replaces
1423: any match for a specified regular expression pattern (@pxref{Regexps}).
1424: 
1425: @table @kbd
1426: @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
1427: Replace every match for @var{regexp} with @var{newstring}.
1428: @end table
1429: 
1430: @cindex back reference, in regexp replacement
1431:   In @code{replace-regexp}, the @var{newstring} need not be constant:
1432: it can refer to all or part of what is matched by the @var{regexp}.
1433: @samp{\&} in @var{newstring} stands for the entire match being
1434: replaced.  @samp{\@var{d}} in @var{newstring}, where @var{d} is a
1435: digit starting from 1, stands for whatever matched the @var{d}th
1436: parenthesized grouping in @var{regexp}.  (This is called a ``back
1437: reference''.)  @samp{\#} refers to the count of replacements already
1438: made in this command, as a decimal number.  In the first replacement,
1439: @samp{\#} stands for @samp{0}; in the second, for @samp{1}; and so on.
1440: For example,
1441: 
1442: @example
1443: M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
1444: @end example
1445: 
1446: @noindent
1447: replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
1448: with @samp{cddr-safe}.
1449: 
1450: @example
1451: M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
1452: @end example
1453: 
1454: @noindent
1455: performs the inverse transformation.  To include a @samp{\} in the
1456: text to replace with, you must enter @samp{\\}.
1457: 
1458:   If you want to enter part of the replacement string by hand each
1459: time, use @samp{\?} in the replacement string.  Each replacement will
1460: ask you to edit the replacement string in the minibuffer, putting
1461: point where the @samp{\?} was.
1462: 
1463:   The remainder of this subsection is intended for specialized tasks
1464: and requires knowledge of Lisp.  Most readers can skip it.
1465: 
1466:   You can use Lisp expressions to calculate parts of the
1467: replacement string.  To do this, write @samp{\,} followed by the
1468: expression in the replacement string.  Each replacement calculates the
1469: value of the expression and converts it to text without quoting (if
1470: it's a string, this means using the string's contents), and uses it in
1471: the replacement string in place of the expression itself.  If the
1472: expression is a symbol, one space in the replacement string after the
1473: symbol name goes with the symbol name, so the value replaces them
1474: both.
1475: 
1476:   Inside such an expression, you can use some special sequences.
1477: @samp{\&} and @samp{\@var{d}} refer here, as usual, to the entire
1478: match as a string, and to a submatch as a string.  @var{d} may be
1479: multiple digits, and the value of @samp{\@var{d}} is @code{nil} if the
1480: @var{d}'th parenthesized grouping did not match.  You can also use
1481: @samp{\#&} and @samp{\#@var{d}} to refer to those matches as numbers
1482: (this is valid when the match or submatch has the form of a numeral).
1483: @samp{\#} here too stands for the number of already-completed
1484: replacements.
1485: 
1486:   Repeating our example to exchange @samp{x} and @samp{y}, we can thus
1487: do it also this way:
1488: 
1489: @example
1490: M-x replace-regexp @key{RET} \(x\)\|y @key{RET}
1491: \,(if \1 "y" "x") @key{RET}
1492: @end example
1493: 
1494:   For computing replacement strings for @samp{\,}, the @code{format}
1495: function is often useful (@pxref{Formatting Strings,,, elisp, The Emacs
1496: Lisp Reference Manual}).  For example, to add consecutively numbered
1497: strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are
1498: already occupied), you can use
1499: 
1500: @example
1501: M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET}
1502: \,(format "%-72sABC%05d" \& \#) @key{RET}
1503: @end example
1504: 
1505: @node Replacement and Lax Matches
1506: @subsection Replace Commands and Lax Matches
1507: 
1508:   This subsection describes the behavior of replace commands with
1509: respect to lax matches (@pxref{Lax Search}) and how to customize it.
1510: In general, replace commands mostly default to stricter matching than
1511: their search counterparts.
1512: 
1513: @cindex lax space matching in replace commands
1514: @vindex replace-lax-whitespace
1515:   Unlike incremental search, the replacement commands do not use lax
1516: space matching (@pxref{Lax Search, lax space matching}) by default.
1517: To enable lax space matching for replacement, change the variable
1518: @code{replace-lax-whitespace} to non-@code{nil}.  (This only affects
1519: how Emacs finds the text to replace, not the replacement text.)
1520: 
1521: @vindex replace-regexp-lax-whitespace
1522:   A companion variable @code{replace-regexp-lax-whitespace} controls
1523: whether @code{query-replace-regexp} uses lax whitespace matching when
1524: searching for patterns.
1525: 
1526: @cindex case folding in replace commands
1527:   If the first argument of a replace command is all lower case, the
1528: command ignores case while searching for occurrences to
1529: replace---provided @code{case-fold-search} is non-@code{nil}.  If
1530: @code{case-fold-search} is set to @code{nil}, case is always significant
1531: in all searches.
1532: 
1533: @vindex case-replace
1534:   In addition, when the @var{newstring} argument is all or partly lower
1535: case, replacement commands try to preserve the case pattern of each
1536: occurrence.  Thus, the command
1537: 
1538: @example
1539: M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
1540: @end example
1541: 
1542: @noindent
1543: replaces a lower case @samp{foo} with a lower case @samp{bar}, an
1544: all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with
1545: @samp{Bar}.  (These three alternatives---lower case, all caps, and
1546: capitalized, are the only ones that @code{replace-string} can
1547: distinguish.)
1548: 
1549:   If upper-case letters are used in the replacement string, they remain
1550: upper case every time that text is inserted.  If upper-case letters are
1551: used in the first argument, the second argument is always substituted
1552: exactly as given, with no case conversion.  Likewise, if either
1553: @code{case-replace} or @code{case-fold-search} is set to @code{nil},
1554: replacement is done without case conversion.
1555: 
1556: @cindex character folding in replace commands
1557:   The replacement commands by default do not use character folding
1558: (@pxref{Lax Search, character folding}) when looking for the text to
1559: replace.  To enable character folding for matching in
1560: @code{query-replace} and @code{replace-string}, set the variable
1561: @code{replace-char-fold} to a non-@code{nil} value.  (This
1562: setting does not affect the replacement text, only how Emacs finds the
1563: text to replace.  It also doesn't affect @code{replace-regexp}.)
1564: 
1565: @node Query Replace
1566: @subsection Query Replace
1567: @cindex query replace
1568: 
1569: @table @kbd
1570: @item M-% @var{string} @key{RET} @var{newstring} @key{RET}
1571: Replace some occurrences of @var{string} with @var{newstring}.
1572: @item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET}
1573: Replace some matches for @var{regexp} with @var{newstring}.
1574: @end table
1575: 
1576: @kindex M-%
1577: @findex query-replace
1578:   If you want to change only some of the occurrences of @samp{foo} to
1579: @samp{bar}, not all of them, use @kbd{M-%} (@code{query-replace}).
1580: This command finds occurrences of @samp{foo} one by one, displays each
1581: occurrence and asks you whether to replace it.  Aside from querying,
1582: @code{query-replace} works just like @code{replace-string}
1583: (@pxref{Unconditional Replace}).  In particular, it preserves case
1584: provided @code{case-replace} is non-@code{nil}, as it normally is
1585: (@pxref{Replacement and Lax Matches}).  A numeric argument means to
1586: consider only occurrences that are bounded by word-delimiter
1587: characters.  A negative prefix argument replaces backward.
1588: 
1589: @kindex C-M-%
1590: @findex query-replace-regexp
1591:   @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}).
1592: It works like @code{replace-regexp} except that it queries
1593: like @code{query-replace}.
1594: 
1595: @vindex query-replace-from-to-separator
1596:   You can reuse earlier replacements with these commands.  When
1597: @code{query-replace} or @code{query-replace-regexp} prompts for the
1598: search string, use @kbd{M-p} and @kbd{M-n} to show previous
1599: replacements in the form @samp{@var{from} -> @var{to}}, where
1600: @var{from} is the search pattern, @var{to} is its replacement, and the
1601: separator between them is determined by the value of the variable
1602: @code{query-replace-from-to-separator}.  Type @key{RET} to select the
1603: desired replacement.  If the value of this variable is @code{nil},
1604: replacements are not added to the command history, and cannot be
1605: reused.
1606: 
1607: @cindex faces for highlighting query replace
1608: @cindex @code{query-replace} face
1609: @cindex @code{lazy-highlight} face, in replace
1610: @vindex query-replace-highlight
1611: @vindex query-replace-lazy-highlight
1612: @vindex query-replace-show-replacement
1613:   These commands highlight the current match using the face
1614: @code{query-replace}.  You can disable this highlight by setting the
1615: variable @code{query-replace-highlight} to @code{nil}.  They highlight
1616: other matches using @code{lazy-highlight} just like incremental search
1617: (@pxref{Incremental Search}); this can be disabled by setting
1618: @code{query-replace-lazy-highlight} to @code{nil}.  By default,
1619: @code{query-replace-regexp} will show the substituted replacement
1620: string for the current match in the minibuffer.  If you want to keep
1621: special sequences @samp{\&} and @samp{\@var{n}} unexpanded, customize
1622: @code{query-replace-show-replacement} variable.
1623: 
1624: @vindex query-replace-skip-read-only
1625:   The variable @code{query-replace-skip-read-only}, if set
1626: non-@code{nil}, will cause replacement commands to ignore matches in
1627: read-only text.  The default is not to ignore them.
1628: 
1629:   The characters you can type when you are shown a match for the string
1630: or regexp are:
1631: 
1632: @ignore @c Not worth it.
1633: @kindex SPC @r{(query-replace)}
1634: @kindex DEL @r{(query-replace)}
1635: @kindex , @r{(query-replace)}
1636: @kindex RET @r{(query-replace)}
1637: @kindex . @r{(query-replace)}
1638: @kindex ! @r{(query-replace)}
1639: @kindex ^ @r{(query-replace)}
1640: @kindex C-r @r{(query-replace)}
1641: @kindex C-w @r{(query-replace)}
1642: @kindex C-l @r{(query-replace)}
1643: @end ignore
1644: 
1645: @c WideCommands
1646: @table @kbd
1647: @item @key{SPC}
1648: @itemx y
1649: to replace the occurrence with @var{newstring}.
1650: 
1651: @item @key{DEL}
1652: @itemx @key{Delete}
1653: @itemx @key{BACKSPACE}
1654: @itemx n
1655: to skip to the next occurrence without replacing this one.
1656: 
1657: @item , @r{(Comma)}
1658: to replace this occurrence and display the result.  You are then asked
1659: for another input character to say what to do next.  Since the
1660: replacement has already been made, @key{DEL} and @key{SPC} are
1661: equivalent in this situation; both move to the next occurrence.
1662: 
1663: You can type @kbd{C-r} at this point (see below) to alter the replaced
1664: text.  You can also type @kbd{C-x u} to undo the replacement; this exits
1665: the @code{query-replace}, so if you want to do further replacement you
1666: must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart
1667: (@pxref{Repetition}).
1668: 
1669: @item @key{RET}
1670: @itemx q
1671: to exit without doing any more replacements.
1672: 
1673: @item .@: @r{(Period)}
1674: to replace this occurrence and then exit without searching for more
1675: occurrences.
1676: 
1677: @item !
1678: to replace all remaining occurrences without asking again.
1679: 
1680: @item ^
1681: to go back to the position of the previous occurrence (or what used to
1682: be an occurrence), in case you changed it by mistake or want to
1683: reexamine it.
1684: 
1685: @item u
1686: to undo the last replacement and go back to where that replacement was
1687: made.
1688: 
1689: @item U
1690: to undo all the replacements and go back to where the first
1691: replacement was made.
1692: 
1693: @item C-r
1694: to enter a recursive editing level, in case the occurrence needs to be
1695: edited rather than just replaced with @var{newstring}.  When you are
1696: done, exit the recursive editing level with @kbd{C-M-c} to proceed to
1697: the next occurrence.  @xref{Recursive Edit}.
1698: 
1699: @item C-w
1700: to delete the occurrence, and then enter a recursive editing level as in
1701: @kbd{C-r}.  Use the recursive edit to insert text to replace the deleted
1702: occurrence of @var{string}.  When done, exit the recursive editing level
1703: with @kbd{C-M-c} to proceed to the next occurrence.
1704: 
1705: @item e
1706: to edit the replacement string in the minibuffer.  When you exit the
1707: minibuffer by typing @key{RET}, the minibuffer contents replace the
1708: current occurrence of the pattern.  They also become the new
1709: replacement string for any further occurrences.
1710: 
1711: @item C-l
1712: to redisplay the screen.  Then you must type another character to
1713: specify what to do with this occurrence.
1714: 
1715: @item Y @r{(Upper-case)}
1716: to replace all remaining occurrences in all remaining buffers in
1717: multi-buffer replacements (like the Dired @kbd{Q} command that performs
1718: query replace on selected files).  It answers this question and all
1719: subsequent questions in the series with ``yes'', without further
1720: user interaction.
1721: 
1722: @item N @r{(Upper-case)}
1723: to skip to the next buffer in multi-buffer replacements without
1724: replacing remaining occurrences in the current buffer.  It answers
1725: this question ``no'', gives up on the questions for the current buffer,
1726: and continues to the next buffer in the sequence.
1727: 
1728: @item C-h
1729: @itemx ?
1730: @itemx @key{F1}
1731: to display a message summarizing these options.  Then you must type
1732: another character to specify what to do with this occurrence.
1733: @end table
1734: 
1735:   Aside from this, any other character exits the @code{query-replace},
1736: and is then reread as part of a key sequence.  Thus, if you type
1737: @kbd{C-k}, it exits the @code{query-replace} and then kills to end of
1738: line.  In particular, @kbd{C-g} simply exits the @code{query-replace}.
1739: 
1740:   To restart a @code{query-replace} once it is exited, use @kbd{C-x
1741: @key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it
1742: used the minibuffer to read its arguments.  @xref{Repetition, C-x @key{ESC}
1743: @key{ESC}}.
1744: 
1745: @cindex invisible text, and query-replace
1746:   The option @code{search-invisible} determines how @code{query-replace}
1747: treats invisible text.  @xref{Outline Search}.
1748: 
1749:   @xref{Operating on Files}, for the Dired @kbd{Q} command which
1750: performs query replace on selected files.  See also @ref{Transforming
1751: File Names}, for Dired commands to rename, copy, or link files by
1752: replacing regexp matches in file names.
1753: 
1754: @node Other Repeating Search
1755: @section Other Search-and-Loop Commands
1756: 
1757:   Here are some other commands that find matches for a regular
1758: expression.  They all ignore case in matching, if the pattern contains
1759: no upper-case letters and @code{case-fold-search} is non-@code{nil}.
1760: Aside from @code{multi-occur} and @code{multi-occur-in-matching-buffers},
1761: which always search the whole buffer, all operate on the text from point
1762: to the end of the buffer, or on the region if it is active.
1763: 
1764: @table @kbd
1765: @findex multi-isearch-buffers
1766: @cindex isearch multiple buffers
1767: @cindex multiple-buffer isearch
1768: @item M-x multi-isearch-buffers
1769: Prompt for one or more buffer names, ending with @key{RET}; then,
1770: begin a multi-buffer incremental search in those buffers.  (If the
1771: search fails in one buffer, the next @kbd{C-s} tries searching the
1772: next specified buffer, and so forth.)  With a prefix argument, prompt
1773: for a regexp and begin a multi-buffer incremental search in buffers
1774: matching that regexp.
1775: 
1776: @findex multi-isearch-buffers-regexp
1777: @item M-x multi-isearch-buffers-regexp
1778: This command is just like @code{multi-isearch-buffers}, except it
1779: performs an incremental regexp search.
1780: 
1781: @findex multi-isearch-files
1782: @cindex isearch multiple files
1783: @cindex multiple-file isearch
1784: @item M-x multi-isearch-files
1785: Prompt for one or more file names, ending with @key{RET}; then,
1786: begin a multi-file incremental search in those files.  (If the
1787: search fails in one file, the next @kbd{C-s} tries searching the
1788: next specified file, and so forth.)  With a prefix argument, prompt
1789: for a regexp and begin a multi-file incremental search in files
1790: matching that regexp.
1791: 
1792: @findex multi-isearch-files-regexp
1793: @item M-x multi-isearch-files-regexp
1794: This command is just like @code{multi-isearch-files}, except it
1795: performs an incremental regexp search.
1796: 
1797: In some modes that set the buffer-local variable
1798: @code{multi-isearch-next-buffer-function} (e.g., in Change Log mode)
1799: a multi-file incremental search is activated automatically.
1800: 
1801: @cindex Occur mode
1802: @cindex mode, Occur
1803: @cindex match (face name)
1804: @vindex list-matching-lines-default-context-lines
1805: @vindex list-matching-lines-jump-to-current-line
1806: @c Too long.
1807: @c @cindex list-matching-lines-current-line-face (face name)
1808: @kindex M-s o
1809: @findex occur
1810: @item M-x occur
1811: @itemx M-s o
1812: Prompt for a regexp, and display a list showing each line in the
1813: buffer that contains a match for it.  If you type @kbd{M-n} at the
1814: prompt, you can reuse search strings from previous incremental
1815: searches.  The text that matched is highlighted using the @code{match}
1816: face.  A numeric argument @var{n} specifies that @var{n} lines of
1817: context are to be displayed before and after each matching line.
1818: 
1819: The default number of context lines is specified by the variable
1820: @code{list-matching-lines-default-context-lines}.  When
1821: @code{list-matching-lines-jump-to-current-line} is non-@code{nil} the
1822: current line is shown highlighted with face
1823: @code{list-matching-lines-current-line-face} and the point is set at
1824: the first match after such line.
1825: 
1826: You can also run @kbd{M-s o} when an incremental search is active;
1827: this uses the current search string.
1828: 
1829: Note that matches for the regexp you type are extended to include
1830: complete lines, and a match that starts before the previous match ends
1831: is not considered a match.
1832: 
1833: @kindex RET @r{(Occur mode)}
1834: @kindex o @r{(Occur mode)}
1835: @kindex C-o @r{(Occur mode)}
1836: In the @file{*Occur*} buffer, you can click on each entry, or move
1837: point there and type @key{RET}, to visit the corresponding position in
1838: the buffer that was searched.  @kbd{o} and @kbd{C-o} display the match
1839: in another window; @kbd{C-o} does not select it.  Alternatively, you
1840: can use the @kbd{M-g M-n} (@code{next-error}) command to visit the
1841: occurrences one by one (@pxref{Compilation Mode}).
1842: 
1843: @cindex Occur Edit mode
1844: @cindex mode, Occur Edit
1845: Typing @kbd{e} in the @file{*Occur*} buffer switches to Occur Edit
1846: mode, in which edits made to the entries are also applied to the text
1847: in the originating buffer.  Type @kbd{C-c C-c} to return to Occur
1848: mode.
1849: 
1850: @findex list-matching-lines
1851: The command @kbd{M-x list-matching-lines} is a synonym for @kbd{M-x
1852: occur}.
1853: 
1854: @findex multi-occur
1855: @item M-x multi-occur
1856: This command is just like @code{occur}, except it is able to search
1857: through multiple buffers.  It asks you to specify the buffer names one
1858: by one.
1859: 
1860: @findex multi-occur-in-matching-buffers
1861: @item M-x multi-occur-in-matching-buffers
1862: This command is similar to @code{multi-occur}, except the buffers to
1863: search are specified by a regular expression that matches visited file
1864: names.  With a prefix argument, it uses the regular expression to
1865: match buffer names instead.
1866: 
1867: @findex how-many
1868: @item M-x how-many
1869: Prompt for a regexp, and print the number of matches for it in the
1870: buffer after point.  If the region is active, this operates on the
1871: region instead.
1872: 
1873: @findex flush-lines
1874: @item M-x flush-lines
1875: Prompt for a regexp, and delete each line that contains a match for
1876: it, operating on the text after point.  When the command finishes,
1877: it prints the number of deleted matching lines.
1878: 
1879: This command deletes the current line if it contains a match starting
1880: after point.  If the region is active, it operates on the region
1881: instead; if a line partially contained in the region contains a match
1882: entirely contained in the region, it is deleted.
1883: 
1884: If a match is split across lines, @code{flush-lines} deletes all those
1885: lines.  It deletes the lines before starting to look for the next
1886: match; hence, it ignores a match starting on the same line at which
1887: another match ended.
1888: 
1889: @findex keep-lines
1890: @item M-x keep-lines
1891: Prompt for a regexp, and delete each line that @emph{does not} contain
1892: a match for it, operating on the text after point.  If point is not at
1893: the beginning of a line, this command always keeps the current line.
1894: If the region is active, the command operates on the region instead;
1895: it never deletes lines that are only partially contained in the region
1896: (a newline that ends a line counts as part of that line).
1897: 
1898: If a match is split across lines, this command keeps all those lines.
1899: @end table
1900: 
1901: @node Search Customizations
1902: @section Tailoring Search to Your Needs
1903: @cindex search customizations
1904: 
1905:   This section describes miscellaneous search-related customizations
1906: not described elsewhere.
1907: 
1908: @cindex default search mode
1909: @cindex search mode, default
1910:   The default search mode for the incremental search is specified by
1911: the variable @code{search-default-mode}.  It can be @code{nil},
1912: @code{t}, or a function.  If it is @code{nil}, the default mode is to
1913: do literal searches without character folding, but with case folding
1914: and lax-whitespace matches as determined by @code{case-fold-search}
1915: and @code{search-whitespace-regexp}, respectively (@pxref{Lax
1916: Search}).  If the value is @code{t}, incremental search defaults to
1917: regexp searches.  The default value specifies a function that only
1918: performs case folding and lax-whitespace matching.
1919: 
1920: @vindex search-highlight
1921:   The current match of an on-going incremental search is highlighted
1922: using the @code{isearch} face.  This highlighting can be disabled by
1923: setting the variable @code{search-highlight} to @code{nil}.
1924: 
1925: @cindex lazy highlighting customizations
1926: @vindex isearch-lazy-highlight
1927: @cindex @code{lazy-highlight} face
1928:   The other matches for the search string that are visible on display
1929: are highlighted using the @code{lazy-highlight} face.  Setting the
1930: variable @code{isearch-lazy-highlight} to @code{nil} disables this
1931: highlighting.  Here are some other variables that customize the lazy
1932: highlighting:
1933: 
1934: @table @code
1935: @item lazy-highlight-initial-delay
1936: Time in seconds to wait before highlighting visible matches.
1937: 
1938: @item lazy-highlight-interval
1939: Time in seconds between highlighting successive matches.
1940: 
1941: @item lazy-highlight-max-at-a-time
1942: The maximum number of matches to highlight before checking for input.
1943: A large number can take some time to highlight, so if you want to
1944: continue searching and type @kbd{C-s} or @kbd{C-r} during that time,
1945: Emacs will not respond until it finishes highlighting all those
1946: matches.  Thus, smaller values make Emacs more responsive.
1947: @end table
1948: 
1949: @vindex search-nonincremental-instead
1950:   Normally, entering @key{RET} within incremental search when the
1951: search string is empty launches a nonincremental search.  (Actually,
1952: it lets you edit the search string, and the next @key{RET} does the
1953: search.)  However, if you customize the variable
1954: @code{search-nonincremental-instead} to @code{nil}, typing @key{RET}
1955: will always exit the incremental search, even if the search string is
1956: empty.
1957: 
1958: @vindex isearch-hide-immediately
1959:   By default, incremental search and query-replace commands match
1960: invisible text, but hide any such matches as soon as the current match
1961: moves off the invisible text.  If you customize the variable
1962: @code{isearch-hide-immediately} to @code{nil}, any invisible text
1963: where matches were found stays on display until the search or the
1964: replace command exits.
1965: 
1966: @cindex search display on slow terminals
1967: @vindex search-slow-speed
1968: @vindex search-slow-window-lines
1969:   Searching incrementally on slow terminals, such as displays
1970: connected to remote machines over slow connection, could be annoying
1971: due to the need to redraw large portions of the display as the search
1972: proceeds.  Emacs provides a special display mode for slow terminals,
1973: whereby search pops up a separate small window and displays the text
1974: surrounding the match in that window.  Small windows display faster,
1975: so the annoying effect of slow speed is alleviated.  The variable
1976: @code{search-slow-speed} determines the baud rate threshold below
1977: which Emacs will use this display mode.  The variable
1978: @code{search-slow-window-lines} controls the number of lines in the
1979: window Emacs pops up for displaying the search results; the default is
1980: 1 line.  Normally, this window will pop up at the bottom of the window
1981: that displays the buffer where you start searching, but if the value
1982: of @code{search-slow-window-lines} is negative, that means to put the
1983: window at the top and give it the number of lines that is the absolute
1984: value of @code{search-slow-window-lines}.
1985: