: [[image:iciclesimage]] || *Previous:* [[Icicles - Search Commands, Overview]] || '''[[Icicles]]''' || IciclesIndex || *Next:* [[Icicles - Other Search Commands]] || ---- == Icicles Search and Replace == Replacement during '''Icicles''' search is something quite different from anything you are used to. There are several different ways to replace search-hit text during '''Icicles''' search, and it can be a bit of a challenge to understand all the possibilities. So my advice is to experiment, as well as to read the descriptions here. You can replace the current search match by using any of the [[Icicles - More About Multi-Commands#AlternativeActions|alternative action]] keys: '''`C-S-RET'''', '''`C-S-mouse-2'''' (in `*Completions*'), '''`C-S-down'''', '''`C-S-up'''', '''`C-S-next'''', '''`C-S-prior'''', '''`C-S-end'''', and '''`C-S-home''''. You can use '''`##M-|##'''' (`icicle-all-candidates-list-alt-action') to replace all matches of your current input at once, throughout the search space. At the first use of any of these, you are prompted for the replacement; it is used thereafter, or until you use '''`##M-,##'''' (`icicle-search-define-replacement'). You can use `##M-,##' at any time during searching to change the replacement for subsequent replacing. Normally, the replacement is a pattern (a string), which can be ''anything that is allowed as a replacement by `query-replace-regexp'''. In Emacs 22 and later, this includes EmacsLisp [[sexp]] evaluation via '''`##\,##'''' -- see ReplaceRegexp for an explanation of `##\,##'. Alternatively, the replacement you define can be a Lisp ''function'', which is applied to the match that is to be replaced, to produce the actual text replacement. To define a function for replacement, use a [[prefix argument]] with `##M-,##` (or with `C-S-RET' etc.). Unlike `query-replace', you ''need not visit each'' search match -- you can visit and replace selected matches ''in any order''. Some other differences from standard `query-replace' and `query-replace-regexp': * Replacing matches of your current input provides a ''contextual'' replacement feature: replace `foo' by `fu', but only in zones that match `##toto.*titi##'. * '''Icicles''' search navigation (`C-next', etc.) lets you replace individual search hits without navigating through each [[search context]] in turn: ''direct access''. * In '''Icicles''' search, replace-all (`##M-|##') means replace all matches of your current input, throughout the search space, not just all matches that follow the [[cursor]]. And remember that you can (a) activate the [[region]] to limit the search-and-replace space and (b) use [[progressive completion]] etc. to narrow the set of hits. * You can act across ''multiple'' [[buffer]]s, files, or [[bookmark]]s -- see information about the `icicle-search' [[prefix argument]]. * You can also replace matches within ''text-property'' search contexts -- just use `icicle-search-text-property' ('''##‘C-c "’##''') as the search command. * As mentioned above, you can replace matches with the result of applying a ''function'' to them. [:SearchMatch--definition] Search matches are replaced -- but just what is meant by a "'''search match'''"? It can be either an entire [[search context]] or each match of your current [[minibuffer]] within a search context. ''Anytime during search and replace:'' * '''`##M-,##'''' redefines the replacement string. * '''`##C-`##'''' toggles '''`icicle-toggle-regexp-quote'''' (as always). This escapes [[regexp]] special characters, so that search is literal. * '''`M-q'''' toggles '''`icicle-search-whole-word-flag''''. By default, this is `nil', meaning that searching is not for whole words (except for `icicle-search-word', bound to `##C-c $##'). * '''`##C-M-`##'''' toggles '''`icicle-search-replace-literally-flag''''. By default, this is `nil', which means that `\' character sequences in replacement text are intrepreted as for `query-replace-regexp'. * '''`##M-_##'''' toggles '''`icicle-search-replace-whole-candidate-flag''''. By default, this is non-`nil', which means that the entire current [[search context]] is replaced, that is, whatever matches the context regexp that you entered initially using `RET'. However, you can use `##M-_##' anytime during searching to toggle between this default behavior and replacement of whatever your current minibuffer input matches. * '''`##M-;##'''' toggles '''`[[Icicles - Customization and General Tips#icicle-search-replace-common-match-flag|icicle-search-replace-common-match-flag]]''''. Together with other [[option]]s, it controls whether to replace the [[Icicles - Expanded-Common-Match Completion|expanded common match]] or just the exact match. See below. ''REMEMBER THIS:'' * If '''`icicle-search-replace-whole-candidate-flag'''' is true (non-`nil'), then the granularity of replacement is a ''complete [[search context]]''. In this case, replacement behaves similarly to `query-replace-regexp' (except that special replacement constructs, such as `##\###', are not treated as such). You can still use minibuffer input to filter the set of search contexts, but replacement is on a whole-context basis. * If '''`icicle-search-replace-whole-candidate-flag'''' is false (`nil'), then you can replace multiple input matches separately within a search context (using `C-S-RET'). This behavior is unique to '''Icicles'''. You cannot, however skip over one input match and replace the next one in the same context -- `C-S-RET' always replaces the first available match in the context (repeated use changes which is first). When `icicle-search-replace-whole-candidate-flag' is `nil', you can also use special replacement constructs, such as `##\###'. If '''`[[Icicles - Customization and General Tips#icicle-search-replace-whole-candidate-flag|icicle-search-replace-whole-candidate-flag]]'''' is true, then you can use the navigational [[Icicles - More About Multi-Commands#AlternativeActions|alternative action]] keys, `C-S-down', `C-S-up', `C-S-next', `C-S-prior', `C-S-end', and `C-S-home', repeatedly to replace successive search contexts. At the buffer limits, these commands wrap around to the other buffer limit (last search context to first, and vice versa). Search traversal using these go-to-next-context-and-replace keys is always by search context, not by input match. This means that you cannot use these keys to replace individual input matches within a search context. If `icicle-search-replace-whole-candidate-flag' is false, then you can use these keys to replace the first input match. More importantly, you can use `C-S-RET' to replace that first match, without moving on to the next context. Because `C-S-RET' always acts on the current search hit (context), using it again, after you have used it to replace the first such match, replaces the next one. And so on. Thus, if your input matches multiple parts of a search context, and you want to replace these matches, use '''`C-S-RET'''' repeatedly. After all of the matches in the current context have been replaced, `C-S-RET' replaces the first match in the next context. (There is a gotcha, however, if the replacement text matches your input -- see below.) You can thus traverse all matches of your input, in the current sort order (by default, the order they appear in the source being searched), by just repeating `C-S-RET'. At the buffer limits, repeating `C-S-RET' wraps around. [:C-S-RET-gotchas] `C-S-RET' always replaces the first input match in the current search context or, if there are no matches, then the first input match in the next context. This behavior has these important consequences: * If you repeat `C-S-RET' and the previous replacement no longer matches your input, then `C-S-RET' moves on to the next input match (which is now the first one) and replaces that. This is why you can usually just repeat `C-S-RET' to successively replaces matches of your input, including from one context to the next. * If, on the other hand, after replacement the text still matches your input, then repeating `C-S-RET' will just replace that match. For example, if you replace the input match `ab' by `abcd', then repeating `C-S-RET' produces `__abcd__', then `__abcd__cd', then `__abcd__cdcd', ... * You cannot replace an input match, skip the next match, and then replace the following one, all in the same context. You can, however, replace some matches and then skip (e.g. `C-next') to the next context. What your input matches, hence what gets replaced if '''`[[Icicles - Customization and General Tips#icicle-search-replace-whole-candidate-flag|icicle-search-replace-whole-candidate-flag]]'''' is `nil', depends on a few '''Icicles''' [[option]]s: * '''`[[Icicles - Customization and General Tips#icicle-regexp-quote-flag|icicle-regexp-quote-flag]]'''' determines whether to use [[regexp]] matching or literal matching. * '''`[[Icicles - Customization and General Tips#icicle-expand-input-to-common-match|icicle-expand-input-to-common-match]]'''', '''`[[Icicles - Customization and General Tips#icicle-search-highlight-all-current-flag|icicle-search-highlight-all-current-flag]]'''', and '''`[[Icicles - Customization and General Tips#icicle-search-replace-common-match-flag|icicle-search-replace-common-match-flag]]'''' together determine whether to replace exactly what your input matches in the current search hit or the [[Icicles - Expanded-Common-Match Completion|expanded common match]] (ECM) of your input among all search hits. If `icicle-expand-input-to-common-match' does not cause your input to be expanded (no ECM), or if either of the other options is `nil', then your exact input match is replaced. Otherwise, the ECM is replaced. The replacement string can be nearly anything that is allowed as a replacement by `query-replace-regexp'. In Emacs 22 or later, this includes EmacsLisp [[sexp]] evaluation via '''`##\,##'''' and constructs such as `##\###' and `##\N##' (back references). You can also use `##\?##', but it is not very useful -- you might as well use `##M-,##' instead, to change the replacement text. Finally, let me repeat what I said at the beginning of this page: '''Icicles''' search-and-replace is different from what you are used to, and there are several different ways to use it. Experiment to get to know how it works, and reread the description here. It is important to understand the various user options (with their toggle commands) and their effects. They can radically change the behavior of replacement. In particular, to put '''Icicles''' search-and-replace to best advantage you need to know ''what gets replaced'', depending on those user options: the whole search hit vs only input matches, an exact input match vs the expanded common match. Experiment with the toggles `##M-_##', `##C-^##', `##C-"##', and `##M-;##'. And you need to know how repeated `C-S-RET' works vs repeated `C-S-next'. I know it's tricky to learn. Experimenting helps. If something happens that you did not expect, reread this section and try to understand. Have fun. '''See Also:''' * [[Icicles - Search Commands, Overview]] and the [[doc string]] of `icicle-search' for more information about search-and-replace. * [[Icicles - Other Search Commands#IciclesCompileOrGrep]] for information about using search-and-replace with `grep' buffers and compilation buffers. * [[Icicles - Dired Enhancements]] for information about using search-and-replace on marked files in DiredMode. ---- || *Previous:* [[Icicles - Search Commands, Overview]] || '''[[Icicles]]''' || IciclesIndex || *Next:* [[Icicles - Other Search Commands]] || DrewsElispLibraries referenced here: Lisp:highlight.el, Lisp:icicles.el CategoryCommands CategoryCompletion CategoryRegexp CategoryRegion CategoryModes CategoryDirectories CategoryFiles CategoryProgrammerUtils CategoryCode CategorySearchAndReplace