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