EmacsWiki: Replace Plus (original) (raw)
This page is about library Replace+, replace+.el. It extends functionalities in the standard Emacs library replace.el, enhancing commands ‘query-replace’ and ‘occur’. (For Emacs 20 it also enhances ‘keep-lines’, ‘flush-lines’, and ‘how-many’.)
Default Value for the Text Acted On
Common to the enhancements for commands ‘query-replace’ and ‘occur’ (and ‘keep-lines’, ‘flush-lines’, and ‘how-many’ for Emacs 20) is the handling of a default value when reading input. For ‘query-replace’ this applies to the text to be replaced and the replacement text. For ‘occur’ it applies to the regexp used to match buffer lines.
The defaulting is very flexible, so it might sound a bit complex. Defaulting is determined in the following order:
1. For ‘query-replace’ only, just as in vanilla Emacs, empty input means to repeat query-replacing using the same old and new text as the last time. This is not a change in behavior.
2. If the region is active and option ‘search/replace-region-as-default-flag’ is non-‘nil’, then the region text is a default.
3. Else, if option ‘search/replace-2nd-sel-as-default-flag’ is non-‘nil’ and the SecondarySelection is defined, then the secondary-selection text is a default.
4. Else, if option ‘search/replace-default-fn’ is non-‘nil’ then it is a function of zero arguments that is called to return a default.
5. Else the first entry in the minibuffer history is a default.
(For Emacs 23 and later, all defaults that can be defined as listed are available, in this order. For Emacs prior to 23, only the first default that can be defined is available.)
Note that ‘query-replace’, unlike the other commands enhanced here, normally uses the region not as default text but to restrict the scope of the command action. When option ‘search/replace-region-as-default-flag’ is non-‘nil’ you lose this feature and gain using the region for defaulting. In this case you can just narrow the region (‘C-x n n’) to restrict the scope of the command.
Because both uses of the region can be useful, you can easily toggles the value of option ‘search/replace-region-as-default-flag’ using command ‘toggle-search/replace-region-as-default’.
Wrt #4 above, consider using library thingatpt+.el, which provides plenty of functions that are useful for grabbing text at point to use as a default value. Among these is the default value of ‘search/replace-default-fn’ (if defined), ‘non-nil-symbol-name-nearest-point’. It finds the nearest symbol to the cursor and returns its name.
Query-Replace
Library replace+.el does not redefine either of the standard query-replace commands, ‘query-replace’ or ‘query-replace-regexp’. Instead, it defines a new command that combines them.
- Command
‘query-replace-w-options’rolls commands‘query-replace’and‘query-replace-regexp’into one. I bind this to **`M-%**’, in place of‘query-replace’. The prefix argument governs the behavior:- None – Replace literal string
matches, searching forward (like‘query-replace’with no prefix arg). ‘-’– Replace literal string
matches, searching backward (like‘query-replace’with a negative prefix arg).- Plain
‘C-u’– Replace word
matches, searching forward (like‘query-replace’with a prefix arg other than‘-’) - Non-negative (e.g.
‘C-2’) – Replace regexp
matches, searching forward (like‘query-replace-regexp’with no prefix arg) - Negative (e.g.
‘C-- 2’) – Replace regexp
matches, searching backward (like‘query-replace-regexp’with a negative prefix arg)
- None – Replace literal string
- If option
‘isearchp-set-region-flag’is non-‘nil’, then‘query-replace-w-options’selects the last target occurrence; that is, it sets the region around it. You can also select the last target manually, using command‘set-region-around-search-target’. This option and command‘set-region-around-search-target’are defined in library isearch+.el. - If option
‘replace-w-completion-flag’is non-‘nil’, then you can use completion when reading the new and old text. (If you use completion, you can enter a space or tab character using‘C-q’.) This option is defined in replace+.el. Command‘toggle-replace-w-completion’toggles option‘replace-w-completion-flag’. - Defaulting is as described above.
- If you also use library isearch+.el then non-
‘nil’option‘isearchp-highlight-regexp-group-levels-flag’means that‘query-replace-regexp’(*`C-M-%**’) highlights the match of each regexp group differently. For lazy-highlighting of other search hits, the odd groups are highlighted differently from the even groups. This is the effect for a search hit for regexp(**\(**`[-a-z]+**)****(**(**(**([-a-z]+**(**[^)]**)**)**)**)**)**.` :
See Also: IsearchPlus for more information about options ‘isearchp-set-region-flag’ and ‘isearchp-highlight-regexp-group-levels-flag’ and command ‘set-region-around-search-target’.
Occur Extensions
Library replace+.el provides the following extensions to Emacs’ standard ‘occur’ command:
- Defaulting is as described above.
- When you visit an occurrence, the line number is highlighted in buffer
‘*Occur*’, using face‘occur-highlight-linenum’. This is similar to highlighting links that you have already visited in Info or in a Web browser: it lets you know where you’ve been. - Occurrences matching the search pattern (regular expression) you supply to
‘occur’are highlighted in the‘*Occur*’buffer, using face‘list-matching-lines-face’. The effect is similar to that of highlighting with the Google toolbar. (This is available also for vanilla Emacs, starting with Emacs 22.) - The text matching the search pattern is highlighted in the source buffer also.
- (Emacs 20 only) In buffer
*Occur*, you can click anywhere on a found line: the entire line is mouse-face active. - (Emacs 20 only) The frame of buffer
*Occur*is shrink-wrapped to fit the matching lines.
See Also: OccurMode, for a screenshot and more information.
Extensions to `flush-lines', `keep-lines', and `how-many'
Library replace+.el provides the following extensions to commands ‘flush-lines’, ‘keep-lines’, and ‘how-many’. They are not needed for users of Emacs 21 or greater.
- Defaulting is as described above.
- The prompt lets you know that only lines after point are affected.