1 ;;; icicles-doc1.el --- Minibuffer input completion and cycling.
3 ;; Filename: icicles-doc1.el
4 ;; Description: Minibuffer completion and cycling.
6 ;; Maintainer: Drew Adams
7 ;; Copyright (C) 1996-2011, Drew Adams, all rights reserved.
8 ;; Created: Tue Aug 1 14:21:16 1995
10 ;; Last-Updated: Sat Sep 10 11:47:15 2011 (-0700)
13 ;; URL: http://www.emacswiki.org/cgi-bin/wiki/icicles-doc1.el
14 ;; Keywords: internal, extensions, help, abbrev, local, minibuffer,
15 ;; keys, apropos, completion, matching, regexp, command
16 ;; Compatibility: GNU Emacs: 20.x, 21.x, 22.x, 23.x
18 ;; Features that might be required by this library:
22 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
26 ;; Icicles documentation, part 1.
28 ;; Files `icicles-doc1.el' and `icicles-doc2.el' contain the doc for
29 ;; Icicles, including how to install and use Icicles. You can also
30 ;; read the Icicles doc, in formatted form, on the Emacs-Wiki Web
31 ;; site: http://www.emacswiki.org/cgi-bin/wiki/Icicles. Emacs Wiki
32 ;; also has a few addtional pages about Icicles. In particular, if
33 ;; you are new to Emacs, as well as Icicles, see this page:
34 ;; http://www.emacswiki.org/cgi-bin/wiki/EmacsNewbieWithIcicles.
36 ;;(@* "Installing Icicles")
38 ;; To use this library:
40 ;; Add this to your initialization file (~/.emacs or ~/_emacs):
42 ;; (require 'icicles) ; Load this library.
43 ;; (icicle-mode 1) ; Turn on Icicle mode.
45 ;; It is best to add this code *after* any code that creates or
46 ;; changes key bindings, so Icicles can pick up all of your key
47 ;; definitions (bindings). However, if you make new bindings, you
48 ;; can always exit and then reenter Icicle mode to pick them up.
50 ;; You will need all of these libraries (loaded by `icicles.el'):
52 ;; `icicles-chg.el' (not loaded - change logs only)
55 ;; `icicles-doc1.el' (not loaded - doc only)
56 ;; `icicles-doc2.el' (not loaded - doc only)
65 ;; The following libraries are recommended but optional (loaded by
66 ;; `icicles.el' if in your `load-path'). They are enhanced by
67 ;; Icicles, or Icicles is enhanced by them, or both. They are all
68 ;; available at Emacs Wiki,
69 ;; http://www.emacswiki.org/cgi-bin/wiki/ElispArea.
71 ;; `apropos-fn+var.el' - Apropos enhancements for fns and vars.
72 ;; `bookmark+.el' - Many bookmark enhancements.
73 ;; `col-highlight.el' - Required by `crosshairs.el'. Emacs 22+
74 ;; `crosshairs.el' - Highlight target positions. Emacs 22+
76 ;; `doremi-frm.el' - Incremental changes.
77 ;; `frame-cmds.el' - Frame and window commands.
78 ;; `fuzzy-match.el' - Fuzzy completion (matching).
79 ;; `hexrgb.el' - Color manipulation.
80 ;; `hl-line+.el' - Required by `crosshairs.el'. Emacs 22+
81 ;; `icomplete+.el' - Enhancements to `icomplete.el'
82 ;; `info+.el' - Enhancements to `info'.
83 ;; `lacarte.el' - Keyboard access to the menubar menus.
84 ;; `mb-depth+.el' - Minibuffer depth indicator. Emacs 22+
85 ;; `pp+.el' - Pretty-printing for `M-:'.
86 ;; `synonyms.el' - A hypertext thesaurus.
87 ;; `thingatpt+.el' - Better defaults for commands, `M-.'.
88 ;; `vline.el' - Required by `crosshairs.el'. Emacs 22+
90 ;; Be aware that some of these libraries in turn require other
91 ;; libraries. For example, library `frame-cmds.el' requires
92 ;; library `frame-fns.el'.
94 ;; Depending on your platform, if you use Icicles in a text
95 ;; terminal (that is, without a window system/manager), then you
96 ;; might need to change some of the key bindings, if some of the
97 ;; default bindings are not available to you.
99 ;; If on your platform, for example, Emacs in a text terminal does
100 ;; not recognize a key such as `S-TAB' (as something different from
101 ;; `TAB'), then you will want to change that key binding. To
102 ;; customize Icicles key bindings, see
103 ;; (@file :file-name "icicles-doc2.el" :to "Customizing Key Bindings").
104 ;; You might also want to customize some of the Icicles faces,
105 ;; since a text terminal is sometimes limited in the colors it can
108 ;; It is of course best to byte-compile all of the libraries
109 ;; (except `icicle-chg.el', `icicles-doc1.el', and
110 ;; `icicles-doc2.el'). You will likely get some byte-compiler
111 ;; warning messages. These are probably benign - ignore them.
112 ;; Icicles is designed to work with multiple versions of Emacs, and
113 ;; that fact provokes compiler warnings. If you get byte-compiler
114 ;; errors (not warnings), then please report a bug, using `M-x
115 ;; icicle-send-bug-report'.
117 ;; Whenever you update Icicles (i.e., download new versions of
118 ;; Icicles source files), I recommend that you do the following:
120 ;; 1. Delete all existing byte-compiled Icicles files
122 ;; 2. Load Icicles (`load-library' or `require').
123 ;; 3. Byte-compile the source files.
125 ;; In particular, always load `icicles-mac.el' (not
126 ;; `icicles-mac.elc') before you byte-compile new versions of the
127 ;; files, in case there have been any changes to Lisp macros (in
128 ;; `icicles-mac.el').
130 ;; After startup, you can turn Icicle mode on or off at any time
131 ;; interactively, using command `icy-mode' (aka `icicle-mode' -
132 ;; prefix `icy' is unique to this command, so it is easier to
135 ;; Note: If you turn on Icicle mode in your init file, it's
136 ;; generally best to do so as late as possible - after you or any
137 ;; libraries that you load do any key binding. This is because
138 ;; Icicles uses the current global key bindings to determine which
139 ;; keys to bind for minibuffer completion and cycling. To pick up
140 ;; the latest bindings at any time, you can of course enter Icicle
141 ;; mode interactively using command `icy-mode' (if necessary, exit,
144 ;; Note: Icicles redefines some functions when you are in Icicle
145 ;; mode (it restores them when you leave Icicle mode). It
146 ;; generally does not use `defadvice' to alter the functions; it
147 ;; redefines them instead. Because of this, there can be
148 ;; incompatibilities with other libraries that also change the same
149 ;; functions (using `defadvice' or otherwise). An example is Viper
150 ;; mode. If you load Viper before Icicles, then you will run into
151 ;; problems with function `read-file-name' because it is tweaked by
152 ;; both Viper and Icicles. If you load Icicles before Viper, you
153 ;; should not encounter this problem (but you might encounter other
154 ;; problems: both Icicles and Viper try to control the minibuffer).
161 ;; If you have library `linkd.el' and Emacs 22 or later, load
162 ;; `linkd.el' and turn on `linkd-mode' now. It lets you easily
163 ;; navigate around the sections of this doc. Linkd mode will
164 ;; highlight this Index and render it more readable. Likewise, for
165 ;; the cross-references and section headings throughout this file.
166 ;; You can get `linkd.el' here:
167 ;; http://www.emacswiki.org/cgi-bin/wiki/linkd.el.
169 ;; (@* "Documentation in File `icicles-doc1.el'")
170 ;; ----------------------------------------------
172 ;; (@> "Nutshell View of Icicles")
173 ;; (@> "README for NON-Readers")
175 ;; (@> "Toggle Options on the Fly")
176 ;; (@> "Cycle Completion Candidates")
177 ;; (@> "Display Completion Candidates")
178 ;; (@> "Prefix Completion and Apropos Completion")
179 ;; (@> "Chains of Simple Match Patterns - Progressive Completion")
180 ;; (@> "Chip Away the Non-Elephant")
181 ;; (@> "Choose Before You Act")
182 ;; (@> "Help on Completion Candidates")
183 ;; (@> "Perform Multiple Operations in One Command")
184 ;; (@> "Perform Alternative Operations on the Fly")
185 ;; (@> "Completion Status Indicators")
186 ;; (@> "Icicles Search")
187 ;; (@> "Complete Key Sequences Too")
188 ;; (@> "Available for Almost Any Input")
189 ;; (@> "Component Icicles Libraries")
190 ;; (@> "If You Are an Emacs-Lisp Programmer")
192 ;; (@> "Inserting Text Found Near the Cursor")
193 ;; (@> "FFAP: Find File At Point")
194 ;; (@> "Proxy Candidates, `M-.'")
195 ;; (@> "Repeat `M-.' To Grab More or Different")
196 ;; (@> "Resolve File Names")
197 ;; (@> "Background on Vanilla Emacs Input Completion")
198 ;; (@> "Cycling Completions")
199 ;; (@> "Traversing Minibuffer Histories")
200 ;; (@> "Apropos Completions")
201 ;; (@> "Expanded-Common-Match Completion")
202 ;; (@> "Progressive Completion")
203 ;; (@> "`M-*': Matching Additional Regexps")
204 ;; (@> "Successive Approximation...")
205 ;; (@> "`M-&': Satisfying Additional Predicates")
207 ;; (@> "Regressive Completion")
208 ;; (@> "Completion On Demand")
209 ;; (@> "Moving Between the Minibuffer and Other Buffers")
210 ;; (@> "Inserting a Regexp from a Variable or Register")
211 ;; (@> "Special Characters in Input Patterns")
212 ;; (@> "Exiting the Minibuffer Without Confirmation")
213 ;; (@> "Ido and IswitchB")
214 ;; (@> "*Completions* Display")
215 ;; (@> "Icompletion")
216 ;; (@> "icomplete+.el Displays the Number of Other Prefix Candidates")
217 ;; (@> "Icicles Highlights the Input that Won't Complete")
218 ;; (@> "Icompletion in *Completions*: Apropos and Prefix Completion")
220 ;; (@> "Sorting Candidates and Removing Duplicates")
221 ;; (@> "Changing the Sort Order")
222 ;; (@> "Defining New Sort Orders")
223 ;; (@> "Different Sorts for Different Sorts of Uses")
224 ;; (@> "Get Help on Candidates")
225 ;; (@> "Use Candidate Help Like You Use Emacs Command `apropos'")
226 ;; (@> "Other Icicles Apropos Commands")
228 ;; (@> "Multi-Commands")
229 ;; (@> "What Is a Multi-Command?")
230 ;; (@> "How Does a Multi-Command Work?")
232 ;; (@> "More about Multi-Commands")
233 ;; (@> "Alternative Actions")
234 ;; (@> "Deleting Objects")
235 ;; (@> "Option `icicle-use-C-for-actions-flag'")
236 ;; (@> "Accessing Saved Locations (Bookmarks) on the Fly")
238 ;; (@> "Icicles Tripping")
239 ;; (@> "Highlighting the Destination")
241 ;; (@> "Key Completion")
242 ;; (@> "Completing Keys")
243 ;; (@> "`S-TAB' Is Everywhere - Start With It")
244 ;; (@> "Completing Keys By Name")
245 ;; (@> "Completing Prefix Keys")
246 ;; (@> "Meta Key Bindings")
247 ;; (@> "Navigate the Key-Binding Hierarchy")
248 ;; (@> "Local Bindings Are Highlighted")
249 ;; (@> "Completing Keys By Just Hitting Them")
250 ;; (@> "Key and Command Help")
251 ;; (@> "`S-TAB' Is a Multi-Command")
252 ;; (@> "Possible Source of Confusion")
253 ;; (@> "Three-Key Emacs")
254 ;; (@> "Entering Special and Foreign Characters")
255 ;; (@> "Handling Keymaps That Are Inaccessible From the Global Map")
257 ;; (@> "Icicles Multi `M-x'")
258 ;; (@> "Examples of Using Multi `M-x'")
259 ;; (@> "What about describe-variable and describe-function?")
260 ;; (@> "Multi `M-x' Turns Every Command into a Multi-Command")
262 ;; (@> "Choose All Completion Candidates")
263 ;; (@> "Sets of Completion Candidates")
264 ;; (@> "Saving and Retrieving Completion Candidates")
265 ;; (@> "Different Places for Saving and Retrieving Candidates")
266 ;; (@> "Set Operations")
267 ;; (@> "Google Matching")
268 ;; (@> "Domain of Discourse")
269 ;; (@> "Global Filtering")
270 ;; (@> "Word Matching and String Matching")
271 ;; (@> "AND Matching and OR Matching")
272 ;; (@> "NOT Matching")
274 ;; (@> "Buffer-Name Input")
276 ;; (@> "File-Name Input and Locating Files Anywhere")
277 ;; (@> "Function `read-file-name'")
278 ;; (@> "Function `completing-read'")
279 ;; (@> "Icicles Commands that Read File Names")
280 ;; (@> "Absolute File Names and Different Directories")
282 ;; (@> "Persistent Sets of Completion Candidates")
283 ;; (@> "Saving Candidates in Cache Files")
284 ;; (@> "Filesets and Icicles Saved Completion Sets")
285 ;; (@> "Improving Performance with Persistent Sets")
286 ;; (@> "Avoid Remote File-Name Completion")
287 ;; (@> "Avoid Generating A Large Completion Set")
289 ;; (@> "Dealing With Large Candidate Sets")
290 ;; (@> "History Enhancements")
291 ;; (@> "What Input, What History?")
292 ;; (@> "Overview of Minibuffer History Enhancements")
293 ;; (@> "Using Completion to Insert Previous Inputs: `M-o'")
294 ;; (@> "Putting Previous Candidates First: `C-M-,'")
295 ;; (@> "Matching Only Historical Candidates: `M-h' and `M-pause'")
296 ;; (@> "Using Other Histories; Commands Any Which Way")
297 ;; (@> "Completing Against All Interactive Commands")
298 ;; (@> "Using an Alternative History")
299 ;; (@> "Cleaning Up History Lists")
301 ;; (@> "Isearch Enhancements")
302 ;; (@> "Launch Occur using the Isearch Search String")
303 ;; (@> "Launch Icicles Search using the Isearch Search String")
305 ;; (@file :file-name "icicles-doc2.el" :to "Documentation in File `icicles-doc2.el'")
306 ;; -----------------------------------------------------------
308 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
309 ;; (@file :file-name "icicles-doc2.el" :to "Introduction: On Beyond Occur...")
310 ;; (@file :file-name "icicles-doc2.el" :to "How Icicles Search Works")
311 ;; (@file :file-name "icicles-doc2.el" :to "Why Use 2 Search Patterns?")
312 ;; (@file :file-name "icicles-doc2.el" :to "Search Outside the Defined Search Contexts?")
313 ;; (@file :file-name "icicles-doc2.el" :to "Search Multiple Buffers, Files, and Bookmarks")
314 ;; (@file :file-name "icicles-doc2.el" :to "User Options for Icicles Searching")
315 ;; (@file :file-name "icicles-doc2.el" :to "Using Regexps with Icicles Search")
317 ;; (@file :file-name "icicles-doc2.el" :to "Search and Replace")
318 ;; (@file :file-name "icicles-doc2.el" :to "Other Icicles Search Commands")
319 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Imenu")
320 ;; (@file :file-name "icicles-doc2.el" :to "Type-Specific Imenu Commands")
321 ;; (@file :file-name "icicles-doc2.el" :to "Imenu Commands that Search Full Definitions")
322 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Imenu Combines Benefits of Imenu and Emacs Tags")
324 ;; (@file :file-name "icicles-doc2.el" :to "Compile/Grep Search")
325 ;; (@file :file-name "icicles-doc2.el" :to "Input Reuse in Interactive Interpreter Modes")
326 ;; (@file :file-name "icicles-doc2.el" :to "Define Your Own Icicles Search Commands")
328 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Bookmark Enhancements")
329 ;; (@file :file-name "icicles-doc2.el" :to "Saving Regions and Selecting Them")
330 ;; (@file :file-name "icicles-doc2.el" :to "Setting a Bookmark and Jumping to a Bookmark")
331 ;; (@file :file-name "icicles-doc2.el" :to "Jumping to a Bookmark")
332 ;; (@file :file-name "icicles-doc2.el" :to "Searching Bookmarked Objects")
333 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Enhancements for Emacs Tags")
334 ;; (@file :file-name "icicles-doc2.el" :to "`icicle-find-tag': Find Tags in All Tags Tables")
335 ;; (@file :file-name "icicles-doc2.el" :to "`icicle-find-first-tag': Find First Tag in Current Table")
336 ;; (@file :file-name "icicles-doc2.el" :to "`icicle-tags-search': Search and Replace Using Tags")
338 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Shell-Command Enhancements")
339 ;; (@file :file-name "icicles-doc2.el" :to "Shell Command Completion as File-Name Completion")
340 ;; (@file :file-name "icicles-doc2.el" :to "Gotcha: `$' in Shell Commands")
341 ;; (@file :file-name "icicles-doc2.el" :to "Known Shell Commands as Proxy Candidates")
342 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Dired Enhancements")
343 ;; (@file :file-name "icicles-doc2.el" :to "Search-and-Replace Marked Files")
344 ;; (@file :file-name "icicles-doc2.el" :to "Save Marked Files as Completion Candidates")
345 ;; (@file :file-name "icicles-doc2.el" :to "Open Dired for a Set of File Names")
346 ;; (@file :file-name "icicles-doc2.el" :to "Marked Files as a Project")
347 ;; (@file :file-name "icicles-doc2.el" :to "Shell Commands on Marked Files")
349 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Info Enhancements")
350 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Completion for Info")
351 ;; (@file :file-name "icicles-doc2.el" :to "Virtual Info Books")
353 ;; (@file :file-name "icicles-doc2.el" :to "Using Icicle-Search With Info")
355 ;; (@file :file-name "icicles-doc2.el" :to "Support for Projects")
356 ;; (@file :file-name "icicles-doc2.el" :to "Bookmarks for Project Access and Organization")
357 ;; (@file :file-name "icicles-doc2.el" :to "A Tags File Can Define a Project")
358 ;; (@file :file-name "icicles-doc2.el" :to "Navigating Among Code Definitions")
359 ;; (@file :file-name "icicles-doc2.el" :to "Searching Project Files")
360 ;; (@file :file-name "icicles-doc2.el" :to "Defining and Saving Sets of Files or Buffers")
361 ;; (@file :file-name "icicles-doc2.el" :to "Retrieving and Reusing a Saved Project")
362 ;; (@file :file-name "icicles-doc2.el" :to "Semantics? Roll Your Own?")
364 ;; (@file :file-name "icicles-doc2.el" :to "Using Complex Completion Candidates")
365 ;; (@file :file-name "icicles-doc2.el" :to "Icicles OO: Object-Action Interaction")
366 ;; (@file :file-name "icicles-doc2.el" :to "Apropos Completion as OO")
367 ;; (@file :file-name "icicles-doc2.el" :to "M-RET")
368 ;; (@file :file-name "icicles-doc2.el" :to "`icicle-object-action' and `icicle-anything'")
369 ;; (@file :file-name "icicles-doc2.el" :to "Icicles with Anything")
371 ;; (@file :file-name "icicles-doc2.el" :to "Multi-Completions")
372 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Multi-Completion Commands")
373 ;; (@file :file-name "icicles-doc2.el" :to "How Multi-Completions Work")
374 ;; (@file :file-name "icicles-doc2.el" :to "Multi-Completions vs `completing-read-multiple'")
376 ;; (@file :file-name "icicles-doc2.el" :to "Dot, Dot, Dot")
377 ;; (@file :file-name "icicles-doc2.el" :to "Fuzzy Completion")
378 ;; (@file :file-name "icicles-doc2.el" :to "Partial Completion")
379 ;; (@file :file-name "icicles-doc2.el" :to "Scatter-Match Completion")
380 ;; (@file :file-name "icicles-doc2.el" :to "Swank (Fuzzy Symbol) Completion")
381 ;; (@file :file-name "icicles-doc2.el" :to "Fuzzy-Match Completion")
382 ;; (@file :file-name "icicles-doc2.el" :to "Levenshtein Completion")
383 ;; (@file :file-name "icicles-doc2.el" :to "Jaro-Winkler Completion")
385 ;; (@file :file-name "icicles-doc2.el" :to "Completion in Other Buffers")
386 ;; (@file :file-name "icicles-doc2.el" :to "Dynamic Abbreviation")
387 ;; (@file :file-name "icicles-doc2.el" :to "BBDB Completion")
388 ;; (@file :file-name "icicles-doc2.el" :to "Thesaurus Lookup and Completion")
389 ;; (@file :file-name "icicles-doc2.el" :to "Completion in Comint Modes")
391 ;; (@file :file-name "icicles-doc2.el" :to "Customization and General Tips")
392 ;; (@file :file-name "icicles-doc2.el" :to "Using Icicles with Delete Selection Mode")
393 ;; (@file :file-name "icicles-doc2.el" :to "Icicles User Options and Faces")
395 ;; (@file :file-name "icicles-doc2.el" :to "File-Name and Directory-Name Completion Tips")
396 ;; (@file :file-name "icicles-doc2.el" :to "Key Bindings")
397 ;; (@file :file-name "icicles-doc2.el" :to "Global Bindings")
398 ;; (@file :file-name "icicles-doc2.el" :to "Icicles-Mode Bindings")
399 ;; (@file :file-name "icicles-doc2.el" :to "Minibuffer Bindings")
401 ;; (@file :file-name "icicles-doc2.el" :to "Customizing Key Bindings")
402 ;; (@file :file-name "icicles-doc2.el" :to "Customizing Global Bindings")
403 ;; (@file :file-name "icicles-doc2.el" :to "Customizing Icicle Mode Bindings")
404 ;; (@file :file-name "icicles-doc2.el" :to "Customizing Minibuffer Bindings")
406 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Redefines Some Standard Functions")
407 ;; (@file :file-name "icicles-doc2.el" :to "Programming with Fancy Candidates")
408 ;; (@file :file-name "icicles-doc2.el" :to "Programming Multi-Completions")
409 ;; (@file :file-name "icicles-doc2.el" :to "Variable icicle-list-use-nth-parts")
410 ;; (@file :file-name "icicles-doc2.el" :to "Variable icicle-candidate-properties-alist")
411 ;; (@file :file-name "icicles-doc2.el" :to "What You See Is Not What You Get")
413 ;; (@file :file-name "icicles-doc2.el" :to "Candidates with Text Properties")
414 ;; (@file :file-name "icicles-doc2.el" :to "Using Property icicle-special-candidate")
415 ;; (@file :file-name "icicles-doc2.el" :to "Applying Text Properties to a Candidate String")
417 ;; (@file :file-name "icicles-doc2.el" :to "Defining Icicles Commands (Including Multi-Commands)")
418 ;; (@file :file-name "icicles-doc2.el" :to "Nothing To It!")
419 ;; (@file :file-name "icicles-doc2.el" :to "Multi-Commands Are Easy To Define Too")
420 ;; (@file :file-name "icicles-doc2.el" :to "Are Users Dependent on Icicles To Use Multi-Commands?")
422 ;; (@file :file-name "icicles-doc2.el" :to "Defining Icicles Tripping Commands")
423 ;; (@file :file-name "icicles-doc2.el" :to "Defining Multiple-Choice Menus")
424 ;; (@file :file-name "icicles-doc2.el" :to "Defining Icicles Multi `M-x'")
425 ;; (@file :file-name "icicles-doc2.el" :to "How Multi `M-x' is Defined")
427 ;; (@file :file-name "icicles-doc2.el" :to "Defining Multi-Commands the Hard Way")
428 ;; (@file :file-name "icicles-doc2.el" :to "Global Filters")
429 ;; (@file :file-name "icicles-doc2.el" :to "Specifying Match Functions for Commands")
430 ;; (@file :file-name "icicles-doc2.el" :to "Defining Buffer-Text Completion for Comint Modes")
431 ;; (@file :file-name "icicles-doc2.el" :to "Note to Programmers")
432 ;; (@file :file-name "icicles-doc2.el" :to "La Petite Histoire")
433 ;; (@file :file-name "icicles-doc2.el" :to "Note on Non-`nil' `pop-up-frames' on MS Windows")
435 ;;(@* "Nutshell View of Icicles")
437 ;; Nutshell View of Icicles
438 ;; ------------------------
440 ;;(@* "README for NON-Readers")
441 ;; ** README for NON-Readers **
443 ;; Load library `icicles.el', turn on Icicle mode, and you're good to
444 ;; go. You can turn Icicle mode off or on at any time with command
445 ;; `icy-mode'. When you turn it off, you're back in vanilla Emacs.
447 ;; Beyond that, the most important thing to know about Icicles is
448 ;; that you can get help on Icicle mode during minibuffer input. You
449 ;; do that either by using item Help of the menu-bar Icicles menu or
450 ;; Minibuf menu, or by hitting `C-?' (`icicle-minibuffer-help').
452 ;; You now know enough to use Icicles. If you have doc-phobia or are
453 ;; easily overwhelmed by explanations, then *read no more* - just try
456 ;; If you want a little more explanation than the help page (`C-?'),
457 ;; then read the rest of section (@> "Nutshell View of Icicles"), but
458 ;; no more. It shows a sample of what you can do in Icicle mode.
460 ;; If you want to know more about Icicles by reading instead of just
461 ;; trying, then read beyond section (@> "Nutshell View of Icicles").
462 ;; There is a lot you can learn, but there is not much that you need
463 ;; to learn, to use Icicles usefully. Do not be afraid to get in and
464 ;; get wet. Above all, do not be overwhelmed by the doc - if it
467 ;; One good way to start is to explore menus `Icicles' and `Minibuf';
468 ;; you can access most Icicles features using these menus, without at
469 ;; the same time struggling to learn new key bindings. The `Icicles'
470 ;; menu is available all of the time (that is, whenever you are in
471 ;; Icicle mode), and the `Minibuf' menu is available whenever the
472 ;; minibuffer is active.
474 ;; During minibuffer input completion, you can also press Control and
475 ;; right-click (`C-mouse-3') on a completion candidate in buffer
476 ;; `*Completions*', and choose from a contextual popup menu,
479 ;; You can customize this menu. By default, submenu `This Candidate'
480 ;; has menu items that apply to the candidate you clicked to pop up
481 ;; the menu. The other submenus have items that apply to all
482 ;; candidates, candidates you have selected (the region in
483 ;; `*Completions*'), or candidates you have saved (marked).
485 ;; Altogether there are many menu items in the popup menu. Think of
486 ;; the menu as a learning device and a way to remind you of possible
487 ;; operations on completion candidates and the keys they are bound
488 ;; to. In this it is similar to the help you get when you use `C-?'
489 ;; in the minibuffer, but with the menu you can also act, not just be
492 ;; See Also: (@> "*Completions* Display").
497 ;; Icicles enhances minibuffer completion. It does so generally,
498 ;; throughout Emacs. It does this by improving the basic Emacs
499 ;; functions that read minibuffer input with completion:
500 ;; `completing-read', `read-file-name', and `read-from-minibuffer'.
502 ;; This means that Icicles affects every kind of minibuffer
503 ;; completion, not just buffers or files or commands or variables or
504 ;; faces or... Every kind. (You can even complete key sequences.)
505 ;; Lisp code need not call a special completion function to get this
506 ;; advantage - each call to `completing-read' etc. benefits
509 ;; Icicles has this effect only when you are in Icicle minor mode.
510 ;; Turn off Icicle mode and Emacs behaves as usual (vanilla).
512 ;; To best understand what Icicles offers you, you need to think a
513 ;; bit differently about minibuffer completion.
515 ;; During (vanilla) Emacs completion:
517 ;; v1. You type some input. Then you ask Emacs (`TAB') to look for a
518 ;; match of your input against the domain of input possibilities:
519 ;; the completion candidates. If a match is found, your input is
520 ;; completed and you hit `RET' to accept it (commit it as your
521 ;; final input). If there are several matches you type some more
522 ;; text and recomplete ... until there is only one match. Then
525 ;; v2. The goal here is to complete and then enter your input, as
526 ;; easily and rapidly as possible.
528 ;; v3. The process starts with a domain of possible inputs: the
529 ;; initial set of candidates. This domain can be realized
530 ;; intensionally, via a function, or more commonly extensionally,
531 ;; via an explicit set.
533 ;; v4. Sometimes completion is "lax" instead of "strict", meaning
534 ;; that you can input any text you like in the end (`RET'), but a
535 ;; set of candidates is still provided for the convenience of
536 ;; completion (`TAB').
538 ;; v5. When you hit `TAB' to complete, your current input in the
539 ;; minibuffer (the contents) filters the domain, narrowing it
540 ;; down to the set of matching candidates, which is shown in
541 ;; buffer `*Completions*'.
543 ;; See Also: (@> "Background on Vanilla Emacs Input Completion").
545 ;; For Icicles it is the completion *process* that is important, and
546 ;; this process can serve several goals. So instead of focusing on
547 ;; the goal of entering a final input (v2), let's consider the
548 ;; overall process: There is a set (domain) of possible candidates
549 ;; (v3) that you filter with your input (v1).
551 ;; If you edit your input and recomplete using `TAB', then the domain
552 ;; is refiltered to a different set of matching completion
553 ;; candidates. Each time you do this your input corresponds to a
554 ;; different set. The process of completion thus provides a great
555 ;; way to filter a set interactively.
557 ;; Now if all you do in the minibuffer at the end of the day is enter
558 ;; your final input (`RET'), then changing your input and
559 ;; recompleting (`TAB') is pretty much a waste of time, a detour.
560 ;; But if you can do more along the way, if you can make use of the
561 ;; current set of matches in some way, then the story is different.
563 ;; This is the key to understanding what Icicles offers. Think of
564 ;; minibuffer completion as a pattern-matching user interface, a
565 ;; general way to interact with sets of named objects.
567 ;; No doubt you have already used completion sometimes as more than
568 ;; just a means toward the end of inputting a value. Perhaps you
569 ;; have used `TAB' during file-name completion to take a look at the
570 ;; nearby directory structure, possibly even finishing with `C-g'
571 ;; instead of entering any file name definitively (`RET'). In that
572 ;; scenario, you are exploring the set of file-name candidates, using
573 ;; minibuffer completion as a help feature.
575 ;; Icicles binds different keys in the minibuffer keymaps to provide
576 ;; different ways to interact with the current set of matches
577 ;; (completion candidates). To exploit the possibilities of
578 ;; filtering a set dynamically by pattern matching, Icicles provides
579 ;; different features that work together.
581 ;; These are the most important Icicles features:
583 ;; i1. Incremental completion. By default, each change you make to
584 ;; your minibuffer input automatically rematches and recompletes
585 ;; it (v5). IOW, the set of current candidates is updated
586 ;; dynamically, incrementally. You can always see (in the
587 ;; `*Completions*' window) what your current input (the
588 ;; minibuffer content) matches. This is a help and exploration
591 ;; i2. Cycling and the current candidate. You can cycle among the
592 ;; current set of candidates (minibuffer matches). The current
593 ;; candidate is placed in the minibuffer as you do this, for
594 ;; possible editing. You can of course hit `RET' to commit the
595 ;; current candidate, edited or not, as your final input.
597 ;; i3. Help, multiple actions, alternative actions. But you can also
598 ;; instead hit a key to provide information (help) about the
599 ;; current candidate; hit a key to act on it (accept it as input
600 ;; but without ending the minibuffer); hit a key to perform some
601 ;; alternative action on it (without ending the minibuffer); and
602 ;; so on. Candidate help is perhaps the Icicles feature used
605 ;; i4. Multi-commands. A command that lets you act on a candidate
606 ;; without ending the minibuffer, so that you can thus act on
607 ;; several candidates, is called a "multi-command". Not every
608 ;; command is a multi-command.
610 ;; i5. Set operations. You can hit a key to act not on any
611 ;; particular matching candidate but on each of them individually
612 ;; or on all of them collectively. Among the collective set
613 ;; operations are union, intersection, difference/complementing,
614 ;; and saving for later reuse.
616 ;; i6. Progressive completion. Set intersection can take a couple of
617 ;; forms. The most useful is "progressive completion": use the
618 ;; current set of matching candidates as the domain for a
619 ;; recursive minibuffer. That is, start over and match different
620 ;; inputs against a subset of the original domain that was
621 ;; defined by the previous matching operation. This is analogous
622 ;; to piping `grep' outputs through additional `grep' filters.
624 ;; i7. More powerful matching. Using your input (minibuffer content)
625 ;; as a dynamic filter is very important in Icicles. In line
626 ;; with this, you can employ different matching methods. The
627 ;; most powerful is regexp matching (which includes substring
630 ;; i8. Candidate sorting. You can sort the current candidates on the
631 ;; fly in different ways, so that you can cycle them in different
632 ;; orders. The possible sort orders at any time depend on the
633 ;; context and type of candidates. You can define your own sort
636 ;; Most of these features are unique to Icicles. Others were
637 ;; original with Icicles but have since been copied by vanilla Emacs
638 ;; or other libraries. But only Icicles offers these features (and
639 ;; more) together, combining them cooperatively.
641 ;; Icicles is very general. It affects many aspects of minibuffer
642 ;; completion. As you learn to take advantage of its features it can
643 ;; change how you use Emacs. But Icicles also stays out of the way
644 ;; if you do not ask for its help. If you just use `TAB' completion
645 ;; and you use none of the keys bound specially during completion
646 ;; (for cycling, progressive completion, etc.), then you will hardly
649 ;; All Lisp code that uses minibuffer completion automatically takes
650 ;; advantage of Icicles. But some other libraries go beyond this by
651 ;; defining Icicles multi-commands or otherwise making some special
652 ;; use of Icicles features. None of these libraries are required in
653 ;; order to use Icicles, but they are recommended because of the
654 ;; synergy they provide. See (@> "Installing Icicles").
656 ;;(@* "Toggle Options on the Fly")
657 ;; ** Toggle Options on the Fly **
659 ;; There are many user options that affect the behavior of Icicles
660 ;; features. Some of these are Boolean (on/off) or allow for simple
661 ;; alternation or cycling of the possible values. Many of those
662 ;; options are associated with toggle commands that are bound to keys
663 ;; whenever the minibuffer is active, or at least active for
666 ;; Throughout this doc you will see references to such options and
667 ;; their toggles. For example: "You can toggle case-sensitivity at
668 ;; any time using `C-A' (that is, `C-S-a') in the minibuffer."
670 ;; The reason for making it so easy to change the values of these
671 ;; options on the fly is that different kinds of completion, in
672 ;; different contexts, can take advantage of different option values.
673 ;; Icicles completion is very general, and a single option value is
674 ;; not always optimal for all contexts.
676 ;; You will become acquainted with a few of these toggle keys and
677 ;; remember them, but you will forget others. What is important to
678 ;; point out here is that `C-?' (`icicle-minibuffer-help') is your
679 ;; friend in the minibuffer. During completion, the help it displays
680 ;; includes, near the top, a list of the toggle keys and the
681 ;; corresponding current values of their options.
683 ;; Whenever you use an Icicles toggle command, a momentary message
684 ;; shows you the new option value. So as an alternative to using
685 ;; `C-?' to see the current value of an option, you can just toggle
688 ;;(@* "Cycle Completion Candidates")
689 ;; ** Cycle Completion Candidates **
693 ;; That is, type "tool" and then hit the `next' key, which is often
694 ;; labeled "Page Down". Each time you hit `next', another match for
695 ;; your input (`tool') replaces it in the minibuffer:
697 ;; M-x ediff-toggle-use-toolbar next
698 ;; M-x scroll-bar-toolkit-scroll next
699 ;; M-x tool-bar-mode next
700 ;; M-x tooltip-mode next
701 ;; M-x ediff-toggle-use-toolbar ; Back to the beginning
703 ;; Keys `next' and `prior' ("Page Up") cycle among all of the
704 ;; commands that contain (match) the minibuffer input - `tool', in
705 ;; this case. Just hit `RET' (Return) when you get to the command
708 ;; (Note: The particular candidates shown here and in other examples
709 ;; might be different from what you see, depending on your version of
710 ;; Emacs and what other libraries you might have loaded.)
712 ;; You can use a regular expression, to narrow the field of matching
715 ;; M-x i s e . + c h a r next
716 ;; M-x isearch-delete-char next
717 ;; M-x isearch-other-control-char next
720 ;; Note that when you cycle, a one-line description of the current
721 ;; candidate is shown in the mode line (of buffer `*Completions*' if
722 ;; visible; otherwise of the current buffer). You can get more
723 ;; detailed info about individual candidates by holding the Control
724 ;; and Meta keys (e.g. `C-M-next') while you cycle - see
725 ;; (@> "*Completions* Display") and (@> "Help on Completion Candidates").
727 ;; Try cycling candidates for `C-h v' for instance, using `next'.
728 ;; Look for their descriptions in the mode line. Now try cycling
729 ;; using `C-M-next' - complete candidate help is shown in buffer
732 ;; See (@> "Cycling Completions") for more about cycling completion
735 ;;(@* "Display Completion Candidates")
736 ;; ** Display Completion Candidates **
738 ;; You can display all of the matches for the current minibuffer
739 ;; input, in the `*Completions*' buffer, using `S-TAB' (Shift TAB).
740 ;; So, for instance, `S-TAB' with `M-x ise.+char' in the minibuffer
741 ;; displays all commands whose names contain `ise' followed
742 ;; (somewhere) by `char'.
744 ;; See (@> "*Completions* Display") for more about using the
745 ;; `*Completions*' window.
747 ;;(@* "Prefix Completion and Apropos Completion")
748 ;; ** Prefix Completion and Apropos Completion **
750 ;; You can get the standard Emacs "prefix" completion, instead of the
751 ;; "apropos" completion just described, by using `TAB' instead of
752 ;; `S-TAB'. You can cycle prefix-completion candidates by using the
753 ;; `end' and `home' keys instead of `next' and `prior'. (All four of
754 ;; these keys are typically together in a central keypad to the right
755 ;; of the main keyboard.)
757 ;; You can also cycle candidates according to the current completion
758 ;; mode, prefix or apropos, using either the mouse wheel or the arrow
759 ;; keys `down' and `up'. These are all called the "modal" cycling
760 ;; keys because they respect the current completion mode.
762 ;; The current completion mode is determined by the last completion
763 ;; key you used, `TAB' or `S-TAB'. If you have not used either so
764 ;; far during the current minibuffer invocation, then the modal keys
765 ;; cycle according to the value of option
766 ;; `icicle-default-cycling-mode'. By default the option value is
767 ;; `prefix', which means that you can use `down', `up', or the mouse
768 ;; wheel to cycle prefix completions without needing to first hit
771 ;; The non-modal cycling keys, `next', `prior', `end', and `home'
772 ;; automatically set the completion mode and update the candidate
773 ;; completions. The modal cycling keys just cycle according to the
774 ;; current completion mode, whether it is apropos or prefix.
776 ;; To cycle using the mouse wheel, the mouse must not be over the
777 ;; `*Completions*' window; if it is, then the wheel scrolls that
778 ;; window instead of cycling candidates - see (@> "*Completions* Display").
780 ;; As an alternative to using `end' or `next', you can cycle
781 ;; candidates downward (forward) by just repeating the same
782 ;; completion key: `TAB' or `S-TAB'. For example:
784 ;; M-x tool TAB ; Display candidates with prefix `tool'
785 ;; M-x tool-bar-mode TAB
786 ;; M-x tooltip-mode TAB
787 ;; M-x tool-bar-mode ; Back to the beginning
791 ;; M-x tool S-TAB ; Display matching candidates
792 ;; M-x ediff-toggle-use-toolbar S-TAB
793 ;; M-x scroll-bar-toolkit-scroll S-TAB
794 ;; M-x tool-bar-mode S-TAB
795 ;; M-x tooltip-mode S-TAB
796 ;; M-x ediff-toggle-use-toolbar ; Back to the beginning
798 ;; Changing to a different completion key (`TAB' to `S-TAB' or vice
799 ;; versa) always switches completion type and completes, but you can
800 ;; then repeat that new completion key to cycle among the candidates.
802 ;; Note: In vanilla Emacs, repeating `TAB' scrolls the
803 ;; `*Completions*' window. In Icicles, you can use `C-v' to scroll
804 ;; `*Completions*' down and `M-v' to scroll up. You can also use the
805 ;; mouse wheel to scroll `*Completions*'.
807 ;; See (@> "Apropos Completions") for more about apropos and prefix
810 ;;(@* "Chains of Simple Match Patterns - Progressive Completion")
811 ;; ** Chains of Simple Match Patterns - Progressive Completion **
813 ;; To see which functions contain `char', `delete', and `back' in
814 ;; their names, in any order:
816 ;; C-h f c h a r S-TAB - Display all function names that contain
819 ;; M-* d e l e t e - Narrow that set of names to those that also
822 ;; M-* b a c k - Narrow the set of matching names further, to
823 ;; those that also contain `back'.
825 ;; This displays a list of functions like this in buffer
826 ;; `*Completions*' (your list might be somewhat different):
828 ;; backward-delete-char backward-delete-char-untabify
829 ;; delete-backward-char icicle-backward-delete-char-untabify
830 ;; icicle-delete-backward-char
831 ;; quail-conversion-backward-delete-char
833 ;; Since you are completing input to `C-h f', you can then cycle to a
834 ;; name using `next' and hit `RET', or click `mouse-2', to see the
835 ;; doc for that function. If, instead, you were completing input to
836 ;; `M-x', you could choose a command to execute. And so on.
838 ;; The thing to notice here is that you can use `M-*' to input chains
839 ;; of multiple simple regexps, to narrow down the set of completion
840 ;; candidates progressively. This is analogous to piping the result
841 ;; of `grep' to another `grep', and piping that result to another
844 ;; Here are a couple others to try (I'm always forgetting the order
845 ;; in these compound names):
847 ;; C-h f w i n d o w S-TAB M-* f r a m e
849 ;; C-h f w i n d o w S-TAB M-* b u f f e r
851 ;; As a shortcut, you can use just `S-SPC' instead of `S-TAB M-*'.
852 ;; See (@> "Progressive Completion") for more about progressive
853 ;; completion with `M-*'.
855 ;;(@* "Chip Away the Non-Elephant")
856 ;; ** Chip Away the Non-Elephant **
858 ;; There's a joke about a sculptor who, when asked how he created
859 ;; such a life-like statue of an elephant, said that he just chipped
860 ;; steadily away, removing marble that did not resemble an elephant.
861 ;; (Actually, Michelangelo supposedly said something similar.)
863 ;; Icicles lets you sculpt this way too - it is in fact a common
864 ;; Icicles usage idiom. There are two ways to say, "I do not want
865 ;; that" when it comes to possible completions:
867 ;; * The `delete' key or `S-mouse-2' says, "Get rid of this
868 ;; completion candidate."
870 ;; * `C-~' says "I want all possible completions *except* those that
871 ;; are the current matches." That is, "Remove all of this, and let
872 ;; me see what's left." `C-~' takes the complement of the current
873 ;; set of matches, using the initial set of possible candidates as
874 ;; the universe of discourse.
876 ;; In other words, instead of coming up with input that you want a
877 ;; completion to match, get rid of one or all of the candidates that
878 ;; do match. You can keep clicking `mouse-2' while holding Shift, or
879 ;; keep hitting `delete' (without Shift), to chip away at the set of
880 ;; possible completions. If there are several candidates in a row
881 ;; that you want to eliminate, just hold down the `delete' key until
884 ;; So that you can use `delete' this way to delete candidates one
885 ;; after the other, in order, the next candidate is chosen each time
886 ;; you delete one. This means that it becomes the current candidate
887 ;; in the minibuffer. You can, however, use `M-k' to clear the
888 ;; minibuffer or use `C-l' (bound to command
889 ;; `icicle-retrieve-previous-input') to clear the minibuffer and
890 ;; retrieve your last real input - see (@> "History Enhancements").
892 ;; `delete' works well to delete isolated candidates or groups of
893 ;; candidates that are in order (the current sort order), one right
894 ;; after the other, and you can of course combine it with positive
897 ;; Note: In Emacs releases prior to Emacs 22, `delete' has no real
898 ;; effect on file-name completion candidates (but it works fine on
899 ;; non file-name candidates). It removes them temporarily, but they
900 ;; are not really removed as possible candidates, so `TAB' and
901 ;; `S-TAB' will still show them as candidates.
903 ;; `C-~' is particularly handy in combination with progressive
904 ;; completion (`M-*') to narrow down a set of candidates, especially
905 ;; when you are not exactly sure what you are looking for. You can
906 ;; repeat `C-~' with different inputs to eliminate everything matched
907 ;; by each of them. In other words, this is a variable-size chisel,
908 ;; and you can use it to remove very large chips.
910 ;; For instance, suppose you are looking for a standard Emacs command
911 ;; involving buffers. You try `M-x buff S-TAB', but that shows
912 ;; zillions of matches. Suppose that you know you do not want a
913 ;; command in some 3rd-party package. You proceed to eliminate
914 ;; those, progressively, using something like this:
916 ;; M-* ediff C-~ ibuffer C-~ icicle C-~ Buffer-menu C-~ ps- C-~
917 ;; ido C-~ search-buffers C-~ moccur C-~ swbuff C-~
919 ;; And so on. That is, instead of using `M-*' repeatedly to specify
920 ;; multiple patterns that candidates must match, you use `C-~'
921 ;; repeatedly (after an initial `M-*'), to chip away candidates you
922 ;; do not want. You could, alternatively, hold down the `delete' key
923 ;; to eliminate each of these groups of command names. There are
924 ;; over 100 commands whose names begin with `ediff', however, so `M-*
925 ;; C-~' can be quicker in that case. It can definitely be quicker
926 ;; when apropos matching is involved. And you can of course combine
927 ;; the fine chiseling of `delete' with the variable-size chiseling of
930 ;; See (@> "Sets of Completion Candidates") for more about `C-~'.
932 ;;(@* "Choose Before You Act")
933 ;; ** Choose Before You Act **
935 ;; The opposite operation from chipping away at a set of candidates
936 ;; to refine it is to build up a set of candidates that you want to
937 ;; act on. This too is easy with Icicles. In some user interfaces,
938 ;; including Dired in Emacs, you can mark items in a checklist and
939 ;; then, when you've selected the items you want and verified the
940 ;; list, act on those that are selected. You might do this, for
941 ;; instance, if you were deleting some files. Icicles lets you
942 ;; interact with completion candidates this same way.
944 ;; You do this by building up a saved set of candidates, and then
945 ;; retrieving these saved candidates later. You can use the
946 ;; retrieved candidates just as you would any current set of
947 ;; candidates. One of the things you can do is act on all of them,
948 ;; that is, act on each, in turn. You do that with `C-!'.
950 ;; Of course, if you can use a regexp to match exactly the candidates
951 ;; you want to act on, then you need not bother to save and retrieve
952 ;; them, before acting on them: you can see them all alone in buffer
953 ;; `*Completions*'. Here's an exercise in choosing candidates to
954 ;; save with the mouse in `*Completions*':
956 ;; C-x C-f i c i TAB - Match all file names that begin with `ici'.
958 ;; Click `mouse-1' inside (or to the left of) `icicles-face.el'. [*]
959 ;; Click `mouse-3' inside (or to the right of) `icicles-mode.el'.
960 ;; Click `mouse-3' again, in the same place.
961 ;; Click `M-S-mouse-2' on each of `icicles.el' and `icicles-cmd1.el'.
963 ;; [* If you click `mouse-1' on a candidate and (starting with Emacs
964 ;; 22) `mouse-1-click-follows-link' is an integer, then you will need
965 ;; to hold the mouse button depressed longer than that many seconds,
966 ;; or else that candidate will simply by chosen. If the value is
967 ;; `t', then this will not work at all. Any other value presents no
968 ;; problem. (Personally, I use `nil'.)]
970 ;; The candidates that you selected - those between `icicles-face.el'
971 ;; and `icicles-mode.el', inclusive, plus `icicles.el' and
972 ;; `icicles-cmd1.el', are highlighted specially in buffer
973 ;; `*Completions*', and feedback in the minibuffer tells you that
974 ;; they were "saved", which you can also think of as "marked".
976 ;; Next, use `C-M-<'. This retrieves the set of saved candidates;
977 ;; that is, it replaces the current set of candidates with the saved
978 ;; candidates. If you now use `C-!', it applies the action to each
979 ;; candidate. In this case, the action is to visit the file (`C-x
982 ;; The combination of saving (marking) candidates and then retrieving
983 ;; only those you have saved is like progressive completion or
984 ;; chipping away: it is another way of progressively narrowing the
985 ;; set of candidates that you act on.
987 ;; See (@> "Choose All Completion Candidates") for more about `C-!'.
988 ;; See (@> "Sets of Completion Candidates") for more about saving and
989 ;; retrieving sets of candidates.
991 ;;(@* "Help on Completion Candidates")
992 ;; ** Help on Completion Candidates **
994 ;; Sometimes, you'd like to be able to ask for help about individual
995 ;; completion candidates while you're in the process of choosing one.
996 ;; That is the purpose of the Icicles `C-M-' key bindings available
997 ;; during completion.
999 ;; The simplest such bindings are `C-M-RET' and `C-M-mouse2'. They
1000 ;; each do the same thing: provide help on the current candidate.
1001 ;; You can use them during cycling or whenever you've narrowed the
1002 ;; choice down to a single candidate. You can check this way, before
1003 ;; you execute a command you're unsure of.
1005 ;; During completion, you can also cycle among the doc strings for
1006 ;; the candidates that match your input, by holding `C-M-' while
1007 ;; using any of the cycling keys:
1009 ;; - `C-M-down', `C-M-up', or `C-M-' + wheel - current-mode matching
1010 ;; - `C-M-next', `C-M-prior' - apropos matching
1011 ;; - `C-M-end', `C-M-home' - prefix matching
1013 ;; See (@> "Prefix Completion and Apropos Completion")).
1015 ;; This gives you a very useful on-the-fly apropos feature - use it
1016 ;; while you're completing a command, to check the difference between
1017 ;; several possible commands. Or just use it to browse doc strings,
1018 ;; to learn more about Emacs.
1020 ;; See (@> "Get Help on Candidates") for more about this.
1022 ;;(@* "Perform Multiple Operations in One Command")
1023 ;; ** Perform Multiple Operations in One Command **
1025 ;; C-x C-f i c i TAB - Find a file whose name starts with `ici'.
1027 ;; down (that is, the down arrow) ... until you get to candidate
1028 ;; `icicles-cmd1.el'
1030 ;; RET - Open file `icicles-cmd1.el'.
1032 ;; Nothing new here. Now try the same thing, but use `C-RET' instead
1033 ;; of `RET'. The command is not ended, and you can continue to
1034 ;; choose files to open:
1036 ;; C-x C-f i c i TAB - Find a file whose name starts with `ici'.
1038 ;; down ... until you get to `icicles-cmd1.el'
1040 ;; C-RET - Open file `icicles-cmd1.el'.
1042 ;; down ... until you get to `icicles-opt.el'
1044 ;; C-RET - Open file `icicles-opt.el'.
1046 ;; down ... until you get to `icicles.el'
1048 ;; RET - Open file `icicles.el' (end).
1050 ;; You just opened three files in a single command. Command
1051 ;; `icicle-file' (`C-x C-f') is an Icicles multi-command. You can
1052 ;; tell if a command is a multi-command when you execute it - if so,
1053 ;; the input prompt is prefixed by `+'. So, for example, when you
1054 ;; used `C-x C-f', the prompt was "+ File or directory:". Icicles
1055 ;; menu items that are multi-commands are also prefixed by `+'.
1057 ;; In addition to using `down' (or `end' or `next') and choosing
1058 ;; (acting on) candidates with `C-RET', you can combine these
1059 ;; operations by using `C-down' (or `C-next'): act on candidates in
1060 ;; succession. And, as mentioned, you can use `C-!' to act on all
1061 ;; candidates at once.
1063 ;; There are many possible uses of multi-commands. They all make use
1064 ;; of the same key bindings, which begin with `C-'. These keys are
1065 ;; analogous to the `C-M-' keys that provide help on completion
1068 ;; See (@> "Multi-Commands") for more information about Icicles
1071 ;;(@* "Perform Alternative Operations on the Fly")
1072 ;; ** Perform Alternative Operations on the Fly **
1074 ;; (If this section seems a bit weird or advanced to you, just skip
1075 ;; it the first time through.)
1077 ;; C-x C-f i c i TAB - Find a file whose name starts with `ici'.
1079 ;; down ... until you get to candidate `icicles-cmd1.el'
1081 ;; C-S-RET - You are prompted to choose a function to apply.
1083 ;; f i n d e TAB RET - Choose function `finder-commentary'.
1085 ;; down ... until you get to candidate `icicles-fn.el'
1087 ;; C-S-RET TAB TAB ... until you get to `find-file-read-only'.
1089 ;; RET - Visit file `icicles-fn.el' in read-only mode.
1091 ;; C-k TAB - Kill rest of input, then complete the prefix `ici'.
1093 ;; C-| b y t e - c TAB - Byte-compile all files matching `ici'.
1095 ;; TAB ... until you get to `icicles-doc1.el', then RET to visit.
1097 ;; What's going on? `C-S-RET' invokes an alternative action on the
1098 ;; current completion candidate. Here, you do this, in turn, for the
1099 ;; file-name candidates `icicles-cmd1.el' and `icicles-fn.el'. `C-|'
1100 ;; invokes an alternative action on *all* of the current completion
1101 ;; candidates. Here, you do this for all file names that begin with
1102 ;; `ici'. Finally, you cycle to `icicles-doc1.el' and hit RET to
1105 ;; The alternative action for `C-x C-f' (command `icicle-file')
1106 ;; prompts you for a function to apply to the current completion
1107 ;; candidate (for `C-S-RET') or to all candidates (for `C-|').
1109 ;; Here, you choose function `finder-commentary' to visit the
1110 ;; Commentary of file `icicles-cmd1.el', function
1111 ;; `find-file-read-only' to visit file `icicles-fn.el' in read-only
1112 ;; mode, and function `byte-compile-file' to byte-compile all files
1113 ;; whose names start with `ici'.
1115 ;; You can use `C-u' with a function you choose, to pretty-print its
1116 ;; result (in buffer `*Pp Eval Output*', if too large for the echo
1117 ;; area). That is useful for functions that have no side effects.
1118 ;; For this to work, use `C-RET', not `RET', to choose the function.
1120 ;; Each command defines its own alternative action, but many Icicles
1121 ;; commands have the behavior described here for `icicle-file': their
1122 ;; alternative action is to let you apply any function that is
1123 ;; appropriate for the given type of candidate (here, file names).
1125 ;; You can even enter an appropriate lambda expression, instead of
1126 ;; completing to one of the function candidates provided. For
1127 ;; example, you could use `C-|' with the following input to copy all
1128 ;; Icicles libraries to directory `ICICLES':
1130 ;; (lambda (f) (copy-file f "ICICLES" t))
1132 ;; Note that function `copy-file' is effectively curried here, to
1133 ;; create a function of a single argument on the fly.
1135 ;; See Also: (@> "Alternative Actions").
1137 ;;(@* "Completion Status Indicators")
1138 ;; ** Completion Status Indicators **
1140 ;; You can always know whether completion is possible when you are
1141 ;; inputting text in the minibuffer and, if so, what kind of
1142 ;; completion. Completion status is indicated in two places: (1) at
1143 ;; the beginning of the minibuffer prompt and (2) in the `Icy'
1144 ;; minor-mode lighter in the mode line. The second is optional,
1145 ;; controlled by option `icicle-highlight-lighter-flag'.
1147 ;; Whenever input completion is available, the prompt is prefixed by
1148 ;; `.' or `+', indicating simple or multi-command completion,
1149 ;; respectively. If completion is strict (your input must match one
1150 ;; of the candidates), then this character is enclosed in a box. If
1151 ;; completion is lax (permissive), there is no box.
1153 ;; The `Icy' minor-mode lighter text is highlighted red during
1154 ;; completion. `+' is added to the lighter (`Icy+') for
1155 ;; multi-command completion, and the lighter is boxed for strict
1156 ;; completion. When minibuffer input is read without completion, the
1157 ;; lighter is not highlighted in any way.
1159 ;; If the list of candidates shown in `*Completions*' is truncated
1160 ;; (because of option `icicle-max-candidates'), then the lighter text
1161 ;; is suffixed by `...'. So if you see `...' then you know that if
1162 ;; you increase `icicle-max-candidates' (e.g. by using `C-x #' during
1163 ;; completion) then more candidates will be available. See
1164 ;; (@file :file-name "icicles-doc2.el" :to "Customization and General Tips")
1165 ;; for info about `C-x #' and option `icicle-max-candidates'.
1167 ;; In addition, the lighter text (with or without `+' and `...') is
1168 ;; `Icy' if completion is case-sensitive and `ICY' if not. You can
1169 ;; toggle case-sensitivity at any time using `C-A' (that is, `C-S-a')
1170 ;; in the minibuffer.
1172 ;; The faces used for this highlighting in the minibuffer and the
1173 ;; mode line are `icicle-completion',
1174 ;; `icicle-multi-command-completion', and
1175 ;; `icicle-mustmatch-completion'. Consult their doc strings for more
1176 ;; information. These faces are combined to produce the various
1177 ;; highlighting effects - keep that in mind if you customize them.
1179 ;; When you are inputting, keep an eye out for this highlighting. If
1180 ;; you do not see it when you are prompted for input, it means that
1181 ;; input completion is not available. This in turn means that
1182 ;; `S-TAB' is available, not for input completion, but for key
1183 ;; completion - see (@> "Key Completion").
1185 ;;(@* "Icicles Search")
1186 ;; ** Icicles Search **
1188 ;; Icicles provides a unique way of searching incrementally. Command
1189 ;; `icicle-search' (`C-c `') is a multi-command. In this case, the
1190 ;; completion candidates are the buffer occurrences that match a
1191 ;; regexp that you input. `C-RET' visits a search-hit candidate, and
1192 ;; `C-next' visits a candidate and prepares to visit the next in
1193 ;; succession. If you visit file `icicles-doc1.el', which contains
1194 ;; the text you are reading now, do this in that buffer:
1198 ;; Search within contexts (regexp): . * r e c u r s i v e . * RET
1200 ;; Search within contexts defined by the regexp `.*recursive.*'.
1202 ;; Choose an occurrence: S-TAB - Show the search hits, in buffer
1203 ;; `*Completions*' (optional).
1205 ;; C-next ... - Cycle among the search hits, navigating to them in
1208 ;; S-TAB next ... - Cycle among the search hits without navigating.
1210 ;; next ... C-RET next ... C-RET - Cycle to particular hits and
1211 ;; visit (only) those hits.
1213 ;; next ... RET - Cycle to a hit and stay there (end).
1218 ;; Search within contexts (regexp): M-p RET
1220 ;; Search again within `.*recursive.*' (`M-p' uses input history).
1222 ;; S-TAB e d i t C-next ... - Search for the substring `edit'
1223 ;; within all search hits for `.*recursive.*'. Cycle among the
1224 ;; matches. The substring `edit' is highlighted inside the
1225 ;; (differently) highlighted `.*recursive.*' hits. Whatever you
1226 ;; type filters the initial set of hits.
1228 ;; M-k - Empty the minibuffer, then S-TAB. All `.*recursive.*'
1229 ;; hits are restored as candidates. Again, whatever your input is
1230 ;; (nothing, now), the set of candidates is dynamically updated to
1233 ;; t \ w + n S-TAB C-next ... - Search for matches of the regexp
1234 ;; `t\w+n' within all search hits for `.*recursive.*' - that is,
1235 ;; `t' followed by at least one other word character, followed by
1236 ;; `n'. Whatever the regexp `t\w+n' matches (`thin', `then',
1237 ;; `traighten', `tion') is highlighted inside each candidate.
1239 ;; RET - Stop searching at the current candidate (end).
1241 ;; Now try the same thing, but first use `C-^' in the minibuffer
1242 ;; (e.g. after you enter `.*recursive.*'). That toggles an Icicles
1243 ;; search option for highlighting your input matches. The behavior
1244 ;; is the same as before, except that all matches to your input are
1245 ;; highlighted at once, not just the current match. And not only the
1246 ;; exact match is highlighted, but the longest common match among all
1247 ;; input matches is highlighted: If your input is `edi', then `edi'
1248 ;; is highlighted (there is no longer common match), but if you input
1249 ;; the four characters `e d i t', then ``abort-recursive-edit'' is
1250 ;; highlighted. You can use `C-^' at any time during searching to
1251 ;; change the highlighting behavior.
1253 ;; Now try the same thing, but first select some text. The search is
1254 ;; confined to the active region (selection) instead of the entire
1257 ;; Now try the same thing (without a region), but use a negative
1258 ;; prefix argument such as `C--' with `C-c `'. This time, after you
1259 ;; input the regexp to search for, you are prompted for one or more
1260 ;; files to search. This too is multi-command input: you can input
1261 ;; any number of file names, using completion.
1265 ;; Search within contexts (regexp): . * r e c u r s i v e . * RET
1267 ;; Search within contexts defined by the regexp `.*recursive.*'.
1269 ;; Choose file (`RET' when done): i c i TAB - Choose among file
1270 ;; candidates that begin with `ici' (shown in `*Completions*').
1272 ;; C-! - Choose all matching file names: icicles-cmd1.el,
1273 ;; icicles-cmd2.el, icicles-doc1.el, icicles-doc2.el,
1274 ;; icicles-face.el, icicles-fn.el, icicles-mac.el, icicles-mcmd.el,
1275 ;; icicles-mode.el, icicles-opt.el, icicles-var.el, and icicles.el.
1277 ;; Choose an occurrence: S-TAB - Show the hits in buffer
1278 ;; `*Completions*' (optional).
1280 ;; C-next ... - Cycle among the search hits in all chosen
1283 ;; Just as you can choose particular search hits to visit, using
1284 ;; `C-RET', so you can use `C-RET' to choose particular files (whose
1285 ;; names match the input, e.g. ici) to search. Just as you can visit
1286 ;; search hits in order, using `C-next' (or `C-end' or `C-down'), so
1287 ;; you can use `C-next' (or `C-end' or `C-down') to choose files to
1288 ;; visit, one after the other.
1290 ;; When you input the initial regexp (`.*recursive.*' in the example
1291 ;; above) to `icicle-search', you can use completion to retrieve a
1292 ;; regexp that you entered previously.
1294 ;; You can use `C-`' in the minibuffer to toggle escaping of regexp
1295 ;; special characters. Use that if you want to find a literal string
1296 ;; - for example, if you want to search for the string `form.' and
1297 ;; not text that matches the regexp `form.' (`form' followed by any
1298 ;; character except newline). If you use `C-`' during Icicles
1299 ;; search, start the search over again for the toggle to take effect.
1301 ;; Oh, can you use progressive completion with Icicles search? Sure.
1302 ;; And chipping away the non-elephant (complementing)? Yep. Try
1303 ;; using vanilla Emacs incremental search to find a line that
1304 ;; contains a given set of words in any (unknown) order and that also
1305 ;; does not contain another given set of words. No can do. But that
1306 ;; is simple using Icicles search. (Yes, you can do it using
1309 ;; And while you're searching, you can perform on-the-fly, on-demand
1310 ;; replacement. You tell Emacs whenever you want to replace text,
1311 ;; instead of replying to an endless litany of `query-replace'
1312 ;; queries. Unlike `query-replace', you need not visit search
1313 ;; matches successively or exhaustively. You can visit and replace
1314 ;; selected matches in any order. And you can even change the order
1315 ;; (using `C-,') in which search hits appear and are navigated
1318 ;; In addition to Icicles search (which is also incremental), Icicles
1319 ;; offers some enhancements to the standard Emacs incremental search,
1322 ;; * You can reuse a previous Isearch search string, choosing it
1323 ;; using Icicles completion. Hit `M-o' during Isearch, type some
1324 ;; input to complete against the search history, and hit `RET' or
1325 ;; click `mouse-2' to choose a string and continue Isearch with it.
1327 ;; * You can start Icicles search from Isearch. The current Isearch
1328 ;; search string becomes the starting point for the Icicles search
1329 ;; regexp. You can edit it or type something different. And you
1330 ;; can complete what you type against the Isearch regexp history.
1331 ;; You can optionally define search contexts with a regexp and then
1332 ;; search for the Isearch string within those contexts.
1336 ;; * (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
1337 ;; for more about searching with Icicles.
1339 ;; * (@file :file-name "icicles-doc2.el" :to "Search and Replace")
1340 ;; for information about replacing selected search hits.
1342 ;; * (@> "Expanded-Common-Match Completion") for more about Icicles
1343 ;; expansion of your input to a common match among all candidates.
1345 ;; * (@> "Isearch Enhancements")
1347 ;; * (@> "Using Completion to Insert Previous Inputs: `M-o'") for
1348 ;; more about `M-o' - you can use it anywhere to complete against
1351 ;;(@* "Complete Key Sequences Too")
1352 ;; ** Complete Key Sequences Too **
1354 ;; Try `S-TAB' at the top level (without first invoking a command
1355 ;; that reads input). Icicles presents all of the possible keys and
1356 ;; their bindings in the current context - for completion. For
1357 ;; example, if you are in Dired mode, the completion candidates
1358 ;; include all key sequences in the global map and the Dired-mode map
1359 ;; (and any current minor-mode maps, such as Icicle mode).
1361 ;; (The documentation always refers to the key that performs key
1362 ;; completion as `S-TAB'. Actually, it is `S-TAB' only by default.
1363 ;; You can customize it, using option `icicle-key-complete-keys'.)
1365 ;; You can then type part of a key name or a command name, and hit
1366 ;; `S-TAB' again to apropos-complete your input. You can navigate
1367 ;; down the key-sequence hierarchy by completing a key sequence piece
1370 ;; S-TAB to see the available keys at top level
1372 ;; Click (using `mouse-2') candidate `C-x = ...', to see the keys
1373 ;; that start with `C-x'
1375 ;; Click `r = ...', to see the keys that start with `C-x r'
1377 ;; Click `b = bookmark-jump', to invoke that command and visit a
1380 ;; Whenever you're completing a prefix key, such as `C-x', you can
1381 ;; click `..' to navigate back up the key-sequence hierarchy. For
1382 ;; instance, if you are completing `C-x p', click `..' to go back to
1383 ;; completing `C-x', and then click `..' to go back to the top level.
1385 ;; The available keys at any level include the following important
1386 ;; keys, which means that you can use Icicles key completion to do
1387 ;; almost anything in Emacs:
1389 ;; * `M-x' - Execute an arbitrary command.
1390 ;; `M-x' is treated as `ESC-x', so complete first `ESC = ...',
1391 ;; then `x = icicle-execute-extended-command'.
1393 ;; * `M-:' - Evaluate any Emacs-Lisp expression.
1394 ;; If command remapping is available (Emacs 22 or later), and if
1395 ;; option `icicle-top-level-key-bindings' remaps `eval-expression'
1396 ;; to `icicle-pp-eval-expression' (which it does, by default), then
1397 ;; complete first `remapped = ...', then `eval-expression =
1398 ;; icicle-pp-eval-expression'. Otherwise, complete first `ESC =
1399 ;; ...', then `: = eval-expression'.
1401 ;; In Icicles, `M-:' gives you a quick pop-up mode for evaluating a
1402 ;; Lisp sexp. Most of the normal Emacs-Lisp mode bindings are in
1403 ;; effect, except that `RET' evaluates the minibuffer contents and
1404 ;; pretty-prints the result. You can also use it with a prefix arg
1405 ;; (`C-u M-:') to insert the result of such an on-the-fly Lisp
1406 ;; evaluation into the current buffer (including the minibuffer).
1408 ;; * `menu-bar = ...' - Invoke any menu-bar menu.
1409 ;; Continue completing, to navigate the entire menu hierarchy.
1411 ;; You can start directly with a key prefix, and then hit `S-TAB' to
1412 ;; complete it - you need not start with `S-TAB'. You can use
1413 ;; Icicles key completion to learn key bindings - `C-M-mouse-2'
1414 ;; displays help on any key.
1416 ;; Instead of clicking a completion candidate with `mouse-2', you can
1417 ;; of course type part of the key name or command name, and then
1418 ;; complete the name and enter it. Gotcha: `S-TAB' uses apropos
1419 ;; completion, by default, so remember that typing `.' matches any
1420 ;; character (except a newline). To match only `..' (to go up a
1421 ;; level), either use prefix completion (`TAB') or escape the regexp
1422 ;; special character: `\.\.' (or use `^\.'). Or cycle to it.
1424 ;; See (@> "Key Completion") for more about Icicles key completion.
1426 ;;(@* "Available for Almost Any Input")
1427 ;; ** Available for Almost Any Input **
1429 ;; All of this works not only for the input of commands, with `M-x',
1430 ;; but for the input of nearly anything. For instance, you can use
1431 ;; `C-x b' (`switch-to-buffer') and cycle among buffer names. Or use
1432 ;; `C-h v' (`describe-variable') and cycle among variable names. It
1433 ;; works whenever a command reads input with completion.
1435 ;; Whenever you're in Icicle mode, you see "Icy" in the mode-line.
1437 ;;(@* "Component Icicles Libraries")
1438 ;; ** Component Icicles Libraries **
1440 ;; Icicles is composed of the following libraries. When you load the
1441 ;; driver library, `icicles.el', the others are all loaded
1444 ;; `icicles.el' - driver library
1445 ;; `icicles-doc1.el' - first part of the doc (this!)
1446 ;; `icicles-doc2.el' - second part of the doc
1447 ;; `icicles-cmd1.el' - top-level commands (part 1)
1448 ;; `icicles-cmd2.el' - top-level commands (part 2)
1449 ;; `icicles-face.el' - faces
1450 ;; `icicles-fn.el' - non-interactive functions
1451 ;; `icicles-mac.el' - macros
1452 ;; `icicles-mcmd.el' - minibuffer commands
1453 ;; `icicles-mode.el' - Icicle mode definition
1454 ;; `icicles-opt.el' - user options (variables)
1455 ;; `icicles-var.el' - internal variables
1457 ;; Libraries `icicles-doc1.el' and `icicles-doc2.el' are not really
1458 ;; libraries. They contain only comments, with the Icicles doc.
1460 ;; Library `lacarte.el' is not part of Icicles, but it is especially
1461 ;; useful when used with Icicles.
1463 ;;(@* "If You Are an Emacs-Lisp Programmer")
1464 ;; ** If You Are an Emacs-Lisp Programmer **
1466 ;; If you are an Emacs-Lisp programmer, this is the no-brainer,
1467 ;; nutshell view of how to take advantage of Icicles in your own code
1468 ;; that calls `completing-read' or `read-file-name':
1470 ;; Add this line to your library: (require 'icicles nil t)
1472 ;; That is really all you need to do. And there is no consequence if
1473 ;; users do not have Icicles (no load error is raised, because of the
1474 ;; non-`nil' third argument). In other words, there is no reason not
1475 ;; to add this soft `require', unless your library somehow conflicts
1476 ;; with Icicles features. (Even then, users will not be affected
1477 ;; unless they turn on Icicle mode.)
1480 ;; For more (and there is a lot more), read on...
1482 ;;(@* "Inserting Text Found Near the Cursor")
1484 ;; Inserting Text Found Near the Cursor
1485 ;; ------------------------------------
1487 ;; Most of Icicles is about completing text that you type in the
1488 ;; minibuffer against some set of possible completion candidates.
1489 ;; This feature is not. It is related only in the sense that it is
1490 ;; also about inputting text that is already available elsewhere.
1492 ;; Some Emacs commands provide, as the default value for minibuffer
1493 ;; input, a word or other text at the cursor position (aka "point").
1494 ;; You can insert this default value in the minibuffer with `M-n'.
1495 ;; Icicles option `icicle-default-value' can be used to automatically
1496 ;; insert the default value into the minibuffer as an initial value,
1497 ;; if you prefer that optional behavior (I do; many people do not).
1500 ;;(@* "FFAP: Find File At Point")
1501 ;; ** FFAP: Find File At Point **
1503 ;; Sometimes you would like to use the text at the cursor, but the
1504 ;; command asking for input does not let you retrieve that text as
1505 ;; the default value. For example, if the text at point is a file
1506 ;; name, you might like to use it with `C-x C-f' to open that file.
1507 ;; Or, if the text is a URL, you might want to visit it using a Web
1510 ;; Some Emacs-Lisp libraries, such as `ffap.el', have as their
1511 ;; specific purpose to help you do this. "Ffap" stands for
1512 ;; `find-file-at-point', the main command in that library. It tries
1513 ;; to interpret the text at point and "do the right thing" with it:
1514 ;; visit a file, open a URL in a Web browser, and so on.
1516 ;; If you like, you can use library `ffap.el' with Icicles. All
1517 ;; Icicles features are then available during file-name and URL
1518 ;; completion. And if you like `ffap.el', you might also like to try
1519 ;; my extension library `ffap-.el'. However, if you use ffap with
1520 ;; Icicles, you might not want to use the ffap key bindings,
1521 ;; preferring the Icicles bindings or the standard Emacs bindings for
1522 ;; keys such as `C-x C-f'. (In that case, do not call function
1523 ;; `ffap-bindings'.)
1525 ;; Icicles provides a couple of simple ways to take advantage of
1526 ;; `ffap-guesser', which is the ffap function that guesses which
1527 ;; string at the cursor position you want to grab, without
1528 ;; sacrificing any key bindings to ffap. One way is to use `M-.'
1529 ;; (command `icicle-insert-string-at-point') at any time in the
1530 ;; minibuffer. It grabs text at or near the cursor and yanks it into
1531 ;; the minibuffer. One of the alternative types of thing it grabs is
1532 ;; whatever text `ffap-guesser' guesses.
1534 ;;(@* "Proxy Candidates, `M-.'")
1535 ;; ** Proxy Candidates, `M-.' **)
1537 ;;;; Another way is to use one of the proxy completion candidates
1538 ;; `*point file name*' or `*mouse-2 file name*' whenever Emacs asks
1539 ;; you to input a file name (provided option
1540 ;; `icicle-add-proxy-candidates-flag' is non-`nil' - toggle with
1541 ;; `C-M-_'). The former picks up the file name at point, just like
1542 ;; `M-.'. The latter lets you click a file name anywhere with
1543 ;; `mouse-2' to pick up the name.
1545 ;; Using `M-.' or a proxy candidate on demand, instead of binding
1546 ;; keys to ffap commands, lets you control which buffer text you use
1547 ;; as minibuffer input and how that text should be interpreted (file
1548 ;; name, URL, and so on). You can change the behavior of `M-.'
1549 ;; (which string-inserting functions are used) by customizing user
1550 ;; option `icicle-thing-at-point-functions'.
1552 ;;(@* "Repeat `M-.' To Grab More or Different")
1553 ;; ** Repeat `M-.' To Grab More or Different **
1555 ;; Actually, `M-.' acts differently if you use it successively.
1556 ;; Successive uses of `M-.' grab and insert either 1) alternative
1557 ;; bits of text (different text "things") or 2) successive bits of
1558 ;; text. The default behavior is #1, but you can change this choice
1559 ;; by customizing option `icicle-default-thing-insertion' (setting it
1560 ;; to `more-of-the-same', instead of `alternatives').
1562 ;; As an example of grabbing successive bits of text (#2), suppose
1563 ;; that the cursor is at the beginning of the word "use" in the
1564 ;; previous paragraph. Then, during minibuffer input, suppose that
1565 ;; you use `M-. M-. M-.'. Each time you hit `M-.', another word is
1566 ;; inserted in the minibuffer:
1570 ;; use it successively
1573 ;; The rest of this section is a bit technical, so you might want to
1574 ;; skip it if you are reading the Icicles doc for the first time. It
1575 ;; details the behavior and definitions of options
1576 ;; `icicle-default-thing-insertion' and
1577 ;; `icicle-thing-at-point-functions', and how to temporarily override
1578 ;; those settings interactively.
1580 ;; Option `icicle-thing-at-point-functions' controls which text at or
1581 ;; near the cursor `M-.' inserts into the minibuffer. It is a cons
1582 ;; cell, that is, an ordered pair:
1584 ;; * The car (first part) is a list of functions that grab different
1585 ;; kinds of strings at or near point (#1, above). Any number of
1586 ;; functions can be used. They are used in sequence by `M-.'. I
1587 ;; recommend that you also use library `thingatpt+.el', so that
1588 ;; `M-.' can take advantage of the string-grabbing functions it
1591 ;; * The cdr (second part) is a function that advances point one text
1592 ;; thing (#2, above). Each time command `M-.' is used
1593 ;; successively, this is called to grab more things of text (of the
1594 ;; same kind). The default function grabs successive words.
1596 ;; If either the car or cdr is empty, then the other alone determines
1597 ;; the behavior of `M-.'. Otherwise, option
1598 ;; `icicle-default-thing-insertion' determines whether the car or the
1599 ;; cdr is used by `M-.'.
1601 ;; For example, if the value of `icicle-default-thing-insertion' is
1602 ;; `alternatives' (the default value), then repeated use of `M-.'
1603 ;; inserts a different kind of thing at point each time. By default,
1604 ;; these are the thing types, in order:
1606 ;; `non-nil-symbol-name-nearest-point' (*) or `symbol-at-point'
1607 ;; `word-nearest-point' (*) or the word at point
1608 ;; `list-nearest-point-as-string' (*), the first enclosing list
1609 ;; `list-nearest-point-as-string' (*), the second enclosing list
1610 ;; `list-nearest-point-as-string' (*), the third enclosing list
1612 ;; `thing-at-point-url-at-point'
1614 ;; The alternatives marked with an asterisk (*) are available only if
1615 ;; you use library `thingatpt+.el'. Alternative `ffap-guesser' is
1616 ;; used only if you use library `ffap.el'.
1618 ;; The first alternative inserts text that has the syntax of an
1619 ;; Emacs-Lisp symbol name. In practice, this can also be a file
1620 ;; name or a URL - it can include characters such as -, /, +, ., :,
1623 ;; The second alternative inserts a word, which includes letters, ',
1626 ;; The third, fourth, and fifth alternatives insert a (non-`nil')
1627 ;; list that is around point - three different enclosing levels.
1629 ;; The sixth alternative inserts whatever `ffap-guesser' returns: a
1630 ;; file name or a URL at point.
1632 ;; The seventh alternative inserts a URL at point, adding prefix
1633 ;; "http://" if needed.
1635 ;; This means that you can quickly pick up a symbol name, a list, a
1636 ;; file name, or a URL at point.
1638 ;; If you use library `thingatpt+.el' then the first two alternatives
1639 ;; pick up the symbol or word nearest point - the cursor need not be
1640 ;; exactly on the symbol or word.
1642 ;; You can of course add to or replace any of the alternatives that
1643 ;; are provided by default.
1645 ;; If you set `icicle-default-thing-insertion' to `more-of-the-same'
1646 ;; instead of `alternatives', then repeated use of `M-.' inserts
1647 ;; successive words into the minibuffer, as shown in the example
1650 ;; You need not make a final choice once and for all between
1651 ;; `alternatives' and `more-of-the-same'. You can also make an
1652 ;; interactive choice by using a prefix argument (`C-u') at any time
1653 ;; to override the value of `icicle-default-thing-insertion'. If you
1654 ;; use plain `C-u', then `M-.' inserts alternative strings. If you
1655 ;; use a numeric prefix argument N (not just plain `C-u'), then it is
1656 ;; the same as using `M-.' N times with `more-of-the-same' as the
1657 ;; value of `icicle-default-thing-insertion'.
1659 ;; And, if the numeric argument is negative, then text is grabbed to
1660 ;; the left of the cursor, instead of to the right. In the example
1661 ;; above, if you used `M-- M-. M-. M-.', then the successive
1662 ;; insertions would be as follows:
1666 ;; differently if you
1669 ;; If you used `M--3 M-.', then you would immediately insert
1670 ;; `differently if you'.
1672 ;;(@* "Resolve File Names")
1673 ;; ** Resolve File Names **
1675 ;; Finally, something that is not directly related to the topic of
1676 ;; this page, but fits here as well as anywhere: you can use `C-x
1677 ;; C-f' in the minibuffer to resolve a file name to its true,
1678 ;; absolute name. Yes, that's the same key that is bound at top
1679 ;; level to `icicle-file' or `find-file' or whatever, but this is
1680 ;; about its use when you are already in the minibuffer.
1682 ;; `C-x C-f' (`icicle-resolve-file-name'), replaces a file name at or
1683 ;; near point (in the minibuffer) with its true, absolute name. (For
1684 ;; it to work near but not precisely at point, you need library
1685 ;; `thingatpt+.el'.) If the file name is relative, it first converts
1686 ;; it to absolute (using the default directory). It then converts an
1687 ;; absolute name that is a symbolic link to its target name. You can
1688 ;; use this anytime in the minibuffer, and you can use it on multiple
1689 ;; parts of the same minibuffer input (e.g. shell command arguments).
1690 ;; (This feature does not work for Emacs 20 or 21.)
1694 ;; * (@> "Inserting a Regexp from a Variable or Register") for
1695 ;; information on inserting text saved in a variable or register.
1697 ;; * (@> "Moving Between the Minibuffer and Other Buffers") for
1698 ;; another way to insert buffer text in the minibuffer.
1700 ;;(@* "Background on Vanilla Emacs Input Completion")
1702 ;; Background on Vanilla Emacs Input Completion
1703 ;; --------------------------------------------
1705 ;; This section reviews standard Emacs behavior regarding input
1706 ;; completion. It does not describe any Icicles completion features.
1707 ;; See also (@> "README").
1709 ;; When you are prompted in the minibuffer to enter something, you
1710 ;; are sometimes presented with a default value. This might be
1711 ;; automatically inserted after the prompt, initially. If not, you
1712 ;; can retrieve the default value yourself, using `M-n' (Emacs 21 or
1715 ;; Often, there is more than one reasonable default value that might
1716 ;; make sense. Depending on what you're being asked to enter, these
1717 ;; "candidate default values" might be command names, buffer names,
1718 ;; existing file names, variable names, and so on.
1720 ;; For most Emacs functions that prompt you for input, the person who
1721 ;; wrote the function decided on the reasonable set of default
1722 ;; values, and passed these to an "input-completing function" such as
1723 ;; `completing-read' or `read-file-name', which prompts you and reads
1724 ;; your input. The programmer also decided whether you will be
1725 ;; *required* to pick one of the default values or you will be free
1726 ;; to enter something else. The programmer might also have told the
1727 ;; input-completing function to require that your input pass some
1728 ;; special test (predicate).
1730 ;; Be aware that standard Emacs terminology does not refer to such a
1731 ;; set of default values as "default values"; they are called
1732 ;; "completions". By "default value", standard Emacs terminology
1733 ;; means only the values that you can access via `M-n'. Icicles
1734 ;; refers to all such potential inputs indifferently as "default
1735 ;; values", "completions", "completion candidates", and "candidates".
1736 ;; Whenever completion is not requiring you to pick one of the
1737 ;; available candidates, they are effectively only default choices.
1739 ;; So, how do you get access to the default values that the
1740 ;; programmer has made available to you, in order to choose one? You
1741 ;; hit certain keys to complete the current contents of the
1742 ;; minibuffer (excluding the prompt). This current, partial input is
1743 ;; considered as a prefix of one of the default values, and it is
1744 ;; completed in the minibuffer to the entire default value
1747 ;; Keys `TAB', `RET' (Return), and `SPC' (Space) perform different
1748 ;; degrees of this "prefix completion" in standard Emacs. If you
1749 ;; type a prefix of one of the available default values, you can
1750 ;; complete the value this way in the minibuffer, and then enter
1751 ;; (commit) it, using `RET'.
1753 ;; But if your partial input matches the prefix of more than one
1754 ;; default value, then completion pops up the list of all matching
1755 ;; completions for you to choose from (in buffer `*Completions*').
1756 ;; You choose a candidate by clicking it with `mouse-2' or placing
1757 ;; the cursor on it and hitting `RET'.
1759 ;; Because this is the way you access the default values supplied to
1760 ;; an input-completing function, I call those values
1761 ;; "prefix-completion candidates". If there is no partial input yet
1762 ;; (empty minibuffer), then the entire list of default values
1763 ;; supplied to the input-completing function appears in the pop-up
1764 ;; `*Completions*' buffer. See the Emacs manual (`C-h i') for more
1765 ;; on this general mechanism of prefix completion (called simply
1766 ;; "completion" there).
1768 ;; Calls to `completing-read' and `read-file-name' are not the only
1769 ;; places where input completion is used. When you use `M-x'
1770 ;; (command `execute-extended-command'), completion is also
1773 ;;(@* "Cycling Completions")
1775 ;; Cycling Completions
1776 ;; -------------------
1778 ;; Icicles lets you use the `end' and `home' keys to cycle through
1779 ;; the list of candidate prefix completions that match whatever input
1780 ;; is present in the minibuffer (or all candidate completions, if
1781 ;; there is no input in the minibuffer). In the minibuffer, each
1782 ;; candidate replaces your partial input, in turn, when you cycle.
1783 ;; The prefix (root) that was completed is underlined in the
1784 ;; minibuffer completion candidate.
1786 ;; As an alternative to using `end' to cycle forward, you can hit
1787 ;; `TAB' repeatedly. See (@> "Prefix Completion and Apropos Completion").
1789 ;; Suppose you use `C-x b' (command `switch-to-buffer'). You can
1790 ;; then use `end' until the right buffer name appears in the
1791 ;; minibuffer, then hit `RET'. Or you can type some text that begins
1792 ;; one or more of the buffer names, and then use `end' to cycle among
1793 ;; those names that match that prefix. If there are many candidates,
1794 ;; typing part of the name to narrow the field can save time.
1796 ;; Another example: Suppose you use `C-h v' (`describe-variable') and
1797 ;; type `cal'. Use `end' to cycle among all variables that start
1798 ;; with `cal', until you find the one you want (then hit `RET').
1800 ;; In other words, the current partial input in the minibuffer
1801 ;; determines a matching set of default values, and those are the
1802 ;; values that you can cycle through. You can at any time erase or
1803 ;; change the partial input - the list of matching candidates
1804 ;; automatically reflects the change.
1806 ;; This also means that it's good to have a quick way to clear the
1807 ;; minibuffer of any input, so Icicles also provides minibuffer key
1808 ;; binding `M-k' to do that.
1810 ;; A visible and audible signal lets you know when you have reached
1811 ;; one end of the list of completion candidates, but you can of
1812 ;; course continue to cycle, wrapping around.
1814 ;; If the completion candidates are already displayed in buffer
1815 ;; `*Completions*' when you try to cycle among them (because you hit
1816 ;; `TAB'), then the current candidate is highlighted in
1817 ;; `*Completions*' as you access it in the minibuffer with the `home'
1818 ;; and `end' keys. If you change the minibuffer input, then the
1819 ;; `*Completions*' list is updated accordingly, to reflect the new
1820 ;; set of matching candidates. The root that was completed (the
1821 ;; minibuffer input) is highlighted in each candidate of the
1822 ;; `*Completions*' display. The `*Completions*' window is
1823 ;; automatically scrolled as needed, to show the current candidate.
1825 ;; Do not become a cycling drone! Input some text to narrow the set
1826 ;; of candidates, before cycling among them to choose one. This is a
1827 ;; good habit to adopt, generally, in Icicles. Most of the power of
1828 ;; Icicles comes in your ability to filter a set of candidates. This
1829 ;; is especially true when it comes to regexp filtering (see
1830 ;; (@> "Apropos Completions")).
1832 ;; Cycling and filtering work hand in hand. If the set of candidates
1833 ;; is small to begin with, then just cycling might be quick enough -
1834 ;; that is the case if you move among a small set of buffers, for
1835 ;; instance. But with Icicles you can profitably use cycling on even
1836 ;; a very large set of candidates - by filtering the set first. The
1837 ;; reason this is not very practical with vanilla Emacs is that
1838 ;; filtering by a prefix only is not very potent.
1840 ;; Tip: Whenever you type or delete text in the minibuffer, your
1841 ;; partial input is remembered. When you cycle completion
1842 ;; candidates, your input is replaced by each candidate, but you can
1843 ;; at any time refresh the minibuffer to retrieve what you last
1844 ;; typed. You do this with `C-l', which is bound in the minibuffer
1845 ;; to command `icicle-retrieve-previous-input'. Editing a completion
1846 ;; candidate that you have cycled into the minibuffer counts as
1847 ;; input. Editing tells Icicles to remember what is in the
1848 ;; minibuffer as your last real input. If you want to replace the
1849 ;; candidate and go back to editing the input you had already typed
1850 ;; before cycling, then use `C-l' - do not just delete characters
1851 ;; from the candidate. See (@> "History Enhancements").
1853 ;; You can change the keys that are bound to completion-candidate
1854 ;; cycling. And you can change whether `down' and `up' start off by
1855 ;; cycling prefix completions or apropos completions.
1856 ;; See (@file :file-name "icicles-doc2.el" :to "Customizing Key Bindings").
1858 ;; Finally, you can use the mouse wheel (Emacs 22 or later) to cycle
1859 ;; candidates according to the current completion mode (prefix or
1860 ;; apropos). See (@> "Prefix Completion and Apropos Completion").
1862 ;; Mouse-wheel cycling works also with modifier keys: `C-M-' for
1863 ;; candidate help, `C-' for candidate actions, and `C-S-' for
1864 ;; alternative candidate actions. In particular, `C-' with the wheel
1865 ;; gives you a very quick way to visit search hits during Icicles
1866 ;; search (and `C-S-' works for search-and-replace).
1867 ;; (See (@> "Icicles Search Commands, Overview").)
1869 ;; If you are an Emacs-Lisp programmer, then you can use
1870 ;; `completing-read' and `read-file-name' to define your own
1871 ;; commands, enabling them to take advantage of Icicles completion
1872 ;; and cycling. The definition of command `icicle-recent-file' is a
1873 ;; good model to follow. Emacs has a `recentf-mode' that lets you
1874 ;; open recently accessed files. But this mode makes you open a file
1875 ;; using a menu interface. Command `icicle-recent-file' lets you use
1876 ;; the usual `find-file' minibuffer interface, with completion and
1877 ;; cycling among your recent files. See sections
1878 ;; (@> "Defining Icicles Commands") and
1879 ;; (@file :file-name "icicles-doc2.el" :to "Note to Programmers")
1880 ;; for more on defining your own commands with `completing-read' and
1881 ;; `read-file-name'.
1883 ;;(@* "Traversing Minibuffer Histories")
1885 ;; Traversing Minibuffer Histories
1886 ;; -------------------------------
1888 ;; Perhaps you are already used to accessing past inputs with vanilla
1889 ;; Emacs using the `down' and `up' arrow keys (or `M-n', `M-p', and
1890 ;; `next'). If not, try it (not in Icicle mode). You can go
1891 ;; backward and forward in the minibuffer histories (there are
1892 ;; different history lists for different kinds of input). You cannot
1893 ;; really cycle them (with wraparound), but when you get to one end
1894 ;; you can reverse the direction.
1896 ;; Anyway, the input-cycling behavior that Icicles offers is in
1897 ;; addition to this standard traversal of histories. Since there
1898 ;; are, by default, several extra pairs of keys used for history
1899 ;; traversal, rebinding some of them to use for Icicles completion is
1902 ;; By default, Icicles rebinds the arrow keys `down' and `up' for
1903 ;; current-mode completion cycling. Icicles also rebinds `end' and
1904 ;; `home' for prefix-completion cycling, and `next' and `prior' for
1905 ;; apropos-completion cycling. But you still have `M-n' and `M-p'
1906 ;; available to access past inputs (history). And the rebindings are
1907 ;; only for minibuffer input; global bindings are not affected.
1909 ;; You can at any time switch back and forth between input-history
1910 ;; traversal (`M-n', `M-p') and completion cycling (`down', `up',
1911 ;; `next', `prior', `end', `home').
1915 ;; * (@> "History Enhancements") for new ways to use Emacs history
1916 ;; lists with Icicles
1918 ;; * (@file :file-name "icicles-doc2.el" :to "Customizing Key Bindings")
1919 ;; for how to change the default Icicles key bindings, including
1920 ;; the keys used for candidate cycling
1922 ;;(@* "Apropos Completions")
1924 ;; Apropos Completions
1925 ;; -------------------
1927 ;; Icicles offers a new way to complete your partial input in the
1928 ;; minibuffer. Instead of considering the string of input characters
1929 ;; to be the prefix of various complete names, you can look for names
1930 ;; that match that string anywhere.
1932 ;; This is the single most important feature that Icicles offers.
1934 ;; This is similar in effect to using command `apropos' to find
1935 ;; "apropos completions" of a string (except it works also for file
1936 ;; and buffer names), so that's the term I use for this: apropos
1937 ;; completion. The more correct characterization of this is that of
1938 ;; the previous paragraph, however: names that match the given
1941 ;; Just as with prefix completion, Icicles lets you cycle among the
1942 ;; apropos candidates. To do this, you use keys `next' and `prior'.
1943 ;; The root that was completed is underlined in the minibuffer
1944 ;; completion candidate.
1946 ;; For example, suppose you use `M-x' to enter a command. You do not
1947 ;; remember the exact command name, but it has something to do with
1948 ;; lines, so you type `M-x line', then hit `next' repeatedly, until
1949 ;; you see the right "line" command - `transpose-lines', perhaps.
1950 ;; Prefix completion cannot find this command, because "line" is not
1951 ;; a prefix of "transpose-lines".
1953 ;; Because `M-x' expects a command name, only command names are
1954 ;; inserted into the minibuffer as the apropos-completion candidates
1955 ;; for `M-x'. Likewise, in other contexts, where names of other
1956 ;; kinds of object are expected, apropos completion inserts only
1957 ;; names of objects of the appropriate type. Prefix completion works
1960 ;; For example, using `next' and `prior' with `C-x b at' lets you
1961 ;; cycle through all buffers (such as `*scratch*') that have "at" in
1962 ;; their name - only buffer names appear as candidates.
1964 ;; As an alternative to using `next' to cycle forward, you can hit
1965 ;; `S-TAB' repeatedly. Similarly, for prefix completion you can
1966 ;; repeat `TAB' to cycle forward. See
1967 ;; (@> "Prefix Completion and Apropos Completion").
1969 ;; Apropos completion uses a regular expression (regexp) as its input
1970 ;; string. You can type `M-x \bes', for instance, to find commands
1971 ;; with "es" at the start of a word within the command name (`\b'
1972 ;; matches the start of a word). It will find `eshell-test' and
1973 ;; `color-theme-blue-eshell', but not `count-lines' - "es" does not
1974 ;; start a word in `count-lines'. Similarly, for file names, buffer
1975 ;; names, and so on.
1977 ;; Prefix completion is actually a special case of apropos
1978 ;; completion, where the regexp starts with "^". (That is not how it
1979 ;; is implemented, however.)
1981 ;; What if you want to see the list of all completion candidates that
1982 ;; match the minibuffer input? Instead of cycling candidates
1983 ;; blindly, just hit `S-TAB' (Shift TAB) at any time to display the
1984 ;; matching candidates in pop-up buffer `*Completions*'. This is
1985 ;; analogous to `TAB' for prefix completion.
1987 ;; (The documentation always refers to the key that performs apropos
1988 ;; completion as `S-TAB'. Actually, it is `S-TAB' only by default.
1989 ;; You can customize it, using option
1990 ;; `icicle-apropos-complete-keys'.)
1992 ;; Everything said in section (@> "Cycling Completions") about the
1993 ;; `*Completions*' buffer for prefix completion is also true for
1994 ;; apropos completion. It is updated to reflect the current set of
1995 ;; matching candidates, and the current completion is highlighted.
1996 ;; The root that was completed is highlighted within each candidate
1997 ;; (first occurrence only). Root highlighting is more important in
1998 ;; the case of apropos completion, because the match position is
1999 ;; different in different candidates. In the case of apropos
2000 ;; completion, the root is not the input string, taken literally, but
2001 ;; the part of a candidate that the input matches. See
2002 ;; (@> "*Completions* Display") for additional ways to use the
2003 ;; minibuffer with `*Completions*'.
2005 ;; Regexp matching is one of the most powerful features of Icicles.
2006 ;; Enjoy! Explore! You can at any time switch back and forth
2007 ;; between prefix completion (`end', `home'), apropos completion
2008 ;; (`next', `prior'), and input history traversal (`M-n', `M-p').
2010 ;;(@* "Expanded-Common-Match Completion")
2012 ;; Expanded-Common-Match Completion
2013 ;; --------------------------------
2015 ;; Apropos (regexp) matching and prefix completion each match a
2016 ;; pattern against a completion candidate. This operation concerns
2017 ;; only a single candidate; it does not take into account the fact
2018 ;; that there are others. Since the matching operation is repeated
2019 ;; anyway for each candidate, however, we can also find an expanded
2020 ;; string that includes the same match (apropos or prefix) for all
2023 ;; For prefix completion, Emacs completes your input to the longest
2024 ;; common prefix match. Icicles uses a similar notion for apropos
2027 ;; For example, if you enter `M-x minib' and hit `TAB', Emacs
2028 ;; completes your input to `minibuffer', which is the longest prefix
2029 ;; match for `minib' among all command names. The actual string that
2030 ;; matches prefix `minib' among all candidates is, itself, `minib'.
2032 ;; If you hit `S-TAB', then each matching candidate contains a
2033 ;; substring that matches your regexp input `minib'. In this case,
2034 ;; that substring is `minib', just as in the prefix-matching case.
2035 ;; And, as in the prefix case, each matching candidate also includes
2036 ;; a longer substring, `minibuffer', which includes what your input
2037 ;; matches for each candidate.
2039 ;; Icicles replaces your regexp input in the minibuffer by a common
2040 ;; substring. Icicles highlights this expanded common match in
2041 ;; buffer `*Completions*' using face
2042 ;; `icicle-common-match-highlight-Completions' (magenta foreground,
2043 ;; by default). What your input matches directly is highlighted in
2044 ;; `*Completions*' using face `icicle-match-highlight-Completions'
2045 ;; (red foreground, by default).
2047 ;; It is of course possible that a given regexp match different
2048 ;; candidates differently, so that there is no common match. In that
2049 ;; case, only the individual matches are highlighted in
2050 ;; `*Completions*' - you will see only red, no magenta, highlighting.
2051 ;; For example, if your regexp input is `min.*buf' then various
2052 ;; different substrings (such as `minibuf' from `minibuffer-complete'
2053 ;; and `mint-truncate-buf' from `comint-truncate-buffer') are
2054 ;; highlighted in red, but these share no common substring.
2056 ;; You will also see only red highlighting if what your input matches
2057 ;; directly is the same as the expanded common match. For example,
2058 ;; if a function `moccur-regexp-read-from-minibuf' is defined (it is
2059 ;; in library `color-moccur.el'), and your input to `C-h f' is
2060 ;; `min[^-]*buf', then only `minibuf' is highlighted in red.
2062 ;; Expanded-common-match completion is convenient, but when
2063 ;; apropos-completing you often need to try variants of a regexp,
2064 ;; editing it and observing which candidates match in
2065 ;; `*Completions*', until you get the regexp right.
2066 ;; Expanded-common-match completion has the disadvantage that you
2067 ;; lose your regexp as input, which makes it hard to edit it!
2069 ;; To retrieve it, use `C-l' (`icicle-retrieve-previous-input')
2070 ;; during completion. You can repeat `C-l' to retrieve older
2071 ;; completion inputs, cycling among them, and you can use `C-S-l'
2072 ;; (that is, `C-L') to cycle previous inputs in the other direction -
2073 ;; see (@> "History Enhancements"). You can set option
2074 ;; `icicle-expand-input-to-common-match-flag' to `nil' to turn off
2075 ;; expanded-common-match completion altogether, if you prefer. You
2076 ;; can also toggle it from the minibuffer at any time, using `C-;'.
2078 ;; Just what is meant by the "expanded common match" that Icicles
2079 ;; finds? It is the longest match of your input pattern that is
2080 ;; common to all candidates and also contains the first input match
2081 ;; in the first or second candidate, whichever is longer.
2083 ;; For apropos completion, this is not always the longest common
2084 ;; match of your input, but in most cases it is, and it is quicker to
2085 ;; compute. In general, the longest common match does not
2086 ;; necessarily contain the first match of your input with either the
2087 ;; first candidate or the second candidate. It might contain a
2088 ;; different input match from the first in both the first and second
2091 ;; For example, with input `a' and candidates `abacb', `abbac', and
2092 ;; `bacba' (in that order), `bac' is the longest common match. But
2093 ;; `a' is the longest common match that contains the first match in
2094 ;; the first candidate. It is the second match of `a' against
2095 ;; `abacb' that yields `bac'. Likewise for the second candidate: it
2096 ;; is the second match of `a' against `abbac' that yields `bac'.
2098 ;; So in this case Icicles will use `a' as the expanded input and
2099 ;; miss the longest common match. If the candidate order is
2100 ;; different, so that `bacba' is either the first or the second
2101 ;; candidate, then Icicles finds the longest common match, because
2102 ;; the first match of `a' against `bacba' yields `bac'.
2104 ;; The reason that Icicles common-match expansion typically finds the
2105 ;; longest common match is that your input typically matches the
2106 ;; first or the second candidate in only one place. And the longer
2107 ;; the input you type, the more likely this is. In practice, it is
2108 ;; only with very short input such as `a' that Icicles expansion
2109 ;; sometimes misses the longest common match. Icicles independently
2110 ;; tries two candidates (first and second) as its starting point, to
2111 ;; increase the probability of finding the longest common match.
2113 ;; It is also technically incorrect to speak of "the" longest common
2114 ;; match: in general, there can be more than one. For example, if
2115 ;; the input is `a' and the candidates are `abab', `abba', and
2116 ;; `baba', then both `ab' and `ba' are longest common substrings.
2117 ;; Again, however, for typical input and typical candidates there is
2118 ;; a single longest common match, and Icicles finds it.
2120 ;; Note that Icicles expanded common match is not just a common
2121 ;; substring among all of the candidates that are matched by your
2122 ;; input pattern. It is a substring common to all candidates matched
2123 ;; by your input, but a substring that also matches your input. For
2124 ;; example, with apropos completion input `a.z' and candidates `abz'
2125 ;; and `apz', there is no expanded common match. The substring `a'
2126 ;; is common to both candidates, but it is not matched by the
2127 ;; (complete) input pattern.
2129 ;; Finally, note that in Emacs 20 no common match is found if your
2130 ;; input or any of the candidates contains binary data. This is
2131 ;; because function `string-match' cannot handle strings with binary
2132 ;; data in Emacs 20.
2134 ;;(@* "Progressive Completion")
2136 ;; Progressive Completion
2137 ;; ----------------------
2139 ;; Perhaps the best way to explain this feature is to use a familiar
2140 ;; analogy. Unix or GNU/Linux command `grep' takes a
2141 ;; regular-expression argument, and matches it against lines in
2142 ;; files. A common idiom that people use is to chain, or cascade,
2143 ;; multiple calls to `grep', using the output of one as the input to
2144 ;; the next. For example:
2146 ;; grep plant *.txt | grep food | grep mineral
2148 ;; The output of the search for "plant" is used as the input for the
2149 ;; search for "food", and the output of that search serves as the
2150 ;; input for the search for "mineral". The order of the three
2151 ;; component searches can make a difference in terms of performance,
2152 ;; but not in terms of the result, which is always the set of lines
2153 ;; in files *.txt that match "plant" AND "food" AND "mineral", in any
2154 ;; order. Each of the `grep' operations defines a set of matches,
2155 ;; and the chain of `grep' operations effects the intersection of
2158 ;; Of course, you could try to accomplish the same thing with a
2159 ;; single call to `grep' using a complex regexp. But why would you?
2161 ;; Moreover, it is in fact impossible to express such an unordered
2162 ;; set intersection using a single regexp. On their own, regular
2163 ;; expressions cannot express set intersection (conjunction) or
2164 ;; complementing (negation). (However, most `grep' programs provide
2165 ;; a way to obtain the lines that do not match a regexp.)
2167 ;; The same idea of combining multiple regexp matches is behind the
2168 ;; Icicles feature of progressive completion: instead of trying to
2169 ;; come up with a single complex regexp that does what you want, try
2170 ;; getting there a step at a time:
2172 ;; 1. Match an input regexp against the set of all possible
2175 ;; 2. Narrow the set of matched candidates by matching them against
2176 ;; another input regexp (or by filtering them with a predicate).
2178 ;; 3. Narrow those results down by matching them against a third
2179 ;; input regexp (or by filtering them with another predicate).
2183 ;;(@* "`M-*': Matching Additional Regexps")
2184 ;; ** `M-*': Matching Additional Regexps **
2186 ;; During completion, `M-*' is bound in the minibuffer to command
2187 ;; `icicle-narrow-candidates', which prompts for a new regexp and
2188 ;; matches it against the current set of completion candidates.
2190 ;; For example, suppose that you want to know about an Emacs function
2191 ;; that deletes the character to the left of point (that is,
2192 ;; backward). You do not recall if it is `delete-character-back',
2193 ;; `delete-backward-char', `character-delete-backward', or whatever.
2194 ;; You take a guess that the name contains `delete', `char', and
2197 ;; 1. `C-h f char S-TAB' displays function names that contain
2200 ;; 2. `M-* delete' narrows that set of function names to those that
2201 ;; also contain `delete'.
2203 ;; 3. `M-* back' narrows the set of matching names further, to those
2204 ;; that also contain `back'.
2206 ;; This displays a list of functions like this in `*Completions*'
2207 ;; (your list might be somewhat different):
2209 ;; backward-delete-char backward-delete-char-untabify
2210 ;; delete-backward-char icicle-backward-delete-char-untabify
2211 ;; icicle-delete-backward-char
2212 ;; quail-conversion-backward-delete-char
2214 ;; Then, of course, you can pick one (or you can use `C-M-next'
2215 ;; repeatedly to view the doc of each of these functions in turn -
2216 ;; see (@> "Get Help on Candidates")).
2218 ;; You get the idea. This feature is both very simple to use and
2219 ;; very useful. It's easy to appreciate using multiple simple
2220 ;; matching steps (regexp or not) instead of a single regexp. Try it
2221 ;; once, and you'll be hooked.
2223 ;;(@* "Successive Approximation...")
2224 ;; ** Successive Approximation... **
2226 ;; You can use as many invocations of `M-*' (and of `M-&', described
2227 ;; in the next section) as you like, in any order. It works with
2228 ;; both prefix completion and apropos completion. You can, for
2229 ;; instance, first use `TAB' to require the target to start with some
2230 ;; string, and then use `M-*' to specify other patterns that parts of
2231 ;; it must also match. However, it of course makes no sense to use
2232 ;; `TAB' instead of `S-TAB' after you use `M-*': once you've said
2233 ;; that the target must start with "fo" there is no sense saying that
2234 ;; it also starts with "ti"!
2236 ;; As a shortcut, instead of using `S-TAB' followed by `M-*', you can
2237 ;; use `S-SPC' (command `icicle-apropos-complete-and-narrow') to do
2238 ;; the same thing. You can thus use only `S-SPC', any number of
2239 ;; times, to choose a candidate by narrowing down the matches.
2241 ;; I call this process of completion by successive approximation, or
2242 ;; progressively narrowing the candidate set, "progressive
2243 ;; completion". If the name "incremental completion" (= icompletion)
2244 ;; were not already taken to mean incremental completion *help*
2245 ;; (which performs no completion), then that might be a good name for
2246 ;; this. This might also be called "stepped", "cascaded", or
2247 ;; "piecewise" completion.
2249 ;; Another possible name for it would be "multiple completion", but I
2250 ;; use that to stand for simultaneous (parallel) completion of
2251 ;; multiple parts of a compound target, which is something different
2252 ;; (see (@file :file-name "icicles-doc2.el" :to "Multi-Completions")).
2253 ;; Progressive completion is a set of mini-completions that are wired
2254 ;; in series, not in parallel.
2256 ;; Note that when you use `M-*' (or `S-SPC') in the minibuffer, it
2257 ;; calls `completing-read' or `read-file-name', which creates a
2258 ;; recursive minibuffer. That is, the minibuffer depth is increased.
2259 ;; (This is not the case for `M-&', however.) In vanilla Emacs,
2260 ;; there is no indicator of the current minibuffer depth, and this
2261 ;; can sometimes be disorienting. Each time you use `M-*' you push
2262 ;; down one level of minibuffer recursion (that is, minibuffer depth
2263 ;; is incremented). Each time you use, say, `C-g', you pop up one
2264 ;; level of minibuffer recursion (that is, minibuffer depth is
2267 ;; If you use library `mb-depth.el', which is included with Emacs 23
2268 ;; and which also works with Emacs 22, Icicle mode takes advantage of
2269 ;; this library by indicating the current depth in the minibuffer. I
2270 ;; recommend you also use my library `mb-depth+.el', which lets you
2271 ;; customize the form and face of the depth indicator.
2273 ;; If you use my library `oneonone.el', then you get visual feedback
2274 ;; on the current minibuffer depth. One-On-One Emacs gives you a
2275 ;; standalone minibuffer frame, and it changes the background hue
2276 ;; (color) of that frame slightly with each change in minibuffer
2277 ;; depth. This is especially helpful with Icicles, where use of
2278 ;; `M-*' (or `S-SPC') is common.
2280 ;; There is a slight difference in behavior between Icicles commands
2281 ;; and some other Emacs commands when you accept input after `M-*'.
2282 ;; When possible, Icicles accepts your input and passes it
2283 ;; immediately to the top level, bypassing any intermediate recursive
2284 ;; minibuffer levels that are waiting for input. However, Emacs
2285 ;; commands that are defined with literal-string `interactive' specs,
2286 ;; such as (interactive "fFile: "), do not use `completing-read' or
2287 ;; `read-file-name', so there is no way for Icicles to take this
2288 ;; shortcut with them. In that case, you will simply need to hit
2289 ;; `RET' again to accept your input at each recursive minibuffer
2290 ;; level, until you get back to the top level. Sorry for this
2291 ;; inconvenience! If you are an Emacs-Lisp programmer, note that
2292 ;; this is one reason to use `completing-read' and `read-file-name'
2293 ;; when you write commands that use completion.
2295 ;; Note: If you use progressive completion with file names in Emacs
2296 ;; 20 or 21, `M-*' calls `completing-read', not `read-file-name'.
2297 ;; This is because `read-file-name' does not accept a PREDICATE
2298 ;; argument before Emacs 22. The effect is that instead of there
2299 ;; being a default directory for completion, the current directory at
2300 ;; the time you hit `M-*' is tacked onto each file name, to become
2301 ;; part of the completion candidates themselves. Yes, this is a
2302 ;; hack. It works, but be aware of the behavior.
2304 ;; Progressive completion lets you match multiple regexps, some of
2305 ;; which could of course be literal substrings, with their regexp
2306 ;; special characters, if any, escaped. If you need to match such
2307 ;; substrings at particular locations in the target completion
2308 ;; candidate, then progressive completion will not do the job - it
2309 ;; matches its component regexps independently. You can regexp-quote
2310 ;; (escape) parts or all of your input using `M-%'
2311 ;; (`icicle-regexp-quote-input').
2312 ;; See (@> "Quoting (Escaping) Special Characters")
2314 ;;(@* "`M-&': Satisfying Additional Predicates")
2315 ;; ** `M-&': Satisfying Additional Predicates **
2317 ;; If you use Icicles, then you will use `M-*' very often. This
2318 ;; section describes a seldom-used feature that can be useful in
2319 ;; certain contexts. If you are new to Icicles or you are unfamiliar
2320 ;; with Emacs Lisp, then you might want to just skim this section or
2321 ;; skip it and come back to it later.
2323 ;; Just as you can use `M-*' to narrow the set of candidates by
2324 ;; matching an additional regexp, so you can use `M-&' (bound to
2325 ;; `icicle-narrow-candidates-with-predicate') to narrow by satisfying
2326 ;; an additional predicate. The idea is the same; the only
2327 ;; difference is that, instead of typing a regexp to match, you type
2328 ;; a predicate to satisfy.
2330 ;; The predicate is a Boolean function of a single completion
2331 ;; candidate. At the prompt, you enter its name or its
2332 ;; lambda-expression definition (anonymous function). The predicate
2333 ;; is used the same way as the PREDICATE argument to
2334 ;; `completing-read' and `read-file-name'. This means that the
2335 ;; candidate argument to the predicate is whatever is used in the
2336 ;; original call to `completing-read' or `read-file-name'; it is not
2337 ;; just a string such as you see in buffer `*Completions*'. To
2338 ;; provide an appropriate predicate, you must be familiar with the
2339 ;; kind of candidate expected by the command you invoked before just
2344 ;; * Command `describe-function' (`C-h f') uses candidates that are
2345 ;; symbols. An appropriate predicate would accept a symbol as
2348 ;; * Command `icicle-search' (`C-c `') uses candidates that have this
2349 ;; form: (CONTEXT . MARKER), where CONTEXT is a string, the search
2350 ;; hit (search context), and MARKER is a buffer marker that locates
2351 ;; the CONTEXT. An appropriate predicate would accept such a
2352 ;; candidate as argument.
2354 ;; Although entering a lambda expression at a prompt might not seem
2355 ;; too convenient, you can at least retrieve previously entered
2356 ;; predicates (using `M-p' and so on).
2358 ;; You can also use `C-M-&' (bound to
2359 ;; `icicle-save-predicate-to-variable') at any time during completion
2360 ;; to save the current predicate as a string-valued variable. By
2361 ;; default, the variable is `icicle-input-string'. You can then
2362 ;; retrieve the saved string later, using `C-=' at the prompt for
2363 ;; `M-&'. The current predicate is what is saved. You can build up
2364 ;; a complex predicate, and then save it for later use.
2366 ;; The inconvenience of typing an Emacs-Lisp sexp must be balanced
2367 ;; against the power of applying predicates on the fly. Whereas
2368 ;; regexp matching is purely syntactic, with a predicate you can
2369 ;; perform semantic tests. During search, for instance, you can look
2370 ;; not only for a syntax match; you can look for matching search
2371 ;; candidates that also belong to a particular class of objects
2372 ;; (e.g. function, variable, type) or that satisfy some other
2373 ;; semantic property.
2374 ;; See also (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview").
2378 ;; * (@> "Sets of Completion Candidates") for another way to perform
2379 ;; a set intersection on sets of candidate completions.
2381 ;; * (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
2382 ;; for a way to search using two regexps - command `icicle-search'
2383 ;; uses the same idea as that behind progressive completion.
2385 ;; * (@file :file-name "icicles-doc2.el" :to "Compile/Grep Search")
2386 ;; for a way to grep files using multiple levels of regexps, and
2387 ;; performing selected replacements.
2389 ;;(@* "Regressive Completion")
2391 ;; Regressive Completion
2392 ;; ---------------------
2394 ;; Though generally less useful than progressive completion, you can
2395 ;; also widen, instead of narrow, the current set of completion
2396 ;; candidates, by providing an alternative pattern (regexp) to match.
2397 ;; By analogy, I call this "regressive completion".
2399 ;; The analogy is not exact. By definition, your current input is
2400 ;; always matched against all candidates in the domain of discourse.
2401 ;; With progressive completion, a recursive minibuffer is entered for
2402 ;; each new pattern to match. The candidates that matched the
2403 ;; previous input of the progression become the new domain of
2404 ;; discourse for the current act (recursive level) of completion.
2406 ;; That same technique is not applicable for widening. Instead, you
2407 ;; enter, using `RET', a new pattern to match as an alternative, and
2408 ;; Icicles changes the current input to a regexp that matches either
2409 ;; what the previous input matched or the alternative pattern. In
2410 ;; other words, it is just a short cut for typing a regexp that
2411 ;; matches a choice: \(...\|...\). The domain of discourse remains
2412 ;; the same - in particular, there is no way to widen the domain of
2413 ;; discourse like narrowing narrows it.
2415 ;; You use `M-+' (`icicle-widen-candidates') for regressive
2416 ;; completion - think of the `+' as set union (OR), just as you think
2417 ;; of the `*' in `M-*' as set intersection (AND). And, just as for
2418 ;; progressive completion, there is a shortcut, `S-backspace', for
2419 ;; `S-TAB' followed by `M-+'.
2421 ;; For example, if you want to see all of the candidates that contain
2422 ;; either `for' or `back', you could type `\(for\|back\)' in the
2423 ;; minibuffer, or you could just type `for', then `S-backspace' (or
2424 ;; `S-TAB' followed by `M-+'), then `back'. Icicles replaces your
2425 ;; input by `\(for\|back\)'. You can continue with additional
2426 ;; alternative match patterns. And you can combine narrowing with
2427 ;; widening, that is, progressive with regressive completion.
2429 ;; You can of course cycle among all matching candidates, regardless
2430 ;; of which alternative they match. One use of regressive completion
2431 ;; is with Icicles search - it corresponds to the OR searching of
2432 ;; common search engines.
2434 ;; Gotcha: When completing file names that are not absolute
2435 ;; (e.g. using `C-x C-f', not `C-u C-x C-f'), be sure that the
2436 ;; default directory is not included in your minibuffer input when
2437 ;; you hit `M-+'. You do not want the overall regexp that `M-+'
2438 ;; constructs to be something like \(/my/default/dir/foo\|bar\) - you
2439 ;; want it to be just \(foo\|bar\). For absolute file name
2440 ;; completion there is no such problem, because the completion
2441 ;; candidates themselves have a directory component. So either use a
2442 ;; `nil' value of `insert-default-directory' or use `M-k' to remove
2443 ;; the directory component before hitting `M-+'.
2445 ;;(@* "Completion On Demand")
2447 ;; Completion On Demand
2448 ;; --------------------
2450 ;; When the minibuffer is active for your input, completion is not
2451 ;; always available. Functions such as `completing-read' and
2452 ;; `read-file-name' provide completion, but other functions that read
2453 ;; input in the minibuffer, such as `read-from-minibuffer' and
2454 ;; `read-string', do not provide completion.
2455 ;; (See (@> "Completion Status Indicators"), for how to tell when
2456 ;; completion is available in Icicles.)
2458 ;; But in Icicles you can always invoke (lax) completion to insert
2459 ;; some completed text in the minibuffer - this is completion on
2462 ;; On-demand completion is always available to insert a file name.
2463 ;; You invoke this using `C-M-F', that is, `C-M-S-f'
2464 ;; (`icicle-read+insert-file-name'). A recursive minibuffer is used
2465 ;; to perform the completion. The result of completing is inserted
2466 ;; at point in the parent minibuffer, without replacing any other
2467 ;; text that might already be there.
2469 ;; You can use this feature to add multiple file or directory names
2470 ;; to the same minibuffer input. In this way, for instance, you can
2471 ;; use it to add particular file or directory names as arguments to a
2472 ;; shell command that you input in the minibuffer. By default, a
2473 ;; relative name is inserted, but if you use a prefix argument then
2474 ;; the directory component is included.
2476 ;; Similarly, you can use `C-M-C', that is, `C-M-S-c'
2477 ;; (`icicle-completing-read+insert'), to invoke non file-name
2478 ;; completion. This, however, is available only if the command
2479 ;; reading from the minibuffer allows it, by defining a set of
2480 ;; possible completions.
2482 ;; The actual keys used for on-demand completion are customizable,
2483 ;; using options `icicle-read+insert-file-name-keys' and
2484 ;; `icicle-completing-read+insert-keys'. The default values are
2485 ;; `C-M-S-f' and `C-M-S-c'.
2487 ;; Another kind of on-demand completion is provided by `M-o'
2488 ;; (`icicle-insert-history-element'). Again, this is always
2489 ;; available in the minibuffer, regardless of whether input is being
2490 ;; read with completion. This invokes completion against the entries
2491 ;; in the current minibuffer history.
2492 ;; See (@> "History Enhancements").
2494 ;;(@* "Moving Between the Minibuffer and Other Buffers")
2496 ;; Moving Between the Minibuffer and Other Buffers
2497 ;; -----------------------------------------------
2499 ;; Sometimes, when the minibuffer is active, you might want to move
2500 ;; the cursor and focus from the minibuffer back to the original
2501 ;; buffer from which you activated the minibuffer. When you are in
2502 ;; Icicle mode, the `pause' key is bound (by default) to command
2503 ;; `icicle-switch-to/from-minibuffer', which does that. This lets
2504 ;; you start minibuffer input (with or without completion), and then
2505 ;; interrupt it to search, edit, and so on, in the original buffer.
2506 ;; This same command (bound to `pause') then lets you switch back to
2507 ;; the minibuffer - it acts as a toggle for the input focus; go back
2508 ;; and forth as much as you like.
2510 ;; This can be especially useful when you use multi-commands (see
2511 ;; (@> "Multi-Commands")). In that case, you often keep the
2512 ;; minibuffer active for completion while performing multiple
2513 ;; completion actions. It can be handy to interrupt this to perform
2514 ;; some normal editing or search, and then resume multi-command
2517 ;; Another use for this feature is to select text in the original
2518 ;; buffer and then insert it in the minibuffer. See also
2519 ;; (@> "Inserting Text Found Near the Cursor") for another way to do
2522 ;; A somewhat related toggle is available using `C-insert'. This
2523 ;; lets you switch the focus between the minibuffer and buffer
2524 ;; `*Completions*'. See (@> "*Completions* Display") for more
2527 ;;(@* "Inserting a Regexp from a Variable or Register")
2529 ;; Inserting a Regexp from a Variable or Register
2530 ;; ----------------------------------------------
2532 ;; Regexps are powerful, but they can sometimes be complex to compose
2533 ;; and hard to remember once composed. A shortcut is to compose a
2534 ;; regexp that you want to use and assign it to an Emacs variable or
2537 ;; If you assign it to a register (using `C-x r s'), then you can use
2538 ;; `C-x r i' (`insert-register') in the minibuffer to insert it. If
2539 ;; you assign it to a string, then you can use `C-='
2540 ;; (`icicle-insert-string-from-variable') to insert it.
2542 ;; If you use `C-u C-=' (provide a prefix argument) then you are
2543 ;; prompted for the variable to use. Completion candidates for this
2544 ;; include all string-valued variables.
2546 ;; Without `C-u', the default variable is used (no prompting),
2547 ;; `icicle-input-string'. So for example, if `icicle-input-string'
2548 ;; had value "[a-zA-Z]+" then it would match any completion candidate
2549 ;; composed only of letters. You can customize
2550 ;; `icicle-input-string'.
2552 ;; For convenience, instead of using Lisp evaluation of a sexp such
2553 ;; as (setq icicle-input-string "[a-zA-Z]+") or (setq my-var ".*"),
2554 ;; you can use Icicles command `icicle-save-string-to-variable' to
2555 ;; save a regexp to a variable. You are prompted for the regexp to
2556 ;; save. Just as for `icicle-insert-string-from-variable', with a
2557 ;; prefix argument you are prompted for the variable to use (all
2558 ;; variables are completion candidates). With no prefix argument the
2559 ;; regexp is saved to variable `icicle-input-string'.
2561 ;; Another way of inserting a string into the minibuffer is to use a
2562 ;; negative prefix arg with `M-:' (e.g. `M-- M-:') during minibuffer
2563 ;; input. With this method, you can type not only a string-valued
2564 ;; variable name but any Emacs-Lisp expression. The expression need
2565 ;; not evaluate to a string - whatever the result of evaluation is,
2566 ;; it is pretty-printed in the minibuffer, to be used as part of your
2569 ;; These shortcut features are especially convenient for use with
2570 ;; command `icicle-search' - you can use it to search text for
2571 ;; sentences, paragraphs, file names, URLs, dates, times, function
2572 ;; definitions, and any other text entities that you can specify by
2573 ;; regexp. Create a library of regexp-valued variables that are
2574 ;; useful to you, and use `C-=' to quickly access them in
2575 ;; `icicle-search'. See
2576 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
2577 ;; for more information.
2579 ;; These shortcuts are also handy for Isearch, in particular, regexp
2580 ;; search. Use `M-e' after `C-M-s', to edit the search string (which
2581 ;; puts you in a minibuffer), then use `C-u C-=' or `C-x r i' to
2582 ;; insert a saved regexp.
2584 ;; See Also: (@> "Inserting Text Found Near the Cursor").
2586 ;;(@* "Special Characters in Input Patterns")
2588 ;; Special Characters in Input Patterns
2589 ;; ------------------------------------
2591 ;; Regular-expression syntax treats some characters specially, but
2592 ;; some of these special characters have another special meaning in
2593 ;; Emacs when used with file-name inputs. What about the conflict
2594 ;; between interpreting characters such as `$', `\', `.', `?', and
2595 ;; `*' as 1) regexp special characters and 2) special characters for
2596 ;; file-name input? For example, when inputting a file name, should
2597 ;; `*' be treated as a regexp multiple-occurrences operator or as a
2598 ;; file-name wildcard?
2600 ;; In Emacs file-name input:
2602 ;; - `$' can be used to prefix environment variables.
2604 ;; - `*' and `?' can be used as wildcards, effectively inputting
2605 ;; multiple file names at once.
2607 ;; - `.' and `..' can be used to navigate a directory hierarchy.
2609 ;; - `\' is a directory separator, like `/', on MS Windows, at least.
2611 ;; Icicles handles the conflict by interpreting such characters as
2612 ;; regexp special characters only during input completion and cycling
2613 ;; - and then only if you do not escape them (with `\'). If present
2614 ;; in the input when you finally accept it (using `RET'), they take
2615 ;; on their normal Emacs meanings for file-name input:
2616 ;; environment-variable prefix, wildcard, directory abbreviation, or
2617 ;; directory separator.
2619 ;; That is, whenever there is a potential conflict of interpretation,
2620 ;; the regexp meaning is used for completion and cycling, and the
2621 ;; standard interpretation for file-name input is used for accepting
2622 ;; the input. So, for example, to get the wildcard interpretation of
2623 ;; `*', just forego regexp completion and cycling. And vice versa:
2624 ;; forego the wildcard interpretation to use regexp completion and
2627 ;; This is in any case the behavior of vanilla Emacs as well. If, in
2628 ;; vanilla Emacs, you use `ici*' or `ici*.el' as input to `find-file'
2629 ;; and hit `TAB', there is no completion available. File-name
2630 ;; globbing and completion are independent.
2632 ;; Note: Because `?' is useful in regexp syntax, the standard Emacs
2633 ;; minibuffer binding of `?', which just displays the
2634 ;; completion-candidates list, is not used in Icicles. In
2635 ;; Icicles, `?' self-inserts in the minibuffer, like any other
2636 ;; printable character. (Use `TAB' or `S-TAB' to display the
2637 ;; list.) In standard Emacs, you must quote `?' or
2638 ;; copy-and-paste it, to insert it in the minibuffer for use as
2639 ;; a file-name wildcard.
2641 ;; The interpretation conflict for `\' (on MS Windows) is not really
2642 ;; a problem, anyway. Although you cannot use a backslash (`\') as a
2643 ;; directory separator during apropos completion and cycling, you can
2644 ;; always use a slash (`/') instead - even on MS Windows. The best
2645 ;; practice is to just break with MS-Windows syntax, and get in the
2646 ;; habit of always using `/' as the directory-separator character.
2648 ;; But what if you copy an absolute filename from some MS Windows
2649 ;; application, so it has backslashes, and you want to use it in
2650 ;; Emacs? You can go ahead and paste it in the minibuffer for
2651 ;; filename completion, as long as you are not doing regexp
2652 ;; completion. You can (a) use prefix completion with it, (b) use
2653 ;; `C-`' to turn on regexp quoting for apropos completion (so you can
2654 ;; complete a substring), or (c) change the backslashes to slashes.
2656 ;; Even if you always use only slash, not backslash, as a directory
2657 ;; separator when inputting, however, it is possible that you could
2658 ;; run into some trouble on MS Windows. You might (knowingly or not)
2659 ;; use `\' as a directory separator in the values of environment
2660 ;; variables that you use as part of file-name input. If you are
2661 ;; regexp completing, then those backslashes will be treated as
2662 ;; regexp escapes. So you should use only non-regexp completion with
2663 ;; input that includes environment variables whose expansions might
2664 ;; include backslashes.
2666 ;; The interpretation conflict for `$' is also not a real problem.
2667 ;; You can get the effect of both interpretations of `$' at the same
2668 ;; time, because Icicles recognizes that `$' at the end of input
2669 ;; cannot be an environment-variable prefix. This means, for
2670 ;; example, that you can use a pattern such as `$HOME.*t$' to match
2671 ;; the files in your home directory whose names end in `t'.
2673 ;; The first `$' here is not treated specially during regexp matching
2674 ;; and cycling; the environment variable `$HOME' is expanded by the
2675 ;; shell to a directory name. The second `$' is treated as the
2676 ;; regexp special character that matches at the end of a line. When
2677 ;; using environment variables, you can also enclose them in braces:
2678 ;; `${HOME}', for example.
2680 ;; Note: Starting with Emacs 23, if option
2681 ;; `icicle-TAB-completion-methods' includes `vanilla', and you choose
2682 ;; `vanilla' completion for `TAB' (by cycling using `C-(' or by
2683 ;; customizing `icicle-TAB-completion-methods' to use `vanilla' as
2684 ;; the default), then Icicles `TAB' completion will complete an
2685 ;; environment variable during file-name completion. This is in
2686 ;; addition to the traditional shell expansion of a variable when you
2689 ;; Tip: Because slash (`/') is about the only non-word syntax
2690 ;; character that is likely to appear in file-name completions,
2691 ;; you can usually use `\W$' to match only directories (by
2692 ;; matching the `/' at the end of their names). `\W' is the
2693 ;; regexp pattern that matches any character that does not
2694 ;; appear in words. For example, you can use `${HOME}\W$' to
2695 ;; match all direct subdirectories in your home directory.
2697 ;;(@* "Quoting (Escaping) Special Characters")
2698 ;; ** Quoting (Escaping) Special Characters **
2700 ;; You can toggle interpretation vs escaping of regexp special
2701 ;; characters at any time, using `C-`' in the minibuffer (command
2702 ;; `icicle-toggle-regexp-quote'). Escaping special characters this
2703 ;; way means they are no longer special; they simply match
2704 ;; themselves. This has the effect of reducing apropos completion to
2705 ;; simple substring completion. If you never want to use regexp
2706 ;; matching (*not* recommended!), you can customize user option
2707 ;; `icicle-regexp-quote-flag', setting it to non-`nil'.
2709 ;; Apropos (regexp) completion contains literal substring completion
2710 ;; as a (common) special case. Sometimes you want to use regexp
2711 ;; completion, but you also want to match a literal substring that
2712 ;; contains special characters. You can of course quote (escape)
2713 ;; each of these characters by hand. Alternatively, you can use
2714 ;; `M-%' (`icicle-regexp-quote-input') to quote the text that you
2715 ;; want to match literally. If the region is active, then it is
2716 ;; quoted; otherwise, your entire minibuffer input is quoted.
2718 ;; Note that if a substring that you want to match literally can
2719 ;; occur anywhere in the target completion candidate, then it is
2720 ;; simpler to just use progressive completion. Quoting a literal
2721 ;; substring is useful when the overall regexp requires it to be at a
2722 ;; certain location in the target.
2726 ;; * (@file :file-name "icicles-doc2.el" :to "Icicles Dired Enhancements")
2727 ;; for how to use Icicles regexp-matching to open Dired on sets of
2728 ;; files that you might not be able to specify using file-name
2731 ;; * (@> "Multi-Commands") for a way to open multiple files whose
2732 ;; names match a regular expression.
2734 ;; * (@file :file-name "icicles-doc2.el" :to "File-Name and Directory-Name Completion Tips")
2736 ;; - Information about abbreviating your home directory as `~' or
2738 ;; - A way to locate and open files by regexp anywhere in your file
2739 ;; system - that is, match against directory-name as well as
2740 ;; file-name components.
2742 ;; * (@> "Progressive Completion")
2744 ;;(@* "Exiting the Minibuffer Without Confirmation")
2746 ;; Exiting the Minibuffer Without Confirmation
2747 ;; -------------------------------------------
2749 ;; Normally, if you exit the minibuffer with input that only
2750 ;; partially matches a completion candidate, the value you input is
2751 ;; exactly what you typed. That is, exiting does not automatically
2752 ;; complete your input - what you type is what you get. This is
2753 ;; "lax" (or "permissive") completion, and it is desirable most of
2754 ;; the time, because it lets you input a value that does not
2755 ;; correspond to any of the completion candidates. This is how, for
2756 ;; instance, you can use `C-x C-f' to open a new file or `C-x b' to
2757 ;; create a new buffer.
2759 ;; However, some people prefer "strict" completion: limiting input to
2760 ;; the available completion candidates. This can be handy in the
2761 ;; case of switching to a buffer, for instance. If you have a buffer
2762 ;; named `new-ideas.txt', you might like to be able to type only
2763 ;; `new' followed by `RET', and not have to first complete the input
2764 ;; text. This is the behavior of libraries `ido.el' and
2767 ;; It is the command you use that decides whether `RET' first
2768 ;; completes your input before exiting the minibuffer (strict
2769 ;; completion) or not (lax completion). This is done in the command
2770 ;; definition by providing a non-`nil' or `nil' REQUIRE-MATCH
2771 ;; argument to function `completing-read', which prompts you and
2772 ;; reads your input, possibly completing it.
2774 ;; If you use standard Emacs command `switch-to-buffer' then
2775 ;; completion is lax: `RET' does not complete your input `new' to
2776 ;; `new-ideas.txt'; it simply accepts your input as is, and creates a
2777 ;; new buffer with that name, `new'.
2779 ;;(@* "Using `S-RET' to Accept a Partial Match")
2780 ;; ** Using `S-RET' to Accept a Partial Match **
2782 ;; By default, Icicles command `icicle-buffer', not vanilla command
2783 ;; `switch-to-buffer', is bound to `C-x b' in Icicle mode. The
2784 ;; default behavior of `icicle-buffer' is the same as the behavior of
2785 ;; `switch-to-buffer' with respect to `RET'. However, you can obtain
2786 ;; the complete-and-exit `RET' behavior with `icicle-buffer' by
2787 ;; setting option `icicle-buffer-require-match-flag' to
2788 ;; `partial-match-ok'. This value overrides the REQUIRE-MATCH
2789 ;; argument to `completing-read', in effect forcing it to `t'.
2791 ;; Whenever completion is strict, requiring a match against one of
2792 ;; the completion candidates (typically, an existing file or buffer
2793 ;; name), you can complete and exit the minibuffer all at once, with
2794 ;; only partial input in the minibuffer, by using `RET'. But what
2795 ;; about apropos completion? Simply use `S-RET'
2796 ;; (`icicle-apropos-complete-and-exit') instead of `RET': `RET' is
2797 ;; standard in Emacs and uses prefix completion; `S-RET' is specific
2798 ;; to Icicles and uses apropos completion. For example, you can type
2799 ;; `idea' followed by `S-RET' to switch to buffer `new-ideas.txt'.
2801 ;; Note: You can customize `icicle-top-level-key-bindings' to prevent
2802 ;; the rebinding of `C-x b' in Icicle mode.
2804 ;;(@* "Accepting Partial Matches by Default")
2805 ;; ** Accepting Partial Matches by Default **
2807 ;; For those people who prefer that a partial match always be
2808 ;; accepted immediately, regardless of the context (whether a match
2809 ;; is required or not) and without having to use `RET' or `S-RET',
2810 ;; there is Icicles user option
2811 ;; `icicle-top-level-when-sole-completion-flag'. If you set this to
2812 ;; non-`nil', then, whenever your input matches only one candidate
2813 ;; completion, that candidate is used immediately. I do not
2814 ;; recommend this practice generally, but some people might prefer
2817 ;; Option `icicle-top-level-when-sole-completion-delay' is the number
2818 ;; of seconds Icicles waits, before returning to top level with the
2819 ;; sole completion. It has no effect if
2820 ;; `icicle-top-level-when-sole-completion-flag' is `nil'. The delay
2821 ;; gives you a chance to forestall acceptance of the sole completion:
2822 ;; editing the completion (typing or deleting a character) before the
2823 ;; delay expires prevents its automatic acceptance.
2825 ;; See Also: (@* "Ido and IswitchB")
2827 ;;(@* "Ido and IswitchB")
2832 ;; Libraries Ido and IswitchB are alternatives to Icicles that also
2833 ;; enhance minibuffer completion in various ways. Their UIs are
2834 ;; similar to each other - Ido essentially extends IswitchB's
2835 ;; buffer-name completion to file names as well. Neither completes
2836 ;; other kinds of candidates. They work only for buffer names or
2837 ;; file names, but you can advise the standard completion functions
2838 ;; to get them to use Ido completion more generally.
2840 ;; The behavior of Ido and IswitchB is different from the default
2841 ;; Icicles behavior. If you prefer their behavior for buffers then
2842 ;; you can just use IswitchB and Icicles together. You cannot use
2843 ;; Icicles and Ido together, however - they use the minibuffer in
2844 ;; incompatible ways.
2846 ;; The default behavior of Icicles is different, but you can make
2847 ;; Icicles behave more like Ido if you like. It would be a mistake
2848 ;; to look for a complete reproduction of the Ido behavior in
2849 ;; Icicles, however. If you want exactly the same behavior as Ido,
2850 ;; then use Ido. ;-)
2852 ;; The Icicles UI is different by design. Some of this difference in
2853 ;; approach has to do with the fact that Ido is specialized to
2854 ;; buffer- and file-name completion. The generality of Icicles makes
2855 ;; a different approach appropriate. Icicles has many additional
2856 ;; features that are not available in other libraries, but its main
2857 ;; advantage is its generality: you use the same user interface for
2858 ;; input of any kind. As you learn more about Icicles you may begin
2859 ;; to appreciate its approach, even if you are a diehard Ido addict.
2861 ;; This section summarizes some differences between Icicles and Ido
2862 ;; and tells you how you can get more Ido-like behavior in Icicles if
2863 ;; that's what you prefer. It does not cover Icicles features that
2864 ;; have no counterpart in Ido or features that they have in common
2865 ;; (except to emphasize some differences).
2867 ;; If you have the Ido habit but want to give Icicles a try, then
2868 ;; this section is for you. I recommend, however, that you give the
2869 ;; default Icicles behavior a good try before convincing yourself
2870 ;; that you still prefer a more Ido-like approach.
2872 ;; See also the references at the section end for other sections that
2873 ;; go into more detail about some of the things mentioned here.
2875 ;; 1. Incremental completion. By default, Icicles does not turn on
2876 ;; incremental completion until you have hit `TAB' or `S-TAB' to
2877 ;; display the matching candidates. Ido turns it on immediately.
2878 ;; You can get that behavior by setting option
2879 ;; `icicle-show-Completions-initially-flag' to `t'.
2881 ;; You can get an intermediate behavior in this regard by instead
2882 ;; setting option `icicle-incremental-completion-flag' to a value
2883 ;; other than `nil' and `t'. That makes Icicles show the matching
2884 ;; candidates as soon as you start typing input. See also option
2885 ;; `icicle-incremental-completion-delay'.
2887 ;; 2. Matching. By default, Ido uses substring matching for
2888 ;; completion. You can hit a key to switch to prefix matching,
2889 ;; "flex" matching, or regexp matching. Icicles gives you these
2890 ;; same matching possibilities, and more. (What Ido calls "flex"
2891 ;; matching Icicles calls "scatter" matching.) The main
2892 ;; difference here is that Icicles regexp support is general and
2893 ;; complete. Regexp-matching in Ido does not work with Ido-style
2896 ;; 3. Current candidate, cycling, sorting. Both Ido and Icicles have
2897 ;; a notion of "current candidate". In Ido, completion candidates
2898 ;; are presented in a predefined sort order, most recently used
2899 ;; first. The current candidate is the first one. You cycle
2900 ;; candidates by moving the first to last or the last to first.
2902 ;; In Icicles, you can switch among any number of sort orders at
2903 ;; any time by hitting a key. (And you can easily define your own
2904 ;; sort orders.) When you cycle candidates, the candidates stay
2905 ;; in order. If the candidates are displayed in `*Completions*'
2906 ;; then the current one is highlighted there, in place. The
2907 ;; highlight moves, not the candidate.
2909 ;; 4. Input editing. In Ido, cycling does not replace your input by
2910 ;; the current candidate. To edit the current candidate you hit a
2911 ;; key to enter an edit mode (recursive minibuffer). In Icicles,
2912 ;; cycling replaces your input in the minibuffer by the current
2913 ;; candidate, so you can just edit it there normally. You can use
2914 ;; `C-l' to retrieve your original input.
2916 ;; 5. Completions shown. In Ido, a limited number of matching
2917 ;; completion candidates are shown in the minibuffer. You can hit
2918 ;; a key to see all matches in a separate buffer.
2920 ;; In Icicles, completion candidates are always shown in buffer
2921 ;; `*Completions*', not in the minibuffer. You can limit the
2922 ;; number of matches shown by customizing option
2923 ;; `icicle-max-candidates'. Only the first
2924 ;; `icicle-max-candidates' (in the current sort order) are shown.
2926 ;; You can also increment and decrement this truncation value on
2927 ;; the fly during completion, by hitting `C-x #' and then using
2928 ;; the vertical arrow keys or the mouse wheel. (For that feature
2929 ;; you also need library `doremi.el'.)
2931 ;; 6. Auto-choice of sole candidate. In Ido, if there is only one
2932 ;; match for your input then `TAB', which normally completes, also
2933 ;; chooses that candidate - you do not need to hit `RET'. By
2934 ;; default, Icicles always requires you to explicitly choose with
2935 ;; `RET' (or `C-RET'). If you set option
2936 ;; `icicle-top-level-when-sole-completion-flag' to non-`nil', then
2937 ;; Icicles provides similar behavior to Ido. See also option
2938 ;; `icicle-top-level-when-sole-completion-delay'.
2940 ;;(@* "Ido-Like Behavior Everywhere: `icicle-ido-like-mode'")
2941 ;; ** Ido-Like Behavior Everywhere: `icicle-ido-like-mode' **
2943 ;; If you want Icicles to be Ido-like in general, then turn on global
2944 ;; minor mode `icicle-ido-like-mode' (not available in Emacs 20).
2945 ;; Doing that sets options `icicle-show-Completions-initially-flag'
2946 ;; and `icicle-top-level-when-sole-completion-flag' to `t'. Turning
2947 ;; the mode off sets them to `nil'.
2949 ;; You can simultaneously set option `icicle-max-candidates' when you
2950 ;; turn on `icicle-ido-like-mode', by using a positive prefix
2951 ;; argument. If you want the option to keep that value when you turn
2952 ;; the mode off, then use a zero or negative prefix argument.
2953 ;; Otherwise, it is reset to `nil' (no limit on the number of
2954 ;; candidates displayed).
2956 ;; When you use this mode, you might also want to use `nil' or `t' as
2957 ;; the value of option `icicle-default-value', in order to not insert
2958 ;; the default value in the minibuffer. If you want to change that
2959 ;; option dynamically for the mode, use `icicle-ido-like-mode-hook'.
2962 ;; (add-hook 'icicle-ido-like-mode-hook
2963 ;; (lambda () (setq icicle-default-value
2964 ;; (if icicle-ido-like-mode t 'insert-end))))
2966 ;;(@* "Ido-Like Behavior for Buffers and Files")
2967 ;; ** Ido-Like Behavior for Buffers and Files **
2969 ;; If you want Ido-like behavior in Icicles for buffers or files, but
2970 ;; not in general, then customize either or both options
2971 ;; `icicle-buffers-ido-like-flag' and `icicle-files-ido-like-flag' to
2976 ;; * (@> "Exiting the Minibuffer Without Confirmation")
2977 ;; * (@file :file-name "icicles-doc2.el" :to "Customization and General Tips"):
2978 ;; `icicle-buffer-require-match-flag',
2979 ;; `icicle-deletion-action-flag',
2980 ;; `icicle-file-require-match-flag',
2981 ;; `icicle-show-Completions-initially-flag',
2982 ;; `icicle-incremental-completion-flag',
2983 ;; `icicle-incremental-completion-delay',
2984 ;; `icicle-max-candidates',
2985 ;; `icicle-regexp-quote-flag',
2986 ;; `icicle-top-level-when-sole-completion-flag',
2987 ;; `icicle-top-level-when-sole-completion-delay',
2988 ;; * (@file :file-name "icicles-doc2.el" :to "Fuzzy Completion")
2989 ;; * (@> "Special Characters in Input Patterns")
2990 ;; * (@> "Prefix Completion and Apropos Completion")
2991 ;; * http://www.emacswiki.org/emacs/IciclesDiscussion#IdoAndIcicles
2992 ;; (out-of-date discussion, but it might be helpful)
2994 ;;(@* "*Completions* Display")
2996 ;; *Completions* Display
2997 ;; ---------------------
2999 ;; Icicles enhances the `*Completions*' display in several ways. The
3000 ;; following features are available whenever buffer `*Completions*'
3003 ;; * In buffer `*Completions*', you can use the arrow keys (`down',
3004 ;; `up', `right', `left') to navigate among the candidate
3005 ;; completions. The current candidate (under the cursor) is
3008 ;; * When you cycle completions in the minibuffer:
3010 ;; - The current candidate is highlighted in `*Completions*'.
3012 ;; - Help on the current candidate (typically, the first line of a
3013 ;; doc string) is displayed in the mode line, provided user
3014 ;; option `icicle-help-in-mode-line-delay' is greater than zero.
3016 ;; * The total number of completion candidates is displayed in the
3017 ;; mode-line of buffer `*Completions*' - e.g. `567 candidates'.
3018 ;; If the number of candidates is currently truncated (because of
3019 ;; option `icicle-max-candidates' - see
3020 ;; (@file :file-name "icicles-doc2.el" :to "Customization and General Tips"),
3021 ;; then the total number of candidates before truncation is also
3022 ;; shown - e.g. `149 shown / 567'.
3024 ;; * You can use `C-insert' to move back and forth between the
3025 ;; minibuffer and `*Completions*'. In each direction, the current
3026 ;; candidate is tracked in the destination buffer. For example, if
3027 ;; the candidate in the minibuffer is `foobar', after you hit
3028 ;; `C-insert' the cursor is on `foobar' in `*Completions*'. In the
3029 ;; other direction, if the cursor is on `foobar' in
3030 ;; `*Completions*', after you hit `C-insert' the current input in
3031 ;; the minibuffer is `foobar'.
3033 ;; * `*Completions*' can also serve as a new kind of icompletion help
3034 ;; - see (@> "Icompletion").
3036 ;; * You can choose multiple candidates during completion, by
3037 ;; clicking them with `mouse-2' while holding the Control key
3038 ;; pressed. See (@> "Multi-Commands"). You can choose a set of
3039 ;; candidates in additional ways, and then act on all of them - see
3040 ;; (@> "Sets of Completion Candidates").
3042 ;; * Icicles dynamically resizes the `*Completions*' window
3043 ;; vertically, to fit the current set of completion candidates.
3044 ;; The window is not resized, however, if buffer `*Completions*'
3045 ;; appears in its own frame. (It is also not resized in Emacs
3046 ;; releases prior to 21.)
3048 ;; You can control this automatic resizing generally or on a
3049 ;; per-command basis:
3051 ;; * User option `icicle-Completions-window-max-height' is the
3052 ;; maximum number of lines to show in the `*Completions*'
3055 ;; * You can override the behavior of option
3056 ;; `icicle-Completions-window-max-height' for any given command,
3057 ;; by setting property `icicle-Completions-window-max-height' on
3058 ;; the command symbol to a different maximum window height
3059 ;; value. This property value is predefined for commands, such
3060 ;; as `icicle-buffer' and `icicle-file', that do not involve the
3061 ;; content of the current buffer during completion. A large
3062 ;; value is used for these commands, so that nearly all of the
3063 ;; frame real estate is given to the `*Completions*' window.
3065 ;; For example, you can use the following code to set the maximum
3066 ;; `*Completions*' height for command `foo' to 100 and turn off
3067 ;; per-command control of the height for command `bar'. If you use
3068 ;; such code, evaluate it after you load Icicles.
3070 ;; (put 'foo 'icicle-Completions-window-max-height 100)
3071 ;; (put 'bar 'icicle-Completions-window-max-height nil)
3073 ;; * Starting with Emacs 23, if you also use Do Re Mi library
3074 ;; `doremi-frm.el', then you can use `C-x -' in the minibuffer to
3075 ;; zoom the `*Completions*' buffer text, shrinking or enlarging it
3076 ;; incrementally using `-' or `=', respectively (`=' is typically
3077 ;; on the same keyboard key as `+', but it needs no Shift).
3079 ;; Also starting with Emacs 23 (whether or not you use
3080 ;; `doremi-frm.el'), you can specify an initial text-scale amount
3081 ;; for the `*Completions*' text, by customizing option
3082 ;; `icicle-Completions-text-scale-decrease'. This controls the
3083 ;; default appearance.
3085 ;; You typically use these features to make the `*Completions*'
3086 ;; text a bit smaller and thus save screen real estate - show more
3087 ;; candidates in less space. However, Emacs 23 text-scaling does
3088 ;; not by itself let you recuperate the saved window space - it
3089 ;; shrinks the text, but it does not shrink the window accordingly.
3090 ;; For that, you also need library `face-remap+.el' and its option
3091 ;; `text-scale-resize-window', which lets you resize the window or
3092 ;; not, horizontally, vertically, or in both directions.
3094 ;; (For example, you might set `split-width-threshold' to a small
3095 ;; number, so `*Completions*' appears on the side rather than above
3096 ;; or below other windows, and in that case you might want to
3097 ;; resize it only horizontally.)
3099 ;; If you use library `oneonone.el' with a standalone
3100 ;; `*Completions*' frame, then see option
3101 ;; `1on1-completions-frame-zoom-font-difference'.
3103 ;; * Icicles varies the number of columns used to display completion
3104 ;; candidates, for a better fit. You can tweak this with options
3105 ;; `icicle-candidate-width-factor' and
3106 ;; `icicle-inter-candidates-min-spaces'.
3108 ;; If you use Do Re Mi (library `doremi.el'), then you can modify
3109 ;; these options incrementally during completion, seeing the effect
3110 ;; as they change. Use `C-x w' or `C-x |' from the minibuffer,
3111 ;; then use the arrow keys or the mouse wheel to increment and
3112 ;; decrement the current value. WYSIWYG.
3114 ;; Why is this important enough to merit changing it dynamically,
3115 ;; instead of just customizing the options once and for all?
3116 ;; Because different sets of candidates have different candidate
3117 ;; lengths and distributions of those lengths. Play with it a bit
3118 ;; and you will see. One size does not fit all in an ideal way.
3120 ;; * You can use `C-x .' (`icicle-toggle-hiding-common-match') in the
3121 ;; minibuffer at any time during completion to toggle hiding of the
3122 ;; matched portions of the candidates in `*Completions*'. This
3123 ;; portion is replaced by ellipsis, `...'. (In Emacs 20, it is
3124 ;; replaced by nothing.)
3126 ;; This can be useful when you do not care about the text that
3127 ;; matches or when that text is particularly long. For example, if
3128 ;; you use `icicle-find-file-absolute' (`C-u C-x C-f') and the
3129 ;; completion candidates are absolute file names that share a
3130 ;; common directory, it can be convenient to hide the directory
3131 ;; portion that is common to all candidates.
3133 ;; * Starting with Emacs 22, thumbnail images are shown in
3134 ;; `*Completions*' for candidates that are (relative or absolute)
3135 ;; names of image files, if option
3136 ;; `icicle-image-files-in-Completions' is non-`nil' (it is `t' by
3137 ;; default). If the option value is `image-only', then only the
3138 ;; thumbnail images are shown. If it is otherwise non-`nil' then
3139 ;; the file names are also shown. You can cycle the option value
3140 ;; using `C-x t' in the minibuffer at any time during completion.
3142 ;; * You can scroll `*Completions*' down using `C-v', and up using
3143 ;; `M-v'. You can use `C-u' at any time to reverse the scroll
3144 ;; directions. In Emacs 22 or later, you can also use the mouse
3145 ;; wheel to scroll `*Completions*'.
3147 ;; * You can lay completion candidates out vertically, if you like,
3148 ;; instead of horizontally (the default). To do that, customize
3149 ;; option `icicle-completions-format' to have the value `vertical'.
3151 ;; Starting with Emacs 23.2, this is also possible in vanilla
3152 ;; Emacs, and the vanilla option for this is `completions-format'.
3153 ;; The default value of `icicle-completions-format' is the value of
3154 ;; `completions-format', so if you prefer you can simply use the
3155 ;; vanilla Emacs option. Vertical layout works in Icicles for all
3156 ;; Emacs versions, starting with Emacs 20.
3158 ;; Unlike the case for vanilla Emacs, in Icicles the arrow keys in
3159 ;; buffer `*Completions*' correctly reflect the candidate order
3160 ;; (e.g. as currently sorted). This also means that candidate
3161 ;; cycling acts properly for a vertical layout.
3163 ;; Note: For visual clarity, a `vertical' value is overridden
3164 ;; (ignored) when multi-line multi-completions are used - the
3165 ;; layout is horizontal. See (@> "Customization and General Tips")
3166 ;; for more information.
3168 ;; * In some cases, Icicles adds one or more additional, proxy
3169 ;; completion candidates. These are placeholders for real
3170 ;; candidates. If you choose a proxy candidate, then the real
3171 ;; candidate that is referred to is used. Typical proxy candidates
3172 ;; include a reference to a name under the cursor, a reference to
3173 ;; whatever you then click `mouse-2' on, and a reference to a name
3174 ;; that is the value of a variable.
3176 ;; The inclusion of proxy candidates is controlled by user option
3177 ;; `icicle-add-proxy-candidates-flag'. You can toggle this
3178 ;; inclusion at any time during completion, using `C-M-_'. For
3179 ;; performance reasons, you must re-invoke some commands after
3180 ;; toggling the flag on, to make the proxy candidates available.
3184 ;; . When you read a file name with completion, the proxy
3185 ;; candidates include the following (reading a face name is
3188 ;; - `*mouse-2 file name*' - proxy for a file name that you
3189 ;; click with `mouse-2'.
3191 ;; - `*point file name*' - proxy for the file name at point (if
3194 ;; - Single-quoted names of file-name variables - proxy for the
3197 ;; . When a command reads input using `icicle-read-number' or
3198 ;; `icicle-read-string-completing', the proxy candidates are all
3199 ;; variables whose values are numbers or strings, respectively.
3200 ;; You can choose such a proxy candidate to use its value. (All
3201 ;; candidates are proxy candidates for these functions.)
3203 ;; . When you use command `icicle-read-color', the proxy
3204 ;; candidates include the following:
3206 ;; - `*point foreground*' - proxy for the foreground color at
3207 ;; the cursor position (point).
3209 ;; - `*mouse-2 foreground*' - proxy for the foreground color
3210 ;; where you then click `mouse-2'.
3212 ;; - `*copied foreground*' - proxy for a previously copied
3213 ;; foreground color, the value of variable
3214 ;; `eyedrop-picked-foreground'.
3216 ;; - Background versions of the first three: `*copied
3217 ;; background*' etc.
3219 ;; - Single-quoted names of color-valued variables - proxy for
3220 ;; the variable value.
3223 ;; (@> "Different Places for Saving and Retrieving Candidates")
3224 ;; for information about using `C-M-{' in the minibuffer to
3225 ;; retrieve the value of any variable as minibuffer input.
3227 ;; Gotcha: Your minibuffer input is matched against proxy
3228 ;; candidates, as usual. If `insert-default-directory' is
3229 ;; non-`nil' when you use `C-x d' (`icicle-dired') then the default
3230 ;; directory is inserted as part of your input. If you use `TAB'
3231 ;; for completion then you will first need to use `M-k' to remove
3232 ;; the directory, as it will not match any of the proxy candidates.
3234 ;; * Clicking `C-mouse-3' on a candidate in `*Completions*' pops up a
3235 ;; contextual menu for acting on completion candidates. You can
3236 ;; customize the menu using option
3237 ;; `icicle-Completions-mouse-3-menu-entries'. By default, the menu
3238 ;; has the following submenus:
3240 ;; . `This Candidate' - Act on the candidate that you clicked to
3241 ;; pop up the menu. Or act on all current candidates,
3242 ;; individually or collectively.
3244 ;; . `Sorting' - Change the current candidate sort order.
3246 ;; . `Save/Retrieve' - Save (mark) candidates or retrieve them,
3247 ;; including to/from a variable or a cache file.
3249 ;; . `Sets' - Perform operations on sets of candidates, in
3250 ;; particular, the set of current candidates and the set of
3251 ;; saved candidates.
3253 ;; . `Toggle/Cycle/Change' - Toggle, cycle, or otherwise change an
3254 ;; Icicles setting, altering the behavior on the fly.
3256 ;; . `Miscellaneous' - Other candidate operations and general
3259 ;; The popup menu is contextual. In particular, the available
3260 ;; items can change depending on whether you use a prefix argument
3261 ;; (`C-u C-mouse-3') and whether you have selected candidates using
3262 ;; the region (e.g. mouse drag). The menu also provides a good
3263 ;; reminder of key bindings available during completion.
3265 ;; There are lots more Icicles features that enhance the display and
3266 ;; behavior of `*Completions*' in some way. Read on...
3270 ;; * (@> "Moving Between the Minibuffer and Other Buffers"), for
3271 ;; information on the `pause' key, which is somewhat related to
3272 ;; using `C-insert'.
3274 ;; * (@file :file-name "icicles-doc2.el" :to "Candidates with Text Properties")
3275 ;; and (@file :file-name "icicles-doc2.el" :to "Programming Multi-Completions")
3276 ;; for information about using text properties in `*Completions*'.
3277 ;; These sections are for Emacs-Lisp programmers.
3279 ;;(@* "Icompletion")
3284 ;; Emacs incremental completion, or icompletion, provided by standard
3285 ;; library `icomplete.el', displays matching prefix completions in
3286 ;; the minibuffer. This display is updated incrementally as you type
3287 ;; characters. In spite of the name, icompletion does not, in fact,
3288 ;; provide any completion; it provides completion help, letting you
3289 ;; know which (prefix) completions are available.
3291 ;; Icicles enhances Emacs icompletion in three ways:
3293 ;; 1. It works with my library `icomplete+.el' to provide minibuffer
3294 ;; feedback on the number of completion candidates.
3296 ;; 2. It highlights the part of your input that does not match any
3297 ;; completion candidate.
3299 ;; 3. It provides a new kind of icompletion, using buffer
3302 ;;(@* "icomplete+.el Displays the Number of Other Prefix Candidates")
3303 ;; ** icomplete+.el Displays the Number of Other Prefix Candidates **
3305 ;; Library `icomplete+.el' enhances `icomplete.el' in various ways.
3306 ;; One of these ways is to complement Icicles by displaying the
3307 ;; number of other prefix-completion candidates when cycling. This
3308 ;; number is displayed whenever you change direction when cycling.
3311 ;; M-x forward-line [Matched] (13 more)
3313 ;; Like `icomplete.el', `icomplete+.el' provides help for only prefix
3314 ;; completions, not apropos completions. (Reminder: There is no
3315 ;; icompletion for file-name completion - see standard library
3318 ;;(@* "Icompletion in *Completions*: Apropos and Prefix Completion")
3319 ;; ** Icompletion in *Completions*: Apropos and Prefix Completion **
3321 ;; Buffer `*Completions*' shows you the current set of candidates for
3322 ;; either prefix or apropos completion. Together, user options
3323 ;; `icicle-incremental-completion-flag',
3324 ;; `icicle-incremental-completion-delay', and
3325 ;; `icicle-incremental-completion-threshold' control incremental
3326 ;; updating of `*Completions*'.
3328 ;; If `icicle-incremental-completion-flag' is non-`nil', then
3329 ;; `*Completions*' is automatically updated when you change your
3330 ;; input in the minibuffer - that is, with each character that you
3331 ;; type or delete. This is another form of icompletion, unique to
3332 ;; Icicles. It uses buffer `*Completions*', instead of the
3333 ;; minibuffer, to show the completion help.
3335 ;; The particular non-`nil' value of
3336 ;; `icicle-incremental-completion-flag' determines when
3337 ;; `*Completions*' is displayed and updated. The default value, `t',
3338 ;; means that `*Completions*' is updated only if it is already
3339 ;; displayed. Use `t' if you do not want `*Completions*' to be too
3340 ;; intrusive but you want it to provide the most help when you ask
3341 ;; for help (via `TAB' or `S-TAB').
3343 ;; Any other non-`nil' value displays and updates `*Completions*'
3344 ;; whenever there is more than one completion candidate. That can be
3345 ;; more helpful, but it can also be more distracting. A value of
3346 ;; `nil' turns off automatic updating altogether - `*Completions*' is
3347 ;; then displayed only upon demand. I find that `t' represents a
3348 ;; good compromise, providing help when I ask for it, and then
3349 ;; continuing to help until I've finished choosing a candidate.
3351 ;; Option `icicle-incremental-completion-delay' is the number of
3352 ;; seconds to wait before updating `*Completions*' incrementally. It
3353 ;; has an effect only when the number of completion candidates is
3354 ;; greater than `icicle-incremental-completion-threshold'. This
3355 ;; delay can improve performance when there are many candidates. It
3356 ;; lets you type ahead before any redisplay occurs; otherwise,
3357 ;; redisplay occurs for each character you type or delete.
3359 ;; You can toggle incremental completion at any time (changing
3360 ;; `icicle-incremental-completion-flag' between `nil' and `t') using
3361 ;; command `icicle-toggle-incremental-completion', which is bound to
3362 ;; `C-#' in the minibuffer. If the number of completion candidates
3363 ;; is very large, then use `C-#' to toggle incremental completion off
3364 ;; - that will save time by not updating `*Completions*'. See also
3365 ;; (@> "Dealing With Large Candidate Sets") for other ways to deal
3366 ;; with a large number of candidates.
3368 ;; Note: Incremental completion is effectively turned off when a
3369 ;; remote file name is read, that is, whenever your file-name input
3370 ;; matches a remote-file syntax.
3372 ;; There are several advantages of using `*Completions*' for
3373 ;; icompletion, as opposed to the minibuffer:
3375 ;; 1. Many more candidates can be displayed in `*Completions*' than
3376 ;; can be displayed by standard icompletion, which uses the
3377 ;; minibuffer for feedback.
3379 ;; 2. Standard (minibuffer) icompletion provides feedback only on
3380 ;; matches for prefix completion. If you use both standard
3381 ;; icompletion and Icicles icompletion, you can have incremental
3382 ;; help for both prefix completion and apropos completion at the
3383 ;; same time, one in the minibuffer and the other in
3386 ;; 3. The other Icicles `*Completions*' features are available for
3387 ;; the current set of matching candidates: cycling, highlighting
3388 ;; of match root, highlighting of previously used candidates, and
3389 ;; so on. See (@> "*Completions* Display").
3391 ;;(@* "Icicles Highlights the Input that Won't Complete")
3392 ;; ** Icicles Highlights the Input that Won't Complete **
3394 ;; When you are typing or correcting your input during completion,
3395 ;; Icicles highlights the part of your minibuffer input that prevents
3396 ;; it from matching any completion candidates, by default. This
3397 ;; works for both prefix completion and apropos completion. For
3398 ;; both, it highlights your input from the leftmost mismatch through
3401 ;; You can use `C-M-l' to move the cursor to the start of the
3402 ;; highlighted, mismatched part of your input. Repeat `C-M-l' to
3403 ;; kill the highlighted portion. (Because it is killed, `C-y' yanks
3406 ;; User options `icicle-incremental-completion-flag',
3407 ;; `icicle-test-for-remote-files-flag',
3408 ;; `icicle-highlight-input-completion-failure',
3409 ;; `icicle-highlight-input-completion-failure-delay', and
3410 ;; `icicle-highlight-input-completion-failure-threshold' control this
3411 ;; highlighting, which is done using face
3412 ;; `icicle-input-completion-fail' (for strict completion) or
3413 ;; `icicle-input-completion-fail-lax' (for lax completion).
3415 ;; If either `icicle-incremental-completion-flag' or
3416 ;; `icicle-highlight-input-completion-failure' is `nil', then no such
3417 ;; highlighting is done. Remember that you can toggle incremental
3418 ;; completion using `C-#' in the minibuffer.
3420 ;; Because this highlighting can have a negative impact on
3421 ;; performance, you can fine-tune when you want it to occur. The
3422 ;; value of `icicle-highlight-input-completion-failure' determines
3423 ;; when this highlighting can take place.
3425 ;; In particular, highlighting the non-matching part of remote file
3426 ;; names can be slow. Two values of the option allow remote file
3427 ;; name highlighting: `always' and `explicit-remote'. The other
3428 ;; values do not highlight remote file names. You probably do not
3429 ;; want to use a value of `always'.
3431 ;; If the value is `nil', then highlighting never occurs. If the
3432 ;; value is `explicit-strict', `explicit', or `explicit-remote', then
3433 ;; highlighting occurs only upon demand: when you hit `TAB' or
3434 ;; `S-TAB' to request completion. If the value is `implicit-strict',
3435 ;; `implicit', or `always', then highlighting occurs also when you
3436 ;; update input during incremental completion (if incremental
3437 ;; completion is turned on).
3439 ;; I use a value of `implicit' myself, but the default value is
3440 ;; `implicit-strict' because, depending on your setup and use cases,
3441 ;; `implicit' can impact performance for file-name completion (which
3442 ;; is lax, not strict). I suggest you try `implicit' to see - this
3443 ;; feature is especially useful for file names.
3445 ;; TIP: An alternative way to be informed about a file name
3446 ;; mismatch (when you use `TAB' or `S-TAB') is to use
3447 ;; `icicle-no-match-hook' to signal you using a visual or
3448 ;; audible cue. For example:
3450 ;; (add-hook 'icicle-no-match-hook
3452 ;; (when (icicle-file-name-input-p) (ding))))
3454 ;; Summary of `icicle-highlight-input-completion-failure' choices:
3457 ;; `explicit-strict' Only on demand and only during strict completion
3458 ;; `explicit' Only on demand (lax and strict completion)
3459 ;; `explicit-remote' Only on demand, even for remote file names
3460 ;; `implicit-strict' Incremental or explicit completion - strict only
3461 ;; `implicit' Incremental/explicit, lax/strict completion
3462 ;; `always' Always (including for remote file names)
3464 ;; These values are listed here in terms of increasing
3465 ;; permissiveness, which also can mean increasing performance impact.
3466 ;; That is, a value of `implicit' is more likely to affect
3467 ;; performance than a value of `explicit'. The greatest performance
3468 ;; hit comes from file-name matching, in particular if remote files
3471 ;; If you know that you will not be using remote file names for a
3472 ;; while, you can let Icicles and Tramp know this by using the toggle
3473 ;; `C-^' in the minibuffer to turn off option
3474 ;; `icicle-test-for-remote-files-flag'. When this is off, you cannot
3475 ;; use remote files.
3477 ;; Turning off `icicle-test-for-remote-files-flag' using `C-^' turns
3478 ;; off Tramp's remote file-name completion and remote file handling.
3479 ;; If you turn off the option using `C-^', then turn it back on using
3480 ;; `C-^' also (instead of just setting the option to non-`nil'), in
3481 ;; order to re-enable Tramp's file-name handling and completion.
3483 ;; Turning off `icicle-test-for-remote-files-flag' can slightly speed
3484 ;; up file-name completion for local files, by avoiding any check for
3485 ;; remote file names. If you seldom use remote files, then you might
3486 ;; want to customize `icicle-test-for-remote-files-flag' to `nil' and
3487 ;; use `C-^' to toggle it back on whenever you do use remote files.
3489 ;; A `nil' value of `icicle-test-for-remote-files-flag' also
3490 ;; overrides the `icicle-highlight-input-completion-failure' values
3491 ;; `implicit-strict', and `explicit-strict' for file-name completion,
3492 ;; treating them the same as `implicit'. It is assumed that you use
3493 ;; those values only to avoid the cost of remote file-name matching.
3495 ;;(@* "Sorting Candidates and Removing Duplicates")
3497 ;; Sorting Candidates and Removing Duplicates
3498 ;; ------------------------------------------
3500 ;; By default, completion candidates are usually presented in buffer
3501 ;; `*Completions*' in alphabetic order. But some commands use
3502 ;; different sort orders by default. Whatever sort order is used for
3503 ;; `*Completions*' is also the order of cycling among candidates.
3505 ;; Also, duplicate candidates are typically removed as completion
3506 ;; choices, by default. But for some commands duplicates are
3507 ;; appropriate, so they are not removed. For example, command
3508 ;; `icicle-search' (`C-c `') uses completion to navigate among search
3509 ;; hits. Duplicate search hits are retained. Although some
3510 ;; search-hit candidates might have the same text, they are located
3511 ;; at different buffer positions.
3513 ;; You can interactively control the order of candidates and whether
3514 ;; duplicates are removed. Use `C-,' during completion to choose a
3515 ;; different sort order or to turn off sorting altogether (one of the
3516 ;; available sort orders is in fact called "turned OFF"). Use `C-$'
3517 ;; to toggle the removal of duplicate candidates. A few commands,
3518 ;; for which sorting is inappropriate, prevent you from sorting.
3520 ;; The available sort orders for `C-,' are those defined by user
3521 ;; option `icicle-sort-orders-alist' - see
3522 ;; (@> "Defining New Sort Orders"), below. However, some commands
3523 ;; adjust this list of possibilities by adding command-relevant sort
3524 ;; orders or removing some that might be inappropriate.
3526 ;; The sort order generally remains as you last set it, for
3527 ;; subsequent commands. However, if the last order you set is
3528 ;; inappropriate for the current command then sorting is turned off.
3529 ;; You can then use `C-,' to choose a sort order appropriate for the
3532 ;;(@* "Changing the Sort Order")
3533 ;; ** Changing the Sort Order **
3535 ;; There are a couple of ways to use `C-,' (bound to command
3536 ;; `icicle-change-sort-order'). Its behavior depends on the value of
3537 ;; user option `icicle-change-sort-order-completion-flag', which is
3538 ;; `nil' by default. This value means to simply cycle to the next
3539 ;; sort order each time you hit `C-,'. A non-`nil' value means to
3540 ;; use completion to choose another sort order. If you have many
3541 ;; available sort orders, then you might prefer a non-`nil' value.
3542 ;; In any case, you can also change this behavior on the fly: using
3543 ;; plain `C-u' (no number) with `C-,' reverses the meaning of
3544 ;; `icicle-change-sort-order-completion-flag' for `C-,'.
3546 ;; However, a numeric prefix argument, such as `C-9', means to simply
3547 ;; reverse the direction of the current sort order; it invokes
3548 ;; command `icicle-reverse-sort-order'. For example, if candidates
3549 ;; are sorted alphabetically from A to Z, then `C-9 C-,' flips the
3550 ;; sort order, so that from then on sorting is from Z to A. If
3551 ;; buffer names are sorted from small to large buffer size, then `C-9
3552 ;; C-,' sorts large buffers first. This works for all sort orders.
3553 ;; The new sort order is echoed, so you can use this twice to just
3554 ;; remind yourself of the current sort order.
3556 ;; In addition to the current sort order, which is defined by the
3557 ;; value of user option `icicle-sort-comparer', an alternative sort
3558 ;; order is available at all times. It is the value of option
3559 ;; `icicle-alternative-sort-comparer'. By default, this sorts
3560 ;; candidates into two alphabetical groups: those previously used as
3561 ;; accepted input, followed by those not yet used.
3563 ;; Just as you can choose a different current sort order using `C-,',
3564 ;; so you can choose a different alternative sort order using `M-,'.
3566 ;; How do you actually use the alternative sort order? Use `C-M-,'
3567 ;; (command `icicle-toggle-alternative-sorting') to swap the
3568 ;; alternative sort for the current sort. This is the quickest way
3569 ;; to flip between two sort orders. If, for example, you set your
3570 ;; alternative sort order to "turned OFF", then this is a quick way
3571 ;; to toggle sorting on and off.
3573 ;; The first time during a session that you use a command that
3574 ;; completes a buffer name or a file name, sorting changes to (that
3575 ;; is, `icicle-sort-comparer' is set to) whatever is specified by
3576 ;; user option `icicle-buffer-sort' or `icicle-file-sort',
3577 ;; respectively, provided the option is non-`nil'. This gives you a
3578 ;; way to privilege a particular sorting method for each of these
3579 ;; kinds of completion.
3581 ;;(@* "Defining New Sort Orders")
3582 ;; ** Defining New Sort Orders **
3584 ;; When you use `C-,' or `M-,', the sort orders that you can choose
3585 ;; from are those in user option `icicle-sort-orders-alist'. You can
3586 ;; customize this option to add or remove available sort orders. A
3587 ;; better way to define a new sort order is to use macro
3588 ;; `icicle-define-sort-command' in your Emacs init file (~/.emacs).
3589 ;; This defines a new Icicles command, named `icicle-sort-ORDER',
3590 ;; where `ORDER' is the name of the new sort order. The definition
3591 ;; of the "alphabetical" sort order provides an example:
3593 ;; (icicle-define-sort-command "alphabetical"
3594 ;; icicle-case-string-less-p
3595 ;; "Sort completion candidates alphabetically.")
3597 ;; The first argument, "alphabetical", is a string naming the new
3598 ;; sort order. When you change to this sort order, a message says
3599 ;; "Sorting is now alphabetical". Whatever sort-order name you
3600 ;; provide is used in the message.
3602 ;; The second argument is the actual function used for sorting. It
3603 ;; can be any function, including a lambda expression. The function
3604 ;; takes two string arguments and returns non-`nil' if and only if
3605 ;; the first string sorts before (is "less than") the second. In
3606 ;; this case, function `icicle-case-string-less-p' is used, which
3607 ;; compares its two arguments alphabetically (lexicographically).
3608 ;; The third argument is the doc string for the new sorting command.
3610 ;; The result of this definition is:
3612 ;; 1. The creation of command `icicle-sort-alphabetical'.
3613 ;; 2. The addition of an entry for the new sort order in option
3614 ;; `icicle-sort-orders-alist'. The entry associates sort order
3615 ;; "alphabetical" with comparison function
3616 ;; `icicle-case-string-less-p'.
3618 ;; You can invoke the new sorting command any time using `M-x', but
3619 ;; you can also change to the new sort order using `C-,' (or `M-,')
3620 ;; during minibuffer completion.
3622 ;;(@* "Different Sorts for Different Sorts of Uses")
3623 ;; ** Different Sorts for Different Sorts of Uses **
3625 ;; There are many different uses of completion in Emacs, and this
3626 ;; means that sorting candidates needs to be flexible - there cannot
3627 ;; be a single sort order, or even a single set of sort orders, that
3628 ;; is useful for all purposes. Completion, and therefore also
3629 ;; sorting of completion candidates, needs to deal with different
3630 ;; types of candidates and different numbers of them, in different
3633 ;; Icicles predefines many sort functions, and you can easily define
3634 ;; more of your own. You can choose a different sort at any time, as
3635 ;; mentioned above. A good sort order can be a big help, depending
3636 ;; on the context. However, sorting is not free, and it can be
3637 ;; helpful to think for a moment about some of the consequences of
3638 ;; sorting, in terms of performance.
3640 ;; What does a sort function do? It determines which of two strings
3641 ;; should come first, that is, which is "less than" the other.
3642 ;; During sorting, pairs of candidates are compared using the sort
3643 ;; function. And each time you change your input by typing or
3644 ;; deleting a character, the new set of matching candidates is sorted
3645 ;; (if `icicle-incremental-completion-flag' is non-`nil').
3647 ;; The number of candidates to be sorted depends on the kind of
3648 ;; completion and how you use Icicles. Some Icicles users like to
3649 ;; use cycling more and completion less, which means sorting more
3650 ;; candidates. Other users favor using completion to narrow down the
3651 ;; number of matches (which I recommend). Some commands typically
3652 ;; have few possible completion candidates; others have many.
3653 ;; Buffer-name completion, for example, typically involves relatively
3654 ;; few candidates, whereas file-name completion typically involves
3657 ;; If there are many candidates matching your input, then many
3658 ;; comparisons will be made each time the candidate set is sorted.
3659 ;; This means that if your sort function is complex, response can be
3660 ;; slow. A complex sort function might be OK for sorting a small or
3661 ;; medium set of candidates, but it might not be appropriate for
3662 ;; sorting a very large set.
3664 ;; Only you, as a user, can control which sort makes the best sense
3665 ;; for you in any given situation. If you are likely to have
3666 ;; zillions of candidates in some context, then you probably will
3667 ;; want to change to a sort that computes quickly. You can, of
3668 ;; course, even choose not to sort at all, but simple sort
3669 ;; comparisons do not noticeably impact performance, even for a very
3670 ;; large number of candidates.
3672 ;; Icicles could offer a threshold option similar to
3673 ;; `icicle-incremental-completion-threshold' (or it could reuse that
3674 ;; option), and not bother to sort if the number of candidates passed
3675 ;; the threshold, but there can be many sort orders of differing
3676 ;; complexity, so a set of thresholds would really be needed, perhaps
3677 ;; one per sort order.
3679 ;; Rather than having you try to manage such complexity ahead of time
3680 ;; using options, it's better to just let you manage it at completion
3681 ;; time: Choose the sort order with knowledge of the possible
3682 ;; candidate set. For example, if the set of candidates to sort will
3683 ;; include every file on your file system, then you probably will
3684 ;; want to use a simple sort. On the other hand, there are
3685 ;; situations where you might nevertheless prefer to wait a few
3686 ;; seconds, in order to perform a complex sort that is of particular
3689 ;; In sum, Icicles keeps it simple, and leaves it up to you to choose
3690 ;; the appropriate sort order for any given context. This design
3691 ;; choice is one reason why Icicles makes it easy to choose a sort
3692 ;; even while you are completing input - each act of completion is
3695 ;; It can help you choose, however, to know which of the predefined
3696 ;; Icicles sort orders are more complex, and therefore tend to be
3697 ;; slower. Here they are:
3699 ;; Sort Order Sort Function Used
3700 ;; ---------- ------------------
3701 ;; by previous use alphabetically `icicle-historical-alphabetic-p'
3702 ;; by last use `icicle-most-recent-first-p'
3704 ;; The reason these sorts are slower is that they check the current
3705 ;; minibuffer history, to see whether, and where, each candidate is
3706 ;; located in the history list. If you, like I, have very long
3707 ;; history lists, then this can take a while. I use histories of
3708 ;; virtually unlimited length - I let library `savehist-20+.el' save
3709 ;; all of my histories from one Emacs session to the next.
3711 ;; Here are some of the Icicles sort orders that exist by default:
3713 ;; - alphabetical - see
3714 ;; (@> "Putting Previous Candidates First: `C-M-,'")
3715 ;; - case-insensitive - (@> "Completion Status Indicators")
3716 ;; - by last use as input
3717 ;; - by previous use alphabetically - see
3718 ;; (@> "Putting Previous Candidates First: `C-M-,'")
3719 ;; by color name (colors) - see
3720 ;; (@file :file-name "icicles-doc2.el" :to "Candidates with Text Properties")
3722 ;; by purity/saturation (colors)
3723 ;; by brightness/value/luminance (colors)
3724 ;; by all HSV components, in order (colors)
3725 ;; by HSV distance from a base color (colors)
3726 ;; by amount of red (colors)
3727 ;; by amount of green (colors)
3728 ;; by amount of blue (colors)
3729 ;; by all RGB components, in order (colors)
3730 ;; by RGB distance from a base color (colors)
3731 ;; 22 by key name, prefix keys first (keys)- see (@> "Completing Prefix Keys")
3732 ;; 22 by key name, local bindings first (keys)- see
3733 ;; (@> "Local Bindings Are Highlighted")
3734 ;; 22 by command name (commands)
3735 ;; - by abbrev frequency (commands) - see
3736 ;; (@> "Multi `M-x' Turns Every Command into a Multi-Command")
3737 ;; by buffer size (buffer names)
3738 ;; *...* buffers last (buffer names)
3739 ;; by major mode name (buffer names)
3740 ;; 22 by mode-line mode name (buffer names)
3741 ;; by file/process name (buffer names)
3742 ;; - by last file modification time (file names) - see
3743 ;; (@> "Icicles Commands that Read File Names")
3744 ;; - by file type (extension) (file names)
3745 ;; - by directories first or last (file names)
3746 ;; - in book order (Info) - see
3747 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Completion for Info")
3748 ;; - special candidates first - see
3749 ;; (@> "Local Bindings Are Highlighted"),
3750 ;; (@file :file-name "icicles-doc2.el" :to "Candidates with Text Properties"),
3751 ;; (@file :file-name "icicles-doc2.el" :to "Icicles OO: Object-Action Interaction")
3752 ;; - proxy candidates first - see (> "*Completions* Display")
3753 ;; - extra candidates first - see
3754 ;; (@file :file-name "icicles-doc2.el" :to "Global Filters")
3755 ;; - by second multi-completion part (multi-completions) - see
3756 ;; (@file :file-name "icicles-doc2.el" :to "Sorting Candidates by Their Second Part")
3757 ;; - turned OFF (does not sort at all)
3759 ;; As you can see, some are appropriate for color-name completion,
3760 ;; some for buffer-name completion, and some for file-name
3761 ;; completion. Some are general, appropriate for most kinds of
3764 ;; Those marked above with the label `22' can be used only with Emacs
3765 ;; 22 or later. Those marked with a hyphen (-) are defined using
3766 ;; `icicle-define-sort-command', so they correspond to explicit
3767 ;; commands whose doc you can examine. The command names in this
3768 ;; case are `icicle-sort-' followed by the sort-order names (with
3769 ;; hyphens substituted for spaces) - for example,
3770 ;; `icicle-sort-by-directories-last' and `icicle-sort-turned-OFF'.
3772 ;;(@* "Adding a Saved Sort Order")
3773 ;; ** Adding a Saved Sort Order **
3775 ;; There are many predefined sort orders (see
3776 ;; (@> "Different Sorts for Different Sorts of Uses")), and you can
3777 ;; define your own new sort orders (see
3778 ;; (@> "Defining New Sort Orders")). This section is about a unique
3779 ;; Icicles feature that lets you combine any number of sort orders
3780 ;; interactively, melding them together.
3782 ;; You do this as follows:
3784 ;; 1. Start with a given sort order (use `C-u C-,' to choose one).
3786 ;; 2. Save the set of candidates you are interested in, using `C-M->'
3787 ;; (see (@> "Saving and Retrieving Completion Candidates")). This
3788 ;; saves the candidates in their current order at the time of the
3789 ;; save: the saved order.
3791 ;; 3. Choose a different sort order (e.g., use `C-u C-,').
3793 ;; 4. Use `C-M-+' (`icicle-plus-saved-sort') to combine the two sort
3794 ;; orders, that is, the (new) current order and the saved order.
3796 ;; What `icicle-plus-saved-sort' does is sum, for each completion
3797 ;; candidate, its ranks (indexes) in the two sort orders, and then
3798 ;; reorder candidates based on the summed ranks.
3800 ;; For example, if a given candidate is the 4th candidate in the
3801 ;; current list of candidates, and it is the 7th candidate in the
3802 ;; saved list of candidates, then its combined sort rank is 4 + 7 =
3803 ;; 11. With a score of 11 it sorts after a candidate whose score is,
3804 ;; for example, 6, and before a candidate whose score is, for
3807 ;; The candidates are reordered according to the combined sort
3808 ;; orders, forming a new current order.
3810 ;; When you use `C-M-+' it does not matter what order the saved
3811 ;; candidates are in or what order you used to sort the current
3812 ;; candidates. (But you will generally want to use the same set of
3813 ;; candidates.) In particular, after using `C-M-+' the candidates
3814 ;; are typically in an order that corresponds to no predefined sort -
3817 ;; You can use `C-M-+' again if you like, to add in the saved sort
3818 ;; order again with the new current order. This gives the saved
3819 ;; order more weight than the original current sort order. Continued
3820 ;; repetition of `C-M-+' gives the saved sort order more and more
3821 ;; weight. Eventually a fixed point is reached: `C-M-+' produces no
3822 ;; further change in the order.
3824 ;; For example, consider `icicle-read-color'. With user option
3825 ;; `icicle-WYSIWYG-Completions-flag' non-`nil' (e.g. a string) it
3826 ;; lets you see the effect of `C-M-+' in a striking, graphical way.
3827 ;; However, to see the effect you will first want to use `S-pause'
3828 ;; (`icicle-toggle-highlight-saved-candidates') to turn off
3829 ;; highlighting of the saved candidates, since that highlighting
3830 ;; obscures the color highlighting.
3832 ;; Sorting by color hue shows essentially a single rainbow of
3833 ;; candidates in `*Completions*': pinks, followed by magentas,
3834 ;; purples, blues, cyans, greens, yellows, browns, reds, and grays.
3835 ;; Sorting by color brightness shows a single value gamut, the
3836 ;; brightest colors followed by dimmer and dimmer colors, down to the
3839 ;; Try `M-x icicle-read-color', sorting (`C-u C-,') first by hue.
3840 ;; Save the completion candidates (`C-M->'). Now sort by brightness
3841 ;; (`C-u C-,' again). Now use `C-M-+' to add/merge the two sort
3842 ;; orders. You now see essentially a series of rainbows, from
3843 ;; brighter to dimmer and dimmer.
3845 ;; Use `C-M-+' again, to give hue more prominence in the merged sort
3846 ;; order. And again. Keep hitting `C-M-+' until there is no more
3847 ;; apparent change in the sort order - at this point you are back to
3850 ;; You can also at any time save the candidates again, saving the
3851 ;; latest order as the new sort order. Then you can reorder the
3852 ;; current candidates using a different sort order (`C-,'). And then
3853 ;; use `C-M-+' again to merge in the newly saved order. You can play
3854 ;; this way ad infinitem.
3859 ;; * (@file :file-name "icicles-doc2.el" :to "Customization and General Tips")
3860 ;; for more about `icicle-buffer-sort' and other buffer-name
3861 ;; completion parameters.
3863 ;; * (@file :file-name "icicles-doc2.el" :to "Global Filters") for a
3864 ;; way to filter and sort the domain of discourse, that is, all
3865 ;; possible candidates, prior to any use of completion.
3867 ;;(@* "Get Help on Candidates")
3869 ;; Get Help on Candidates
3870 ;; ----------------------
3872 ;; General Icicles help is available at any time during minibuffer
3873 ;; input, by hitting `C-?' (`icicle-minibuffer-help'). This section
3874 ;; is about specific help on individual completion candidates
3877 ;; When you cycle among candidates for input, help on the current
3878 ;; candidate is shown in the mode-line, provided user option
3879 ;; `icicle-help-in-mode-line-delay' is greater than zero. This makes
3880 ;; it easy to see what each candidate means or does. Similarly, this
3881 ;; help is shown whenever your input is completed entirely to one of
3882 ;; the candidates. If you use library `lacarte.el', then mode-line
3883 ;; candidate help is even available for menu-item candidates.
3885 ;; Typically, this candidate mode-line help is the first line of the
3886 ;; candidate's doc string, but alternative help sources can be used
3887 ;; (and a doc string is not available for some kinds of candidates).
3889 ;; To see more help than what is shown in the mode-line, for each
3890 ;; candidate or any given candidate as you cycle, press and hold the
3891 ;; Control and Meta keys while using the vertical arrow keys, for
3892 ;; prefix completion, or the `prior' and `next' keys (often labeled
3893 ;; Page Up and Page Down), for apropos completion. To show help on
3894 ;; any individual candidate, navigate to it (by cycling or using
3895 ;; completion), and hit `C-M-RET' - or press Control and Meta and
3896 ;; click it with `mouse-2' (`C-M-mouse-2') in buffer `*Completions*'.
3898 ;; For example, if you use standard command `switch-to-buffer' and
3899 ;; you cycle among candidate buffer names using `C-M-end' (prefix
3900 ;; completion), then the major and minor modes of each candidate
3901 ;; buffer are described in buffer `*Help*' as the buffer name appears
3902 ;; in the minibuffer.
3904 ;; By default, you need not use the Meta key for candidate help; the
3905 ;; same bindings work with just the Control key. So, for example,
3906 ;; you can click `C-mouse-2' to get help on a candidate or use
3907 ;; `C-next' to cycle candidate help information. However, Icicles
3908 ;; multi-commands often have a different use for these bindings that
3909 ;; do not include Meta. It is only by default, when a multi-command
3910 ;; has not bound a more specific action to the plain Control
3911 ;; bindings, that you can use the sans-Meta bindings for help on
3914 ;; For example, Icicles binds `M-x', `C-x b', and `C-x C-f' to
3915 ;; multi-commands that execute a command, switch to a buffer, and
3916 ;; open a file, respectively. If you use only the Control key,
3917 ;; without the Meta key, when choosing candidates for these commands,
3918 ;; you will not get help on the candidates; instead, you will execute
3919 ;; a candidate command, switch to a candidate buffer, and open a
3920 ;; candidate file, respectively. For more information, see
3921 ;; (@> "Multi-Commands").
3923 ;;(@* "Use Candidate Help Like You Use Emacs Command `apropos'")
3924 ;; ** Use Candidate Help Like You Use Emacs Command `apropos' **
3926 ;; You can use this candidate-help functionality as a kind of
3927 ;; expanded `apropos' functionality. As an example, type `C-h v
3928 ;; out', then type `S-TAB' to display all variables that match "out"
3929 ;; (in buffer `*Completions*'). Then use `C-M-next' repeatedly to
3930 ;; cycle among those variables, displaying their documentation in the
3931 ;; `*Help*' buffer as they appear one by one in the minibuffer. Or
3932 ;; click individual variable names with `C-M-mouse-2', to display
3933 ;; their documentation.
3935 ;; The standard `apropos' commands show only the first doc-string
3936 ;; line. Icicles shows that automatically in the mode-line, and it
3937 ;; shows the complete doc string on demand when you use `C-M-'. This
3938 ;; can be handy, for instance, when you are unsure which of several
3939 ;; similarly named candidates to choose. Seeing a candidate's
3940 ;; documentation along with its name can help you decide.
3942 ;; You can click links in buffer `*Help*' to look up more info, and
3943 ;; then resume `C-M-next' where you left off, all without leaving
3946 ;; This also works with menu items, if you load library `lacarte.el'
3947 ;; as well as Icicles. As you cycle among matching menu items, the
3948 ;; corresponding command documentation is displayed in `*Help*'.
3950 ;; If you also use library `help-fns+.el' (Emacs 22 or later) or
3951 ;; library `help+.el' (or `help+20.el' for Emacs 20), then you can
3952 ;; use these Icicles features with additional help commands such as
3953 ;; `describe-file' (`C-h M-f'), `describe-keymap' (`C-h M-k'),
3954 ;; `describe-command' (`C-h C-c'), `describe-option' (`C-h o'), and
3955 ;; `describe-option-of-type'.
3957 ;; `C-h C-o', which is bound by those libraries to command
3958 ;; `describe-option-of-type', is bound in Icicle mode to
3959 ;; `icicle-describe-option-of-type' instead, which uses
3960 ;; multi-completion and is therefore more powerful.
3961 ;; See (@file :file-name "icicles-doc2.el" :to "Multi-Completions").
3962 ;; `C-h C-o' describes a user option that is of a particular custom
3963 ;; type: you match the type and the option name at the same time.
3965 ;; As an example, try `C-h C-o ici C-M-j string S-TAB' (`C-M-j' just
3966 ;; separates the option name and type parts). In buffer
3967 ;; `*Completions*', you see all options whose name contains `ici' and
3968 ;; whose type (or an inherited type) definition contains `string'.
3969 ;; That means not only options that are strings, but options that are
3970 ;; lists that contain string elements, options that can be a string
3971 ;; or something else, and so on.
3973 ;; Browse the doc for these options, one after the other, using
3974 ;; `C-M-next'. This is a way to see, at the same time, the
3975 ;; documentation for individual options (in buffer `*Help*') and the
3976 ;; types their values must satisfy (in `*Completions*').
3978 ;; And remember that you can leave the option-name part or the type
3979 ;; part empty, to see all options of a certain type or options of all
3980 ;; types with a certain name pattern. For example, `C-h C-o .* C-M-j
3981 ;; string S-TAB' or `C-h C-o ici S-TAB'.
3983 ;; And you can of course use progressive completion as well, to
3984 ;; match, say, a type that has a `string' component and an `integer'
3985 ;; component - or whatever. The type part of a completion candidate
3986 ;; is an entire `defcustom' type, so its `:tag' values are also
3987 ;; included. This means that you can also match against the
3988 ;; descriptive text (tag) that appears next to a value component in
3991 ;; `C-h C-o' is a powerful way to browse options and their
3992 ;; documentation. See the doc string of
3993 ;; `icicle-describe-option-of-type' for more possibilities.
3995 ;; Candidate help (prefix `C-M-') is available for these types of
3996 ;; completion candidates, by default:
3999 ;; * commands and other functions
4000 ;; * keymap variables (if `describe-keymap' is defined - see
4001 ;; library `help-fns+.el')
4002 ;; * user options and other variables
4004 ;; * fonts (mode-line help only)
4005 ;; * command abbreviations (using `apropos-command' for matches)
4010 ;; Starting with Emacs 22, if the candidate names an image file and
4011 ;; you have command-line tool `exiftool' installed and in your
4012 ;; `$PATH' or `exec-path', then EXIF information (metadata) about the
4013 ;; image is included. See standard Emacs library `image-dired.el'
4014 ;; for more information about `exiftool'.
4016 ;; If the same candidate names a function, a variable, and a face, or
4017 ;; any two of these, then all such documentation is shown (Emacs 22
4020 ;; In addition to the candidate types listed above, any command that
4021 ;; uses completion can define its own candidate help action function
4022 ;; and bind it to `icicle-candidate-help-fn'.
4024 ;; A command can also provide its own mode-line and tooltip help for
4025 ;; any individual candidate. See
4026 ;; (@file :file-name "icicles-doc2.el" :to "Applying Text Properties to a Candidate String").
4028 ;; For more information about the types of candidates and their
4029 ;; associated documentation, see the documentation for command
4030 ;; `icicle-help-on-candidate'. This command is bound to `C-M-RET',
4031 ;; `C-M-mouse-2', `C-help', `C-M-help', `C-f1', and `C-M-f1'. When
4032 ;; no specific action is defined for candidates, it is also bound to
4033 ;; `C-RET' and `C-mouse-2'. You can use this to get help on any
4034 ;; completion candidate during completion. See also the related
4035 ;; help-cycling commands, `icicle-next-candidate-per-mode-help',
4036 ;; `icicle-help-on-next-apropos-candidate', and so on, bound to
4037 ;; `C-M-down', `C-M-up', `C-M-next', `C-M-prior', `C-M-end', and
4040 ;; If you use one-buffer-per-frame (`pop-up-frames' non-`nil'), then
4041 ;; displaying `*Help*' in one frame might interfere with viewing
4042 ;; `*Completions*' in another. For that reason, the `*Completions*'
4043 ;; frame is raised to the front. Also, if user option
4044 ;; `icicle-move-Completions-frame' is non-`nil' then the
4045 ;; `*Completions*' frame is moved to the edge of the display, out of
4046 ;; the way, whenever you access help on a candidate. (Default value:
4047 ;; `right', meaning move it to the right).
4050 ;;(@* "Other Icicles Apropos Commands")
4051 ;; ** Other Icicles Apropos Commands **
4053 ;; There are also Icicles replacements for the standard Emacs
4054 ;; `apropos' commands. They act similarly, but they also let you see
4055 ;; the list of regexp matches incrementally (as with all Icicles
4056 ;; commands), using `S-TAB'. If you also use my library
4057 ;; `apropos-fn+var.el', then these Icicles commands take advantage of
4058 ;; the apropos enhancements in that library.
4060 ;; The Icicles apropos commands are: `icicle-apropos',
4061 ;; `icicle-apropos-command', `icicle-apropos-function',
4062 ;; `icicle-apropos-option', `icicle-apropos-variable', and
4063 ;; `icicle-apropos-zippy'.
4065 ;; Another feature of these Icicles commands is that when more than
4066 ;; one type of object can be a candidate, candidates of a certain
4067 ;; type are shown in buffer `*Completions*' using face
4068 ;; `icicle-special-candidate'. For example, command `icicle-apropos'
4069 ;; shows function names as special candidates, to help you
4070 ;; distinguish them from variable names.
4072 ;; In addition, Icicles commands `icicle-doc', `icicle-fundoc', and
4073 ;; `icicle-vardoc' provide the functionality of standard Emacs
4074 ;; command `apropos-documentation', but with additional features -
4075 ;; see (@file :file-name "icicles-doc2.el" :to "Multi-Completions").
4076 ;; In addition, you can use command `icicle-plist' to find symbols
4077 ;; with certain property-list keys and values, and you can use
4078 ;; command `icicle-describe-option-of-type' (bound to `C-h C-o') to
4079 ;; find user options of a certain type.
4081 ;; Command `icicle-customize-apropos-options-of-type' is similar to
4082 ;; `icicle-describe-option-of-type', in that it lets you specify the
4083 ;; type of matching options. But instead of describing an option, it
4084 ;; opens Customize for all options of the specified type that match
4085 ;; your input regexp. (Unlike `icicle-describe-option-of-type',
4086 ;; however, it is not a multi-completion command: you first specify
4087 ;; the type, then the regexp to match.)
4089 ;; One difference between Icicles apropos commands and the standard
4090 ;; commands, besides the Icicles enhancements already described, is
4091 ;; that (starting with Emacs 22) the standard commands let you input
4092 ;; a set of keywords, as an alternative to inputting a regexp.
4093 ;; Icicles apropos commands do not allow for keyword input, as such.
4094 ;; However, Icicles progressive completion provides a more powerful
4095 ;; way to search with multiple keywords (in fact, multiple regexps) -
4096 ;; you can of course use it with the Icicles apropos commands. Also,
4097 ;; there are several problems with the standard Emacs apropos
4098 ;; commands, with respect to interpreting your input as either a set
4099 ;; of keywords or a regexp. Because they allow two very different
4100 ;; syntaxes as input, the standard apropos commands are forced to
4101 ;; make some limiting compromises for keyword searching.
4103 ;; See Also: (@> "Progressive Completion").
4105 ;;(@* "Multi-Commands")
4110 ;;(@* "What Is a Multi-Command?")
4111 ;; ** What Is a Multi-Command? **
4113 ;; A multi-command is a command that lets you make multiple input
4114 ;; choices in a single command execution: a multiple-choice command.
4115 ;; You can choose multiple items from a set of choices, using buffer
4116 ;; `*Completions*' as a multiple-choice "menu". (It's not necessary
4117 ;; to display `*Completions*', however.) Instead of asking you
4118 ;; "Which file do you want to delete?", a multi-command asks you, in
4119 ;; effect, "Which file(S) do you want to delete?".
4121 ;; Nothing especially new here. Any Emacs command could be defined
4122 ;; to use an input loop, asking for file names until you do something
4123 ;; to signal that you're done inputting. It could provide for
4124 ;; file-name completion by calling `read-file-name' to read your
4127 ;; * But what if you could also filter the domain of discourse on the
4128 ;; fly, so that the candidate files were only those matching a
4129 ;; regular expression (regexp) that you typed? Then, the command
4130 ;; definition would need to provide for that behavior too.
4132 ;; * And what if you could then take the complement of that set of
4133 ;; candidate file names, with respect to the complete set of files
4134 ;; in the directory? Or subtract (exclude) some set of file names
4135 ;; from the set of matching names, to get the set of possible
4138 ;; * And what if the set of potential candidates at each step (regexp
4139 ;; match, complement, set difference) could also be displayed in a
4140 ;; multiple-choice menu?
4142 ;; For such multi-command functionality you need Icicles.
4144 ;; You can tell whether a command is a multi-command when you execute
4145 ;; it: if it is a multi-command, then the prompt is prefixed by `+'.
4146 ;; For example, multi-command `icicle-file' uses this prompt:
4148 ;; + File or directory:
4150 ;; Normal, non multi-command `find-file' uses this prompt, which has
4155 ;; Just remember that `+' means that you can choose any number of
4156 ;; inputs. For a list of predefined Icicles multi-commands, use
4157 ;; `C-?' (`icicle-minibuffer-help') in the minibuffer - search for
4158 ;; `+' at the beginning of a line.
4160 ;;(@* "How Does a Multi-Command Work?")
4161 ;; ** How Does a Multi-Command Work? **
4163 ;; When an Icicles multi-command prompts you for input, you can make
4164 ;; a single choice and press `RET' to confirm it, as usual, or you
4165 ;; can choose any number of completion candidates, using `C-RET' (or
4166 ;; `C-mouse-2') for each. You can thus act on multiple candidates,
4167 ;; or even multiple times on the same candidate, during the same
4168 ;; execution of the command.
4170 ;; But you do not have to - you can use any multi-command just as if
4171 ;; it were a normal, single-choice command.
4173 ;; For example, command `icicle-delete-file' lets you delete a single
4174 ;; file or a set of files that match your minibuffer input - all in
4175 ;; the same command execution. If you type no input, then all files
4176 ;; in the current directory match, and you can delete any number of
4177 ;; them individually. If you type `~$' and hit `S-TAB'
4178 ;; (`icicle-apropos-complete'), then all files that end in `~' match,
4179 ;; and you can delete any number of them. Similarly, command
4180 ;; `icicle-buffer-other-window' lets you display any number of
4181 ;; buffers, and so on.
4183 ;; You make multiple choices this way by cycling through the
4184 ;; candidate completions, as usual, and hitting `C-RET' whenever you
4185 ;; want to choose (act on) the current cycle candidate. Or just
4186 ;; press and hold Control while clicking each chosen candidate with
4189 ;; Similarly, you can use `C-down', `C-up', `C-next', `C-prior',
4190 ;; `C-end', or `C-home' to act on successive candidates, forward or
4191 ;; backward. You can thus just hold down the Control key while
4192 ;; cycling, to act on each candidate in turn, if you want.
4194 ;; Instead of, or in addition to, cycling, you can use completion to
4195 ;; get to a particular candidate you want. No matter how a candidate
4196 ;; is made current, you can choose the current candidate (perform the
4197 ;; action on it) using `C-RET' or `C-mouse-2'.
4199 ;; For lax (permissive) completion, you can use `C-RET' to act on
4200 ;; *any* input text - you need not choose one of the available
4201 ;; candidates. This means, for example, that you can create any
4202 ;; number of new file buffers with a single `C-x C-f' invocation, as
4203 ;; well as open any number of existing files.
4205 ;; As always, hitting `RET' (or `S-RET') ends the command. For most
4206 ;; multi-commands, hitting `RET' performs the same action as `C-RET',
4207 ;; but it is possible to have a command that acts differently for
4208 ;; `RET' and `C-RET'. That is the case, for instance, when help is
4209 ;; displayed via `C-RET'.
4211 ;; You can use `C-RET' or `C-mouse-2' repeatedly to act multiple
4212 ;; times on the same candidate. A shortcut is to use `C-u' with
4213 ;; `C-RET' or `C-mouse-2'. That will work if the candidate action
4214 ;; function is designed to be `C-u' sensitive. This is the case for
4215 ;; the Icicles multi-commands that read the name of a command or
4216 ;; keyboard macro and execute the command or macro:
4217 ;; `icicle-execute-extended-command' (`M-x'), `icicle-kmacro'
4218 ;; (`S-f4'), and `icicle-execute-named-keyboard-macro' (`C-x M-e').
4220 ;; So, for example, if you use `C-u 10 C-RET' on command
4221 ;; `forward-char' during `M-x' command completion, the cursor
4222 ;; advances 10 characters. Another example: `C-x M-e C-u 200 C-RET'
4223 ;; on a keyboard-macro candidate `foo' executes `foo' 200 times. You
4224 ;; can use all of the numeric prefix argument shortcuts, such as
4225 ;; `M--', `M-7', and `C-6', with the exception of `C--', which has a
4226 ;; different meaning (`icicle-candidate-set-difference') in the
4227 ;; Icicles minibuffer.
4229 ;; Note that you can supply a prefix argument for both the
4230 ;; multi-command and any of its individual actions. The command is
4231 ;; free to interpret these differently. For example, a prefix arg
4232 ;; for `icicle-kmacro' provides a default repeat factor, which can
4233 ;; then be overridden for any individual action by providing a
4234 ;; different prefix arg. As another example, a prefix arg used with
4235 ;; any file-name candidate for command `icicle-find-file' visits the
4236 ;; file in read-only mode. But a prefix arg for the command itself
4237 ;; reverses this effect: read-only becomes the default so that a
4238 ;; prefix arg for a candidate means visit not read-only.
4240 ;; If user option `icicle-use-candidates-only-once-flag' is
4241 ;; non-`nil', then, when you act on a candidate, it is removed from
4242 ;; the list of available candidates, for clarity. Commands where
4243 ;; this behavior is appropriate bind this option to a non-`nil'
4244 ;; value. This is a user option, but you normally will not customize
4247 ;; You can use `C-g' to exit a multi-command at any time, without
4248 ;; making a final choice using `RET'. If the actions performed by a
4249 ;; multi-command are easily reversible, `C-g' will often restore
4250 ;; things to the way they were before performing the actions.
4252 ;; Does this `C-RET' stuff sound familiar? Using a multi-command is
4253 ;; similar to accessing help on a candidate
4254 ;; (see (@> "Get Help on Candidates")). A multi-command is any
4255 ;; command that has a special action defined for use with `C-RET'
4256 ;; (command `icicle-candidate-action') on the current cycle
4257 ;; candidate. If no such special action is defined, then help on the
4258 ;; candidate is displayed - displaying help is just the default
4259 ;; action for `C-RET', used when no other action is defined. You can
4260 ;; always access candidate help using the `C-M-' prefix: `C-M-help',
4261 ;; `C-M-f1', `C-M-RET', `C-M-mouse-2', `C-M-down', `C-M-up',
4262 ;; `C-M-next', `C-M-prior', `C-M-end', and `C-M-home'.
4264 ;; You can also cycle among elements of a set, performing actions, if
4265 ;; you use my libraries `doremi.el', `doremi-cmd.el', and
4266 ;; `doremi-frm.el'. Like Icicles, Do Re Mi lets you see the effect
4267 ;; of a choice immediately, whenever you make changes. Each library
4268 ;; has its own advantages and special uses. Advantages of Icicles
4271 ;; - completion to candidate values
4272 ;; - restoration after making changes, letting you preview changes
4273 ;; without actually applying them
4277 ;; * (@> "More about Multi-Commands") for more about using
4280 ;; * (@file :file-name "icicles-doc2.el" :to "Defining Icicles Commands (Including Multi-Commands)")
4281 ;; for how to define your own multi-commands.
4283 ;; * (@> "Moving Between the Minibuffer and Other Buffers").
4285 ;;(@* "More about Multi-Commands")
4287 ;; More about Multi-Commands
4288 ;; -------------------------
4290 ;; A multi-command is any command that uses input completion and lets
4291 ;; you perform actions on any number of individual completion
4292 ;; candidates without exiting completion.
4294 ;; The default action is invoked on the current candidate by `C-RET'
4295 ;; (`icicle-candidate-action'). There are three other kinds of
4296 ;; actions on individual candidates:
4298 ;; * alternative actions, invoked by `C-S-RET'
4299 ;; * deletion actions, invoked by `S-delete'
4300 ;; * help actions, invoked by `C-M-RET'
4302 ;; A given command can define any combination of these four kinds of
4303 ;; actions: none of them, any one of them, any two of them, any three
4304 ;; of them, or all four kinds.
4306 ;; This section provides information about alternative actions and
4307 ;; deletion actions.
4311 ;; * (@> "Get Help on Candidates") for information about using
4313 ;; * (@file :file-name "icicles-doc2.el" :to "Defining Multi-Commands the Hard Way")
4314 ;; for information about defining a custom candidate-help action
4317 ;;(@* "Alternative Actions")
4318 ;; ** Alternative Actions **
4320 ;; Just as you can use `C-RET', `C-mouse-2', `C-next', and so on to
4321 ;; invoke a command's default action on multiple completion
4322 ;; candidates individually, so you can use `C-S-RET'
4323 ;; (`icicle-candidate-alt-action'), `C-S-mouse-2', `C-S-next', and so
4324 ;; on to invoke an alternative action that is associated with the
4325 ;; command. If the main action of a command `my-find-file' is to
4326 ;; visit a file, and the alternative action is to print a file, then
4327 ;; you can use `C-S-RET' to print one or more files on the fly, even
4328 ;; as you are completing the name of a file to be visited.
4330 ;; Keys `C-|' and `M-|' apply the alternative action defined for a
4331 ;; given multi-command to *all* matching candidates at once, in the
4332 ;; same way that `C-!' and `M-!' apply the main action defined for it
4333 ;; to all candidates. For example, in Icicles search (e.g. `C-c `'),
4334 ;; the alternative action (e.g. `C-S-RET') replaces all or part of
4335 ;; the current search hit, and `M-|' does the same for all search
4338 ;; It is the particular command that defines its alternative action.
4339 ;; Some commands define no such action. Some commands, as their
4340 ;; alternative action, prompt you to choose (using completion) a
4341 ;; function to be applied to the current completion candidate. In
4342 ;; this case, a single alternative action effectively provides a set
4343 ;; of possible actions.
4345 ;; To achieve this, such commands use the value of user option
4346 ;; `icicle-type-actions-alist', which associates lists of possible
4347 ;; functions with specific candidate types. For example, for
4348 ;; file-name candidates, you can choose among functions that act on
4351 ;; Choosing such a function to apply is itself a multi-command
4352 ;; operation. You can thus apply any number of functions to any
4353 ;; number of candidates.
4355 ;; For example, while you are using `C-x C-f', you can, say, print
4356 ;; one or more candidate files on the fly, or invoke a shell command
4357 ;; on selected files, or byte-compile them... This is a particularly
4358 ;; handy feature, especially if you customize
4359 ;; `icicle-type-actions-alist' for your own particular use.
4361 ;; Some such functions you can choose produce no side effect; they
4362 ;; simply return a value. But if you use `C-u' before `C-S-RET',
4363 ;; then the result of applying the function is pretty-printed (in the
4364 ;; echo area or buffer `*Pp Eval Output*'). For example, if you use
4365 ;; `C-x C-f', you hit `C-u C-S-RET' on the candidate file name
4366 ;; `icicles-doc1.el', and you choose the function candidate
4367 ;; `file-attributes' at the completion prompt `How (action): ', then
4368 ;; the properties of the candidate file (`icicles-doc1.el') are
4369 ;; displayed. With just `C-S-RET' (no prefix arg), the list of
4370 ;; properties is computed, but not displayed.
4372 ;; Be aware of this gotcha: The alternative action for commands that
4373 ;; use `icicle-type-actions-alist' prompts for a function. If you
4374 ;; want to apply that function to all current completion candidates,
4375 ;; then you must use `M-|', not `C-|', because `C-|' prompts you for
4376 ;; each candidate. `M-|' is designed to do the right thing here: it
4377 ;; prompts you once for the function to apply, and then applies it to
4378 ;; each of the current candidates. Andyou can filter the set of
4379 ;; current candidates (progressive completion and so on), or retrieve
4380 ;; a saved set of candidates to operate on.
4382 ;; Note that completion while you choose a function to apply is lax.
4383 ;; This means that you can really enter any function, including a
4384 ;; lambda expression that you invent on the fly. Of course, the
4385 ;; function must accept an object of the appropriate type, (but it
4386 ;; need not actually use that argument).
4388 ;; Using a lambda expression here is a good way to curry a function
4389 ;; that requires multiple arguments, so that it adapts to expect just
4390 ;; a single argument of the appropriate object type. For example,
4391 ;; (lambda (sym-name) (get (intern (sym-name)) 'invisible))
4392 ;; transforms function `get', which takes a symbol and a property as
4393 ;; arguments, to a function that takes a symbol name and looks up the
4394 ;; `invisible' property of the symbol.
4396 ;; Option `icicle-type-actions-alist' is predefined with a number of
4397 ;; candidate types (buffer, color, command, face, file, frame,
4398 ;; function, option, process, variable, and window) and their
4399 ;; associated action functions, but you can add new types or modify
4400 ;; their associated function lists. Any Emacs-Lisp functions can be
4401 ;; used, including lambda expressions. But each function must accept
4402 ;; a value of the appropriate type as its sole required argument
4403 ;; (additional, optional arguments are OK).
4405 ;; Sometimes, you might want to define your own alternative action
4406 ;; function for some command. Do this if you always want the same
4407 ;; alternative action, and it is not the predefined one. To do this,
4408 ;; just customize option `icicle-alternative-actions-alist'. The
4409 ;; associations defined by this option always override any predefined
4410 ;; alternative actions for the corresponding commands.
4412 ;; An alternative to using option `icicle-alternative-actions-alist'
4413 ;; is to define a new command, wrapping an existing command with a
4414 ;; `let' binding that defines the action you want. I recommend using
4415 ;; the option instead, but you might sometimes prefer this approach.
4418 ;; (defun my-icicle-find-file (f)
4419 ;; "`icicle-find-file', but with `w32-browser' as the alt action."
4421 ;; (let ((icicle-candidate-alt-action-fn 'w32-browser))
4422 ;; (list (read-file-name "File: "))))
4423 ;; (icicle-find-file f))
4425 ;; If you are familiar with Icicles object-action commands (see
4426 ;; (@file :file-name "icicles-doc2.el" :to "Icicles OO: Object-Action Interaction")),
4427 ;; then this idea of choosing an object (completion candidate) and
4428 ;; then choosing a function to act on it will ring a bell. And just
4429 ;; as for the object-action commands, here too Icicles exploits any
4430 ;; object-action associations ("sources" and "types") defined by
4431 ;; library Anything (`anything.el'), if you happen to use that, in
4432 ;; addition to the associations defined by
4433 ;; `icicle-type-actions-alist'. And when you do use the Icicles
4434 ;; object-action commands, the same behavior is available as for
4435 ;; alternative actions.
4437 ;; You might have noticed, above, that a type/actions association is
4438 ;; predefined for type `function'. Since the actions you can choose
4439 ;; are themselves functions, you can even use `C-S-RET' on one of
4440 ;; them, to apply a function-for-functions (e.g. `find-function' or
4441 ;; `symbol-function') to it. This is a curiosity, but it can
4442 ;; sometimes be useful.
4444 ;; Finally, note that the completion candidate to which you apply an
4445 ;; alternative action is in most cases a string. In some cases, the
4446 ;; alternative action functions expect a non-string object, and they
4447 ;; will raise an error if applied to a string.
4449 ;; Icicles takes care of this in the case of buffer-name candidates.
4450 ;; It assumes that you really want to operate on a buffer, not its
4451 ;; name (a string), so it automatically calls `get-buffer' before
4452 ;; applying the alternative action function.
4456 ;; * (@> "Perform Alternative Operations on the Fly")
4457 ;; * (@file :file-name "icicles-doc2.el" :to "Icicles OO: Object-Action Interaction")
4458 ;; * (@file :file-name "icicles-doc2.el" :to "Search and Replace")
4459 ;; * (@> "Choose All Completion Candidates")
4461 ;;(@* "Deleting Objects")
4462 ;; ** Deleting Objects **
4464 ;; When it is defined for a particular command, minibuffer command
4465 ;; `icicle-delete-candidate-object', bound to `S-delete' (that's the
4466 ;; `delete' key, Shifted), deletes the object or objects named by the
4467 ;; completion candidate on which it operates. (At least that is the
4468 ;; default behavior - if you customize `icicle-deletion-action-flag'
4469 ;; to `nil', then `S-delete' has no effect.)
4471 ;; Which objects are thus targeted by a given candidate (name) is
4472 ;; something that must be defined by the particular command. The doc
4473 ;; string of a command should always indicate the effect of using
4474 ;; `S-delete', if a deletion action is defined.
4476 ;; As an example of a deletion action, Icicles command
4477 ;; `icicle-buffer-other-window', bound to `C-x 4 b', opens buffers
4478 ;; named by the individual candidates you act on, using `C-RET'. But
4479 ;; it also lets you kill any buffer that you act on, using
4480 ;; `S-delete'. This is not the alternative action for the command
4481 ;; (which is bound to `C-S-RET'); it is the deletion action.
4482 ;; Similarly, command `icicle-bookmark' jumps to a bookmark, but you
4483 ;; can also use `S-delete' with it to delete individual bookmarks.
4485 ;; When you use `S-delete' with a command that allows duplicate
4486 ;; candidate names that represent different candidate objects, it
4487 ;; deletes only the object associated with the current candidate
4490 ;; Some multi-commands define a deletion action, so that `S-delete'
4491 ;; works; some do not. Consult the doc for any given command to see
4492 ;; if it does. Whenever it is defined, the meaning of "delete"
4493 ;; depends on the particular command you use.
4495 ;; `S-delete' deletes only the objects named by the current
4496 ;; completion candidate. However, with a prefix argument, it deletes
4497 ;; *ALL* objects named by the current set of completion candidates,
4498 ;; after you confirm that this is really what you want to do. This
4499 ;; is a quick way to delete things whenever `S-delete' is available:
4500 ;; Use input patterns, with progressive completion, chipping away,
4501 ;; and so on, to define the candidates to delete, then use `C-u
4502 ;; S-delete' and confirm their deletion. Bye-bye.
4504 ;; Do not confuse the unshifted `delete' key with `S-delete'.
4505 ;; `delete' does not delete any objects; it just removes a completion
4506 ;; candidate so that you cannot complete to it. `S-delete' deletes
4507 ;; an object and removes its name as a completion candidate.
4509 ;; If you are an Emacs-Lisp programmer, then you can define your own
4510 ;; multi-commands that provide a deletion action via `S-delete'.
4511 ;; There are two ways to do this. Both involve binding
4512 ;; `icicle-delete-candidate-object':
4514 ;; * Bind it to a deletion function. The function must accept a
4515 ;; completion candidate string and perform the deletion.
4517 ;; * Bind it to a symbol (variable) whose value is a list of
4518 ;; completion-candidate objects. The entries in the list must be
4519 ;; completion candidates for the current call to `completing-read',
4520 ;; but the list itself need not be the COLLECTION argument to
4521 ;; `completing-read'. The list can be an alist, a list of strings,
4522 ;; or a list of symbols. The object that corresponds to the
4523 ;; current candidate when `S-delete' is invoked is deleted from the
4524 ;; list. If, in addition, the list variable is a user option, then
4525 ;; the updated list value is saved in the user's custom file.
4527 ;; For more information about using this feature in Emacs-Lisp code,
4528 ;; see the doc of function `icicle-delete-current-candidate-object'
4529 ;; (`S-delete') and variable `icicle-delete-candidate-object'.
4531 ;;(@* "Option `icicle-use-C-for-actions-flag'")
4532 ;; ** Option `icicle-use-C-for-actions-flag' **
4534 ;; In some contexts, you end up using `C-next' more than `next', and
4535 ;; likewise for the other keys that combine candidate action and
4536 ;; cycling. This is especially true for Icicles multi-commands that
4537 ;; act like a browser, such as `icicle-search', `icicle-imenu',
4538 ;; `icicle-find-tag', `icicle-Info-goto-node', and
4539 ;; `icicle-compilation-search'. In these cases, you use the action
4540 ;; keys to navigate among the locations indicated by the completion
4543 ;; If you set user option `icicle-use-C-for-actions-flag' to `nil',
4544 ;; then the keys that cycle are swapped with the keys that both cycle
4545 ;; and act on a candidate. You can then use `down', `up', `next',
4546 ;; `prior', `end', and `home' to both cycle and act (e.g. navigate),
4547 ;; and `C-down', `C-up', `C-next', `C-prior', `C-end', and `C-home'
4548 ;; to merely cycle, without acting. The option has no effect on
4551 ;; You can toggle `icicle-use-C-for-actions-flag' at any time using
4552 ;; `M-g' (`icicle-toggle-C-for-actions') in the minibuffer.
4554 ;;(@* "Accessing Saved Locations (Bookmarks) on the Fly")
4555 ;; ** Accessing Saved Locations (Bookmarks) on the Fly **
4557 ;; When you complete the names of some kinds of objects, you can use
4558 ;; `C-x m' to follow bookmarks to objects of that type. This is
4559 ;; available only if you use library `bookmark+.el'.
4561 ;; For example, when you invoke a command that completes file names,
4562 ;; you can use `C-x m' to interrupt that operation and complete
4563 ;; against the names of file bookmarks. This is a multi-command, so
4564 ;; you can actually visit any number of file bookmarks. When
4565 ;; finished, you can continue with non-bookmark file-name completion.
4567 ;; The same thing holds for Info bookmarks when you use
4568 ;; `icicle-Info-goto-node' (`g' in Info mode); for buffer (non-file)
4569 ;; bookmarks when you use `icicle-buffer' (`C-x b'); and for Dired
4570 ;; bookmarks when you use `icicle-dired' (`C-x d').
4573 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Bookmark Enhancements")
4575 ;;(@* "Icicles Tripping")
4577 ;; Tripping with Icicles
4578 ;; ---------------------
4580 ;; Among the more useful multi-commands are those whose actions take
4581 ;; you to some location indicated by the completion candidate. This
4582 ;; is the way commands such as `icicle-bookmark', `icicle-find-tag',
4583 ;; `icicle-Info-goto-node', and `icicle-occur' work - you can use
4584 ;; `next' and so on to move among candidates to choose them to act
4585 ;; on, but when you do act on them, Icicles takes you to the places
4588 ;; So just holding down both the Control key and `next' takes you
4589 ;; from one place to the next. And `C-mouse-2' takes you directly to
4590 ;; the location you click. Typically, `C-g' aborts the trip and puts
4591 ;; you back at your starting point, and `RET' ends the trip at the
4592 ;; chosen destination.
4594 ;; There are many such Icicles tripping (or navigation or browsing)
4595 ;; commands, and they all work similarly. They give you the normal
4596 ;; cycling behavior provided by vanilla Emacs commands such as
4597 ;; `find-tag' (via `M-.', `C-u M-.', `M-*' etc.) or
4598 ;; `set-mark-command' (via `C-u C-SPC'). But unlike the vanilla
4599 ;; Emacs commands, the keys for this cycling are always the same.
4601 ;; More importantly, you need not cycle through all possibilities.
4602 ;; You can go directly to particular locations with `C-RET',
4603 ;; `C-mouse-2' or using completion. And your input filters the
4604 ;; available candidates, as always. And you can, as always, use
4605 ;; progressive completion, chipping away, and so on to define your
4606 ;; `C-next' trip itinerary using a process of refinement.
4608 ;; Whereas vanilla Emacs gives you some commands that let you use
4609 ;; completion to enter a destination and go there, and it gives you
4610 ;; other commands that let you cycle among locations, Icicles rolls
4611 ;; all of that into one. And you use the same keys, always, to
4614 ;; Here are some of the Icicles tripping commands:
4616 ;; * Trips among tagged files (delicious-style tagging - requires
4617 ;; library `bookmark+.el'). (The `a' stands for "autofile".)
4618 ;; (Use prefix key `C-x 4 j' for other-window commands.)
4619 ;; `icicle-find-file-tagged' (`C-x j t a a')
4620 ;; `icicle-find-file-all-tags' (`C-x j t a *')
4621 ;; `icicle-find-file-all-tags-regexp' (`C-x j t a % *')
4622 ;; `icicle-find-file-some-tags' (`C-x j t a +')
4623 ;; `icicle-find-file-some-tags-regexp' (`C-x j t a % +')
4625 ;; * `icicle-bookmark-other-window' - (`C-- C-x r m')
4626 ;; Trip among bookmarks of all types. (Also bound to `C-x 4 j j'
4627 ;; if library `bookmark+.el' is used.)
4629 ;; * Type-specific bookmark trips (requires library `bookmark+.el').
4630 ;; (Use prefix key `C-x 4 j' for other-window commands.)
4631 ;; `icicle-bookmark-non-file' (`C-x j b')
4632 ;; `icicle-bookmark-bookmark-list' (`C-x j B')
4633 ;; `icicle-bookmark-dired' (`C-x j d')
4634 ;; `icicle-bookmark-file' (`C-x j f')
4635 ;; `icicle-bookmark-gnus' (`C-x j g')
4636 ;; `icicle-bookmark-info' (`C-x j i')
4637 ;; `icicle-bookmark-desktop' (`C-x j K')
4638 ;; `icicle-bookmark-local-file' (`C-x j l')
4639 ;; `icicle-bookmark-man' (`C-x j m')
4640 ;; `icicle-bookmark-region' (`C-x j r',
4642 ;; `icicle-bookmark-remote-file' (`C-x j n')
4643 ;; `icicle-bookmark-all-tags' (`C-x j t *')
4644 ;; `icicle-bookmark-some-tags' (`C-x j t +')
4645 ;; `icicle-bookmark-all-tags-regexp' (`C-x j t % *')
4646 ;; `icicle-bookmark-some-tags-regexp' (`C-x j t % +')
4647 ;; `icicle-bookmark-file-all-tags' (`C-x j t f *')
4648 ;; `icicle-bookmark-file-all-tags-regexp' (`C-x j t f % *')
4649 ;; `icicle-bookmark-file-some-tags' (`C-x j t f +')
4650 ;; `icicle-bookmark-file-some-tags-regexp' (`C-x j t f % +')
4651 ;; `icicle-bookmark-url' (`C-x j u')
4652 ;; `icicle-bookmark-w3m' (`C-x j w')
4653 ;; `icicle-bookmark-this-buffer' (`C-x j .')
4654 ;; `icicle-bookmark-specific-buffers' (`C-x j = b')
4655 ;; `icicle-bookmark-specific-files' (`C-x j = f')
4657 ;; * `icicle-buffer' (`C-x b') - Trip among buffers
4658 ;; * `icicle-compilation-search' (`C-c `') - Trip among `grep' hits
4659 ;; * `icicle-dired' - Trip among directories
4660 ;; * `icicle-find-file' (`C-x C-f') - Trip among files
4661 ;; * `icicle-find-file-absolute' (`C-u C-x C-f') - Trip among files
4662 ;; * `icicle-find-file-in-tags-table' - Trip among files listed in
4663 ;; current tags table (project)
4664 ;; * `icicle-find-file-read-only' (`C-x C-r') - Visit read-only
4665 ;; * `icicle-find-first-tag' (`C-x 4 .') - Trip among tag hits
4666 ;; * `icicle-find-tag' (`M-.') - Trip among tag hits
4667 ;; * `icicle-goto-global-marker' (`C-- C-x C-SPC') - Trip among
4669 ;; * `icicle-goto-marker' (`C-- C-SPC') - Trip among local markers
4670 ;; * `icicle-imenu' (`C-c =') - Trip among definitions
4671 ;; (`icicle-imenu-full' to search full definitions)
4673 ;; * Type-specific Imenu trips (library `imenu+.el' recommended).
4674 ;; (And `*-full' versions of each to search full definitions.)
4675 ;; `icicle-imenu-command'
4676 ;; `icicle-imenu-face'
4677 ;; `icicle-imenu-key-explicit-map'
4678 ;; `icicle-imenu-key-implicit-map'
4679 ;; `icicle-imenu-macro'
4680 ;; `icicle-imenu-non-interactive-function'
4681 ;; `icicle-imenu-user-option'
4682 ;; `icicle-imenu-variable'
4684 ;; * `icicle-Info-goto-node' (`g' in Info)- Trip among Info nodes
4685 ;; * `icicle-Info-index' (`i' in Info) - Trip among Info nodes
4686 ;; * `icicle-Info-menu' (`m' in Info) - Trip among Info nodes
4687 ;; * `icicle-locate-file' - Trip among files
4688 ;; * `icicle-occur' (`C-c '') - Trip among `occur' hits
4689 ;; (`icicle-search' among
4690 ;; single-line hits)
4691 ;; * `icicle-recent-file' - Trip among recent files
4692 ;; * `icicle-search' (`C-c `') - Trip among regexp search hits
4693 ;; * `icicle-search-bookmarks-together' (`C-u C-c `'),
4694 ;; `icicle-search-bookmark', - Search multiple bookmarks
4695 ;; * Type-specific bookmark searches
4696 ;; `icicle-search-bookmark-list-bookmark' - Search bookmark lists
4697 ;; `icicle-search-dired-bookmark' - Search Dired bookmarks
4698 ;; `icicle-search-file-bookmark' - Search file bookmarks
4699 ;; `icicle-search-gnus-bookmark' - Search Gnus bookmarks
4700 ;; `icicle-search-info-bookmark' - Search Info bookmarks
4701 ;; `icicle-search-local-file-bookmark'- Search local-file bookmarks
4702 ;; `icicle-search-man-bookmark' - Search `man'-page bookmarks
4703 ;; `icicle-search-non-file-bookmark' - Search non-file bookmarks
4704 ;; `icicle-search-region-bookmark' - Search bookmarked regions
4705 ;; `icicle-search-remote-file-bookmark' - Search remote bookmarks
4706 ;; `icicle-search-url-bookmark' - Search URL bookmarks
4707 ;; * `icicle-search-char-property' - Trip among buffer strings with
4708 ;; with a text/overlay property
4709 ;; * `icicle-search-dired-marked' - Search marked files in Dired
4710 ;; * `icicle-search-file' - Search multiple files
4711 ;; * `icicle-search-ibuffer-marked' - Search marked bufs in Ibuffer
4712 ;; * `icicle-search-keywords' (`C-c ^') - Trip among keyword search
4714 ;; * `icicle-search-overlay-property' - Trip among buffer strings
4715 ;; with some overlay property.
4716 ;; * `icicle-search-pages' - Search Emacs pages
4717 ;; * `icicle-search-paragraphs' - Search Emacs paragraphs
4718 ;; * `icicle-search-sentences' - Search sentences as contexts
4719 ;; * `icicle-search-text-property' (`C-c "') - Trip among buffer
4720 ;; strings with a text property
4721 ;; * `icicle-search-thing' - Search thing-at-point things
4722 ;; * `icicle-search-word' (`C-c $') - Search whole-word hits
4723 ;; * `icicle-search-xml-element' - Search XML elements
4724 ;; * `icicle-search-xml-element-text-node' - Search text of XML elts
4725 ;; * `icicle-select-frame' (`C-x 5 o') - Trip among frames, by name
4726 ;; * `icicle-select-window' (`C-0 C-x o') - Trip among windows, by
4729 ;;(@* "Highlighting the Destination")
4730 ;; ** Highlighting the Destination **
4732 ;; `icicle-bookmark-region-other-window' activates the bookmarked
4733 ;; region (highlighting it) when you visit it, if you use Transient
4734 ;; Mark mode (or, e.g., Delete Selection mode).
4736 ;; Starting with Emacs 22, most Icicles commands that have single
4737 ;; positions as their trip visits (e.g. `icicle-bookmark',
4738 ;; `icicle-Info-goto-node', `icicle-goto-marker', `icicle-find-tag')
4739 ;; highlight those positions temporarily as they are visited. Except
4740 ;; for the Icicles search commands, this highlighting is provided by
4741 ;; library `crosshairs.el'. If `crosshairs.el' and the libraries it
4742 ;; requires are not in your `load-path', then no such highlighting
4747 ;; * (@> "Icicles Commands that Read File Names") for information
4748 ;; about `icicle-find-file', `icicle-find-file-absolute',
4749 ;; `icicle-find-file-in-tags-table', `icicle-locate-file', and
4750 ;; `icicle-recent-file'.
4751 ;; * (@file :file-name "icicles-doc2.el" :to "Icicles Enhancements for Emacs Tags")
4752 ;; for information about `icicle-find-first-tag' and
4753 ;; `icicle-find-tag'.
4754 ;; * (@file :file-name "icicles-doc2.el" :to "Icicles Bookmark Enhancements")
4755 ;; for information about the bookmark browsing commands.
4756 ;; * (@file :file-name "icicles-doc2.el" :to "Icicles Info Enhancements")
4757 ;; for information about `icicle-Info-goto-node',
4758 ;; `icicle-Info-index', and `icicle-Info-menu'.
4759 ;; * (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
4760 ;; for information about `icicle-occur' and `icicle-search'.
4761 ;; * (@file :file-name "icicles-doc2.el" :to "Other Icicles Search Commands")
4762 ;; for information about `icicle-compilation-search',
4763 ;; `icicle-imenu*' commands, `icicle-search-char-property',
4764 ;; `icicle-search-keywords', `icicle-search-overlay-property', and
4765 ;; `icicle-search-text-property'.
4767 ;; * (@file :file-name "icicles-doc2.el" :to "Defining Icicles Tripping Commands")
4768 ;; for information about defining your own tripping commands.
4770 ;;(@* "Key Completion")
4775 ;; Here's another weird Icicles feature: completing key sequences,
4776 ;; instead of commands. (This feature works only for Emacs 22 and
4779 ;; What on earth for? Ever want to use one of those myriad `C-x' key
4780 ;; sequences, but forget just what it was? The standard solution to
4781 ;; that is to use `C-x C-h', to display all of the `C-x' bindings
4782 ;; together with their commands.
4784 ;; OK, but then you have to scroll down the list of bindings,
4785 ;; searching for the command you want, and then use its key binding.
4786 ;; You can use `C-M-s' to search for a substring of the command name,
4787 ;; in case you do not recall the exact name, but why not use Icicles
4788 ;; completion for this? Why not match against possible key sequences
4791 ;;(@* "Completing Keys")
4792 ;; ** Completing Keys **
4794 ;; To complete keys in Icicles, start the key sequence as usual, and
4795 ;; then hit `S-TAB' (command `icicle-complete-keys'). For example,
4796 ;; use `C-x' or `C-x 4', and then hit `S-TAB' to complete the prefix
4797 ;; `C-x' or `C-x 4' (or whatever). You're then completing against
4798 ;; candidates that are composed of two parts, separated by " = ":
4800 ;; * a key binding that completes what you've typed so far -
4801 ;; e.g. `C-j' (that is, `C-x C-j')
4803 ;; * the command it is bound to - e.g. `dired-jump-other-window'
4805 ;; So, for example, this is a single completion candidate:
4807 ;; C-j = dired-jump-other-window
4809 ;; You can match your minibuffer input against the key name, the
4810 ;; command name, or both.
4812 ;; Suppose, for instance, that you want to use a version-control
4813 ;; command, and you remember that all such commands are bound to key
4814 ;; sequences that begin with `C-x v'. You enter as much of the key
4815 ;; sequence as you remember (`C-x v'), and then you hit `S-TAB'. You
4816 ;; can then use completion (either apropos or prefix) against the
4817 ;; matching key sequences and command names to invoke the right
4818 ;; command. And, as a bonus, you are reminded of its key sequence.
4819 ;; You can thus use Icicles key completion to execute a command and,
4820 ;; at the same time, learn its key binding.
4822 ;; (The documentation always refers to the key that performs key
4823 ;; completion as `S-TAB'. Actually, it is `S-TAB' only by default.
4824 ;; You can customize it, using option `icicle-key-complete-keys'.)
4826 ;;(@* "`S-TAB' Is Everywhere - Start With It")
4827 ;; ** `S-TAB' Is Everywhere - Start With It **
4829 ;; In Icicle mode, whenever you are not in the minibuffer or buffer
4830 ;; `*Completions*', key `S-TAB' initiates key completion. That is,
4831 ;; you do not need to first type part of a key sequence to use it -
4832 ;; you can start with it. Hit `S-TAB' at any time, and you're
4833 ;; completing a key sequence, even if you have not yet hit any keys.
4834 ;; This lets you see all key sequences that are available in a given
4835 ;; context. For example, in Dired, keys special to that mode are
4836 ;; included (and are highlighted as local bindings -
4837 ;; see (@> "Local Bindings Are Highlighted")).
4839 ;; When completing a key sequence, you can type part of a command
4840 ;; name, then hit `S-TAB' to apropos-complete against the command
4841 ;; name. In this respect, `S-TAB' acts like `M-x', but the key
4842 ;; binding is also part of the completion candidate, so you can also
4845 ;;(@* "Completing Keys By Name")
4846 ;; ** Completing Keys By Name **
4848 ;; So, just how do you complete input against a set of
4849 ;; binding-plus-command completion candidates? You can always cycle
4850 ;; among the candidates, of course, and then choose one. But what
4851 ;; about completion? Just type text to match candidates, then use
4852 ;; `S-TAB' or `TAB' as usual to complete the text. Text? Yes.
4853 ;; Completion candidates are always, ultimately, strings.
4855 ;; Suppose that you type `C-x S-TAB' to show all key sequences that
4856 ;; begin with `C-x'. You might see a candidate that looks like this:
4858 ;; C-q = toggle-read-only
4860 ;; You can then type "C-q" or "d-onl" or any other substring, and
4861 ;; then use `S-TAB' to complete the candidate. (This second use of
4862 ;; `S-TAB' invokes the command `icicle-apropos-complete', which has
4863 ;; nothing to do with `icicle-complete-keys', which was invoked by
4864 ;; the first `S-TAB'. The first was invoked outside the minibuffer;
4865 ;; the second was invoked from the minibuffer, during completion.)
4867 ;;(@* "Completing Prefix Keys")
4868 ;; ** Completing Prefix Keys **
4870 ;; What happens if the completion candidate is itself a prefix key?
4871 ;; For example, `C-x S-TAB' shows some candidates whose commands are
4872 ;; shown as "...", like this:
4875 ;; 6 = ... C-k = ...
4876 ;; ESC = ... RET = ...
4878 ;; These represent prefix keys (`C-x 4', `C-x C-k', and so on). If
4879 ;; you choose such a candidate, then you just continue completing -
4880 ;; buffer `*Completions*' is updated to show the completions of the
4881 ;; compound prefix: `C-x 4', `C-x RET', or whichever you choose. The
4882 ;; minibuffer prompt shows the completion so far; if you choose
4883 ;; `RET', for instance, then it shows `C-x RET' while prompting you
4884 ;; for the rest of the key sequence.
4886 ;; By default, completion candidates are sorted in buffer
4887 ;; `*Completions*' with local bindings listed first. You can use
4888 ;; `C-M-,' at any time during key completion to toggle between this
4889 ;; order and sorting with the prefix-key candidates shown first. You
4890 ;; can use `C-,' at any time to change the sort order among these two
4891 ;; orders and sorting by command name.
4893 ;; Gotcha: Commands that are remapped do not show up with the
4894 ;; bindings you think they have. For example, `C-x C-f' is bound to
4895 ;; `icicle-file' in Icicle mode, by default, but `C-x S-TAB' does not
4896 ;; include the completion candidate `C-f = icicle-file'. Instead,
4897 ;; `S-TAB' at the top level (without first doing `C-x') shows a
4898 ;; (pseudo) prefix key `remap = ..', and if you follow that then
4899 ;; you'll see the candidate `find-file = icicle-file'. The binding
4900 ;; of `C-x C-f' does not appear as such, because `find-file' is
4901 ;; remapped to command `icicle-file': whatever `find-file' was bound
4902 ;; to is indirectly bound to `icicle-file'. This indirection shows up
4903 ;; in Icicles key completion as (pseudo) prefix key `remap = ..'.
4905 ;;(@* "Meta Key Bindings")
4906 ;; ** Meta Key Bindings **
4908 ;; If you use `S-TAB' at the top level, and you look for the key
4909 ;; sequence `M-x' or `M-d', you will not find it. Meta key bindings
4910 ;; are there, but many of them are disguised as keys in the `ESC'
4911 ;; prefix keymap - e.g. `ESC x' for `M-x'. That is, you must first
4912 ;; choose the `ESC` prefix key: `ESC = ...', and then choose the `x'
4913 ;; key or whatever. That's just the way Emacs works. So, yes, you
4914 ;; can use Icicles key completion to execute any Emacs command, even
4915 ;; one that is not bound to a key sequence, and you can use it to
4916 ;; evaluate any EmacsLisp expression. See (@> "Three-Key Emacs").
4918 ;;(@* "Navigate the Key-Binding Hierarchy")
4919 ;; ** Navigate the Key-Binding Hierarchy **
4921 ;; Choosing a completion candidate such as `C-x = ...' effectively
4922 ;; navigates down the key-binding hierachy (prefix-key hierarchy), to
4923 ;; complete against all keys with prefix `C-x'. Choosing `5 = ...'
4924 ;; to complete the prefix `C-x' then navigates down another level, to
4925 ;; complete keys that have prefix `C-x 5'.
4927 ;; What about navigating back up the hierarchy, say from the `C-x 5'
4928 ;; keys to the `C-x' keys, or from the `C-x' keys to the keys with no
4929 ;; prefix? The special completion candidate `..' does that. By
4930 ;; default, it is always the first candidate in the `*Completions*'
4931 ;; list. It is of course not available unless you are completing a
4932 ;; prefix; that is, it is not available at the top level.
4934 ;; This feature means that you can navigate the key-binding hierachy
4935 ;; just as you would navigate the file-system hierarchy (using, say,
4936 ;; `C-x C-f') or the menu-bar hierarchy (using library `lacarte.el').
4937 ;; (In fact, since menu-bar bindings are also key bindings, you can
4938 ;; also use key completion to navigate the menu-bar hierarchy - just
4939 ;; complete the prefix key `menu-bar'! Start with `S-TAB', choose
4940 ;; `menu-bar = ...', then choose a menu, and so on.)
4942 ;; Icicles key completion thus provides a general browser for key
4943 ;; bindings, which you can also use to learn about keys and their
4944 ;; associated comands, without necessarily executing them - see
4945 ;; (@> "Key and Command Help").
4947 ;; Gotcha: `S-TAB' uses apropos completion, by default, so remember
4948 ;; that typing `.' matches any character (except a newline). To
4949 ;; match only the literal string `..' (to go up a level), do one of
4952 ;; * Turn on escaping of regexp special characters - use `C-`' in the
4953 ;; minibuffer to toggle this.
4955 ;; * Use prefix completion (`TAB').
4957 ;; * Escape the regexp special character explicitly: `\.\.' (or use
4960 ;; * Cycle to candidate `..'.
4962 ;;(@* "Local Bindings Are Highlighted")
4963 ;; ** Local Bindings Are Highlighted **
4965 ;; Sometimes it helps to know which key sequences are local bindings,
4966 ;; that is, bindings that are specific to the current mode. For
4967 ;; example, Dired mode defines keys specific to Dired buffer, such as
4968 ;; `* %', `% g', and `!'. To help you distinguish local key bindings
4969 ;; from others (global and minor-mode bindings), local bindings are
4970 ;; highlighted in buffer `*Completions*' using face
4971 ;; `icicle-special-candidate'.
4973 ;;(@* "Completing Keys By Just Hitting Them")
4974 ;; ** Completing Keys By Just Hitting Them **
4976 ;; It may seem odd that you must complete a key sequence by entering
4977 ;; the names of keys, rather than just hitting the keys themselves:
4978 ;; e.g. typing "C-f" rather than hitting `C-f'. However, if keys
4979 ;; themselves were used for completing, then they could not be used
4980 ;; normally during key-sequence completion. You could not move the
4981 ;; cursor around the minibuffer using `C-f' or `right' (right arrow),
4982 ;; because those keys would be treated as input for completion. You
4983 ;; could not use `up' or `down' to cycle among completion candidates
4984 ;; for the same reason. Likewise, you could not use printing
4985 ;; (self-inserting) keys, such as `a' and `$', to match command
4986 ;; names. Having to use key names, instead of keys, for completion
4987 ;; is a small price to pay for being able to complete key sequences.
4989 ;; Nevertheless, Icicles also provides a way for you to type key
4990 ;; sequences directly, even if it is something of a workaround:
4991 ;; precede each key with `M-q' (`icicle-insert-key-description',
4992 ;; during key completion) - think of `q' for "quote". This inserts
4993 ;; the key description of whatever key you hit next. This key
4994 ;; description (name) can be used to match key-completion candidates.
4995 ;; So, for example, instead of typing "C-f", you can hit `M-q' and
4996 ;; then hit `C-f'. The key description "C-f" is inserted in the
4997 ;; minibuffer. If you use `M-q C-M-right', then "C-M-right" is
4998 ;; inserted. Try it: `S-TAB M-q C-M-right' -> "C-M-right". Then hit
4999 ;; `TAB' or `S-TAB' to complete the candidate all the way to this:
5001 ;; C-M-right = enlarge-frame-horizontally
5003 ;; Note: Whether or not angle brackets are used is governed by user
5004 ;; option `icicle-key-descriptions-use-<>-flag'. By default, this is
5005 ;; `nil', so angle brackets are not used, which I think improves
5006 ;; readability. If you set this to non-`nil', then you will see
5007 ;; "<C-M-right>" instead of "C-M-right", both as a completion
5008 ;; candidate and as what is inserted when you use `M-q'. You can
5009 ;; also provide a prefix argument to `M-q' to flip the behavior of
5010 ;; `icicle-key-descriptions-use-<>-flag' for that occurrence only.
5012 ;;(@* "Key and Command Help")
5013 ;; ** Key and Command Help **
5015 ;; That points out another use of key completion, opposite to
5016 ;; learning the bindings of commands: learning the commands bound to
5017 ;; given keys. In other words, `S-TAB M-q' does both what `C-h w'
5018 ;; (`where-is') does and what `C-h c' (`describe-key-briefly') does.
5019 ;; It also does what `C-h b' (`describe-bindings') does.
5021 ;; The point here is not that `S-TAB M-q' is quicker than `C-h w' or
5022 ;; `C-h c' or `C-h b' - it's not. The point is that key completion
5023 ;; can be handy in several ways, and it can teach you various things
5024 ;; about keys and commands as you use it.
5026 ;; In addition to this key-completion help about bindings, you can
5027 ;; display help on the commands that are the right sides of the
5028 ;; `S-TAB' completion-candidate equations, by using the multi-command
5029 ;; help keys (see (@> "Help on Completion Candidates")). That is,
5030 ;; while completing, you can use `C-M-mouse-2', `C-M-RET',
5031 ;; `C-M-next', and so on to describe the command named in the current
5032 ;; completion candidate.
5034 ;;(@* "`S-TAB' Is a Multi-Command")
5035 ;; ** `S-TAB' Is a Multi-Command **
5037 ;; Yes, `S-TAB' as `icicle-complete-keys' is a multi-command - see
5038 ;; (@> "Multi-Commands")). This means that you can, within the same
5039 ;; execution of `S-TAB', invoke any number of keys by clicking
5040 ;; (`C-mouse-2') their names in buffer `*Completions*' or choosing
5041 ;; them any other way (`C-RET', `C-next', and so on).
5043 ;; Since you can navigate up and down the key-binding hierarchy, you
5044 ;; could even stay within a single `S-TAB' invocation to do nearly
5045 ;; everything you want in Emacs (see (@> "Three-Key Emacs"))!
5047 ;;(@* "Possible Source of Confusion")
5048 ;; ** Possible Source of Confusion **
5050 ;; Keep in mind that `S-TAB' has two different uses in Icicles when
5051 ;; you are providing input in the minibuffer:
5053 ;; * If input completion is available, then `S-TAB' performs apropos
5054 ;; completion (it is, in effect, bound to
5055 ;; `icicle-apropos-complete').
5057 ;; * If input completion is not available, then `S-TAB' performs key
5058 ;; completion (it is, in effect, bound to `icicle-complete-keys').
5060 ;; In addition, in buffer `*Completions*' `S-TAB' moves backward
5061 ;; among the candidate completions.
5063 ;; This is by design; it takes advantage of the fact that these
5064 ;; contexts are mutually exclusive. However, this economy comes at a
5065 ;; risk of potential confusion. It's important that you know whether
5066 ;; or not completion is available when you are inputting text. If
5067 ;; input completion is not available, but you think it is, then
5068 ;; hitting `S-TAB' might give you a surprise by key completing. That
5069 ;; behavior is normal - you can use key-completion to input special
5070 ;; characters, for instance. But if you think that you are instead
5071 ;; completing the original input requested, then you can become
5074 ;; Icicles provides completion status indicators so that you can
5075 ;; easily tell when completion is available for minibuffer input.
5076 ;; There are two indicators: (1) at the beginning of the minibuffer
5077 ;; prompt and (2) in the `Icy' minor-mode lighter in the mode line.
5078 ;; See (@> "Completion Status Indicators"). If completion is not
5079 ;; indicated when you are prompted for input, it means that `S-TAB'
5080 ;; is available, not for input completion, but for key completion.
5081 ;; Another clue can be found in the prompt text. For key completion,
5082 ;; it says "Complete keys: ".
5084 ;; If you nevertheless find the overloaded use of `S-TAB' confusing,
5085 ;; you can change the bindings of the key `S-TAB' in these different
5086 ;; contexts. To do that, you can customize options
5087 ;; `icicle-apropos-complete-keys', `icicle-key-complete-keys', and
5088 ;; `icicle-previous-candidate-keys'.
5090 ;;(@* "Three-Key Emacs")
5091 ;; ** Three-Key Emacs **
5093 ;; Icicles key completion piles a lot of stuff into `S-TAB'. Just as
5094 ;; `M-x' lets you execute any Emacs command, so does `S-TAB'. But
5095 ;; `S-TAB' also lets you insert characters. With the exception of
5096 ;; inserting multi-byte characters, you might say that it gives you
5097 ;; all of Emacs in one key binding.
5099 ;; Of course, you need a couple other keys, as well. How many?
5100 ;; Suppose you had limited accessibility in terms of input devices.
5101 ;; Maybe you use Emacs on a cell phone, without voice recognition -
5102 ;; or whatever. How many keys, buttons, or whatnot do you need to
5105 ;; 1. You need one for `C-g', to interrupt commands.
5106 ;; 2. You need one to start telling Emacs what to do.
5107 ;; 3. You might need one to choose from a set of possible things to
5109 ;; 4. You need one to tell Emacs that you're done telling it what to
5112 ;; (#2 and #3 might be combined somehow.)
5114 ;; What does vanilla Emacs offer out of the box in this regard?
5116 ;; * You can get by with just `mouse-1' and the menu-bar menus, but
5117 ;; they do not cover all of Emacs. You cannot use them to enter
5118 ;; text, for instance. Of course, you could add more menus, to be
5121 ;; * You can use `M-x' plus `RET' to execute any command. But how
5122 ;; would you insert text?
5124 ;; * Similarly, for `M-:', which lets you evaluate any Emacs-Lisp
5125 ;; sexp. You still need a way to type characters.
5127 ;; Icicles key completion lets you do almost anything in Emacs with
5128 ;; three or four keys, buttons, or whatever:
5130 ;; * `S-TAB' - Offers every key sequence as a possible choice to
5132 ;; * `next' - Cycles among candidates, for choosing.
5133 ;; * `RET' - Chooses the current candidate.
5134 ;; * And of course `C-g', to cancel the current operation.
5136 ;; `S-TAB' includes key `M-x (represented as prefix key `ESC'
5137 ;; followed by `x'), which offers all commands (even those not bound)
5138 ;; as possible choices. It also includes key `M-:' (`ESC' followed
5139 ;; by `:'), which lets you execute any Emacs-Lisp expression. That's
5140 ;; almost all of Emacs!
5142 ;; You could even perhaps get away with only three mouse buttons, and
5145 ;; * `mouse-1' - Choose candidates, scroll, and so on (direct access,
5148 ;; * `mouse-2' - Do what `S-TAB' does (bind it to
5149 ;; `icicle-complete-keys' and `icicle-apropos-complete').
5151 ;; * `mouse-3' - Do what `C-g' does (bind it to `keyboard-quit' and
5152 ;; `icicle-abort-recursive-edit').
5154 ;; Here, `mouse-2' and `mouse-3' are not even used as mouse (pointer)
5155 ;; functions; any keys or buttons would do. You could use just
5156 ;; `mouse-1' plus a Shift key and a Control key.
5158 ;; Would you want to use Emacs only this way? Of course not, if you
5159 ;; had a choice. Typing the character `a' by cycling through every
5160 ;; possible key binding/command combination and hitting `RET' when
5161 ;; you get to `a = self-insert-command' would be the epitome of
5162 ;; tedium. Likewise, doing everything with a single pointer-device
5163 ;; button. Using only three or four keys or buttons is definitely
5164 ;; not the ideal way to take advantage of Emacs.
5166 ;; But you are probably not limited to just 3 or 4 keys or buttons.
5167 ;; The real point here is that Icicles `S-TAB' opens the door to
5168 ;; almost everything in Emacs. And if you do have a normal keyboard,
5169 ;; then you can type letters and such to match command names and key
5170 ;; sequences. Key `next' matches substrings (regexps, actually),
5171 ;; which makes choice even quicker.
5173 ;;(@* "Entering Special and Foreign Characters")
5174 ;; ** Entering Special and Foreign Characters **
5176 ;; Command `self-insert-command' is bound to each key that is
5177 ;; associated with a character that can be inserted in text. It is
5178 ;; the binding of the key `a' and the key `$'. It is also the
5179 ;; binding of keys that your keyboard might not even have - keys that
5180 ;; correspond to special or odd characters and characters in other
5183 ;; To Icicles key completion, these keys are like other keys.
5184 ;; However, because there are many, many keys bound to
5185 ;; `self-insert-command', it can be distracting and slow to allow
5186 ;; such keys as completion candidates. If option
5187 ;; `icicle-complete-keys-self-insert-ranges' is `nil' (the default
5188 ;; value), then such keys are excluded as candidates. This is
5189 ;; probably what you want, always.
5191 ;; If the option is non-`nil', then you can use key completion to
5192 ;; insert the characters whose codes are in the range(s) defined by
5193 ;; the option value. This lets you see the candidate characters in
5194 ;; `*Completions*' (WYSIWYG), but it is not a terribly convenient or
5195 ;; quick way to insert characters.
5197 ;; Starting with Emacs 23, vanilla Emacs has Unicode support, and you
5198 ;; can insert any Unicode characters using either an input method or
5199 ;; command `ucs-insert', which lets you complete against the Unicode
5202 ;; If you do use a non-`nil' value for
5203 ;; `icicle-complete-keys-self-insert-ranges' then use only small
5204 ;; ranges for better performance, e.g., `((0 . 687))' covers Latin
5205 ;; characters. For Emacs 22, the option is effectively Boolean: any
5206 ;; non-`nil' value allows all self-inserting keys as candidates
5207 ;; (there are far fewer available characters in Emacs 22).
5209 ;;(@* "Handling Keymaps That Are Inaccessible From the Global Map")
5210 ;; ** Handling Keymaps That Are Inaccessible From the Global Map **
5212 ;; Actually, `S-TAB' is not bound to `icicle-complete-keys' in every
5213 ;; keymap. That would be inconvenient, in general. By default, it
5214 ;; is so bound in each keymap that is accessible from the global
5215 ;; keymap, as determined by function `accessible-keymaps'.
5217 ;; You've seen, above, how you can navigate through prefix keys,
5218 ;; starting with the global map. In Dired, for instance, you can use
5219 ;; `S-TAB' at the top level, then choose the prefix key `*' in
5220 ;; `*Completions*', then choose a key, such as `/' (to mark
5221 ;; directories), in the `*' keymap.
5223 ;; However, the act of binding of `S-TAB' in keymaps that are
5224 ;; accessible from the global map does not bind it in the `*' prefix
5225 ;; keymap itself. To handle this case, Icicles explicitly does for
5226 ;; `dired-mode-map' what it does for the global map: it binds `S-TAB'
5227 ;; in each keymap that is accessible from `dired-mode-map'. Because
5228 ;; of this, you can use `* S-TAB' to show all key completions of `*'.
5230 ;; This treatment of `dired-mode-map' is done by default. Similarly
5231 ;; for a few other keymaps. But you might have other keymaps that
5232 ;; you would like to treat similarly - keymaps that Icicles might be
5233 ;; unaware of. You do this by including them in the list value of
5234 ;; user option `icicle-keymaps-for-key-completion', along with
5235 ;; `dired-mode-map' and the others provided in the default value.
5236 ;; The list entries are Emacs-Lisp symbols that are bound to keymaps,
5237 ;; each of which should define at least one prefix key. If you add a
5238 ;; keymap variable to this list, then `S-TAB' will be bound so that
5239 ;; you can use it to complete the prefix keys defined by that map.
5241 ;; Notice that there is no keymap variable that corresponds to prefix
5242 ;; key `*' in Dired mode. You need only provide a keymap (variable
5243 ;; `dired-mode-map') from which the prefix key is accessible; it is
5244 ;; not necessary to also provide a variable that corresponds to the
5245 ;; prefix keymap itself.
5247 ;; If a keymap listed in `icicle-keymaps-for-key-completion' is not
5248 ;; defined when Icicle mode is entered, then it is ignored. If you
5249 ;; later define that keymap, then just exit and reenter Icicle mode
5250 ;; for the `S-TAB' binding to take effect. For example, use `M-x
5251 ;; icy-mode' twice after entering Calendar mode, to be able to
5252 ;; complete `calendar-mode' prefix keys such as `t' - `t S-TAB'.
5254 ;;(@* "Icicles Multi `M-x'")
5256 ;; Icicles Multi `M-x'
5257 ;; -------------------
5259 ;; How about a multi-command replacement for `M-x'? Instead of
5260 ;; executing a single command, it would execute any number of
5261 ;; commands. This section describes two such multi-commands,
5262 ;; `icicle-execute-extended-command' and `icicle-command-abbrev',
5263 ;; which by default are bound in Icicle mode to `M-x' and `C-x SPC',
5264 ;; respectively. See Also:
5265 ;; (@file :file-name "icicles-doc2.el" :to "Defining Icicles Multi `M-x'").
5267 ;;(@* "Multi `M-x': `icicle-execute-extended-command'")
5268 ;; ** Multi `M-x': `icicle-execute-extended-command' **
5270 ;; When you use `M-x' in vanilla Emacs, you are actually executing
5271 ;; the standard Emacs command `execute-extended-command'. That
5272 ;; command prompts you for the name of another command, which you
5273 ;; input. It uses `completing-read' to do this, which is why you can
5274 ;; take advantage of Icicles features when you use `M-x'. Nothing
5277 ;; Command `icicle-execute-extended-command' is simply a
5278 ;; multi-command version of `execute-extended-command'. It does the
5279 ;; same thing, except that it also lets you execute multiple
5280 ;; commands, one by one, using `C-RET' (or `C-next' and so on),
5281 ;; without ever exiting the minibuffer.
5283 ;; With the default value of option `icicle-top-level-key-bindings',
5284 ;; `M-x' is bound to `icicle-execute-extended-command' whenever you
5285 ;; are in Icicle mode. If you never use it as a multi-command, you
5286 ;; will not notice any difference from `execute-extended-command'.
5288 ;;(@* "Examples of Using Multi `M-x'")
5289 ;; *** Examples of Using Multi `M-x' ***
5291 ;; Example: Repeat a command multiple times. Yes, `C-x z' does this
5292 ;; already (and better) - this is just an illustration. `M-x
5293 ;; forward-ch TAB' completes to `forward-char'. Then, use `C-RET' to
5294 ;; execute that command. Repeat as many times as you want. Use a
5295 ;; prefix arg if you like.
5297 ;; To switch to another command in the same `M-x' invocation: Erase
5298 ;; the minibuffer (`M-k'), complete the second command, then use
5299 ;; `C-RET'. As long as you have not yet used `RET', `S-RET', `C-g'
5300 ;; (or, say, `C-]'), you remain within the same invocation of `M-x'.
5302 ;; What about executing a command that, itself, reads an input
5303 ;; argument? That's OK. And if that command reads its input with
5304 ;; completion, then you can use `C-RET' on the completion candidates
5307 ;; Example: `M-x describe-fa TAB C-RET' gives you the prompt for
5308 ;; command `describe-face'.
5310 ;; 1. Type `ici S-TAB' to see the available Icicles faces.
5312 ;; 2. Hit `next' until face `icicle-complete-input' is highlighted.
5314 ;; 3. Hit `C-RET' to display its documentation.
5316 ;; 4. Type `C-next' a few times to see the doc of other Icicles
5319 ;; 5. Use `M-k' to erase the minibuffer, then type `search S-TAB' to
5320 ;; see faces about searching.
5322 ;; 6. Cycle through them with `next', then use `C-RET' on
5323 ;; `icicle-search-main-regexp-current' to show its documentation.
5325 ;; 7. Use `C-next' to do the same for face
5326 ;; `icicle-search-main-regexp-others'.
5328 ;; 8. Use `RET' to finish with command `describe-face' - but you're
5329 ;; still in the same invocation of `M-x'.
5331 ;; 9. Change the input to `describe-coding-system' and play again,
5332 ;; this time with coding-system names...
5334 ;; Remember, if you get confused or lost: `C-]'
5335 ;; (`abort-recursive-edit') or `M-x top-level' should always
5336 ;; straighten you out.
5338 ;;(@* "What about describe-variable and describe-function?")
5339 ;; *** What about describe-variable and describe-function? ***
5341 ;; Sadly, if you try the last example with `describe-variable' or
5342 ;; `describe-function', you might be in for a surprise. In Emacs 20,
5343 ;; they both work fine. In later Emacs versions, `describe-variable'
5344 ;; gives you the message "You did not specify a variable", and
5345 ;; `describe-function' displays a `*Help*' buffer that says that each
5346 ;; function you choose is really a keyboard macro!
5348 ;; Why? It's a bit complex, but worth hearing about if you want to
5349 ;; understand multi M-x better.
5351 ;; When you choose a command that reads an argument in the minibuffer
5352 ;; and you then hit a multi-command key such as `C-RET' to choose an
5353 ;; argument, Icicles tries to apply the command you chose to the
5354 ;; argument you chose. However, completion candidates are always
5355 ;; strings, and the command you chose might expect something other
5356 ;; than a string. That is the case for `describe-variable', for
5357 ;; instance. The case of describe-function' is special: it
5358 ;; interprets a string argument blindly as a keyboard macro sequence.
5360 ;; Icicles is smart enough to pick up a `wrong-type-argument' error,
5361 ;; if the command you choose barfs on a string argument. In that
5362 ;; case, Icicles converts the string to a symbol (or a number) and
5363 ;; tries again, using the symbol (or the number).
5365 ;; And that's why `describe-variable' works in Emacs 20 but not in
5366 ;; later versions: In Emacs 20, `describe-variable' (sanely) raises a
5367 ;; type error if you pass it a string, and Icicles is able to save
5368 ;; the day by then passing it the corresponding symbol. In later
5369 ;; versions of Emacs, however, instead of raising an error with the
5370 ;; message "You did not specify a variable", `describe-variable' just
5371 ;; displays the message - no error, so there is no way for Icicles to
5374 ;; I've reported this design misfeature to the Emacs developers, and
5375 ;; I hope it will be fixed in a future Emacs version. Until then, at
5376 ;; least you know... The more general lesson is this: Icicles can
5377 ;; turn every command into a multi-command, but multi-command actions
5378 ;; will not work for every command.
5380 ;;(@* "Multi `M-x' Turns Every Command into a Multi-Command")
5381 ;; *** Multi `M-x' Turns Every Command into a Multi-Command ***
5383 ;; Most of the time, of course, you do not execute commands
5384 ;; successively by name; instead, you use key bindings. The point
5385 ;; here is that even if you have a binding for a command, Icicles
5386 ;; `M-x' lets you use any command as a multi-command, which can
5387 ;; sometimes be advantageous.
5389 ;; For example, Icicles defines and binds a real multi-command to
5390 ;; `C-x 0' in Icicle mode, which lets you delete any number of
5391 ;; windows. But, even without such a multi-command, you can get a
5392 ;; similar effect by using `M-x delete-windows-on'. In this way, you
5393 ;; can turn ordinary Emacs commands that use completion into
5396 ;; The other point is that you can move from one command to another
5397 ;; within the same execution of `M-x'. This is a different feature
5398 ;; from being able to use any command that uses completion as a
5399 ;; multi-command. Both features have their uses.
5401 ;;(@* "Multi `M-x' with Abbreviations: `icicle-command-abbrev'")
5402 ;; ** Multi `M-x' with Abbreviations: `icicle-command-abbrev' **
5404 ;; The second multi-command that you can use in place of
5405 ;; `execute-extended-command' is `icicle-command-abbrev', bound in
5406 ;; Icicle mode to `C-x SPC'. It is similar to `M-x'
5407 ;; (`icicle-execute-extended-command'), with the added twist that it
5408 ;; lets you input command abbreviations, as well as commands.
5410 ;; If option `icicle-add-proxy-candidates-flag' is non-`nil', then
5411 ;; command abbreviations, as well as commands, are available as
5412 ;; completion candidates. Otherwise, only commands are available.
5413 ;; You can toggle this user option using `C-M-_' in the minibuffer.
5415 ;; Emacs partial completion and some other libraries provide ways for
5416 ;; you to enter command abbreviations instead of command names at the
5417 ;; command prompt (`M-x'). Library `exec-abbrev-cmd.el' by Tassilo
5418 ;; Horn <tassilo@member.fsf.org> is an example.
5420 ;; So just what is a command abbreviation? Hyphens (`-') in command
5421 ;; names divide them into parts. For example, `find-file' has two
5422 ;; parts: `find' and `file'. Each character of a command
5423 ;; abbreviation corresponds to one part of each of the commands that
5424 ;; match the abbreviation. For example, abbreviation `ff' matches
5425 ;; commands `find-file' and `focus-frame', and abbreviation `fg'
5426 ;; matches `find-grep'.
5428 ;; If user option `icicle-command-abbrev-match-all-parts-flag' is
5429 ;; `nil', then an abbreviation need not match all parts of a command
5430 ;; name; it need match only a prefix. For example, `nil' means that
5431 ;; abbreviation `ff' also matches `find-file-other-window' and `fg'
5432 ;; also matches `find-grep-dired'.
5434 ;; In Icicles, you can input both abbreviations and commands at the
5435 ;; same prompt, and you can take advantage of the multi-command
5436 ;; feature to execute multiple commands. You can thus treat command
5437 ;; abbreviations just like commands. If an abbreviation matches a
5438 ;; single command name, then that command is invoked immediately. If
5439 ;; it matches more than one, then you can use completion to choose
5442 ;; One or more, that is - multi-command completion is available for
5443 ;; both abbreviations and commands. That is, you can invoke any
5444 ;; number of them within the same use of `C-x SPC'.
5446 ;; What happens if your input matches a command name but it is also
5447 ;; an abbreviation for other command names? By default, command
5448 ;; names take precedence: if your input matches a command name then
5449 ;; that command is invoked. So, for example, by default the command
5450 ;; `cd' takes precedence over `cd' as an abbreviation for commands
5451 ;; such as `compile-defun' and `cancel-debug-on-entry'. If you
5452 ;; instead want abbreviations to take precedence over command names,
5453 ;; then set option `icicle-command-abbrev-priority-flag' to `t'.
5455 ;; Abbreviations are completed against the (persistent) list of
5456 ;; abbreviations you have used in the past. That list is also
5457 ;; directly customizable as option `icicle-command-abbrev-alist'.
5459 ;; Besides completing against past abbreviations, you can enter new
5460 ;; abbreviations (the completion is thus lax). When you exit Emacs,
5461 ;; your abbreviations list is updated and saved, along with the
5462 ;; number of times you've used each abbreviation. The latter
5463 ;; information is used to sort your abbreviations for completion, so
5464 ;; that those used most frequently are available first.
5466 ;;(@* "Choose All Completion Candidates")
5468 ;; Choose All Completion Candidates
5469 ;; --------------------------------
5471 ;; The previous section describes how you can use `C-RET'
5472 ;; (`icicle-candidate-action') to choose (act on) multiple completion
5473 ;; candidates, individually. If you hold down the Control key while
5474 ;; you cycle through the candidates, you can run through each of
5475 ;; them, one by one.
5477 ;; Command `icicle-all-candidates-action', which is bound to `C-!' in
5478 ;; the minibuffer, is a shorthand way of doing that: act on all
5479 ;; candidates that match the current input. In many contexts, `C-!'
5480 ;; reports on any objects that were not acted upon successfully (in
5481 ;; buffer `*Help*').
5483 ;; All multi-commands let you use `C-!' in this way. Whenever a
5484 ;; command defines a special action for `C-RET' to perform on the
5485 ;; current completion candidate, you can use `C-!' to perform it on
5486 ;; all candidates at once.
5488 ;; Perhaps you already use `% m' (command `dired-mark-files-regexp')
5489 ;; in Dired to mark all files that match a given regular expression,
5490 ;; and then operate on all of the marked files in some way (search
5491 ;; with `A', query-replace with `Q', open with `F', delete with `D',
5492 ;; and so on). When you execute a multi-command, `C-!' lets you do
5493 ;; something similar.
5495 ;; How does it work? It applies `icicle-candidate-action-fn' to each
5496 ;; completion candidate that (apropos- or prefix-) matches the
5497 ;; current input in the minibuffer.
5499 ;; Most top-level Icicles commands are multi-commands. Command
5500 ;; `icicle-delete-file' is an example. Instead of entering a file
5501 ;; name at the prompt (e.g. using completion or cycling), you can
5502 ;; type a regular expression, use `S-TAB' to see all matching files,
5503 ;; and then use `C-!' to delete all of them at once.
5505 ;; You get the idea: Use the minibuffer to determine a set of objects
5506 ;; by pattern matching, and then act on all elements of the set.
5508 ;; In addition to `C-!', keys `M-!', `C-|', and `M-|' act similarly:
5510 ;; * `M-!' is like `C-!', but it acts on the list of matching
5511 ;; candidates as a whole, rather than acting individually on each
5512 ;; candidate. For example, with command `icicle-customize-face',
5513 ;; `M-!' opens a single Customize buffer for all of the matching
5514 ;; faces, while `C-!' opens a separate Customize buffer for each
5517 ;; * `C-|' and `M-|' are like `C-!' and `M-!', respectively, but they
5518 ;; apply an alternative action, not the main action, whenever one
5521 ;; In the definition of a given multi-command, the appropriate action
5522 ;; functions are bound to variables:
5524 ;; * `icicle-candidate-action-fn' (`C-!') - normal single-candidate
5527 ;; * `icicle-candidate-alt-action-fn' (`C-|') - alternative
5528 ;; single-candidate action
5530 ;; * `icicle-all-candidates-list-action-fn' (`M-!') - normal
5531 ;; list-of-candidates action
5533 ;; * `icicle-all-candidates-list-alt-action-fn' (`M-|') - alternative
5534 ;; list-of-candidates action
5536 ;; For most multi-commands, however, only the normal single-candidate
5537 ;; action is defined. In this case, `M-!' duplicates what `C-!'
5538 ;; does. If the corresponding function is not available, each of the
5539 ;; list-action keys (`M-!', `M-|') behaves the same as the
5540 ;; corresponding single-candidate key (`C-!', `C-|), and vice versa.
5541 ;; So for instance, if `icicle-all-candidates-list-action-fn' is
5542 ;; `nil' when reading some input, then `M-!' acts the same as `C-!'.
5544 ;; As a shortcut, if you have saved completion candidates and they
5545 ;; all belong to the current set of completion candidates, then `C-!'
5546 ;; acts on the saved candidates instead of the complete set of
5547 ;; candidates. This means that you need not first do `C-M-<' to
5548 ;; retrieve the saved candidates; you can do `C-!' directly to act on
5549 ;; them. `C-|', `M-!', and `M-|' work the same way.
5551 ;; All of the all-candidates actions inhibit candidate help display
5552 ;; in the mode line and minibuffer messages that the individual
5553 ;; actions might effect. This is to avoid unnecessary delays.
5557 ;; * (@file :file-name "icicles-doc2.el" :to "Icicles Dired Enhancements")
5558 ;; for an Icicles alternative to both `A' and `Q' (search and
5559 ;; replace) in Dired.
5561 ;;(@* "Sets of Completion Candidates")
5563 ;; Sets of Completion Candidates
5564 ;; -----------------------------
5566 ;; Whereas `C-RET' acts on individual objects, `C-!' acts on an
5567 ;; entire set of objects at once, via their names: the set of all
5568 ;; current completion candidates. There are additional Icicles
5569 ;; commands that also act, not on individual completion candidates,
5570 ;; but on one or more sets of completion candidates.
5572 ;; One of these is `M-*', which effectively narrows the set of
5573 ;; completion candidates by taking the intersection of the candidate
5574 ;; sets defined by various input regexps.
5576 ;; This section presents some more Icicles commands that act on sets
5577 ;; of completion candidates. The basic idea is that you can perform
5578 ;; set operations using the current set of completion candidates,
5579 ;; changing it into a different set. You can, then, for example, use
5580 ;; `C-!' to act on everything in a custom-defined set. Or you can
5581 ;; define a custom set that you want to use often (for example, a
5582 ;; list of project files), save it persistently, and then retrieve it
5583 ;; later to use for completion.
5585 ;;(@* "Saving and Retrieving Completion Candidates")
5586 ;; ** Saving and Retrieving Completion Candidates **
5588 ;; Set operations such as union and difference act on two sets. The
5589 ;; current set of completion candidates is always one of these sets.
5590 ;; If an operation, such as set complement, acts on a single set,
5591 ;; then it acts on the current set.
5593 ;; When two sets are involved, the other set is called the "saved
5594 ;; set". This just means that at some previous time in your sesssion
5595 ;; you saved some completion candidates as the value of variable
5596 ;; `icicle-saved-completion-candidates'.
5598 ;; In buffer `*Completions*', candidates that have been saved are
5599 ;; highlighted using face `icicle-saved-candidate'.
5601 ;; By default, the saved set is not persistent; it is saved only
5602 ;; until the next save in the same Emacs session overwrites it or
5603 ;; adds to it. See (@> "Persistent Sets of Completion Candidates")
5604 ;; for ways to save candidates persistently.
5606 ;; One way you can save candidates is to use
5607 ;; `icicle-candidate-set-save', bound to `C-M->'. This saves all of
5608 ;; the current candidates.
5610 ;; Gotcha: If you use progressive completion and you have not yet
5611 ;; typed anything after `M-*' or `S-SPC', then there is not
5612 ;; yet a set of candidates to save. If you use `C-M->' at
5613 ;; that point, you will reset the saved candidates to none.
5614 ;; To define the current candidates, either type something or
5617 ;; Another way to save candidates, besides `C-M->', is to select
5618 ;; candidates in buffer `*Completions*' using the (active) region,
5619 ;; and then use `icicle-candidate-set-save-selected', bound to
5620 ;; `C-M-)'. This saves any candidates that are at least partially in
5623 ;; You can also use `C-M-)' to UNsave all candidates: just select no
5624 ;; candidates before you hit `C-M-)', to reset the set of saved
5625 ;; completions to none. Think of this as replacing the saved set
5626 ;; with the empty set (no candidates). And you need not use `TAB' or
5627 ;; `S-TAB' first to use this, since the current set of candidates is
5628 ;; not used in any way when you reset the saved set.
5630 ;; Command `icicle-mouse-candidate-set-save', bound to `M-S-mouse-3'
5631 ;; in `*Completions*' combines these two: if the region is active,
5632 ;; then the selected candidates become the saved set; otherwise, all
5633 ;; candidates are saved. This binding makes it easy to save
5634 ;; candidates using the mouse: select them (e.g. drag or double-click
5635 ;; `mouse-1', or click `mouse-1' then `mouse-3'), then use
5636 ;; `M-S-mouse-3' to save. [*]
5638 ;; You can process the list of saved candidates in any way you like
5639 ;; using Emacs Lisp. For example, you can save a list of file names
5640 ;; that match a regexp, then print the list or process the individual
5641 ;; files in some way. Here, for instance, is how to save the set of
5642 ;; file names that contain either `dir' or `ici':
5644 ;; `C-x C-f \(dir\|ici\) S-TAB C-M-> C-g'
5646 ;; You can retrieve a set of saved candidates with command
5647 ;; `icicle-candidate-set-retrieve', bound to `C-M-<'. This replaces
5648 ;; the current set of candidates with those retrieved. It also acts
5649 ;; like `M-*' by entering a recursive minibuffer, which removes any
5650 ;; saved-candidates highlighting. Using `TAB' or `S-TAB' restores
5651 ;; the highlighting.
5653 ;; You can use `C-<' to retrieve a set of saved candidates and add
5654 ;; them to the current candidates, instead of replacing those
5655 ;; candidates. This way, you can build up the current set of
5656 ;; candidates by retrieving (combining) several saved sets.
5658 ;; In the other direction, you can save additional candidates, adding
5659 ;; them to a set of candidates already saved, in these ways:
5661 ;; * `C->' (`icicle-candidate-set-save-more') adds all of the current
5664 ;; * `C-)' (`icicle-candidate-set-save-more-selected') adds any
5665 ;; candidates that you have selected using the region in
5668 ;; * `M-mouse-3' (`icicle-mouse-candidate-set-save-more') acts the
5669 ;; same as `C-)' or `C->', depending on whether or not the region
5670 ;; is active in `*Completions*': it adds selected or all
5673 ;; * Extending the region with `mouse-3', and then clicking `mouse-3'
5674 ;; again in the same place, acts the same as `C-)'. That is, click
5675 ;; `mouse-1', then click `mouse-3' twice in another location, to
5676 ;; save all candidates between the `mouse-1' and `mouse-3'
5679 ;; * The `insert' key (`icicle-save/unsave-candidate') adds just the
5680 ;; current completion candidate (e.g. during cycling). Clicking a
5681 ;; candidate in `*Completions*' with `M-S-mouse-2'
5682 ;; (`icicle-mouse-save/unsave-candidate') does the same thing. If
5683 ;; you do this to a candidate that has already been saved, then it
5684 ;; is UNsaved (no longer saved).
5686 ;; Note that the `insert' key and `M-S-mouse-2' are toggles for a
5687 ;; given candidate, saving or unsaving it. In this sense each is its
5688 ;; own opposite. In another sense, the opposite operation of saving
5689 ;; is simply removing a candidate from the current set of candidates.
5690 ;; You do that using the `delete' key or `S-mouse-2'.
5692 ;; Matching, saving, and retrieving candidates is a powerful way to
5693 ;; interact with completion. One important use is to prepare a list
5694 ;; of candidates on which to act, and then act on them all at once
5695 ;; using `C-!'. This is a good way to proceed when you want to
5696 ;; double-check what to act on, before you actually act. This is the
5697 ;; same idea behind marking files in Dired and then operating on the
5698 ;; marked files, using `x'. It corresponds to what is represented in
5699 ;; some user interfaces by filling out a checklist followed by
5702 ;; [* If you click `mouse-1' on a candidate and (starting with Emacs
5703 ;; 22) `mouse-1-click-follows-link' is an integer, then you will need
5704 ;; to hold the mouse button depressed longer than that many seconds,
5705 ;; or else that candidate will simply by chosen. If the value is
5706 ;; `t', then this will not work at all. Any other value presents no
5707 ;; problem. (Personally, I use `nil'.)]
5709 ;;(@* "Different Places for Saving and Retrieving Candidates")
5710 ;; ** Different Places for Saving and Retrieving Candidates **
5712 ;; You can save completion candidates to a different variable from
5713 ;; `icicle-saved-completion-candidates' by using a numeric prefix
5714 ;; argument to command `icicle-candidate-set-save'; that is, use `C-u
5715 ;; N C-M->'. Alternatively, use `C-M-}', which is bound to command
5716 ;; `icicle-candidate-set-save-to-variable'. You are prompted for the
5717 ;; name of the variable, and you can use completion when inputting
5718 ;; it. During this completion, the only available candidates are
5719 ;; variables that you have used for saved candidates (but completion
5720 ;; is lax, so you can type a new variable name). The same behavior
5721 ;; works also for `C->', `C-M-)', and `C-)'.
5723 ;; To retrieve completion candidates that were previously saved to a
5724 ;; variable other than `icicle-saved-completion-candidates', so that
5725 ;; they become the current set of candidates, use `C-u N C-M-<',
5726 ;; where N is an integer, or `C-M-{' (`icicle-candidate-set-retrieve'
5727 ;; or `icicle-candidate-set-retrieve-from-variable').
5729 ;; Using a plain prefix argument (`C-u' without a number) with
5730 ;; `C-M->' and `C-M-<' saves or retrieves a candidate set using a
5731 ;; cache file, not a variable. Alternatively, as a shortcut you can
5732 ;; use `C-}' and `C-{' for this.
5733 ;; See (@> "Persistent Sets of Completion Candidates") and
5734 ;; (@file :file-name "icicles-doc2.el" :to "Support for Projects").
5736 ;; When you save candidates to a different variable from
5737 ;; `icicle-saved-completion-candidates', they are not shown in buffer
5738 ;; `*Completions*' using face `icicle-saved-candidate'. When you
5739 ;; save candidates to a cache file, they are also saved to
5740 ;; `icicle-saved-completion-candidates', so they are shown in
5741 ;; `*Completions*' using face `icicle-saved-candidate'.
5743 ;; `C->' and `C-<' accept the same prefix arguments as `C-M->' and
5744 ;; `C-M-<' , letting you specify the source or destination (variable,
5745 ;; cache file) when you save or retrieve additional candidates.
5747 ;;(@* "Set Operations")
5748 ;; ** Set Operations **
5750 ;; The other available set-operation commands for use with completion
5751 ;; candidates, besides saving and retrieving, are these:
5753 ;; * `icicle-candidate-set-swap', bound to `C-%'. Swap the saved and
5754 ;; current sets of completion candidates.
5756 ;; * `icicle-candidate-set-define', bound to `C-:'. Define the
5757 ;; current set of completion candidates by evaluating an input
5758 ;; sexp. The sexp must evaluate to a list of strings, such as is
5759 ;; returned by `all-completions'. You can use this to substitute
5760 ;; any list of strings, and then operate on them as completions,
5761 ;; using any Icicles functionalities. Keep in mind, however, that
5762 ;; the completions must be of the proper type for the context in
5763 ;; which they are used. For example, if you are executing a
5764 ;; command, they must be command names.
5766 ;; * `icicle-candidate-set-complement', bound to `C-~'. Complement
5767 ;; the current set of candidates: replace the current candidate set
5768 ;; with its set complement. This means all possible completions of
5769 ;; the appropriate type that do *not* match the current input. You
5770 ;; can combine this with progressive completion (`M-*') to
5771 ;; progressively eliminate candidates that match different inputs.
5772 ;; This process-of-elimination matching is a common Icicles usage
5775 ;; * `icicle-candidate-set-union', bound to `C-+'. Replace the
5776 ;; current candidate set by its union with the saved set of
5779 ;; * `icicle-candidate-set-difference', bound to `C--'. Replace the
5780 ;; current candidate set by its set difference with the saved set
5781 ;; of candidates. That is, the saved candidates are subtracted
5782 ;; from the current candidates, and the result becomes the current
5783 ;; candidate set. To obtain the opposite set difference,
5784 ;; subtracting the current candidates from the saved candidates,
5785 ;; just use `icicle-candidate-set-swap' followed by
5786 ;; `icicle-candidate-set-difference'.
5788 ;; * `icicle-candidate-set-intersection', bound to `C-*'. Replace
5789 ;; the current candidate set by its intersection with the saved set
5790 ;; of candidates. Unlike the set intersection provided by `M-*',
5791 ;; `C-*' is, in itself, a one-time operation. `M-*' can be
5792 ;; repeated, using the previous intersection as one of the sets to
5793 ;; be intersected in a new operation. Both `C-*' and `M-*' use the
5794 ;; current set of matching candidates as one of the sets being
5795 ;; intersected. But `M-*' reads another input regexp to define the
5796 ;; other set to be intersected, whereas `C-*' uses the saved
5797 ;; candidates set as the other set. `M-*' is useful for chaining,
5798 ;; to achieve progressive approximation. `C-*' is useful to
5799 ;; perform an intersection on a set from a previous input reading.
5801 ;; * `icicle-candidate-set-truncate', bound to `M-$'. Truncate the
5802 ;; set of completion candidates, so that it includes only the first
5803 ;; N candidates (as displayed in `*Completions*'). You are
5804 ;; prompted for N. You can use this when the order of candidates
5805 ;; represents priority in some way, so that you are interested only
5806 ;; in the topmost candidates.
5808 ;; You can operate on or choose from all input values in the set that
5809 ;; results from any of these set operations. For example, you can
5810 ;; use `C-~' to see the list of objects that do not match the current
5811 ;; input, to cycle among those objects, or to operate on any or all
5812 ;; of them. Use `C-~' at any time to switch to the complement of the
5813 ;; current set of candidates.
5815 ;; Example: To cycle through all files whose names do not end in
5816 ;; `el', you can do the following:
5818 ;; 1. Use `C-f' to read a file name.
5819 ;; 2. Type `el$' to match all file names that end in `el'.
5820 ;; 3. Use `S-TAB' to show the matching files.
5821 ;; 4. Use `C-~' to flip to the complement: files not ending in `el'.
5822 ;; 5. Use `next' or `prior' to cycle among the new set of candidates.
5824 ;; A minibuffer message briefly confirms each of the set operations.
5826 ;; When buffer `*Completions*' is displayed, the union, difference,
5827 ;; and intersection commands scroll the buffer when repeated.
5828 ;; Repeating `icicle-candidate-set-complement' complements the
5829 ;; complement, of course, giving the original set.
5831 ;; Once you have established a set of completion candidates using any
5832 ;; of the candidate-set commands, you can cycle among the candidates
5833 ;; of that set using either prefix or apropos cycling (`down', `up',
5834 ;; `next', `prior', `end', or `home'). However, switching from
5835 ;; prefix to apropos cycling (or completion), or vice versa,
5836 ;; establishes a new completion set of the appropriate type, as
5837 ;; usual. Switching completion type signifies that you are finished
5838 ;; with the specially defined completion set, and you want to
5839 ;; redefine it using apropos or prefix cycling or completion.
5841 ;; Note: Prefix icompletion (`icomplete.el' or `icomplete+.el' - see
5842 ;; (@> "Icompletion")) does not take into account the candidate
5843 ;; set resulting from a set operation: it always displays the
5844 ;; normal set of prefix completions in the minibuffer.
5846 ;; Note: You might have noticed that, as a mnemonic device, the keys
5847 ;; bound to the various set operations use the corresponding
5848 ;; binary arithmetic or Boolean operators: `~' (unary negation)
5849 ;; for complement (not); `*' (multiplication) for intersection
5850 ;; (and); `+' (addition) for union (or); and `-' (subtraction)
5851 ;; for difference. Note too that the `C--' and `C-+' bindings
5852 ;; mean that you cannot use these key sequences for prefix
5853 ;; arguments - you must use `C-u N', or `M-N' instead, where N
5854 ;; is a possibly signed integer.
5858 ;; * (@> "Multi-Commands") for information about `C-RET'.
5860 ;; * (@> "Choose All Completion Candidates") for information about
5863 ;; * (@> "Progressive Completion") for information about `M-*'.
5865 ;; * (@> "File-Name Input and Locating Files Anywhere") and
5866 ;; (@> "Persistent Sets of Completion Candidates"), for information
5867 ;; about saving completion candidates persistently and retrieving
5870 ;; * (@> "History Enhancements"), (@> "Google Matching"), and
5871 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
5872 ;; for examples of other set operations on input candidates.
5874 ;; * (@file :file-name "icicles-doc2.el" :to "Icicles Dired Enhancements")
5875 ;; for information about saving and reusing sets of file-name
5876 ;; candidates with Dired.
5878 ;;(@* "Google Matching")
5883 ;; This section presents nothing new - but you might not want to skip
5884 ;; it. It points out something that you might not have picked up
5885 ;; yet. You've learned about Icicles regexp matching and candidate
5886 ;; set operations, but it can be worthwhile to compare how Icicles
5887 ;; matches inputs against completion candidates with how Google
5888 ;; matches search strings against Web pages. Summary: You can do
5889 ;; pretty much the same things, but the way you accomplish them is
5892 ;;(@* "Domain of Discourse")
5893 ;; ** Domain of Discourse **
5895 ;; In Google, the domain of discourse, that is, the possible set of
5896 ;; search hits, is the set of Web pages. There are also search
5897 ;; fields that limit the domain of discourse by file type, page
5898 ;; number, update date, page position, freedom of use, and even
5899 ;; morality ("Safe Search").
5901 ;; In Icicles (Emacs), the domain of discourse changes automatically,
5902 ;; depending on the current context. For command-name input, it is
5903 ;; the set of all named commands; for variable-name input, it is the
5904 ;; set of variable names; and so on.
5906 ;;(@* "Global Filtering")
5907 ;; ** Global Filtering **
5909 ;; In Google, you can limit searching to specific Web sites, or
5910 ;; exclude certain Web sites from searching.
5912 ;; In Icicles, you can add extra completion candidates using variable
5913 ;; `icicle-extra-candidates', and you can filter out (other)
5914 ;; candidates globally using filter variables
5915 ;; `icicle-must-match-regexp', `icicle-must-not-match-regexp',
5916 ;; `icicle-must-pass-predicate', and
5917 ;; `icicle-must-pass-after-match-predicate'. These are internal
5918 ;; Icicles variables. Normally, you do not change them directly;
5919 ;; instead, a command can use them to limit or extend the effective
5920 ;; domain of discourse.
5921 ;; See (@file :file-name "icicles-doc2.el" :to "Global Filters").
5923 ;; Variables `icicle-must-pass-predicate' and
5924 ;; `icicle-must-pass-after-match-predicate' apply to the textual
5925 ;; candidates that can be displayed in buffer `*Completions*'. You
5926 ;; can also apply a predicate to the full alist-entry or
5927 ;; obarray-symbol candidates that are supplied to `completing-read'
5928 ;; or `read-file-name' as its COLLECTION argument. As a programmer,
5929 ;; you can of course do that when your code calls these functions.
5930 ;; As an Icicles user, you can use `M-&' to define and apply
5931 ;; predicates to such alist-entry candidates on the fly, while
5933 ;; See (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview").
5935 ;;(@* "Word Matching and String Matching")
5936 ;; ** Word Matching and String Matching **
5938 ;; Google matches words, by default, but you can specify an "exact
5939 ;; phrase" to get literal string matching.
5941 ;; By default, Icicles (apropos-)matches regexps, but you can use
5942 ;; `\b' in a regexp to perform word matching, and you can use `C-`'
5943 ;; (`icicle-toggle-regexp-quote') to perform exact (literal)
5944 ;; matching. See (@> "What About Special-Character Conflicts?").
5946 ;;(@* "AND Matching and OR Matching")
5947 ;; ** AND Matching and OR Matching **
5949 ;; Google has search fields for AND matching ("with all of the
5950 ;; words") and OR matching ("with at least one of the words").
5952 ;; In Icicles, you can use progressive completion to perform AND
5953 ;; matching: use `M-*' to introduce each term to match.
5954 ;; Alternatively, you can use `C-*'
5955 ;; (`icicle-candidate-set-intersection'). You can use `C-+'
5956 ;; (`icicle-candidate-set-union') to perform OR matching. Note that,
5957 ;; by definition, unordered AND matching is not possible using a
5958 ;; single regexp. See (@> "Progressive Completion") and
5959 ;; (@> "Sets of Completion Candidates").
5961 ;;(@* "NOT Matching")
5962 ;; ** NOT Matching **
5964 ;; Google has a search field for terms that must not occur in search
5965 ;; hits: "without the words".
5967 ;; In Icicles, you can use `C-~' (`icicle-candidate-set-complement')
5968 ;; to exclude matching completion candidates. You can combine this
5969 ;; with progressive completion, to exclude any number of terms: `toto
5970 ;; C-~ M-* titi C-~ M-* foobar' excludes all candidates matching
5971 ;; toto, titi, or foobar. Use this process-of-eliminiation technique
5972 ;; to progressively pare down the set of possible candidates. Note
5973 ;; that such generalized complementing (as opposed to complementing a
5974 ;; character set) is not possible using a single regexp - you cannot
5975 ;; use a regular expression to say "Show me everything that does
5976 ;; *not* match this". See (@> "Sets of Completion Candidates") and
5977 ;; (@> "Progressive Completion").
5979 ;;(@* "Buffer-Name Input")
5981 ;; Buffer-Name Input
5982 ;; -----------------
5984 ;; The Icicles commands that read buffer names are multi-commands
5985 ;; (see (@> "Multi-Commands")), so you can act on more than one
5986 ;; buffer during a given command invocation.
5988 ;; These commands all let you use a prefix argument to control which
5989 ;; buffers are completion candidates. It is the numeric value of the
5990 ;; prefix arg that matters:
5992 ;; * Positive: only buffers visiting files
5993 ;; * Zero: only buffers with the same mode as the current buffer
5994 ;; * Negative: only buffers associated with the selected frame
5996 ;; In addition to the usual Icicles key bindings, during buffer-name
5997 ;; completion you can use the following keys:
5999 ;; * `C-x M' (`icicle-filter-buffer-cands-for-mode') to filter the
6000 ;; buffer-name candidates to keep only those with a given major
6001 ;; mode. You are prompted for the mode.
6003 ;; * `C-x m' (`icicle-bookmark-non-file-other-window') to visit a
6004 ;; bookmarked buffer. This is available only if you use library
6005 ;; `bookmark+.el'. This too is a multi-command, so you can
6006 ;; actually visit any number of buffer bookmarks with one use of
6007 ;; `C-x m'. When finished, you can continue with non-bookmark
6008 ;; buffer-name completion.
6010 ;; * `S-delete' to kill the buffer named by the current completion
6013 ;; During completion, candidate sorting is specific to buffer names.
6014 ;; `C-,' cycles among the following sort orders:
6017 ;; * `*...*' last: put buffers such as `*Messages*' and `*Help*' last
6019 ;; * by major mode name
6020 ;; * by mode-line mode name (mode name that appears in the mode line)
6021 ;; * by (absolute) file or process name
6023 ;; Finally, several user options control the completion behavior.
6024 ;; See (@file :file-name "icicles-doc2.el" :to "Customization and General Tips")
6025 ;; and (@file :file-name "icicles-doc2.el" :to "Global Filters").
6030 ;; * (@> "Ido and IswitchB") to use Icicles with a buffer-switching
6031 ;; behavior that is similar to Ido and IswitchB
6032 ;; * (@> "`M-&': Satisfying Additional Predicates") to filter the
6033 ;; buffer candidates on the fly in multiple ways (e.g. size)
6035 ;;(@* "File-Name Input and Locating Files Anywhere")
6037 ;; File-Name Input and Locating Files Anywhere
6038 ;; -------------------------------------------
6040 ;; Emacs offers two main functions for reading minibuffer input with
6041 ;; completion: `completing-read' and `read-file-name'. Icicles uses
6042 ;; both of these, and it enhances each of them in various ways for
6043 ;; use in your own Emacs-Lisp code. These two functions can each be
6044 ;; used to read file-name input, but they do so in very different
6047 ;; In addition to the usual Icicles key bindings, during file-name
6048 ;; completion you can use the following keys:
6050 ;; * `C-backspace' (`icicle-up-directory') to navigate up the
6051 ;; directory hierarchy. It removes the last directory component
6052 ;; (and any partial file name) from your minibuffer input.
6054 ;; (For Emacs versions before Emacs 22, this feature is available
6055 ;; only for completion of absolute file names.)
6057 ;; * `C-c +' (`icicle-make-directory') to create a directory on the
6060 ;; * `C-x m' (`icicle-bookmark-file-other-window') to visit a
6061 ;; bookmarked file or directory. This is available only if you use
6062 ;; library `bookmark+.el'. It is a multi-command, so you can
6063 ;; actually visit any number of file bookmarks. When finished, you
6064 ;; can continue with non-bookmark file-name completion.
6066 ;; * `S-delete' to delete the file named by the current completion
6069 ;; * `M-|' (`icicle-all-candidates-list-alt-action') to open Dired on
6070 ;; the currently matching file names. That is, it opens a special
6071 ;; Dired buffer that contains only the matching files. You are
6072 ;; prompted for the Dired buffer name. See (@> "Alternative Actions").
6074 ;; In many cases for Icicles multi-commands that read a file name,
6075 ;; you can use `M-n' to pick up the file name at point, or if none
6076 ;; then the name of the file you are currently visiting.
6078 ;; Note: Whether a command supports file-name globbing wildcards such
6079 ;; as `*' is independent of whether it uses `read-file-name' or
6080 ;; `completing-read'. It is the command itself that offers such
6081 ;; support or not. Globbing takes place only after the file name
6082 ;; (with wildcards) is read. All Icicles commands that visit files
6083 ;; (all of the commands mentioned in this section) let you use
6084 ;; globbing wildcards. Remember also that file-name globbing, with
6085 ;; its special wildcards, has nothing to do with regexp completion
6086 ;; matching. See (@> "What About Special-Character Conflicts?") for
6087 ;; more information about file-name globbing.
6089 ;;(@* "Function `read-file-name'")
6090 ;; ** Function `read-file-name' **
6092 ;; Function `read-file-name' is specialized for file-name input with
6093 ;; completion. It knows about files and file names for your current
6094 ;; platform. It knows about Emacs remote file name syntax (Tramp,
6095 ;; Ange FTP). And starting with Emacs 23, `TAB' also completes
6096 ;; environment variables during `read-file-name' completion.
6098 ;; Using `read-file-name' is the most flexible way to read a file
6099 ;; name in Emacs, and it is the traditional way. Unless stated
6100 ;; otherwise, "file-name completion", even in the Icicles doc, refers
6101 ;; to `read-file-name' completion.
6103 ;; When `read-file-name' reads input, only the file name itself, not
6104 ;; the directory portion, is used for matching. The directory is
6105 ;; understood to be the value of variable `default-directory' (which
6106 ;; you can change using command `cd', for instance). The behavior is
6107 ;; thus the same whether or not the directory name is present in the
6108 ;; minibuffer. If you prefer, you can delete the directory name
6109 ;; first, using `M-k'.
6111 ;; With `read-file-name', you can thus use apropos completion to
6112 ;; match a file-name substring, without needing to prefix the
6113 ;; substring with `.*' in the minibuffer. For example, to match the
6114 ;; file named `favorite-foo-file.bar' in directory
6115 ;; `/some/path/to/my/', you need not use `/some/path/to/my/.*foo'; it
6116 ;; is sufficient to use either `foo' or `/some/path/to/my/foo'.
6118 ;; An additional feature of `read-file-name' in Icicle mode is that
6119 ;; candidates that are directory names are highlighted in buffer
6120 ;; `*Completions*' using face `icicle-special-candidate'.
6122 ;;(@* "Function `completing-read'")
6123 ;; ** Function `completing-read' **
6125 ;; Function `completing-read' is a general function for reading input
6126 ;; with completion. It is not specially designed for reading file
6127 ;; names. It knows nothing about files and file names. It knows
6128 ;; nothing about remote file-name syntax. When `completing-read'
6129 ;; reads input, it makes no use of `default-directory'. The
6130 ;; completion candidates are treated as simple strings; they are not
6131 ;; really treated as file names.
6133 ;; Icicles commands that use `completing-read' to read a file name
6134 ;; typically read an absolute name, that is, a name that includes the
6135 ;; directory portion. This means that you can match against any part
6136 ;; of the full name, including any directory components. The
6137 ;; directory portions of the candidate file names need not be the
6138 ;; same - you can thus complete against a set of files in multiple
6141 ;;(@* "Icicles Commands that Read File Names")
6142 ;; ** Icicles Commands that Read File Names **
6144 ;; Icicles commands that use `read-file-name' include all
6145 ;; multi-commands, such as `icicle-find-file', that are defined using
6146 ;; `icicle-define-file-command'. Vanilla Emacs command `find-file'
6147 ;; is another example of a command that uses `read-file-name'.
6149 ;; Icicles commands that use `completing-read' to read file names
6150 ;; include the multi-commands `icicle-find-file-absolute',
6151 ;; `icicle-find-file-in-tags-table', `icicle-recent-file',
6152 ;; `icicle-locate-file', and `icicle-locate-file-no-symlinks'. These
6153 ;; are defined using `icicle-define-command', not
6154 ;; `icicle-define-file-command'.
6156 ;; There are also `-other-window' versions of all of the Icicles
6157 ;; commands that read file names.
6159 ;; The Icicles commands that use `completing-read' to read file names
6160 ;; have an additional feature: you can use a prefix argument to tell
6161 ;; them to combine the last modification date with the file name, as
6162 ;; a multi-completion - see
6163 ;; (@file :file-name "icicles-doc2.el" :to "Multi-Completions").
6164 ;; This means that you can easily look up files whose modification
6165 ;; time or date matches some (regexp) criterion, such as being
6166 ;; sometime in July 2008.
6168 ;; When using a command that reads an absolute file name, remember
6169 ;; that, to save space, you can use `C-x .' to toggle hiding of the
6170 ;; common match portions of the candidates in `*Completions*'. This
6171 ;; portion is often a long directory substring.
6173 ;; Command `icicle-file' is bound, by default, to `C-x C-f' in Icicle
6174 ;; mode, thus taking the place of `find-file'. It combines
6175 ;; `icicle-find-file' and `icicle-find-file-absolute'. With no
6176 ;; prefix argument, it matches relative file names; with a prefix
6177 ;; argument, it matches absolute names (as ordinary strings). With a
6178 ;; negative prefix argument, you can match also the modification
6181 ;; An additional feature of `icicle-find-file-absolute' and
6182 ;; `icicle-find-file-absolute-other-window' is that candidates that
6183 ;; are directory names are highlighted in buffer `*Completions*'
6184 ;; using face `icicle-special-candidate'.
6186 ;; Commands `icicle-find-file-in-tags-table' and
6187 ;; `icicle-find-file-in-tags-table-other-window' let you visit files
6188 ;; that are listed in the current Emacs tags table. You can think of
6189 ;; these potential completion candidates as all of the files in a
6190 ;; project defined by the tags table.
6192 ;; You can use `icicle-recent-file' to open any file that you have
6193 ;; visited recently, perhaps in a previous Emacs session.
6195 ;; You can use `icicle-locate-file' to find a file when you do not
6196 ;; know what directory it is in. It looks throughout a given
6197 ;; directory, including throughout all of its subdirectories.
6198 ;; Command `icicle-locate-file-no-symlinks' is the same, except that
6199 ;; it does not follow symbolic links. Both of these locate commands
6200 ;; respect option `icicle-ignored-directories', which is a list of
6201 ;; directories to ignore - by default, version-control directories.
6203 ;; By default, the target directory for `icicle-locate-file' is the
6204 ;; current directory, but if you supply a non-negative numeric prefix
6205 ;; argument (non-positive means include the date), then you are
6206 ;; prompted for the directory to search. If you use the root of your
6207 ;; file system as the search directory, then the locate-file commands
6208 ;; will match completion candidates anywhere in your file system.
6210 ;; This can be quite useful. It gives you much of the power of the
6211 ;; Unix `find' command just for completing input! And with
6212 ;; incremental completion (see (@> "Icompletion")), you can see what
6213 ;; matches your input as you type.
6215 ;; Obviously, if you use your entire file system as the set of
6216 ;; completion candidates, then gathering and matching such a large
6217 ;; set of file names can take some time. On my hard drive, for
6218 ;; instance, there are 36 GB full of files, and it takes about 40
6219 ;; seconds to gather all of the file names. In spite of this
6220 ;; inconvenience, this functionality can be useful. And of course
6221 ;; searching a shallower directory tree presents less of a
6222 ;; performance penalty - you pay for what you get.
6224 ;; There is a way, however, of having your cake and eating it too.
6225 ;; You can gather all of the file names in your file system once, and
6226 ;; save that list of completion candidates to a cache file on disk,
6228 ;; See (@> "Persistent Sets of Completion Candidates"), for how to do
6231 ;;(@* "Absolute File Names and Different Directories")
6232 ;; ** Absolute File Names and Different Directories **
6234 ;; Since `completing-read' has no understanding of file-name syntax,
6235 ;; including remote file-name syntax, `icicle-find-file-absolute'
6236 ;; (`C-u C-x C-f') and similar commands are similarly ignorant. (You
6237 ;; can nevertheless use `C-.' with these Icicles commands, to toggle
6238 ;; respect of `completion-ignored-extensions'.) In particular, these
6239 ;; commands will not let you complete to a remote file name if the
6240 ;; current directory is local. They also will not let you complete
6241 ;; to a file name in a different local directory.
6243 ;; Because all Icicles commands that read file names use lax
6244 ;; completion, you can nevertheless visit a file in a different
6245 ;; directory (remote or local) from the current one, even though you
6246 ;; cannot complete your input to such a name. That is, you can
6247 ;; always use `RET' with any file name as minibuffer input.
6249 ;; So how can you complete your input to an absolute file-name in a
6250 ;; different directory? By retrieving a saved candidate set that has
6251 ;; such absolute names and then completing against that set. For
6252 ;; example, you can retrieve a set that represents files on a remote
6253 ;; machine and complete to their names even from a local directory.
6254 ;; All that counts for `completing-read' is that your input can match
6255 ;; candidates, where that matching is ordinary (apropos or prefix)
6258 ;; To create such a saved set of names, you can visit the directory
6259 ;; (perhaps remote) that contains the files and then use `C-u C-x
6260 ;; C-f' and `C-}' to save the candidates. You can later retrieve
6261 ;; this saved set for completion, no matter what the current
6262 ;; directory is. As another example, you can use
6263 ;; `icicle-locate-file' in a remote directory to create a saved set
6264 ;; that includes remote files that are all somewhere under that
6265 ;; remote directory.
6267 ;; In addition, you can add more file names to an existing saved set
6268 ;; using `C->', `C-)', `M-mouse-3', `insert', or `M-S-mouse-2' - see
6269 ;; (@> "Sets of Completion Candidates"). The added names can come
6270 ;; from a different directory than files already in the saved set. In
6271 ;; this way, you can build up a saved set that includes files from
6272 ;; any directories, some of which can be local and some remote, some
6273 ;; remote from one host, some remote from another, and so on. You can
6274 ;; create a saved set with any mix of absolute file names from any
6279 ;; * To create and add to a saved set of absolute file names, use a
6280 ;; command that expects absolute file names, and do this from the
6281 ;; directory that contains the files you want to add.
6283 ;; * When you retrieve a saved set of file-name candidates for
6284 ;; completion, use a command that expects the same kind of file
6285 ;; names, relative or absolute, as the saved names. For example,
6286 ;; if you save a set of project files that are spread over
6287 ;; different directories (and hence are absolute), then retrieve
6288 ;; that candidate set using, say, `C-u C-x C-f' (absolute), not
6289 ;; `C-x C-f' (relative).
6291 ;; Finally, although the commands that read absolute file names are
6292 ;; essentially ignorant of directory hierarchies and of file names as
6293 ;; such, so that they treat their candidates only as simple strings,
6294 ;; a few of these commands nevertheless define their domain of
6295 ;; possible file-name candidates relative to some starting directory.
6297 ;; This is the case for `icicle-find-file-absolute' and
6298 ;; `icicle-locate-file' (and their variants). For these commands,
6299 ;; you can use `C-c C-d' (think UNIX command `cd') during completion
6300 ;; to change the current working directory (`default-directory') on
6301 ;; the fly. You are prompted for the directory. The domain of
6302 ;; possible candidates is recomputed relative to the new
6303 ;; `default-directory'.
6305 ;; Use `C-c C-d' this way as many times as you like. You can use
6306 ;; this feature to add file names from different directories to a
6307 ;; saved set of candidates. When the command is finished, the
6308 ;; original `default-directory' is restored.
6312 ;; * (@> "Persistent Sets of Completion Candidates") for information
6313 ;; about saving a set of file names persistently
6314 ;; * (@> "Sets of Completion Candidates") for information about
6315 ;; creating, saving, and retrieving sets of file names
6316 ;; * (@> "Dealing With Large Candidate Sets") for ways to deal with a
6317 ;; large number of candidates
6318 ;; * (@file :file-name "icicles-doc2.el" :to "Multi-Completions")
6319 ;; * (@file :file-name "icicles-doc2.el" :to "Support for Projects")
6320 ;; for more about `icicle-find-file-in-tags-table'
6321 ;; * (@> "Completion On Demand") for information about on-demand
6322 ;; insertion of file names, using completion, from any minibuffer
6325 ;;(@* "Persistent Sets of Completion Candidates")
6327 ;; Persistent Sets of Completion Candidates
6328 ;; ----------------------------------------
6330 ;; Section (@> "Sets of Completion Candidates") describes how you can
6331 ;; save the current set of completion candidates and reuse it later.
6332 ;; This is not a persistent save, however; the candidates are simply
6333 ;; saved in variable `icicle-saved-completion-candidates' for the
6334 ;; duration of your Emacs session (or until you save candidates
6337 ;; You can save the current set of completions (whatever it is)
6338 ;; persistently by supplying a plain prefix argument (`C-u') when you
6339 ;; use `C-M->' (`icicle-candidate-set-save') during completion.
6340 ;; Alternatively, you can use `C-}', bound to
6341 ;; `icicle-candidate-set-save-persistently', which does the same
6342 ;; thing. To retrieve completion candidates that were previously
6343 ;; saved to a cache file, so that they become the current set of
6344 ;; candidates, use either `C-u C-M-<' or `C-{'
6345 ;; (`icicle-candidate-set-retrieve' or
6346 ;; `icicle-candidate-set-retrieve-persistent').
6348 ;; Tip: Suppose you have already saved a set of candidates, but not
6349 ;; persistently, and you now want to write this saved set to a
6350 ;; cache file. Use `C-M-<' followed by `TAB' or `S-TAB',
6351 ;; followed by `C-}'. That is, retrieve the saved candidates
6352 ;; and then save the retrieved candidates persistently. (You
6353 ;; use `TAB' or `S-TAB' because retrieval opens a recursive
6356 ;; Note that using a numeric prefix argument (`C-u' with a number)
6357 ;; with `C-M->' and `C-M-<' saves or retrieves a
6358 ;; completion-candidates set using a variable that you name, not a
6359 ;; cache file. See (@> "Sets of Completion Candidates").
6361 ;;(@* "Saving Candidates in Cache Files")
6362 ;; ** Saving Candidates in Cache Files **
6364 ;; If you have used the Emacs file-name cache (see the Emacs manual,
6365 ;; node "File Name Cache"), then you have already used a cache file
6366 ;; of (file-name) completion candidates. In vanilla Emacs, you use
6367 ;; `C-TAB' during file-name input to complete to a cached file name.
6368 ;; In Icicles, you use `C-{'.
6370 ;; In Icicles, the cached candidates are not limited to file names,
6371 ;; and you can have any number of cache files, to save different sets
6372 ;; of completion candidates. Each cache file saves the set of
6373 ;; candidates that was current when you created (saved) the set.
6375 ;; The fact that a cache file can contain just those candidates that
6376 ;; were current when you saved it is a considerable advantage, when
6377 ;; combined with Icicles features for sculpting the current set of
6378 ;; matching candidates. As far as I know, Icicles is the only
6379 ;; package to offer this feature. You spend a few moments to
6380 ;; fine-tune a set of candidates, using, for example, `M-*', `C-~',
6381 ;; and `delete', and then save it for later use. From then on, you
6382 ;; can match against exactly those candidates anytime you want.
6384 ;; For example, you might have a software project that involves only
6385 ;; certain directories and perhaps only certain kinds of files in
6386 ;; those directories are of interest as completion candidates. Those
6387 ;; directories and files can even be in disparate locations.
6389 ;; Start with command `icicle-locate-file' (or
6390 ;; `icicle-locate-file-no-symlinks'). Then use progressive
6391 ;; completion to match the directories and files you want and chip
6392 ;; away at those you do not want. Once you get just the set you need
6393 ;; for your project, save that set using `C-}'. You can have any
6394 ;; number of saved sets, for different projects or different purposes
6395 ;; in the same project.
6397 ;; You name the sets of saved candidates, and these names are
6398 ;; associated with the cache files in user option
6399 ;; `icicle-saved-completion-sets'. This is an alist of entries, each
6400 ;; of which is of the form (SET-NAME . CACHE-FILE-NAME). You can
6401 ;; customize this option, or set it in your init file (~/.emacs).
6403 ;; You can use command `icicle-add/update-saved-completion-set' to
6404 ;; add a new set to `icicle-saved-completion-sets' or update
6405 ;; (replace) an existing such set. You can use command
6406 ;; `icicle-remove-saved-completion-set' to remove a saved set.
6408 ;; As an alternative to customizing `icicle-saved-completion-sets' or
6409 ;; using command `icicle-add/update-saved-completion-set', you can
6410 ;; simply try to save a set of completion candidates persistently,
6411 ;; using `C-u C-M->' or `C-}'. You are then prompted for the names
6412 ;; of the candidate set and cache file to use, and the names you
6413 ;; enter are automatically entered in option
6414 ;; `icicle-saved-completion-sets'. That option is automatically
6415 ;; saved to your custom file, so the next time you use Emacs you can
6416 ;; retrieve any saved set of candidates that you like.
6418 ;; When you try to retrieve a persistent set of completion
6419 ;; candidates, you are similarly prompted for the candidate-set name
6420 ;; and the cache-file name.
6422 ;; In addition to saving the current set of completion candidates to
6423 ;; a cache file, you can add individual strings as future completion
6424 ;; candidates to any cache file, and you can remove candidates from a
6425 ;; cache file individually. You do this using commands
6426 ;; `icicle-add-entry-to-saved-completion-set' and
6427 ;; `icicle-remove-entry-from-saved-completion-set'.
6429 ;; Adding an individual candidate is similar to using the Emacs
6430 ;; file-name cache commands that add file names to the cache, but it
6431 ;; adds only a single candidate. For file names, adding a directory
6432 ;; name effectively provides completion for all of its files as well,
6433 ;; so there is no need to add each file name as well as the directory
6434 ;; name. Alternatively, you can always use `C-}' to add all file
6435 ;; names that match your current input.
6437 ;;(@* "Filesets and Icicles Saved Completion Sets")
6438 ;; ** Filesets and Icicles Saved Completion Sets **
6440 ;; Starting with release 22, GNU Emacs includes a filesets feature
6441 ;; that lets you create named sets of file names, called "filesets".
6442 ;; It is a powerful feature, letting you define such sets by
6443 ;; intension, using regexp patterns, as well as by extension, listing
6444 ;; file names explicitly. You can easily use a fileset to define a
6445 ;; project of files.
6447 ;; Icicles lets you use an Emacs fileset any time you can use an
6448 ;; Icicles saved completion set, provided that option
6449 ;; `icicle-filesets-as-saved-completion-sets-flag' is non-`nil'.
6451 ;; That is, you can retrieve fileset file names as the current set of
6452 ;; completion candidates or save the current completion candidates to
6453 ;; a fileset. Provided
6454 ;; `icicle-filesets-as-saved-completion-sets-flag' is non-`nil', you
6455 ;; can always choose a fileset as the set to retrieve. To save to a
6456 ;; fileset, use a prefix arg with `C-}' or a zero prefix arg with
6457 ;; `C-M->'. Saving candidates to a fileset gives you an alternative
6458 ;; to customizing option `filesets-data'.
6460 ;; Being able to use an Emacs fileset in place of an Icicles saved
6461 ;; set lets you use filesets in additional ways. For example, it
6462 ;; lets you open Dired on only the files in a fileset, for easy
6463 ;; manipulation of the member files. Conversely, you can save all of
6464 ;; the marked files in a Dired buffer as a fileset. See
6465 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Dired Enhancements").
6467 ;; Beyond letting you use a fileset in place of a persistent Icicles
6468 ;; saved completion set, you can include filesets in such saved
6469 ;; Icicles sets. That is, you can save one or more filesets of any
6470 ;; kind (`:files', `:tree', etc.) in an Icicles persistent saved set
6471 ;; (cache file). When you then retrieve such a saved set, all of the
6472 ;; file names specified by all of the included filesets become
6473 ;; completion candidates.
6475 ;; For example, this could be a saved Icicles set that combines a
6476 ;; `:tree' fileset with an explicit `:files' fileset and with two
6477 ;; additional files:
6479 ;; ((:fileset "set1" (:tree "~/my/dir" "^ici.+\\.el$"))
6480 ;; (:fileset "set2" (:files "dired+.el" "c:/my/dir/buff-menu+.el"))
6481 ;; "c:/some/other/dir/foobar.el"
6482 ;; "c:/somewhere/else/toto.el")
6484 ;; This is a great way to put together a project of files from
6485 ;; different directory trees. And even aside from the use of such a
6486 ;; saved set for completion, this combining of filesets is something
6487 ;; that you cannot do with Emacs filesets alone, as far as I know -
6488 ;; you cannot combine different filesets into super filesets, and a
6489 ;; given fileset can specify files in only one way (`:files',
6490 ;; `:tree', etc.). Icicles gives you a way to associate related
6491 ;; filesets and use them together as a single set.
6493 ;; You can use commands
6494 ;; `icicle-remove-entry-from-saved-completion-set' and
6495 ;; `icicle-add-entry-to-saved-completion-set' to remove a fileset
6496 ;; from an Icicles saved set or add a fileset to a saved set. To
6497 ;; add, use a prefix arg to tell
6498 ;; `icicle-add-entry-to-saved-completion-set' that you are adding a
6499 ;; fileset and not a single completion candidate. To add a single
6500 ;; file (default: the current buffer's file) to a fileset, use
6501 ;; command `icicle-add-file-to-fileset'.
6503 ;; Note: Use the right type of saved candidates (persistent or not)
6504 ;; for a given command. It is the particular command that determines
6505 ;; whether or not a given type of saved candidate is appropriate.
6506 ;; For example, you can save search hits when you use
6507 ;; `icicle-search-file' (same as `icicle-search' with a negative
6508 ;; prefix arg), and those saved search-hit candidates effectively
6509 ;; reference files and positions in those files. And you can later
6510 ;; retrieve and reuse such saved candidates to visit the search
6511 ;; positions. But those candidates are not merely file names, so
6512 ;; they cannot be used with a command such as `find-file' or
6513 ;; `icicle-file' that expects a file name. Conversely, you cannot
6514 ;; use a saved set of file names with a command such as
6515 ;; `icicle-search-file' that expects `icicle-search' candidates.
6517 ;;(@* "Improving Performance with Persistent Sets")
6518 ;; ** Improving Performance with Persistent Sets **
6520 ;; There are two independent reasons that using a persistent set of
6521 ;; file names can improve performance:
6523 ;; * Avoiding remote file-name completion. You can complete your
6524 ;; input against remote file names without using Tramp and thus
6525 ;; without accessing the remote file system. (Once you have chosen
6526 ;; the file you want, visiting it of course makes a remote access.)
6528 ;; * Avoiding generation of a large completion set. Retrieving a
6529 ;; list of file names is much, much faster than generating such a
6530 ;; list. So generate once and retrieve often, from a cache.
6532 ;; These are covered in the next two sections.
6534 ;;(@* "Avoid Remote File-Name Completion")
6535 ;; *** Avoid Remote File-Name Completion ***
6537 ;; When you complete the name of a remote file, Tramp accesses the
6538 ;; remote file system to see which matching files exist. This takes
6539 ;; time. The completion itself is complicated - it involves parsing
6540 ;; the remote file name and calling upon various file handlers. But
6541 ;; the greatest time spent is in accessing the remote machine.
6543 ;; When you retrieve a (persistently) saved set of file names during
6544 ;; completion, you are telling Emacs that these are the candidates
6545 ;; you want to complete against. You are not asking Emacs (Tramp) to
6546 ;; tell you what the possible candidates are; you are telling it.
6547 ;; (Obviously you will want to save the completions in a file on the
6548 ;; local machine, so retrieval itself takes no time.)
6550 ;; After retrieving the saved candidates as the only possible ones,
6551 ;; you might type some input and complete it (`TAB' or `S-TAB') to
6552 ;; narrow your choices. Or you might not bother with completion but
6553 ;; instead pick one of the candidates using `mouse-2' or by cycling
6554 ;; to it and using `RET'.
6556 ;; You can use either relative or absolute file-name completion with
6557 ;; remote file names. Relative name completion as provided by
6558 ;; `read-file-name' (via `C-x C-f', for example) always involves
6559 ;; Tramp (or ange-ftp, prior to Emacs 22). When using relative name
6560 ;; completion, you can save time in these ways:
6562 ;; * Turn off incremental completion (using `C-#'), so that Tramp is
6563 ;; used only when you hit `TAB' or `S-TAB', not with each character
6564 ;; you type or delete!
6566 ;; * Use `mouse-2', or cycle and use `RET', so that you avoid
6567 ;; completion altogether. Tramp is then used only to access the
6570 ;; If you use absolute file-name completion as provided by
6571 ;; `completing-read' (via `C-u C-x C-f', for example), then you need
6572 ;; not worry about turning off incremental completion or avoiding
6573 ;; completion by cycling or using `mouse-2'. This is because
6574 ;; completion is entirely local - `completing-read' has no notion of
6575 ;; files, let alone remote files.
6577 ;; In addition, if you use absolute file-name completion then you
6578 ;; need not bother to type the (long) remote file-name prefix to get
6579 ;; into the right directory for completion. Again, `completing-read'
6580 ;; has no notion of files or directories - it just completes an input
6581 ;; pattern against string candidates. Just type a substring or other
6582 ;; regexp and then hit `S-TAB'.
6584 ;; In general, using absolute file names (`C-u C-x C-f') is the way
6585 ;; to go when dealing with remote files. There is no need to forego
6586 ;; the advantages of Icicles completion. On the other hand, if you
6587 ;; are going to work in a directory on a remote machine for some time
6588 ;; using files other than those in some saved completion set, then
6589 ;; you might want to use relative file names (`C-x C-f').
6591 ;;(@* "Avoid Generating A Large Completion Set")
6592 ;; *** Avoid Generating A Large Completion Set ***
6594 ;; Section (@> "File-Name Input and Locating Files Anywhere") tells
6595 ;; you how you can locate any file in your file system. If you save
6596 ;; the set of all file names persistently, you will increase the
6597 ;; performance of using it - it is much faster to retrieve the list
6598 ;; of all file names than it is to generate it.
6600 ;; With 36 GB of files in my file system, my all-file-system cache
6601 ;; file is 20 MB, and retrieving the file-name completions from it
6602 ;; takes only a few seconds. With this feature, Icicles essentially
6603 ;; gives you the functionality of the Unix `locate' command, but with
6604 ;; the addition of real-time regexp matching. Here is all you do:
6606 ;; M-x icicle-locate-file RET
6607 ;; C-# ; Once or twice: turn off incremental completion.
6608 ;; C-{ ; Retrieve all file names from your cache file.
6609 ;; ; You are prompted for the set name and file name.
6610 ;; foo.*bar ; Regexp to match names with `foo' followed by `bar'.
6611 ;; S-TAB ; Update `*Completions*' display (because of `C-#').
6613 ;; Of course, once you have retrieved a set of candidates from your
6614 ;; cache file, you can access them again without re-reading the file.
6615 ;; When they are retrieved from your cache they are saved in variable
6616 ;; `icicle-saved-completion-candidates', so the next time you want to
6617 ;; use them, just retrieve them from this variable with `C-M-<'.
6621 ;; * (@> "File-Name Input and Locating Files Anywhere") for
6622 ;; information about relative vs absolute file names and about
6623 ;; finding files located anywhere in your file system
6625 ;; * (@> "Icompletion") for information about `C-#' (toggle
6626 ;; incremental completion)
6628 ;; * (@> "Sets of Completion Candidates") for information about
6629 ;; `C-M->' (save current candidates)
6631 ;; * (@> "Dealing With Large Candidate Sets")
6633 ;; * (@file :file-name "icicles-doc2.el" :to "Icicles Bookmark Enhancements")
6634 ;; for information about using autofile bookmarks, which are
6635 ;; another form of persistent file names
6637 ;;(@* "Dealing With Large Candidate Sets")
6639 ;; Dealing With Large Candidate Sets
6640 ;; ---------------------------------
6642 ;; One of the advantages Icicles provides is the ability to deal with
6643 ;; large sets of completion candidates with ease. There are other
6644 ;; libraries that also let you cycle among various choices of
6645 ;; different kinds (buffers, files, and so on), but cycling quickly
6646 ;; loses its effectiveness as the number of candidates increases.
6648 ;; Icicles apropos matching lets you work with a large initial set of
6649 ;; candidates by filtering them, quickly reducing the number
6650 ;; candidates to cycle through. Filtering by a prefix only (vanilla
6651 ;; Emacs) is not very potent. Until you get used to Icicles, you
6652 ;; will be surprised at your ability to manipulate even humongous
6655 ;; Nevertheless, there can be times when a candidate set is so large
6656 ;; that you need to use a few tricks to deal with it efficiently.
6657 ;; There are two main things that take time when dealing with a large
6658 ;; set: computing the set and displaying it (with highlighting) in
6659 ;; buffer `*Completions*'. In particular, incremental completion
6660 ;; display is costly because it does both of these, recompute the set
6661 ;; and redisplay it, each time you type or delete a character in the
6664 ;; Here are some tips to improve performance with a large set of
6667 ;; * Turn off incremental completion display in buffer
6668 ;; `*Completions*'. You can do this on the fly at any time by
6669 ;; using `C-#' in the minibuffer - use `C-#' again to turn it back
6670 ;; on. See (@> "Icompletion").
6672 ;; * Compute a large candidate set only once, cache the result, and
6673 ;; reuse it later by reading the cache instead of recomputing.
6674 ;; This is useful, for instance, for the candidate set of all files
6675 ;; on your file system. You can cache a set of candidates in
6676 ;; either a variable (quickest, but not persistent) or a disk file
6677 ;; (slower, persistent).
6678 ;; See (@> "Persistent Sets of Completion Candidates").
6680 ;; * Compute a large candidate set (and perhaps cache it or filter
6681 ;; it) without displaying it in `*Completions*', by using `C-M-TAB'
6682 ;; or `C-M-S-TAB' instead of `TAB' or `S-TAB', respectively. These
6683 ;; are bound to commands `icicle-prefix-complete-no-display' and
6684 ;; `icicle-apropos-complete-no-display'. For example, when
6685 ;; initially computing the set of all files on your file system for
6686 ;; `C-u M-x icicle-locate-file', use `C-M-S-TAB' to compute the
6687 ;; set, then use `C-}' to save it to a cache file - you need never
6690 ;; (The documentation refers to the keys that do this as
6691 ;; `C-M-S-TAB' and `C-M-TAB'. Actually, this is only by default.
6692 ;; You can customize this, using options
6693 ;; `icicle-apropos-complete-no-display-keys' and
6694 ;; `icicle-prefix-complete-no-display-keys'.)
6696 ;;(@* "History Enhancements")
6698 ;; History Enhancements
6699 ;; --------------------
6701 ;; This section is about accessing and reusing previous input that
6702 ;; you have typed in the minibuffer.
6704 ;;(@* "What Input, What History?")
6705 ;; ** What Input, What History? **
6707 ;; First, what is meant by "input" and "input history"? In vanilla
6708 ;; Emacs and in this doc, "minibuffer history" and "input history"
6709 ;; generally refer to input that you have typed (or cycled or
6710 ;; completed) in the minibuffer and then entered using `RET' (or
6711 ;; `S-RET'). Emacs provides different history lists for this,
6712 ;; depending on the kind of input. The most general such list is the
6713 ;; value of variable `minibuffer-history'.
6715 ;; But what about input that you type in the minibuffer (e.g. during
6716 ;; completion) but that you do not enter with `RET'? That is not
6717 ;; recorded in any standard history list, so you cannot recall it
6718 ;; using `M-p' and `M-n'.
6720 ;; The Icicles doc speaks ambiguously of "minibuffer input". This
6721 ;; always refers to something that you type in the minibuffer, but
6722 ;; sometimes it means input that you enter with `RET' and sometimes
6723 ;; it does not. The context and the use of phrases such as "entered"
6724 ;; and "entered with `RET'" should make clear what is meant. Input
6725 ;; that you type during completion but that you do not necessarily
6726 ;; enter is sometimes referred to in the Icicles doc as "completion
6729 ;; Because completion is so important to Icicles, because cycling
6730 ;; replaces the input you type in the minibuffer, and because you
6731 ;; sometimes need to retrieve such typed input that was never
6732 ;; entered, Icicles also records this input. You can retrieve it
6733 ;; during completion using `C-l' (`icicle-retrieve-previous-input')
6734 ;; and `C-S-l', that is, `C-L', (`icicle-retrieve-next-input'). Use
6735 ;; these commands to cycle among your past completion inputs
6736 ;; (backward and forward, respectively).
6738 ;; User option `icicle-completion-history-max-length' limits the
6739 ;; number of completion inputs to save.
6741 ;; If you customize user option `icicle-C-l-uses-completion-flag' to
6742 ;; non-`nil', then, instead of cycling, `C-l' lets you use Icicles
6743 ;; completion to retrieve a past completion input (`C-L' does the
6744 ;; same thing). Using completion to retrieve a past input does not
6745 ;; also choose that input as the candidate for the main completion;
6746 ;; it just replaces your current minibuffer input with it. Because
6747 ;; `C-l' completion uses a recursive minibuffer, you can also use
6748 ;; `C-g' to cancel this completion and return to the main completion.
6750 ;; You can temporarily reverse the effect of
6751 ;; `icicle-C-l-uses-completion-flag' by using a prefix argument
6752 ;; (`C-u') with `C-l'. Thus, `C-u C-l' uses completion if
6753 ;; `icicle-C-l-uses-completion-flag' is `nil' and cycles if it is
6756 ;; The other sections here describe Icicles enhancements for
6757 ;; minibuffer histories. They are thus concerned only with inputs
6758 ;; that you enter, not with completion inputs that are not entered.
6760 ;;(@* "Overview of Minibuffer History Enhancements")
6761 ;; ** Overview of Minibuffer History Enhancements **
6763 ;; Icicles enhances the minibuffer history in these independent ways:
6765 ;; 1. Commands invoked using a menu-bar menu are included in the
6766 ;; command history for `M-x'. This helps you quickly find again
6767 ;; and reuse a (possibly deep) menu item. It lets you use
6768 ;; completion to access such commands. And it helps you learn the
6769 ;; commands that correspond to menu items that you use, thus
6770 ;; providing a missing bridge between menu use and minibuffer use.
6772 ;; If you do not want to include menu-item commands in the command
6773 ;; history, then set option `icicle-menu-items-to-history-flag' to
6776 ;; Note: Non-`nil' `icicle-menu-items-to-history-flag' simply
6777 ;; makes Emacs handle menu items that you choose the same way that
6778 ;; it handles commands that you enter using `RET'. It does not
6779 ;; add such menu items to your completion history, which you
6780 ;; access using `C-l' (see (@> "What Input, What History?"),
6783 ;; 2. Command `icicle-insert-history-element' (bound to `M-o' in the
6784 ;; minibuffer) lets you use (lax) completion to insert a history
6785 ;; element in the minibuffer.
6787 ;; 3. Candidates displayed in `*Completions*' are highlighted using
6788 ;; face `icicle-historical-candidate' (blue foreground, by
6789 ;; default), when they have been used previously, so you can more
6790 ;; easily recognize them. This highlighting is controlled by
6791 ;; option `icicle-highlight-historical-candidates-flag'. You can
6792 ;; toggle this from the minibuffer at any time using `C-pause'.
6794 ;; 4. Command `icicle-toggle-alternative-sorting', (`C-M-,' in the
6795 ;; minibuffer) re-sorts completion candidates, placing previously
6796 ;; used candidates first. This is a toggle: repeat it to return
6797 ;; to the original order.
6799 ;; 5. Command `icicle-keep-only-past-inputs' (`M-pause' in the
6800 ;; minibuffer) restricts the current set of completion candidates
6801 ;; to those that you have used previously. In other words, it
6802 ;; keeps only those candidates that are highlighted in blue. To
6803 ;; use `M-pause', you must first have used `TAB' or `S-TAB' to
6804 ;; establish an explicit candidate set. If you use `C-u M-pause',
6805 ;; then the previously used candidates are ordered
6806 ;; chronologically, most recent first. Without `C-u', the normal
6807 ;; sort order is used (`icicle-sort-comparer').
6809 ;; 6. Command `icicle-history' (`M-h' in the minibuffer) matches the
6810 ;; current input against the minibuffer history directly. It can
6811 ;; be used during completion.
6813 ;; 7. Command `icicle-other-history' (`C-M-pause' in the minibuffer)
6814 ;; lets you use a different history for the current completion.
6815 ;; You can choose the history using completion.
6817 ;; 8. Commands `icicle-clear-history' and
6818 ;; `icicle-clear-current-history' (`M-i' in the minibuffer)
6819 ;; provide a general way to clean up histories.
6821 ;; 9. When you cycle among previously entered inputs using `M-p' and
6822 ;; `M-n', you can use `M-k' (command
6823 ;; `icicle-erase-minibuffer-or-history-element') to delete the
6824 ;; current occurrence from the history list. This is a quick and
6825 ;; handy way to clean up list entries that you are no longer
6826 ;; interested in. Only the occurrence that you have cycled to is
6827 ;; deleted; if there are identical entries elsewhere in the
6828 ;; history, they remain.
6830 ;; Some of these enhancements are described below in more detail.
6831 ;; Each of 1-7 lets you see the complete list of previous inputs that
6832 ;; match your current input. In vanilla Emacs, the history lists are
6833 ;; never shown as such; you can access previous inputs only one at a
6834 ;; time, in order (with `M-p'). In vanilla Emacs, you can use a
6835 ;; regexp to search the history list (via `M-r'), but the regexp
6836 ;; matching is not dynamic, and the first match found is the (only)
6839 ;; Displaying previous inputs that match the current input sounds
6840 ;; like a minor advantage, but it is actually quite helpful in
6841 ;; practice. Among other things, it means that you can work with
6842 ;; long history lists in a practical way.
6844 ;;(@* "Using Completion to Insert Previous Inputs: `M-o'")
6845 ;; ** Using Completion to Insert Previous Inputs: `M-o' **
6847 ;; Unlike the other minibuffer history enhancements, described below,
6848 ;; which are available only during minibuffer completion, you can use
6849 ;; `M-o' (`icicle-insert-history-element') anytime you are asked for
6850 ;; minibuffer input. It provides a recursive minibuffer in which you
6851 ;; can match a previous input using completion. After you hit `RET'
6852 ;; to accept your choice, it is inserted in the minibuffer just as if
6853 ;; you had typed it. This is a form of on-demand completion
6854 ;; (see (@> "Completion On Demand"), and as such is always available.
6856 ;; This has the advantage over cycling with `M-n' or `M-p' and
6857 ;; searching with `M-s' or `M-r', that you can use Icicles completion
6858 ;; and cycling to quickly access a previous input, no matter how long
6859 ;; ago you entered it.
6861 ;; When completion is available for reading input, if you use `M-o'
6862 ;; to choose a previously entered input, this just inserts that input
6863 ;; in the minibuffer. What is in the minibuffer after you use `M-o'
6864 ;; is not automatically chosen for the main completion - you can edit
6865 ;; the minibuffer contents before entering it with `RET'. You can
6866 ;; also use `C-g' during the `M-o' completion to cancel it and return
6867 ;; to the main completion.
6869 ;;(@* "Putting Previous Candidates First: `C-M-,'")
6870 ;; ** Putting Previous Candidates First: `C-M-,' **
6872 ;; At any time, two of the Icicles sort orders are immediately
6873 ;; available. These are the values of user options
6874 ;; `icicle-sort-comparer' and `icicle-alternative-sort-comparer'. By
6875 ;; default, the former usually sorts alphabetically, and the latter
6876 ;; puts all previously used inputs first, before the candidates you
6877 ;; have not yet used. Each of these groups, used and unused
6878 ;; candidates, is then sorted alphabetically, separately. So, with
6879 ;; the default alternative sort, you can see all matching candidates
6880 ;; (used and unused), but you privilege those used previously - they
6881 ;; are the first listed in `*Completions*' and the first available
6884 ;; If you prefer, by customizing these user options, you can use
6885 ;; `icicle-historical-alphabetic-p' as the main sort function (option
6886 ;; `icicle-sort-comparer') and some other sort function
6887 ;; (e.g. `icicle-case-string-less-p') as the alternative sort
6890 ;; You can toggle at any time between normal sorting and alternative
6891 ;; sorting, using command `icicle-toggle-alternative-sorting'.
6892 ;; During completion, this is bound to `C-M-,'. Together with
6893 ;; toggling between normal sorting and not sorting at all, which is a
6894 ;; sort-order choice available through `C-,', this gives you quite a
6895 ;; lot of flexibility.
6897 ;;(@* "Matching Only Historical Candidates: `M-h' and `M-pause'")
6898 ;; ** Matching Only Historical Candidates: `M-h' and `M-pause' **
6900 ;; Both `M-h' (`icicle-history') and `M-pause'
6901 ;; (`icicle-keep-only-past-inputs') can be used toward the same end.
6902 ;; They both work for all input types. They both use the appropriate
6903 ;; history list for the current command. They both provide
6904 ;; completion and cycling for the minibuffer history. Use them as
6905 ;; another way to search through a history list or complete to one of
6908 ;; For example, If you use `C-x C-f' to find a file, and then use
6909 ;; `M-h' or `M-pause', the completion candidates will be the names of
6910 ;; files that you have previously accessed (file names you have input
6911 ;; in the minibuffer), and which match the current minibuffer input.
6913 ;; `M-h' lets you complete your input against the minibuffer input
6914 ;; history. `M-pause' lets you restrict the current explicit set of
6915 ;; completion candidates to those that are also in the minibuffer
6918 ;; They provide similar functionality in different ways. The
6919 ;; difference is that `M-pause' takes the current set of matching
6920 ;; candidates into account. It is a completion-candidates set
6921 ;; operation, similar to those described in section
6922 ;; (@> "Sets of Completion Candidates").
6924 ;; This means, in particular, that with `M-pause' you can first
6925 ;; perform set operations on the set of candidates, and then use that
6926 ;; result to restrict the history search. For example, you can first
6927 ;; complement the candidate set using `C-~', then use `M-pause' to
6928 ;; restrict those candidates to matches in the history list. In this
6929 ;; way, you avoid including matches from the original match set when
6930 ;; searching the history.
6932 ;; Example: You are in a directory with lots of files that have the
6933 ;; prefix `foo' and lots of C-language source files. You happen to
6934 ;; be interested in another file, however. One way to get to that
6935 ;; file is to use Dired's ability to mark files by matching a regexp
6936 ;; and then use Dired's ability to omit the marked files from view.
6937 ;; You can scan through those that remain, and pick the one you want.
6938 ;; However, it turns out that even then there are many files to scan.
6939 ;; You accessed the one you want now just the other day, but the file
6940 ;; date is unfortunately not significant.
6942 ;; In Icicles, you use regexp matching and take the set complement of
6943 ;; the hits, just like in Dired: `C-x C-f foo.*\.c$' defines the
6944 ;; candidate set as all files whose names start with `foo' and have
6945 ;; extension `c'. `C-~' then defines the candidate set as all files
6946 ;; whose names are not like that. Finally, you use `M-pause' to
6947 ;; restrict the file-name candidates to names that you have used
6948 ;; before. You've accessed many, many files recently, so just
6949 ;; cycling through the history with `M-p' would be tedious. You
6950 ;; could match a regexp against the file history, but how can you
6951 ;; come up with a regexp that finds anti-matches?
6953 ;; A consequence of this difference between `M-h' and `M-pause' is
6954 ;; that using `TAB' or `S-TAB' after `M-pause' abandons use of the
6955 ;; minibuffer history and starts a new set of completion candidates.
6956 ;; It simply completes the current input in the context of the
6957 ;; current command; `TAB' and `S-TAB' have nothing to do with the
6958 ;; minibuffer history in this case. Using `TAB' or `S-TAB' after
6959 ;; `M-h', however, re-completes your input against the current
6962 ;; Another consequence is that you can use `down' or `C-down' on the
6963 ;; candidates displayed by `M-h', but not on those displayed by
6964 ;; `M-pause'. For example, to cycle through the doc for each
6965 ;; variable that starts with `icicle-' which you have previously
6966 ;; input, you can use `C-h v icicle- M-h', then repeatedly use
6969 ;; Also, file-name and directory-name completion works differently in
6970 ;; these two commands. By default, the current directory is (as
6971 ;; always) inserted into the minibuffer by commands such as
6972 ;; `find-file', so either `M-h' or `M-pause' after `C-x C-f' will
6973 ;; match previously input file names from the current directory.
6975 ;; However, in the case of `M-h', the entire minibuffer input is
6976 ;; matched against the history list, which is a list of absolute file
6977 ;; names. `M-pause' works only with the current candidate set,
6978 ;; which, if you have already used `TAB' or `S-TAB' in the current
6979 ;; directory, is a set of relative file names in that directory.
6981 ;; This difference has a consequence for apropos (regexp) completion
6982 ;; with `M-h'. It means that to match a file name using a substring
6983 ;; you must, in the minibuffer, either not specify a directory (erase
6984 ;; it) or explicitly use `.*' before the file-name substring.
6986 ;; For example, with `M-h', `/foo/bar/lph' will not apropos-match the
6987 ;; previously input file name `/foo/bar/alphabet-soup.el'; you should
6988 ;; use either `/foo/bar/.*lph' or `lph' (no directory).
6990 ;; In the case of `M-pause', however, the input is matched against
6991 ;; the history list as restricted by the existing completion list.
6992 ;; And, since apropos file-name completion uses only the relative
6993 ;; file name, without the directory name, as a regexp, the candidate
6994 ;; list that is restricted has already matched the input regexp. The
6995 ;; action of `M-pause' is simply to filter the list of candidates,
6996 ;; keeping those that are in the history list. This means that, with
6997 ;; `M-pause', the input `/foo/bar/lph' will match against the
6998 ;; previously input file name `/foo/bar/alphabet-soup.el'.
7000 ;; Note that neither `M-h' nor `M-pause' uses a recursive minibuffer;
7001 ;; they each simply co-opt the current completion, changing it to
7002 ;; completion against the history. This means that whatever
7003 ;; completion mode (prefix or apropos) was in effect before you use
7004 ;; `M-h' or `M-pause' remains in effect for the history completion as
7007 ;; If this all sounds confusing, just give it a try; it is much
7008 ;; harder to describe than it is to experience.
7010 ;;(@* "Using Other Histories; Commands Any Which Way")
7011 ;; ** Using Other Histories; Commands Any Which Way **
7013 ;; This section describes how to complete your input against a
7014 ;; history other than the default history provided for the current
7015 ;; command. A special case of this, starting with Emacs 23, is
7016 ;; completing a command, abbrev, or keyboard macro name against all
7017 ;; such that were previously executed in any interactive way. This
7018 ;; includes commands invoked using a menu.
7020 ;;(@* "Completing Against All Interactive Commands")
7021 ;; *** Completing Against All Interactive Commands ***
7023 ;; When you execute a command using `M-x', it is added to the history
7024 ;; `extended-command-history'. Likewise, when you execute a command
7025 ;; or abbrev using `icicle-command-abbrev-command'. And when you
7026 ;; execute a keyboard macro using `C-x M-e'
7027 ;; (`icicle-execute-named-keyboard-macro'), it is added to history
7028 ;; `icicle-kmacro-history'.
7030 ;; However, when you execute a command, abbrev, or keyboard macro in
7031 ;; other ways than these, it is not added to such a history. For
7032 ;; example, if you choose a menu item, the associated command is not
7033 ;; added to any of these histories. Thus, although `M-o' lets you
7034 ;; complete against previously used commands, this does not include
7035 ;; commands that were called via a menu item.
7037 ;; To remedy this, starting with Emacs 23 Icicles can optionally add
7038 ;; all commands that are called using `call-interactively' to the
7039 ;; larger command history `icicle-interactive-history'. This
7040 ;; includes commands on menus. To enable this feature, you must
7041 ;; customize option `icicle-populate-interactive-history-flag', to
7042 ;; make it non-`nil'. Thereafter, when you enter Icicle mode, all
7043 ;; interactive use of commands records them on this special history.
7045 ;; During completion, you can then use `C-M-pause'
7046 ;; (`icicle-other-history') to complete against this extended set of
7047 ;; previously used commands. For example, if you use menu item `Open
7048 ;; File', then the corresponding command, `menu-find-file-existing',
7049 ;; becomes available as a completion candidate. (Recall too that the
7050 ;; command associated with a given menu item is shown in the
7051 ;; `*Completions*' mode line whenever you cycle to it.)
7053 ;; Be aware that use of this feature can slow Emacs down, and the
7054 ;; history list can become quite large.
7056 ;;(@* "Using an Alternative History")
7057 ;; *** Using an Alternative History ***
7059 ;; When you are completing something other than a command, abbrev, or
7060 ;; keyboard macro (or even when you complete one of those, if you use
7061 ;; a prefix argument), `C-M-pause' prompts you for an alternative
7062 ;; history to use - any history you like. You can choose the history
7063 ;; using completion. This does not automatically complete your
7064 ;; current input against the history you choose; it simply changes
7065 ;; the current history for the duration of the current minibuffer
7066 ;; completion. (You can use `M-h', as usual, if you want to complete
7067 ;; against the chosen history.)
7069 ;;(@* "Cleaning Up History Lists")
7070 ;; ** Cleaning Up History Lists **
7072 ;; Besides the use of `M-k' during history cycling (`M-p', `M-n') to
7073 ;; remove individual input occurrences from the current history list,
7074 ;; you can use commands `icicle-clear-history' and
7075 ;; `icicle-clear-current-history' to clean minibuffer histories
7076 ;; entirely of selected entries. Command
7077 ;; `icicle-clear-current-history' is bound to `M-i' in the
7078 ;; minibuffer. It is `icicle-clear-history' specialized to work on
7079 ;; just the current history list.
7081 ;; These commands prompt you for a history entry to delete from a
7082 ;; history list. These are multi-commands, so you can delete
7083 ;; multiple entries. For each entry you choose, all of its
7084 ;; occurrences are deleted from the history.
7086 ;; Command `icicle-clear-history' first prompts you for a history
7087 ;; list to act on. This too is multi-command input, so you can use
7088 ;; `icicle-clear-history' to remove entries from multiple histories.
7090 ;; If you use a prefix argument with these commands, then the
7091 ;; histories are emptied entirely (upon confirmation). Thus, for
7092 ;; instance, you can use `C-u M-i' at any time during minibuffer
7093 ;; input to completely empty the current history list.
7095 ;; See Also: (@> "More about Multi-Commands") for information about
7096 ;; using `S-delete' to delete objects associated with completion
7099 ;;(@* "Isearch Enhancements")
7101 ;; Isearch Enhancements
7102 ;; --------------------
7104 ;; Icicles provides two different enhancements for searching:
7106 ;; - Icicles search: Top-level Icicles commands that provide an
7107 ;; entirely new and different way for you to search.
7108 ;; This is described in section
7109 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview").
7111 ;; - Extensions to standard Emacs incremental search, Isearch.
7112 ;; These are described in this section.
7114 ;; * Search string completion against previous search strings.
7115 ;; * Occur mode interface for Isearch hits.
7116 ;; * Icicles search (`icicle-search') interface, reusing the
7117 ;; Isearch search string (by default).
7121 ;; * (@file :file-name "icicles-doc2.el" :to "Support for Projects")
7122 ;; for information about using `grep' to search all of the files in
7125 ;;(@* "Isearch Completion Against the Search History")
7126 ;; ** Isearch Completion Against the Search History **
7128 ;; When you search incrementally (`C-s'), Emacs lets you use `M-TAB'
7129 ;; (aka `C-M-i', aka `ESC-TAB') to complete your input to a string
7130 ;; that you have sought previously, that is, a string in the current
7131 ;; search history (`search-ring' or `regexp-search-ring'). In Icicle
7132 ;; mode, this feature is enhanced so that you can use all of the
7133 ;; completion enhancements provided by Icicles: `M-TAB' is bound to
7134 ;; `icicle-isearch-complete' during Isearch.
7136 ;; Some operating systems grab `M-TAB' for their own use, making it
7137 ;; unavailable for Emacs. They normally do not grab `ESC TAB', which
7138 ;; in Emacs is typically the same ase `M-TAB'. For this reason,
7139 ;; Icicles also binds `icicle-isearch-complete' to both `ESC TAB' and
7140 ;; `C-M-TAB'. (Note: For MS Windows, you can use
7141 ;; (w32-register-hot-key [M-tab]) to allow Emacs to use `M-TAB'.)
7143 ;; Icicles users are in the habit of using `M-o' to complete the
7144 ;; current minibuffer input against previously entered inputs.
7145 ;; Because of the similarity, you can likewise use `M-o' during
7146 ;; Isearch to complete the current search string: `M-o' is equivalent
7149 ;; The keys bound by default to `icicle-isearch-complete' in
7150 ;; `isearch-mode-map' are thus `M-TAB', `ESC TAB', `C-M-TAB', and
7151 ;; `M-o'. But you can change the keys to use for this by customizing
7152 ;; option `icicle-isearch-complete-keys'.
7154 ;; When you use `M-o' (or `M-TAB') while searching, Isearch exits
7155 ;; momentarily, giving way to Icicles completion in the minibuffer
7156 ;; (Isearch actually uses the echo area, not the minibuffer). You
7157 ;; can then use either `S-TAB' or `TAB' to complete your search
7158 ;; string. After you finish completing (e.g. by hitting `RET'),
7159 ;; Isearch resumes with the new, completed search string. It's
7160 ;; pretty seamless, and easier to try than to describe.
7162 ;; Reminder: Using `S-TAB' vs `TAB' for regexp vs non-regexp
7163 ;; completion against previous search strings has nothing to do with
7164 ;; regexp vs non-regexp searching. You can of course use either kind
7165 ;; of searching before or after having used either kind of
7166 ;; completion. Isearch uses different search rings for regexp and
7167 ;; non-regexp searching. The kind of search in progress (regexp or
7168 ;; not) at the moment you ask Isearch for completion determines which
7169 ;; search ring provides the candidates for completion.
7171 ;;(@* "Launch Occur using the Isearch Search String")
7172 ;; ** Launch Occur using the Isearch Search String **
7174 ;; If you use library `color-moccur.el' or library
7175 ;; `occur-schroeder.el', then `C-o' is bound during Isearch to
7176 ;; `isearch-moccur', which provides an Occur buffer interface for
7177 ;; search hits. This has nothing per se to do with Icicles, but you
7178 ;; might find it useful. (Library `color-moccur.el' itself binds
7179 ;; `M-o' for this, but `M-o' is used in Icicles for search-string
7182 ;;(@* "Launch Icicles Search using the Isearch Search String")
7183 ;; ** Launch Icicles Search using the Isearch Search String **
7185 ;; Icicles search is described in section
7186 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview").
7188 ;; You can start Icicles search from Isearch: Hit `S-TAB' to choose
7189 ;; the Icicles search initial regexp - the default value is the
7190 ;; current Isearch search string, but you can edit that. Completion
7191 ;; is available for your input - completion against your previous
7192 ;; Isearch regexp search strings.
7194 ;; For example, use `C-s C-w C-w S-TAB' to pick up the next two words
7195 ;; at the cursor, then type `.*' before and after them and hit `RET'.
7196 ;; That puts you in Icicles search with the completion candidates
7197 ;; being all of the lines in the buffer that contain that two-word
7198 ;; phrase. Type some more text to narrow the candidate lines to
7199 ;; those that match what you type. Then use `C-next' to visit search
7202 ;; With Emacs 22 and later, and provided option
7203 ;; `isearch-allow-scrolling' (a misnomer) is non-`nil', you can use a
7204 ;; prefix argument with `S-TAB' to change the behavior. You still
7205 ;; choose an Isearch search string using completion. But in this
7206 ;; case the string does not define the Icicles search contexts.
7207 ;; Instead, you are prompted for a search-context regexp to do that.
7208 ;; The Isearch string is copied to the `kill-ring', so you can yank
7209 ;; it into your minibuffer input anytime, to search for it within
7210 ;; each of the search contexts.
7212 ;; The key to initiate Icicles search from Isearch is `S-TAB' only by
7213 ;; default. You can change this key by customizing option
7214 ;; `icicle-search-from-isearch-keys'.
7216 ;; The Icicles doc is continued in file `icicles-doc2.el'.
7218 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
7220 ;; This program is free software; you can redistribute it and/or
7221 ;; modify it under the terms of the GNU General Public License as
7222 ;; published by the Free Software Foundation; either version 2, or (at
7223 ;; your option) any later version.
7225 ;; This program is distributed in the hope that it will be useful,
7226 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
7227 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
7228 ;; GNU General Public License for more details.
7230 ;; You should have received a copy of the GNU General Public License
7231 ;; along with this program; see the file COPYING. If not, write to
7232 ;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth
7233 ;; Floor, Boston, MA 02110-1301, USA.
7235 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
7239 ;; You need not load this file. It contains only documentation.
7241 (provide 'icicles-doc1)
7243 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
7244 ;;; icicles-doc1.el ends here