0001: @c -*- coding: utf-8 -*-
0002: @c This is part of the Emacs manual.
0003: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 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-w} 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{search-exit-option} is customized to @code{shift-move},
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{search-exit-option} is @code{move}, 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:   To search the Web for the text in region, type @kbd{M-s M-w}.  This
0688: command performs an Internet search for the words in region using the
0689: search engine whose @acronym{URL} is specified by the variable
0690: @code{eww-search-prefix} (@pxref{Basics, EWW, , eww, The Emacs Web
0691: Wowser Manual}).  If the region is not active, or doesn't contain any
0692: words, this command prompts the user for a URL or keywords to search.
0693: 
0694: 
0695: @node Symbol Search
0696: @section Symbol Search
0697: @cindex symbol search
0698: 
0699:   A @dfn{symbol search} is much like an ordinary search, except that
0700: the boundaries of the search must match the boundaries of a symbol.
0701: The meaning of @dfn{symbol} in this context depends on the major mode,
0702: and usually refers to a source code token, such as a Lisp symbol in
0703: Emacs Lisp mode.  For instance, if you perform an incremental symbol
0704: search for the Lisp symbol @code{forward-word}, it would not match
0705: @code{isearch-forward-word}.  This feature is thus mainly useful for
0706: searching source code.
0707: 
0708: @table @kbd
0709: @item M-s _
0710: @findex isearch-toggle-symbol
0711: If incremental search is active, toggle symbol search mode
0712: (@code{isearch-toggle-symbol}); otherwise, begin an incremental
0713: forward symbol search (@code{isearch-forward-symbol}).
0714: @item M-s .
0715: Start a symbol incremental search forward with the symbol found near
0716: point added to the search string initially.
0717: @item M-s _ @key{RET} @var{symbol} @key{RET}
0718: Search forward for @var{symbol}, nonincrementally.
0719: @item M-s _ C-r @key{RET} @var{symbol} @key{RET}
0720: Search backward for @var{symbol}, nonincrementally.
0721: @end table
0722: 
0723: @kindex M-s _
0724: @kindex M-s .
0725: @findex isearch-forward-symbol
0726: @findex isearch-forward-symbol-at-point
0727:   To begin a forward incremental symbol search, type @kbd{M-s _} (or
0728: @kbd{M-s .} if the symbol to search is near point).  If incremental
0729: search is not already active, this runs the command
0730: @code{isearch-forward-symbol}.  If incremental search is already
0731: active, @kbd{M-s _} switches to a symbol search, preserving the
0732: direction of the search and the current search string; you can disable
0733: symbol search by typing @kbd{M-s _} again.  In incremental symbol
0734: search, while you are typing the search string, only the beginning
0735: of the search string is required to match the beginning of a symbol,
0736: and @samp{Pending} appears in the search prompt until you use a search
0737: repeating key like @kbd{C-s}.
0738: 
0739:   To begin a nonincremental symbol search, type @kbd{M-s _ @key{RET}}
0740: for a forward search, or @kbd{M-s _ C-r @key{RET}} or a backward
0741: search.  In nonincremental symbol searches, the beginning and end of
0742: the search string are required to match the beginning and end of a
0743: symbol, respectively.
0744: 
0745:   The symbol search commands don't perform character folding, and
0746: toggling lax whitespace matching (@pxref{Lax Search, lax space
0747: matching}) has no effect on them.
0748: 
0749: @node Regexp Search
0750: @section Regular Expression Search
0751: @cindex regexp search
0752: @cindex search for a regular expression
0753: 
0754:   A @dfn{regular expression} (or @dfn{regexp} for short) is a pattern
0755: that denotes a class of alternative strings to match.  Emacs
0756: provides both incremental and nonincremental ways to search for a
0757: match for a regexp.  The syntax of regular expressions is explained in
0758: the next section.
0759: 
0760: @table @kbd
0761: @item C-M-s
0762: Begin incremental regexp search (@code{isearch-forward-regexp}).
0763: @item C-M-r
0764: Begin reverse incremental regexp search (@code{isearch-backward-regexp}).
0765: @end table
0766: 
0767: @kindex C-M-s
0768: @findex isearch-forward-regexp
0769: @kindex C-M-r
0770: @findex isearch-backward-regexp
0771:   Incremental search for a regexp is done by typing @kbd{C-M-s}
0772: (@code{isearch-forward-regexp}), by invoking @kbd{C-s} with a
0773: prefix argument (whose value does not matter), or by typing @kbd{M-r}
0774: within a forward incremental search.  This command reads a
0775: search string incrementally just like @kbd{C-s}, but it treats the
0776: search string as a regexp rather than looking for an exact match
0777: against the text in the buffer.  Each time you add text to the search
0778: string, you make the regexp longer, and the new regexp is searched
0779: for.  To search backward for a regexp, use @kbd{C-M-r}
0780: (@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument,
0781: or @kbd{M-r} within a backward incremental search.
0782: 
0783: @vindex regexp-search-ring-max
0784:   All of the special key sequences in an ordinary incremental search
0785: (@pxref{Special Isearch}) do similar things in an incremental regexp
0786: search.  For instance, typing @kbd{C-s} immediately after starting the
0787: search retrieves the last incremental search regexp used and searches
0788: forward for it.  Incremental regexp and non-regexp searches have
0789: independent defaults.  They also have separate search rings, which you
0790: can access with @kbd{M-p} and @kbd{M-n}.  The maximum number of search
0791: regexps saved in the search ring is determined by the value of
0792: @code{regexp-search-ring-max}, 16 by default.
0793: 
0794:   Unlike ordinary incremental search, incremental regexp search
0795: does not use lax space matching by default.  To toggle this feature
0796: use @kbd{M-s @key{SPC}} (@code{isearch-toggle-lax-whitespace}).
0797: Then any @key{SPC} typed in incremental regexp search will match
0798: any sequence of one or more whitespace characters.  The variable
0799: @code{search-whitespace-regexp} specifies the regexp for the lax
0800: space matching.  @xref{Special Isearch}.
0801: 
0802:   Also unlike ordinary incremental search, incremental regexp search
0803: cannot use character folding (@pxref{Lax Search}).  (If you toggle
0804: character folding during incremental regexp search with @kbd{M-s '},
0805: the search becomes a non-regexp search and the search pattern you
0806: typed is interpreted as a literal string.)
0807: 
0808:   In some cases, adding characters to the regexp in an incremental
0809: regexp search can make the cursor move back and start again.  For
0810: example, if you have searched for @samp{foo} and you add @samp{\|bar},
0811: the cursor backs up in case the first @samp{bar} precedes the first
0812: @samp{foo}.  @xref{Regexps}.
0813: 
0814:   Forward and backward regexp search are not symmetrical, because
0815: regexp matching in Emacs always operates forward, starting with the
0816: beginning of the regexp.  Thus, forward regexp search scans forward,
0817: trying a forward match at each possible starting position.  Backward
0818: regexp search scans backward, trying a forward match at each possible
0819: starting position.  These search methods are not mirror images.
0820: 
0821: @findex re-search-forward
0822: @findex re-search-backward
0823:   Nonincremental search for a regexp is done with the commands
0824: @code{re-search-forward} and @code{re-search-backward}.  You can
0825: invoke these with @kbd{M-x}, or by way of incremental regexp search
0826: with @kbd{C-M-s @key{RET}} and @kbd{C-M-r @key{RET}}.  When you invoke
0827: these commands with @kbd{M-x}, they search for the exact regexp you
0828: specify, and thus don't support any lax-search features (@pxref{Lax
0829: Search}) except case folding.
0830: 
0831:   If you use the incremental regexp search commands with a prefix
0832: argument, they perform ordinary string search, like
0833: @code{isearch-forward} and @code{isearch-backward}.  @xref{Incremental
0834: Search}.
0835: 
0836: @node Regexps
0837: @section Syntax of Regular Expressions
0838: @cindex syntax of regexps
0839: @cindex regular expression
0840: @cindex regexp
0841: 
0842:   This section (and this manual in general) describes regular
0843: expression features that users typically use.  @xref{Regular
0844: Expressions,,, elisp, The Emacs Lisp Reference Manual}, for additional
0845: features used mainly in Lisp programs.
0846: 
0847:   Regular expressions have a syntax in which a few characters are
0848: special constructs and the rest are @dfn{ordinary}.  An ordinary
0849: character matches that same character and nothing else.  The special
0850: characters are @samp{$^.*+?[\}.  The character @samp{]} is special if
0851: it ends a character alternative (see below).  The character @samp{-}
0852: is special inside a character alternative.  Any other character
0853: appearing in a regular expression is ordinary, unless a @samp{\}
0854: precedes it.  (When you use regular expressions in a Lisp program,
0855: each @samp{\} must be doubled, see the example near the end of this
0856: section.)
0857: 
0858:   For example, @samp{f} is not a special character, so it is ordinary, and
0859: therefore @samp{f} is a regular expression that matches the string
0860: @samp{f} and no other string.  (It does @emph{not} match the string
0861: @samp{ff}.)  Likewise, @samp{o} is a regular expression that matches
0862: only @samp{o}.  (When case distinctions are being ignored, these regexps
0863: also match @samp{F} and @samp{O}, but we consider this a generalization
0864: of ``the same string'', rather than an exception.)
0865: 
0866:   Any two regular expressions @var{a} and @var{b} can be concatenated.
0867: The result is a regular expression which matches a string if @var{a}
0868: matches some amount of the beginning of that string and @var{b}
0869: matches the rest of the string.  As a trivial example, concatenating
0870: the regular expressions @samp{f} and @samp{o} gives the regular
0871: expression @samp{fo}, which matches only the string @samp{fo}.  To do
0872: something less trivial, you need to use one of the special characters.
0873: Here is a list of them.
0874: 
0875: @table @asis
0876: @item @kbd{.}@: @r{(Period)}
0877: is a special character that matches any single character except a
0878: newline.  For example, the regular expressions @samp{a.b} matches any
0879: three-character string that begins with @samp{a} and ends with
0880: @samp{b}.
0881: 
0882: @item @kbd{*}
0883: is not a construct by itself; it is a postfix operator that means to
0884: match the preceding regular expression repetitively any number of
0885: times, as many times as possible.  Thus, @samp{o*} matches any number
0886: of @samp{o}s, including no @samp{o}s.
0887: 
0888: @samp{*} always applies to the @emph{smallest} possible preceding
0889: expression.  Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
0890: @samp{fo}.  It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
0891: 
0892: The matcher processes a @samp{*} construct by matching, immediately,
0893: as many repetitions as can be found.  Then it continues with the rest
0894: of the pattern.  If that fails, backtracking occurs, discarding some
0895: of the matches of the @samp{*}-modified construct in case that makes
0896: it possible to match the rest of the pattern.  For example, in matching
0897: @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
0898: tries to match all three @samp{a}s; but the rest of the pattern is
0899: @samp{ar} and there is only @samp{r} left to match, so this try fails.
0900: The next alternative is for @samp{a*} to match only two @samp{a}s.
0901: With this choice, the rest of the regexp matches successfully.
0902: 
0903: @item @kbd{+}
0904: is a postfix operator, similar to @samp{*} except that it must match
0905: the preceding expression at least once.  Thus, @samp{ca+r} matches the
0906: strings @samp{car} and @samp{caaaar} but not the string @samp{cr},
0907: whereas @samp{ca*r} matches all three strings.
0908: 
0909: @item @kbd{?}
0910: is a postfix operator, similar to @samp{*} except that it can match
0911: the preceding expression either once or not at all.  Thus, @samp{ca?r}
0912: matches @samp{car} or @samp{cr}, and nothing else.
0913: 
0914: @item @kbd{*?}, @kbd{+?}, @kbd{??}
0915: @cindex non-greedy regexp matching
0916: are non-@dfn{greedy} variants of the operators above.  The normal
0917: operators @samp{*}, @samp{+}, @samp{?} match as much as they can, as
0918: long as the overall regexp can still match.  With a following
0919: @samp{?}, they will match as little as possible.
0920: 
0921: Thus, both @samp{ab*} and @samp{ab*?} can match the string @samp{a}
0922: and the string @samp{abbbb}; but if you try to match them both against
0923: the text @samp{abbb}, @samp{ab*} will match it all (the longest valid
0924: match), while @samp{ab*?}  will match just @samp{a} (the shortest
0925: valid match).
0926: 
0927: Non-greedy operators match the shortest possible string starting at a
0928: given starting point; in a forward search, though, the earliest
0929: possible starting point for match is always the one chosen.  Thus, if
0930: you search for @samp{a.*?$} against the text @samp{abbab} followed by
0931: a newline, it matches the whole string.  Since it @emph{can} match
0932: starting at the first @samp{a}, it does.
0933: 
0934: @item @kbd{\@{@var{n}\@}}
0935: is a postfix operator specifying @var{n} repetitions---that is, the
0936: preceding regular expression must match exactly @var{n} times in a
0937: row.  For example, @samp{x\@{4\@}} matches the string @samp{xxxx} and
0938: nothing else.
0939: 
0940: @item @kbd{\@{@var{n},@var{m}\@}}
0941: is a postfix operator specifying between @var{n} and @var{m}
0942: repetitions---that is, the preceding regular expression must match at
0943: least @var{n} times, but no more than @var{m} times.  If @var{m} is
0944: omitted, then there is no upper limit, but the preceding regular
0945: expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is
0946: equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to
0947: @samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}.
0948: 
0949: @item @kbd{[ @dots{} ]}
0950: is a @dfn{character set}, beginning with @samp{[} and terminated by
0951: @samp{]}.
0952: 
0953: In the simplest case, the characters between the two brackets are what
0954: this set can match.  Thus, @samp{[ad]} matches either one @samp{a} or
0955: one @samp{d}, and @samp{[ad]*} matches any string composed of just
0956: @samp{a}s and @samp{d}s (including the empty string).  It follows that
0957: @samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr},
0958: @samp{caddaar}, etc.
0959: 
0960: You can also include character ranges in a character set, by writing the
0961: starting and ending characters with a @samp{-} between them.  Thus,
0962: @samp{[a-z]} matches any lower-case @acronym{ASCII} letter.  Ranges may be
0963: intermixed freely with individual characters, as in @samp{[a-z$%.]},
0964: which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or
0965: period.  As another example, @samp{[α-ωί]} matches all lower-case
0966: Greek letters.
0967: 
0968: You can also include certain special @dfn{character classes} in a
0969: character set.  A @samp{[:} and balancing @samp{:]} enclose a
0970: character class inside a character alternative.  For instance,
0971: @samp{[[:alnum:]]} matches any letter or digit.  @xref{Char Classes,,,
0972: elisp, The Emacs Lisp Reference Manual}, for a list of character
0973: classes.
0974: 
0975: To include a @samp{]} in a character set, you must make it the first
0976: character.  For example, @samp{[]a]} matches @samp{]} or @samp{a}.  To
0977: include a @samp{-}, write @samp{-} as the first or last character of the
0978: set, or put it after a range.  Thus, @samp{[]-]} matches both @samp{]}
0979: and @samp{-}.
0980: 
0981: To include @samp{^} in a set, put it anywhere but at the beginning of
0982: the set.  (At the beginning, it complements the set---see below.)
0983: 
0984: When you use a range in case-insensitive search, you should write both
0985: ends of the range in upper case, or both in lower case, or both should
0986: be non-letters.  The behavior of a mixed-case range such as @samp{A-z}
0987: is somewhat ill-defined, and it may change in future Emacs versions.
0988: 
0989: @item @kbd{[^ @dots{} ]}
0990: @samp{[^} begins a @dfn{complemented character set}, which matches any
0991: character except the ones specified.  Thus, @samp{[^a-z0-9A-Z]} matches
0992: all characters @emph{except} @acronym{ASCII} letters and digits.
0993: 
0994: @samp{^} is not special in a character set unless it is the first
0995: character.  The character following the @samp{^} is treated as if it
0996: were first (in other words, @samp{-} and @samp{]} are not special there).
0997: 
0998: A complemented character set can match a newline, unless newline is
0999: mentioned as one of the characters not to match.  This is in contrast to
1000: the handling of regexps in programs such as @code{grep}.
1001: 
1002: @item @kbd{^}
1003: is a special character that matches the empty string, but only at the
1004: beginning of a line in the text being matched.  Otherwise it fails to
1005: match anything.  Thus, @samp{^foo} matches a @samp{foo} that occurs at
1006: the beginning of a line.
1007: 
1008: For historical compatibility reasons, @samp{^} can be used with this
1009: meaning only at the beginning of the regular expression, or after
1010: @samp{\(} or @samp{\|}.
1011: 
1012: @item @kbd{$}
1013: is similar to @samp{^} but matches only at the end of a line.  Thus,
1014: @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
1015: 
1016: For historical compatibility reasons, @samp{$} can be used with this
1017: meaning only at the end of the regular expression, or before @samp{\)}
1018: or @samp{\|}.
1019: 
1020: @item @kbd{\}
1021: has two functions: it quotes the special characters (including
1022: @samp{\}), and it introduces additional special constructs.
1023: 
1024: Because @samp{\} quotes special characters, @samp{\$} is a regular
1025: expression that matches only @samp{$}, and @samp{\[} is a regular
1026: expression that matches only @samp{[}, and so on.
1027: 
1028: See the following section for the special constructs that begin
1029: with @samp{\}.
1030: @end table
1031: 
1032:   Note: for historical compatibility, special characters are treated as
1033: ordinary ones if they are in contexts where their special meanings make no
1034: sense.  For example, @samp{*foo} treats @samp{*} as ordinary since there is
1035: no preceding expression on which the @samp{*} can act.  It is poor practice
1036: to depend on this behavior; it is better to quote the special character anyway,
1037: regardless of where it appears.
1038: 
1039: As a @samp{\} is not special inside a character alternative, it can
1040: never remove the special meaning of @samp{-} or @samp{]}.  So you
1041: should not quote these characters when they have no special meaning
1042: either.  This would not clarify anything, since backslashes can
1043: legitimately precede these characters where they @emph{have} special
1044: meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax),
1045: which matches any single character except a backslash.
1046: 
1047: @node Regexp Backslash
1048: @section Backslash in Regular Expressions
1049: 
1050:   For the most part, @samp{\} followed by any character matches only
1051: that character.  However, there are several exceptions: two-character
1052: sequences starting with @samp{\} that have special meanings.  The
1053: second character in the sequence is always an ordinary character when
1054: used on its own.  Here is a table of @samp{\} constructs.
1055: 
1056: @table @kbd
1057: @item \|
1058: specifies an alternative.  Two regular expressions @var{a} and @var{b}
1059: with @samp{\|} in between form an expression that matches some text if
1060: either @var{a} matches it or @var{b} matches it.  It works by trying to
1061: match @var{a}, and if that fails, by trying to match @var{b}.
1062: 
1063: Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
1064: but no other string.
1065: 
1066: @samp{\|} applies to the largest possible surrounding expressions.  Only a
1067: surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
1068: @samp{\|}.
1069: 
1070: Full backtracking capability exists to handle multiple uses of @samp{\|}.
1071: 
1072: @item \( @dots{} \)
1073: is a grouping construct that serves three purposes:
1074: 
1075: @enumerate
1076: @item
1077: To enclose a set of @samp{\|} alternatives for other operations.
1078: Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
1079: 
1080: @item
1081: To enclose a complicated expression for the postfix operators @samp{*},
1082: @samp{+} and @samp{?} to operate on.  Thus, @samp{ba\(na\)*} matches
1083: @samp{bananana}, etc., with any (zero or more) number of @samp{na}
1084: strings.
1085: 
1086: @item
1087: To record a matched substring for future reference.
1088: @end enumerate
1089: 
1090: This last application is not a consequence of the idea of a
1091: parenthetical grouping; it is a separate feature that is assigned as a
1092: second meaning to the same @w{@samp{\( @dots{} \)}} construct.  In practice
1093: there is usually no conflict between the two meanings; when there is
1094: a conflict, you can use a shy group, described below.
1095: 
1096: @item \(?: @dots{} \)
1097: @cindex shy group, in regexp
1098: specifies a @dfn{shy group} that does not record the matched substring;
1099: you can't refer back to it with @samp{\@var{d}} (see below).  This is
1100: useful in mechanically combining regular expressions, so that you can
1101: add groups for syntactic purposes without interfering with the
1102: numbering of the groups that are meant to be referred to.
1103: 
1104: @item \@var{d}
1105: @cindex back reference, in regexp
1106: matches the same text that matched the @var{d}th occurrence of a
1107: @samp{\( @dots{} \)} construct.  This is called a @dfn{back
1108: reference}.
1109: 
1110: After the end of a @samp{\( @dots{} \)} construct, the matcher remembers
1111: the beginning and end of the text matched by that construct.  Then,
1112: later on in the regular expression, you can use @samp{\} followed by the
1113: digit @var{d} to mean ``match the same text matched the @var{d}th time
1114: by the @samp{\( @dots{} \)} construct''.
1115: 
1116: The strings matching the first nine @samp{\( @dots{} \)} constructs
1117: appearing in a regular expression are assigned numbers 1 through 9 in
1118: the order that the open-parentheses appear in the regular expression.
1119: So you can use @samp{\1} through @samp{\9} to refer to the text matched
1120: by the corresponding @samp{\( @dots{} \)} constructs.
1121: 
1122: For example, @samp{\(.*\)\1} matches any newline-free string that is
1123: composed of two identical halves.  The @samp{\(.*\)} matches the first
1124: half, which may be anything, but the @samp{\1} that follows must match
1125: the same exact text.
1126: 
1127: If a particular @samp{\( @dots{} \)} construct matches more than once
1128: (which can easily happen if it is followed by @samp{*}), only the last
1129: match is recorded.
1130: 
1131: @item \`
1132: matches the empty string, but only at the beginning of the string or
1133: buffer (or its accessible portion) being matched against.
1134: 
1135: @item \'
1136: matches the empty string, but only at the end of the string or buffer
1137: (or its accessible portion) being matched against.
1138: 
1139: @item \=
1140: matches the empty string, but only at point.
1141: 
1142: @item \b
1143: matches the empty string, but only at the beginning or
1144: end of a word.  Thus, @samp{\bfoo\b} matches any occurrence of
1145: @samp{foo} as a separate word.  @samp{\bballs?\b} matches
1146: @samp{ball} or @samp{balls} as a separate word.
1147: 
1148: @samp{\b} matches at the beginning or end of the buffer
1149: regardless of what text appears next to it.
1150: 
1151: @item \B
1152: matches the empty string, but @emph{not} at the beginning or
1153: end of a word.
1154: 
1155: @item \<
1156: matches the empty string, but only at the beginning of a word.
1157: @samp{\<} matches at the beginning of the buffer only if a
1158: word-constituent character follows.
1159: 
1160: @item \>
1161: matches the empty string, but only at the end of a word.  @samp{\>}
1162: matches at the end of the buffer only if the contents end with a
1163: word-constituent character.
1164: 
1165: @item \w
1166: matches any word-constituent character.  The syntax table determines
1167: which characters these are.  @xref{Syntax Tables,, Syntax Tables,
1168: elisp, The Emacs Lisp Reference Manual}.
1169: 
1170: @item \W
1171: matches any character that is not a word-constituent.
1172: 
1173: @item \_<
1174: matches the empty string, but only at the beginning of a symbol.
1175: A symbol is a sequence of one or more symbol-constituent characters.
1176: A symbol-constituent character is a character whose syntax is either
1177: @samp{w} or @samp{_}.  @samp{\_<} matches at the beginning of the
1178: buffer only if a symbol-constituent character follows.  As with words,
1179: the syntax table determines which characters are symbol-constituent.
1180: 
1181: @item \_>
1182: matches the empty string, but only at the end of a symbol.  @samp{\_>}
1183: matches at the end of the buffer only if the contents end with a
1184: symbol-constituent character.
1185: 
1186: @item \s@var{c}
1187: matches any character whose syntax is @var{c}.  Here @var{c} is a
1188: character that designates a particular syntax class: thus, @samp{w}
1189: for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.}
1190: for ordinary punctuation, etc.  @xref{Syntax Tables,, Syntax Tables,
1191: elisp, The Emacs Lisp Reference Manual}.
1192: 
1193: @item \S@var{c}
1194: matches any character whose syntax is not @var{c}.
1195: 
1196: @cindex categories of characters
1197: @cindex characters which belong to a specific language
1198: @findex describe-categories
1199: @item \c@var{c}
1200: matches any character that belongs to the category @var{c}.  For
1201: example, @samp{\cc} matches Chinese characters, @samp{\cg} matches
1202: Greek characters, etc.  For the description of the known categories,
1203: type @kbd{M-x describe-categories @key{RET}}.
1204: 
1205: @item \C@var{c}
1206: matches any character that does @emph{not} belong to category
1207: @var{c}.
1208: @end table
1209: 
1210:   The constructs that pertain to words and syntax are controlled by
1211: the setting of the syntax table.  @xref{Syntax Tables,, Syntax Tables,
1212: elisp, The Emacs Lisp Reference Manual}.
1213: 
1214: @node Regexp Example
1215: @section Regular Expression Example
1216: 
1217:   Here is an example of a regexp---similar to the regexp that Emacs
1218: uses, by default, to recognize the end of a sentence, not including
1219: the following space (i.e., the variable @code{sentence-end-base}):
1220: 
1221: @example
1222: @verbatim
1223: [.?!][]\"')}]*
1224: @end verbatim
1225: @end example
1226: 
1227: @noindent
1228: This contains two parts in succession: a character set matching
1229: period, @samp{?}, or @samp{!}, and a character set matching
1230: close-brackets, quotes, or parentheses, repeated zero or more times.
1231: 
1232: @node Lax Search
1233: @section Lax Matching During Searching
1234: 
1235: @cindex lax search
1236: @cindex character equivalence in search
1237:   Normally, you'd want search commands to disregard certain minor
1238: differences between the search string you type and the text being
1239: searched.  For example, sequences of whitespace characters of
1240: different length are usually perceived as equivalent; letter-case
1241: differences usually don't matter; etc.  This is known as
1242: @dfn{character equivalence}.
1243: 
1244:   This section describes the Emacs lax search features, and how to
1245: tailor them to your needs.
1246: 
1247: @cindex lax space matching in search
1248: @kindex M-s SPC @r{(Incremental search)}
1249: @kindex SPC @r{(Incremental search)}
1250: @findex isearch-toggle-lax-whitespace
1251: @vindex search-whitespace-regexp
1252:   By default, search commands perform @dfn{lax space matching}:
1253: each space, or sequence of spaces, matches any sequence of one or more
1254: whitespace characters in the text.  (Incremental regexp search has a
1255: separate default; see @ref{Regexp Search}.)  Hence, @w{@samp{foo bar}}
1256: matches @w{@samp{foo bar}}, @w{@samp{foo@ @ bar}},
1257: @w{@samp{foo@ @ @ bar}}, and so on (but not @samp{foobar}).  More
1258: precisely, Emacs matches each sequence of space characters in the
1259: search string to a regular expression specified by the variable
1260: @code{search-whitespace-regexp}.  For example, to make spaces match
1261: sequences of newlines as well as spaces, set it to
1262: @samp{"[[:space:]\n]+"}.  The default value of this variable depends
1263: on the buffer's major mode; most major modes classify spaces, tabs,
1264: and formfeed characters as whitespace.
1265: 
1266:   If you want whitespace characters to match exactly, you can turn lax
1267: space matching off by typing @kbd{M-s @key{SPC}}
1268: (@code{isearch-toggle-lax-whitespace}) within an incremental search.
1269: Another @kbd{M-s @key{SPC}} turns lax space matching back on.  To
1270: disable lax whitespace matching for all searches, change
1271: @code{search-whitespace-regexp} to @code{nil}; then each space in the
1272: search string matches exactly one space.
1273: 
1274: @cindex case folding in search
1275: @cindex case-sensitivity and search
1276:   Searches in Emacs by default ignore the case of the text they are
1277: searching through, if you specify the search string in lower case.
1278: Thus, if you specify searching for @samp{foo}, then @samp{Foo} and
1279: @samp{fOO} also match.  Regexps, and in particular character sets,
1280: behave likewise: @samp{[ab]} matches @samp{a} or @samp{A} or @samp{b}
1281: or @samp{B}.  This feature is known as @dfn{case folding}, and it is
1282: supported in both incremental and non-incremental search modes.
1283: 
1284: @vindex search-upper-case
1285:   An upper-case letter anywhere in the search string makes the search
1286: case-sensitive.  Thus, searching for @samp{Foo} does not find
1287: @samp{foo} or @samp{FOO}.  This applies to regular expression search
1288: as well as to literal string search.  The effect ceases if you delete
1289: the upper-case letter from the search string.  The variable
1290: @code{search-upper-case} controls this: if it is non-@code{nil} (the
1291: default), an upper-case character in the search string makes the
1292: search case-sensitive; setting it to @code{nil} disables this effect
1293: of upper-case characters.
1294: 
1295: @vindex case-fold-search
1296:   If you set the variable @code{case-fold-search} to @code{nil}, then
1297: all letters must match exactly, including case.  This is a per-buffer
1298: variable; altering the variable normally affects only the current buffer,
1299: unless you change its default value.  @xref{Locals}.
1300: This variable applies to nonincremental searches also, including those
1301: performed by the replace commands (@pxref{Replace}) and the minibuffer
1302: history matching commands (@pxref{Minibuffer History}).
1303: 
1304: @kindex M-c @r{(Incremental search)}
1305: @kindex M-s c @r{(Incremental search)}
1306: @findex isearch-toggle-case-fold
1307:   Typing @kbd{M-c} or @kbd{M-s c} (@code{isearch-toggle-case-fold})
1308: within an incremental search toggles the case sensitivity of that
1309: search.  The effect does not extend beyond the current incremental
1310: search, but it does override the effect of adding or removing an
1311: upper-case letter in the current search.
1312: 
1313:   Several related variables control case-sensitivity of searching and
1314: matching for specific commands or activities.  For instance,
1315: @code{tags-case-fold-search} controls case sensitivity for
1316: @code{find-tag}.  To find these variables, do @kbd{M-x
1317: apropos-variable @key{RET} case-fold-search @key{RET}}.
1318: 
1319: @cindex character folding in search
1320: @cindex equivalent character sequences
1321:   Case folding disregards case distinctions among characters, making
1322: upper-case characters match lower-case variants, and vice versa.  A
1323: generalization of case folding is @dfn{character folding}, which
1324: disregards wider classes of distinctions among similar characters.
1325: For instance, under character folding the letter @code{a} matches all
1326: of its accented cousins like @code{@"a} and @code{@'a}, i.e., the
1327: match disregards the diacritics that distinguish these
1328: variants.  In addition, @code{a} matches other characters that
1329: resemble it, or have it as part of their graphical representation,
1330: such as @sc{u+249c parenthesized latin small letter a} and @sc{u+2100
1331: account of} (which looks like a small @code{a} over @code{c}).
1332: Similarly, the @acronym{ASCII} double-quote character @code{"} matches
1333: all the other variants of double quotes defined by the Unicode
1334: standard.  Finally, character folding can make a sequence of one or
1335: more characters match another sequence of a different length: for
1336: example, the sequence of two characters @code{ff} matches @sc{u+fb00
1337: latin small ligature ff}.  Character sequences that are not identical,
1338: but match under character folding are known as @dfn{equivalent
1339: character sequences}.
1340: 
1341: @kindex M-s ' @r{(Incremental Search)}
1342: @findex isearch-toggle-char-fold
1343:   Generally, search commands in Emacs do not by default perform
1344: character folding in order to match equivalent character sequences.
1345: You can enable this behavior by customizing the variable
1346: @code{search-default-mode} to @code{char-fold-to-regexp}.
1347: @xref{Search Customizations}.  Within an incremental search, typing
1348: @kbd{M-s '} (@code{isearch-toggle-char-fold}) toggles character
1349: folding, but only for that search.  (Replace commands have a different
1350: default, controlled by a separate option; see @ref{Replacement and Lax
1351: Matches}.)
1352: 
1353:   Like with case folding, typing an explicit variant of a character,
1354: such as @code{@"a}, as part of the search string disables character
1355: folding for that search.  If you delete such a character from the
1356: search string, this effect ceases.
1357: 
1358: @node Replace
1359: @section Replacement Commands
1360: @cindex replacement
1361: @cindex search-and-replace commands
1362: @cindex string substitution
1363: @cindex global substitution
1364: 
1365:   Emacs provides several commands for performing search-and-replace
1366: operations.  In addition to the simple @kbd{M-x replace-string}
1367: command, there is @kbd{M-%} (@code{query-replace}), which presents
1368: each occurrence of the search pattern and asks you whether to replace
1369: it.
1370: 
1371:   The replace commands normally operate on the text from point to the
1372: end of the buffer.  When the region is active, they operate on it
1373: instead (@pxref{Mark}).  The basic replace commands replace one
1374: @dfn{search string} (or regexp) with one @dfn{replacement string}.  It
1375: is possible to perform several replacements in parallel, using the
1376: command @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}).
1377: 
1378: @menu
1379: * Unconditional Replace::   Replacing all matches for a string.
1380: * Regexp Replace::          Replacing all matches for a regexp.
1381: * Replacement and Lax Matches::
1382:                             Lax searching for text to replace.
1383: * Query Replace::           How to use querying.
1384: @end menu
1385: 
1386: @node Unconditional Replace
1387: @subsection Unconditional Replacement
1388: @findex replace-string
1389: 
1390: @table @kbd
1391: @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
1392: Replace every occurrence of @var{string} with @var{newstring}.
1393: @end table
1394: 
1395:   To replace every instance of @samp{foo} after point with @samp{bar},
1396: use the command @kbd{M-x replace-string} with the two arguments
1397: @samp{foo} and @samp{bar}.  Replacement happens only in the text after
1398: point, so if you want to cover the whole buffer you must go to the
1399: beginning first.  All occurrences up to the end of the buffer are
1400: replaced; to limit replacement to part of the buffer, activate the
1401: region around that part.  When the region is active, replacement is
1402: limited to the region (@pxref{Mark}).
1403: 
1404:   When @code{replace-string} exits, it leaves point at the last
1405: occurrence replaced.  It adds the prior position of point (where the
1406: @code{replace-string} command was issued) to the mark ring, without
1407: activating the mark; use @kbd{C-u C-@key{SPC}} to move back there.
1408: @xref{Mark Ring}.
1409: 
1410:   A prefix argument restricts replacement to matches that are
1411: surrounded by word boundaries.
1412: 
1413:   @xref{Replacement and Lax Matches}, for details about
1414: case-sensitivity and character folding in replace commands.
1415: 
1416: @node Regexp Replace
1417: @subsection Regexp Replacement
1418: @findex replace-regexp
1419: 
1420:   The @kbd{M-x replace-string} command replaces exact matches for a
1421: single string.  The similar command @kbd{M-x replace-regexp} replaces
1422: any match for a specified regular expression pattern (@pxref{Regexps}).
1423: 
1424: @table @kbd
1425: @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
1426: Replace every match for @var{regexp} with @var{newstring}.
1427: @end table
1428: 
1429: @cindex back reference, in regexp replacement
1430:   In @code{replace-regexp}, the @var{newstring} need not be constant:
1431: it can refer to all or part of what is matched by the @var{regexp}.
1432: @samp{\&} in @var{newstring} stands for the entire match being
1433: replaced.  @samp{\@var{d}} in @var{newstring}, where @var{d} is a
1434: digit starting from 1, stands for whatever matched the @var{d}th
1435: parenthesized grouping in @var{regexp}.  (This is called a ``back
1436: reference''.)  @samp{\#} refers to the count of replacements already
1437: made in this command, as a decimal number.  In the first replacement,
1438: @samp{\#} stands for @samp{0}; in the second, for @samp{1}; and so on.
1439: For example,
1440: 
1441: @example
1442: M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
1443: @end example
1444: 
1445: @noindent
1446: replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
1447: with @samp{cddr-safe}.
1448: 
1449: @example
1450: M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
1451: @end example
1452: 
1453: @noindent
1454: performs the inverse transformation.  To include a @samp{\} in the
1455: text to replace with, you must enter @samp{\\}.
1456: 
1457:   If you want to enter part of the replacement string by hand each
1458: time, use @samp{\?} in the replacement string.  Each replacement will
1459: ask you to edit the replacement string in the minibuffer, putting
1460: point where the @samp{\?} was.
1461: 
1462:   The remainder of this subsection is intended for specialized tasks
1463: and requires knowledge of Lisp.  Most readers can skip it.
1464: 
1465:   You can use Lisp expressions to calculate parts of the
1466: replacement string.  To do this, write @samp{\,} followed by the
1467: expression in the replacement string.  Each replacement calculates the
1468: value of the expression and converts it to text without quoting (if
1469: it's a string, this means using the string's contents), and uses it in
1470: the replacement string in place of the expression itself.  If the
1471: expression is a symbol, one space in the replacement string after the
1472: symbol name goes with the symbol name, so the value replaces them
1473: both.
1474: 
1475:   Inside such an expression, you can use some special sequences.
1476: @samp{\&} and @samp{\@var{d}} refer here, as usual, to the entire
1477: match as a string, and to a submatch as a string.  @var{d} may be
1478: multiple digits, and the value of @samp{\@var{d}} is @code{nil} if the
1479: @var{d}'th parenthesized grouping did not match.  You can also use
1480: @samp{\#&} and @samp{\#@var{d}} to refer to those matches as numbers
1481: (this is valid when the match or submatch has the form of a numeral).
1482: @samp{\#} here too stands for the number of already-completed
1483: replacements.
1484: 
1485:   Repeating our example to exchange @samp{x} and @samp{y}, we can thus
1486: do it also this way:
1487: 
1488: @example
1489: M-x replace-regexp @key{RET} \(x\)\|y @key{RET}
1490: \,(if \1 "y" "x") @key{RET}
1491: @end example
1492: 
1493:   For computing replacement strings for @samp{\,}, the @code{format}
1494: function is often useful (@pxref{Formatting Strings,,, elisp, The Emacs
1495: Lisp Reference Manual}).  For example, to add consecutively numbered
1496: strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are
1497: already occupied), you can use
1498: 
1499: @example
1500: M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET}
1501: \,(format "%-72sABC%05d" \& \#) @key{RET}
1502: @end example
1503: 
1504: @node Replacement and Lax Matches
1505: @subsection Replace Commands and Lax Matches
1506: 
1507:   This subsection describes the behavior of replace commands with
1508: respect to lax matches (@pxref{Lax Search}) and how to customize it.
1509: In general, replace commands mostly default to stricter matching than
1510: their search counterparts.
1511: 
1512: @cindex lax space matching in replace commands
1513: @vindex replace-lax-whitespace
1514:   Unlike incremental search, the replacement commands do not use lax
1515: space matching (@pxref{Lax Search, lax space matching}) by default.
1516: To enable lax space matching for replacement, change the variable
1517: @code{replace-lax-whitespace} to non-@code{nil}.  (This only affects
1518: how Emacs finds the text to replace, not the replacement text.)
1519: 
1520: @vindex replace-regexp-lax-whitespace
1521:   A companion variable @code{replace-regexp-lax-whitespace} controls
1522: whether @code{query-replace-regexp} uses lax whitespace matching when
1523: searching for patterns.
1524: 
1525: @cindex case folding in replace commands
1526:   If the first argument of a replace command is all lower case, the
1527: command ignores case while searching for occurrences to
1528: replace---provided @code{case-fold-search} is non-@code{nil}.  If
1529: @code{case-fold-search} is set to @code{nil}, case is always significant
1530: in all searches.
1531: 
1532: @vindex case-replace
1533:   In addition, when the @var{newstring} argument is all or partly lower
1534: case, replacement commands try to preserve the case pattern of each
1535: occurrence.  Thus, the command
1536: 
1537: @example
1538: M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
1539: @end example
1540: 
1541: @noindent
1542: replaces a lower case @samp{foo} with a lower case @samp{bar}, an
1543: all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with
1544: @samp{Bar}.  (These three alternatives---lower case, all caps, and
1545: capitalized, are the only ones that @code{replace-string} can
1546: distinguish.)
1547: 
1548:   If upper-case letters are used in the replacement string, they remain
1549: upper case every time that text is inserted.  If upper-case letters are
1550: used in the first argument, the second argument is always substituted
1551: exactly as given, with no case conversion.  Likewise, if either
1552: @code{case-replace} or @code{case-fold-search} is set to @code{nil},
1553: replacement is done without case conversion.
1554: 
1555: @cindex character folding in replace commands
1556:   The replacement commands by default do not use character folding
1557: (@pxref{Lax Search, character folding}) when looking for the text to
1558: replace.  To enable character folding for matching in
1559: @code{query-replace} and @code{replace-string}, set the variable
1560: @code{replace-char-fold} to a non-@code{nil} value.  (This
1561: setting does not affect the replacement text, only how Emacs finds the
1562: text to replace.  It also doesn't affect @code{replace-regexp}.)
1563: 
1564: @node Query Replace
1565: @subsection Query Replace
1566: @cindex query replace
1567: 
1568: @table @kbd
1569: @item M-% @var{string} @key{RET} @var{newstring} @key{RET}
1570: Replace some occurrences of @var{string} with @var{newstring}.
1571: @item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET}
1572: Replace some matches for @var{regexp} with @var{newstring}.
1573: @end table
1574: 
1575: @kindex M-%
1576: @findex query-replace
1577:   If you want to change only some of the occurrences of @samp{foo} to
1578: @samp{bar}, not all of them, use @kbd{M-%} (@code{query-replace}).
1579: This command finds occurrences of @samp{foo} one by one, displays each
1580: occurrence and asks you whether to replace it.  Aside from querying,
1581: @code{query-replace} works just like @code{replace-string}
1582: (@pxref{Unconditional Replace}).  In particular, it preserves case
1583: provided @code{case-replace} is non-@code{nil}, as it normally is
1584: (@pxref{Replacement and Lax Matches}).  A numeric argument means to
1585: consider only occurrences that are bounded by word-delimiter
1586: characters.  A negative prefix argument replaces backward.
1587: 
1588: @kindex C-M-%
1589: @findex query-replace-regexp
1590:   @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}).
1591: It works like @code{replace-regexp} except that it queries
1592: like @code{query-replace}.
1593: 
1594: @vindex query-replace-from-to-separator
1595:   You can reuse earlier replacements with these commands.  When
1596: @code{query-replace} or @code{query-replace-regexp} prompts for the
1597: search string, use @kbd{M-p} and @kbd{M-n} to show previous
1598: replacements in the form @samp{@var{from} -> @var{to}}, where
1599: @var{from} is the search pattern, @var{to} is its replacement, and the
1600: separator between them is determined by the value of the variable
1601: @code{query-replace-from-to-separator}.  Type @key{RET} to select the
1602: desired replacement.  If the value of this variable is @code{nil},
1603: replacements are not added to the command history, and cannot be
1604: reused.
1605: 
1606: @cindex faces for highlighting query replace
1607: @cindex @code{query-replace} face
1608: @cindex @code{lazy-highlight} face, in replace
1609: @vindex query-replace-highlight
1610: @vindex query-replace-lazy-highlight
1611: @vindex query-replace-show-replacement
1612:   These commands highlight the current match using the face
1613: @code{query-replace}.  You can disable this highlight by setting the
1614: variable @code{query-replace-highlight} to @code{nil}.  They highlight
1615: other matches using @code{lazy-highlight} just like incremental search
1616: (@pxref{Incremental Search}); this can be disabled by setting
1617: @code{query-replace-lazy-highlight} to @code{nil}.  By default,
1618: @code{query-replace-regexp} will show the substituted replacement
1619: string for the current match in the minibuffer.  If you want to keep
1620: special sequences @samp{\&} and @samp{\@var{n}} unexpanded, customize
1621: @code{query-replace-show-replacement} variable.
1622: 
1623: @vindex query-replace-skip-read-only
1624:   The variable @code{query-replace-skip-read-only}, if set
1625: non-@code{nil}, will cause replacement commands to ignore matches in
1626: read-only text.  The default is not to ignore them.
1627: 
1628:   The characters you can type when you are shown a match for the string
1629: or regexp are:
1630: 
1631: @ignore @c Not worth it.
1632: @kindex SPC @r{(query-replace)}
1633: @kindex DEL @r{(query-replace)}
1634: @kindex , @r{(query-replace)}
1635: @kindex RET @r{(query-replace)}
1636: @kindex . @r{(query-replace)}
1637: @kindex ! @r{(query-replace)}
1638: @kindex ^ @r{(query-replace)}
1639: @kindex C-r @r{(query-replace)}
1640: @kindex C-w @r{(query-replace)}
1641: @kindex C-l @r{(query-replace)}
1642: @end ignore
1643: 
1644: @c WideCommands
1645: @table @kbd
1646: @item @key{SPC}
1647: @itemx y
1648: to replace the occurrence with @var{newstring}.
1649: 
1650: @item @key{DEL}
1651: @itemx @key{Delete}
1652: @itemx @key{BACKSPACE}
1653: @itemx n
1654: to skip to the next occurrence without replacing this one.
1655: 
1656: @item , @r{(Comma)}
1657: to replace this occurrence and display the result.  You are then asked
1658: for another input character to say what to do next.  Since the
1659: replacement has already been made, @key{DEL} and @key{SPC} are
1660: equivalent in this situation; both move to the next occurrence.
1661: 
1662: You can type @kbd{C-r} at this point (see below) to alter the replaced
1663: text.  You can also type @kbd{C-x u} to undo the replacement; this exits
1664: the @code{query-replace}, so if you want to do further replacement you
1665: must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart
1666: (@pxref{Repetition}).
1667: 
1668: @item @key{RET}
1669: @itemx q
1670: to exit without doing any more replacements.
1671: 
1672: @item .@: @r{(Period)}
1673: to replace this occurrence and then exit without searching for more
1674: occurrences.
1675: 
1676: @item !
1677: to replace all remaining occurrences without asking again.
1678: 
1679: @item ^
1680: to go back to the position of the previous occurrence (or what used to
1681: be an occurrence), in case you changed it by mistake or want to
1682: reexamine it.
1683: 
1684: @item u
1685: to undo the last replacement and go back to where that replacement was
1686: made.
1687: 
1688: @item U
1689: to undo all the replacements and go back to where the first
1690: replacement was made.
1691: 
1692: @item C-r
1693: to enter a recursive editing level, in case the occurrence needs to be
1694: edited rather than just replaced with @var{newstring}.  When you are
1695: done, exit the recursive editing level with @kbd{C-M-c} to proceed to
1696: the next occurrence.  @xref{Recursive Edit}.
1697: 
1698: @item C-w
1699: to delete the occurrence, and then enter a recursive editing level as in
1700: @kbd{C-r}.  Use the recursive edit to insert text to replace the deleted
1701: occurrence of @var{string}.  When done, exit the recursive editing level
1702: with @kbd{C-M-c} to proceed to the next occurrence.
1703: 
1704: @item e
1705: to edit the replacement string in the minibuffer.  When you exit the
1706: minibuffer by typing @key{RET}, the minibuffer contents replace the
1707: current occurrence of the pattern.  They also become the new
1708: replacement string for any further occurrences.
1709: 
1710: @item C-l
1711: to redisplay the screen.  Then you must type another character to
1712: specify what to do with this occurrence.
1713: 
1714: @item Y @r{(Upper-case)}
1715: to replace all remaining occurrences in all remaining buffers in
1716: multi-buffer replacements (like the Dired @kbd{Q} command that performs
1717: query replace on selected files).  It answers this question and all
1718: subsequent questions in the series with ``yes'', without further
1719: user interaction.
1720: 
1721: @item N @r{(Upper-case)}
1722: to skip to the next buffer in multi-buffer replacements without
1723: replacing remaining occurrences in the current buffer.  It answers
1724: this question ``no'', gives up on the questions for the current buffer,
1725: and continues to the next buffer in the sequence.
1726: 
1727: @item C-h
1728: @itemx ?
1729: @itemx @key{F1}
1730: to display a message summarizing these options.  Then you must type
1731: another character to specify what to do with this occurrence.
1732: @end table
1733: 
1734:   Aside from this, any other character exits the @code{query-replace},
1735: and is then reread as part of a key sequence.  Thus, if you type
1736: @kbd{C-k}, it exits the @code{query-replace} and then kills to end of
1737: line.  In particular, @kbd{C-g} simply exits the @code{query-replace}.
1738: 
1739:   To restart a @code{query-replace} once it is exited, use @kbd{C-x
1740: @key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it
1741: used the minibuffer to read its arguments.  @xref{Repetition, C-x @key{ESC}
1742: @key{ESC}}.
1743: 
1744: @cindex invisible text, and query-replace
1745:   The option @code{search-invisible} determines how @code{query-replace}
1746: treats invisible text.  @xref{Outline Search}.
1747: 
1748:   @xref{Operating on Files}, for the Dired @kbd{Q} command which
1749: performs query replace on selected files.  See also @ref{Transforming
1750: File Names}, for Dired commands to rename, copy, or link files by
1751: replacing regexp matches in file names.
1752: 
1753: @node Other Repeating Search
1754: @section Other Search-and-Loop Commands
1755: 
1756:   Here are some other commands that find matches for a regular
1757: expression.  They all ignore case in matching, if the pattern contains
1758: no upper-case letters and @code{case-fold-search} is non-@code{nil}.
1759: Aside from @code{multi-occur} and @code{multi-occur-in-matching-buffers},
1760: which always search the whole buffer, all operate on the text from point
1761: to the end of the buffer, or on the region if it is active.
1762: 
1763: @table @kbd
1764: @findex multi-isearch-buffers
1765: @cindex isearch multiple buffers
1766: @cindex multiple-buffer isearch
1767: @item M-x multi-isearch-buffers
1768: Prompt for one or more buffer names, ending with @key{RET}; then,
1769: begin a multi-buffer incremental search in those buffers.  (If the
1770: search fails in one buffer, the next @kbd{C-s} tries searching the
1771: next specified buffer, and so forth.)  With a prefix argument, prompt
1772: for a regexp and begin a multi-buffer incremental search in buffers
1773: matching that regexp.
1774: 
1775: @findex multi-isearch-buffers-regexp
1776: @item M-x multi-isearch-buffers-regexp
1777: This command is just like @code{multi-isearch-buffers}, except it
1778: performs an incremental regexp search.
1779: 
1780: @findex multi-isearch-files
1781: @cindex isearch multiple files
1782: @cindex multiple-file isearch
1783: @item M-x multi-isearch-files
1784: Prompt for one or more file names, ending with @key{RET}; then,
1785: begin a multi-file incremental search in those files.  (If the
1786: search fails in one file, the next @kbd{C-s} tries searching the
1787: next specified file, and so forth.)  With a prefix argument, prompt
1788: for a regexp and begin a multi-file incremental search in files
1789: matching that regexp.
1790: 
1791: @findex multi-isearch-files-regexp
1792: @item M-x multi-isearch-files-regexp
1793: This command is just like @code{multi-isearch-files}, except it
1794: performs an incremental regexp search.
1795: 
1796: In some modes that set the buffer-local variable
1797: @code{multi-isearch-next-buffer-function} (e.g., in Change Log mode)
1798: a multi-file incremental search is activated automatically.
1799: 
1800: @cindex Occur mode
1801: @cindex mode, Occur
1802: @cindex match (face name)
1803: @vindex list-matching-lines-default-context-lines
1804: @vindex list-matching-lines-jump-to-current-line
1805: @c Too long.
1806: @c @cindex list-matching-lines-current-line-face (face name)
1807: @kindex M-s o
1808: @findex occur
1809: @item M-x occur
1810: @itemx M-s o
1811: Prompt for a regexp, and display a list showing each line in the
1812: buffer that contains a match for it.  If you type @kbd{M-n} at the
1813: prompt, you can reuse search strings from previous incremental
1814: searches.  The text that matched is highlighted using the @code{match}
1815: face.  A numeric argument @var{n} specifies that @var{n} lines of
1816: context are to be displayed before and after each matching line.
1817: 
1818: The default number of context lines is specified by the variable
1819: @code{list-matching-lines-default-context-lines}.  When
1820: @code{list-matching-lines-jump-to-current-line} is non-@code{nil} the
1821: current line is shown highlighted with face
1822: @code{list-matching-lines-current-line-face} and the point is set at
1823: the first match after such line.
1824: 
1825: You can also run @kbd{M-s o} when an incremental search is active;
1826: this uses the current search string.
1827: 
1828: Note that matches for the regexp you type are extended to include
1829: complete lines, and a match that starts before the previous match ends
1830: is not considered a match.
1831: 
1832: @kindex RET @r{(Occur mode)}
1833: @kindex o @r{(Occur mode)}
1834: @kindex C-o @r{(Occur mode)}
1835: In the @file{*Occur*} buffer, you can click on each entry, or move
1836: point there and type @key{RET}, to visit the corresponding position in
1837: the buffer that was searched.  @kbd{o} and @kbd{C-o} display the match
1838: in another window; @kbd{C-o} does not select it.  Alternatively, you
1839: can use the @kbd{M-g M-n} (@code{next-error}) command to visit the
1840: occurrences one by one (@pxref{Compilation Mode}).
1841: 
1842: @cindex Occur Edit mode
1843: @cindex mode, Occur Edit
1844: Typing @kbd{e} in the @file{*Occur*} buffer switches to Occur Edit
1845: mode, in which edits made to the entries are also applied to the text
1846: in the originating buffer.  Type @kbd{C-c C-c} to return to Occur
1847: mode.
1848: 
1849: @findex list-matching-lines
1850: The command @kbd{M-x list-matching-lines} is a synonym for @kbd{M-x
1851: occur}.
1852: 
1853: @findex multi-occur
1854: @item M-x multi-occur
1855: This command is just like @code{occur}, except it is able to search
1856: through multiple buffers.  It asks you to specify the buffer names one
1857: by one.
1858: 
1859: @findex multi-occur-in-matching-buffers
1860: @item M-x multi-occur-in-matching-buffers
1861: This command is similar to @code{multi-occur}, except the buffers to
1862: search are specified by a regular expression that matches visited file
1863: names.  With a prefix argument, it uses the regular expression to
1864: match buffer names instead.
1865: 
1866: @findex how-many
1867: @item M-x how-many
1868: Prompt for a regexp, and print the number of matches for it in the
1869: buffer after point.  If the region is active, this operates on the
1870: region instead.
1871: 
1872: @findex flush-lines
1873: @item M-x flush-lines
1874: Prompt for a regexp, and delete each line that contains a match for
1875: it, operating on the text after point.  This command deletes the
1876: current line if it contains a match starting after point.  If the
1877: region is active, it operates on the region instead; if a line
1878: partially contained in the region contains a match entirely contained
1879: in the region, it is deleted.
1880: 
1881: If a match is split across lines, @code{flush-lines} deletes all those
1882: lines.  It deletes the lines before starting to look for the next
1883: match; hence, it ignores a match starting on the same line at which
1884: another match ended.
1885: 
1886: @findex keep-lines
1887: @item M-x keep-lines
1888: Prompt for a regexp, and delete each line that @emph{does not} contain
1889: a match for it, operating on the text after point.  If point is not at
1890: the beginning of a line, this command always keeps the current line.
1891: If the region is active, the command operates on the region instead;
1892: it never deletes lines that are only partially contained in the region
1893: (a newline that ends a line counts as part of that line).
1894: 
1895: If a match is split across lines, this command keeps all those lines.
1896: @end table
1897: 
1898: @node Search Customizations
1899: @section Tailoring Search to Your Needs
1900: @cindex search customizations
1901: 
1902:   This section describes miscellaneous search-related customizations
1903: not described elsewhere.
1904: 
1905: @cindex default search mode
1906: @cindex search mode, default
1907:   The default search mode for the incremental search is specified by
1908: the variable @code{search-default-mode}.  It can be @code{nil},
1909: @code{t}, or a function.  If it is @code{nil}, the default mode is to
1910: do literal searches without character folding, but with case folding
1911: and lax-whitespace matches as determined by @code{case-fold-search}
1912: and @code{search-whitespace-regexp}, respectively (@pxref{Lax
1913: Search}).  If the value is @code{t}, incremental search defaults to
1914: regexp searches.  The default value specifies a function that only
1915: performs case folding and lax-whitespace matching.
1916: 
1917: @vindex search-highlight
1918:   The current match of an on-going incremental search is highlighted
1919: using the @code{isearch} face.  This highlighting can be disabled by
1920: setting the variable @code{search-highlight} to @code{nil}.
1921: 
1922: @cindex lazy highlighting customizations
1923: @vindex isearch-lazy-highlight
1924: @cindex @code{lazy-highlight} face
1925:   The other matches for the search string that are visible on display
1926: are highlighted using the @code{lazy-highlight} face.  Setting the
1927: variable @code{isearch-lazy-highlight} to @code{nil} disables this
1928: highlighting.  Here are some other variables that customize the lazy
1929: highlighting:
1930: 
1931: @table @code
1932: @item lazy-highlight-initial-delay
1933: Time in seconds to wait before highlighting visible matches.
1934: 
1935: @item lazy-highlight-interval
1936: Time in seconds between highlighting successive matches.
1937: 
1938: @item lazy-highlight-max-at-a-time
1939: The maximum number of matches to highlight before checking for input.
1940: A large number can take some time to highlight, so if you want to
1941: continue searching and type @kbd{C-s} or @kbd{C-r} during that time,
1942: Emacs will not respond until it finishes highlighting all those
1943: matches.  Thus, smaller values make Emacs more responsive.
1944: @end table
1945: 
1946: @vindex search-nonincremental-instead
1947:   Normally, entering @key{RET} within incremental search when the
1948: search string is empty launches a nonincremental search.  (Actually,
1949: it lets you edit the search string, and the next @key{RET} does the
1950: search.)  However, if you customize the variable
1951: @code{search-nonincremental-instead} to @code{nil}, typing @key{RET}
1952: will always exit the incremental search, even if the search string is
1953: empty.
1954: 
1955: @vindex isearch-hide-immediately
1956:   By default, incremental search and query-replace commands match
1957: invisible text, but hide any such matches as soon as the current match
1958: moves off the invisible text.  If you customize the variable
1959: @code{isearch-hide-immediately} to @code{nil}, any invisible text
1960: where matches were found stays on display until the search or the
1961: replace command exits.
1962: 
1963: @cindex search display on slow terminals
1964: @vindex search-slow-speed
1965: @vindex search-slow-window-lines
1966:   Searching incrementally on slow terminals, such as displays
1967: connected to remote machines over slow connection, could be annoying
1968: due to the need to redraw large portions of the display as the search
1969: proceeds.  Emacs provides a special display mode for slow terminals,
1970: whereby search pops up a separate small window and displays the text
1971: surrounding the match in that window.  Small windows display faster,
1972: so the annoying effect of slow speed is alleviated.  The variable
1973: @code{search-slow-speed} determines the baud rate threshold below
1974: which Emacs will use this display mode.  The variable
1975: @code{search-slow-window-lines} controls the number of lines in the
1976: window Emacs pops up for displaying the search results; the default is
1977: 1 line.  Normally, this window will pop up at the bottom of the window
1978: that displays the buffer where you start searching, but if the value
1979: of @code{search-slow-window-lines} is negative, that means to put the
1980: window at the top and give it the number of lines that is the absolute
1981: value of @code{search-slow-window-lines}.
1982: