/
Icicles_-_Search-And-Replace
237 lines (173 loc) · 11.3 KB
/
Icicles_-_Search-And-Replace
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
: [[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 pattern; 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
pattern for subsequent replacements. The replacement pattern
can be ''anything that is allowed as a replacement by
`query-replace-regexp'''. In Emacs 22 or later, this includes EmacsLisp
[[sexp]] evaluation via '''`##\,##'''' -- see ReplaceRegexp for an explanation of `##\,##'.
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.
[: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 '''`<tt>[[Icicles - Customization and General Tips#icicle-search-replace-common-match-flag|icicle-search-replace-common-match-flag]]</tt>''''.
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 '''`<tt>[[Icicles - Customization and General Tips#icicle-search-replace-whole-candidate-flag|icicle-search-replace-whole-candidate-flag]]</tt>'''' 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
'''`<tt>[[Icicles - Customization and General Tips#icicle-search-replace-whole-candidate-flag|icicle-search-replace-whole-candidate-flag]]</tt>'''' is `nil', depends on a
few '''Icicles''' [[option]]s:
* '''`<tt>[[Icicles - Customization and General Tips#icicle-regexp-quote-flag|icicle-regexp-quote-flag]]</tt>'''' determines whether to use [[regexp]]
matching or literal matching.
* '''`<tt>[[Icicles - Customization and General Tips#icicle-search-highlight-all-current-flag|icicle-search-highlight-all-current-flag]]</tt>'''', '''`<tt>[[Icicles - Customization and General Tips#icicle-expand-input-to-common-match-flag|icicle-expand-input-to-common-match-flag]]</tt>'''', and
'''`<tt>[[Icicles - Customization and General Tips#icicle-search-replace-common-match-flag|icicle-search-replace-common-match-flag]]</tt>'''' 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 any of these 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 didn't 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