Icicles - Search-And-Replace

Previous: Icicles - Search Commands, OverviewIciclesIciclesIndexNext: 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 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’:

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:


If `icicle-search-replace-whole-candidate-flag’ is true, then you can use the navigational 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’ 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:

What your input matches, hence what gets replaced if `icicle-search-replace-whole-candidate-flag’ is ‘nil’, depends on a few Icicles options:

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:

Previous: Icicles - Search Commands, OverviewIciclesIciclesIndexNext: Icicles - Other Search Commands

DrewsElispLibraries referenced here: Lisp:highlight.el, Lisp:icicles.el

CategoryCommands CategoryCompletion CategoryRegexp CategoryRegion CategoryModes CategoryDirectories CategoryFiles CategoryProgrammerUtils CategoryCode CategorySearchAndReplace