1 ;;; icicles-doc2.el --- Minibuffer input completion and cycling.
3 ;; Filename: icicles-doc2.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:54:56 2011 (-0700)
13 ;; URL: http://www.emacswiki.org/cgi-bin/wiki/icicles-doc2.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 2.
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 ;; This file continues the Icicles documentation, which starts in
37 ;; file `icicles-doc1.el'.
44 ;; If you have library `linkd.el' and Emacs 22 or later, load
45 ;; `linkd.el' and turn on `linkd-mode' now. It lets you easily
46 ;; navigate around the sections of this doc. Linkd mode will
47 ;; highlight this Index and render it more readable. Likewise, for
48 ;; the cross-references and section headings throughout this file.
49 ;; You can get `linkd.el' here:
50 ;; http://www.emacswiki.org/cgi-bin/wiki/linkd.el.
52 ;; (@file :file-name "icicles-doc1.el" :to "Documentation in File `icicles-doc1.el'")
53 ;; -----------------------------------------------------------
55 ;; (@file :file-name "icicles-doc1.el" :to "Nutshell View of Icicles")
56 ;; (@file :file-name "icicles-doc1.el" :to "README for Non-Readers")
57 ;; (@file :file-name "icicles-doc1.el" :to "Toggle Options on the Fly")
58 ;; (@file :file-name "icicles-doc1.el" :to "Cycle Completion Candidates")
59 ;; (@file :file-name "icicles-doc1.el" :to "Display Completion Candidates")
60 ;; (@file :file-name "icicles-doc1.el" :to "Prefix Completion and Apropos Completion")
61 ;; (@file :file-name "icicles-doc1.el" :to "Chains of Simple Match Patterns - Progressive Completion")
62 ;; (@file :file-name "icicles-doc1.el" :to "Chip Away the Non-Elephant")
63 ;; (@file :file-name "icicles-doc1.el" :to "Choose Before You Act")
64 ;; (@file :file-name "icicles-doc1.el" :to "Help on Completion Candidates")
65 ;; (@file :file-name "icicles-doc1.el" :to "Perform Multiple Operations in One Command")
66 ;; (@file :file-name "icicles-doc1.el" :to "Perform Alternative Operations on the Fly")
67 ;; (@file :file-name "icicles-doc1.el" :to "Completion Status Indicators")
68 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Search")
69 ;; (@file :file-name "icicles-doc1.el" :to "Complete Key Sequences Too")
70 ;; (@file :file-name "icicles-doc1.el" :to "Available for Almost Any Input")
71 ;; (@file :file-name "icicles-doc1.el" :to "Component Icicles Libraries")
72 ;; (@file :file-name "icicles-doc1.el" :to "If You Are an Emacs-Lisp Programmer")
74 ;; (@file :file-name "icicles-doc1.el" :to "Inserting Text Found Near the Cursor")
75 ;; (@file :file-name "icicles-doc1.el" :to "FFAP: Find File At Point")
76 ;; (@file :file-name "icicles-doc1.el" :to "Proxy Candidates, `M-.'")
77 ;; (@file :file-name "icicles-doc1.el" :to "Repeat `M-.' To Grab More or Different")
78 ;; (@file :file-name "icicles-doc1.el" :to "Resolve File Names")
79 ;; (@file :file-name "icicles-doc1.el" :to "Background on Vanilla Emacs Input Completion")
80 ;; (@file :file-name "icicles-doc1.el" :to "Cycling Completions")
81 ;; (@file :file-name "icicles-doc1.el" :to "Traversing Minibuffer Histories")
82 ;; (@file :file-name "icicles-doc1.el" :to "Apropos Completions")
83 ;; (@file :file-name "icicles-doc1.el" :to "Expanded-Common-Match Completion")
84 ;; (@file :file-name "icicles-doc1.el" :to "Progressive Completion")
85 ;; (@file :file-name "icicles-doc1.el" :to "`M-*': Matching Additional Regexps")
86 ;; (@file :file-name "icicles-doc1.el" :to "Successive Approximation...")
87 ;; (@file :file-name "icicles-doc1.el" :to "`M-&': Satisfying Additional Predicates")
89 ;; (@file :file-name "icicles-doc1.el" :to "Regressive Completion")
90 ;; (@file :file-name "icicles-doc1.el" :to "Completion On Demand")
91 ;; (@file :file-name "icicles-doc1.el" :to "Moving Between the Minibuffer and Other Buffers")
92 ;; (@file :file-name "icicles-doc1.el" :to "Inserting a Regexp from a Variable or Register")
93 ;; (@file :file-name "icicles-doc1.el" :to "Special Characters in Input Patterns")
94 ;; (@file :file-name "icicles-doc1.el" :to "Alternative Libraries: Other Methods of Choosing Default Values")
95 ;; (@file :file-name "icicles-doc1.el" :to "Exiting the Minibuffer Without Confirmation")
96 ;; (@file :file-name "icicles-doc1.el" :to "*Completions* Display")
97 ;; (@file :file-name "icicles-doc1.el" :to "Icompletion")
98 ;; (@file :file-name "icicles-doc1.el" :to "icomplete+.el Displays the Number of Other Prefix Candidates")
99 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Highlights the Input that Won't Complete")
100 ;; (@file :file-name "icicles-doc1.el" :to "Icompletion in *Completions*: Apropos and Prefix Completion")
102 ;; (@file :file-name "icicles-doc1.el" :to "Sorting Candidates and Removing Duplicates")
103 ;; (@file :file-name "icicles-doc1.el" :to "Changing the Sort Order")
104 ;; (@file :file-name "icicles-doc1.el" :to "Defining New Sort Orders")
105 ;; (@file :file-name "icicles-doc1.el" :to "Different Sorts for Different Sorts of Uses")
107 ;; (@file :file-name "icicles-doc1.el" :to "Get Help on Candidates")
108 ;; (@file :file-name "icicles-doc1.el" :to "Use Candidate Help Like You Use Emacs Command `apropos'")
109 ;; (@file :file-name "icicles-doc1.el" :to "Other Icicles Apropos Commands")
111 ;; (@file :file-name "icicles-doc1.el" :to "Multi-Commands")
112 ;; (@file :file-name "icicles-doc1.el" :to "What Is a Multi-Command?")
113 ;; (@file :file-name "icicles-doc1.el" :to "How Does a Multi-Command Work?")
115 ;; (@file :file-name "icicles-doc1.el" :to "More about Multi-Commands")
116 ;; (@file :file-name "icicles-doc1.el" :to "Alternative Actions")
117 ;; (@file :file-name "icicles-doc1.el" :to "Deleting Objects")
118 ;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'")
119 ;; (@file :file-name "icicles-doc1.el" :to "Accessing Saved Locations (Bookmarks) on the Fly")
121 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Tripping")
122 ;; (@file :file-name "icicles-doc1.el" :to "Highlighting the Destination")
124 ;; (@file :file-name "icicles-doc1.el" :to "Key Completion")
125 ;; (@file :file-name "icicles-doc1.el" :to "Completing Keys")
126 ;; (@file :file-name "icicles-doc1.el" :to "`S-TAB' Is Everywhere - Start With It")
127 ;; (@file :file-name "icicles-doc1.el" :to "Completing Keys By Name")
128 ;; (@file :file-name "icicles-doc1.el" :to "Completing Prefix Keys")
129 ;; (@file :file-name "icicles-doc1.el" :to "Meta Key Bindings")
130 ;; (@file :file-name "icicles-doc1.el" :to "Navigate the Key-Binding Hierarchy")
131 ;; (@file :file-name "icicles-doc1.el" :to "Local Bindings Are Highlighted")
132 ;; (@file :file-name "icicles-doc1.el" :to "Completing Keys By Just Hitting Them")
133 ;; (@file :file-name "icicles-doc1.el" :to "Key and Command Help")
134 ;; (@file :file-name "icicles-doc1.el" :to "`S-TAB' Is a Multi-Command")
135 ;; (@file :file-name "icicles-doc1.el" :to "Possible Source of Confusion")
136 ;; (@file :file-name "icicles-doc1.el" :to "Three-Key Emacs")
137 ;; (@file :file-name "icicles-doc1.el" :to "Entering Special and Foreign Characters")
138 ;; (@file :file-name "icicles-doc1.el" :to "Handling Keymaps That Are Inaccessible From the Global Map")
140 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Multi `M-x'")
141 ;; (@file :file-name "icicles-doc1.el" :to "Examples of Using Multi `M-x'")
142 ;; (@file :file-name "icicles-doc1.el" :to "What about describe-variable and describe-function?")
144 ;; (@file :file-name "icicles-doc1.el" :to "Multi `M-x' Turns Every Command into a Multi-Command")
146 ;; (@file :file-name "icicles-doc1.el" :to "Choose All Completion Candidates")
147 ;; (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates")
148 ;; (@file :file-name "icicles-doc1.el" :to "Saving and Retrieving Completion Candidates")
149 ;; (@file :file-name "icicles-doc1.el" :to "Different Places for Saving and Retrieving Candidates")
150 ;; (@file :file-name "icicles-doc1.el" :to "Set Operations")
152 ;; (@file :file-name "icicles-doc1.el" :to "Google Matching")
153 ;; (@file :file-name "icicles-doc1.el" :to "Domain of Discourse")
154 ;; (@file :file-name "icicles-doc1.el" :to "Global Filtering")
155 ;; (@file :file-name "icicles-doc1.el" :to "Word Matching and String Matching")
156 ;; (@file :file-name "icicles-doc1.el" :to "AND Matching and OR Matching")
157 ;; (@file :file-name "icicles-doc1.el" :to "NOT Matching")
159 ;; (@file :file-name "icicles-doc1.el" :to "Buffer-Name Input")
161 ;; (@file :file-name "icicles-doc1.el" :to "File-Name Input and Locating Files Anywhere")
162 ;; (@file :file-name "icicles-doc1.el" :to "Function `read-file-name'")
163 ;; (@file :file-name "icicles-doc1.el" :to "Function `completing-read'")
164 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Commands that Read File Names")
165 ;; (@file :file-name "icicles-doc1.el" :to "Absolute File Names and Different Directories")
167 ;; (@file :file-name "icicles-doc1.el" :to "Persistent Sets of Completion Candidates")
168 ;; (@file :file-name "icicles-doc1.el" :to "Saving Candidates in Cache Files")
169 ;; (@file :file-name "icicles-doc1.el" :to "Filesets and Icicles Saved Completion Sets")
170 ;; (@file :file-name "icicles-doc1.el" :to "Improving Performance with Persistent Sets")
171 ;; (@file :file-name "icicles-doc1.el" :to "Avoid Remote File-Name Completion")
172 ;; (@file :file-name "icicles-doc1.el" :to "Avoid Generating A Large Completion Set")
174 ;; (@file :file-name "icicles-doc1.el" :to "Dealing With Large Candidate Sets")
175 ;; (@file :file-name "icicles-doc1.el" :to "History Enhancements")
176 ;; (@file :file-name "icicles-doc1.el" :to "What Input, What History?")
177 ;; (@file :file-name "icicles-doc1.el" :to "Overview of Minibuffer History Enhancements")
178 ;; (@file :file-name "icicles-doc1.el" :to "Using Completion to Insert Previous Inputs: `M-o'")
179 ;; (@file :file-name "icicles-doc1.el" :to "Putting Previous Candidates First: `C-M-,'")
180 ;; (@file :file-name "icicles-doc1.el" :to "Matching Only Historical Candidates: `M-h' and `M-pause'")
181 ;; (@file :file-name "icicles-doc1.el" :to "Using Other Histories; Commands Any Which Way")
182 ;; (@file :file-name "icicles-doc1.el" :to "Completing Against All Interactive Commands")
183 ;; (@file :file-name "icicles-doc1.el" :to "Using an Alternative History")
184 ;; (@file :file-name "icicles-doc1.el" :to "Cleaning Up History Lists")
186 ;; (@file :file-name "icicles-doc1.el" :to "Isearch Enhancements")
187 ;; (@file :file-name "icicles-doc1.el" :to "Launch Occur using the Isearch Search String")
188 ;; (@file :file-name "icicles-doc1.el" :to "Launch Icicles Search using the Isearch Search String")
190 ;; (@* "Documentation in File `icicles-doc2.el'")
191 ;; ----------------------------------------------
193 ;; (@> "Icicles Search Commands, Overview")
194 ;; (@> "Introduction: On Beyond Occur...")
195 ;; (@> "How Icicles Search Works")
196 ;; (@> "Why Use 2 Search Patterns?")
197 ;; (@> "Search Outside the Defined Search Contexts")
198 ;; (@> "Search Multiple Buffers, Files, and Bookmarks")
199 ;; (@> "User Options for Icicles Searching")
200 ;; (@> "Using Regexps with Icicles Search")
202 ;; (@> "Search and Replace")
203 ;; (@> "Other Icicles Search Commands")
204 ;; (@> "Icicles Imenu")
205 ;; (@> "Type-Specific Imenu Commands")
206 ;; (@> "Imenu Commands that Search Full Definitions")
207 ;; (@> "Icicles Imenu Combines Benefits of Imenu and Emacs Tags")
209 ;; (@> "Compile/Grep Search")
210 ;; (@> "Input Reuse in Interactive Interpreter Modes")
211 ;; (@> "Define Your Own Icicles Search Commands")
213 ;; (@> "Icicles Bookmark Enhancements")
214 ;; (@> "Saving Regions and Selecting Them")
215 ;; (@> "Setting a Bookmark and Jumping to a Bookmark")
216 ;; (@> "Jumping to a Bookmark")
217 ;; (@> "Searching Bookmarked Objects")
219 ;; (@> "Icicles Enhancements for Emacs Tags")
220 ;; (@> "`icicle-find-tag': Find Tags in All Tags Tables")
221 ;; (@> "`icicle-find-first-tag': Find First Tag in Current Table")
222 ;; (@> "`icicle-tags-search': Search and Replace Using Tags")
224 ;; (@> "Icicles Shell-Command Enhancements")
225 ;; (@> "Shell Command Completion as File-Name Completion")
226 ;; (@> "Gotcha: `$' in Shell Commands")
227 ;; (@> "Known Shell Commands as Proxy Candidates")
229 ;; (@> "Icicles Dired Enhancements")
230 ;; (@> "Search-and-Replace Marked Files")
231 ;; (@> "Save Marked Files as Completion Candidates")
232 ;; (@> "Open Dired for a Set of File Names")
233 ;; (@> "Marked Files as a Project")
234 ;; (@> "Shell Commands on Marked Files")
236 ;; (@> "Icicles Info Enhancements")
237 ;; (@> "Icicles Completion for Info")
238 ;; (@> "Virtual Info Books")
240 ;; (@> "Using Icicle-Search With Info")
242 ;; (@> "Support for Projects")
243 ;; (@> "Bookmarks for Project Access and Organization")
244 ;; (@> "A Tags File Can Define a Project")
245 ;; (@> "Navigating Among Code Definitions")
246 ;; (@> "Searching Project Files")
247 ;; (@> "Defining and Saving Sets of Files or Buffers")
248 ;; (@> "Retrieving and Reusing a Saved Project")
249 ;; (@> "Semantics? Roll Your Own?")
251 ;; (@> "Using Complex Completion Candidates")
252 ;; (@> "Icicles OO: Object-Action Interaction")
253 ;; (@> "Apropos Completion as OO")
255 ;; (@> "`icicle-object-action' and `icicle-anything'")
256 ;; (@> "Icicles with Anything")
258 ;; (@> "Multi-Completions")
259 ;; (@> "Icicles Multi-Completion Commands")
260 ;; (@> "How Multi-Completions Work")
261 ;; (@> "Multi-Completions vs `completing-read-multiple'")
263 ;; (@> "Dot, Dot, Dot")
264 ;; (@> "Fuzzy Completion")
265 ;; (@> "Partial Completion")
266 ;; (@> "Scatter-Match Completion")
267 ;; (@> "Swank (Fuzzy Symbol) Completion")
268 ;; (@> "Fuzzy-Match Completion")
269 ;; (@> "Levenshtein Completion")
270 ;; (@> "Jaro-Winkler Completion")
272 ;; (@> "Completion in Other Buffers")
273 ;; (@> "Dynamic Abbreviation")
274 ;; (@> "BBDB Completion")
275 ;; (@> "Thesaurus Lookup and Completion")
276 ;; (@> "Completion in Comint Modes")
278 ;; (@> "Customization and General Tips")
279 ;; (@> "Using Icicles with Delete Selection Mode")
280 ;; (@> "Icicles User Options and Faces")
282 ;; (@> "File-Name and Directory-Name Completion Tips")
283 ;; (@> "Key Bindings")
284 ;; (@> "Global Bindings")
285 ;; (@> "Icicles-Mode Bindings")
286 ;; (@> "Minibuffer Bindings")
288 ;; (@> "Customizing Key Bindings")
289 ;; (@> "Customizing Global Bindings")
290 ;; (@> "Customizing Icicle Mode Bindings")
291 ;; (@> "Customizing Minibuffer Bindings")
293 ;; (@> "Icicles Redefines Some Standard Functions")
294 ;; (@> "Programming with Fancy Candidates")
295 ;; (@> "Programming Multi-Completions")
296 ;; (@> "Variable icicle-list-use-nth-parts")
297 ;; (@> "Variable icicle-candidate-properties-alist")
298 ;; (@> "What You See Is Not What You Get")
300 ;; (@> "Candidates with Text Properties")
301 ;; (@> "Using Property icicle-special-candidate")
302 ;; (@> "Applying Text Properties to a Candidate String")
304 ;; (@> "Defining Icicles Commands (Including Multi-Commands)")
305 ;; (@> "Nothing To It!")
306 ;; (@> "Multi-Commands Are Easy To Define Too")
307 ;; (@> "Are Users Dependent on Icicles To Use Multi-Commands?")
309 ;; (@> "Defining Icicles Tripping Commands")
310 ;; (@> "Defining Multiple-Choice Menus")
311 ;; (@> "Defining Icicles Multi `M-x'")
312 ;; (@> "How Multi `M-x' is Defined")
314 ;; (@> "Defining Multi-Commands the Hard Way")
315 ;; (@> "Global Filters")
316 ;; (@> "Specifying Match Functions for Commands")
317 ;; (@> "Defining Buffer-Text Completion for Comint Modes")
318 ;; (@> "Note to Programmers")
319 ;; (@> "La Petite Histoire")
320 ;; (@> "Note on Non-`nil' `pop-up-frames' on MS Windows")
322 ;;(@* "Icicles Search Commands, Overview")
324 ;; Icicles Search Commands, Overview
325 ;; ---------------------------------
327 ;; This section provides an overview of Icicles search.
331 ;; * The doc string (`C-h f') of command `icicle-search'; it provides
332 ;; a boatload of general information about Icicles search.
334 ;; * (@> "Other Icicles Search Commands") for specialized Icicles
335 ;; search commands, including search in particular buffers.
337 ;; * (@> "Icicles Info Enhancements") for information about using
338 ;; Icicles to search in Info mode.
340 ;; * (@> "Icicles Bookmark Enhancements") for information about
341 ;; searching bookmarks.
343 ;; * (@> "Support for Projects") for information about using `grep'
344 ;; to search all of the files in a project.
346 ;;(@* "Introduction: On Beyond Occur...")
347 ;; ** Introduction: On Beyond Occur... **
349 ;; You've no doubt used standard Emacs command `occur'. It finds all
350 ;; lines in a buffer that match a regexp that you enter. It displays
351 ;; the matching lines as links in buffer `*Occur*' - you can click a
352 ;; link to navigate to the corresponding line in the original buffer.
353 ;; Using buffer `*Occur*' is similar to using the output of the Emacs
356 ;; Command `icicle-occur' is similar to `occur', but instead of
357 ;; entering a regexp (with `RET') you type a regexp and then use
358 ;; `S-TAB' to show the matching lines in buffer `*Completions*'. As
359 ;; usual in Icicles, you can complete to a single candidate, or cycle
360 ;; among candidates to choose one. To navigate to a match in the
361 ;; original buffer, use `C-RET', `C-mouse-2', `C-next', or `C-prior'.
362 ;; One advantage of `icicle-occur' over `occur' is that you can
363 ;; change the regexp on the fly to match different sets of lines.
365 ;; Another, major advantage is that you can use progressive
366 ;; completion to find lines that match multiple regexps. A similar,
367 ;; but less interactive, effect can be had using chained `grep'
368 ;; commands, but it is otherwise not possible with other search
369 ;; methods such as regexp Isearch. A regexp simply cannot express
370 ;; intersection ("and") except in the limited form of "followed by".
372 ;; Command `icicle-search' is a generalization of `icicle-occur'.
373 ;; You enter an initial, search-context regexp (using `RET'), which
374 ;; defines a set of completion candidates: all of the matching
375 ;; strings in the current buffer (by default). These candidates are
376 ;; called "search contexts".
378 ;; Command `icicle-occur' is really `icicle-search' with an implicit
379 ;; initial regexp of `.*' (which you do not enter, however). That
380 ;; is, the initial completion candidates for `icicle-occur' are all
381 ;; of the lines of the buffer (`.' matches any character except a
384 ;; With `icicle-search', the candidates need not be single, complete
385 ;; lines; they can be any strings in the buffer, including multi-line
386 ;; strings. Your initial regexp is used over and over to find the
387 ;; set of matching strings in the region or buffer that you search.
388 ;; These strings then serve as the completion candidates.
390 ;; For example, you might use a search-context regexp of
391 ;; "[A-Z][^.?!]+[.?!]" to search sentences, "\\(.+\n\\)+" to search
392 ;; paragraphs, or "\\([^\f]*[\f]\\|[^\f]+$\\)" to search pages.
393 ;; (That's in fact how convenience commands
394 ;; `icicles-search-sentences', `icicles-search-paragraphs', and
395 ;; `icicles-search-pages' are defined.)
397 ;; `\f' is the form-feed, or page-separator, character. You input
398 ;; `\f', `\t', and `\n' using `C-q l', `C-q TAB', and `C-j',
399 ;; respectively. See (@> "Dot, Dot, Dot") for information about
400 ;; multi-line dot (`.'), which matches also newline.
402 ;; Again, you can use progressive completion (`M-*' or `S-SPC') to
403 ;; match several different regexps within the same page or the same
404 ;; sentence. For example, you could find all sentences that contain
405 ;; `character', `delete', and `backward', in any order, as follows:
407 ;; C-c ` [A-Z][^.?!]+[.?!] RET
408 ;; character M-* delete M-* backward
410 ;; When you visit a search context, both `icicle-occur' and
411 ;; `icicle-search' highlight that hit. For `icicle-occur', the
412 ;; search context is the current line. For `icicle-search', it is
413 ;; whatever your search-context regexp matches.
415 ;;(@* "How Icicles Search Works")
416 ;; ** How Icicles Search Works **
418 ;; There are several Icicles search commands, some of which are bound
419 ;; to keys in Icicle mode:
421 ;; `C-c '', `icicle-occur' (aka `icicle-search-lines') -
422 ;; An `occur' with incremental completion
423 ;; `C-c `' `icicle-search' - Seach buffer areas that match regexp
424 ;; `icicle-search-buffer' (`C-1') - Search selected buffers
425 ;; `icicle-search-buff-menu-marked' - BufferMenu marked
426 ;; `icicle-search-ibuffer-marked' - Search Ibuffer marked
427 ;; `icicle-search-dired-marked' - Search Dired marked files
428 ;; `icicle-search-file' (`C--') - Search selected files
429 ;; `icicle-search-bookmarks-together' (`C-u'),
430 ;; `icicle-search-bookmark' - Search bookmarks
431 ;; `icicle-search-*-bookmark' - Bookmarks of a given type
432 ;; `C-c $' `icicle-search-word' - Whole words as contexts
433 ;; `C-c ^' `icicle-search-keywords' - Search with regexp keywords
434 ;; `C-c `' `icicle-compilation-search' - Search compilation hits
436 ;; `C-c "' ["] `icicle-search-text-property' -
437 ;; Search text having a given text property
438 ;; `icicle-search-overlay-property' -
439 ;; Search text having a given overlay property
440 ;; `icicle-search-char-property' -
441 ;; Search text having a given text/overlay property
442 ;; `icicle-search-pages' - Search Emacs pages
443 ;; `icicle-search-paragraphs' - Search Emacs paragraphs
444 ;; `icicle-search-sentences' - Search sentences as contexts
445 ;; `icicle-search-thing' - Search thing-at-point things
446 ;; optionally ignoring comments
447 ;; `icicle-search-xml-element' - Search XML elements
448 ;; `icicle-search-xml-element-text-node'- Search text nodes
450 ;; `C-c =' `icicle-imenu' (aka `icicle-search-defs') -
451 ;; Navigate among Imenu entries.
452 ;; `icicle-imenu-command' -
453 ;; Navigate among Emacs command definitions.
454 ;; `icicle-imenu-non-interactive-function' -
455 ;; Navigate among Emacs non-interactive function
457 ;; `C-c TAB' `icicle-comint-command' - Retrieve a past shell command.
459 ;; There are many `icicle-search-*-bookmark' commands, for searching
460 ;; within bookmarks of various types. And for each of the
461 ;; `icicle-menu*' commands there is a `-full' version that searches
462 ;; the full text of a command etc. definition.
464 ;; All Icicles search commands operate in the same general way:
466 ;; 1. Unlike standard incremental search, Icicles search commands
467 ;; search the entire buffer, not just the part that follows the
468 ;; cursor. If the region is active, however, then the search is
469 ;; confined to the region. Some Icicles search commands let you
470 ;; search across multiple buffers, multiple files, or multiple
471 ;; bookmarks, including region bookmarks. Searching within one or
472 ;; more such regions of text is a first way to limit the context
475 ;; 2. You limit the search context in a second way, by providing some
476 ;; information, such as a regexp or a character property (text or
477 ;; overlay property), that defines zones of text that you want to
478 ;; search. You can use (lax) completion against previous input to
479 ;; enter the regexp or the character property. In some cases, the
480 ;; information (e.g. regexp) to define the search context is
481 ;; provided automatically by the search command; for example,
482 ;; `icicle-occur' assumes that you want to search lines.
484 ;; 3. If you use a regexp to define the search context, and if that
485 ;; regexp has subgroups, that is, subexpressions of the form
486 ;; `\(...\)', then you are prompted for the subgroup to use to
487 ;; define the search context. 0 means the entire regexp match is
488 ;; used as a context. 1 means that whatever the first subgroup
489 ;; matches is used as a context, and so on.
491 ;; Using a subgroup thus limits the search context in a third way.
492 ;; It lets you find a search match within a larger search-match
493 ;; context. For example, you might choose a Lisp argument list as
494 ;; the search context, specifying that it must follow `(defun ':
495 ;; `(defun [^(]*\(([^(]*)\)'. Subgroup 1 is the argument list.
496 ;; Specifying a subgroup search context helps you become more
497 ;; familiar with regexps. Icicles search highlighting (see below)
498 ;; shows you the subgroup matches instantly.
500 ;; 4. You can limit the set of search contexts in a fourth way, by
501 ;; using `M-&' to provide predicates that search-context
502 ;; candidates must satisfy. Command `icicle-search' and its
503 ;; derivative functions use candidates of the form (CONTEXT
504 ;; . MARKER), where CONTEXT is a string, the search hit (search
505 ;; context), and MARKER is a buffer marker that locates the
506 ;; CONTEXT. Predicates you supply to the `M-&' prompt must expect
507 ;; such candidates. Only contexts that satisfy the predicate are
508 ;; found. For example, if the predicate is (lambda (x) (commandp
509 ;; (intern-soft (car x)))), then only contexts that name Emacs
510 ;; commands are found. Or, if you have a predicate `verbp' that
511 ;; tests whether a word is an English verb form, then you can use
512 ;; that to limit word matches to verbs. In this way, you can
513 ;; combine purely syntactic searching (regexp or text-property
514 ;; match) with more semantic search criteria. After building up a
515 ;; complex predicate by using `M-&', you can save it to a variable
516 ;; with `C-M-&' and then reuse it later with `C-='.
517 ;; See also (@file :file-name "icicles-doc1.el" :to "Progressive Completion").
519 ;; 5. Icicles finds all of the qualified search contexts, and
520 ;; presents them to you as completion candidates. As always for
521 ;; Icicles completion, the number of search hits (matching
522 ;; candidates), is displayed in the mode-line of buffer
523 ;; `*Completions*' - e.g., `72 candidates'.
525 ;; 6. You can navigate among the source-buffer search contexts, using
526 ;; the multi-command action keys (`C-next', `C-prior', `C-RET',
527 ;; `C-mouse-2'). The contexts are highlighted in the source
528 ;; buffer(s). You can scroll the current search-hits buffer
529 ;; forward and backward using `C-M-v' and `C-M-S-v' (aka `C-M-V').
530 ;; Whenever the destination would be off-screen, user option
531 ;; `icicle-recenter' is passed to `recenter' to make it visible.
533 ;; 7. As always in Icicles, your current minibuffer input filters the
534 ;; set of current candidates - the search contexts, so that only
535 ;; those that contain matches to your input remain as candidates.
536 ;; This is a second level of matching: looking for a refinement
537 ;; pattern within the search contexts. And this constitutes a
538 ;; fifth way you can limit the set of search contexts.
540 ;; 8. As always in Icicles, this input can be a regexp. This is
541 ;; ordinary apropos completion, applied to searching. You do not
542 ;; type `RET' to enter this regexp, and you can change it on the
543 ;; fly to change the set of search hits. Icicles searching is
544 ;; thus incremental, in the sense that changing your input
545 ;; dynamically changes the set of matching search hits. Icicles
546 ;; searching is not incremental with respect to the initial,
547 ;; context matching, however.
549 ;; 9. As always in Icicles, you can type some input and then hit
550 ;; `C-~' to remove all candidates that match that input. Then
551 ;; type some other input and hit `C-~' again to remove those
552 ;; matches. Or you can use `M-&' to define a predicate, and then
553 ;; hit `C-~' to remove all candidates that satisfy that predicate.
554 ;; And so on. And you can use `S-mouse-2' or the `delete' key to
555 ;; remove individual search hits. These techniques let you chip
556 ;; away at the search set, removing hits that are uninteresting.
557 ;; This is a very powerful technique for both searching and
558 ;; search-and-replace (see next), and it constitutes a sixth way
559 ;; to limit the set of search contexts. See also
560 ;; (@file :file-name "icicles-doc1.el" :to "Chip Away the Non-Elephant").
562 ;; 10. You can sort the search hits in various ways. This can
563 ;; facilitate navigation and comparison of hits, as well as
564 ;; search-and-replace (see #11). And you can define your own
565 ;; Icicles search commands that provide custom search orders for
566 ;; particular kinds of search. It is likely that you have never
567 ;; considered being able to sort search hits, but if you think
568 ;; about it you will see that this can be handy. If you are
569 ;; searching across multiple buffers, files, or bookmarks, sorting
570 ;; helps you compare, visit, and replace related hits from the
571 ;; different sources, instead of having to handle all of the hits
572 ;; from each source in turn.
574 ;; 11. You can replace text while you search, forward, backward, or
575 ;; randomly. You can replace entire search contexts or just the
576 ;; parts that match your current input. You can use any
577 ;; replacement string that is allowed by `query-replace-regexp'.
578 ;; In Emacs 22 or later, this includes `\,', to substitute the
579 ;; result of a Lisp evaluation. Use the alternative-action keys
580 ;; for replacement: `C-S-RET', `C-S-mouse-2', `C-S-down',
581 ;; `C-S-up', `C-S-next', `C-S-prior', `C-S-end', and `C-S-home'.
582 ;; At the first use, you are prompted for the replacement string;
583 ;; it is used thereafter. You can use `M-|'
584 ;; (`icicle-all-candidates-list-alt-action') to replace all
585 ;; matches. See (@> "Search and Replace").
587 ;; 12. When you visit a search context (using `C-mouse-2' or
588 ;; `C-down', for example), the part of the candidate that matches
589 ;; your input is highlighted. An entire search context is
590 ;; highlighted in face `icicle-search-main-regexp-current', and
591 ;; the part that matches your input is highlighted in face
592 ;; `icicle-search-current-input'. All other search contexts are
593 ;; also highlighted (in face `icicle-search-main-regexp-others').
595 ;; 13. User option `icicle-search-highlight-all-current-flag'
596 ;; controls whether the input matches are highlighted within each
597 ;; search context or only within the current context. It,
598 ;; together with `icicle-expand-input-to-common-match-flag',
599 ;; controls whether the input-match highlighting covers an
600 ;; expanded common match among all matches or just the exact input
603 ;; 14. If you do not use a subgroup to define the search context (as
604 ;; in #3, above), that is, if the search context corresponds to
605 ;; the entire search regexp, then up to eight context levels
606 ;; (subgroups) are each highlighted differently, using faces
607 ;; `icicle-search-context-level-1' through
608 ;; `icicle-search-context-level-8'. This context-level
609 ;; highlighting is not done if user option
610 ;; `icicle-search-highlight-context-levels-flag' is `nil'.
612 ;; You might have noticed that out of these 14 search features, 6
613 ;; constitute independent ways in which you can narrow or limit the
614 ;; set of search hits among which you can navigate. And another one
615 ;; (sorting) further facilitates your observation and selection of
616 ;; search hits. Restricting the search space and making search-hit
617 ;; patterns more evident are in fact what search is all about, and
618 ;; Icicles offers you some unique tools to do this.
620 ;; For several Icicles search commands, including `icicle-search'
621 ;; (`C-c `'), you provide an initial regexp to define the search
622 ;; contexts (step 1, above). Why use two regexps to search (steps 1
623 ;; and 4, above)? To make things simpler. Regular expressions are
624 ;; powerful for searching, but they can also be cumbersome sometimes.
625 ;; Why not use one simple regexp to set up a set of candidates and
626 ;; then, optionally, use a second simple regexp to filter those
629 ;; This is the same idea as that behind progressive completion. And
630 ;; speaking of which, how would you find a line that contains a given
631 ;; set of words (each of them), but in an arbitrary (unknown) order?
632 ;; Progressive completion. Which lines in this doc section contain
633 ;; the words `which', `you', and `how', in any order? If you are
634 ;; reading this doc in file `icicles-doc2.el', then just use
635 ;; `icicle-occur' with progressive completion:
637 ;; C-c ' which M-SPC you M-SPC how
639 ;; That narrows things down to four lines that you can then navigate
640 ;; among. Progressive completion gives Icicles search a power boost.
642 ;; Like `icicle-occur', commands `icicle-search-word' (`C-c $') and
643 ;; `icicle-search-keywords' (`C-c ^') are variants of `icicle-search'
644 ;; that differ only in the regexp used. Each accepts your input and
645 ;; converts it to a regexp that does the right thing.
646 ;; `icicle-search-word' just adds `\b' before and after the word you
647 ;; type, so that it matches at word boundaries.
649 ;; `icicle-search-keywords' wraps the keywords you provide as input
650 ;; with regexp grouping (`\(...\)') and alternative (`\|') syntax, so
651 ;; that search looks for any of the keywords.
653 ;; "Keywords" here is an understatement. Each keyword is actually a
654 ;; regexp and is treated as such, unless you use `C-`' to turn on
655 ;; escaping of regexp special characters. In that case, each keyword
656 ;; is matched as a substring. At the `C-c $' prompt, you can use
657 ;; completion to choose keywords that you have already entered, or
658 ;; you can use `C-RET' to enter new keywords.
660 ;; As a shortcut, you can use the search string during incremental
661 ;; search (Isearch) as the initial regexp for `icicle-search'. You
662 ;; do this by hitting `S-TAB' during Isearch. This ends Isearch and
663 ;; passes its search string to `icicle-search'. This can be a handy
664 ;; way to start `icicle-search', picking up its search pattern by
665 ;; using, say, `C-s C-w C-w...'.
666 ;; See (@file :file-name "icicles-doc1.el" :to "Launch Icicles Search using the Isearch Search String")
668 ;;(@* "Search Outside the Defined Search Contexts")
669 ;; ** Search Outside the Defined Search Contexts **
671 ;; For each of the predefined Icicles search commands, including for
672 ;; `icicle-search' itself, you can alternatively choose to search,
673 ;; not the search contexts as you define them, but the non-contexts,
674 ;; that is, the buffer text that is outside (in between) the search
675 ;; contexts as defined.
677 ;; For example, if you use `icicle-search-thing' and you define sexps
678 ;; as the search contexts, then this feature lets you search the
679 ;; zones of text that are not within a sexp. Or if you use
680 ;; `icicle-search-text-property' (`C-c "'), you can search the zones
681 ;; of text that do not have a text-property value that you specify
682 ;; (e.g., property `face' with faces `font-lock-comment-face' and
683 ;; `font-lock-comment-delimiter-face' - which means all code outside
686 ;; To turn this context-complementing feature on and off, hit `C-M-~'
687 ;; (`icicle-toggle-search-complementing-domain') during completion.
688 ;; This is a toggle, and it affects only future search commands, not
691 ;;(@* "Search Multiple Buffers, Files, and Bookmarks")
692 ;; ** Search Multiple Buffers, Files, and Bookmarks **
694 ;; If you provide a prefix argument to most Icicles search functions,
695 ;; then you can search multiple buffers, files, or bookmarks.
697 ;; * Plain prefix argument (`C-u') - Search multiple bookmarks of
698 ;; various kinds. To use this feature, you must also use library
699 ;; `bookmark+.el'. See (@> "Icicles Bookmark Enhancements").
701 ;; * Non-negative numeric prefix argument (e.g. `C-9') - Search
702 ;; multiple buffers - you are prompted for the buffers to search.
703 ;; If the prefix argument is 99, then only buffers that are
704 ;; visiting files are candidates. You can use `C-RET' and so on to
705 ;; choose individual buffers with completion. You can use `C-!' to
706 ;; choose all buffers or all buffers that match a regexp.
707 ;; (See (@file :file-name "icicles-doc1.el" :to "Multi-Commands").)
709 ;; Note: You can use `M-s i' in Ibuffer or Buffer Menu to search
710 ;; all marked buffers using Icicles search. In Ibuffer, menu item
711 ;; `Icicles Search (and Replace)...' does the same thing as `M-s
714 ;; * Negative numeric prefix argument (e.g. `C--') - Search multiple
715 ;; files in the current directory - you are prompted for the files
716 ;; to search. As for multiple-buffer searching, you can use
717 ;; `C-RET' and so on.
719 ;; Note: You can use `M-s i' in Dired to search all marked files
720 ;; using Icicles search. Menu item `Search (and Replace)...' is
721 ;; added to the Icicles submenu of menu `Multiple' (or `Operate'),
722 ;; and it does the same thing as `M-s i'.
724 ;; As a convenience, some specialized Icicles commands are defined
725 ;; that correspond to `icicle-search' with the various
726 ;; prefix-argument cases: `icicle-search-bookmarks-together',
727 ;; `icicle-search-buffer', and `icicle-search-file'. If you often
728 ;; use `C-c `' with one of the prefix argument options, then you
729 ;; might want to bind one or more of these commands. These commands
730 ;; are also available in the Icicles menu-bar menu (or the Search
731 ;; menu, if it exists).
733 ;;(@* "User Options for Icicles Searching")
734 ;; ** User Options for Icicles Searching **
736 ;; You can customize the following user options, to control search
737 ;; and replacement behavior.
739 ;; * If `icicle-show-multi-completion-flag' is non-`nil' (the default
740 ;; value), then, whenever you use a prefix argument, Icicles search
741 ;; functions annotate each candidate with the name of the buffer
742 ;; where the search hit occurs, highlighted, to help orient you.
743 ;; The buffer name is actually part of the (multi-completion)
744 ;; candidate, so you can match against it.
746 ;; Note that even when the value of this option is `nil', if option
747 ;; `icicle-help-in-mode-line-delay' is greater than zero then you
748 ;; can see the buffer name in the mode-line (as well as the
749 ;; position and length of the search context in the buffer).
751 ;; * Icicles search functions that use an initial regexp highlight
752 ;; the first `icicle-search-highlight-threshold' matches for that
753 ;; regexp at once (using face `icicle-search-main-regexp-others').
754 ;; The effect is similar to the Emacs 22+ lazy search highlighting
755 ;; of Isearch (except that the highlighting is not in fact lazy).
757 ;; * If `icicle-search-highlight-all-current-flag' is non-`nil', then
758 ;; Icicles search functions highlight your current input match
759 ;; within *all* search contexts at once. If it is non-`nil' and
760 ;; `icicle-expand-input-to-common-match-flag' is also non-`nil',
761 ;; then what is highlighted for each input match is the expanded
762 ;; common match among all input matches throughout the search area.
763 ;; If either is `nil', then only the exact input match is
767 ;; (see (@file :file-name "icicles-doc1.el" :to "Nutshell View of Icicles")),
768 ;; if the initial regexp defining the search context is
769 ;; `.*recursive.*', and your input is `edit', then searching file
770 ;; `icicles-doc1.el' highlights not `edit' but
771 ;; ``abort-recursive-edit'', which is the longest common match
772 ;; among all input matches.
774 ;; Gotcha: Remember that the expanded common match pertains to the
775 ;; entire completion candidate. In the context of Icicles
776 ;; search, if you are interested in multiple matches of
777 ;; your input within the same search context, and you want
778 ;; to be sure to catch each match, then turn off
779 ;; common-match expansion.
781 ;; Why? The search context as a whole is compared with the
782 ;; other search contexts when looking for the expanded
783 ;; common match. Your input is matched against the entire
784 ;; context (search hit), and the expanded common match is
785 ;; (typically) the longest match that is common to the
786 ;; other search contexts. Do not expect the longest common
787 ;; match of your input against all occurrences in the
788 ;; search contexts. What counts is the longest single
789 ;; match for a given context.
791 ;; For example, if your input is `then' and two of the
792 ;; search hits are `But then X and then Y' and `W and then
793 ;; Z', the expanded common match will be `and then', not
794 ;; `then'. The matches highlighted for your input thus do
795 ;; not include each occurrence of `then' in the search
796 ;; hits, but rather each occurrence of `and then'.
798 ;; If `icicle-expand-input-to-common-match-flag',
799 ;; `icicle-search-highlight-all-current-flag', and
800 ;; `icicle-search-replace-common-match-flag' are all non-`nil',
801 ;; then a search replacement replaces the expanded common match;
802 ;; otherwise, it replaces only the exact match.
804 ;; The default value of `icicle-search-highlight-all-current-flag'
805 ;; is `nil', because non-`nil' can impact performance negatively if
806 ;; there are many search contexts - the highlighting is updated
807 ;; with each input change. You can toggle the value at any time
808 ;; using command `icicle-toggle-highlight-all-current', bound to
809 ;; `C-^' in the minibuffer during Icicles search.
811 ;; * If option `icicle-search-cleanup-flag' is non-`nil' (the default
812 ;; value) then search highlighting is removed after the search. If
813 ;; you set this to `nil' then you can remove search highlighting
814 ;; manually later using command `icicle-search-highlight-cleanup'.
815 ;; You can toggle this search highlight removal at any time using
816 ;; command `icicle-toggle-search-cleanup', which is bound to `C-.'
817 ;; in the minibuffer during Icicles search.
819 ;; One use of `nil' `icicle-search-cleanup-flag' is to highlight
820 ;; regexp matches throughout a region or buffer (or multiple files
821 ;; or...). In that capacity, Icicles search functions act like
822 ;; some of the highlighting commands in my library `highlight.el'.
823 ;; Note that when `icicle-search-cleanup-flag' is `nil', *all*
824 ;; Icicles search highlighting remains: last-visited search
825 ;; context, other context matches, current-input matches, and even
826 ;; regexp subgroups. The faces for these are, respectively:
828 ;; - `icicle-search-main-regexp-current'
829 ;; - `icicle-search-main-regexp-others'
830 ;; - `icicle-search-highlight-input-matches-here' (everywhere, if
831 ;; `icicle-search-highlight-all-current-flag' is non-`nil')
832 ;; - `icicle-search-context-level-1' through
833 ;; `icicle-search-context-level-8'
835 ;; * If `icicle-search-replace-whole-candidate-flag' is `nil', then
836 ;; whatever matches your current input is replaced, within the
837 ;; current search context, when you perform replacement
838 ;; (e.g. `C-S-RET'). If the value is non-`nil' (the default
839 ;; value), then the entire search context is replaced, instead.
840 ;; You can use `M-_' at any time during searching and replacing, to
843 ;; * Command `icicle-search-word' (bound to `C-c $') always searches
844 ;; for a whole word: your initial search string is matched only
845 ;; against whole words. Non-`nil' `icicle-search-whole-word-flag'
846 ;; makes other Icicles search commands also perform whole-word
847 ;; searching. You can use `M-q' while searching to toggle this
848 ;; option; the new value takes effect for the next complete search.
850 ;; Whole-word searching here means that matches can contain
851 ;; embedded strings of non word-constituent chars (they are skipped
852 ;; over, when matching, included in the match), and any leading or
853 ;; trailing word-constituent chars in the search string are dropped
854 ;; (ignored for matching, not included in the match). This means,
855 ;; for instance, that you can match `foo-bar' as a word, even in
856 ;; contexts (such as Emacs Lisp) where `-' is not a
857 ;; word-constituent character. Similarly, you can include embedded
858 ;; whitespace in a "word", e.g., `foo bar'.
860 ;; * You can toggle `icicle-use-C-for-actions-flag' at any time using
861 ;; `M-g' in the minibuffer. This is handy for multi-commands that
862 ;; browse, such as Icicles search. It means that you can use
863 ;; `next' and so on instead of `C-next' and so on to navigate among
865 ;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'").
867 ;; * Non-`nil' option `icicle-ignore-comments-flag' means that
868 ;; `icicle-search-thing' and related commands
869 ;; (e.g. `icicle-search-xml-element') ignore comments. That is,
870 ;; they hide comments temporarily while they scan the region or
871 ;; buffer for things of the given type to serve as search contexts
872 ;; (completion candidates). This prevents them, for example, from
873 ;; presenting as a candidate a sexp or a list that is commented
874 ;; out. You can toggle this option anytime using `C-M-;' in the
875 ;; minibuffer, but to see the effect you might need to invoke the
876 ;; current command again.
878 ;; * `icicle-search-hook': Functions run after searching and moving
879 ;; to a match, whether by `RET' or `C-RET' (or `C-next' or
882 ;; It can sometimes be useful to highlight all regexp matches using a
883 ;; large value of `icicle-search-highlight-threshold' and a `nil'
884 ;; value of `icicle-search-cleanup-flag', and then set
885 ;; `icicle-search-highlight-threshold' to zero and use an Icicles
886 ;; search function again with a different regexp to search through
887 ;; the same region or buffer. This lets you see the relation between
888 ;; the two sets of regexp matches.
890 ;;(@* "Using Regexps with Icicles Search")
891 ;; ** Using Regexps with Icicles Search **
893 ;; You can use Icicles search to find text entities of a certain kind
894 ;; - sentences, paragraphs, file names, URLs, and so on. A
895 ;; convenient way to do this is to use `C-='
896 ;; (`icicle-insert-string-from-variable') or `C-x r i'
897 ;; (`insert-register') in the minibuffer to insert a predefined
898 ;; regexp that matches a particular kind of text entity. Which of
899 ;; these you use depends on whether the regexp string is saved in a
900 ;; variable (`C-=') or a register (`C-x r i').
902 ;; For example, suppose you are in a mail client and you want to move
903 ;; between mail headers. If you use a regexp that matches the header
904 ;; field you want (e.g. the sent date or sender) then Icicles search
905 ;; highlights all such occurrences and lets you navigate among them -
906 ;; instant mail browser! Or, suppose you are in a C++ or Perl file
907 ;; and you want to navigate among function definitions or other
908 ;; definitions. If you have a canned regexp that matches the start
909 ;; of a definition, then you can use `C-=' to quickly turn
910 ;; `icicle-search' into a code browser. In a log file, navigate
911 ;; among date or time entries or IP addresses... Of course, most
912 ;; programming modes and mail clients already provide other ways to
913 ;; navigate, but you get the idea - Icicles search provides a general
914 ;; way to navigate among things, as long as you can match them with
915 ;; regexps, and `C-=' lets you quickly access a library of predefined
918 ;; You can find useful regexps to store in variables in the standard
919 ;; Emacs Lisp libraries. Grep for `font-lock-keywords' or `regexp'
920 ;; in the Emacs `lisp' directory and its subdirectories.
922 ;; See `align.el' for regexps for programming languages.
923 ;; See `url-dav.el' for regexps matching ISO 8601 dates.
924 ;; See `rmail.el', `sendmail.el', and `mh-show.el' for regexps
925 ;; matching mail-header fields.
927 ;; Imenu regexps occurring as parts of different values of
928 ;; `imenu-generic-expression' for different buffer types can be used
929 ;; as variable values for `C-='. They all work fine with
930 ;; `icicle-search', turning it into a navigator for the given mode.
931 ;; See, for example, `generic-x.el' and `lisp-mode.el'. Here is a
932 ;; regexp for Javascript function definitions from `generic-x.el':
934 ;; "^function\\s-+\\([A-Za-z0-9_]+\\)"
936 ;; And `lisp-imenu-generic-expression' (in `lisp-mode.el') provides
937 ;; regexps for Lisp function, variable, and type definitions. Here
938 ;; is the variable-definition regexp:
940 ;; "^\\s-*(\\(def\\(c\\(onst\\(ant\\)?\\|ustom\\)\\|ine-symbol-macro
941 ;; \\|parameter\\|var\\)\\)\\s-+\\(\\(\\sw\\|\\s_\\)+\\)"
943 ;; You certainly do not want to type a regexp like that into the
944 ;; minibuffer (and the function-definition regexp is twice as
945 ;; complex)! Put it into a variable or register once and use `C-='
946 ;; or `C-x r i' from then on to retrieve it - simple.
948 ;; If it's so simple, then why not let a command do it? This is
949 ;; exactly what command `icicle-imenu' (bound to `C-c =') does. You
950 ;; do not need to bother looking up Imenu regexps and assigning them
951 ;; to variables for use with `C-=' and `icicle-search'-
952 ;; `icicle-imenu' does that for you automatically.
953 ;; See (@> "Other Icicles Search Commands").
955 ;; In sum: For complete interactivity, type a regexp dynamically as
956 ;; input to `icicle-search'. For isolated special regexps that you
957 ;; use, save them in variables and use `C-=' with `icicle-search'.
958 ;; For well-defined sets of regexps, especially if used frequently,
959 ;; define a command that uses `icicle-search'. There is a spectrum
960 ;; of use cases for `icicle-search'.
962 ;; Command `icicle-search' is very general and very powerful. It
963 ;; might never replace incremental search - either regexp or literal
964 ;; string search, but in some cases it can be quite handy. Think of
965 ;; it as another tool to add to your search-tool belt. Admittedly,
966 ;; it does take a little getting used to. Remember, in particular,
967 ;; that the initial, context regexp you enter (with `RET') cannot be
968 ;; changed without re-executing `icicle-search'.
970 ;; And remember too that `C-l' (`icicle-retrieve-previous-input') is
971 ;; your friend - it clears the minibuffer during cycling, retrieving
972 ;; your last real input. Use it to modify your second and subsequent
973 ;; regexps on the fly - those that filter the initial candidate list
974 ;; further. You can repeat `C-l' to retrieve older completion
975 ;; inputs, and you can use `C-S-l' (that is, `C-L') to cycle previous
976 ;; inputs in the other direction. See
977 ;; (@file :file-name "icicles-doc1.el" :to "History Enhancements").
979 ;; Oh - And do not forget that you can do things like take the
980 ;; complement of your fine-tuning regexp matches, within the context
981 ;; of your coarse-tuning matches. See
982 ;; (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates").
984 ;; For example, use `^.*defun.*$' as the main regexp, to find all
985 ;; lines containing `defun'. Then type `icicle' to match only the
986 ;; lines with `defun' that also contain `icicle'. Then complement
987 ;; (`C-~') that set, to see the lines that contain `defun' but not
990 ;; And you can then save that set of matches, and then subtract it
991 ;; from another set of matches in a different search... You get the
992 ;; idea. When performing set operations combined with
993 ;; `icicle-search', keep in mind that the saved set does not include
994 ;; any position information - it is only a set of matching strings.
995 ;; So, in particular, a set-union operation (`C-+') is not useful
996 ;; with `icicle-search' (adding a saved set of strings without
997 ;; positions is useless). Still, you can do things like match lines
998 ;; that contain `defun' followed somewhere by `()', and then subtract
999 ;; the (saved) set of lines in the same region that contain `icicle'.
1000 ;; Try it in an Icicles library, using regexps `.*icicle.*$' and
1001 ;; `^*.defun.*().*$'.
1003 ;; One more reminder: When you save a set of completion candidates
1004 ;; (`C-M->'), make sure that you actually have a set of candidates to
1005 ;; save! It is not enough to just enter a regexp at the
1006 ;; `icicle-search' prompt. You must also use some Icicles command,
1007 ;; such as `TAB', `S-TAB', `next', or `down' to tell Icicles how to
1008 ;; create the candidate set - how to match the regexp.
1012 ;; * The doc string (`C-h f') of command `icicle-search'; it provides
1013 ;; general information about Icicles search.
1015 ;; * (@> "Other Icicles Search Commands") for specialized Icicles
1016 ;; search commands `icicle-comint-search',
1017 ;; `icicle-compilation-search', `icicle-imenu',
1018 ;; `icicle-imenu-command', `icicle-imenu-non-interactive-function',
1019 ;; `icicle-search-char-property', `icicle-search-keywords',
1020 ;; `icicle-search-overlay-property', and
1021 ;; `icicle-search-text-property'.
1023 ;; * (@> "Search and Replace") for information about replacing search
1024 ;; hits or parts of search hits.
1026 ;; * (@> "Customization and General Tips") for information about the
1027 ;; `icicle-search-*' faces, which control Icicles search.
1029 ;; * (@file :file-name "icicles-doc1.el" :to "Progressive Completion")
1030 ;; for information about `M-*' and `M-&'.
1032 ;; * (@file :file-name "icicles-doc1.el" :to "Multi-Commands") for
1033 ;; information about `C-RET', `C-mouse-2', `C-next', and `C-prior'.
1035 ;; * (@> "Icicles Bookmark Enhancements") for information about
1036 ;; searching bookmarks.
1038 ;; * (@file :file-name "icicles-doc1.el" :to "Inserting a Regexp from a Variable or Register")
1039 ;; for more about inserting a saved string.
1041 ;; * (@> "Icicles Info Enhancements") for information about using
1042 ;; Icicles to search in Info mode.
1044 ;;(@* "Search and Replace")
1046 ;; Search and Replace
1047 ;; ------------------
1049 ;; Replacement during Icicles search is something quite different
1050 ;; from anything you are used to. There are several different ways
1051 ;; to replace search-hit text during Icicles search, and it can be a
1052 ;; bit of a challenge to understand all the possibilities. So my
1053 ;; advice is to experiment, as well as to read the descriptions here.
1055 ;; You can replace the current search match by using any of the
1056 ;; alternative action keys: `C-S-RET', `C-S-mouse-2' (in
1057 ;; `*Completions*'), `C-S-down', `C-S-up', `C-S-next', `C-S-prior',
1058 ;; `C-S-end', or `C-S-home', . You can use `M-|'
1059 ;; (`icicle-all-candidates-list-alt-action') to replace all matches
1060 ;; of your current input at once, throughout the search space.
1062 ;; At the first use of any of these, you are prompted for the
1063 ;; replacement pattern; it is used thereafter, or until you use `M-,'
1064 ;; (`icicle-search-define-replacement'). You can use `M-,' at any
1065 ;; time during searching to change the pattern for subsequent
1066 ;; replacements. The replacement pattern can be anything that is
1067 ;; allowed as a replacement by `query-replace-regexp'. In Emacs 22
1068 ;; or later, this includes Lisp sexp evaluation via `\,'.
1070 ;; Unlike `query-replace', you need not visit each search match - you
1071 ;; can visit and replace selected matches in any order. Some other
1072 ;; differences from standard `query-replace' and
1073 ;; `query-replace-regexp':
1075 ;; * Replacing matches of your current input provides a contextual
1076 ;; replacement feature: replace `foo' by `fu', but only in zones
1077 ;; that match `toto.*titi'.
1079 ;; * Icicles search navigation (`C-next', etc.) lets you replace
1080 ;; individual search hits without navigating through each search
1081 ;; context in turn: direct access.
1083 ;; * In Icicles search, replace-all (`M-|') means replace all
1084 ;; matches of your current input, throughout the search space, not
1085 ;; just all matches that follow the cursor. And remember that you
1086 ;; can (a) activate the region to limit the search-and-replace
1087 ;; space and (b) use progressive completion etc. to narrow the set
1090 ;; * You can act across multiple buffers, files, or bookmarks -
1091 ;; see information about the `icicle-search' prefix arg.
1093 ;; * You can also replace matches within text-property search
1094 ;; contexts - just use `icicle-search-text-property' (`C-c "') ["]
1095 ;; as the search command.
1097 ;; Search matches are replaced - but just what is meant by a "search
1098 ;; match"? It can be either an entire search context or each match
1099 ;; of your current minibuffer input within a search context.
1101 ;; Anytime during search and replace:
1103 ;; * `M-,' redefines the replacement string.
1105 ;; * `C-`' toggles `icicle-toggle-regexp-quote' (as always). This
1106 ;; escapes regexp special characters, so that search is literal.
1108 ;; * `M-q' toggles `icicle-search-whole-word-flag'. By default,
1109 ;; this is `nil', meaning that searching is not for whole words
1110 ;; (except for `icicle-search-word', bound to `C-c $').
1112 ;; * `C-M-`' toggles `icicle-search-replace-literally-flag'. By
1113 ;; default, this is `nil', which means that `\' character
1114 ;; sequences in replacement text are intrepreted as for
1115 ;; `query-replace-regexp'.
1117 ;; * `M-_' toggles `icicle-search-replace-whole-candidate-flag'. By
1118 ;; default, this is non-`nil', which means that the entire current
1119 ;; search context is replaced, that is, whatever matches the
1120 ;; context regexp that you entered initially using `RET'.
1121 ;; However, you can use `M-_' anytime during searching to toggle
1122 ;; between this default behavior and replacement of whatever your
1123 ;; current minibuffer input matches.
1125 ;; * `M-;' toggles `icicle-search-replace-common-match-flag'.
1126 ;; Together with other options, it controls whether to replace the
1127 ;; expanded common match or just the exact match. See below.
1131 ;; - If `icicle-search-replace-whole-candidate-flag' is true
1132 ;; (non-`nil'), then the granularity of replacement is a complete
1133 ;; search context. In this case, replacement behaves similarly to
1134 ;; `query-replace-regexp' (except that special replacement
1135 ;; constructs, such as `\#', are not treated as such). You can
1136 ;; still use minibuffer input to filter the set of search contexts,
1137 ;; but replacement is on a whole-context basis.
1139 ;; - If `icicle-search-replace-whole-candidate-flag' is false
1140 ;; (`nil'), then you can replace multiple input matches separately
1141 ;; within a search context (using `C-S-RET'). This behavior is
1142 ;; unique to Icicles. You cannot, however skip over one input
1143 ;; match and replace the next one in the same context - `C-S-RET'
1144 ;; always replaces the first available match in the context
1145 ;; (repeated use changes which is first). When
1146 ;; `icicle-search-replace-whole-candidate-flag' is `nil', you can
1147 ;; also use special replacement constructs, such as `\#'.
1149 ;; If `icicle-search-replace-whole-candidate-flag' is true, then you
1150 ;; can use the navigational alternative action keys, `C-S-down',
1151 ;; `C-S-up', `C-S-next', `C-S-prior', `C-S-end', and `C-S-home',
1152 ;; repeatedly to replace successive search contexts. At the buffer
1153 ;; limits, these commands wrap around to the other buffer limit (last
1154 ;; search context to first, and vice versa).
1156 ;; Search traversal using these go-to-next-context-and-replace keys
1157 ;; is always by search context, not by individual input match. This
1158 ;; means that you cannot use these keys to replace input matches
1159 ;; within a search context.
1161 ;; If `icicle-search-replace-whole-candidate-flag' is false, then you
1162 ;; can use these keys to replace the first input match. More
1163 ;; importantly, you can use `C-S-RET' to replace that first match,
1164 ;; without moving on to the next context. Because `C-S-RET' always
1165 ;; acts on the current search hit (context), using it again, after
1166 ;; you have used it to replace the first such match, replaces the
1167 ;; next one. And so on.
1169 ;; Thus, if your input matches multiple parts of a search context and
1170 ;; you want to replace these matches, use `C-S-RET' repeatedly.
1171 ;; After all of the matches in the current context have been
1172 ;; replaced, `C-S-RET' replaces the first match in the next context.
1173 ;; (There is a gotcha, however, if the replacement text matches your
1174 ;; input - see below.)
1176 ;; You can thus traverse all matches of your input, in the current
1177 ;; sort order (by default, the order they appear in the source being
1178 ;; searched), by just repeating `C-S-RET'. At the buffer limits,
1179 ;; repeating `C-S-RET' wraps around.
1181 ;; `C-S-RET' always replaces the first input match in the
1182 ;; current search context or, if there are no matches, then the first
1183 ;; input match in the next context. This behavior has these
1184 ;; important consequences:
1186 ;; * If you repeat `C-S-RET' and the previous replacement no longer
1187 ;; matches your input, then `C-S-RET' moves on to the next input
1188 ;; match (which is now the first one) and replaces that. This is
1189 ;; why you can usually just repeat `C-S-RET' to successively
1190 ;; replaces matches of your input, including from one context to
1193 ;; * If, on the other hand, after replacement the text still matches
1194 ;; your input, then repeating `C-S-RET' will just replace that
1195 ;; match. For example, if you replace the input match `ab' by
1196 ;; `abcd', then repeating `C-S-RET' produces `abcd', then `abcdcd',
1197 ;; then `abcdcdcd',...
1199 ;; * You cannot replace an input match, skip the next match, and then
1200 ;; replace the following one, all in the same context. You can,
1201 ;; however, replace some matches and then skip (e.g. `C-next') to
1202 ;; the next context.
1204 ;; What your input matches, hence what gets replaced if
1205 ;; `icicle-search-replace-whole-candidate-flag' is `nil', depends on
1206 ;; a few Icicles options:
1208 ;; - `icicle-regexp-quote-flag' determines whether to use regexp
1209 ;; matching or literal matching.
1211 ;; - `icicle-search-highlight-all-current-flag',
1212 ;; `icicle-expand-input-to-common-match-flag' and
1213 ;; `icicle-search-replace-common-match-flag' together determine
1214 ;; whether to replace exactly what your input matches in the
1215 ;; current search hit or the expanded common match (ECM) of your
1216 ;; input among all search hits. If any of these options is `nil',
1217 ;; then your exact input match is replaced; otherwise, the ECM is
1220 ;; The replacement string can be nearly anything that is allowed as a
1221 ;; replacement by `query-replace-regexp'. In Emacs 22 or later, this
1222 ;; includes Emacs-Lisp sexp evaluation via `\,' and constructs such
1223 ;; as `\#' and `\N' (back references). You can also use `\?', but it
1224 ;; is not very useful - you might as well use `M-,' instead, to
1225 ;; change the replacement text.
1227 ;; Finally, let me repeat what I said at the beginning of this page:
1228 ;; Icicles search-and-replace is different from what you are used to,
1229 ;; and there are several different ways to use it. Experiment to get
1230 ;; to know how it works, and reread the description here.
1232 ;; It is important to understand the various user options (with their
1233 ;; toggle commands) and their effects. They can radically change the
1234 ;; behavior of replacement.
1236 ;; In particular, to put Icicles search-and-replace to best advantage
1237 ;; you need to know what gets replaced, depending on those user
1238 ;; options: the whole search hit vs only input matches, an exact
1239 ;; input match vs the expanded common match. Experiment with the
1240 ;; toggles `M-_', `C-^', `C-;', and `M-;'. And you need to know how
1241 ;; repeated `C-S-RET' works vs repeated `C-S-next'.
1243 ;; I know it's tricky to learn. Experimenting helps. If something
1244 ;; happens that you did not expect, reread this section and try to
1245 ;; understand. Have fun.
1249 ;; * (@> "Icicles Search Commands, Overview") and the doc string of
1250 ;; `icicle-search' for more information about search-and-replace.
1252 ;; * (@> "Compile/Grep Search") for information about using
1253 ;; search-and-replace with `grep' buffers and compilation buffers.
1255 ;; * (@* "Icicles Dired Enhancements") for information about using
1256 ;; search-and-replace on marked files in Dired.
1258 ;;(@* "Other Icicles Search Commands")
1260 ;; Other Icicles Search Commands
1261 ;; -----------------------------
1263 ;; Function `icicle-search' is very general. As is explained in
1264 ;; (@> "Icicles Search Commands, Overview"), command `icicle-occur'
1265 ;; is defined trivially using `icicle-search' - it is basically
1266 ;; `icicle-search' with a regexp of `.*', to match lines. Similarly,
1267 ;; `icicle-search-word' (`C-c $') uses a regexp of `\bWORD\b', where
1268 ;; `WORD' is the word to look for, and `icicle-search-keywords'
1269 ;; (`C-c ^') uses a regexp of `\(KW1\|KW2\|KW2...\|KWn\)', where the
1270 ;; `KWm' are the keywords (regexps) to look for.
1272 ;; Still other Icicles commands are available that make use of
1273 ;; `icicle-search'. And you can define your own, specialized search
1274 ;; commands along the same lines. To do that, it is instructive to
1275 ;; look at the source code of the commands described in this section;
1276 ;; they can serve as a model for defining your own search commands.
1278 ;; Two of the commands described here, `icicle-compilation-search'
1279 ;; and `icicle-comint-search', are specialized versions of
1280 ;; `icicle-search' that work only in particular buffers where there
1281 ;; is little need for `icicle-search' itself. For this reason, these
1282 ;; commands reuse the key sequence, `C-c `' (backquote), that is
1283 ;; normally bound to `icicle-search'. This shadow binding occurs if
1284 ;; the current major mode is a compilation mode (for
1285 ;; `icicle-compilation-search') or an interactive interpreter mode
1286 ;; such as `shell-mode' or Lisp interactive mode (for
1287 ;; `icicle-comint-search').
1289 ;; [Programmer Note: Actually, the way this works is that `C-c `' is
1290 ;; bound to the value of internal variable `icicle-search-generic'.
1291 ;; You can use this mechanism to provide custom Icicles search
1292 ;; commands for particular buffers.]
1294 ;; Besides the commands described in this section, there are Icicles
1295 ;; search commands for navigating tags-file definitions and searching
1296 ;; their associated source files. These are described in section
1297 ;; (@> "Icicles Enhancements for Emacs Tags").
1299 ;; If you use `M-g' in the minibuffer to toggle option
1300 ;; `icicle-use-C-for-actions-flag', then you can use just `next'
1301 ;; instead of `C-next' to navigate when using any Icicles search
1303 ;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'").
1305 ;;(@* "Searching Text with Properties")
1306 ;; ** Searching Text with Properties **
1308 ;; Instead of providing a context regexp, for commands
1309 ;; `icicle-search-char-property', `icicle-search-overlay-property',
1310 ;; and `icicle-search-text-property' (`C-c "') ["] you provide a
1311 ;; character property (e.g. `face') and its value
1312 ;; (e.g. `font-lock-function-name-face'). All zones of text that
1313 ;; have that property with that value become the completion
1314 ;; candidates (search hits). As always, you can filter this set of
1315 ;; candidates by typing input in the minibuffer.
1317 ;; By a "character property" is meant either a text property or an
1318 ;; overlay property. `icicle-search-char-property' searches both
1319 ;; kinds of character property; `icicle-search-overlay-property'
1320 ;; searches only overlay properties; and
1321 ;; `icicle-search-text-property' (`C-c "' ["]) searches only text
1324 ;; For example, if you use `icicle-search-char-property' with a
1325 ;; `face' property value `highlight', then the text searched includes
1326 ;; text with that overlay value and text with that text-property
1327 ;; value. With a `face' property value of `font-lock-string-face',
1328 ;; you can browse or search doc strings, and so on.
1330 ;; If the property chosen is `face', then you can in fact choose
1331 ;; multiple faces, in multi-command fashion (e.g. `C-mouse-2'), and
1332 ;; the text that is searched has at least one of the faces you
1333 ;; choose. If you choose no face value (empty input), then the
1334 ;; target is text that has any face at all. The search hits are
1335 ;; zones of text that are distinguished by their `face' values.
1337 ;; As with other Icicles search commands, a prefix argument controls
1338 ;; whether these character-property commands search the current
1339 ;; buffer, selected bookmarks, selected files, or selected buffers.
1340 ;; However, keep in mind that, since in this case you are searching
1341 ;; character properties, you will find search hits only for buffers
1342 ;; that already have such properties, for example, buffers that have
1345 ;;(@* "Icicles Imenu")
1346 ;; ** Icicles Imenu **
1348 ;; Command `icicle-imenu', which is bound to `C-c =', is an Imenu
1349 ;; browser. It lets you use Icicles completion to navigate among or
1350 ;; search the content of definitions of functions, variables, macros,
1351 ;; keys, and so on in a programming language (any language that Imenu
1352 ;; handles). As always in Icicles, your current input (e.g. a
1353 ;; regexp) filters the set of available candidates. That is, you can
1354 ;; match against parts of an Imenu entry - any parts. That's
1355 ;; particularly useful if there are many entries in the Imenu menu;
1356 ;; you do not need to read/scan the whole list.
1358 ;; If you look at the definition of `icicle-imenu' you'll see that it
1359 ;; simply lets you choose an Imenu submenu (`Functions', `User
1360 ;; Options', and so on) that is appropriate for the current buffer
1361 ;; type, and then it calls `icicle-search', passing it the
1362 ;; appropriate Imenu regexp. You can similarly define your own
1363 ;; specialized search commands using `icicle-search' to browse regexp
1364 ;; matches. You get all of the features of `icicle-search' when you
1365 ;; do that. For example, `icicle-imenu' gives you these advantages
1366 ;; over a standard Imenu menu:
1368 ;; * You can restrict navigation (search) to a region.
1370 ;; * You can navigate (browse) among multiple entries, instead of
1371 ;; choosing them one by one from a menu.
1373 ;; * You can restrict the entries to browse using (regexp) pattern
1376 ;; * As for `icicle-search', you can search multiple bookmarks,
1377 ;; multiple buffers, or multiple files.
1379 ;;(@* "Type-Specific Imenu Commands")
1380 ;; *** Type-Specific Imenu Commands ***
1382 ;; In addition, Icicles provides specializations of `icicle-imenu',
1383 ;; to find only definitions of particular types:
1385 ;; `icicle-imenu-command', `icicle-imenu-face',
1386 ;; `icicle-imenu-key-explicit-map', `icicle-imenu-key-implicit-map',
1387 ;; `icicle-imenu-macro', `icicle-imenu-non-interactive-function',
1388 ;; `icicle-imenu-user-option', `icicle-imenu-variable'
1390 ;; All of these commands use only the Imenu regexps that match
1391 ;; entities of different types. Because these regexps were designed
1392 ;; (for Imenu) only to locate the start of a definition, they
1393 ;; generally do not match full definitions. This makes them OK for
1394 ;; use by an Icicles multi-command as a browser, to navigate among
1395 ;; definitions. But it does not make them useful for searching the
1396 ;; content of definitions.
1398 ;;(@* "Imenu Commands that Search Full Definitions")
1399 ;; *** Imenu Commands that Search Full Definitions ***
1401 ;; Icicles also provides a similar set of commands, with the same
1402 ;; names but with suffix `-full', which do use full definitions as
1403 ;; the completion candidates, so you can search those bodies. When
1404 ;; you only want to navigate, you will generally use the non `-full'
1405 ;; commands because the candidates are simpler. When you want to
1406 ;; search you will generally use the `-full' commands.
1408 ;; Be aware that "full" really means what it says only for
1409 ;; definitions in languages like Lisp. These commands in fact first
1410 ;; match the Imenu regexp, then use the text between the regexp match
1411 ;; beginning and one sexp forward. In the case of Lisp sexps, that
1412 ;; means they use the full sexp for the definition. But in the case
1413 ;; of other languages, such as C, the "full" definitions can in fact
1414 ;; be shorter than the simple regexp matches.
1417 ;;(@* "Icicles Imenu Combines Benefits of Imenu and Emacs Tags")
1418 ;; *** Icicles Imenu Combines Benefits of Imenu and Emacs Tags ***
1420 ;; * Imenu lets you navigate among definitions in a single buffer.
1422 ;; * Emacs tags let you navigate among definitions in multiple files,
1423 ;; but you must build and update the tags file that identifies the
1426 ;; Like Emacs tags, Icicles Imenu commands let you navigate among
1427 ;; definitions in multiple files - and also multiple bookmarks and
1428 ;; multiple non-file buffers. Like Imenu, you need not build a tags
1429 ;; file. Unlike Imenu, Icicles provides regexp completion that lets
1430 ;; you filter Imenu hits that you want to visit.
1432 ;; Another difference from Emacs tags, besides the need for a tags
1433 ;; file, is that, since Icicles locates definitions using Imenu
1434 ;; regexps, you can only navigate among definitions in buffers that
1435 ;; you are visiting. This is both an advantage and a disadvantage:
1436 ;; you can narrow the search to certain files, but you must know
1437 ;; which files to search. And if you want to search all files, then
1438 ;; you must open them all (e.g. by matching a project regexp),
1440 ;; The differences mean that Icicles Imenu commands do not provide a
1441 ;; substitute for Emacs tags; they provide some similar
1442 ;; functionality. They add another tool to your tool belt, handier
1443 ;; in some situations than using tags, and less useful in some other
1446 ;; See Also: (@> "Icicles Enhancements for Emacs Tags")
1448 ;;(@* "Compile/Grep Search")
1449 ;; ** Compile/Grep Search **
1451 ;; In a compilation-results buffer, such as `*Compilation*' or
1452 ;; `*grep*', you can use command `icicle-compilation-search', bound
1453 ;; to `C-c `', to search among the result set (search hits). This is
1454 ;; similar to `icicle-search', but when you use `C-RET', `C-mouse-2',
1455 ;; `C-down', `C-up', `C-next', `C-prior', `C-end', or `C-home', it
1456 ;; visits the source code that corresponds to the current line in the
1457 ;; compilation buffer. Just as for `icicle-search', you can narrow
1458 ;; the set of search contexts by typing a regexp.
1460 ;; Using `icicle-compilation-search' with `grep' gives you two levels
1461 ;; of regexp searching: 1) the `grep' regexp and 2) your current
1462 ;; input regexp. And you can of course use progressive completion
1463 ;; (`M-*') to add any number of additional levels. (And, starting
1464 ;; with Emacs 22, you can pipe to other `grep' commands in the same
1467 ;; In Emacs 22 and later, you can also replace search-hit text. You
1468 ;; can replace the entire grep regexp match or just the part of it
1469 ;; that matches your current input, depending on the value of option
1470 ;; `icicle-search-replace-whole-candidate-flag' (which you can toggle
1471 ;; with `M-_'). Replacement acts here just as it does for
1474 ;; You can also use a non-`grep' compilation buffer to perform search
1475 ;; and replace. Use it, for example, to correct errors in source
1478 ;; Icicles thus gives you several ways to perform search-and-replace
1479 ;; throughout multiple files: `grep'/compilation, `icicle-occur', and
1480 ;; `icicle-search'. The latter is of course not limited to
1481 ;; line-by-line search.
1483 ;; See Also: (@> "Search and Replace").
1485 ;;(@* "Input Reuse in Interactive Interpreter Modes")
1486 ;; ** Input Reuse in Interactive Interpreter Modes **
1488 ;; In an interactive interpreter mode such as `shell-mode' or
1489 ;; interactive Lisp mode, you can search for and reuse a previous
1490 ;; input, possibly editing it first. Command `icicle-comint-search',
1491 ;; bound to `C-c `', lets you use Icicles completion and cycling to
1492 ;; access your previous (shell or Lisp) inputs; it uses
1493 ;; `icicle-search', so it highlights your regexp input matches, and
1494 ;; so on. You can use `C-$' at any time to toggle removal of
1495 ;; duplicate past inputs as completion candidates; by default,
1496 ;; duplicates are removed.
1498 ;; Being a search command, however, `icicle-comint-search' has access
1499 ;; only to the commands that are visible in the buffer. It does not
1500 ;; use the `comint-input-ring', so it cannot, for instance, give you
1501 ;; access to commands used in a previous session, which might have
1502 ;; been recorded in a history file.
1504 ;; Another Icicles command, `icicle-comint-command', which is not a
1505 ;; search command, does use `comint-input-ring' and does give you
1506 ;; completion and cycling against previous inputs that might not have
1507 ;; come from the current session. It is bound to `C-c TAB' in
1508 ;; `comint-mode' and derived modes.
1510 ;;(@* "Define Your Own Icicles Search Commands")
1511 ;; ** Define Your Own Icicles Search Commands **
1513 ;; Function `icicle-search' is not only a useful user command; it is
1514 ;; also a framework for you to define your own Icicles search
1515 ;; commands. Consult the source code for the commands presented
1516 ;; above for models. And consult the doc string of `icicle-search'
1517 ;; for more information about calling it non-interactively. In
1518 ;; particular, note that:
1520 ;; * You can pass a functional argument instead of a regexp to
1521 ;; `icicle-search', and it will use that function to define the
1522 ;; search contexts. The function is passed, as arguments, the
1523 ;; buffer to search, the beginning and end of the search region in
1524 ;; that buffer, and any additional arguments that you pass to
1527 ;; * You can pass a predicate argument to `icicle-search', in
1528 ;; addition to passing a regexp, and the search contexts will be
1529 ;; only those regexp matches that also satisfy the predicate. The
1530 ;; predicate takes two arguments, the search-context string and a
1531 ;; marker at the end of the search context. For information about
1532 ;; this, consult the doc string for function
1533 ;; `icicle-search-regexp-scan'. For a model of using this feature,
1534 ;; see the code that defines command `icicle-imenu'.
1536 ;; By using your own function to define the search contexts, either
1537 ;; from scratch or by limiting regexp matches using a predicate, you
1538 ;; can perform semantic-based searching. That is, your search
1539 ;; command can use information besides syntax to define search hits.
1540 ;; For instance, commands `icicle-imenu-command' and
1541 ;; `icicle-imenu-non-interactive-function' use the semantic predicate
1542 ;; `commandp' to distinguish Emacs-Lisp commands from non-interactive
1547 ;; * (@> "Icicles Search Commands, Overview") for general information
1548 ;; about Icicles search and the commands `icicle-search' and
1551 ;; * (@> "Search and Replace") for information about replacing search
1552 ;; hits or parts of search hits.
1554 ;; * (@file :file-name "icicles-doc1.el" :to "Multi-Commands") for
1555 ;; information about using `C-RET', `C-mouse-2', `C-down', `C-up',
1556 ;; `C-next', `C-prior', `C-end', and `C-home'.
1558 ;; * (@file :file-name "icicles-doc1.el" :to "Progressive Completion")
1559 ;; for information about using any number of search regexps with
1560 ;; `M-*' and any number of search predicates with `M-&'.
1562 ;; * (@> "Icicles Info Enhancements") for information about using
1563 ;; Icicles with Info mode.
1565 ;;(@* "Icicles Bookmark Enhancements")
1567 ;; Icicles Bookmark Enhancements
1568 ;; -----------------------------
1570 ;; Many of the enhancements described in this section are available
1571 ;; only if you also use library `bookmark+.el' (which I recommend).
1572 ;; Bookmark+ is compatible with vanilla Emacs bookmarks across
1573 ;; multiple Emacs versions. It enhances the use of bookmarks in many
1574 ;; ways. The explanation here does not attempt to describe the
1575 ;; Bookmark+ enhancements; it describes only the Icicles features
1576 ;; that make use of them.
1578 ;; One of the main Bookmark+ enhancements is support for new bookmark
1579 ;; types. Icicles provides type-specific bookmark commands and
1580 ;; bookmark-candidate filtering.
1582 ;; In addition, when you complete the names of some kinds of objects,
1583 ;; you can use `C-x m' to choose objects of that type. For example,
1584 ;; when you use `icicle-dired' (`C-x d') to complete a directory
1585 ;; name, you can use `C-x m' to choose among your Dired bookmarks.
1586 ;; See (@file :file-name "icicles-doc1.el" :to "Accessing Saved Locations (Bookmarks) on the Fly").
1588 ;; Regardless of the bookmark type, another Bookmark+ feature that
1589 ;; Icicles takes advantage of is the fact that a bookmark (any
1590 ;; bookmark) can save not only a single position but a region, that
1591 ;; is, two positions. You can think of this as bookmarking, or
1592 ;; saving, regions. When you jump to a region bookmark, the region
1593 ;; is activated (if option `bmkp-use-region' is non-`nil').
1595 ;; These are the main Icicles bookmarking features:
1597 ;; * Tagging files (a la delicious) and jumping to tagged files
1598 ;; * Bookmarking the region and selecting a bookmarked region
1599 ;; * Setting a bookmark and jumping to a bookmark
1600 ;; * Searching the text of a bookmark's buffer or region
1602 ;; Each is described in a little more detail below. More generally,
1603 ;; however, the Bookmark+ doc is your friend. See these sections of
1604 ;; the Bookmark+ doc:
1606 ;; * (@file :file-name "bookmark+-doc.el" :to "Bookmark Tags")
1607 ;; * (@file :file-name "bookmark+-doc.el" :to "Autofile Bookmarks")
1608 ;; * (@file :file-name "bookmark+-doc.el" :to "Tag Commands and Keys")
1609 ;; * (@file :file-name "bookmark+-doc.el" :to "Tags: Sets of Bookmarks")
1610 ;; * (@file :file-name "bookmark+-doc.el" :to "Bookmark Tags Can Have Values")
1613 ;;(@* "Saving Regions and Selecting Them")
1614 ;; ** Saving Regions and Selecting Them **
1616 ;; Saving the region just means bookmarking it. As for any bookmark,
1617 ;; it must have a name. When you later jump to a region bookmark,
1618 ;; the region is activated (provided option `bmkp-use-region' is
1621 ;; Icicles gives you quick ways to save a region and select
1622 ;; (activate) a saved region. You can do both using `C-x C-x'.
1624 ;; * With no prefix arg, `C-x C-x' exchanges point and mark
1625 ;; (activating the region), as usual.
1627 ;; * With a plain prefix arg (`C-u'), `C-x C-x' jumps to a region
1628 ;; bookmark that you choose using completion, and activates it.
1630 ;; * With a numeric prefix arg, `C-x C-x' saves the region. If the
1631 ;; prefix arg is negative, then you are prompted for the name to
1632 ;; use. Otherwise, the bookmark is named automatically using the
1633 ;; buffer name plus ": " plus the first
1634 ;; `icicle-bookmark-name-length-max' characters of the region text.
1635 ;; (Newline characters are changed to spaces for the name.)
1637 ;; So if (a) you are visiting buffer `foo', (b) the region text
1638 ;; starts with "Arise, you wretched of the earth! For justice
1639 ;; thunders condemnation: A better world's in birth!", and (c) the
1640 ;; value of option `icicle-bookmark-name-length-max' is 15, then
1641 ;; `C-9 C-x C-x' sets the region bookmark named `foo: Arise, you'.
1643 ;;(@* "Setting a Bookmark and Jumping to a Bookmark")
1644 ;; ** Setting a Bookmark and Jumping to a Bookmark **
1646 ;; Just as `C-x C-x' lets you either set or jump to a region
1647 ;; bookmark, so `C-x r m' lets you either set or jump to any
1648 ;; bookmark. `C-x r m' is the vanilla Emacs key for setting a
1649 ;; bookmark. In Icicle mode it is bound by default to command
1650 ;; `icicle-bookmark-cmd'. (By default, whatever keys are normally
1651 ;; bound to `bookmark-set' are remapped in Icicle mode to
1652 ;; `icicle-bookmark-cmd'.)
1654 ;; * With no prefix arg or a plain prefix arg (`C-u'), `C-x r m' acts
1655 ;; like `icicle-bookmark-set'. This is similar to `bookmark-set',
1656 ;; but if you use Bookmark+ then you can use (lax) completion,
1657 ;; choosing from existing bookmarks for the same buffer. This
1658 ;; makes it easy to update a nearby bookmark.
1660 ;; The same completion enhancements are available as for bookmark
1661 ;; jumping - see (@> "Jumping to a Bookmark"), below.
1663 ;; * With a negative prefix arg, `C-x r m' jumps to a bookmark (with
1664 ;; completion). See (@> "Jumping to a Bookmark"), below.
1666 ;; * With a non-negative prefix arg, `C-x r m' sets a bookmark,
1667 ;; automatically naming it. This is like the automatic naming for
1668 ;; a region bookmark, except that instead of including a prefix of
1669 ;; the region text, the name includes text from the current line
1670 ;; that starts at point.
1672 ;; So if the cursor in buffer `foo' is on the `y' in a line with
1673 ;; the text "Arise, you wretched of the earth!", then the bookmark
1674 ;; will automatically be named `foo: you wretch'.
1676 ;; If the prefix argument is 0, then the new bookmark does not
1677 ;; overwrite any existing bookmark with the same name.
1679 ;;(@* "Jumping to a Bookmark")
1680 ;; ** Jumping to a Bookmark **
1682 ;; Icicles commands that jump to a bookmark are multi-commands: you
1683 ;; can use them to jump to any number of bookmarks in a single
1684 ;; invocation. Each jump command acts as a bookmark browser.
1686 ;; As with most Icicles tripping commands, after you jump to a
1687 ;; (non-region) bookmark, the cursor position is highlighted using
1688 ;; cross hairs, if you also use library `crosshairs.el'.
1690 ;; Bookmark names are highlighted in buffer `*Completions*' to
1691 ;; indicate the bookmark type. The faces used are those defined by
1694 ;; If option `icicle-show-multi-completion-flag' is non-`nil', then
1695 ;; each completion candidate is a multi-completion, with up to three
1696 ;; parts: the bookmark name, the bookmark file or buffer name, and
1697 ;; any (del.icio.us-style) tags the bookmark has. You can toggle
1698 ;; option `icicle-show-multi-completion-flag' (for the next command)
1699 ;; using `M-m' during completion.
1701 ;; When using multi-completion candidates, you can match any of the
1702 ;; multi-completion parts. For example, you can match all bookmarks
1703 ;; that have any tags by typing this when choosing a bookmark:
1705 ;; C-M-j . * C-M-j S-TAB
1707 ;; Or match all bookmarks whose names match `P42' and whose tags
1710 ;; P 4 2 . * C-M-j . * C-M-j . * b l u e S-TAB
1712 ;; (Each `C-M-j' inserts `^G\n', which is `icicle-list-join-string'.)
1714 ;; `C-M-RET' shows detailed info about the current bookmark
1715 ;; completion candidate. `C-u C-M-RET' shows the complete, internal
1716 ;; info for the bookmark. Likewise, for the other candidate help
1717 ;; keys: `C-M-down' etc. And the mode line always shows summary
1718 ;; info about the current bookmark.
1720 ;; During bookmark completion you can sort the candidates in various
1721 ;; bookmark-specific ways:
1723 ;; * By the current (latest) `*Bookmark List*' order
1724 ;; * By bookmark name
1725 ;; * By last access as a bookmark (date + time)
1726 ;; * By bookmark visit frequency (number of times visited)
1727 ;; * By last buffer or file access (date + time)
1728 ;; * With marked bookmarks before unmarked (in `*Bookmark List*')
1730 ;; * By (local) file type
1731 ;; * By (local) file size
1732 ;; * By last (local) file access (date + time)
1733 ;; * By last (local) file update (date + time)
1734 ;; * By Info location (manual and node)
1737 ;; * By bookmark type
1739 ;; The most general Icicles jump commands are `icicle-bookmark' and
1740 ;; `icicle-bookmark-other-window'. In Icicle mode these are bound to
1741 ;; whatever `bookmark-jump' and `bookmark-jump-other-window' are
1742 ;; normally bound to. If you use Bookmark+, the default bindings are
1743 ;; `C-x j j' and `C-x 4 j j', respectively.
1745 ;; When you use these commands, you can narrow the completion
1746 ;; candidates to bookmarks of a specific type using these keys:
1748 ;; `C-M-b' - non-file (buffer) bookmarks
1749 ;; `C-M-B' - bookmark-list bookmarks
1750 ;; `C-M-d' - Dired bookmarks
1751 ;; `C-M-f' - file bookmarks
1752 ;; `C-M-F' - local-file bookmarks
1753 ;; `C-M-g' - Gnus bookmarks
1754 ;; `C-M-I' - Info bookmarks
1755 ;; `C-M-K' - desktop bookmarks
1756 ;; `C-M-m' - `man' pages
1757 ;; `C-M-r' - bookmarks with regions
1758 ;; `C-M-u' - URL bookmarks
1759 ;; `C-M-w' - W3M (URL) bookmarks
1760 ;; `C-M-@' - remote-file bookmarks
1761 ;; `C-M-= b' - bookmarks for a specific buffer
1762 ;; `C-M-= f' - bookmarks for a specific file
1763 ;; `C-M-= .' - bookmarks for the current buffer
1765 ;; In addition, there are individual jump commands for bookmarks of
1766 ;; each of each type, and these commands are bound by default to keys
1767 ;; with the prefix `C-x 4 j' that use the same mnemonic characters as
1768 ;; for narrowing. For example, `icicle-bookmark-info-other-window'
1769 ;; is bound to `C-x 4 j i'.
1771 ;; Commands `icicle-bookmark' and `icicle-bookmark-other-window' can
1772 ;; use a cache for the set of available bookmarks. This improves
1773 ;; performance, especially if you have a lot of bookmarks. The
1774 ;; downside is that the list of completion candidates is not
1775 ;; automatically updated when you add new bookmarks.
1777 ;; By default, this caching is off, so the set of possible bookmark
1778 ;; candidates is always up-to-date. You can turn on this caching by
1779 ;; setting option `icicle-bookmark-refresh-cache-flag' to `nil'.
1781 ;; Alternatively, you can use a prefix argument to reverse the effect
1782 ;; of this option. If you have a lot of bookmarks then I recommend
1783 ;; that you customize the option to `nil' and just update it
1784 ;; occasionally by using `C-u' for bookmark completion. That will
1785 ;; temporarily turn off caching so that the current jump command
1786 ;; refreshes (updates) the cache. The default value of the option is
1787 ;; `t' only to avoid confusion for new users.
1789 ;; The bookmarks cache is also used for searching bookmarks (see
1790 ;; next). The type-specific bookmark jump commands
1791 ;; (e.g. `icicle-bookmark-info-other-window') do not use the cache,
1792 ;; since they typically use a smaller number of candidates. And the
1793 ;; cache is automatically updated whenever you use `S-delete' to
1794 ;; delete a candidate bookmark.
1798 ;; * (@file :file-name "icicles-doc1.el" :to "Icicles Tripping")
1800 ;;(@* "Searching Bookmarked Objects")
1801 ;; ** Searching Bookmarked Objects **
1803 ;; Icicles search (and replace) lets you search across multiple
1804 ;; buffers, files, or bookmarks. This is true for nearly all Icicles
1805 ;; search commands. You use a plain prefix argument to specify
1806 ;; bookmark searching. For command `icicle-search' itself (`C-u C-c
1807 ;; `'), you can alternatively use the specific command
1808 ;; `icicle-search-bookmarks-together'.
1810 ;; When you do this you first choose the bookmarks to search, using
1811 ;; completion. Use `C-RET' and similar multi-command actions to
1812 ;; choose (use `RET' for the final choice). Once you have chosen the
1813 ;; bookmarks, you type a search pattern to narrow the set of
1816 ;; (Multi-command `icicle-bookmark-list' similarly lets you choose
1817 ;; bookmark names. It returns them as a Lisp list of strings.)
1819 ;; When you search the text of a region bookmark, the search is
1820 ;; limited to the region.
1822 ;; In addition to using `C-u' with the general Icicles search
1823 ;; commands, you can use the following Icicles search commands that
1824 ;; are specific to bookmarks:
1826 ;; * icicle-search-bookmark
1827 ;; * icicle-search-autofile-bookmark
1828 ;; * icicle-search-bookmark-list-bookmark
1829 ;; * icicle-search-desktop-bookmark
1830 ;; * icicle-search-dired-bookmark
1831 ;; * icicle-search-file-bookmark
1832 ;; * icicle-search-gnus-bookmark
1833 ;; * icicle-search-info-bookmark
1834 ;; * icicle-search-local-file-bookmark
1835 ;; * icicle-search-man-bookmark
1836 ;; * icicle-search-non-file-bookmark
1837 ;; * icicle-search-region-bookmark
1838 ;; * icicle-search-remote-file-bookmark
1839 ;; * icicle-search-specific-buffers-bookmark
1840 ;; * icicle-search-specific-files-bookmark
1841 ;; * icicle-search-this-buffer-bookmark
1842 ;; * icicle-search-url-bookmark
1843 ;; * icicle-search-w3m-bookmark
1844 ;; * icicle-search-all-tags-bookmark
1845 ;; * icicle-search-all-tags-regexp-bookmark
1846 ;; * icicle-search-some-tags-bookmark
1847 ;; * icicle-search-some-tags-regexp-bookmark
1849 ;; `icicle-search-bookmark' is a general command; the others are each
1850 ;; specific to a certain kind of bookmark candidate, and they need
1851 ;; library `bookmark+.el'. The last four let you search bookmarks
1852 ;; that have a certain set of tags.
1854 ;; All of these commands act the same way. They are multi-commands,
1855 ;; so you can use them to search multiple bookmarks. But unlike
1856 ;; `icicle-search-bookmarks-together' (`C-u C-c `'), you do not first
1857 ;; choose all of the bookmarks and then search them together.
1858 ;; Instead, you search them one at a time.
1860 ;; `icicle-search-bookmark' is flexible, letting you specify any set
1861 ;; of bookmarks to use as candidates. The candidates are the
1862 ;; bookmarks last shown in the `*Bookmark List*' display (list
1863 ;; `bmkp-sorted-alist', to be precise).
1865 ;; You can use the Bookmark+ features of `*Bookmark List*' to limit
1866 ;; the candidates to bookmarks of a certain type (e.g., only
1867 ;; autofiles, using `A S'), bookmarks with certain tags (e.g., only
1868 ;; those with tags matching a regexp using `T m %' followed by `>'),
1869 ;; and so on. Whatever set of bookmarks are shown (or were last
1870 ;; shown) in `*Bookmark List*' are the bookmarks to be searched.
1874 ;; * (@> "Icicles Search Commands, Overview") for information about
1875 ;; command `icicle-search'.
1876 ;; * (@> "Jumping to a Bookmark") for information about bookmark
1877 ;; caching. Caching is also used for bookmark searching.
1878 ;; * (@> "Support for Projects")
1880 ;;(@* "Icicles Enhancements for Emacs Tags")
1882 ;; Icicles Enhancements for Emacs Tags
1883 ;; -----------------------------------
1885 ;; In Emacs and Icicles, the word "tag" is used in multiple ways.
1886 ;; This section is about tags as identifiers of source-code
1887 ;; definitions. Emacs uses tags files, typically named `TAGS', to
1888 ;; index these definition locations.
1890 ;; What constitutes a "definition" is determined by the content of
1891 ;; the tags file. Typically, definition recognition is available for
1892 ;; programming languages, but in fact a tags table can record any
1893 ;; text at all as a definition. That is, if you create your own tags
1894 ;; table, you can use the Emacs tags feature to navigate among any
1895 ;; "definitions" of your own choosing.
1897 ;; If you use `M-g' in the minibuffer to toggle option
1898 ;; `icicle-use-C-for-actions-flag', then you can use just `next'
1899 ;; instead of `C-next' to navigate when using any of the Icicles tags
1900 ;; browsing commands described here. See
1901 ;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'").
1905 ;; * (@> "Support for Projects")
1906 ;; * (@file :file-name "icicles-doc1.el" :to "File-Name Input and Locating Files Anywhere")
1908 ;;(@* "`icicle-find-tag': Find Tags in All Tags Tables")
1909 ;; ** `icicle-find-tag': Find Tags in All Tags Tables **
1911 ;; In vanilla Emacs, you use commands such as `find-tag' (`M-.') to
1912 ;; find a tag, `tags-loop-continue' (`M-,') to find another matching
1913 ;; tag, `tags-apropos' to list all tags that match a regexp, and
1914 ;; `list-tags' to show all tags (definitions) in a given source file.
1916 ;; In Icicles, you can use multi-command `icicle-find-tag', bound to
1917 ;; `M-.' in Icicle mode, to do all of this. It is similar to the
1918 ;; Icicles search commands. It is a general tags browser, just as
1919 ;; `icicle-imenu' is an Imenu browser. Being a multicommand, you can
1920 ;; visit any number of tags, in any order, in a single `M-.'
1923 ;; With `icicle-find-tag', you enter (using `RET') a regexp to match
1924 ;; the tags you want to visit. By default, all tags in all tags
1925 ;; files are searched, and the matches become completion candidates
1926 ;; (which you can of course match further by typing another pattern).
1927 ;; As always, you can use progressive completion, chip away the
1928 ;; non-elephant, and so on. Just as with Icicles search commands,
1929 ;; you use `C-RET', `C-mouse-2', `C-next', and so on, to visit the
1930 ;; search hits. You can use `M-*' (`icicle-pop-mark') to return to
1931 ;; the place you invoked `M-.'.
1933 ;; By default, the completion candidates are multi-completions: the
1934 ;; source file name is included. This is an important aid, because
1935 ;; there can be similar, or even identical, tags in different source
1936 ;; files. Your current input can of course filter the source-file
1937 ;; name also, excluding certain files from the search.
1939 ;; A prefix argument changes the default behavior, as follows:
1941 ;; * If non-negative (>= 0), then only the current tag table is used,
1942 ;; instead of all tag tables.
1944 ;; * If non-positive (<= 0), then the source file name is not part of
1945 ;; the completion candidate; only the tag itself is used.
1949 ;; * (@> "Icicles Search Commands, Overview") for general information
1950 ;; about Icicles search commands.
1952 ;; * (@file :file-name "icicles-doc1.el" :to "Nutshell View of Icicles")
1953 ;; for information about progressive completion and chipping away
1954 ;; the non-elephant.
1956 ;;(@* "`icicle-find-first-tag': Find First Tag in Current Table")
1957 ;; ** `icicle-find-first-tag': Find First Tag in Current Table **
1959 ;; Sometimes you do not need the full power and flexibility of
1960 ;; `icicle-find-tag'. If you just want to find the first tag among
1961 ;; several duplicates that match your input, and you just want to use
1962 ;; the current tags table, then you can use `icicle-find-first-tag'
1963 ;; or `icicle-find-first-tag-other-window'. These commands are like
1964 ;; vanilla `find-tag', but they are multi-commands, so you can visit
1965 ;; any number of tags in one invocation. Unlike `find-tag', however,
1966 ;; you cannot follow up to find another tag that matches using `M-,'.
1968 ;;(@* "`icicle-tags-search': Search and Replace Using Tags")
1969 ;; ** `icicle-tags-search': Search and Replace Using Tags **
1971 ;; In vanilla Emacs, you use commands `tags-search',
1972 ;; `tags-query-replace', and `tags-loop-continue' (`M-,') to search
1973 ;; and replace text in source files whose definitions are indexed in
1976 ;; In Icicles, you can use multi-command `icicle-tags-search' to
1977 ;; search and replace. It is in fact just command `icicle-search'
1978 ;; applied to the relevant source files.
1980 ;; See Also (@> "Icicles Search Commands, Overview") for information
1981 ;; about `icicle-search.
1983 ;;(@* "Icicles Shell-Command Enhancements")
1985 ;; Icicles Shell-Command Enhancements
1986 ;; ----------------------------------
1988 ;; Icicles provides completion support for shell commands in these
1991 ;; * In Shell mode and related modes, it enhances completion of
1992 ;; commands, previous inputs (commands plus their switches and
1993 ;; arguments), file names, and environment variables.
1994 ;; See (@> "Completion in Comint Modes").
1996 ;; * In any buffer, it provides Icicles completion for `M-!' and
1997 ;; `M-|'. This is an optional feature that is not enabled by
2000 ;; * In Dired mode, it provides Icicles completion for `!', and `&'.
2001 ;; See (@> "Shell Commands on Marked Files"). This is an optional
2002 ;; feature that is not enabled by default.
2004 ;; This section describes the optional Icicles completion available
2005 ;; for `M-!' and `M-|'. It applies also to completion for `!', and
2006 ;; `&' in Dired (but those have additional enhancements).
2008 ;; In vanilla Emacs, when you enter a shell command at the prompt for
2009 ;; `M-!' or `M-|', no completion is available for Emacs prior to
2010 ;; Emacs 23. In Emacs 23, no completion is available for empty
2011 ;; input, and non-empty input is completed only to a shell command
2012 ;; that is in your search path.
2014 ;; In Icicle mode, `M-!' and `M-|' can, like in vanilla Emacs 23,
2015 ;; complete using commands in your search path. This depends on the
2016 ;; the value of option `icicle-guess-commands-in-path' (see below).
2018 ;;(@* "Shell Command Completion as File-Name Completion")
2019 ;; ** Shell Command Completion as File-Name Completion **
2021 ;; The most significant thing about Icicles completion for reading a
2022 ;; shell command is that it is in fact *file-name* completion.
2023 ;; Reading a shell command means, first, reading a file name. This
2024 ;; is unexpected, to say the least.
2026 ;; Because of this unusual behavior, this feature is optional and is
2027 ;; not enabled by default. To enable it, customize option
2028 ;; `icicle-functions-to-redefine' to add the shell-related functions
2029 ;; `dired-read-shell-command' and `read-shell-command'. If you do
2030 ;; that, then Icicle mode will substitute Icicles functions for these
2031 ;; standard functions and you will get the Icicles completion
2034 ;; A shell command is itself an executable file, either a binary
2035 ;; program or a script. That's not so shocking. But since Icicles
2036 ;; uses file-name completion for your entire shell-command input,
2037 ;; including any switches (options) and command arguments, all of
2038 ;; that input is interpreted by `read-file-name' as a file name,
2039 ;; before it gets passed on to the shell.
2041 ;; The reason for providing file-name completion for a shell command
2042 ;; is to let you easily invoke a program no matter where it resides,
2043 ;; whether or not its directory is in your search path. You can use
2044 ;; completion to navigate to the command's location.
2046 ;; Icicles shell-command completion is lax, so you can enter any
2047 ;; command you want, not just a file-name completion candidate. And
2048 ;; you can edit the completed input before hitting `RET', to add
2049 ;; command switches (options) and arguments. The overall input
2050 ;; string is taken as a (pseudo) file name, but it is then passed to
2051 ;; the shell for execution.
2053 ;;(@* "Gotcha: `$' in Shell Commands")
2054 ;; ** Gotcha: `$' in Shell Commands **
2056 ;; There is a gotcha, however, regarding `$' and file-name input:
2058 ;; When you hit `RET' to accept the input, `read-file-name' finishes
2059 ;; its job, as always, by trying to expand any environment variables
2060 ;; in the string. Usually this is what you want, and it presents no
2061 ;; problem. But in the context of a shell another `$' syntax is also
2062 ;; used. For example, `$1' typically means the first argument or
2063 ;; first field; it does not mean a variable named `1'.
2065 ;; `read-file-name' knows nothing about this different `$' syntax,
2066 ;; and it systematically calls `substitute-in-file-name' to expand
2067 ;; any environment variables in the file name you enter (when you hit
2068 ;; `RET'). It interprets `$1' the same way it inteprets `$PATH',
2069 ;; treating `1' as an (unknown) environment variable. This is not
2070 ;; what you want it to do. If you input `awk '{print $1}' Emacs
2071 ;; raises this error:
2073 ;; Substituting nonexistent environment variable "1"
2075 ;; What can you do about this? Three possible approaches:
2077 ;; * Do not use this Icicles feature at all. The feature is turned
2080 ;; * You can escape a dollar sign by doubling it: use `$$' instead of
2081 ;; `$' when you want to pass a `$' to the shell and not let
2082 ;; `read-file-name' try to interpret it in terms of an environment
2085 ;; * You can turn off Icicle mode temporarily whenever you use a
2086 ;; complex command that involves `$': `M-x icy-mode'.
2088 ;;(@* "Known Shell Commands as Proxy Candidates")
2089 ;; ** Known Shell Commands as Proxy Candidates **
2091 ;; If you do turn on Icicles file-name completion for reading shell
2092 ;; commands, then extra, known shell commands are also made available
2093 ;; as proxy completion candidates, provided that option
2094 ;; `icicle-guess-commands-in-path' is non-`nil' (it is `nil' by
2095 ;; default). These extra candidates are the names of all executable
2096 ;; files (or of all files, if `shell-completion-execonly' is `nil')
2097 ;; in your search path.
2099 ;; The fact that these are Icicles proxy candidates means that they
2100 ;; are available regardless of the current default-directory - they
2101 ;; are not in fact treated as file-name candidates, even though they
2102 ;; are available during file-name completion. You can easily
2103 ;; recognize Icicles proxy candidates in buffer `*Completions*': they
2104 ;; have face `icicle-proxy-candidates'. See
2105 ;; (@file :file-name "icicles-doc1.el" :to "Completions Display").
2107 ;; If `icicle-guess-commands-in-path' is non-`nil', the list of
2108 ;; search-path candidate commands is computed once and cached as the
2109 ;; value of option `icicle-shell-command-candidates-cache'. The
2110 ;; particular non-`nil' value of `icicle-guess-commands-in-path'
2111 ;; determines when the cache is filled.
2113 ;; If the value of `icicle-guess-commands-in-path' is `first-use',
2114 ;; the cache is filled the first time you use it, and each time you
2115 ;; turn on Icicle mode it is updated. If the value of
2116 ;; `icicle-guess-commands-in-path' is `load', then the cache is
2117 ;; instead filled each time you load Icicles.
2119 ;; Regardless of the non-`nil' value of
2120 ;; `icicle-guess-commands-in-path', if you save
2121 ;; `icicle-shell-command-candidates-cache', then that value is used
2122 ;; in future sessions (no delay for searching your path).
2124 ;; If your environment changes, you can use command
2125 ;; `icicle-recompute-shell-command-candidates' to update the cached
2126 ;; list at any time. With a prefix argument, the updated value is
2127 ;; saved persistently.
2129 ;; In addition to the extra candidates computed by searching your
2130 ;; search path, in contexts such as Dired where target (e.g. marked)
2131 ;; files for the shell command are known, the extra candidates
2132 ;; include additional commands (possibly including switches) that
2133 ;; Icicles can guess might be appropriate for the target files.
2134 ;; See (@> "Shell Commands on Marked Files").
2136 ;; During Icicles shell-command completion, help is available for
2137 ;; individual candidates, using `C-M-RET', `C-M-mouse-2', and so on.
2138 ;; For an extra candidate, help is provided for the command by the
2139 ;; `apropos' shell command (if available). For a file-name
2140 ;; candidate, help shows the file's properties. See
2141 ;; (@file :file-name "icicles-doc1.el" :to "Get Help on Candidates").
2145 ;; * After you have typed or completed the shell command per se
2146 ;; (e.g. a file name or search-path command), you can use `C-M-S-f'
2147 ;; (file-name completion on demand) to complete (relative) file
2148 ;; names to insert as shell-command arguments as part of the
2149 ;; command line to submit to the shell. See
2150 ;; (@file :file-name "icicles-doc2.el" :to "Completion On Demand").
2152 ;; * You can use `M-o' anytime in the minibuffer to complete against
2153 ;; a previous input. This means that if you have previously
2154 ;; entered some complex shell command (e.g. with various switches
2155 ;; or arguments), then you can use `M-o' to retrieve it for reuse
2156 ;; (possibly editing it). See
2157 ;; (@file :file-name "icicles-doc2.el" :to "Using Completion to Insert Previous Inputs: `M-o'")
2159 ;;(@* "Icicles Dired Enhancements")
2161 ;; Icicles Dired Enhancements
2162 ;; --------------------------
2164 ;; Icicles can help with Dired in these ways:
2166 ;; * You can use Icicles search-and-replace on the marked files.
2168 ;; * You can save marked file names as completion candidates for
2171 ;; * You can open Dired on saved file names, that is, names that you
2172 ;; previously saved as a completion candidates set or as an Emacs
2173 ;; fileset. It does not matter how the file names were saved or
2174 ;; which directories the files are in. The set of saved file names
2175 ;; can be persistent or just for the current Emacs session.
2177 ;; * You can use file-name completion when you use `!' or `&' to
2178 ;; execute a shell command. This is an optional feature that is
2179 ;; not enabled by default. See also (@> "Icicles Shell-Command Enhancements").
2181 ;;(@* "Search-and-Replace Marked Files")
2182 ;; ** Search-and-Replace Marked Files **
2184 ;; In Dired, `A' searches the marked files using a regexp, and `Q'
2185 ;; launches `query-replace-regexp' on them. But suppose that you
2186 ;; want to change only a few occurrences in each file, perhaps among
2187 ;; the first occurrences. Using `Q', you are forced to review each
2188 ;; search hit in turn - all of them; you cannot simply skip the rest
2189 ;; in one file and continue with the next file.
2191 ;; [I suggested that this feature be added to Emacs, and it has been
2192 ;; added in Emacs 23: you can now skip to the next file.]
2194 ;; One workaround is to use `M->' to go to the end of a file, and
2195 ;; then `M-,' to resume query-replace. Or you can quit the command
2196 ;; altogether, unmark the file you're finished searching, and then
2197 ;; hit `Q' again, but that's not very convenient. A similar problem
2198 ;; applies to searching using `A'.
2200 ;; In Dired with Icicles, you can use `M-s i'
2201 ;; (`icicle-search-dired-marked') to search the files and possibly
2202 ;; replace search hits. This runs `icicle-search', so you have
2203 ;; available all of its features, including accessing search hits
2204 ;; directly, in any order. To skip a whole file, just match its name
2205 ;; with your minibuffer input and then use `C-~' to remove all of its
2206 ;; occurrences from the set of hits.
2208 ;; Note: You can similarly use `M-s i' in Ibuffer or Buffer Menu to
2209 ;; search all marked buffers using Icicles search.
2211 ;;(@* "Save Marked Files as Completion Candidates")
2212 ;; ** Save Marked Files as Completion Candidates **
2214 ;; In Dired with Icicles, you can use `C-M->'
2215 ;; (`icicle-dired-save-marked') to save the marked file names as a
2216 ;; set of completion candidates, for reuse later (e.g., using
2217 ;; `C-M-<'). Similarly, you can use `C->' to add the marked files to
2218 ;; an existing saved set of candidates.
2220 ;; These bindings act similarly to `C-M->' and `C->' in the
2221 ;; minibuffer: a prefix argument controls whether you save candidates
2222 ;; to a variable or a cache file. Also, `C-M-}' saves to a variable
2223 ;; you name, and `C-}' saves to a cache file - see
2224 ;; (@* "Marked Files as a Project"), below.
2226 ;; You can use such a saved set of file names as candidates during
2227 ;; file-name completion. They are saved as absolute names,
2228 ;; which means you can use them with, say, `C-u C-x C-f'. See
2229 ;; (@file :file-name "icicles-doc1.el" :to "Absolute File Names and Different Directories").
2231 ;;(@* "Open Dired for a Set of File Names")
2232 ;; ** Open Dired for a Set of File Names **
2234 ;; In Dired with Icicles you can use `C-M-<'
2235 ;; (`icicle-dired-chosen-files-other-window') to open Dired for a set
2236 ;; of file or directory names that you choose interactively or that
2237 ;; you have previously saved (persistently or not) as completion
2238 ;; candidates or as an Emacs fileset.
2240 ;; For example, this opens Dired on all files whose names match the
2241 ;; regexp `.*foo.*bar' (the initial `.*' is implicit):
2243 ;; C-M-< foo.*bar S-TAB C-! C-g
2245 ;; The Dired buffer that is created is named `Icy File Set' (suffixed
2246 ;; with <1>, <2>, etc. as needed), and it contains only the chosen
2249 ;; The file names are checked to be sure they reference existing
2250 ;; files. If any of the names are relative names, those files are
2251 ;; checked for existence in the Dired directory. If you use a prefix
2252 ;; argument, then you are prompted for the directory to use.
2254 ;;(@* "Marked Files as a Project")
2255 ;; ** Marked Files as a Project **
2257 ;; Just as `C-}' in the minibuffer is a shortcut for `C-u C-M->',
2258 ;; which saves the current set of completion candidates persistently,
2259 ;; so `C-}' in Dired saves the marked file names in a cache file or,
2260 ;; with a prefix arg, an Emacs fileset. Similarly, just as `C-{' in
2261 ;; the minibuffer is a shortcut for `C-u C-M-<', which retrieves
2262 ;; candidates from a persistent set, so `C-{' in Dired retrieves a
2263 ;; persistent set of file names and opens them in a separate Dired
2266 ;; You can think of such persistent file-name sets as projects.
2267 ;; `C-}' is bound to command `icicle-dired-save-marked-as-project'
2268 ;; (aka `icicle-dired-save-marked-persistently'). `C-{' is bound to
2269 ;; command `icicle-dired-project-other-window'.
2271 ;; Again, you can use such a project as a candidate set for file-name
2272 ;; completion at any time. In addition, `C-}' and `C-{' can be handy
2273 ;; in Dired for working with projects even without using completion.
2274 ;; The files in a project can be distributed among any directories
2275 ;; anywhere. This gives you an easy way to open Dired on just the
2276 ;; files you want and operate on them there.
2278 ;; And while in a project in Dired you can use `C-M-<' to mark a
2279 ;; project subset to work on, and then use `C-M->' to operate on that
2280 ;; subset using Icicles completion. And you can have any number of
2281 ;; projects - you access each by its name (with completion) and need
2282 ;; not remember its cache file name.
2284 ;;(@* "Shell Commands on Marked Files")
2285 ;; ** Shell Commands on Marked Files **
2287 ;; This is an optional feature that is not enabled by default. See
2288 ;; also (@> "Icicles Shell-Command Enhancements").
2290 ;; In Icicle mode, `!' and `&' in Dired let you complete a shell
2291 ;; command. You can optionally use Icicles file-name completion for
2292 ;; the shell command, by customizing option
2293 ;; `icicle-functions-to-redefine' to add the shell-related functions
2294 ;; `dired-read-shell-command' and `read-shell-command'.
2296 ;; If you do that, then Icicle mode will substitute Icicles functions
2297 ;; for these standard functions and you will get the Icicles
2298 ;; completion described here. This is the same optional program-file
2299 ;; completion that is available anywhere when a shell command is read
2300 ;; (see (@> "Icicles Shell-Command Enhancements")), but in Dired the
2301 ;; extra, proxy candidates include commands that Icicles thinks might
2302 ;; be particularly appropriate for the marked files.
2304 ;; These proxy candidates are not necessarily only command names.
2305 ;; They can include switches (options) that specialize a command.
2306 ;; For example, if a PDF file (*.pdf) is marked in Dired, the
2307 ;; completion candidates might include `gv -safer', `pdftotext ? -',
2308 ;; and `xpdf'. The first two of these are not just command names
2309 ;; (`-safer' is a command switch).
2311 ;; Starting with Emacs 23, Icicles uses both of the following methods
2312 ;; to guess extra (proxy) candidates that are file type-specific:
2314 ;; * MIME-type associations
2316 ;; * The rules defined by user option `dired-guess-shell-alist-user'
2317 ;; and variable `dired-guess-shell-alist-default' (provided you use
2318 ;; Dired X, that is, standard library `dired-x.el')
2320 ;; Prior to Emacs 23, MIME types are not used. In the example of a
2321 ;; PDF file, candidates `gv -safer' and `pdftotext ? -' are provided
2322 ;; by MIME-type associations, and candidate `xpdf' is provided by the
2323 ;; Dired X rules. Note that you can customize the rules.
2325 ;; Any candidates that are specific to the marked files are Icicles
2326 ;; proxy candidates - see
2327 ;; (@file :file-name "icicles-doc1.el" :to "Completions Display").
2328 ;; These are available regardless of the current default-directory.
2329 ;; They are not treated as file-name candidates, even though they are
2330 ;; available during file-name completion. Icicles proxy candidates
2331 ;; have face `icicle-proxy-candidates' in buffer `*Completions*'.
2333 ;; Again, everything that is true for shell-command completion
2334 ;; elsewhere is also true for shell-command completion in Dired. See
2335 ;; (@> "Icicles Shell-Command Enhancements"). This includes adding
2336 ;; all commands from your search path as proxy candidates if option
2337 ;; `icicle-guess-commands-in-path' is non-`nil', and providing help
2338 ;; on individual candidates (shell commands or files) during
2344 ;; * (@> "Icicles Shell-Command Enhancements") for more information
2345 ;; about shell-command completion
2347 ;; * (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates")
2348 ;; for information about saved completion candidates
2350 ;; * (@file :file-name "icicles-doc1.el" :to "Chip Away the Non-Elephant")
2351 ;; for the use of `C-~' to remove matching candidates
2353 ;; * (@> "Icicles Search Commands, Overview") for information about
2356 ;; * (@> "Search and Replace") for how to replace selected search hits
2358 ;; * (@file :file-name "icicles-doc1.el" :to "Persistent Sets of Completion Candidates")
2359 ;; for more information about using persistent sets
2361 ;; * (@> "Support for Projects") for more information about working
2364 ;; * Library `dired+.el', which has related features such as `C-M-*'
2365 ;; to open Dired on just the marked files and `M-g' to `grep' just
2366 ;; the marked files.
2368 ;;(@* "Icicles Info Enhancements")
2370 ;; Icicles Info Enhancements
2371 ;; -------------------------
2373 ;; Icicles can help with Info in these ways:
2375 ;; * Icicles completion is available for any input.
2377 ;; * You can use `icicle-search' on part or all of a manual, if you
2378 ;; flatten it first with `Info-merge-subnodes' .
2380 ;;(@* "Icicles Completion for Info")
2381 ;; ** Icicles Completion for Info **
2383 ;; Whenever completion is available for Info commands, such as `g'
2384 ;; (`Info-goto-node'), `i' (`Info-index'), and `m' (`Info-menu'), you
2385 ;; can take advantage of Icicles completion. For instance, if you
2386 ;; type `g yan', you can use `S-TAB' for apropos completion and
2387 ;; choose node `Isearch Yank', whose name contains `yan' but does not
2388 ;; start with it. This is an obvious and standard Icicles feature.
2390 ;; Although vanilla Emacs also accepts a substring as input for `i',
2391 ;; it does not provide substring or regexp completion, and it will
2392 ;; not accept a regexp as final input.
2394 ;; Icicle mode binds `g', `i', and `m' to multi-commands
2395 ;; `icicle-Info-goto-node', `icicle-Info-index', and
2396 ;; `icicle-Info-menu', which means that you can also use `g', `i',
2397 ;; and `m' with `C-next', `C-RET', `C-mouse-2', and so on, to browse
2398 ;; among matching Info nodes. Unlike browsing with repeated use of
2399 ;; `,' after `i' in vanilla Emacs, you can continue to see all of the
2400 ;; matching candidates, in buffer `*Completions*', and you need not
2401 ;; visit the index hits in sequential order.
2403 ;; If you use `M-g' in the minibuffer to toggle
2404 ;; `icicle-use-C-for-actions-flag', then you can use just `next'
2405 ;; instead of `C-next' to navigate. See
2406 ;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'").
2408 ;; As usual in Icicles, you can sort completion candidates in various
2409 ;; ways, using `C-,' (`icicle-change-sort-order'). For `g', in
2410 ;; particular, although the default order is alphabetical, you can
2411 ;; choose `in book order', which shows the node candidates in the
2412 ;; same order as in the book. In that case, using `g' and then
2413 ;; navigating among candidates sequentially using `C-down', `C-up',
2414 ;; `C-next', `C-prior', `C-end', or `C-home', visits the nodes in
2415 ;; their natural order.
2417 ;; As a special case of this, if you use a negative prefix argument
2418 ;; (that is, `M-- g'), then not only are the candidate nodes
2419 ;; presented `in book order', they are also limited to the nodes that
2420 ;; follow your current location in the book - that is, to the
2421 ;; remainder of the book. (A non-negative numeric prefix argument
2422 ;; has the same meaning as for `Info-goto-node'.)
2424 ;; In addition, except when you are at the `Top' node, a pseudo-node
2425 ;; `..' is added to the set of completion candidates. Choosing this
2426 ;; takes you up to the parent of the current node. You can thus use
2427 ;; `g' in Info not only to explore nodes by name, but also as another
2428 ;; means to traverse the Info menu hierarchy.
2430 ;;(@* "Virtual Info Books")
2431 ;; *** Virtual Info Books ***
2433 ;; You can take advantage of Icicles completion-candidate set
2434 ;; operations to create your own virtual Info books. That is, you
2435 ;; can define and save sets of Info nodes or Info index entries, and
2436 ;; then reuse them later.
2438 ;; Both `m' and `g' in Info use nodes as candidates, so you can use
2439 ;; `m' or `g' or a combination of `m' and `g' to define a node set,
2440 ;; and you can use either `m' or `g' to reuse a node set. A set of
2441 ;; index entries is different: You must use `i' to create and reuse
2444 ;; Remember that you can define a candidate set incrementally, adding
2445 ;; more elements using `C->', `C-)', `insert', `M-S-mouse-2',
2446 ;; `M-mouse-3', or `mouse-1 mouse-3 mouse-3'. And you can save a
2447 ;; candidate set persistently. [*]
2449 ;; You can even create a virtual book that includes Info nodes from
2450 ;; different manuals. For example, you might want to collect
2451 ;; together specific nodes that deal with some particular topic, such
2452 ;; as faces, from both the Emacs manual and the Elisp manual.
2454 ;; You do this using `C-u g' (a plain prefix argument). This
2455 ;; prepends the Info file name (book identifier) to each node-name
2456 ;; completion candidate. For example, when you are in the Emacs
2457 ;; manual, each node candidate is prefixed by `(emacs)', and in the
2458 ;; Elisp manual each candidate is prefixed by `(elisp)'. You define
2459 ;; a set of candidates in the usual Icicles ways, changing manuals as
2460 ;; needed to add additional nodes to the set you save.
2462 ;; A node name prefixed by its file name is analogous to an absolute
2463 ;; file name, that is, a relative file name prefixed by its
2464 ;; directory. Because such a saved candidate has a book prefix,
2465 ;; e.g. `(emacs)', it is absolute and unambiguous. You can use it
2466 ;; wherever you happen to be in Info, to go directly to that node.
2467 ;; This is a feature of `g' even in vanilla Emacs: you can go to a
2468 ;; node in a different manual from the one you are currently
2471 ;; When you want to reuse a virtual book, hit `g' again, retrieve the
2472 ;; saved set of node candidates that defines the book, and navigate
2473 ;; among the saved nodes.
2475 ;; If you use library `info+.el', you can also take advantage of its
2476 ;; definition of virtual books and saved Info nodes. That library
2477 ;; defines command `Info-virtual-book', which opens Info on a Table
2478 ;; of Contents of a virtual book of nodes that you have saved either
2479 ;; using command `Info-save-current-node' or by customizing user
2480 ;; option `Info-saved-nodes'.
2482 ;; Icicles command `icicle-Info-virtual-book' extends
2483 ;; `Info-virtual-book' by letting you define the virtual book nodes
2484 ;; using completion. That is, you can use `g' to save a set of
2485 ;; node-name completion candidates (as the value of variable
2486 ;; `icicle-saved-completion-candidates'), and then use command
2487 ;; `icicle-Info-virtual-book' to open an Info buffer with those nodes
2490 ;; If you have not saved any node-name candidates, then
2491 ;; `icicle-Info-virtual-book' acts the same as `Info-virtual-book':
2492 ;; it opens the virtual book that is defined by `Info-saved-nodes'.
2493 ;; With `info+.el', the key `.' adds the current node to
2494 ;; `Info-saved-nodes', which gives you a convenient way to build up a
2495 ;; virtual book as you read. This is like Emacs bookmarking, but it
2496 ;; keeps your saved Info nodes separate from your other bookmarks.
2498 ;; With a prefix argument, `icicle-Info-virtual-book' lets you choose
2499 ;; a persistently saved completion set to use instead of
2500 ;; `icicle-saved-completion-candidates' or `Info-saved-nodes'. This
2501 ;; means that you can have any number of such saved node sets as
2502 ;; virtual books, to use at any time.
2506 ;; * (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates")
2507 ;; for information about defining, saving, and reusing sets of
2508 ;; completion candidates.
2510 ;; * (@> "Icicles Bookmark Enhancements") for information about using Info bookmarks.
2512 ;; [* If you click `mouse-1' on a candidate and (starting with Emacs
2513 ;; 22) `mouse-1-click-follows-link' is an integer, then you will need
2514 ;; to hold the mouse button depressed longer than that many seconds,
2515 ;; or else that candidate will simply by chosen. If the value is
2516 ;; `t', then this will not work at all. Any other value presents no
2517 ;; problem. (Personally, I use `nil'.)]
2519 ;;(@* "Using Icicle-Search With Info")
2520 ;; ** Using Icicle-Search With Info **
2522 ;; Icicles searching (`icicle-search') is not Isearch. It searches
2523 ;; for all matches in the portion of text you tell it to search.
2524 ;; This means that you cannot use it to search an entire manual in
2525 ;; one operation, unless you have the entire manual available in a
2526 ;; single buffer to be searched.
2528 ;; So, when you use `icicle-search' (`C-c `') to search with Info,
2529 ;; you are limited to a few options:
2531 ;; * You can use it normally, to search within a single Info node.
2533 ;; * You can widen the visible portion of the Info buffer
2534 ;; (`C-x n w'), to use it on an entire Info file. However:
2536 ;; 1. It is not obvious how a given Info manual is divided into
2537 ;; files. That is, you need to be aware of the point at which
2538 ;; the manual moves from one file to the next.
2540 ;; 2. Only the nodes in the same file that you have already visited
2541 ;; are highlighted, and lots of ugly Info "plumbing" becomes
2542 ;; visible in the other nodes.
2544 ;; 3. You lose all Info features, such as navigation using links.
2546 ;; * There is another way to search across nodes, which addresses #1
2547 ;; and #2, but still does not give you navigable links and such.
2548 ;; Think of it as a hack that can sometimes be handy. That is what
2549 ;; is described below.
2551 ;; The idea is to flatten a subtree of Info nodes - possibly an
2552 ;; entire manual, but more typically a node and its children - and
2553 ;; then use `icicle-search' (`C-c `') over that flattened document.
2554 ;; What is needed is a command that flattens Info subtrees. Library
2555 ;; `info+.el' provides such a command, `Info-merge-subnodes', and
2556 ;; binds it to `+' in Info.
2558 ;; You can control how you want the flattening to occur, by using
2559 ;; different values of prefix argument. For searching, you probably
2560 ;; want complete flattening of the chosen subtree, in a single
2561 ;; buffer, so you use a prefix arg of zero: `C-u 0 +'.
2563 ;; This does not replace the `*Info*' buffer that you started with;
2564 ;; it creates a new buffer, named after the root node of the subtree
2565 ;; you flattened. A principle use of `Info-merge-subnodes' is to
2566 ;; print out a manual or a portion of it. Also, I wrote a library
2567 ;; (`mkhtml.el', outdated now) that lets you convert the result to
2570 ;; In sum, you can use Icicles search in Info: `C-u 0 +', then
2573 ;; One caveat, however: You will generally want to limit your search
2574 ;; to a reasonably small subtree of a manual, instead of flattening
2575 ;; and then searching the entire manual. Flattening a large manual
2576 ;; can take a while: it took me 10 minutes to flatten the Emacs
2577 ;; Manual. Of course, you could flatten a large manual once, and
2578 ;; save the result in a file for later searches.
2580 ;; Obviously, flattening in order to search is less convenient than
2581 ;; using manual-wide incremental search (`C-s') with Info (starting
2582 ;; with Emacs 22), and it is often less convenient than using
2583 ;; `Info-search' (bound to `s' in Info). Icicles searching is
2584 ;; different from both, and it has its advantages and disadvantages.
2585 ;; When you want the advantages of Icicles searching in Info, the
2586 ;; flattening hack can be useful. When you do not need those
2587 ;; advantages, other search methods can sometimes be more
2592 ;; * (@file :file-name "icicles-doc1.el" :to "Multi-Commands") for
2593 ;; information on using multi-commands.
2595 ;; * (@> "Icicles Search Commands, Overview") for information about
2596 ;; command `icicle-search'.
2598 ;; * Library `info+.el' for information about `Info-merge-subnodes'.
2600 ;;(@* "Support for Projects")
2602 ;; Icicles Support for Projects
2603 ;; ----------------------------
2605 ;; This section mainly provides pointers to other sections of the
2606 ;; Icicles doc that describe features that can help you work with a
2607 ;; project that involves multiple files, buffers, or bookmarks.
2610 ;;(@* "Bookmarks for Project Access and Organization")
2611 ;; ** Bookmarks for Project Access and Organization **
2613 ;; If you use Bookmark+ (library `bookmark+.el'), then you can use
2614 ;; bookmarks of various types, including the following, to help
2615 ;; manage software projects:
2617 ;; * Dired buffers, with specific sets of files and subdirectories
2618 ;; that are marked or omitted, and using specific listing switches.
2620 ;; * `*Bookmark List*' buffers, with specific sets of bookmarks that
2621 ;; are marked or hidden.
2623 ;; * Multiple alternative bookmark files. For example, use a
2624 ;; different one for each project. Or use different ones for
2625 ;; subprojects and use them together for a full project.
2627 ;; * Desktops, which include sets of variables and visited buffers
2630 ;; * Composite, or sequence, bookmarks, which combine other
2633 ;; You can also associate tags, in the del.icio.us sense, with most
2634 ;; types of bookmarks. (Such tags are unrelated to the Emacs
2635 ;; source-code tags that use tags files.) A bookmark can have any
2636 ;; number of tags, and multiple bookmarks can have the same tag,
2637 ;; which means you can use them to organize their target objects.
2638 ;; And tags can be more than just names: they can be user-defined
2639 ;; attributes, with Emacs-Lisp objects as their values.
2641 ;; These and other Bookmark+ features give you different ways to
2642 ;; save, restore, filter, access, and otherwise organize projects, as
2643 ;; collections of information about source-code components and
2644 ;; related software.
2646 ;; Icicles enhances access to such features.
2647 ;; See (@> "Icicles Bookmark Enhancements").
2649 ;;(@* "A Tags File Can Define a Project")
2650 ;; ** A Tags File Can Define a Project **
2652 ;; One simple kind of a project includes the files that are in or
2653 ;; under a single directory. Such a project is limited, but it can
2654 ;; often be useful, and it has the advantage of being supported by
2655 ;; several existing Emacs features.
2657 ;; Another simple kind of project includes the files that are listed
2658 ;; in a given Emacs tags file. This is obviously more complex and
2659 ;; flexible than a directory listing.
2661 ;; Icicles provides multi-commands for visiting one or more files
2662 ;; that are listed in the current tags table:
2663 ;; `icicle-find-file-in-tags-table' and
2664 ;; `icicle-find-file-in-tags-table-other-window'. See also
2665 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Commands that Read File Names").
2667 ;;(@* "Navigating Among Code Definitions")
2668 ;; ** Navigating Among Code Definitions **
2670 ;; For software projects, you need to be able to navigate among code
2671 ;; definitions. Imenu and Emacs tags features are useful for this,
2672 ;; as are `grep' and compilation buffers. Icicles improves all of
2673 ;; these. (A tags file is just a saved index for project files.)
2677 ;; * (@> "Icicles Imenu")
2678 ;; * (@> "Icicles Enhancements for Emacs Tags")
2679 ;; * (@> "Compile/Grep Search")
2681 ;;(@* "Searching Project Files")
2682 ;; ** Searching Project Files **
2684 ;; Searching within your project is another area where Icicles can
2685 ;; help. Icicles search is both search and navigation. Navigating
2686 ;; among tags definitions that match a regexp is also really
2687 ;; searching, and the same is true for Imenu and grep navigation.
2689 ;; See also (@> "Icicles Search Commands, Overview") and its
2690 ;; subsections for information about the many ways that you can use
2691 ;; Icicles search to access parts of your projects.
2693 ;; See also (@> "Icicles Dired Enhancements") for an easy way to
2694 ;; search marked files in Dired with Icicles search.
2696 ;; See also (@> "Searching Bookmarked Objects") for ways to search
2697 ;; bookmarked objects, including the files that have a given set of
2698 ;; del.icio.us-style tags and the bookmarks that are marked in a
2699 ;; given bookmark-list state.
2701 ;; And do not forget that all uses of Icicles search also let you do
2702 ;; search-and-replace on the fly. This applies to `grep' results,
2703 ;; searching marked files in Dired, tags navigation, and Imenu
2704 ;; navigation. You can at any time replace the current search hit or
2705 ;; just the part of it that matches your current input.
2707 ;;(@* "Defining and Saving Sets of Files or Buffers")
2708 ;; ** Defining and Saving Sets of Files or Buffers **
2710 ;; Let's assume that you have one or more sets of files or buffers
2711 ;; that you use frequently. For each such set of objects, you create
2712 ;; an Emacs option whose value is a list of the file or buffer names
2715 ;; Later, you use the option value to refer to those objects by name.
2716 ;; This brings you back to the context of working with just those
2717 ;; particular files or buffers that belong to your project. You can
2718 ;; search such sets or navigate among their objects. Icicles has a
2719 ;; number of features that can help with these tasks.
2721 ;; Note: Bookmarks are also persistent references to files and
2722 ;; buffers, and you can use sets of bookmarks similarly. Bookmarking
2723 ;; is a vanilla Emacs feature. Being able to manipulate explicit
2724 ;; sets of bookmarks is a Bookmark+ feature (library `bookmark+.el').
2725 ;; Bookmarking features are described elsewhere, but they work in
2726 ;; concert with Icicles to offer very good project support.
2727 ;; See (@> "Icicles Bookmark Enhancements").
2729 ;; Before you can name and save a set of file or buffer names, you
2730 ;; must define its members: pick the file and buffer names that you
2731 ;; want to belong to a given project. Icicles can help with this.
2733 ;; For buffers, use commands `icicle-add-buffer-config' and
2734 ;; `icicle-remove-buffer-config' to define one or more buffer
2735 ;; configurations. These are named sets of buffers, sort functions,
2736 ;; and other parameters that control completion of buffer names.
2737 ;; Thereafter, you can use command `icicle-buffer-config' to choose a
2738 ;; configuration to be current.
2740 ;; To define a set of files, you use Icicles completion against file
2741 ;; names. You can use progressive completion, chip away the
2742 ;; non-elephant, and so on, to get just the file names you want.
2744 ;; For this completion, you can use a command that calls
2745 ;; `read-file-name', and so matches relative file names using the
2746 ;; current `default-directory'. Or you can use a command that calls
2747 ;; `completing-read', and so matches file names only as ordinary
2748 ;; strings, that is, with no notion that they are file names. In the
2749 ;; latter case, the file names are often absolute, which means that
2750 ;; you can match not only file names but also directory components.
2752 ;; Examples of the former type are `icicle-find-file' and
2753 ;; `icicle-find-file-read-only' (`C-x C-r' by default). Examples of
2754 ;; the latter type are `icicle-find-file-absolute',
2755 ;; `icicle-find-file-in-tags-table', `icicle-recent-file', and
2756 ;; `icicle-locate-file'. Command `icicle-file' (bound to `C-x C-f'
2757 ;; by default) lets you do both, depending on the prefix argument.
2759 ;; You save a set of file names the same way you save any set of
2760 ;; completion candidates. You can save all of the names that match
2761 ;; your current input. You can add a set of names or individual
2762 ;; names to a set of names that you have already saved.
2764 ;; In addition, you can save the marked files in Dired as a set of
2767 ;; Your project is not only files that are all in the same directory,
2768 ;; of course. You can save file names from multiple directories in
2769 ;; the same set. And you can include directory names as well, for
2770 ;; use later with commands that operate on directories. Finally, you
2771 ;; can also save file names as Emacs filesets and use those the same
2772 ;; way. An Icicles set of saved file names can include Emacs
2774 ;; (@file :file-name "icicles-doc1.el" :to "Filesets and Icicles Saved Completion Sets").
2778 ;; * (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates")
2779 ;; * (@file :file-name "icicles-doc1.el" :to "Persistent Sets of Completion Candidates")
2780 ;; * (@> "Icicles Bookmark Enhancements")
2781 ;; * (@file :file-name "icicles-doc1.el" :to "Progressive Completion")
2782 ;; * (@file :file-name "icicles-doc1.el" :to "Chip Away the Non-Elephant")
2783 ;; * (@file :file-name "icicles-doc1.el" :to "File-Name Input and Locating Files Anywhere")
2784 ;; * (@> "Save Marked Files as Completion Candidates") (Dired)
2786 ;;(@* "Retrieving and Reusing a Saved Project")
2787 ;; ** Retrieving and Reusing a Saved Project **
2789 ;; This section could also be called "Using Retrieved Saved Sets".
2791 ;; You retrieve a set of saved file names (a project) the same way
2792 ;; you retrieve any saved set of completion candidates. That is, you
2793 ;; access the files defined for your project by retrieving their
2794 ;; names during completion, to serve as the current set of completion
2795 ;; candidates. This odd feature is unique to Icicles.
2797 ;; There's nothing much more to say about this, except that you
2798 ;; should be taking advantage of it now. Define and save a set of
2799 ;; project files (or buffers), and later use just those files,
2800 ;; staying within the bounds of your project for your navigation,
2801 ;; search, compilation, etc. needs. Even if the files you use in a
2802 ;; given project are scattered all over your file system, Icicles
2803 ;; lets you access them together as a named unit. For more
2805 ;; (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates").
2807 ;; If you use library `bookmark+.el' then you can open a project that
2808 ;; is defined by a set of bookmarks, by doing one of the following:
2810 ;; * Using a project-specific bookmark file.
2812 ;; * Using a bookmark-list bookmark (it records a `*Bookmark List*'
2813 ;; buffer state, including which bookmarks are marked or omitted).
2815 ;; You can also open Dired for a project or for a list of file names
2816 ;; saved non-persistently as completion candidates - only those files
2817 ;; are listed in the Dired buffer.
2818 ;; See (@> "Icicles Dired Enhancements").
2820 ;; You can also run `grep' on a saved list of file names using
2821 ;; command `icicle-grep-saved-file-candidates'. If you use library
2822 ;; `dired+.el', then you can also `grep' the files in a project or
2823 ;; saved list of file names by opening it in Dired and then using
2824 ;; `M-g' (`diredp-do-grep').
2826 ;; Finally, note that among the sets of completion candidates that
2827 ;; you can save are Icicles search hits. That's right. Icicles
2828 ;; search lets you search multiple buffers, files, or bookmarks, and
2829 ;; you can save selected search hits or all matching hits for later
2830 ;; use. When you save search hits, Icicles records the buffer or
2831 ;; file names and the hit locations within those buffers or files.
2832 ;; When you retrieve such a saved set to access its hits, Icicles
2833 ;; automatically takes you to the proper files.
2835 ;; A related feature is being able to filter tags definitions and
2836 ;; then save the filtered hit list. This works the same way, and it
2837 ;; gives you the equivalent of per-project tags files: A saved hit
2838 ;; list acts just like a custom tags file when you reuse it. And
2839 ;; unlike some of your project files, a tags file does not change
2840 ;; often, so saved hit sets stay accurate longer.
2842 ;;(@* "Semantics? Roll Your Own?")
2843 ;; ** Semantics? Roll Your Own? **
2845 ;; I no longer develop software. I just putz around with Emacs Lisp
2846 ;; for my own enjoyment, entertainment, and enlightenment. So I do
2847 ;; not use things like ECB (Emacs Code Browser) or Semantic
2848 ;; (Bovinator). I do not use any IDE that has knowledge of a
2849 ;; particular programming language. The Icicles commands I've
2850 ;; written therefore use little or no semantic or language
2851 ;; information; they rely upon syntax for the most part, and they are
2852 ;; essentially language-agnostic (i.e. ignorant).
2854 ;; But you are a different story. If you use, say, Semantic, you
2855 ;; could write a little Emacs-Lisp code to take advantage of Icicles
2856 ;; in combination with Semantic's parser information. With complete
2857 ;; ignorance of Semantic, I dare say it would not be hard. If you
2858 ;; can get an alist of completion candidates for something from
2859 ;; Semantic in some context, then you can exploit all of the Icicles
2860 ;; features: apropos completion, progressive completion,
2861 ;; multi-commands, Icicles search, and so on. Likewise for any other
2862 ;; IDE that plays well with Emacs and for any other programming
2863 ;; language support. Think about it. Others would appreciate your
2866 ;; Icicles provides lots of features for Emacs-Lisp programmers. The
2867 ;; end-user commands I've written using some of those features are
2868 ;; really just a demonstration of what you can do. Try rolling your
2869 ;; own Icicles commands. See Also: (@> "Note to Programmers").
2871 ;;(@* "Using Complex Completion Candidates")
2873 ;; Using Complex Completion Candidates
2874 ;; -----------------------------------
2876 ;; This section could also be called "Applying a Function
2877 ;; Interactively" or "Mapping over Sets". It is about applying a
2878 ;; function to members of a set of completion candidates that you
2879 ;; select interactively. The candidates can represent arbitrarily
2880 ;; complex data, and the function is applied to the associated data
2881 ;; as well, not just to the displayed (string) candidate that names
2884 ;; You already know that you can manipulate sets of candidates - see
2885 ;; (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates").
2886 ;; The elements of those sets are strings; you choose
2887 ;; candidate names. Sometimes, however, you need to choose among
2888 ;; named items that are themselves complex, containing more
2889 ;; information than just the name. That is the idea behind
2890 ;; multi-command `icicle-apply', which this section introduces.
2892 ;; You (or a command that you use) can obtain the information
2893 ;; associated with a name after you choose the name. This is what
2894 ;; happens, for instance, when you use `find-file'; the command looks
2895 ;; up the file associated with the file name you choose. Icicles
2896 ;; multi-commands such as `icicle-file' perform this lookup both when
2897 ;; you act on a candidate during completion (e.g. `C-RET') and when
2898 ;; you make a final candidate selection (`RET') - see
2899 ;; (@file :file-name "icicles-doc1.el" :to "Multi-Commands").
2901 ;; Names and their associated information can be available in Emacs
2902 ;; Lisp in the form of an association list (alist), that is, a list
2903 ;; whose items are conses (cons cells). An alist is often used to
2904 ;; represent a function that maps one set of things to another. The
2905 ;; conses in the alist represent the tuples (typically pairs) of
2906 ;; related items. The car of each cons is called its "key"; the cdr
2907 ;; is called its "value". Different alists have different kinds of
2908 ;; keys and values. Typical key types include symbols and strings;
2909 ;; typical value types include symbols, strings, numbers, and lists.
2910 ;; There are quite a few standard Emacs-Lisp variables whose value is
2911 ;; an alist. Most are internal variables, but some are user options.
2912 ;; See the Emacs-Lisp manual for more about alists.
2914 ;; The completion mechanism of Emacs function `completing-read' can
2915 ;; take an alist as input: the keys are the completion-candidate
2916 ;; strings that you choose from. For Emacs completion, however, the
2917 ;; value (cdr) of each alist key/value entry is completely ignored.
2918 ;; Icicles uses `completing-read', and it works the same way. If a
2919 ;; command needs to access the value associated with a key
2920 ;; (candidate), then it must somehow do so independently of
2923 ;; Command `icicle-search' offers an example of this. The completion
2924 ;; alist contains key/value pairs whose car (key) is a search-hit
2925 ;; string that matches your search string and whose cdr (value) is
2926 ;; the buffer position for the hit. When you use completion with
2927 ;; this command, you work only with the keys, but `icicle-search'
2928 ;; also keeps track of the corresponding buffer positions for you.
2929 ;; The logic for doing this is coded into the definition of
2932 ;; It is common to want to do something interesting interactively
2933 ;; with the values also, not just the keys, of a completion alist.
2934 ;; Why lose the important value information when you choose a key?
2935 ;; And instead of requiring the logic of each command to deal with
2936 ;; this need individually, why not provide a general mechanism for
2937 ;; accessing this information - both by program and interactively?
2938 ;; This is what command `icicle-apply' is for.
2940 ;; To make use of completion alist values, you need to access the cdr
2941 ;; of a key/value cons (pair). Different alists are structured
2942 ;; differently: the cdr can itself be complex (structured - a cons).
2943 ;; In general, you want to access not just the cdr (value) but the
2944 ;; key as well, the key/value pair as a whole, to do what you want
2945 ;; with it - that is, to apply some function to it.
2947 ;; Emacs-Lisp programmers sometimes map functions over lists to
2948 ;; obtain a different list. For example, mapping the function `1+'
2949 ;; over the list (3 1 4 1 5 9) gives the list (4 2 5 2 6 10). Or if
2950 ;; interested only in the side effects, they apply a function
2951 ;; iteratively over a list without bothering to accumulate the
2952 ;; results as a new list. The command `icicle-apply' is inspired by
2953 ;; these common practices of mapping and iterating over a list, but
2954 ;; it applies only to alists. And it lets you choose interactively
2955 ;; which alist elements to act on, instead of always acting on all
2958 ;; `icicle-apply' lets you apply a function of your choice to any
2959 ;; number of key/value entries in an alist. As user of the command,
2960 ;; you choose the entries to act on. The alist is used for
2961 ;; completion; you choose among the keys. The function is applied to
2962 ;; the corresponding key/value pairs, however, not to the keys alone.
2964 ;; For example, given the alist `auto-mode-alist' and the function
2965 ;; `cdr', you can choose to apply `cdr' to selected alist entries.
2966 ;; This acts as a simple lookup function, because `cdr' just returns
2967 ;; the value associated with a chosen key. If you choose, for
2968 ;; example, the candidate (key) "\.el\'", then the (value) result is
2969 ;; the symbol `emacs-lisp-mode'. In this case, the chosen key/value
2970 ;; pair is ("\\.el\\'" . emacs-lisp-mode). (A literal backslash must
2971 ;; be doubled in an Emacs-Lisp string.)
2973 ;; Function `cdr' returns the value, which is `emacs-lisp-mode' here.
2974 ;; If instead of `cdr' you use the function (lambda (x)
2975 ;; (describe-function (cdr x))), then the result of choosing
2976 ;; candidate "\.el\'" is to display the help for function
2977 ;; `emacs-lisp-mode'. This function first uses `cdr' to obtain the
2978 ;; value (the mode) and then applies `describe-function' to that
2981 ;; A typical use of `icicle-apply' is to define your own
2982 ;; multi-command that you or someone else can use to act on objects
2983 ;; selected by name. The definition of command `icicle-goto-marker'
2984 ;; provides an example. It uses an alist whose elements are pairs
2985 ;; composed of a text line (the key) and the marker (the value) in
2986 ;; that line. It applies a function that moves to the marker.
2988 ;; If called interactively (as opposed to being used to define
2989 ;; another command), `icicle-apply' lets you use completion to choose
2990 ;; not only the objects to act on but also the function to apply to
2991 ;; them and the alist to choose them from. See the doc string of
2992 ;; `icicle-apply' for more information.
2994 ;; Note that you can type in a lambda expression when prompted for
2995 ;; the function. You can use any function, provided it targets a
2996 ;; key/value pair (a cons). This is why you could not simply use
2997 ;; `describe-function' itself as the function to apply in the example
2998 ;; above: `describe-function' expects a symbol argument, not a cons.
3000 ;; So what is `icicle-apply' really for? Anything you want. You can
3001 ;; use it to simply browse an alist or to perform actions on complex
3002 ;; things. The idea is to let you take advantage of Icicles features
3003 ;; to interactively filter and manipulate a set of completion keys,
3004 ;; and then apply any function you like to them - not just to the
3005 ;; keys, but to the keys or their values, or both.
3007 ;; You can use apropos (regexp) matching or prefix matching to filter
3008 ;; the alist, as always, during completion. You can use `C-RET' and
3009 ;; so on to act on (that is, apply the function to) selected
3010 ;; key/value pairs that match your current input.
3012 ;; You can also act on *all* such pairs, by using `C-!' or `M-!'.
3013 ;; `C-!' corresponds to iterating over the items in a list, applying
3014 ;; a function to each. `M-!' applies a function not to each chosen
3015 ;; pair, but to the *list* of all chosen pairs. By default, the
3016 ;; completion candidates are not sorted, but you can of course sort
3017 ;; them in various ways, either interactively or by program.
3019 ;; As an Emacs-Lisp programmer, you can use function `icicle-apply'
3020 ;; programmatically to let users look things up in alists that you
3021 ;; construct or to act on selected alist entries in complex ways.
3022 ;; Icicles just provides the interactive completion features.
3024 ;; The real value of `icicle-apply' comes from what you do with it.
3025 ;; Use it with a database of geographical coordinates to look up
3026 ;; location names provided by users and draw corresponding vicinity
3027 ;; maps. Use it with a list of hardware configurations to let users
3028 ;; perform diagnostic or maintenance operations on selected
3029 ;; equipment. You get the idea - use your imagination.
3031 ;; Note: Although completion alists normally require string-valued
3032 ;; keys, `icicle-apply' is designed to work with any alist.
3034 ;;(@* "Icicles OO: Object-Action Interaction")
3036 ;; Icicles OO: Object-Action Interaction
3037 ;; --------------------------------------
3039 ;; Here's another crazy Icicles feature: Instead of choosing a
3040 ;; function (e.g. command) and then the object to apply it to, choose
3041 ;; the object first and then the function.
3043 ;; The first thing to say about this feature is that Emacs is not
3044 ;; really designed for this, so it's not feasible to do this in a
3045 ;; entirely satisfactory way. In particular, there is no practical
3046 ;; way, given an object, to find all of the functions that apply to
3047 ;; it, in order to allow all of those functions, and only those
3048 ;; functions, as completion candidates.
3050 ;; The second thing to say is that there are several ways that
3051 ;; Icicles helps you operate on an object that you have already
3054 ;; * apropos completion - (1) choose an object type by name, (2)
3055 ;; choose a function, (3) choose the target object
3057 ;; * alternative action by type, during completion - (1) choose a
3058 ;; target object, (2) choose a function appropriate for the
3061 ;; * `M-RET' during completion - (1) choose a target object, (2)
3062 ;; choose any function
3064 ;; * `icicle-object-action' and `icicle-anything' - (1) choose an
3065 ;; object type by name, (2) choose the target object, (3) choose a
3068 ;; As a special case, if you use library Anything (`anything.el'),
3069 ;; then `icicle-object-action' lets you apply one or more Anything
3070 ;; actions defined for the object. See (@> "Icicles with Anything")
3071 ;; for more information.
3073 ;;(@* "Apropos Completion as OO")
3074 ;; ** Apropos Completion as OO **
3076 ;; You can use apropos completion with `M-x' to narrow the set of
3077 ;; possible commands to those that have a given object type in their
3078 ;; name. You choose the command before the individual object, but
3079 ;; you at least choose the object type first (which narrows the set
3080 ;; of possible objects).
3082 ;; If you use Icicles, you already use apropos completion this way,
3083 ;; but you might not have thought about it in these terms. If you
3084 ;; want to invoke some command on a buffer, you might start by typing
3085 ;; `M-x buffer S-TAB' or `M-x buff S-TAB'. This is simple, but it
3086 ;; really does get you most of the way toward object-action
3087 ;; interaction. And you can of course then use progressive
3088 ;; completion (`M-*') to filter the matching commands for additional
3089 ;; object-type names; for example `M-* window' keeps only those
3090 ;; commands whose names contain both `buffer' and `window'.
3092 ;; Of course, this approach requires the command name to actually
3093 ;; advertise truthfully the object types that it operates on. There
3094 ;; are false positives and true negatives, but Emacs is generally
3095 ;; quite helpful in this respect.
3097 ;;(@* "Alternative Action as OO")
3098 ;; ** Alternative Action as OO **
3101 ;; (@file :file-name "icicles-doc1.el" :to "Alternative Actions"),
3102 ;; many Icicles commands, as their alternative action
3103 ;; (e.g. `C-S-RET'), prompt you to choose an action to be applied to
3104 ;; the current completion candidate. The actions you can choose are
3105 ;; all appropriate functions for the current type of object
3106 ;; (candidate). If you use library Anything (see below), then any
3107 ;; actions defined for the current type by Anything are included.
3110 ;; (@file :file-name "icicles-doc1.el" :to "Alternative Actions").
3115 ;; `M-RET' (`icicle-candidate-read-fn-invoke') during completion
3116 ;; provides a typeless object-action interaction, which is always
3117 ;; available. (You can also use `ESC RET' or `ESC C-m'.)
3119 ;; This is similar to the action choice provided for some
3120 ;; commands by `C-S-RET', except that there is no notion of the
3121 ;; current object type - you can choose from among all Emacs-Lisp
3124 ;; Whenever you cycle through completion candidates, `M-RET' enters a
3125 ;; recursive edit that prompts you for a function to apply to the
3126 ;; current candidate. `M-mouse-2' does the same thing. For example,
3127 ;; if the current candidate is a buffer named `foo.el', then `M-RET'
3128 ;; prompts you for a function to apply to it. (Actually, the
3129 ;; function is applied to the candidate, which is the buffer name in
3130 ;; this case, but many functions accept an object name in place of
3133 ;; The function you enter can be anything, including a lambda
3134 ;; expression that accepts an argument of the appropriate type. The
3135 ;; function is read with (lax) completion. It is up to you to choose
3136 ;; a function that is appropriate for the current object type.
3138 ;; If you use a prefix argument (`C-u M-RET' or `C-u M-mouse-2'),
3139 ;; then the result of the function application is pretty-printed.
3140 ;; Otherwise, the function is called for effect only.
3142 ;;(@* "`icicle-object-action' and `icicle-anything'")
3143 ;; ** `icicle-object-action' and `icicle-anything' **
3145 ;; Another way that Icicles helps with object-action interaction is
3146 ;; provided by command `icicle-object-action'. This reads an
3147 ;; object-type name ("what"), with completion; then it reads an
3148 ;; object of that type ("which"), with completion; then it reads a
3149 ;; function (name or lambda expression) to apply to the object
3150 ;; ("how"), with (lax) completion. Again, use a prefix argument if
3151 ;; you want to pretty-print the result.
3153 ;; `what-which-how' is an alias for command `icicle-object-action'.
3154 ;; It is easy to remember, taking its name from the successive input
3155 ;; prompts: "What?" - a file. "Which?" - icicles.el. "How?" open.
3156 ;; Another alias for the same command is `a', because it acts on a
3157 ;; file, a buffer, a symbol, a process, and so on. The first thing
3158 ;; it does is prompt you for the type of object, so you do `M-x a RET
3159 ;; buffer', `M-x a RET symbol', and so on.
3161 ;; The aliases `what-which-how' and `a' are just convenience
3162 ;; commands. They are defined only if user option
3163 ;; `icicle-define-alias-commands-flag' is non-`nil'. Two related
3164 ;; commands are also defined only if this option is non-`nil':
3166 ;; * `file' - same as `a RET file'
3167 ;; * `buffer' - same as `a RET buffer'
3169 ;; For example: `M-x file RET'. You are prompted for a file to act
3170 ;; on, and then for the action to use.
3172 ;; Note: If you use AUCTeX, then be aware of an AUCTeX bug that
3173 ;; causes problems if `icicle-define-alias-commands-flag' is
3174 ;; non-`nil'. Here is the bug description, filed 2007/10/05 by Bjorn
3176 ;; http://lists.gnu.org/archive/html/bug-auctex/2007-10/msg00006.html.
3177 ;; The problem is that AUCTeX mistakenly invokes the Icicles `file'
3178 ;; command, in an inappropriate context. AUCTeX does not define any
3179 ;; function `file' when it is loaded, but it invokes one, if defined.
3180 ;; This appears to be a name-capture problem. Since there is no
3181 ;; `file' function defined when Icicles is loaded, Icicles defines
3182 ;; its command. AUCTeX developers will no doubt fix this bug. Until
3183 ;; then, AUCTeX users can avoid the bug by setting
3184 ;; `icicle-define-alias-commands-flag' to `nil'.
3186 ;; The "type" of an object is one of these:
3188 ;; a. A type defining an entry in user option
3189 ;; `icicle-predicate-types-alist'. These are type predicates,
3190 ;; such as `bufferp', `keywordp', or `atom'.
3192 ;; b. The `type' of an Anything source, or its `name' if it has no
3193 ;; `type'. This is available only if you use library
3196 ;; c. A type defining an entry in user option
3197 ;; `icicle-type-actions-alist'.
3199 ;; Icicles completion is available for each prompt: the type, the
3200 ;; object, and the action to apply to the object. Types defined by
3201 ;; Anything are highlighted in buffer `*Completions*' using face
3202 ;; `icicle-special-candidate'. In the case of an Anything type, you
3203 ;; can use multi-command features to act on multiple objects in
3204 ;; multiple ways, all within a single `a' invocation. See
3205 ;; (@> "Icicles with Anything") for more information about using
3208 ;; The objects of types (b) and (c) are easily named, and their names
3209 ;; serve as the completion candidates when you choose them. So, for
3210 ;; instance, if you choose type `buffer', then you can act on a
3211 ;; buffer by choosing its name.
3213 ;; The objects of predicate type (type a, above) are not necessarily
3214 ;; named. The completion candidates for these objects are symbols
3215 ;; whose values are the objects that are acted upon. The object-type
3216 ;; names used for these candidates are really Emacs-Lisp type
3217 ;; predicate names, which all end in `p', except for `atom'.
3219 ;; So, for instance, if you choose type `bufferp', then you can
3220 ;; choose a symbol whose value is a buffer, in order to act on that
3221 ;; buffer. A buffer is of course always named, but an object of type
3222 ;; `stringp' is not. The value of `emacs-version' is one such string
3223 ;; that you can act on.
3225 ;; Be aware that the action function you choose must accommodate the
3226 ;; object you choose as its only argument. Also, completion of the
3227 ;; function candidate itself is lax, so you can enter a lambda
3228 ;; expression as the action.
3230 ;; Objects that are naturally associated with names are treated
3231 ;; differently, depending on the type. Besides Anything types, the
3232 ;; following object types are used for named objects: `buffer',
3233 ;; `command', `face', `frame', `function', `option', `process',
3234 ;; `symbol', `variable', `window'. For all of these except `window',
3235 ;; the name of the object is used. For `window', the candidate
3236 ;; objects are the names of the buffers that are currently shown in a
3237 ;; window (on any frame).
3239 ;; You'll note that some types are treated both ways, 1) using named
3240 ;; objects and 2) using symbols whose values are objects. An example
3241 ;; is `frame' and `framep': the completion candidates (objects) for
3242 ;; type `frame' are frame names; the candidates for type `framep' are
3243 ;; symbols whose values are frames.
3247 ;; * (@> "Icicles with Anything")
3248 ;; * (@file :file-name "icicles-doc1.el" :to "Apropos Completions").
3249 ;; * (@file :file-name "icicles-doc1.el" :to "Progressive Completion").
3251 ;;(@* "Icicles with Anything")
3253 ;; Icicles with Anything
3254 ;; ---------------------
3256 ;; Library Anything (`anything.el') lets you define object types and
3257 ;; associate actions with them. It provides command `anything',
3258 ;; which you can use to apply an action to an object, choosing the
3259 ;; object first by name. All objects (of all types) that have a name
3260 ;; that matches your input are candidates. You can use command
3261 ;; `anything' while in Icicle mode; it has the same behavior with
3262 ;; Icicles as without it.
3264 ;; Icicles also integrates some Anything features within its own
3265 ;; completion environment, so that you can use Icicles features such
3266 ;; as progressive completion at the same time. In particular, you
3267 ;; can act on multiple Anything objects in the same command
3268 ;; invocation, and you can act on them using multiple Anything
3271 ;; Command `icicle-anything' (alias `any') is just command
3272 ;; `icicle-object-action' (alias `a') restricted to Anything types -
3273 ;; see (@> "Icicles OO: Object-Action Interaction"). It is more
3274 ;; convenient than `a' if you know that you want to use an Anything
3275 ;; type, because the set of type candidates to choose from is more
3278 ;; When you act on an object of an Anything type, you are not
3279 ;; prompted for the action ("how"). The default Anything action is
3280 ;; applied, or you can choose a different Anything action.
3282 ;; Command `any' (or command `a' when applied to an Anything type) is
3283 ;; a multi-command (see
3284 ;; (@file :file-name "icicles-doc1.el" :to "Multi-Commands")):
3286 ;; * `C-RET', `C-mouse-2', and so on perform the default Anything
3287 ;; action on each chosen object.
3289 ;; * `C-S-RET', `C-S-mouse-2', and so on, prompt you, for each chosen
3290 ;; object, to choose one or more Anything actions (with
3293 ;; You can thus act on any number of Anything objects in any number
3294 ;; of Anything ways, all in the same `any' command invocation. And
3295 ;; you can of course use Icicles completion and cycling to choose.
3296 ;; User option `icicle-anything-transform-candidates-flag' determines
3297 ;; whether Anything function `anything-transform-candidates' is
3298 ;; applied to displayed Anything candidates in Icicles.
3300 ;; Here's an example of using command `any'. Let's assume that you
3301 ;; have an `action' entry such as this in `anything-type-attributes'
3302 ;; for the Anything type `command':
3304 ;; (action ("Call interactively"
3305 ;; . (lambda (command-name)
3306 ;; (call-interactively (intern command-name))))
3307 ;; ("Describe command"
3308 ;; . (lambda (command-name)
3309 ;; (describe-function (intern command-name))))
3310 ;; ("Add command to kill ring" . kill-new)
3311 ;; ("Go to command's definition"
3312 ;; . (lambda (command-name)
3313 ;; (find-function (intern command-name)))))
3315 ;; This defines four actions for objects of type `command', the
3316 ;; default action being the first listed ("Call interactively").
3318 ;; You enter command `any', choose the Anything type `command', and
3319 ;; then choose the command `icicle-face-list' to act on:
3322 ;; What (type): command RET
3323 ;; Which (command): icicle-face-list RET
3325 ;; This invokes command `icicle-face-list', because the default
3326 ;; Anything action for an object of type `command' is to call it.
3328 ;; If you use `C-RET' instead of `RET' when choosing command
3329 ;; `icicle-face-list', then you remain within the `any' invocation,
3330 ;; and you can do something with another command after
3331 ;; `icicle-face-list'. If you use `C-S-RET' when choosing a command,
3332 ;; then you are prompted for the action to invoke for that command:
3334 ;; Which (command): icicle-face-list C-S-RET
3335 ;; How (action): Go to command's definition RET
3337 ;; If you choose the Anything action "Go to command's definition",
3338 ;; then, well, that's what happens: here, you go to the definition of
3339 ;; `icicle-face-list'. Again, you could use `C-RET' instead of
3340 ;; `RET', to perform this action on the command and then choose and
3341 ;; apply (via `RET' or `C-RET') another action to the same command.
3343 ;; After you've stopped (via `RET' or `C-g') acting on command
3344 ;; `icicle-face-list', you can clear the minibuffer (using `M-k') and
3345 ;; type another command to act on, and so on. Or, you can stop (via
3346 ;; `RET' or `C-g') and end the invocation of command `any'.
3348 ;; At each prompt, you can use (apropos or prefix) completion or
3349 ;; cycling to pick a candidate. So, for instance, using completion,
3350 ;; you could simply do this to choose `command', `icicle-face-list',
3351 ;; and "Go to command definition":
3353 ;; M-x any RET c RET face-l S-TAB C-S-RET g TAB RET
3355 ;; Icicles enhances Anything by providing multi-command features, as
3356 ;; well as by providing all of the other standard Icicles features:
3357 ;; apropos and prefix completion, cycling, progressive completion,
3358 ;; help on individual candidates, and so on. On the other hand,
3359 ;; Anything by itself provides some features that Icicles does not
3360 ;; exploit. The aim of command `any' is to give you the basic
3361 ;; Anything features in an Icicles completion context.
3363 ;; A significant behavior difference between Anything (that is,
3364 ;; command `anything') and Icicles command `any' is that with
3365 ;; `anything' only the object name is used for filtering, whereas
3366 ;; with Icicles command `any' you first narrow down the potential
3367 ;; candidates by type, before the object name is matched (against
3368 ;; objects of only that type).
3370 ;; That is, with Anything, your input pattern is matched against
3371 ;; every possible object of every possible type. You then choose
3372 ;; among the matches. If you want, after that wide-net matching you
3373 ;; can cycle among only the matches of a given type (e.g. file), but
3374 ;; matching against all other types has already taken place.
3376 ;; This behavior of starting with typeless matching can be convenient
3377 ;; sometimes (you need not specify the object type), but it can also
3378 ;; be inconvenient (and unnecessarily slow) to match objects of types
3379 ;; totally unrelated to what you're after. In such cases, it can
3380 ;; require either a long input pattern or cycling among more
3381 ;; candidates, to disambiguate among the hits.
3383 ;; With Icicles command `any', you have the inconvenience of needing
3384 ;; to specify first the type of object you want, but this has the
3385 ;; advantage of eliminating searching among irrelevant types.
3386 ;; Finally, remember that you can use both `anything' and `any' -
3387 ;; choose whichever is most convenient for the current task.
3389 ;;(@* "Multi-Completions")
3391 ;; Multi-Completions
3392 ;; -----------------
3394 ;; This section is about using completion candidates that are
3395 ;; composed of more than one part: strings that you can complete
3396 ;; against separately and simultaneously.
3398 ;;(@* "Icicles Multi-Completion Commands")
3399 ;; ** Icicles Multi-Completion Commands **
3401 ;; Have you ever used standard Emacs command `apropos-documentation'?
3402 ;; It searches the doc strings of all Emacs-Lisp symbols for matches
3403 ;; to an input regexp, and displays the hits. It can be useful when
3404 ;; you do not remember the name of a function or variable but you can
3405 ;; guess at terms that might occur in its doc string. Typically,
3406 ;; people resort to it only after first trying apropos commands that
3407 ;; match against the function or variable name.
3409 ;; The idea behind `apropos-documentation' also motivates Icicles
3410 ;; command `icicle-doc'. This is a multi-command (see
3411 ;; (@file :file-name "icicles-doc1.el" :to "Multi-Commands")),
3412 ;; so you can use `C-RET' and `C-next' to browse the regexp matches,
3413 ;; displaying the documentation of each match in turn, and you can
3414 ;; change the regexp to get different matches during the same command
3417 ;; Like `apropos-documentation', `icicle-doc' lets you match a regexp
3418 ;; against the doc strings of symbols such as functions, variables,
3419 ;; and faces. You can of course use progressive completion to match
3420 ;; multiple regexps. Here, for example, is a query that shows all doc
3421 ;; strings (functions, variables, faces - a lot! of doc strings)
3422 ;; that match both `mail' and `mode line', in either order,
3423 ;; as completion candidates:
3425 ;; M-x icicle-doc RET mail S-SPC mode line
3427 ;; You cannot do that with vanilla Emacs `apropos-documentation' or
3428 ;; with any other vanilla Emacs `apropos*' command.
3430 ;; Commands `icicle-vardoc', `icicle-fundoc', and `icicle-plist' are
3431 ;; similar to `icicle-doc' in the kind of functionality they provide.
3433 ;; Each of these commands gathers a tremendous amount of information
3434 ;; to construct an initial set of completion candidates based on all
3435 ;; existing Emacs symbols (in the standard `obarray'). This is
3436 ;; time-consuming. Since the set of symbols that have property lists
3437 ;; or that name functions, variables, or faces changes little, you
3438 ;; can optionally bypass this gathering and reuse the last initial
3439 ;; set of candidates for that command. You do this by invoking the
3440 ;; command using a prefix argument (non-negative prefix arg, for
3441 ;; `icicle-vardoc' and `icicle-plist').
3443 ;; Each of these particular commands also uses Icicles
3444 ;; multi-completion. A "multi-completion" is a completion candidate
3445 ;; that has multiple parts. A multi-completion command lets your
3446 ;; input match any or all parts individually, at the same time.
3448 ;; * Commands `icicle-vardoc' and `icicle-fundoc' let you match both
3449 ;; the function or variable name and the doc string.
3451 ;; * Command `icicle-doc' lets you match any combination of the
3454 ;; - the function, variable, or face name
3455 ;; - the type: FUNCTION, VARIABLE, or FACE (uppercase)
3458 ;; * Command `icicle-plist' lets you match both a symbol name and its
3459 ;; property list. You can use it to find symbols with certain
3460 ;; property-list keys or values. By default (for Emacs 22 or
3461 ;; later), plists are pretty-printed (in `*Help*' and
3462 ;; `*Completions*'), but if you use a negative prefix argument then
3463 ;; pretty-printing is skipped, gaining a little time.
3465 ;; * Command `icicle-describe-option-of-type' (bound to `C-h C-o' in
3466 ;; Icicle mode) lets you match both an option name and the option's
3467 ;; `defcustom' type definition. There are several ways to match
3468 ;; type definitions, controlled by the prefix argument - see the
3469 ;; command's doc string. You can match a type directly or taking
3470 ;; type inheritance into account. You can match a type as a sexp
3471 ;; or using a regexp. You can match a type expression or match the
3472 ;; option's current value against a type.
3474 ;; Other Icicles commands that use multi-completion include
3475 ;; `icicle-locate-file', `icicle-locate-file-other-window',
3476 ;; `icicle-recent-file', and `icicle-recent-file-other-window'.
3477 ;; These commands let you match against two-part multi-completion
3478 ;; candidates that are composed of an absolute file name and the
3479 ;; file's last modification date. This means that you can easily
3480 ;; find those notes you took sometime last week...
3482 ;; The way multi-completion commands work is a bit inelegant perhaps,
3483 ;; and it can take a little getting used to, but it is quite powerful
3484 ;; and lets you do things with completion that are otherwise
3487 ;; In the case of commands that use two-part multi-completions, you
3488 ;; provide two regexps as input, one to match the name of a symbol
3489 ;; (e.g. a function or variable) and one to match some associated
3490 ;; information (doc string, property list, or type definition).
3492 ;; However, since completion candidates are not actually multipart,
3493 ;; you in fact type a single regexp that is the concatenation of the
3494 ;; two. You join these two regexps using `icicle-list-join-string'
3495 ;; (a user option), which, by default, is `^G^J', that is, a
3496 ;; control-G character followed by a control-J (newline) character.
3497 ;; As always, you can input control characters using `C-q', so to
3498 ;; input `^G^J' you can use `C-q C-g C-q C-j'.
3500 ;; However, in Icicles, `C-j' (newline) is self-inserting during
3501 ;; completion, so you do not need to quote it with `C-q' - you can
3502 ;; use just `C-q C-g C-j'. Better yet, you can use `C-M-j'
3503 ;; (`icicle-insert-list-join-string') to insert `^G^J'.
3505 ;; This has the added benefit (in Emacs 22 or later) of hiding the
3506 ;; `^G' - it's there, but you do not see it. This hiding is only
3507 ;; cosmetic; you still match the characters `^G' and `^J'. In the
3508 ;; same way, Icicles hides the `^G' part of `^G^J' in
3509 ;; `*Completions*', so the join string appears as a newline
3512 ;; This hiding of `^G' happens only when option
3513 ;; `icicle-list-join-string' has its (ugly but useful) default value.
3514 ;; If not seeing the join string confuses you and you would prefer to
3515 ;; distinguish multi-completion part separators from ordinary newline
3516 ;; characters, then customize `icicle-list-join-string' - just remove
3517 ;; the following from the Lisp sexp that defines the default value:
3519 ;; (set-text-properties 0 1 '(display "") strg)
3521 ;; As an example of using a multi-completion command, you can use the
3522 ;; following to match a function name that contains `dired' and its
3523 ;; doc string that contains `file':
3525 ;; M-x icicle-fundoc dired^G^Jfile S-TAB
3527 ;; That is, you type this:
3529 ;; M-x icicle-fundoc dired C-q C-g C-j file S-TAB
3533 ;; M-x icicle-fundoc dired C-M-j file S-TAB
3535 ;; Well, almost. The way it actually works is that the completion
3536 ;; candidates are themselves formed by concatenating symbol names
3537 ;; with their doc strings, using `icicle-list-join-string'. Your
3538 ;; input regexp is matched against those candidates. This means that
3539 ;; the input regexp `dired^G^Jfile' would actually match only
3540 ;; function names that *end* with `dired' and doc strings that
3541 ;; *begin* with `file'.
3543 ;; To match `file' against any part of the doc string, you must
3544 ;; explicitly link the two component regexps with a regexp that
3545 ;; matches anything. If you want to search only the first lines of
3546 ;; doc strings, you can use `.*' to do that: `dired.*^G^J.*file' will
3547 ;; match all functions whose names contain `dired' and whose doc
3548 ;; strings' first lines contain `file'.
3550 ;; Why only the first lines? Because `.' matches any character
3551 ;; except a newline - it does not look past the first line. If you
3552 ;; want to search the entire doc strings (or property lists, for
3553 ;; `icicle-plist'), then you need to use a connecting regexp that
3554 ;; matches any character, including a newline. That means a regexp
3555 ;; such as `\(.\|\n\)'. Or you can just use the Icicles multi-line
3556 ;; dot feature - see (@> "Dot, Dot, Dot").
3558 ;; Without a multi-line dot, you would use something like this to
3559 ;; search whole, multi-line doc strings for `file':
3561 ;; M-x icicle-fundoc dired.*^G^J\(.\|\n\)*file S-TAB
3563 ;; That is, you would type (without the spaces):
3565 ;; M-x icicle-fundoc dired.* C-M-j \ ( . \ | C-j \ ) * file S-TAB
3567 ;; With a multi-line dot, you would type just this:
3569 ;; M-x icicle-fundoc dired.* C-M-j . * file S-TAB
3571 ;; What if you want to match, say, `file' in either the function name
3572 ;; or the doc string, not necessarily both? Remember that a
3573 ;; multi-completion is in fact a single string, with a separator such
3574 ;; as `^G^J' in the middle somewhere. Because it is a single string,
3575 ;; the simple minibuffer input `file' matches the substring `file'
3576 ;; anywhere in the multi-completion. So the answer is just this:
3578 ;; M-x icicle-fundoc file S-TAB
3580 ;; Even this simple command expression combines the effect of Emacs
3581 ;; commands `apropos-function' with that of `apropos-documentation'.
3583 ;;(@* "How Multi-Completions Work")
3584 ;; ** How Multi-Completions Work **
3586 ;; These commands that accept a multipart regexp are examples of
3587 ;; Icicles multi-completion. Icicles extends standard function
3588 ;; `completing-read' so that it will accept, as the set of completion
3589 ;; candidates, an alist argument whose candidates are not only
3590 ;; individual strings but can also be lists of strings. Each string
3591 ;; in the list is one part of a multipart completion candidate, that
3592 ;; is, a multi-completion. The strings are joined together pairwise
3593 ;; using `icicle-list-join-string' by `completing-read'. Commands
3594 ;; `icicle-fundoc' and`icicle-vardoc' each use lists of two strings
3595 ;; (name and doc), but a multi-completion can have any number of
3598 ;; Why is the default value of `icicle-list-join-string' so odd:
3599 ;; `^G^J'? You can use any string you like, but here is the
3600 ;; rationale behind the default choice:
3602 ;; - ^G does not normally occur in simple strings such as doc strings
3603 ;; - a newline (^J) visually separates the multiple component strings
3604 ;; - ^G^J is not too difficult to enter: `C-M-j' or `C-q C-g C-j'
3606 ;; It is important that the value of `icicle-list-join-string' not be
3607 ;; something that is, itself, likely to match any of the candidates.
3608 ;; Otherwise, it would not serve its role as separator.
3610 ;; I find that it helps a bit (in Emacs 22 or later) to customize
3611 ;; face `escape-glyph', which is used for control characters such as
3612 ;; `^G', in such a way that it stands out a bit, especially because
3613 ;; control characters can be used in regexps that also use `^' as a
3614 ;; special character. I use an orange background with a blue
3615 ;; foreground for this face.
3617 ;;(@* "Multi-Completions Let You Match Multiple Things in Parallel")
3618 ;; ** Multi-Completions Let You Match Multiple Things in Parallel **
3620 ;; Consider the command `describe-option-of-type', defined in my
3621 ;; library `help-fns+.el' (or `help+.el', for Emacs 20). This lets
3622 ;; you first pick a `defcustom' type using completion and then pick
3623 ;; an option of that type to describe. There are two separate,
3624 ;; sequential acts of completion. For each completion act, your
3625 ;; current input defines a set of matches. You can see all option
3626 ;; types that match, say, the regexp `.*string', which means all
3627 ;; types that contain `string'. After you choose one of those types,
3628 ;; you can see all options of that type whose names start with
3629 ;; `icicle' and then pick one.
3631 ;; You can thus tweak the type regexp to filter types, and you can
3632 ;; tweak the name regexp to filter option names. And you can of
3633 ;; course use progressive completion to whittle down either set of
3634 ;; matches, piecemeal.
3636 ;; What you cannot do, however, using `describe-option-of-type' is
3637 ;; filter both sets at the same time: narrow down the set of type
3638 ;; matches and name matches simultaneously. For that, you need
3639 ;; Icicles multi-completion. Without it, you must commit 100% to a
3640 ;; type before you can choose among the options of that type. With
3641 ;; it, you can change the type (or the name) part of your input
3642 ;; regexp on the fly, and see immediately the set of matching names
3643 ;; (or types) as well.
3645 ;;(@* "Multi-Completions vs `completing-read-multiple'")
3646 ;; ** Multi-Completions vs `completing-read-multiple' **
3648 ;; Note that there is (only) a superficial similarity between Icicles
3649 ;; multi-completion and the functionality provided by function
3650 ;; `completing-read-multiple' of standard Emacs library `crm.el'.
3651 ;; The latter lets you complete multiple strings in the minibuffer,
3652 ;; one at a time. It involves ordinary Emacs prefix completion, and
3653 ;; it uses the same set of completion candidates for each of the
3654 ;; strings in the input.
3656 ;; By contrast, Icicles multi-completion completes each part of your
3657 ;; input against a different set of completion candidates. For
3658 ;; example, when you use `icicle-vardoc', it completes the
3659 ;; variable-name part of your input against the names of defined
3660 ;; variables, and the variable-description part against the doc
3661 ;; strings of defined variables. Standard Emacs command
3662 ;; `completing-read-multiple' lets you complete several different
3663 ;; variable names at the same minibuffer prompt, but they each
3664 ;; complete against the same set of variable names.
3666 ;; Multi-completion matches a list of regexps in parallel. See also
3667 ;; the description of `M-*', which matches a list of regexps in
3668 ;; series: (@file :file-name "icicles-doc1.el" :to "Progressive Completion").
3669 ;; You can combine these features, of course.
3671 ;;(@* "Sorting Candidates by Their Second Part")
3672 ;; ** Sorting Candidates by Their Second Part **
3674 ;; Most multi-completions have two parts. Typically, the first part
3675 ;; is the main part, that is, the part that you will most frequently
3676 ;; complete against. Many candidate sort orders involve some flavor
3677 ;; of alphabetic order, and this means alphabetizing first with
3678 ;; respect to the first multi-completion part.
3680 ;; However, it can sometimes be convenient to sort instead by the
3681 ;; second part first. That is what the Icicles sort order "by 2nd
3682 ;; parts alphabetically" is for. You can use it, for example, with
3683 ;; command `icicle-locate-file' to sort file-name candidates first by
3684 ;; date, and then by file-name for the same date. This gives you an
3685 ;; easy way to look up files that you modified during a given time
3686 ;; period. For example, your input regexp can limit candidates to
3687 ;; those files last modified sometime in July, 2008, and you can then
3688 ;; access these chronologically (by cycling or in buffer
3689 ;; `*Completions*'). And do not forget that you can always reverse
3690 ;; the current sort order, using `C-N C-,' where N is an integer.
3694 ;; * (@> "Programming Multi-Completions") for information about
3695 ;; changing the appearance and behavior of Icicles
3696 ;; multi-completions using Emacs-Lisp code.
3698 ;; * (@file :file-name "icicles-doc1.el" :to "Sorting Candidates and Removing Duplicates")
3700 ;; * (@file :file-name "icicles-doc1.el" :to "Progressive Completion")
3702 ;;(@* "Dot, Dot, Dot")
3707 ;; This section is about dot, that is, `.', and its role as a regexp
3708 ;; special character in apropos completion.
3710 ;; Since the inception of regular-expression matching, `.' has
3711 ;; matched any character *except* a newline character (aka `^J', aka
3712 ;; `C-j'). Recent languages typically have an additional mode in
3713 ;; which `.' can match any character, including a newline. See, for
3714 ;; example, http://www.regular-expressions.info/dot.html and this
3715 ;; language comparison for regexp features:
3716 ;; http://www.regular-expressions.info/refflavors.html.
3718 ;; It is not unusual to manipulate multi-line completion candidates
3719 ;; in Icicles, in which case it can be handy to let `.' match any
3720 ;; character, including a newline. For this and more general
3721 ;; reasons, I long ago requested such a mode for Emacs, but there was
3722 ;; little interest in implementing it. In Emacs, dot never matches a
3723 ;; newline. Too bad.
3725 ;; The regexp `\(.\|[\n]\)' is good enough, of course: it matches any
3726 ;; character: any character any except newline, plus newline. But it
3727 ;; is a bit unwieldly, especially when used within a larger regexp,
3728 ;; and especially if used more than once in the same regexp.
3729 ;; Interactively, you input the `\n' using `C-j', and it appears in
3730 ;; the minibuffer as a newline character; that is, it creates another
3733 ;; For convenience in multi-line matching, I added a *multi-line
3734 ;; dot*, or dot-matches-newline-too, hack to Icicles. This feature
3735 ;; is turned off, by default. You can toggle it on/off, using
3736 ;; command `icicle-toggle-dot' (aka `icicle-toggle-.'), which is
3737 ;; bound to `C-M-.' in the minibuffer during completion.
3739 ;; When this is turned on, `.' is highlighted in the minibuffer
3740 ;; (using face `highlight'), and it matches newlines also. In fact,
3741 ;; although it appears as just a highlighted dot, the ugly regexp
3742 ;; `\(.\|[\n]\)' (the value of constant `icicle-anychar-regexp') is
3743 ;; really used, under the covers. Icicles takes care of things so
3744 ;; that you can edit normally (delete and transpose characters,
3745 ;; etc.): A multi-line `.' acts just like a normal, single character,
3746 ;; even though it is really a string of ten characters.
3748 ;; If you prefer to see the full regexp, `\(.\|[\n]\)', but
3749 ;; highlighted, then set option `icicle-dot-show-regexp-flag' to
3750 ;; non-`nil'. (In Emacs 20, the newline-matching dot is always shown
3751 ;; as that full regexp.) If you prefer to turn on newline matching
3752 ;; by default, then just customize option `icicle-dot-string'.
3754 ;; This match-anything dot is handy, but sometimes you might want to
3755 ;; match anything except a newline, perhaps in the same input pattern
3756 ;; where you also want to match any character (possibly a newline) at
3757 ;; other positions. How can you get the plain dot behavior, when
3758 ;; multi-line dot is turned on?
3760 ;; One way is just to use a regexp that matches anything except
3761 ;; newline: `[^\n]' (which you input using `[ ^ C-j ]'). Another way
3762 ;; is to use a plain prefix argument: `C-u .'. (A numeric prefix
3763 ;; argument N inserts N multi-line dots, each of which matches any
3764 ;; single character.)
3766 ;; `C-u' flips the behavior of `.' when you hit it: If by default `.'
3767 ;; enters a multi-line dot, then `C-u .' enters a plain dot. If by
3768 ;; default `.' enters a plain dot, then `C-u .' enters a multi-line
3769 ;; dot. So `C-u' also gives you a way to enter a one-off multi-line
3770 ;; dot, if you prefer to generally have `.' not match a newline.
3771 ;; Either way, what you see in the minibuffer is the single character
3772 ;; `.', highlighted if it is a multi-line dot, unhighlighted if it is
3775 ;; Multi-line dots are converted to plain dots automatically when you
3776 ;; use prefix completion. And if you then move back to apropos
3777 ;; completion during the same completion operation, you get back any
3778 ;; multi-line dots you had before, and any plain dots that you
3779 ;; entered before remain plain.
3781 ;; So when is a multi-line dot useful? Whenever you want to match
3782 ;; against multi-line candidates. Typical use cases include
3783 ;; `icicle-search' and the Icicles doc commands, `icicle-vardoc',
3784 ;; `icicle-fundoc', and `icicle-doc'.
3786 ;; Note that the dot-matching behavior described here applies only to
3787 ;; matching minibuffer input against completion candidates. It does
3788 ;; not mean that whenever you type `.' in the minibuffer it is
3789 ;; interpreted specially. For example, when you input (using `RET')
3790 ;; a regexp as the context pattern for Icicles search, a `.' has its
3791 ;; usual meaning in Emacs regexps - it does not match newlines.
3793 ;; If you want a regexp that you input (using `RET') to match any
3794 ;; character including a newline, then you can use `C-u C-=
3795 ;; icicle-anychar-regexp' to insert the proper string explicitly.
3796 ;; You can shorten this to just `C-=' if you use command
3797 ;; `icicle-save-string-to-variable':
3799 ;; M-x icicle-save-string-to-variable C-u C-= icicle-anychar-regexp
3803 ;; * (@> "Using Regexps with Icicles Search")
3804 ;; * (@file :file-name "icicles-doc1.el" :to "Inserting a Regexp from a Variable or Register")
3806 ;;(@* "Fuzzy Completion")
3811 ;; There are a few different kinds of what might be called "fuzzy"
3812 ;; matching used in Icicles completion, in addition to apropos
3813 ;; (regexp) matching and prefix matching. And if you have your own
3814 ;; method of matching then you can use that as well, by adding it to
3815 ;; option `icicle-S-TAB-completion-methods-alist'.
3817 ;; The following methods are predefined:
3819 ;; * Fuzzy - This method uses a fairly sophisticated matching
3820 ;; algorithm that seems to account for various typing mistakes.
3821 ;; This algorithm is provided by library `fuzzy-match.el', so I
3822 ;; call its use in Icicles `fuzzy' completion. You must have
3823 ;; library `fuzzy-match.el' to use this.
3825 ;; * Swank - Symbols are completed using the algorithm of
3826 ;; `el-swank-fuzzy.el' - see that library for details.
3828 ;; * Scatter - This is a simple, poor man's fuzzy matching method
3829 ;; that I call `scatter' matching. Ido calls it `flex' matching.
3830 ;; The TextMate editor has the same thing for file-name matching
3831 ;; (only), without naming it.
3833 ;; * Levenshtein - This method checks whether two strings differ by
3834 ;; at most a given number of character operations, the so-called
3835 ;; "Levenshtein distance". You must have library `levenshtein.el'
3838 ;; * Jaro-Winkler - This method gives matching weight to having both
3839 ;; (a) more characters that match in the right positions (Jara) and
3840 ;; (b) a longer exact prefix within the first four characters
3843 ;; My opinion about the relative usefulness of the various methods:
3844 ;; Basic (prefix) completion and apropos completion are by far the
3845 ;; most useful. They are followed, in order of decreasing
3846 ;; usefulness, by scatter, fuzzy, Levenshtein, vanilla, Jaro-Winkler,
3847 ;; and swank completion. YMMV.
3849 ;; Besides these methods, remember that you can get ordinary
3850 ;; substring matching with `S-TAB' by using `C-`' to turn off
3851 ;; (toggle) escaping of regexp special characters. With special
3852 ;; characters escaped, `S-TAB' does literal substring completion.
3854 ;; The type of completion matching that is used when you hit `S-TAB'
3855 ;; and `TAB' is controlled by user options
3856 ;; `icicle-S-TAB-completion-methods-alist' and
3857 ;; `icicle-TAB-completion-methods', respectively. The possible
3858 ;; methods for `TAB' are predefined, but you can add additional
3859 ;; methods for `S-TAB' by customizing
3860 ;; `icicle-S-TAB-completion-methods-alist'.
3862 ;;(@* "Changing Completion Method")
3863 ;; ** Changing Completion Method **
3865 ;; You can use fuzzy or swank completion in place of prefix
3866 ;; completion (`TAB'). You can use scatter, Levenshtein, or
3867 ;; Jaro-Winkler completion in place of apropos completion (`S-TAB').
3868 ;; You can change completion methods easily at any time, by hitting a
3869 ;; key in the minibuffer:
3871 ;; * `C-(' (command `icicle-next-TAB-completion-method') to cycle
3872 ;; among `TAB' completion methods: `basic', `vanilla', `fuzzy', and
3873 ;; `swank' (`vanilla' only for Emacs 23 and later; `fuzzy' only if
3874 ;; you have library `fuzzy-match.el'; `swank' only if you have
3875 ;; library `el-swank-fuzzy.el').
3877 ;; * `M-(' (command `icicle-next-S-TAB-completion-method') to cycle
3878 ;; `S-TAB' completion methods: `apropos', `scatter', `Levenshtein',
3879 ;; `Levenshtein strict', and `Jaro-Winkler' (only if you have the
3880 ;; Autocomplete library `fuzzy.el').
3882 ;; Repeating `C-(' and `TAB' or `M-(' and `S-TAB' on the fly for the
3883 ;; same input can be a good way to learn the differences between the
3884 ;; various completion methods.
3886 ;; If you provide a prefix argument to `C-(' or `M-(', then the newly
3887 ;; chosen method is used only for the current command. More
3888 ;; precisely, the previously active method is restored as soon as you
3889 ;; return to the top level.
3891 ;; The completion methods available for cycling via `C-(' or `M-('
3892 ;; are defined by options `icicle-TAB-completion-methods' and
3893 ;; `icicle-S-TAB-completion-methods-alist', respectively. By
3894 ;; default, the first method in each list is used for matching.
3896 ;; Sometimes you might want to make a different set of completion
3897 ;; methods available during input. You can use options
3898 ;; `icicle-TAB-completion-methods-per-command' and
3899 ;; `icicle-S-TAB-completion-methods-per-command' to do this. These
3900 ;; define the methods to be made available during specific commands
3901 ;; (that read input with completion). That is, they give you
3902 ;; command-specific control over `C-(' and `M-('.
3904 ;; The per-command control is provided by advising (`defadvice') the
3905 ;; particular commands. You can also do this interactively, using
3906 ;; commands `icicle-set-TAB-methods-for-command' and
3907 ;; `icicle-set-S-TAB-methods-for-command'. Invoking one of these
3908 ;; with a negative prefix argument removes the advice, restoring the
3909 ;; default choice of methods for the target command.
3911 ;; For example, this sets the available `TAB' methods for command
3912 ;; `icicle-read-color' to fuzzy (the default for this command) and
3915 ;; M-x icicle-set-TAB-methods-for-command RET
3916 ;; Command: icicle-read-color RET
3917 ;; TAB methods: fuzzy RET
3918 ;; TAB methods: basic RET
3921 ;; And this removes the special treatment for `C-(' during
3922 ;; `icicle-read-color', restoring the default `TAB' methods that are
3923 ;; defined by option `icicle-TAB-completion-methods':
3925 ;; C-- M-x icicle-set-TAB-methods-for-command RET
3926 ;; Command: icicle-read-color RET
3928 ;;(@* "Partial Completion")
3929 ;; ** Partial Completion **
3931 ;; This section pertains to Emacs releases starting with Emacs 23.
3933 ;; If option `icicle-TAB-completion-methods' includes `vanilla'
3934 ;; (which it does, by default), and you choose `vanilla' completion
3935 ;; for `TAB' (by cycling using `C-(' or by customizing
3936 ;; `icicle-TAB-completion-methods' to use `vanilla' as the default),
3937 ;; then Icicles `TAB' completion respects the standard Emacs option
3938 ;; `completion-styles', so the behavior of `TAB' is similar to what
3939 ;; it is in vanilla Emacs.
3941 ;; Emacs includes `partial-completion' in the default value of
3942 ;; `completion-styles'. This means that Icicles too will make use of
3943 ;; partial completion when you use `TAB' (with `vanilla'). Icicles
3944 ;; makes no use of `completion-styles' when you use `S-TAB'.
3946 ;; Partial completion is not really a kind of fuzzy completion, but
3947 ;; its effect can sometimes be similar. In some ways, it is similar
3948 ;; to scatter-match completion (see next), but it requires you to
3949 ;; explicitly mark where to skip ahead (using `*', ` ' (space), or
3952 ;; Icicles does not support using the mode `partial-completion-mode',
3953 ;; and Emacs itself is in the process of deprecating it, now that the
3954 ;; partial-completion style is active by default.
3956 ;; I do not necessarily recommend using `vanilla' for `TAB'
3957 ;; completion, or, if you do, including `partial-completion' as an
3958 ;; entry in `completion-styles', because its effect is often
3959 ;; counter-intuitive or confusing. But it is included by default in
3960 ;; Emacs, and Icicles supports it. You might find it useful in
3961 ;; file-name completion, to be able to complete directory components,
3964 ;;(@* "Scatter-Match Completion")
3965 ;; ** Scatter-Match Completion **
3967 ;; The idea behind scatter-match completion is very simple: input
3968 ;; characters are matched in order against completion candidates, but
3969 ;; possibly with intervening characters. That is, your input
3970 ;; scatter-matches a completion candidate if each character is also
3971 ;; in the candidate, and the character order is respected.
3973 ;; What this really amounts to is matching input `abc' as if it were
3974 ;; the regexp `a.*b.*c'. That's all.
3976 ;; You can use Icicles scatter matching at any time in place of
3977 ;; apropos (regexp) matching. Unlike the cases of swank and fuzzy
3978 ;; completion (see below), you can use it to complete file names
3981 ;;(@* "Swank (Fuzzy Symbol) Completion")
3982 ;; ** Swank (Fuzzy Symbol) Completion **
3984 ;; If you choose `swank' completion, what you get in Icicles is fuzzy
3985 ;; completion (see next), except regarding symbols. That is, swank
3986 ;; completion per se applies only to symbols. Symbols are completed
3987 ;; using the algorithm of `el-swank-fuzzy.el' - see that library for
3990 ;; Icicles options `icicle-swank-timeout' and
3991 ;; `icicle-swank-prefix-length' give you some control over the
3992 ;; behavior. When the `TAB' completion method is `swank', you can
3993 ;; use `C-x 1' (`icicle-doremi-increment-swank-timeout+') and `C-x 2'
3994 ;; (`icicle-doremi-increment-swank-prefix-length+') in the minibuffer
3995 ;; to increment these options on the fly using the arrow keys `up'
3998 ;; Swank symbol completion uses heuristics that relate to supposedly
3999 ;; typical patterns found in symbol names. It also uses a timeout
4000 ;; that can limit the number of matches. It is generally quite a bit
4001 ;; slower than fuzzy completion, and it sometimes does not provide
4002 ;; all candidates that you might think should match, even when all of
4003 ;; your input is a prefix (or even when it is already complete!).
4005 ;; If swank completion produces no match when you think it should,
4006 ;; remember that you can use `C-(' on the fly to change the
4007 ;; completion method.
4009 ;; I do not necessarily recommend swank symbol completion, but it is
4010 ;; available for those who appreciate it.
4012 ;; Like fuzzy completion (see next), swank completion always sorts
4013 ;; candidate symbols according to its own scoring, putting what it
4014 ;; thinks are the best matches first. This means that using `C-,' in
4015 ;; the minibuffer to sort candidates differently has no effect.
4017 ;;(@* "Fuzzy-Match Completion")
4018 ;; ** Fuzzy-Match Completion **
4020 ;; Fuzzy completion takes more explaining. It is described in detail
4021 ;; in the commentary of library `fuzzy-match.el'; please refer to
4022 ;; that documentation. Here are some things to keep in mind when you
4023 ;; use Icicles fuzzy completion:
4025 ;; * File-name completion is never fuzzy. Basic prefix completion is
4026 ;; used for file names.
4027 ;; * Fuzzy completion is always case-sensitive. This means that
4028 ;; `C-A' in the minibuffer has no effect on fuzzy completion.
4029 ;; * Fuzzy completion always takes a space prefix in your input into
4030 ;; account. This means that `M-_' in the minibuffer has no effect
4031 ;; on fuzzy completion.
4032 ;; * Fuzzy completion candidates are always sorted by decreasing
4033 ;; match strength. This means that using `C-,' in the minibuffer
4034 ;; to sort candidates differently has no effect.
4036 ;; Fuzzy completion is a form of prefix completion in which some
4037 ;; input characters might not be present in a matched candidate.
4038 ;; Matching finds the candidates that have the most characters in
4039 ;; common with your input, in the same order and with a minimum of
4040 ;; non-matching characters. It can skip over non-matching
4041 ;; characters, as long as the number of characters skipped in the
4042 ;; candidate is less that those following them that match. After the
4043 ;; matching candidates are found, they are sorted by skip length and
4044 ;; then candidate length.
4046 ;; Here are some examples:
4048 ;; Input Completion Domain Matches (Candidates)
4049 ;; ----- ----------------- --------------------
4051 ;; abc {xxabcxx, xabcxxx,
4052 ;; xabx} {xabcxxx, xxabcxx}
4054 ;; point-mx Emacs variables {point-max, point-max-marker}
4056 ;; begining-of-l Emacs commands {beginning-of-line,
4057 ;; beginning-of-line-text,
4058 ;; move-beginning-of-line,
4059 ;; widget-beginning-of-line}
4061 ;; The last example shows that although fuzzy matching is a kind of
4062 ;; prefix matching, your input is not necessarily a prefix of each
4063 ;; matching candidate. It is prefix matching because it tries to
4064 ;; match your input starting at its beginning. This input prefix is
4065 ;; matched against candidate substrings, not necessarily candidate
4066 ;; prefixes, but the non-matching part (if any) preceding the matched
4067 ;; substring must not be longer than the matching part. That is,
4068 ;; non-matching substrings can be skipped over, but they must be no
4069 ;; longer than the matching substrings that follow them. If an input
4070 ;; prefix does not match under these conditions, it is skipped over.
4072 ;; After matching an input prefix this way, the same process is
4073 ;; repeated, recursively, for input text following that prefix and
4074 ;; for match positions following the matches found. That is, after
4075 ;; each such prefix match, the process starts again where it left off
4076 ;; in both the input and the candidates. The resulting matches
4077 ;; contain one or more substrings of your input that are each at
4078 ;; least as long as the non-matching parts that immediately precede
4079 ;; them. Only matches with the highest number of matching characters
4080 ;; are retained. They are sorted by two criteria: (1) nearness of
4081 ;; matches to the start of the candidate and (2) candidate length.
4083 ;; The fuzzy-match algorithm is detailed in library `fuzzy-match.el'.
4084 ;; However, it is easier to get a feel for what it does by trying it
4085 ;; than by reading any description. Just give it a try. Do not
4086 ;; expect it to rival apropos completion in power or expressivity,
4087 ;; however. Instead, think of it as prefix completion for lazy or
4088 ;; inaccurate typists! If that sounds like you, then you might find
4091 ;; As an example, here are some command-name candidates for the input
4092 ;; `fo' (there are lots more):
4094 ;; fortune forms-mode focus-frame
4095 ;; follow-mode forward-sexp forward-list
4096 ;; forward-word forward-line forward-page
4098 ;; ifconfig info Info-up
4099 ;; Info-edit Info-next Info-help
4101 ;; Info-mouse-follow-nearest-node Info-goto-emacs-key-command-node
4103 ;; And here are all the command-name candidates for the input `fol':
4105 ;; follow-mode follow-delete-other-windows-and-split
4106 ;; Info-last info-lookup-file info-lookup-reset
4107 ;; Info-last-preorder info-lookup-symbol Info-last-menu-item
4108 ;; nnfolder-generate-active-file mh-folder-mode
4110 ;; The first thing to notice is the distribution of candidates for
4111 ;; input `fo'. Candidates are in decreasing order of match fit:
4113 ;; * The nearer the match to the start of the candidate, the better
4116 ;; * The greater the ratio of matched text to unmatched text, the
4119 ;; Note too the candidate `ifconfig'. First, note that it has no
4120 ;; strict match for substring `fo'. Its match is in fact in two
4121 ;; parts: `f', then `o'. Second, note that it is considered a better
4122 ;; fuzzy match than the candidate `info'. This is because its match
4123 ;; (`f') is nearer to the start of the candidate (second character,
4126 ;; The second thing to notice is that when you type the third input
4127 ;; character, `l', the candidates are not a subset of the original
4128 ;; set that matches `fo'. The candidates in the second screenshot
4129 ;; all match `fol' in a fuzzy way, even though one of them,
4130 ;; `mh-folder-mode', does not match `fo' sufficiently well to be
4131 ;; included as a candidate. Why? Because in the `fo' case, the
4132 ;; match is only two characters long and it starts after three
4133 ;; non-matching characters.
4135 ;; For both inputs: If all input prefixes are fair game for matching,
4136 ;; why doesn't `*Completions*' also include other command names that
4137 ;; match only the prefix `f' and nothing else? Because there is at
4138 ;; least one match that matches more than that - only the best
4139 ;; matches are retained. In this case, the best matches for input
4140 ;; `fo' match both the `f' and the `o', and the best matches for
4141 ;; input `fol' match all three of those characters.
4143 ;; Refer to `fuzzy-match.el' for a precise description of fuzzy
4144 ;; matching. It refers to "matchiness" for how many characters match
4145 ;; and "closeness" for the ratio of number of characters matched to
4146 ;; candidate length.
4148 ;; Note: It is not practical to try to highlight the exact candidate
4149 ;; portions that match different parts of your input. Because
4150 ;; fuzzy-match input does not function as a literal string for
4151 ;; matching purposes, it is more akin to substring matching than to
4152 ;; plain prefix matching. For this reason, regexp-match highlighting
4153 ;; is used for fuzzy matching. That is why you see the input `fo'
4154 ;; highlighted in `*Completions*' candidates in other than just the
4155 ;; prefix position. It is also why the matching `f' and `o' in
4156 ;; candidate `ifconfig' are not highlighted: for highlighting
4157 ;; purposes, your input is treated as a regexp.
4159 ;; One takeaway here is that fuzzy completion is complicated. Rather
4160 ;; than try to understand how it works and think ahead in those
4161 ;; terms, you just need to get a feel for it - learn by doing. Have
4164 ;;(@* "Levenshtein Completion")
4165 ;; ** Levenshtein Completion **
4167 ;; The "Levenshtein distance" is the maximum number of character
4168 ;; insertions, deletions, or replacements that are needed to
4169 ;; transform one string to another. The more similar two strings
4170 ;; are, the smaller their Levenshtein distance.
4172 ;; When this kind of completion is used, Icicles considers your input
4173 ;; to match a completion candidate if their Levenshtein distance is
4174 ;; no greater than the value of option `icicle-levenshtein-distance'.
4175 ;; The default value of the option is 1, meaning that the difference
4176 ;; is at most one character operation.
4178 ;; Using a strict definition of the distance, this also requires the
4179 ;; length of your input to be within the Levenshtein distance of the
4180 ;; length of a completion candidate, for it to match. That is quite
4183 ;; It is more flexible to consider your input to match a candidate if
4184 ;; it is within `icicle-levenshtein-distance' of some *substring* of
4185 ;; the candidate. Because candidate substrings are tested, the
4186 ;; length of your input need not be nearly the same as the candidate
4189 ;; When you cycle among `S-TAB' completion methods using `M-(', there
4190 ;; are thus two choices for Levenshtein completion: `Levenshtein' and
4191 ;; `Levenshtein strict'. The former is generally more useful.
4193 ;; The larger the value of `icicle-levenshtein-distance', the slower
4194 ;; Levenshtein completion becomes, since it must test more
4195 ;; possibilities. Also, when the value is 1 (except for `Levenshtein
4196 ;; strict'), Icicles uses a fast, special-case algorithm, and it
4197 ;; highlights the matching parts of candidates in buffer
4198 ;; `*Completions*'. 1 is the most useful value.
4200 ;; If the value is other than 1 (or if it is 1 with `Levenshtein
4201 ;; strict'), then you must also use library `levenshtein.el', and
4202 ;; Levenshtein completion can be quite slow. In that case, you will
4203 ;; no doubt want to turn off incremental completion (`C-#').
4205 ;;(@* "Jaro-Winkler Completion")
4206 ;; ** Jaro-Winkler Completion **
4208 ;; The Jaro-Winkler method was developed for comparing names for the
4209 ;; U.S. census. It tends to take into account some typical spelling
4210 ;; mistakes, and it is best suited for use with short candidates.
4212 ;; When checking whether two strings match, higher matching weight
4213 ;; results when there are more characters in each string that are
4214 ;; also present in the other, and in approximately the same
4217 ;; Looking only at those characters that nearly match in this sense
4218 ;; (same character in about the same position), the more exact
4219 ;; matches there are (same character in exactly the same position),
4220 ;; the higher the matching weight. That is, weight is reduced for
4221 ;; characters that nearly match but are not quite in the right
4224 ;; So far, this describes Jaro matching. The Jaro matching weight is
4225 ;; the average of three values; (a) the ratio of the first string's
4226 ;; near matches to its length, the same for the second string, and
4227 ;; (c) the ratio of exact matches to total matches (near and exact).
4229 ;; The Winkler part of the method comes from giving additional weight
4230 ;; for prefixes that match exactly. The longer the exact prefix
4231 ;; match (up to 4 characters) the greater the weight.
4233 ;; Unlike the other matching methods, for Jaro-Winkler to complete
4234 ;; your input it must have the same number of characters as the
4235 ;; candidate to be matched, plus or minus two (actually
4236 ;; `fuzzy-accept-length-difference'). In particular, this means that
4237 ;; you cannot hit `S-TAB' with an empty minibuffer to see all of the
4242 ;; * (@file :file-name "icicles-doc1.el" :to "Icicles Multi `M-x'")
4243 ;; for completion of command abbreviations
4245 ;; * (@file :file-name "icicles-doc1.el" :to "Apropos Completions")
4246 ;; for completion with regexp matching
4248 ;; * http://en.wikipedia.org/wiki/Jaro-Winkler_distance for
4249 ;; information about Jaro-Winkler matching
4251 ;;(@* "Completion in Other Buffers")
4253 ;; Completion in Other Buffers
4254 ;; ---------------------------
4256 ;; In addition to input completion, you can use Icicles to complete
4257 ;; words and symbols in other buffers, besides the minibuffer.
4258 ;; Icicles enhances this completion in these ways:
4260 ;; 1. Lisp symbol completion via `M-TAB' (`lisp-complete-symbol').
4261 ;; (This is also `ESC-TAB' and `C-M-i'.)
4263 ;; 2. Word completion using the dynamic abbreviation of standard
4264 ;; Emacs library `dabbrev.el', via `C-M-/'.
4266 ;; 3. Mailing information completion for BBDB (Insidious Big Brother
4269 ;; 4. Word completion using the words and phrases in a thesaurus, via
4270 ;; `C-c /' (requires library `synonyms.el').
4272 ;; 5. `TAB' completion of the following in Shell mode and ESS modes
4273 ;; (and other, similar interpreters):
4276 ;; * Previous inputs - commands plus their arguments
4278 ;; * Environment variables
4280 ;; Whenever multiple completion candidates are available, you can use
4281 ;; Icicles completion, with all of its features: cycling of
4282 ;; candidates (`TAB', `down', or `next'), apropos (regexp) completion
4283 ;; (`S-TAB'), progressive completion (`M-SPC'), help on individual
4284 ;; candidates (`C-M-RET'), and so on.
4286 ;;(@* "Dynamic Abbreviation")
4287 ;; ** Dynamic Abbreviation **
4289 ;; Library `dabbrev.el' lets you type a few characters in a buffer
4290 ;; and then prefix-complete them (in the same buffer) to a full word
4291 ;; or symbol name. The completion candidates come from words or
4292 ;; symbol names in buffers that you are editing. This functionality
4293 ;; is called "dynamic abbreviation", though that is not a very good
4294 ;; term for it (words are completed, not abbreviated, dynamically).
4296 ;; In Emacs, there are two ways to "dynamically abbreviate" text:
4298 ;; a. `M-/' (command `dabbrev-expand') completes to a candidate word.
4299 ;; Repeating it replaces the completion with a different one -
4300 ;; that is, it cycles candidates in the text buffer (not in the
4303 ;; b. `C-M-/' (command `dabbrev-completion') completes to the common
4304 ;; prefix of all matching completion candidates. Repeating it
4305 ;; displays buffer `*Completions*' for you to choose a candidate.
4306 ;; However, in this case, there is no way to cycle among the
4309 ;; If there are many candidate completions, then cycling among them
4310 ;; with `M-/' can be tedious. You can use `C-M-/' to complete to a
4311 ;; common prefix, thus narrowing the set of candidates, but then you
4312 ;; lose the ability to cycle among them.
4314 ;; If user option `icicle-functions-to-redefine' contains an entry
4315 ;; for `dabbrev-completion' (which it does by default) then Icicles
4316 ;; redefines command `dabbrev-completion' (it does not change
4317 ;; `dabbrev-expand') so that it uses Icicles completion when there
4318 ;; are multiple completions. You can use any Icicles features, such
4319 ;; as apropos completion and candidate cycling. In addition, you can
4320 ;; even complete an empty prefix, starting from scratch with apropos
4323 ;;(@* "BBDB Completion")
4324 ;; ** BBDB Completion **
4326 ;; Library `bbdb.el', available at http://bbdb.sourceforge.net/, is a
4327 ;; rolodex-like database program for GNU Emacs.
4329 ;; If user option `icicle-functions-to-redefine' contains an entry
4330 ;; for `bbdb-complete-name' (which it does by default) then Icicles
4331 ;; redefines command `bbdb-complete-name' so that it uses Icicles
4332 ;; completion when there are multiple completions. You can use any
4333 ;; Icicles features, such as apropos completion and candidate
4334 ;; cycling. For this feature to take effect, you must load BBDB
4335 ;; before you load Icicles.
4337 ;;(@* "Thesaurus Lookup and Completion")
4338 ;; ** Thesaurus Lookup and Completion **
4340 ;; Library `synonyms.el' provides various features for defining a
4341 ;; thesaurus and looking up words and phrases in it. Icicles
4342 ;; provides a multi-command version (alias `icicle-synonyms') of the
4343 ;; command `synonyms', which shows all of the synonyms that match a
4344 ;; regular expression (e.g. a word or phrase) and lets you navigate
4345 ;; among hyperlinked thesaurus entries.
4347 ;; Command `icicle-complete-thesaurus-entry' completes a word in a
4348 ;; text buffer to any word or phrase in the thesaurus. With the
4349 ;; default value of option `icicle-top-level-key-bindings', this is
4350 ;; bound to `C-c /' in Icicle mode.
4352 ;; Tip: You can use `icicle-complete-thesaurus-entry' to quickly
4353 ;; check the spelling of a word. If it is correctly spelled, then it
4354 ;; appears as a complete completion (is highlighted as such in the
4357 ;; Another Icicles (multi-)command that uses the thesaurus is
4358 ;; `icicle-insert-thesaurus-entry'. It lets you use Icicles
4359 ;; completion, cycling, and so on to insert thesaurus words and
4360 ;; phrases in any buffer. It does not complete the word at point.
4361 ;; Within a single call to it, insert any number of thesaurus
4362 ;; entries, in succession. If you wanted to, you could write an
4363 ;; entire book using a single call to
4364 ;; `icicle-insert-thesaurus-entry'!
4366 ;; All of these Icicles commands require that you load library
4369 ;;(@* "Completion in Comint Modes")
4370 ;; ** Completion in Comint Modes **
4372 ;; `TAB' in a shell or similar buffer provides Icicles completion for
4373 ;; command names, file names, and environment variables that are
4374 ;; known to the shell (or other interpreter).
4376 ;; You can also complete input using your previous inputs as the set
4377 ;; of candidates. Just type something at the prompt, hit `C-c `',
4378 ;; and pick one or more previous inputs to execute again (this uses
4379 ;; `icicle-search', so it is a multi-command). You need not
4380 ;; re-execute the exact same shell command; you can edit your
4381 ;; previous input before hitting `RET' to enter the command.
4383 ;; These features are available for Comint mode and several modes
4384 ;; that inherit from it, including Shell mode, Shell Script (SH)
4385 ;; mode, various ESS modes (Emacs Speaks Statistics), Inferior
4386 ;; Emacs-Lisp mode (IELM), Grand Unified Debugger (GUD) mode, Tcl
4387 ;; mode, Rlogin mode, and NS Lookup mode.
4391 ;; * (@> "Icicles Shell-Command Enhancements") for more information
4392 ;; about Icicles enhancements for Comint mode and related modes
4394 ;; * (@> "Other Icicles Search Commands") for information about other
4395 ;; Icicles search enhancements for Comint mode and related modes
4397 ;; * (@> "Defining Buffer-Text Completion for Comint Modes") for
4398 ;; information about how you can add Icicles completion to other
4399 ;; modes that inherit from Comint mode
4401 ;;(@* "Customization and General Tips")
4403 ;; Customization and General Tips
4404 ;; ------------------------------
4406 ;; This section contains some tips on using Icicles and descriptions
4407 ;; of Icicles user options.
4411 ;; * (@> "File-Name and Directory-Name Completion Tips") for tips on
4412 ;; using Icicles to complete file names. User options related to
4413 ;; file-name and directory-name completion are presented there, not
4416 ;; * (@file :file-name "icicles-doc1.el" :to "Dealing With Large Candidate Sets")
4417 ;; for tips on improving performance when dealing with a large
4418 ;; number of completion candidates.
4420 ;; * (@> "Customizing Key Bindings") for information on customizing
4421 ;; Icicles key bindings.
4423 ;;(@* "Using Icicles with Delete Selection Mode")
4424 ;; ** Using Icicles with Delete Selection Mode **
4426 ;; Icicles works especially well with Delete Selection mode, which I
4427 ;; use and recommend. (Likewise, for PC selection mode, which uses
4428 ;; Delete Selection mode.) In Delete Selection mode, whenever the
4429 ;; region (selection) is active (highlighted), you can simply type to
4430 ;; replace text in the region, or hit `DEL' (Backspace) or `C-d'
4431 ;; (Delete) to delete the region.
4433 ;; However, library `delsel.el', which provides Delete Selection
4434 ;; mode, binds keys in minibuffer maps that are also bound by
4435 ;; Icicles. For this reason, if you use both Icicles and Delete
4436 ;; Selection mode, you must turn on Icicle mode after you turn on
4437 ;; Delete Selection mode. If you forget to do this, you will notice
4438 ;; that `C-g' does not abort minibuffer input. The remedy is simply
4439 ;; to turn Icicle mode off, then on again.
4441 ;;(@* "Icicles User Options and Faces")
4442 ;; ** Icicles User Options and Faces **
4444 ;; There are many user options (user variables) and several faces
4445 ;; that Icicles defines, and you can also use various standard user
4446 ;; options, including Icomplete options, that control various aspects
4449 ;; One thing that can be important to understand is that if you
4450 ;; customize an option, and if the default value of that option
4451 ;; changes later in a more recent Icicles version, then your
4452 ;; customization will preclude your taking advantage of any new
4453 ;; features represented by that default option value.
4455 ;; This is important particularly for complex options such as
4456 ;; `icicle-top-level-key-bindings'. Taking that option as an
4457 ;; example, if Icicles later adds more commands with default key
4458 ;; bindings then you will not see those bindings if you have a
4459 ;; customized value of `icicle-top-level-key-bindings'. There is
4460 ;; nothing wrong with that; I just want you to be aware of it.
4462 ;; In general, it can be a good idea to look at the latest change-log
4463 ;; entry for `icicles-opt.el' in `icicles-chg.el', to see what
4464 ;; changes have been made. If you then want to take advantage of
4465 ;; some change, you can use `M-x customize option' and visually
4466 ;; compare your customized value with the new default value in
4467 ;; `icicles-opt.el', then edit your customized value as you like.
4469 ;; * User option `icicle-mode-hook' is a normal hook containing
4470 ;; functions that are run after entering and exiting Icicle mode.
4471 ;; This is `nil', by default.
4473 ;; * User option `icicle-minibuffer-setup-hook' is a list of
4474 ;; functions to be run at the end of minibuffer setup for Icicle
4475 ;; mode. This is `nil', by default.
4477 ;; * User option `icicle-update-input-hook' is a list of functions to
4478 ;; be run when minibuffer input is updated (typing or deleting).
4479 ;; This is `nil', by default.
4481 ;; * User option `icicle-no-match-hook' is a list of functions to be
4482 ;; run during completion (`TAB' or `S-TAB') when there are no
4483 ;; completion candidates that match the current input. This is
4484 ;; `nil', by default.
4486 ;; * Case sensitivity: The following standard user options control
4487 ;; whether completion distinguishes between uppercase and lowercase
4490 ;; * `completion-ignore-case'
4491 ;; * `read-file-name-completion-ignore-case' (Emacs 22 and later)
4492 ;; * `read-buffer-completion-ignore-case' (Emacs 23 and later)
4494 ;; In addition, you can toggle case-sensitivity at any time using
4495 ;; `C-A' (that is, `C-S-a') in the minibuffer. This toggles
4496 ;; `case-fold-search' and `completion-ignore-case'. With a prefix
4497 ;; argument, it also toggles
4498 ;; `read-file-name-completion-ignore-case' and
4499 ;; `read-buffer-completion-ignore-case'.
4501 ;; More precisely, it toggles the default value of
4502 ;; `case-fold-search', and then it sets the other variables to the
4503 ;; value of `case-fold-search'. Because the default value of
4504 ;; `case-fold-search' is changed, all buffers are affected. Note
4505 ;; that because some Icicles commands bind one or more of these
4506 ;; variables, toggling case-sensitivity during command execution
4507 ;; will not necessarily toggle their global values.
4509 ;; You can tell whether completion is currently case-sensitive by
4510 ;; looking at the Icicle minor-mode lighter in the mode line, if
4511 ;; `icicle-highlight-lighter-flag' is non-`nil'. If
4512 ;; case-sensitive, then the lighter text (with or without
4513 ;; multi-command symbol `+') is `Icy'; if not, it is `ICY'.
4515 ;; * User options `icicle-region-background',
4516 ;; `icicle-point-position-in-candidate',
4517 ;; `icicle-mark-position-in-candidate', and
4518 ;; `icicle-change-region-background-flag' are all used to define
4519 ;; the region (the selected text) when cycling completion
4520 ;; candidates. They are described below individually. The region
4521 ;; is active when cycling, so you can easily delete it or replace
4524 ;; * User option `icicle-point-position-in-candidate' defines the
4525 ;; minibuffer cursor position (point) while cycling candidate
4526 ;; completions. By default, the cursor is placed at the end of the
4527 ;; root being completed. You can instead place it at the root
4528 ;; beginning or at the beginning or end of the complete minibuffer
4529 ;; input. For file-name input, the beginning of minibuffer input
4530 ;; starts after the directory name (which is inserted
4533 ;; * Similarly, user option `icicle-mark-position-in-candidate'
4534 ;; defines the position of the mark; by default, it is at the end
4535 ;; of the input. Together, these two options control the size and
4536 ;; placement of the region in a flexible way. You can make the
4537 ;; region include all of the input, only the root, from beginning
4538 ;; to root, or from root to end. You can put the cursor at either
4539 ;; end of the region. You can get rid of the region altogether, by
4540 ;; making point and mark coincide (at any of the possible
4543 ;; * Because the region background color is often quite different
4544 ;; from the frame background color (in order to have it stand out),
4545 ;; it can be a bit hard to read the completion candidates when the
4546 ;; region is highlighted during input cycling. If user option
4547 ;; `icicle-change-region-background-flag' is non-`nil', however,
4548 ;; then the region background is changed to a color that differs
4549 ;; only slightly from the frame background, making it easier to
4550 ;; read the completion candidates. The actual background color
4551 ;; used is the value of `icicle-region-background', which you can
4552 ;; customize. If you make this color the same as the frame
4553 ;; background, then the region background is, in effect, invisible.
4555 ;; * The default value of `icicle-change-region-background-flag' is
4556 ;; determined by the current value of `delete-selection-mode', that
4557 ;; is, whether or not Delete Selection mode is enabled, when
4558 ;; Icicles is loaded. For this reason, if you use Delete Selection
4559 ;; mode and you want the region background to change in the
4560 ;; minibuffer, you should either turn on Delete Selection mode
4561 ;; before loading `icicles.el' or explicitly customize
4562 ;; `icicle-change-region-background-flag' to non-`nil'.
4564 ;; * User option `icicle-default-value' controls the treatment of a
4565 ;; default value for minibuffer input. This includes not only
4566 ;; functions that read input with completion (`completing-read',
4567 ;; `read-file-name'), but also other input-reading functions:
4568 ;; `read-from-minibuffer' and `read-string'. The default value of
4569 ;; `t' gives the vanilla Emacs behavior: `completing-read' adds the
4570 ;; default input value to the prompt as a hint (but
4571 ;; `read-file-name' does not). Non-`nil' and non-`t' means to
4572 ;; automatically insert the default input value into the minibuffer
4573 ;; as the initial value. I prefer to have it inserted, as I often
4574 ;; use the default value (perhaps editing it). A value of `nil'
4575 ;; neither inserts the default value nor adds it to the prompt. If
4576 ;; the value is `t' or `nil', remember that you can always insert
4577 ;; the default value manually with `M-n'. If the value is neither
4578 ;; `t' nor `nil', you can always use `M-p' to remove the default
4579 ;; value from the minibuffer.
4581 ;; A non-`nil', non-`t' value of `icicle-default-value' controls
4582 ;; also whether or not the initial value is preselected, and where
4583 ;; to leave the cursor: at the beginning or end of the value.
4584 ;; Preselecting the value can be useful in Delete Selection mode or
4585 ;; PC Selection mode, because it makes it easy to replace that
4586 ;; value by typing characters, or delete it by hitting `DEL'
4587 ;; (Backspace) or `C-d' (Delete). However, all of the initial
4588 ;; input is lost if you type or hit `C-d' or `DEL', which is
4589 ;; inconvenient if you want to edit it only slightly.
4591 ;; * User options `icicle-thing-at-point-functions' and
4592 ;; `icicle-default-thing-insertion' control the behavior of `M-.'
4593 ;; in the minibuffer, which grabs text from the current buffer and
4594 ;; yanks it into the minibuffer.
4595 ;; See (@file :file-name "icicles-doc1.el" :to "Inserting Text Found Near the Cursor")
4596 ;; and the doc string (`C-h v') of
4597 ;; `icicle-thing-at-point-functions' for more information.
4599 ;; * User option `icicle-comint-dynamic-complete-replacements'
4600 ;; specifies a list of function replacements for
4601 ;; `icicle-comint-dynamic-complete' to replace the functions in
4602 ;; `comint-dynamic-complete-functions'. You can use this to
4603 ;; provide Icicles completion for various modes that inherit from
4604 ;; Comint mode. By default, it treats Comint mode and Shell mode.
4606 ;; * User option `icicle-input-string' is a regexp string that is
4607 ;; inserted in the minibuffer when you use `C-='. See
4608 ;; (@file :file-name "icicles-doc1.el" :to "Inserting a Regexp from a Variable or Register").
4610 ;; * In buffer `*Completions*', face `icicle-historical-candidate' is
4611 ;; used to highlight completion candidates that you have used
4612 ;; (entered with `RET') previously. This highlighting is
4613 ;; controlled by user option
4614 ;; `icicle-highlight-historical-candidates-flag'. You can toggle
4615 ;; this option from the minibuffer at any time using `C-pause'.
4616 ;; See (@file :file-name "icicles-doc1.el" :to "History Enhancements").
4618 ;; * In buffer `*Completions*', face `icicle-saved-candidate' is used
4619 ;; to highlight completion candidates that you have saved (e.g.,
4620 ;; using `C-M->'). This highlighting is controlled by user option
4621 ;; `icicle-highlight-saved-candidates-flag'. You can toggle this
4622 ;; option from the minibuffer at any time using `S-pause'.
4623 ;; See (@file :file-name "icicles-doc1.el" :to "Saving and Retrieving Completion Candidates").
4625 ;; * In buffer `*Completions*', face
4626 ;; `icicle-current-candidate-highlight' highlights the current
4627 ;; completion candidate, and, provided user option
4628 ;; `icicle-expand-input-to-common-match-flag' is non-`nil', face
4629 ;; `icicle-common-match-highlight-Completions' highlights the
4630 ;; expanded common match among all completions. Faces
4631 ;; `icicle-match-highlight-Completions' and
4632 ;; `icicle-match-highlight-minibuffer' highlight whatever your
4633 ;; input matches, in buffer `*Completions*' and in the minibuffer,
4634 ;; respectively. In the minibuffer, face `icicle-complete-input'
4635 ;; highlights your input when it is complete.
4637 ;; * Non-`nil' user option `icicle-touche-pas-aux-menus-flag' means
4638 ;; that Icicles will not add menu items to menu-bar menus, except
4639 ;; for the Icicles and Minibuf menus. Default value `nil' means
4640 ;; that whenever an appropriate menu-bar menu exists, Icicles items
4641 ;; are added to it (when in Icicle mode). For example, if `nil',
4642 ;; then Delete File is added to the File menu; otherwise it is
4643 ;; added to the Icicles menu. The value of this option is used
4644 ;; only when Icicle mode is initially established, so changing it
4645 ;; has no effect after Icicles has been loaded. However, you can
4646 ;; change it and save the new value, so it will be used next time.
4648 ;; * User option `icicle-functions-to-redefine' controls whether
4649 ;; Icicles redefines some standard functions, enhancing them to use
4650 ;; Icicles completion. You can specify which functions to
4651 ;; redefine. The original function definitions are restored when
4652 ;; you exit Icicle mode.
4654 ;; * Option `icicle-inhibit-advice-functions' is a list of functions
4655 ;; that Icicles redefines, and for which Icicle mode deactivates
4656 ;; the advice. The advice for each is reactivated when you leave
4657 ;; Icicle mode. Generally, it is a bad idea to use advice with
4658 ;; functions that Icicles redefines, in particular minibuffer
4659 ;; functions. If you want to allow some such advice or prohibit
4660 ;; advice for additional functions, then customize this list.
4662 ;; Note: If you or a library you load advises one of these
4663 ;; functions while you are in Icicle mode, then toggle Icicle mode
4664 ;; twice, so that this option can have the proper effect.
4666 ;; * The following user options specify the keys to use for
4667 ;; mode-specific completion-candidate cycling. The default
4668 ;; bindings are in parentheses.
4670 ;; `icicle-apropos-cycle-next-keys' (`next')
4671 ;; `icicle-apropos-cycle-previous-keys' (`prior')
4672 ;; `icicle-prefix-cycle-next-keys' (`end')
4673 ;; `icicle-prefix-cycle-previous-keys' (`home')
4674 ;; `icicle-apropos-cycle-next-action-keys' (`C-next')
4675 ;; `icicle-apropos-cycle-previous-action-keys' (`C-prior')
4676 ;; `icicle-prefix-cycle-next-action-keys' (`C-end')
4677 ;; `icicle-prefix-cycle-previous-action-keys' (`C-home')
4678 ;; `icicle-apropos-cycle-next-alt-action-keys' (`C-S-next')
4679 ;; `icicle-apropos-cycle-previous-alt-action-keys' (`C-S-prior')
4680 ;; `icicle-prefix-cycle-next-alt-action-keys' (`C-S-end')
4681 ;; `icicle-prefix-cycle-previous-alt-action-keys' (`C-S-home')
4682 ;; `icicle-apropos-cycle-next-help-keys' (`C-M-next')
4683 ;; `icicle-apropos-cycle-previous-help-keys' (`C-M-prior')
4684 ;; `icicle-prefix-cycle-next-help-keys' (`C-M-end')
4685 ;; `icicle-prefix-cycle-previous-help-keys' (`C-M-home')
4687 ;; * The following user options specify the keys to use for cycling
4688 ;; candidates according to the current completion mode. The
4689 ;; default bindings are in parentheses.
4691 ;; `icicle-modal-cycle-down-keys' (`down')
4692 ;; `icicle-modal-cycle-up-keys' (`up')
4693 ;; `icicle-modal-cycle-down-action-keys' (`C-down')
4694 ;; `icicle-modal-cycle-up-action-keys' (`C-up')
4695 ;; `icicle-modal-cycle-down-alt-action-keys' (`C-S-down')
4696 ;; `icicle-modal-cycle-up-alt-action-keys' (`C-S-up')
4697 ;; `icicle-modal-cycle-down-help-keys' (`C-M-down')
4698 ;; `icicle-modal-cycle-up-help-keys' (`C-M-up')
4700 ;; The completion mode, and hence the behavior of these keys, is
4701 ;; changed only when you hit `TAB' or `S-TAB' during completion:
4702 ;; the mode is prefix completion after `TAB' and apropos completion
4705 ;; Note: If your customizations of the modal and non-modal cycling
4706 ;; keys conflict, the non-modal values win. For example, if you
4707 ;; define both `icicle-modal-cycle-up-keys' and
4708 ;; `icicle-prefix-cycle-previous-keys' as the list `([up])', then
4709 ;; the `up' key will perform prefix cycling, not modal cycling.
4711 ;; * User option `icicle-default-cycling-mode' determines the
4712 ;; completion mode to be used before you hit `TAB' or `S-TAB'.
4713 ;; This affects only modal cycling - e.g. using keys such as `down'
4714 ;; and `C-down'. Values:
4716 ;; - `prefix' (default) means cycle prefix completions
4717 ;; - `apropos' means cycle apropos completions
4718 ;; - other non-`nil' value means cycle inputs from input history
4719 ;; - `nil' means do not cycle: you must first hit a completion key
4721 ;; For example, if the value is `apropos' then you can immediately
4722 ;; cycle apropos completions without first hitting `S-TAB'.
4724 ;; Once you have used `TAB' or `S-TAB', the only way to traverse
4725 ;; the input history is to use `M-p' and `M-n'.
4727 ;; * User option `icicle-word-completion-keys' is a list of keys to
4728 ;; use for word completion. By default, the only such key is
4731 ;; * User option `icicle-apropos-complete-no-display-keys' is a list
4732 ;; of keys to bind to `icicle-apropos-complete-no-display'. By
4733 ;; default, these keys are `C-M-S-tab' and `C-M-S-iso-lefttab',
4734 ;; which together implement `C-M-S-TAB'. Similarly,
4735 ;; `icicle-prefix-complete-no-display-keys' is the list of keys for
4736 ;; `icicle-prefix-complete-no-display'. By default, the only such
4737 ;; key is `C-M-tab'.
4739 ;; * Option `icicle-prefix-complete-keys' is the list of keys for
4740 ;; `icicle-prefix-complete'. By default, these keys are `tab' and
4741 ;; `C-i', which together implement `TAB'.
4743 ;; * Option `icicle-apropos-complete-keys' is the list of keys to
4744 ;; bind to `icicle-apropos-complete'. By default, these keys are
4745 ;; `S-tab' and `S-iso-lefttab', which together implement `S-TAB'.
4746 ;; (In Emacs 22 and later, `backtab' is the canonical key that
4747 ;; represents both `S-tab' and `S-iso-lefttab', so that is used in
4748 ;; the default value.)
4750 ;; * Option `icicle-key-complete-keys' is the list of keys to bind to
4751 ;; `icicle-complete-keys'. By default, these keys are `S-tab' and
4752 ;; `S-iso-lefttab', which together implement `S-TAB'. (In Emacs 22
4753 ;; and later, `backtab' is the canonical key that represents both
4754 ;; `S-tab' and `S-iso-lefttab', so that is used in the default
4757 ;; * Option `icicle-previous-candidate-keys' is the list of keys to
4758 ;; bind to `icicle-move-to-previous-completion', for moving among
4759 ;; candidates in buffer `*Completions*'. By default, these keys
4760 ;; are `S-tab' and `S-iso-lefttab', which together implement
4761 ;; `S-TAB'. (In Emacs 22 and later, `backtab' is the canonical key
4762 ;; that represents both `S-tab' and `S-iso-lefttab', so that is
4763 ;; used in the default value.)
4765 ;; * Option `icicle-isearch-complete-keys' is the list of keys for
4766 ;; `icicle-isearch-complete'. By default, these keys are `M-TAB',
4767 ;; `ESC TAB', `C-M-TAB', and `M-o'.
4769 ;; * Option `icicle-read+insert-file-name-keys' is the list of keys
4770 ;; for invoking file-name completion on demand. By default,
4771 ;; `C-M-S-f' is the only such key. Option
4772 ;; `icicle-completing-read+insert-keys' is the list of keys for
4773 ;; invoking non file-name completion on demand. By default,
4774 ;; `C-M-S-c' is the only such key. See (@> "Completion On Demand").
4776 ;; * User option `icicle-act-before-cycle-flag' `nil' means that keys
4777 ;; such as `C-next', which combine candidate action and cycling,
4778 ;; cycle to the next (or previous) candidate and act on it.
4779 ;; Non-`nil' means they act on the current candidate and then cycle
4780 ;; to the next (or previous) candidate. When the value is `nil',
4781 ;; you can think of `C-next' as an operation on the next candidate.
4782 ;; When the value is non-`nil', you can think of `C-next' as an
4783 ;; operation on the current candidate, which ends by making the
4784 ;; next candidate current. Similarly for the other cycling keys
4785 ;; that act, alternative-act, or show help on a candidate. The
4786 ;; default value is `nil'. See also option
4787 ;; `icicle-use-C-for-actions-flag', which changes the keys affected
4788 ;; by `icicle-act-before-cycle-flag'.
4790 ;; * If option `icicle-use-C-for-actions-flag' is `nil', then the
4791 ;; keys that cycle candidates are swapped with the keys that both
4792 ;; cycle and act on a candidate. You can then use `down', `up',
4793 ;; `next', `prior', `end' and `home' to both cycle and act, and
4794 ;; `C-down', `C-up', `C-next', `C-prior', `C-end', and `C-home' to
4795 ;; merely cycle, without acting (e.g. navigating). The option has
4796 ;; no effect on other keys. You can toggle this option at any time
4797 ;; using `M-g' (`icicle-toggle-C-for-actions') in the minibuffer.
4799 ;; (The keys mentioned here are the default bindings. The actual
4800 ;; keys swapped are those defined by these user options:
4801 ;; `icicle-prefix-cycle-next-action-keys',
4802 ;; `icicle-prefix-cycle-previous-action-keys',
4803 ;; `icicle-apropos-cycle-next-action-keys',
4804 ;; `icicle-apropos-cycle-previous-action-keys',
4805 ;; `icicle-modal-cycle-down-action-keys',
4806 ;; `icicle-modal-cycle-up-action-keys',
4807 ;; `icicle-prefix-cycle-next-keys',
4808 ;; `icicle-prefix-cycle-previous-keys',
4809 ;; `icicle-apropos-cycle-next-keys',
4810 ;; `icicle-apropos-cycle-previous-keys',
4811 ;; `icicle-modal-cycle-down-keys', `icicle-modal-cycle-up-keys'.)
4813 ;; * Non-`nil' user option
4814 ;; `icicle-top-level-when-sole-completion-flag' means that whenever
4815 ;; there is only one completion candidate that matches your input,
4816 ;; that candidate is used immediately, without requiring you to hit
4817 ;; `RET' or `S-RET'.
4819 ;; * When `icicle-top-level-when-sole-completion-flag' is `nil',
4820 ;; option `icicle-top-level-when-sole-completion-delay' is the
4821 ;; number of seconds Icicles waits, before returning to top level
4822 ;; with the sole completion. (It has no effect if the flag is
4823 ;; `nil'.) The delay gives you a chance to forestall acceptance of
4824 ;; the sole completion: editing the completion (typing or deleting
4825 ;; a character) before the delay expires prevents its automatic
4826 ;; acceptance. The default value is 0 seconds (no delay).
4828 ;; * Non-`nil' user option `icicle-TAB-shows-candidates-flag' means
4829 ;; that hitting `TAB' for prefix completion immediately shows the
4830 ;; completion candidates in buffer `*Completions*'. If `nil', then
4831 ;; candidates are shown only after `TAB' is hit a second time,
4832 ;; which is the standard Emacs behavior. The default value is `t'.
4833 ;; (Actually, the concerned keys are those defined by option
4834 ;; `icicle-prefix-complete-keys', not necessarily `TAB'.)
4836 ;; * Non-`nil' option `icicle-max-candidates' means truncate the list
4837 ;; of completion candidates to at most this many. If you use
4838 ;; library `doremi.el' then you can use `C-x #' during completion
4839 ;; to increment or decrement the option value using the vertical
4840 ;; arrow keys or the mouse wheel. A numeric prefix argument for
4841 ;; `C-x #' sets the increment size. A plain prefix argument
4842 ;; (`C-u') resets `icicle-max-candidates' to `nil', meaning no
4845 ;; * Non-`nil' user option `icicle-expand-input-to-common-match-flag'
4846 ;; means that completion commands `TAB' and `S-TAB' expand your
4847 ;; minibuffer input to (typically) the longest substring common to
4848 ;; all completion candidates and that matches your (complete) input
4849 ;; pattern. This replaces the input you typed. If you want to
4850 ;; edit your original, raw input, use `C-l'. If your input has
4851 ;; been expanded, then hit `C-l' twice: once to replace a
4852 ;; completion candidate (from, say, `next') with the common match
4853 ;; string, and a second time to replace the common match string
4854 ;; with your original input. The main reason you might want to set
4855 ;; this to `nil' is for apropos completion, if you want to always
4856 ;; work with a regexp in the minibuffer. You can toggle this
4857 ;; option at any time using `C-;' in the minibuffer.
4858 ;; See (@file :file-name "icicles-doc1.el" :to "Expanded-Common-Match Completion").
4860 ;; * Non-`nil' user option
4861 ;; `icicle-hide-common-match-in-Completions-flag' hides, in buffer
4862 ;; `*Completions*', the common match for your current input from
4863 ;; each candidate. You can toggle this anytime during completion
4864 ;; using `C-x .' (no prefix arg), which is bound to command
4865 ;; `icicle-toggle-hiding-common-match'. The common match used is
4866 ;; governed by option `icicle-expand-input-to-common-match-flag'.
4868 ;; * Non-`nil' option `icicle-hide-non-matching-lines-flag' hides, in
4869 ;; buffer `*Completions*', all lines in multi-line candidates that
4870 ;; do not match your current minibuffer input. In Emacs 22+,
4871 ;; consecutive such lines are elided as `...'. You can toggle this
4872 ;; option anytime during completion using `C-u C-x .', which is
4873 ;; bound to command `icicle-toggle-hiding-non-matching-lines'.
4875 ;; * User option `icicle-show-Completions-initially-flag' controls
4876 ;; whether or not buffer `*Completions*' is shown initially,
4877 ;; without your needing to hit `TAB' or `S-TAB' to show it.
4878 ;; However, if you type something before
4879 ;; `icicle-incremental-completion-delay', then display is
4880 ;; inhibited. The default value is `nil', meaning that
4881 ;; `*Completions*' is not shown until you hit `TAB' or `S-TAB'.
4882 ;; More typical than setting this option to non-`nil' globally is
4883 ;; to bind it to non-`nil' in Emacs-Lisp code, to display
4884 ;; `*Completions*' as a menu. For example, pass a non-`nil'
4885 ;; binding to `icicle-define-command' to create a command that
4886 ;; displays a multiple-choice menu.
4888 ;; For an alternative but similar behavior to using non-`nil' for
4889 ;; `icicle-show-Completions-initially-flag', you can set option
4890 ;; `icicle-incremental-completion-flag' to a value that is neither
4891 ;; `nil' nor `t'. That displays `*Completions*' as soon as you
4892 ;; type or delete input, but not initially.
4894 ;; * User option `icicle-incremental-completion-flag' controls
4895 ;; whether or not `*Completions*' is updated incrementally
4896 ;; (icompletion) as you type. You can toggle incremental
4897 ;; completion at any time using `C-#'. For more information, see
4898 ;; (@file :file-name "icicles-doc1.el" :to "Icompletion").
4900 ;; * User options `icicle-incremental-completion-delay' and
4901 ;; `icicle-incremental-completion-threshold' together cause a delay
4902 ;; before incremental completion takes effect.
4903 ;; See (@file :file-name "icicles-doc1.el" :to "Icompletion").
4905 ;; * User option `icicle-Completions-display-min-input-chars' is the
4906 ;; minimum number of input characters that allow buffer
4907 ;; `*Completions*' to remain displayed. By default, this is zero
4908 ;; (0), meaning that any number of input characters, even none,
4909 ;; allows `*Completions*' to remain displayed. If you use
4910 ;; incremental completion (see `icicle-incremental-completion-*'),
4911 ;; and you are bothered by `*Completions*' being automatically
4912 ;; updated when, for instance, you empty the minibuffer, then you
4913 ;; might want to set this option to, say, 1 or 2. With a value of
4914 ;; 2, for instance, whenever the minibuffer input has less than 2
4915 ;; characters, incremental completion will remove the
4916 ;; `*Completions*' window. You can also remove the `*Completions*'
4917 ;; window at any time using `C-x 0' in the minibuffer.
4919 ;; * Non-`nil' option `icicle-show-Completions-help-flag' means
4920 ;; display help (instructions) at the top of the `*Completions*'
4921 ;; window. These instructions are shown in faces
4922 ;; `icicle-Completions-instruction-1' and
4923 ;; `icicle-Completions-instruction-2'.
4925 ;; * Option `icicle-help-in-mode-line-delay' is the number of seconds
4926 ;; to display help on individual completion candidates in the
4927 ;; mode-line as you cycle or your input is completed. The
4928 ;; mode-line that is used is that of buffer `*Completions*', if it
4929 ;; is displayed, or the current buffer, otherwise. Typically, this
4930 ;; mode-line candidate help is the first line of a doc string, but
4931 ;; alternative help is available.
4933 ;; Regardless of the option value, a user event (e.g. a key press)
4934 ;; always interrupts (terminates) this help display. Note too that
4935 ;; `post-command-hook' actions do not take place until this display
4938 ;; * Face `icicle-mode-line-help' is used to highlight Icicles help
4939 ;; shown in the mode-line. This includes that controlled by option
4940 ;; `icicle-help-in-mode-line-delay' and the indication in
4941 ;; `*Completions*' of the total number of matching candidates.
4943 ;; * User option `icicle-Completions-mouse-3-menu-entries' defines
4944 ;; the contextual menu that is popped up when you click `C-mouse-3'
4945 ;; on a candidate in `*Completions*'. As an aid to customizing it,
4946 ;; refer to any of the constants `icicle-Completions-*' that define
4947 ;; its submenus. The submenu definitions are easier to understand
4948 ;; in the source code (`icicles-opt.el'), because Customize does
4949 ;; not pretty-print them.
4951 ;; * Non-`nil' user option `icicle-move-Completions-frame' means that
4952 ;; `icicle-candidate-action' moves the frame showing buffer
4953 ;; `*Completions*' to the edge of the display, out of the way of
4954 ;; other frames. The possible non-`nil' values are `right' and
4955 ;; `left', specifying the display edge to use.
4957 ;; This option can be useful if you use one-buffer-per-frame
4958 ;; (non-`nil' `pop-up-frames'). In that case, I recommend that you
4959 ;; also try my library `oneonone.el'. See
4960 ;; (@> "Note on Non-`nil' `pop-up-frames' on MS Windows") for more
4961 ;; advice about non-`nil' `pop-up-frames'.
4963 ;; * User option `icicle-Completions-window-max-height' is the
4964 ;; maximum height of the `*Completions*' window, in lines. The
4965 ;; window is fit to the buffer size, with this as maximum height.
4966 ;; This is not used if `*Completions*' is a special display buffer
4967 ;; with its own frame, and it is not used in Emacs releases prior
4970 ;; * Starting with Emacs 23, you can use option
4971 ;; `icicle-Completions-text-scale-decrease' to change the size of
4972 ;; the text used in buffer `*Completions*'.
4974 ;; * User option `icicle-candidate-width-factor' controls how many
4975 ;; columns of completion candidates are displayed in
4976 ;; `*Completions*'. The widest current candidate is scaled by this
4977 ;; percentage, and the window width is divided by that figure.
4978 ;; Other things are taken into account also, but this gives you a
4979 ;; way to tweak the number of columns: the larger this number, the
4980 ;; fewer the columns.
4982 ;; If you use Do Re Mi (library `doremi.el'), then you can modify
4983 ;; `icicle-candidate-width-factor' incrementally during completion,
4984 ;; seeing the effect as it changes. Use `C-x w' from the
4985 ;; minibuffer, then use the `right' and `left' arrow keys or the
4986 ;; mouse wheel to increment and decrement the value. You can at
4987 ;; the same time use the `up' and `down' keys to adjust the value
4988 ;; of `icicle-inter-candidates-min-spaces'. WYSIWYG.
4990 ;; * User option `icicle-inter-candidates-min-spaces' is the minimum
4991 ;; number of spaces between candidates displayed in
4992 ;; `*Completions*'. The default value is one space.
4994 ;; If you use Do Re Mi (library `doremi.el'), then you can modify
4995 ;; `icicle-inter-candidates-min-spaces' incrementally during
4996 ;; completion, seeing the effect as it changes. Use `C-x |' from
4997 ;; the minibuffer, then use the `up' and `down' arrow keys or the
4998 ;; mouse wheel to increment and decrement the value. You can at
4999 ;; the same time use the `left' and `right' keys to adjust the
5000 ;; value of `icicle-candidate-width-factor'. WYSIWYG.
5002 ;; * Non-`nil' option `icicle-image-files-in-Completions' means that
5003 ;; thumbnail images are shown in `*Completions*' for candidates
5004 ;; that are (relative or absolute) names of image files. The
5005 ;; default value is `t'. If the value is `image-only', then only
5006 ;; the thumbnail images are shown. If it is otherwise non-`nil'
5007 ;; then the file names are also shown. You can cycle the option
5008 ;; value using `C-x t' in the minibuffer at any time during
5009 ;; completion. This feature is available starting with Emacs 22.
5011 ;; * Option `icicle-completions-format' controls whether candidates
5012 ;; displayed in `*Completions*' are laid out horizontally (the
5013 ;; default) or vertically. Set the value to `vertical' for the
5014 ;; latter. Starting with Emacs 23.2, you can just use the vanilla
5015 ;; option `completions-format' for this, if you want the same type
5016 ;; of layout with Icicle mode turned on or off.
5018 ;; Icicles always displays multi-line candidates in a single
5019 ;; column, for readability. When this is the case, the completions
5020 ;; format (horizontal or vertical) makes no difference - the effect
5021 ;; is the same. (Icicles also inserts an empty line after each
5022 ;; multi-line candidate, for readability.)
5024 ;; * If option `icicle-menu-items-to-history-flag' is non-`nil' (the
5025 ;; default), then commands that you invoke using the menu-bar menu
5026 ;; are included in the command history for `M-x'.
5028 ;; * Non-`nil' option `icicle-populate-interactive-history-flag'
5029 ;; means that any interactive use of a command causes it to be
5030 ;; added to the history `icicle-interactive-history'. You can
5031 ;; access this history by using `C-M-pause' during completion. Be
5032 ;; aware that addition of all interactive invocations to this
5033 ;; history can slow Emacs down. (This option is only available
5034 ;; starting with Emacs 23.)
5036 ;; * User option `icicle-sort-comparer' controls the order of
5037 ;; completion candidates during cycling and in buffer
5038 ;; `*Completions*'. If `nil', then no sorting is done. If
5039 ;; non-`nil', then the value must be a string-comparison function -
5040 ;; the function is passed to the standard function `sort' to do the
5041 ;; sorting. The default value for `icicle-sort-comparer' is
5042 ;; `icicle-case-string-less-p', which sorts alphabetically,
5043 ;; possibly ignoring letter case. During completion, you can
5044 ;; toggle sorting using `C-,'. If you are an Emacs-Lisp programmer
5045 ;; and you write new commands using Icicles functionalities, you
5046 ;; can bind `icicle-sort-comparer' temporarily to any sort function
5049 ;; * User option `icicle-alternative-sort-comparer' is an alternative
5050 ;; to `icicle-sort-comparer, providing a different sort order. By
5051 ;; default, it is `icicle-historical-alphabetic-p', a function that
5052 ;; sorts previously used completion candidates before candidates
5053 ;; that have not yet been used, and sorts alphabetically within
5054 ;; each of these groups of candidates. In other words, it places
5055 ;; inputs that you have used previously at the top of buffer
5056 ;; `*Completions*' and makes them available for completion first.
5057 ;; During completion, you can toggle normal and alternative sorting
5058 ;; using `C-M-,'. See (@> "Sorting Candidates") and
5059 ;; (@file :file-name "icicles-doc1.el" :to "History Enhancements").
5061 ;; * User option `icicle-change-sort-order-completion-flag' specifies
5062 ;; whether `C-,' cycles among available sort orders or lets you
5063 ;; choose a sort order using Icicles completion. Non-`nil' means
5064 ;; to use completion; `nil' (the default value) means to cycle.
5065 ;; You can override the current setting at any time by using `C-u
5066 ;; C-,'. See (@> "Sorting Candidates").
5068 ;; * User option `icicle-sort-orders-alist' is an alist of possible
5069 ;; sort orders for user to choose from using `C-,' or `M-,'.
5070 ;; See (@> "Sorting Candidates").
5072 ;; * The value of user option `icicle-transform-function' is a
5073 ;; function that is applied to the list of completion candidates,
5074 ;; to transform them before they are presented to the user. If
5075 ;; `nil', then no transformation is done. The default
5076 ;; transformation is to remove duplicate candidates, when
5077 ;; transformation is active, but the default value of this option
5078 ;; is `nil'. You can toggle transformation at any time using
5079 ;; command `icicle-toggle-transforming', bound to `C-$' in the
5080 ;; minibuffer. Although this is a user option, you probably do
5081 ;; *NOT* want to change its value by customizing it. Icicles
5082 ;; commands already "do the right thing" when it comes to candidate
5085 ;; The value of this option can be changed by program locally, for
5086 ;; use in particular contexts. For example, when you use
5087 ;; `icicle-search-generic' (`C-c `') in a *shell* buffer, Icicles
5088 ;; uses this variable with a value of `icicle-remove-duplicates',
5089 ;; to remove duplicate shell commands from your input history list.
5090 ;; Lisp programmers can use this variable to transform the list of
5091 ;; candidates in any way they like. A typical use is to remove
5092 ;; duplicates, by binding it to `icicle-remove-duplicates' or
5093 ;; `icicle-remove-dups-if-extras'.
5095 ;; * User options `icicle-require-match-flag',
5096 ;; `icicle-buffer-require-match-flag', and
5097 ;; `icicle-file-require-match-flag' let you override the value of
5098 ;; the REQUIRE-MATCH argument provided to `completing-read' or
5099 ;; `read-file-name'. They are provided mainly for use (binding) in
5100 ;; `icicle-define-command' and `icicle-define-file-command', but
5101 ;; you may also use them globally, if you wish. See
5102 ;; (@file :file-name "icicles-doc1.el" :to "Exiting the Minibuffer Without Confirmation").
5104 ;; A typical use is made in the definition of command
5105 ;; `icicle-buffer': `icicle-buffer-require-match-flag' is used to
5106 ;; bind `icicle-require-match-flag', so that you can, for example,
5107 ;; match only existing buffers and be able to match on partial
5108 ;; input without explicitly completing (hitting `TAB' or `S-TAB').
5109 ;; Simply set the option to `partial-match-ok' to get this
5110 ;; behavior. To apropos-complete and exit the minibuffer, use
5111 ;; `S-RET' instead of `RET'. See
5112 ;; (@file :file-name "icicles-doc1.el" :to "Exiting the Minibuffer Without Confirmation"),
5113 ;; for more information.
5115 ;; * Non-`nil' user option `icicle-ignore-space-prefix-flag' means to
5116 ;; ignore completion candidates that start with a space. However,
5117 ;; such candidates are not ignored for prefix completion if the
5118 ;; input also starts with a space. Naturally, apropos completion
5119 ;; is not affected by whether or not the input starts with a space.
5121 ;; Option `icicle-buffer-ignore-space-prefix-flag' lets you
5122 ;; override the value of `icicle-ignore-space-prefix-flag' for use
5123 ;; with buffer-name completion (the names of internal buffers start
5124 ;; with a space). It is provided mainly for binding when using
5125 ;; `icicle-define-command' (`icicle-buffer' does this).
5127 ;; You can toggle `icicle-ignore-space-prefix-flag' at any time
5128 ;; using `M-_' in the minibuffer. If the current command binds
5129 ;; this option locally, then it is the local, not the global, value
5130 ;; that is changed. For example, if
5131 ;; `icicle-buffer-ignore-space-prefix-flag' is non-`nil', then
5132 ;; `M-_' toggles `icicle-ignore-space-prefix-flag' to `nil' only
5133 ;; for the duration of the buffer command (e.g. `icicle-buffer').
5135 ;; * Non-`nil' user option `icicle-test-for-remote-files-flag' means
5136 ;; that Icicles tests for remote file names; `nil' means that it
5137 ;; does not. You can toggle this using `C-^' in the minibuffer
5138 ;; (except during Icicles search). Turning off remote file-name
5139 ;; testing means that you cannot use remote files with Tramp; it
5140 ;; disables Tramp's remote file-name handling and completion. This
5141 ;; can, for local files, slightly speed up incremental completion
5142 ;; and the highlighting of the part of your current input that does
5143 ;; not complete (see `icicle-highlight-input-completion-failure').
5145 ;; * Non-`nil' user option `icicle-regexp-quote-flag' reduces apropos
5146 ;; completion to simple substring completion and Icicles regexp
5147 ;; search to literal search. Regexp special characters are no
5148 ;; longer recognized as special; they simply match themselves. You
5149 ;; probably do not want to customize this option. Instead, you can
5150 ;; toggle it at any time using `C-`' in the minibuffer.
5152 ;; * User options `icicle-command-abbrev-match-all-parts-flag',
5153 ;; `icicle-command-abbrev-priority-flag', and
5154 ;; `icicle-command-abbrev-alist' control the behavior of
5155 ;; multi-command `icicle-command-abbrev' (`C-x SPC'). The first
5156 ;; determines whether an abbreviation must match all parts of a
5157 ;; command name. The second controls whether command names or
5158 ;; abbreviations take precedence in case of conflict. The third is
5159 ;; the persistent list of your command abbreviations.
5161 ;; * User options `icicle-S-TAB-completion-methods-alist' and
5162 ;; `icicle-TAB-completion-methods' control which completion method
5163 ;; is used by `S-TAB' and `TAB', respectively, to complete your
5164 ;; input. By default, the first method in each list is used for
5165 ;; matching. You can use `M-(' and `C-(' (commands
5166 ;; `icicle-next-S-TAB-completion-method' and
5167 ;; `icicle-next-TAB-completion-method') in the minibuffer to cycle
5168 ;; among the `S-TAB' and `TAB' methods.
5170 ;; For fuzzy completion (choice `fuzzy' when cycling with `C-('),
5171 ;; `TAB' completes non-filename input using fuzzy prefix matching
5172 ;; as defined in library `fuzzy-match.el'. See the Commentary in
5173 ;; `fuzzy-match.el' for details about fuzzy matching.
5175 ;; Fuzzy completion is not available for file-name completion; it
5176 ;; is always case-sensitive; leading spaces are taken into account;
5177 ;; and completion candidates are always sorted by decreasing fuzzy
5178 ;; match strength. In other words, fuzzy completion is not
5179 ;; affected by `C-A', `M-_', or `C-,'.
5181 ;; * User options `icicle-S-TAB-completion-methods-per-command' and
5182 ;; `icicle-TAB-completion-methods-per-command' provide per-command
5183 ;; control of the completion methods available when you cycle using
5184 ;; `C-(' and `M-('. Use them if you want to specify which methods
5185 ;; are available for particular commands that read input with
5188 ;; * User option `icicle-levenshtein-distance' is the Levenshtein
5189 ;; distance allowed for strings to be considered as matching during
5190 ;; N-off completion. This means that two strings match if they
5191 ;; differ by at most this many character operations (insertion,
5192 ;; deletion, replacement). This option is used only if you have
5193 ;; library `levenshtein.el'. See (@> "Fuzzy Completion").
5195 ;; * Top-level command `icicle-search' uses several faces to
5196 ;; highlight found text that matches your input. Faces
5197 ;; `icicle-search-main-regexp-current' and
5198 ;; `icicle-search-main-regexp-others' highlight what your
5199 ;; search-context regexp (entered with `RET') matches. The former
5200 ;; highlights the current search context; the latter highlights all
5201 ;; other search contexts.
5203 ;; Face `icicle-search-current-input' highlights what your current
5204 ;; input (typically another regexp) matches; that is, it highlights
5205 ;; a match within a search context. Faces
5206 ;; `icicle-search-context-level-1' through
5207 ;; `icicle-search-context-level-8' highlight the first eight regexp
5208 ;; subgroup matches, within a search context. This highlighting is
5209 ;; done whenever `icicle-search-highlight-context-levels-flag' is
5210 ;; non-`nil' and the search context corresponds to the entire
5213 ;; * User option `icicle-search-highlight-context-levels-flag'
5214 ;; controls highlighting of regexp subgroup matches within the
5215 ;; search context. Non-`nil' (the default value) means highlight
5218 ;; * User option `icicle-search-highlight-threshold' controls
5219 ;; highlighting with face `icicle-search-main-regexp-others': this
5220 ;; many matches, maximum, are highlighted. If zero, then only the
5221 ;; current match is highlighted. The effect is similar to the
5222 ;; Emacs 22+ lazy search highlighting of Isearch (except that the
5223 ;; highlighting is not in fact lazy).
5225 ;; * Non-`nil' user option `icicle-search-highlight-all-current-flag'
5226 ;; means highlight the current input match in all main search hits
5227 ;; at the same time. If `icicle-expand-input-to-common-match-flag'
5228 ;; is also non-`nil', then what is highlighted for each input match
5229 ;; is the expanded common match among all input matches throughout
5230 ;; the search area. If either is `nil', then only the exact input
5231 ;; match is highlighted.
5233 ;; The default value of `icicle-search-highlight-all-current-flag'
5234 ;; is `nil', because non-`nil' can impact performance negatively if
5235 ;; there are many search contexts - the highlighting is updated
5236 ;; with each input change. You can toggle the value at any time
5237 ;; using command `icicle-toggle-highlight-all-current', bound to
5238 ;; `C-^' in the minibuffer (except during file-name completion).
5240 ;; * If, in addition to `icicle-search-highlight-all-current-flag'
5241 ;; and `icicle-expand-input-to-common-match-flag', option
5242 ;; `icicle-search-replace-common-match-flag' is also non-`nil',
5243 ;; then a search replacement replaces the expanded common match;
5244 ;; otherwise, it replaces only the exact match. You can toggle the
5245 ;; value at any time using `M-;' in the minibuffer.
5247 ;; * Non-`nil' user option `icicle-search-cleanup-flag' means that
5248 ;; `icicle-search' highlighting is removed after the search. This
5249 ;; is the default behavior. If you set this to `nil' then you can
5250 ;; remove search highlighting manually later using command
5251 ;; `icicle-search-highlight-cleanup'. You can toggle this search
5252 ;; highlight removal at any time using command
5253 ;; `icicle-toggle-search-cleanup', which is bound to `C-.' in the
5254 ;; minibuffer during Icicles search.
5256 ;; One use of `nil' `icicle-search-cleanup-flag' is to highlight
5257 ;; regexp matches throughout a region or buffer (or multiple files
5258 ;; or...). In that capacity, Icicles search functions act like
5259 ;; some of the highlighting commands in my library `highlight.el'.
5260 ;; Note that when `icicle-search-cleanup-flag' is `nil', *all*
5261 ;; Icicles search highlighting remains: last-visited search
5262 ;; context, other context matches, current-input matches, and even
5263 ;; regexp subgroups. The faces for these are, respectively:
5265 ;; - `icicle-search-main-regexp-current'
5266 ;; - `icicle-search-main-regexp-others'
5267 ;; - `icicle-search-highlight-input-matches-here' (everywhere, if
5268 ;; `icicle-search-highlight-all-current-flag' is non-`nil')
5269 ;; - `icicle-search-context-level-1' through
5270 ;; `icicle-search-context-level-8'
5272 ;; * Non-`nil' user option `icicle-search-whole-word-flag' means that
5273 ;; whole-word search is done. You can use `M-q' while searching to
5274 ;; toggle this option; the new value takes effect for the next
5277 ;; Whole-word searching here means that matches can contain
5278 ;; embedded strings of non word-constituent chars (they are skipped
5279 ;; over, when matching, included in the match), and any leading or
5280 ;; trailing word-constituent chars in the search string are dropped
5281 ;; (ignored for matching, not included in the match). This means,
5282 ;; for instance, that you can match `foo-bar' as a word, even in
5283 ;; contexts (such as Emacs Lisp) where `-' is not a
5284 ;; word-constituent character. Similarly, you can include embedded
5285 ;; whitespace in a "word", e.g., `foo bar'.
5287 ;; See also (@> "Icicles Search Commands, Overview").
5289 ;; * If user option `icicle-search-replace-whole-candidate-flag' is
5290 ;; `nil', then whatever matches your current input is replaced,
5291 ;; within the current search context, when you perform replacement
5292 ;; during Icicles searching (e.g. `C-S-RET'). If the value is
5293 ;; non-`nil' (the default value), then the entire search context is
5294 ;; replaced, instead. You can use `M-_' at any time during
5295 ;; searching and replacing, to toggle the value.
5297 ;; * User option `icicle-search-replace-literally-flag' determines
5298 ;; whether Icicles search-and-replace replaces text literally or
5299 ;; interprets `\' specially in the replacement text, as in
5300 ;; `query-replace-regexp'. Non-`nil' means to treat replacement
5301 ;; text literally. The default value is `nil'. You can use
5302 ;; `C-M-`' to toggle this at any time during Icicles search.
5304 ;; * Non-`nil' option `icicle-ignore-comments-flag' means that
5305 ;; `icicle-search-thing' and related commands
5306 ;; (e.g. `icicle-search-xml-element') ignore comments. That is,
5307 ;; they hide comments temporarily while they scan the region or
5308 ;; buffer for things of the given type to serve as search contexts
5309 ;; (completion candidates). This prevents them, for example, from
5310 ;; presenting as a candidate a sexp or a list that is commented
5311 ;; out. You can toggle this option anytime using `C-M-;' in the
5312 ;; minibuffer, but to see the effect you might need to invoke the
5313 ;; current command again.
5315 ;; * User option `icicle-search-hook' is a list of functions to be
5316 ;; run after searching and moving to an `icicle-search' match,
5317 ;; whether you move there by `RET', `C-RET', `C-next', or
5320 ;; * User option `icicle-recenter' is passed as argument to
5321 ;; `recenter' whenever the current navigation destination would be
5322 ;; off-screen, to make it visible.
5324 ;; * User option `icicle-bookmark-name-length-max' is the maximum
5325 ;; number of characters to use when `icicle-bookmark-cmd' (`C-x r
5326 ;; m') with a non-negative numeric prefix argument automatically
5327 ;; names a bookmark.
5329 ;; * User option `icicle-bookmark-refresh-cache-flag' determines
5330 ;; whether commands such as `icicle-bookmark' and
5331 ;; `icicle-search-bookmark' refresh the bookmark-list cache. The
5332 ;; default value of `t', meaning refresh, ensures that the set of
5333 ;; bookmark candidates is always up-to-date, but you can improve
5334 ;; performance for a large bookmark list if you customize it to
5337 ;; In any case, a plain prefix argument (`C-u') for these commands
5338 ;; overrides the default setting of the option for the duration of
5339 ;; the command. Thus if the customized value is `nil', you can use
5340 ;; `C-u' occasionally to refresh the list on demand. In addition,
5341 ;; the cache is refreshed whenever you use `S-delete' to delete a
5342 ;; candidate bookmark.
5344 ;; * Non-`nil' user option `icicle-show-multi-completion-flag' means
5345 ;; that for some commands additional information is shown along
5346 ;; with each completion candidate. That is, a multi-completion is
5347 ;; used. You can match against any parts of the multi-completion.
5348 ;; The default value is `t'.
5350 ;; For example, for command `icicle-search', the name of the buffer
5351 ;; associated with each completion candidate is added to the
5352 ;; candidate and highlighted. You can match against the buffer
5353 ;; name, as well as the search hit within the buffer.
5355 ;; Note that even when the value of this option is `nil', you can
5356 ;; often see the multi-completion information in the mode-line when
5357 ;; you cycle candidates, and you can typically see it in the help
5358 ;; that is displayed by `C-M-mouse-2' and so on.
5360 ;; * User options `icicle-buffer-match-regexp',
5361 ;; `icicle-buffer-no-match-regexp', `icicle-buffer-predicate', and
5362 ;; `icicle-buffer-extras' determine the behavior of Icicles buffer
5363 ;; commands, such as `icicle-buffer' and `insert-buffer'. They
5364 ;; determine the set of buffer-name candidates available for
5367 ;; The first three restrict this set to names that satisfy the
5368 ;; properties they specify. Option `icicle-buffer-extras' lets you
5369 ;; add additional buffer names to the set of candidates, after
5370 ;; restriction by the other options. Extra buffer-name candidates
5371 ;; are displayed in buffer `*Completions*' using face
5372 ;; `icicle-extra-candidate'.
5374 ;; Note that if an extra candidate is already a candidate anyway
5375 ;; then it will be present twice in the list of all candidates
5376 ;; (that is, unless `icicle-transform-function' removes duplicate
5379 ;; Note that `icicle-buffer-predicate' is applied after matching
5380 ;; against user input. It thus corresponds to
5381 ;; `icicle-must-pass-after-match-predicate', not to
5382 ;; `icicle-must-pass-predicate'.
5384 ;; Options `icicle-file-match-regexp',
5385 ;; `icicle-file-no-match-regexp', `icicle-file-predicate', and
5386 ;; `icicle-file-extras' act similarly for file-name completion.
5387 ;; You could use `icicle-file-no-match-regexp' or
5388 ;; `icicle-file-predicate', for instance, to exclude files that are
5389 ;; in or under the directories in `vc-directory-exclusion-list':
5391 ;; (defun my-locate-non-vc-file ()
5392 ;; "`icicle-locate-file', but excluding stuff in VC directories."
5394 ;; (let ((icicle-file-predicate 'not-excluded-vc-file-p))
5395 ;; (icicle-locate-file)))
5397 ;; (defun not-excluded-vc-file-p (file)
5398 ;; "nil if FILE is in a `vc-directory-exclusion-list' directory."
5399 ;; (or (not (boundp 'vc-directory-exclusion-list))
5400 ;; (not (consp vc-directory-exclusion-list))
5401 ;; (not (let ((case-fold-search completion-ignore-case))
5403 ;; (dolist (dir vc-directory-exclusion-list)
5404 ;; (when (string-match
5405 ;; (concat ".*" dir "\\(/.*\\)?")
5407 ;; (throw 'nevfp t)))
5410 ;; * Option `icicle-ignored-directories' is a list of directories
5411 ;; that are ignored by commands `icicle-locate-file' and
5412 ;; `icicle-locate-file-no-symlinks'. By default, this is the value
5413 ;; of `vc-directory-exclusion-list'.
5415 ;; * User option `icicle-buffer-sort' is a predicate used to sort
5416 ;; buffer-name candidates in Icicles buffer commands such as
5417 ;; `icicle-buffer' and `icicle-insert-buffer'. Option
5418 ;; `icicle-file-sort' acts similarly for file-name completion. The
5419 ;; default value of `icicle-buffer-sort' is
5420 ;; `icicle-buffer-sort-*...*-last', which sorts names of buffers
5421 ;; that begin with `*' after other buffer names. These options
5422 ;; affect only the initial sort order used for buffer and file
5423 ;; names, respectively, that is, the order used first in an Emacs
5424 ;; session. The values are also put first in the list of possible
5425 ;; sort orders for cycling.
5427 ;; * User option `icicle-buffer-configs' is a list of named
5428 ;; configurations of options `icicle-buffer-match-regexp',
5429 ;; `icicle-buffer-no-match-regexp', `icicle-buffer-predicate',
5430 ;; `icicle-buffer-extras', and `icicle-buffer-sort'. You use
5431 ;; command `icicle-buffer-config' to choose one of the
5432 ;; configurations to be current. You can use commands
5433 ;; `icicle-add-buffer-config' and `icicle-remove-buffer-config' to
5434 ;; add and remove configurations from the list.
5436 ;; Example: A configuration such as the following, named "Files and
5437 ;; Scratch", defines `icicle-buffer-predicate' to display only file
5438 ;; buffers, and it defines `icicle-buffer-extras' to include the
5439 ;; extra buffer `*scratch*':
5441 ;; ("Files and Scratch" nil nil
5442 ;; (lambda (bufname) (buffer-file-name (get-buffer bufname)))
5443 ;; ("*scratch*") icicle-sort-comparer)
5445 ;; The idea of buffer-option configurations was borrowed from
5446 ;; library `bs.el', by Olaf Sylvester <olaf@geekware.de>.
5448 ;; * User option `icicle-dot-string' is the regexp string inserted by
5449 ;; `icicle-insert-dot-command' (bound to `.' in the minibuffer
5450 ;; during completion). You can set it to a regexp that matches any
5451 ;; character, including newline. The default value instead matches
5452 ;; any character except newline. You can toggle between these two
5453 ;; behaviors using command `icicle-toggle-dot', bound to `C-M-.'
5454 ;; during completion.
5456 ;; * Non-`nil' option `icicle-dot-show-regexp-flag' means show the
5457 ;; underlying regexp (value of constant `icicle-anychar-regexp')
5458 ;; explicitly for a multi-line dot (`.'). A `nil' value works only
5459 ;; for Emacs versions 21 and later.
5461 ;; * User options `icicle-list-join-string' and
5462 ;; `icicle-list-nth-parts-join-string' are described in sections
5463 ;; (@> "Multi-Completions") and (@> "Programming Multi-Completions").
5464 ;; Option `icicle-list-join-string' is the separator string that
5465 ;; joins together the parts of a multi-completion. The end string
5466 ;; is appended to each multi-completion candidate. Option
5467 ;; `icicle-list-nth-parts-join-string' specifies how the
5468 ;; multi-completion extracted parts are joined back together when a
5469 ;; user chooses a multi-completion.
5471 ;; The default value of `icicle-list-join-string' is `^G^J'. With
5472 ;; Emacs 22 and later, the `^G' part is hidden when it appears in
5473 ;; `*Completions*', and you can hide it in the minibuffer also by
5474 ;; using `C-M-j' instead of typing `C-q C-g C-j'. See the doc
5475 ;; string for more information.
5477 ;; * Face `icicle-candidate-part' highlights one or more parts of a
5478 ;; candidate, in buffer `*Completions*'. The candidate is
5479 ;; typically a multi-completion.
5481 ;; * Face `icicle-special-candidate' highlights candidates, in
5482 ;; `*Completions*', that are considered "special". Generally,
5483 ;; these are candidates that match user option
5484 ;; `icicle-special-candidate-regexp'.
5486 ;; * Similarly, face `icicle-proxy-candidate' highlights proxy
5487 ;; candidates. These are placeholders for real candidates.
5488 ;; Non-`nil' user option `icicle-add-proxy-candidates-flag' means
5489 ;; include proxy candidates whenever there are any. You can toggle
5490 ;; this option during completion using command
5491 ;; `icicle-toggle-proxy-candidates', which is bound to `C-M-_' in
5492 ;; the minibuffer. For performance reasons, you will in some cases
5493 ;; need to re-invoke the command to make the proxy candidates
5496 ;; * Face `icicle-extra-candidate' highlights extra candidates, that
5497 ;; is, members of `icicle-extra-candidates', `icicle-buffer-extras',
5498 ;; or `icicle-file-extras'.
5500 ;; * User option `icicle-kmacro-ring-max' acts as `kmacro-ring-max'
5501 ;; when you are in Icicle mode. (When you exit Icicle mode,
5502 ;; `kmacro-ring-max' is restored.) In Icicles, you will typically
5503 ;; want to use a much larger number than the default value in
5506 ;; * User options `icicle-regexp-search-ring-max' and
5507 ;; `icicle-search-ring-max' act as `regexp-search-ring-max' and
5508 ;; `search-ring-max', respectively, when you are in Icicle mode.
5509 ;; (When you exit Icicle mode, `regexp-search-ring-max' and
5510 ;; `search-ring-max' are restored.) The reason for having these
5511 ;; options is that with Icicles you will likely want to use a much
5512 ;; longer search history. By default, these are as large as
5513 ;; possible (virtually unlimited).
5515 ;; Suggestion: If you use library `savehist.el' (recommended),
5516 ;; customize `savehist-additional-variables' to include variables
5517 ;; `search-ring' and `regexp-search-ring', so that your search
5518 ;; histories will be saved between Emacs sessions.
5520 ;; Note: You can clear (empty) a given search history with command
5521 ;; `clear-option' (aka `icicle-reset-option-to-nil'). For example,
5522 ;; to clear the regular-expression search history, do this:
5524 ;; `C-u M-x clear-option RET regexp-search-ring RET'
5526 ;; (The `C-u' is needed because this variable is not a user
5527 ;; option.) If you use my library `misc-cmds.el', you can clear
5528 ;; search histories easier, using commands `clear-search-history',
5529 ;; `clear-regexp-search-history', and `clear-search-histories'.
5530 ;; See (@file :file-name "icicles-doc1.el" :to "Isearch Completion").
5532 ;; * User option `icicle-completion-history-max-length' limits the
5533 ;; number of completion inputs to save. If you customize user
5534 ;; option `icicle-C-l-uses-completion-flag' to non-`nil', then,
5535 ;; instead of cycling, `C-l' lets you use Icicles completion to
5536 ;; retrieve a past completion input. (`C-L' does the same thing.)
5537 ;; If you use library `savehist.el', then you can save the history
5538 ;; of completion inputs persistently by customizing user option
5539 ;; `savehist-additional-variables' to include the Icicles internal
5540 ;; variables `icicle-previous-raw-file-name-inputs' and
5541 ;; `icicle-previous-raw-non-file-name-inputs'.
5543 ;; * Faces `icicle-completion', `icicle-multi-command-completion',
5544 ;; and `icicle-mustmatch-completion' indicate the status of
5545 ;; minibuffer completion. During completion, Icicles uses them for
5546 ;; a minibuffer indicator and, if user option
5547 ;; `icicle-highlight-lighter-flag' is non-`nil', for the `Icy'
5548 ;; mode-line lighter as well.
5550 ;; * Non-`nil' option
5551 ;; `icicle-highlight-input-initial-whitespace-flag' uses face
5552 ;; `icicle-whitespace-highlight' to highlight any whitespace that
5553 ;; starts your minibuffer input. This is done to help you
5554 ;; recognize accidentally typing such whitespace. Otherwise, you
5555 ;; might not understand the set of matching completion candidates
5556 ;; (or lack thereof). There is not necessarily anything wrong with
5557 ;; input that starts with whitespace - it might be what you want,
5558 ;; but without this highlighting it is easy to not notice the
5561 ;; * The part of your current input that does not complete can be
5562 ;; highlighted automatically, and you can then remove that part
5563 ;; using `C-M-l'. This highlighting is controlled by options
5564 ;; `icicle-incremental-completion-flag',
5565 ;; `icicle-test-for-remote-files-flag',
5566 ;; `icicle-highlight-input-completion-failure',
5567 ;; `icicle-highlight-input-completion-failure-delay', and
5568 ;; `icicle-highlight-input-completion-failure-threshold'. The
5569 ;; highlighting uses face `icicle-input-completion-fail' (for
5570 ;; strict completion) or `icicle-input-completion-fail-lax' (for
5571 ;; lax completion). For details, see the option doc strings and
5572 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Highlights the Input that Won't Complete").
5574 ;; * User option `icicle-top-level-key-bindings' specifies top-level
5575 ;; commands and their bindings for Icicle mode. By default, this
5576 ;; rebinds several standard Emacs keys (in Icicle mode only). For
5577 ;; example, it substitutes `icicle-kill-buffer' for `kill-buffer'
5578 ;; (binding it to whatever `kill-buffer' is bound to globally).
5579 ;; Top-level commands are commands that are not used only in the
5580 ;; minibuffer. To change these bindings, customize
5581 ;; `icicle-top-level-key-bindings'. If you do that, then you must
5582 ;; exit and re-enter Icicle mode to ensure that the change takes
5583 ;; effect. This is really necessary only if your changes would
5586 ;; * Non-`nil' option `icicle-define-alias-commands-flag' defines a
5587 ;; few top-level Icicles commands whose names do not begin with
5588 ;; `icicle-', for convenience when using `M-x'. For example,
5589 ;; command `toggle' is defined as an alias for command
5590 ;; `icicle-toggle-option'. In any case, no such command is ever
5591 ;; defined by Icicles if a function with the same name is already
5594 ;; * Non-`nil' option `icicle-byte-compile-eval-after-load-flag'
5595 ;; means byte-compile definitions made within `eval-after-load'.
5596 ;; Some Icicles functions (commands, in particular) work only if a
5597 ;; given library is loaded. Some such functions are defined inside
5598 ;; an `eval-after-load' form, which means they are defined only,
5599 ;; and as soon as, the required library is loaded.
5601 ;; If this option is non-`nil' then those function definitions are
5602 ;; byte-compiled. This compilation adds a bit to the load time, in
5603 ;; effect, but it means that the functions run faster.
5605 ;; * User option `icicle-color-themes' is a list of color themes to
5606 ;; cycle through when you use command `icicle-color-theme'.
5608 ;; * User option `icicle-saved-completion-sets' is a persistent list
5609 ;; of named sets of completion candidates. You can switch among
5610 ;; such sets at any time. See
5611 ;; (@file :file-name "icicles-doc1.el" :to "Persistent Sets of Completion Candidates").
5613 ;; * User option `icicle-filesets-as-saved-completion-sets-flag'
5614 ;; non-`nil' means you can use Emacs filesets to save completion
5615 ;; candidates persistently. This means that you can save file-name
5616 ;; candidates in a persistent Icicles saved completion set (cache
5617 ;; file) or in in an Emacs fileset. It also means that an Icicles
5618 ;; persistent completion set can contain filesets, in addition to
5619 ;; file names: any number of filesets, and filesets of different
5620 ;; type. Available only for Emacs 22 and later, and you must load
5621 ;; library `filesets.el' (and enable filesets using
5622 ;; `(filesets-init)').
5624 ;; * User option `icicle-key-descriptions-use-<>-flag' determines
5625 ;; whether angle brackets (`<', `>') are used by Icicles for named
5626 ;; keys, such as function keys (`<f9>' vs `f9') and pseudo keys
5627 ;; (`<mode-line>' vs `mode-line'). Non-`nil' means to use angle
5628 ;; brackets. This option does not affect Emacs key descriptions
5629 ;; outside of Icicles (e.g. `C-h k' or `C-h w'), and it has no
5630 ;; effect for versions of Emacs prior to 21, because they never use
5631 ;; angle brackets. The default value is `nil', because I think
5632 ;; angle brackets reduce readability.
5634 ;; * User option `icicle-keymaps-for-key-completion' is a list of
5635 ;; variables that are bound to keymaps in which you want to bind
5636 ;; `S-TAB' (actually, each of the keys in the value of option
5637 ;; `icicle-key-complete-keys') to `icicle-complete-keys'. Each
5638 ;; such keymap should have at least one prefix key. `S-TAB' is
5639 ;; bound in each keymap, so that you can use it to complete the
5640 ;; prefix keys. See also `icicle-complete-key-anyway-flag'.
5642 ;; * Non-`nil' option `icicle-complete-key-anyway-flag' means bind
5643 ;; `S-TAB' (actually, each of the keys in the value of option
5644 ;; `icicle-key-complete-keys') to `icicle-complete-keys' in each
5645 ;; keymap of option `icicle-keymaps-for-key-completion', regardless
5646 ;; of whether `S-TAB' already has a binding in that keymap. A
5647 ;; value of `nil' means bind `S-TAB' only if there is not already a
5650 ;; * Non-`nil' option `icicle-complete-keys-self-insert-ranges' means
5651 ;; that `icicle-complete-keys' includes some self-inserting keys as
5652 ;; completion candidates. You will probably want to leave this
5653 ;; `nil'. This option has no effect before Emacs 22.
5654 ;; See (@file :file-name "icicles-doc1.el" :to "Entering Special and Foreign Characters")
5656 ;; * User option `icicle-yank-function' is a function to use to yank
5657 ;; text. By default, it is `yank'. Command
5658 ;; `icicle-yank-maybe-completing' calls this function, except when
5659 ;; it is called from the minibuffer or called with a negative
5662 ;; * Non-`nil' user option `icicle-use-candidates-only-once-flag'
5663 ;; means that acting on a candidate removes it from the set of
5664 ;; available candidates, so that you do not see that it can be used
5665 ;; again. (`TAB' or `S-TAB' makes it available again.) The
5666 ;; default value is `nil', and you probably do not want to
5667 ;; customize this. However, if you write Emacs-Lisp code that uses
5668 ;; completion, then you can bind this to non-`nil' in contexts
5669 ;; where that makes sense.
5671 ;; * Non-`nil' user option `icicle-deletion-action-flag' means
5672 ;; `S-delete' during completion deletes the current object. More
5673 ;; precisely, it deletes the object named by the current completion
5674 ;; candidate, if a deletion action is defined for the current
5675 ;; command. If no deletion action is defined, then the value of
5676 ;; this option has no effect for that command.
5678 ;; * User option `icicle-alternative-actions-alist' is an alist that
5679 ;; associates Emacs commands and alternative action functions. It
5680 ;; overrides any alternative actions defined otherwise for the
5683 ;; * User option `icicle-type-actions-alist' is an alist that
5684 ;; associates Emacs object types, such as buffer, file, and
5685 ;; process, with functions that accept an object of the given type
5686 ;; as their only required object. This is used by some Emacs
5687 ;; commands during completion to prompt for a function to apply to
5688 ;; the current completion candidate. Each function can be a symbol
5689 ;; or a lambda expression. At runtime, symbols that are not
5690 ;; functions (`functionp') are ignored.
5692 ;; * User option `icicle-type-actions-alist' is an alist of Emacs
5693 ;; object types and associated actions (functions). Each function
5694 ;; must accept an object of the specified type as its only required
5695 ;; argument. A function here can be a symbol or a lambda
5696 ;; expression. Any symbols that do not have function definitions
5697 ;; when this option is used are filtered out (not used).
5699 ;; * Non-`nil' user option `icicle-use-anything-candidates-flag'
5700 ;; means Anything actions are used for candidate alternate actions
5701 ;; in some Icicles commands, and Anything types and actions are
5702 ;; used by command `icicle-object-action' (aka `what-which-how' and
5703 ;; `a'). The default value is `t'. This option has no effect if
5704 ;; library `anything.el' cannot be loaded.
5706 ;; * Non-`nil' user option
5707 ;; `icicle-anything-transform-candidates-flag' means that Anything
5708 ;; function `anything-transform-candidates' is applied to displayed
5709 ;; Anything candidates in Icicles.
5711 ;; The advantage of a `nil' value is that command `icicle-anything'
5712 ;; then acts as a multi-command: you can act on multiple
5713 ;; candidates, or apply multiple actions for the same candidate,
5714 ;; within a single invocation of `icicle-anything' (or related
5715 ;; commands). The advantage of a non-`nil' value is that some of
5716 ;; the displayed Anything candidates might be more readable. The
5717 ;; default value is `nil'. This option has no effect if library
5718 ;; `anything.el' cannot be loaded.
5720 ;; * User option `icicle-WYSIWYG-Completions-flag' controls how face
5721 ;; and color names are displayed as candidates in `*Completions*'.
5722 ;; If value is non-`nil', then a WYSIWYG (what you see is what you
5723 ;; get) sample of the face or color is shown. If the value is a
5724 ;; string, then a face name is accompanied by a separate face
5725 ;; swatch with that string text. If the value is `t', then the
5726 ;; face name itself is shown using the face it names. You can use
5727 ;; command `icicle-toggle-WYSIWYG-Completions' to toggle this
5730 ;; * Non-`nil' user option
5731 ;; `icicle-unpropertize-completion-result-flag' means that
5732 ;; `completing-read' and (starting with Emacs 23) `read-file-name'
5733 ;; will strip all text properties from the result they return.
5734 ;; Regardless of the option value, Icicles strips text properties
5735 ;; that it adds for its internal use. See the doc string of
5736 ;; function `icicle-unpropertize' for more information about this.
5738 ;; The default value of the option is `nil'. It is not likely that
5739 ;; you will need to change this, but you might if you use some
5740 ;; other library that cannot accept a propertized string as the
5741 ;; result of completion.
5743 ;; Note: This is the case if you use GNUS - it has a known bug in
5744 ;; this regard (reported 2008-06-21). It blindly prints the
5745 ;; Emacs-Lisp string that is the result of completion into an MML
5746 ;; attribute value: filename=#("~/.gnus/attach.el" 0 25 (face
5747 ;; nil)). GNUS should ensure that whatever it uses for an
5748 ;; attribute value is valid for MML (has normal "..." string
5749 ;; syntax, with acceptable characters). But it simply calls a Lisp
5750 ;; print function, which prints #("...").
5752 ;; * User options `icicle-pp-eval-expression-print-length' and
5753 ;; `icicle-pp-eval-expression-print-level' control the Lisp sexp
5754 ;; print length and print level, respectively, for values printed
5755 ;; by `M-:' (`icicle-pp-eval-expression').
5757 ;; * Non-`nil' option `icicle-guess-commands-in-path' means that all
5758 ;; executable files (or all files, if option
5759 ;; `shell-completion-execonly' is `nil') in your search path are
5760 ;; included among the completion candidates whenever a shell
5761 ;; command is read. The particular non-`nil' value determines when
5762 ;; this list of commands is updated from your current search path.
5763 ;; The default value is `nil'.
5764 ;; See (@> "Icicles Shell-Command Enhancements").
5766 ;; * Non-`nil' option `icicle-quote-shell-file-name-flag' means that
5767 ;; `icicle-read-shell-command-completing' double-quotes the file
5768 ;; name at the beginning of the shell command it reads. This
5769 ;; affects several Emacs commands, such as `M-!' that read a shell
5770 ;; command and its arguments.
5772 ;; If this is `nil', then such commands will not quote a
5773 ;; shell-command file name such as
5774 ;; `c:/Program Files/My Dir/mycmd.exe'. In that case, a shell such
5775 ;; as `bash' fails for a shell command such as
5776 ;; `c:/Program Files/My Dir/mycmd.exe arg1 arg2 &', because it
5777 ;; interprets only `c:/Program' as the shell command. That is, it
5778 ;; interprets the space (`SPC') characters in the file name as
5781 ;; If this is non-`nil' (the default value), then input such as
5782 ;; `c:/Program Files/My Dir/mycmd.exe arg1 arg2 &' is passed to the
5783 ;; shell as `"c:/Program Files/My Dir/mycmd.exe" arg1 arg2 &'
5784 ;; (notice the double-quotes).
5786 ;; See the doc string of `icicle-quote-file-name-part-of-cmd' for
5787 ;; information about the characters that, like `SPC', lead to
5788 ;; file-name quoting.
5790 ;; * Non-`nil' user option `icicle-inhibit-ding-flag' means Icicles
5791 ;; never uses an audible bell (ding).
5793 ;; * Option `icicle-option-type-prefix-arg-list' is a list of symbols
5794 ;; that control prefix arguments for command
5795 ;; `icicle-describe-option-of-type (bound to `C-h C-o' by
5796 ;; default). A list of six symbols taken from this list:
5798 ;; `direct' `inherit' `inherit-or-value'
5799 ;; `direct-or-value' `inherit-or-regexp' `direct-or-regexp'
5801 ;; Choose the order you like. The list members map, in order from
5802 ;; left to right, to these prefix argument keys:
5807 ;; 4. `C-9' (positive)
5809 ;; 6. `C--' (negative)
5811 ;; For the meanings of the symbols, see the doc string of
5812 ;; `icicle-describe-option-of-type', which describes the default
5813 ;; prefix-argument bindings for the command.
5815 ;; * Non-`nil' user option `icicle-customize-save-flag' means that
5816 ;; Icicles will save the updated value of option
5817 ;; `icicle-command-abbrev-alist' when you quit Emacs. This is the
5818 ;; normal behavior. If you for some reason do not want your
5819 ;; `custom-file' or init file updated in this way, then customize
5820 ;; `icicle-customize-save-flag' to `nil'.
5822 ;; * If `icicle-buffers-ido-like-flag' is `t' then `icicle-buffer'
5823 ;; and similar commands act more Ido-like. Specifically, those
5824 ;; commands then bind these options to `t':
5825 ;; `icicle-show-Completions-initially-flag',
5826 ;; `icicle-top-level-when-sole-completion-flag', and
5827 ;; `icicle-default-value'.
5829 ;; * If `icicle-files-ido-like-flag' is `t' then `icicle-file' and
5830 ;; similar commands act more Ido-like. Specifically, those
5831 ;; commands then bind these options to `t':
5832 ;; `icicle-show-Completions-initially-flag',
5833 ;; `icicle-top-level-when-sole-completion-flag', and
5834 ;; `icicle-default-value'.
5836 ;; * The value of option `icicle-customize-save-variable-function' is
5837 ;; the function Icicles uses to automatically save user option
5838 ;; changes made by some commands. I recommend that you do *NOT*
5839 ;; change this option value. This is provided only for users who
5840 ;; might want to disable such automatic saving of option changes,
5841 ;; by setting this to `ignore', or users who might want to manage
5842 ;; such option saving using their own function instead of the
5843 ;; default value, `customize-save-variable'.
5845 ;;(@* "File-Name and Directory-Name Completion Tips")
5847 ;; File-Name and Directory-Name Completion Tips
5848 ;; --------------------------------------------
5850 ;; This section contains some tips about completing file and
5853 ;; * Functions `icicle-file-type-less-p', `icicle-dirs-first-p', and
5854 ;; `icicle-dirs-last-p' are provided as possible values for user
5855 ;; option `icicle-sort-comparer'. When choosing a sort order using
5856 ;; `C-,' or `M-,', these are called `by file type', `by directories
5857 ;; first', and `by directories last'. They sort directory names
5858 ;; (alphabetically) before non-directory names (after, for
5859 ;; `icicle-dirs-last-p'). Function `icicle-file-type-less-p' sorts
5860 ;; non-directories by file type (extension) alphabetically. For
5861 ;; non-file-name input these all act like
5862 ;; `icicle-case-string-less-p'.
5864 ;; * User option `icicle-cycle-into-subdirs-flag' controls whether or
5865 ;; not minibuffer-input cycling explores subdirectories. By
5866 ;; default, it is `nil', meaning that cycling does not descend into
5869 ;; non-`nil' - When this option is non-nil, you might want to use a
5870 ;; function such as `icicle-dirs-last-p' for option
5871 ;; `icicle-sort-comparer', to prevent cycling depth-first
5872 ;; into the subdirectories.
5874 ;; `nil' - When this option is `nil', you can still choose to cycle
5875 ;; into a given directory (which is why `nil' is the default
5876 ;; value). When cycling reaches a candidate directory that
5877 ;; you want to cycle through, just: 1) move the cursor
5878 ;; (e.g. `C-e'), 2) hit `TAB' or `S-TAB' to "complete" the
5879 ;; candidate, and then 3) use any of the cycle keys, such as
5880 ;; `down', to cycle within the candidate directory.
5882 ;; Although the candidate directory was already completed by
5883 ;; cycling, moving the cursor and explicitly "completing" it
5884 ;; tells Icicles that you want to treat the candidate in the
5885 ;; minibuffer as real input, just as if you had typed it, not
5886 ;; merely as a cycling candidate.
5888 ;; * You can use `..' during completion to access a parent directory,
5889 ;; and you can use `/' and `~/' to shadow input to the left. There
5890 ;; is currently no special treatment of MS Windows drive letters
5891 ;; (e.g. `C:') - I use Cygwin on Windows.
5893 ;; * Non-`nil' user option
5894 ;; `icicle-hide-common-match-in-Completions-flag' hides the common
5895 ;; match for your current input from each candidate in
5896 ;; `*Completions*'. You can toggle this at any time during
5897 ;; completion using `C-x .' (`icicle-toggle-hiding-common-match').
5898 ;; This can be especially useful when reading an absolute file name
5899 ;; (e.g. `C-u C-x C-f'), by removing any common directory
5902 ;; * Standard Emacs user option `completion-ignored-extensions' is a
5903 ;; list of file-name extensions. File names that match any of
5904 ;; these extensions are generally ignored for completion (but see
5905 ;; the doc string for particulars). In Icicles, however, the
5906 ;; behavior is slightly different:
5908 ;; - In vanilla Emacs the option is itself ignored for display in
5909 ;; buffer `*Completions*'. That is, even file names that are
5910 ;; ignored for completion are shown in `*Completions*' as
5911 ;; available completion candidates.
5913 ;; - In Icicles this is not the case. When a file name is ignored
5914 ;; it is ignored completely; it is not shown in `*Completions*'.
5915 ;; But in Icicles you can toggle this ignoring off or on at any
5916 ;; time during completion, using `C-.' in the minibuffer.
5918 ;; In addition, if you load library `completion-ignored-build.el',
5919 ;; by Kevin Ryde, then Icicles automatically takes advantage of
5920 ;; that library's dynamic adjustment of ignored extensions. (Just
5921 ;; load the library - do not enable its minor mode or advice.)
5923 ;; * User option `icicle-use-~-for-home-dir-flag' controls whether
5924 ;; your home directory is written in the minibuffer using `~' or in
5925 ;; expanded form, during completion. The default value is `t',
5926 ;; which means to use `~', saving minibuffer space. You can toggle
5927 ;; this option at any time using command
5928 ;; `icicle-toggle-~-for-home-dir', bound to `M-~'.
5930 ;; * Remember that you can use a regular expression to
5931 ;; apropos-complete file names. This is a powerful feature. Do
5932 ;; not confuse its use with the ability to use shell wildcards
5933 ;; (globbing) to access multiple files at once. For example, if
5934 ;; you use `C-x 4 f *.el RET', then all files with suffix `el' will
5935 ;; be opened. Regexp matching is used only for apropos (not
5936 ;; prefix) completion and cycling. See
5937 ;; (@file :file-name "icicles-doc1.el" :to "What About Special-Character Conflicts?").
5939 ;; * You can use `$' for both environment variables and as a regexp
5940 ;; special character. For example, you can use a pattern such as
5941 ;; `$HOME.*t$' to match the files in your home directory (`$HOME')
5942 ;; whose names end in `t'. See
5943 ;; (@file :file-name "icicles-doc1.el" :to "What About Special-Character Conflicts?").
5945 ;; * Starting with Emacs 23, and if the current `TAB' completion
5946 ;; method is `vanilla' (see (@* "Fuzzy Completion")), you can
5947 ;; complete environment variables during file-name completion,
5948 ;; using `TAB'. So you can, for example, complete `$HO' to any of
5949 ;; the candidates `HOME', `HOMEDRIVE', `HOMEPATH'. This is in
5950 ;; addition to the expansion of complete environment variables
5951 ;; (e.g. `$HOME' to `/my/home/dir/') when you use `S-TAB' or `RET'.
5953 ;; * You can use the idiom `\W$' as input to match only directories,
5954 ;; when a command asks for a file or directory name. The `\W' says
5955 ;; to match any non word-syntax character. The `$' says to match
5956 ;; this at the end of the name. This works because directory names
5957 ;; appear as completion candidates with a trailing slash (`/'), and
5958 ;; slash (`/') is about the only non word-syntax character that is
5959 ;; likely to appear in file-name completions. See
5960 ;; (@file :file-name "icicles-doc1.el" :to "What About Special-Character Conflicts?").
5962 ;; * You can use library `ffap.el', if you like, with Icicles, to
5963 ;; pick up the file, directory, or URL name under the cursor. All
5964 ;; Icicles features are available during file-name and URL
5965 ;; completion. If you like `ffap.el', you might also like to try
5966 ;; my extension library `ffap-.el'. See also
5967 ;; (@file :file-name "icicles-doc1.el" :to "Inserting Text Found Near the Cursor").
5969 ;; * Many Icicles commands that target file or directory names look
5970 ;; only in the current directory (`default-directory'). This means
5971 ;; that the directory part of the name is ignored for matching
5972 ;; purposes. You can thus use apropos completion to match a
5973 ;; substring, without needing to prefix the substring with `.*'.
5974 ;; For example, to match file `favorite-foo-file.bar' in directory
5975 ;; `/some/path/to/my/', it is sufficient to use either `foo' or
5976 ;; `/some/path/to/my/foo'.
5978 ;; * Some Icicles commands that target file names match your input
5979 ;; against file names as ordinary strings, that is, with no notion
5980 ;; that they are actually file names. This is the case for
5981 ;; `icicle-locate-file', `icicle-recent-file',
5982 ;; `icicle-find-file-in-tags-table', and
5983 ;; `icicle-find-file-absolute', as well as `icicle-file' with a
5984 ;; prefix argument. Such candidates are often absolute file names.
5985 ;; In that case, you can regexp-match against any part of the
5986 ;; absolute file name, including directory components. See
5987 ;; (@file :file-name "icicles-doc1.el" :to "File-Name Input and Locating Files Anywhere").
5989 ;; * If you have symbolic links that might get in the way of
5990 ;; exploring directories while locating files, you can use command
5991 ;; `icicle-locate-file-no-symlinks' instead of
5992 ;; icicle-ignored-directories' - it will not follow symbolic links.
5994 ;; This also gives you a way to temporarily avoid descending into a
5995 ;; subdirectory you are not interested in: put a symbolic link in
5996 ;; its place temporarily.
5998 ;; Another, cleaner way to skip certain directories is to customize
5999 ;; or `let'-bind option `icicle-ignored-directories'. By default
6000 ;; this is the value of `vc-directory-exclusion-list', which means
6001 ;; that it ignores version-control directories.
6005 ;; * (@> "Customization and General Tips") for general tips about
6006 ;; using Icicles. Many of those tips apply also to file-name and
6007 ;; directory-name completion.
6008 ;; * (@file :file-name "icicles-doc1.el" :to "File-Name Input and Locating Files Anywhere").
6010 ;;(@* "Key Bindings")
6015 ;; You can customize any of the key bindings that Icicles uses - see
6016 ;; (@> "Customizing Key Bindings"). I recommend that you first try
6017 ;; using the default bindings, however. There are many Icicles key
6018 ;; bindings (in particular in the minibuffer), but they are grouped
6019 ;; into a few natural sets, to help you remember them.
6021 ;;(@* "Global Bindings")
6022 ;; ** Global Bindings **
6024 ;; Icicles does not change your global key bindings. It changes some
6025 ;; minibuffer bindings, and it adds some bindings for Icicle mode,
6026 ;; but it does not change your global bindings.
6028 ;; There are two exceptions:
6030 ;; 1. In Icicle mode, various Icicles commands are added to menu-bar
6031 ;; menus. File commands are added to the File menu, and so on, under
6032 ;; an Icicles submenu. Those items that do not belong naturally to
6033 ;; any existing menu-bar menu are added to a new top-level Icicles
6034 ;; menu and to the existing Minibuf menu. Whatever the menu they
6035 ;; appear in, however, Icicles menu items are visible only when
6036 ;; Icicle mode is active.
6038 ;; If you do not want Icicles to add items to menus besides Minibuf
6039 ;; and Icicles, then set option `icicle-touche-pas-aux-menus' to
6040 ;; non-`nil'. See (@> "Customizing Key Bindings").
6042 ;; 2. Icicles adds the key `S-TAB' (bound to `icicle-complete-keys')
6043 ;; to each existing keymap. This allows you to complete keys in any
6044 ;; keymap. For technical reasons, these bindings are not part of
6045 ;; `icicle-mode-map'; other keymaps are enhanced to include this
6046 ;; binding. However, this Icicles binding of `S-TAB' never replaces
6047 ;; any existing binding of `S-TAB'. See
6048 ;; (@file :file-name "icicles-doc1.el" :to "Key Completion") for more
6049 ;; information about this use of `S-TAB'.
6051 ;; (The documentation always refers to the key that performs key
6052 ;; completion as `S-TAB'. Actually, it is `S-TAB' only by default.
6053 ;; You can customize it, using option `icicle-key-complete-keys'.)
6055 ;;(@* "Icicle-Mode Bindings")
6056 ;; ** Icicle-Mode Bindings **
6058 ;; Most Icicle-mode bindings are in the Icicles menu-bar menu. In
6059 ;; addition, option `icicle-top-level-key-bindings' causes Icicles to
6060 ;; bind some keyboard keys to some top-level Icicles commands. Some
6061 ;; of these take the place of similar, global bindings whenever you
6062 ;; are in Icicle mode. Typically, these top-level commands are
6063 ;; Icicles multi-command versions of the vanilla Emacs commands.
6064 ;; See (@file :file-name "icicles-doc1.el" :to "Multi-Commands").
6066 ;; You can customize option `icicle-top-level-key-bindings' to
6067 ;; specify the top-level commands that you want to bind in Icicle
6068 ;; mode, and the keys you want to bind them to. With the default
6069 ;; value of `icicle-top-level-key-bindings', Icicles makes the
6070 ;; following Icicle-mode bindings:
6072 ;; * `C-c '' - `icicle-occur'
6073 ;; * `C-c =' - `icicle-imenu'
6074 ;; * `C-c `' - `icicle-search'
6075 ;; * `C-c `' - `icicle-compilation-search' (in *grep* etc.)
6076 ;; * `C-c `' - `icicle-comint-search' (in *shell* etc.)
6077 ;; * `C-c TAB' - `icicle-comint-command' (in *shell* etc.)
6078 ;; * `C-c /' - `icicle-complete-thesaurus-entry'
6079 ;; * `C-h C-o' - `icicle-describe-option-of-type'
6080 ;; * `ESC M-x' - `lacarte-execute-command'
6081 ;; * `M-`', `f10' - `lacarte-execute-menu-command'
6082 ;; * `M-x' - `icicle-execute-extended-command'
6083 ;; * `C-x SPC' - `icicle-command-abbrev'
6084 ;; * `C-x M-e' - `icicle-execute-named-keyboard-macro'
6085 ;; * `S-f4' - `icicle-kmacro'
6086 ;; * `pause' - `icicle-switch-to/from-minibuffer'
6088 ;; `S-TAB' is bound, in effect, to `icicle-complete-keys', which
6089 ;; completes a key sequence. Prefix keys followed by `S-TAB' are
6090 ;; also bound to `icicle-complete-keys'. (`S-TAB' is effectively
6091 ;; bound to other commands in buffer `*Completions*' and in the
6094 ;; (The documentation always refers to the key that performs key
6095 ;; completion as `S-TAB'. Actually, it is `S-TAB' only by default.
6096 ;; You can customize it, using option `icicle-key-complete-keys'.)
6098 ;; When `icicle-top-level-key-bindings' has its default value,
6099 ;; Icicles also substitutes all of the key bindings for some standard
6100 ;; Emacs commands. For example, Icicles binds `icicle-buffer' to all
6101 ;; keys that are globally bound outside Icicle mode to standard
6102 ;; command `switch-to-buffer'. By default, the following standard
6103 ;; commands have their bindings co-opted this way by Icicles
6106 ;; Standard Command Icicles Command
6108 ;; `abort-recursive-edit'.............`icicle-abort-recursive-edit'
6109 ;; `bookmark-jump'....................`icicle-bookmark'
6110 ;; `bookmark-jump-other-window'.......`icicle-bookmark-other-window'
6111 ;; `bookmark-set'.....................`icicle-bookmark-cmd'
6112 ;; `dabbrev-completion'...............`icicle-dabbrev-completion'
6113 ;; `delete-window'....................`icicle-delete-window'
6114 ;; `dired'............................`icicle-dired'
6115 ;; `dired-other-window'...............`icicle-dired-other-window'
6116 ;; `eval-expression'..................`icicle-pp-eval-expression'
6117 ;; `exchange-point-and-mark'.........`icicle-exchange-point-and-mark'
6118 ;; `execute-extended-command'.......`icicle-execute-extended-command'
6119 ;; `find-file'........................`icicle-file'
6120 ;; `find-file-other-window'...........`icicle-file-other-window'
6121 ;; `find-file-read-only'..............`icicle-find-file-read-only'
6122 ;; `find-file-read-only-other-window'.`...read-only-other-window'
6123 ;; `find-tag'.........................`icicle-find-tag'
6124 ;; `find-tag-other-window'.......`icicle-find-first-tag-other-window'
6125 ;; `Info-goto-node'...................`icicle-Info-goto-node'
6126 ;; `Info-index'.......................`icicle-Info-index'
6127 ;; `Info-menu'........................`icicle-Info-menu'
6128 ;; `insert-buffer'....................`icicle-insert-buffer'
6129 ;; `kill-buffer'......................`icicle-kill-buffer'
6130 ;; `lisp-complete-symbol'.............`icicle-lisp-complete-symbol'
6131 ;; `other-window'.....................`icicle-other-window-or-frame'
6132 ;; `other-frame'......................`icicle-select-frame'
6133 ;; `pop-global-mark'...`icicle-goto-global-marker-or-pop-global-mark'
6134 ;; `pop-tag-mark'.....................`icicle-pop-tag-mark'
6135 ;; `pp-eval-expression'...............`icicle-pp-eval-expression'
6136 ;; `set-mark-command'........`icicle-goto-marker-or-set-mark-command'
6137 ;; `switch-to-buffer'.................`icicle-buffer'
6138 ;; `switch-to-buffer-other-window'....`icicle-buffer-other-window'
6139 ;; `where-is'.........................`icicle-where-is'
6140 ;; `yank'.............................`icicle-yank-maybe-completing'
6142 ;; Actually, by default, Icicles binds `icicle-yank-maybe-completing'
6143 ;; to whatever the value of option `icicle-yank-function' is. By
6144 ;; default, this value is `yank'.
6146 ;; Option `icicle-top-level-key-bindings' remaps not only these
6147 ;; standard Emacs commands but also some commands provided by other
6148 ;; libraries. For example, if you use package `Bookmark+', then
6149 ;; type-specific bookmark jump commands such as
6150 ;; `bmkp-dired-jump-other-window' are remapped to Icicles
6151 ;; multi-command versions.
6153 ;; In addition, option `icicle-functions-to-redefine' redefines some
6154 ;; vanilla functions to their Icicles versions while in Icicle mode.
6155 ;; Any redefined functions that are bound to keys keep those
6156 ;; bindings. For example, `Info-index' is by default redefined to
6157 ;; `icicle-Info-index' in Icicle mode, so `i' in Info mode is
6158 ;; effectively bound to `icicle-Info-index'. Commands listed in
6159 ;; option `icicle-functions-to-redefine' are typically bound in
6160 ;; keymaps other than the global map.
6162 ;; Here are some other Icicles commands that you might want to bind
6163 ;; to keys in Icicle mode - they are not bound by Icicles (except to
6166 ;; `clear-option' (alias) - Set value of binary option to `nil'
6167 ;; `icicle-add-buffer-candidate' -
6168 ;; Add buffer to those always shown
6169 ;; `icicle-add-buffer-config' - Add to `icicle-buffer-configs'
6170 ;; `icicle-add-entry-to-saved-completion-set' -
6171 ;; Add a completion candidate to a saved set
6172 ;; `icicle-add/update-saved-completion-set' - Add a set to
6173 ;; `icicle-saved-completion-sets'
6174 ;; `icicle-apply' - Selectively apply function to alist items
6175 ;; `icicle-apropos' - `apropos', but shows matches
6176 ;; `icicle-apropos-command' - Enhanced `apropos-command'
6177 ;; `icicle-apropos-variable' - Enhanced `apropos-variable'
6178 ;; `icicle-apropos-zippy' - Show matching Zippy quotes
6179 ;; `icicle-bookmark-file-other-window' - Jump to file bookmarks
6180 ;; `icicle-bookmark-dired-other-window' - Jump to Dired bookmarks
6181 ;; `icicle-bookmark-gnus-other-window' - Jump to Gnus bookmarks
6182 ;; `icicle-bookmark-info-other-window' - Jump to Info bookmarks
6183 ;; `icicle-bookmark-local-file-other-window' - Jump to local files
6184 ;; `icicle-bookmark-non-file-other-window' - Jump to buffers
6185 ;; `icicle-bookmark-region-other-window' - Jump to region bookmarks
6186 ;; `icicle-bookmark-remote-file-other-window' - Jump to remote files
6187 ;; `icicle-bookmark-url-other-window' - Jump to URL bookmarks
6188 ;; `icicle-bookmark-w3m-other-window' - Jump to W3M bookmarks
6189 ;; `icicle-buffer-config' - Pick options for Icicles buffer commands
6190 ;; `icicle-buffer-list' - Choose a list of buffer names
6191 ;; `icicle-choose-faces' - Choose a list of face names
6192 ;; `icicle-choose-invisible-faces' - Choose invisible face names
6193 ;; `icicle-choose-visible-faces' - Choose visible face names
6194 ;; `icicle-clear-history' - Clear minibuffer histories
6195 ;; `icicle-color-theme' - Change color theme
6196 ;; `icicle-completing-yank' - Yank text using completion
6197 ;; `icicle-customize-face' - Multi-command `customize-face'
6198 ;; `icicle-customize-icicles-group' -
6199 ;; Customize Icicles options and faces
6200 ;; `icicle-delete-file' - Delete a file or directory
6201 ;; `icicle-delete-windows' - Delete all windows for a buffer
6202 ;; `icicle-doc' - Display doc of function, variable, or face
6203 ;; `icicle-doremi-increment-variable+' -
6204 ;; Increment a variable using Do Re Mi
6205 ;; `icicle-face-list' - Choose a list of face names
6206 ;; `icicle-file-list' - Choose a list of file names
6207 ;; `icicle-font' - Change the frame font
6208 ;; `icicle-frame-bg' - Change the frame background color
6209 ;; `icicle-frame-fg' - Change the frame foreground color
6210 ;; `icicle-fundoc' - Display the doc of a function
6211 ;; `icicle-hide-faces' - Hide a set of faces you choose
6212 ;; `icicle-hide-only-faces' - Hide a set of faces; show all others
6213 ;; `icicle-increment-option' - Increment numeric options (Do Re Mi)
6214 ;; `icicle-increment-variable' - Increment variables (Do Re Mi)
6215 ;; `icicle-Info-virtual-book' - Open Info on a virtual book
6216 ;; `icicle-insert-thesaurus-entry' -
6217 ;; Insert a thesaurus entry
6218 ;; `icicle-keyword-list' - Choose a list of keywords (regexps)
6219 ;; `icicle-locate-file' - Open a file located anywhere
6220 ;; `icicle-minibuffer-help' - Show Icicles minibuffer help
6221 ;; `icicle-plist' - Show symbols, property lists
6222 ;; `icicle-recent-file' - Open a recently used file
6223 ;; `icicle-recompute-shell-command-candidates' - Update from PATH
6224 ;; `icicle-remove-buffer-candidate' -
6225 ;; Remove buffer from those always shown
6226 ;; `icicle-remove-buffer-config'- Remove from `icicle-buffer-configs'
6227 ;; `icicle-remove-entry-from-saved-completion-set' -
6228 ;; Remove a candidate from a saved set
6229 ;; `icicle-remove-file-from-recentf-list' - Remove from recent files
6230 ;; `icicle-remove-saved-completion-set' - Remove a set from
6231 ;; `icicle-saved-completion-sets'
6232 ;; `icicle-reset-option-to-nil' -
6233 ;; Set value of binary option to `nil'
6234 ;; `icicle-save-string-to-variable' -
6235 ;; Save text for use with `C-='
6236 ;; `icicle-search-all-tags-bookmark' - Search bookmarks that have all
6237 ;; of a given set of tags
6238 ;; `icicle-search-all-tags-regexp-bookmark' - Search bookmarks all of
6239 ;; whose tags match a given regexp
6240 ;; `icicle-search-autofile-bookmark' - Search autofile bookmarks only
6241 ;; `icicle-search-bookmark' - Search bookmarks
6242 ;; `icicle-search-bookmark-list-bookmark' - bookmark-list bookmarks
6243 ;; `icicle-search-bookmarks-together' - Search bookmarks together
6244 ;; `icicle-search-buff-menu-marked' - Search marked buffers, in order
6245 ;; `icicle-search-buffer' - Search multiple buffers
6246 ;; `icicle-search-char-property' - Search for character properties
6247 ;; `icicle-search-desktop-bookmark' -- Search desktop bookmarks
6248 ;; `icicle-search-dired-bookmark' - Search Dired bookmarks
6249 ;; `icicle-search-dired-marked' - Search the marked files in Dired
6250 ;; `icicle-search-file' - Search multiple files
6251 ;; `icicle-search-file-bookmark' - Search file bookmarks
6252 ;; `icicle-search-gnus-bookmark' - Search Gnus bookmarks
6253 ;; `icicle-search-ibuffer-marked' - Search marked buffers in Ibuffer
6254 ;; `icicle-search-info-bookmark' - Search Info bookmarks
6255 ;; `icicle-search-local-file-bookmark' - Search local file bookmarks
6256 ;; `icicle-search-man-bookmark' - Search `man'-page bookmarks
6257 ;; `icicle-search-non-file-bookmark' - Search non-file bookmarks
6258 ;; `icicle-search-overlay-property' - Search for overlay properties
6259 ;; `icicle-search-pages' - Search Emacs pages (delimited by ^L chars)
6260 ;; `icicle-search-paragraphs' - Search Emacs paragraphs
6261 ;; `icicle-search-region-bookmark' - Search bookmarked regions
6262 ;; `icicle-search-remote-file-bookmark' - Search remote files
6263 ;; `icicle-search-sentences' - Search using sentences as contexts
6264 ;; `icicle-search-some-tags-bookmark' - Search bookmarks that have
6265 ;; some of a given set of tags
6266 ;; `icicle-search-some-tags-regexp-bookmark' - Search bookmarks some
6267 ;; of whose tags match a given regexp
6268 ;; `icicle-search-specific-buffers-bookmark' - Search bookmarks for a
6269 ;; given set of buffers
6270 ;; `icicle-search-specific-files-bookmark' - Search bookmarks for a
6271 ;; given set of files
6272 ;; `icicle-search-thing' - Search thing-at-point-defined things
6273 ;; `icicle-search-this-buffer-bookmark' - Search bookmarks in buffer
6274 ;; `icicle-search-url-bookmark' - Search URL bookmarks
6275 ;; `icicle-search-w3m-bookmark' - Search W3M bookmarks
6276 ;; `icicle-search-xml-element' - Search the contents of XML elements
6277 ;; `icicle-search-xml-element-text-node' - Search XML text nodes
6278 ;; `icicle-select-window' - Select a window by its buffer name
6279 ;; `icicle-set-option-to-t' - Set value of binary option to `t'
6280 ;; `icicle-show-faces' - Show invisible faces you choose
6281 ;; `icicle-show-only-faces' - Show some invisible faces; hide others
6282 ;; `icicle-toggle-option' - Toggle the value of a binary option
6283 ;; `icicle-vardoc' - Display the doc of a variable
6284 ;; `toggle' (alias) - Toggle the value of a binary option
6286 ;;(@* "Minibuffer Bindings")
6287 ;; ** Minibuffer Bindings **
6289 ;; There are many key bindings available while input is read in the
6290 ;; minibuffer. Most of these keys are bound in the minibuffer
6291 ;; completion keymaps, but some are bound in the `*Completions*'
6292 ;; buffer keymap and some are bound when reading input without
6295 ;; In addition, clicking `C-mouse-3' on a completion candidate in
6296 ;; buffer `*Completions*' pops up a menu of available commands. Some
6297 ;; of these menu commands are applicable to the completion you click;
6298 ;; others apply to the current state of completion or to the complete
6299 ;; set of completion candidates. The associated key bindings are
6300 ;; indicated in the menu items, so this can be a good way to learn
6301 ;; minibuffer and `*Completions*' bindings.
6303 ;; The following key is helpful during any minibuffer input. It pops
6304 ;; up the `*Help*' buffer with information about using the minibuffer
6305 ;; in Icicle mode. During completion, this includes information
6306 ;; similar to what you are reading now. It also lists toggle
6307 ;; commands and the current toggle values.
6309 ;; `C-?' - `icicle-minibuffer-help'
6311 ;; The following key bindings are made for the minibuffer completion
6312 ;; keymaps. They are in effect whenever you are using the minibuffer
6313 ;; for input with completion (e.g. `completing-read',
6314 ;; `read-file-name', `M-x').
6316 ;; `down', `wheel-down' - `icicle-next-candidate-per-mode' (modal)
6317 ;; `up', `wheel-up' - `icicle-previous-candidate-per-mode' (modal)
6319 ;; `next', `prior' - `icicle-next-apropos-candidate',
6320 ;; `icicle-previous-apropos-candidate', which
6321 ;; cycle candidate apropos completions.
6323 ;; `end', `home' - `icicle-next-prefix-candidate',
6324 ;; `icicle-previous-prefix-candidate',
6325 ;; which cycle candidate prefix completions.
6327 ;; Whether a modal cycling key is used for prefix or apropos
6328 ;; completion at a given time depends on the current completion
6329 ;; mode, which is determined by which of `TAB' and `S-TAB' was used
6330 ;; last, or by option `icicle-default-cycling-mode' if neither was
6333 ;; (The mouse wheel bindings are only for Emacs 22 and later.
6334 ;; The documentation refers to the keys that cycle completion
6335 ;; candidates as `down', `up', `next', `prior', `end', and
6336 ;; `home'. Actually, these are the cycling keys only by default.
6337 ;; You can customize them using options
6338 ;; `icicle-modal-cycle-down-keys', `icicle-modal-cycle-up-keys',
6339 ;; `icicle-apropos-cycle-next-keys',
6340 ;; `icicle-apropos-cycle-previous-keys',
6341 ;; `icicle-prefix-cycle-next-keys', and
6342 ;; icicle-prefix-cycle-previous-keys'.)
6344 ;; Keys bound globally to commands that perform simple text
6345 ;; insertion, deletion, and transposition operations - commands
6346 ;; such as `self-insert-command' - are bound to Icicles versions of
6347 ;; those commands that do the same thing but also provide apropos
6348 ;; icompletion. This includes keys such as `C-d', `C-k', and `C-w'
6349 ;; (and lots more). See (@file :file-name "icicles-doc1.el" :to "Icompletion").
6351 ;; `pause' - `icicle-switch-to/from-minibuffer': Move cursor to
6352 ;; the buffer from which the minibuffer was activated.
6354 ;; `C-insert' - `icicle-switch-to-Completions-buf': Move cursor to
6355 ;; the current candidate in buffer `*Completions*'.
6357 ;; `C-v' - `icicle-scroll-Completions-forward': Scroll the
6358 ;; `*Completions*' window forward
6360 ;; `M-v' - `icicle-scroll-Completions-backward': Scroll the
6361 ;; `*Completions*' window backward
6363 ;; `C-M-v' - `icicle-scroll-forward': Scroll the current
6364 ;; non-minibuffer window forward
6366 ;; `C-M-V' (`C-M-S-v') - `icicle-scroll-backward': Scroll the
6367 ;; current non-minibuffer window backward
6369 ;; `M-*' - `icicle-narrow-candidates': Narrow the set of
6370 ;; completion candidates using another input regexp.
6372 ;; `M-SPC' - `icicle-prefix-word-complete': Complete current input
6373 ;; in minibuffer, as a prefix, a single word at a time.
6374 ;; This replaces `minibuffer-complete-word'. In fact,
6375 ;; it is the keys in `icicle-word-completion-keys' that
6376 ;; are bound to this command; `M-SPC' is by default.
6378 ;; `S-SPC' - `icicle-apropos-complete-and-narrow': Same as
6379 ;; `S-TAB' followed by `M-*'.
6381 ;; `TAB' - `icicle-prefix-complete': Complete current input in
6382 ;; minibuffer, as a prefix. If there is more than one
6383 ;; prefix-completion candidate, display them in buffer
6384 ;; `*Completions*', highlighting the common prefix.
6385 ;; This replaces `minibuffer-complete'.
6387 ;; (The documentation always refers to the key that does
6388 ;; this as `TAB'. Actually, it is only `TAB' by
6389 ;; default. You can customize it, using option
6390 ;; `icicle-prefix-complete-keys'.)
6392 ;; `S-TAB' - In the minibuffer: `icicle-apropos-complete' - like
6393 ;; `TAB', but use apropos completion. In buffer
6394 ;; `*Completions*': `icicle-move-to-previous-completion'
6395 ;; - move backwards among candidates.
6397 ;; (The documentation always refers to the keys that do
6398 ;; these things as `S-TAB'. Actually, they are only
6399 ;; `S-TAB' by default. You can customize the keys,
6400 ;; using options `icicle-apropos-complete-keys' and
6401 ;; `icicle-previous-candidate-keys'.)
6403 ;; `C-M-TAB' - `icicle-prefix-complete-no-display': Like `TAB', but
6404 ;; does not display candidates in `*Completions*'.
6406 ;; (The documentation always refers to the key that does
6407 ;; this as `C-M-TAB'. Actually, it is only `C-M-TAB' by
6408 ;; default. You can customize it, using option
6409 ;; `icicle-prefix-complete-no-display-keys'.)
6411 ;; `C-M-S-TAB' - `icicle-apropos-complete-no-display': Like
6412 ;; `S-TAB', but does not display candidates.
6414 ;; (The documentation always refers to the key that does
6415 ;; this as `C-M-S-TAB'. Actually, it is only
6416 ;; `C-M-S-TAB' by default. You can customize it, using
6417 ;; option `icicle-apropos-complete-no-display-keys'.)
6419 ;; `C-M-&' - `icicle-save-predicate-to-variable': Save the current
6420 ;; predicate used for completion to a variable.
6422 ;; `delete' - `icicle-remove-candidate': Remove the current
6423 ;; candidate from consideration.
6425 ;; `S-mouse-2' - `icicle-mouse-remove-candidate': Same as `delete'.
6427 ;; `M-q' - `icicle-insert-key-description': Insert the textual
6428 ;; representation of a key sequence, during key
6431 ;; `M-o' - `icicle-insert-history-element': Invoke completion to
6432 ;; insert a previously entered input in the minibuffer.
6434 ;; `M-%' - Regexp quote current input or its active region, then
6435 ;; apropos-complete. Use this to literally match all or
6436 ;; some input in the context of regexp matching overall.
6438 ;; `C-M-F' (`C-M-S-f') - `icicle-read+insert-file-name': Invoke
6439 ;; completion to insert a file name in the minibuffer.
6441 ;; `C-M-C' (`C-M-S-c') - `icicle-completing-read+insert': Invoke
6442 ;; completion to insert something other than a file name
6443 ;; (not always available).
6445 ;; (`C-M-F' and `C-M-C' are the default values for
6446 ;; the keys that invoke completion on demand. You can
6447 ;; customize the keys to use, using options
6448 ;; `icicle-read+insert-file-name-keys' and
6449 ;; `icicle-completing-read+insert-keys'.)
6451 ;; In Icicles, multi-line completion candidates are not uncommon.
6452 ;; You can move up and down minibuffer lines with `C-p' and `C-n',
6453 ;; and you can use the following keys to move among line beginnings
6456 ;; `C-a', `C-e' - `icicle-beginning-of-line+',
6457 ;; `icicle-end-of-line+': Like normal `C-a', `C-e', but
6458 ;; repeating goes to the previous or next line.
6460 ;; If you use libraries `fit-frame.el' and `oneonone.el' with a
6461 ;; standalone minibuffer frame (non-`nil'
6462 ;; `1on1-minibuffer-frame-flag'), and if option
6463 ;; `1on1-fit-minibuffer-frame-flag' is non-`nil', then the minibuffer
6464 ;; frame is automatically resized to fit its content as you edit that
6465 ;; content. (Options `1on1-fit-minibuffer-frame-max-height' and
6466 ;; `1on1-fit-minibuffer-frame-max-height-percent' define the maximum
6467 ;; height for this.)
6469 ;; If, in addition, you bind `1on1-fit-minibuffer-frame' to a key,
6470 ;; then you can use that key repeatedly to increase the height by one
6471 ;; line, even beyond the maximum. Library `setup-keys.el' binds this
6474 ;; (If you do not use a separate minibuffer frame, then you will
6475 ;; likely want to set standard option `resize-mini-windows' to `t',
6476 ;; not to `grow-only', at least while in Icicle mode.)
6478 ;; `C-M-j' - `icicle-insert-list-join-string': Insert
6479 ;; `icicle-list-join-string'. See also
6480 ;; (@> "Multi-Completions").
6482 ;; You can insert a single Icicles multi-line dot using `C-u .', or
6483 ;; by turning on this dot magic generally, using `C-M-.':
6485 ;; `.' - `icicle-insert-dot-command'
6486 ;; `C-M-.' - `icicle-toggle-dot'
6488 ;; In vanilla Emacs, the following keys have a special purpose during
6489 ;; input completion, but in Icicles they simply insert the character
6490 ;; typed - they are self-inserting. This is because (1) there are
6491 ;; better ways to do what vanilla Emacs uses these keys for and (2)
6492 ;; it is useful to be able to insert these characters without first
6493 ;; typing `C-q' to quote them.
6496 ;; (@file :file-name "icicles-doc1.el" :to "What About Special-Character Conflicts?")
6500 ;; `C-j' (newline) - see also `C-o', above, and
6501 ;; (@> "Multi-Completions")
6503 ;; The following minibuffer bindings are made to clear minibuffer
6504 ;; input, making them handy for editing and removing completions
6505 ;; (e.g. default or initial values) in the minibuffer.
6507 ;; `M-k' - `icicle-erase-minibuffer-or-history-element'
6508 ;; `M-S-backspace', `M-S-delete' - `icicle-erase-minibuffer'
6510 ;; `M-k' has an alternative behavior when you are cycling minibuffer
6511 ;; history items: it deletes the current item from the history.
6513 ;; The following key is bound during completion to control the
6514 ;; display of thumbnail images in `*Completions*' for candidates that
6515 ;; name image files. It cycles the value of option
6516 ;; `icicle-image-files-in-Completions' to show images and names (the
6517 ;; default), show only names, or show only images.
6519 ;; `C-x t' - `icicle-cycle-image-file-thumbnail'
6521 ;; During (absolute or relative) file-name completion, the following
6522 ;; minibuffer bindings are also in effect:
6524 ;; `C-backspace' - `icicle-up-directory':
6525 ;; Navigate up the directory hierarchy.
6526 ;; `C-c +' - `icicle-make-directory': Create a directory.
6527 ;; `C-x m' - `icicle-bookmark-file-other-window':
6528 ;; Visit a file or directory (Dired) bookmark.
6530 ;; (@file :file-name "icicles-doc1.el" :to "Accessing Saved Locations (Bookmarks) on the Fly").
6531 ;; (Available only if you use `bookmark+.el'.)
6533 ;; During absolute file-name completion, you can use `C-c C-d' to
6534 ;; change the current directory on the fly (think UNIX command `cd').
6536 ;; (@file :file-name "icicles-doc1.el" :to "Absolute File Names and Different Directories").
6538 ;; During buffer-name completion, the following minibuffer bindings
6539 ;; are also in effect:
6541 ;; `C-x m' - `icicle-bookmark-non-file-other-window':
6542 ;; Visit a buffer (non-file) bookmark. See also
6543 ;; (@file :file-name "icicles-doc1.el" :to "Accessing Saved Locations (Bookmarks) on the Fly").
6544 ;; (Available only if you use `bookmark+.el'.)
6546 ;; `C-x M' - `icicle-filter-buffer-cands-for-mode':
6547 ;; Filter the buffer candidate to keep only those
6548 ;; in a given major mode (you are prompted for
6551 ;; The following minibuffer binding moves the cursor to the start of
6552 ;; the part of your input, if any, that is highlighted because it
6553 ;; does not match any completion candidate (see option
6554 ;; `icicle-highlight-input-completion-failure'). Repeating this
6555 ;; command kills the rest of the line, removing the highlighted
6556 ;; mismatched input.
6558 ;; `C-M-l' - `icicle-goto/kill-failed-input'
6560 ;; The remaining input matches at least one candidate.
6562 ;; The following minibuffer bindings can be used to get rid of a
6563 ;; completion inserted during cycling, and retrieve what you last
6564 ;; typed during completion or any previous completion inputs:
6566 ;; `C-l' - `icicle-retrieve-previous-input'
6567 ;; `C-S-l' (`C-L') - `icicle-retrieve-next-input'
6569 ;; You can use these to cycle among and reuse inputs that you typed
6570 ;; during completion but did not enter. This completion input is not
6571 ;; recorded in the standard input histories - they record only input
6572 ;; that you have entered with `RET'.
6573 ;; See (@file :file-name "icicles-doc1.el" :to "History Enhancements").
6575 ;; For example, suppose that you used `C-h v hook' to examine various
6576 ;; hook variables, and you did this using`C-next' to display their
6577 ;; documentation. If you finished the command by just typing `C-g',
6578 ;; then your input (`hook') was never really entered, so it is not
6579 ;; available via the minibuffer history (`M-p'). You can retrieve it
6580 ;; with `C-l', to use it again, in your next command. User option
6581 ;; `icicle-C-l-uses-completion-flag' controls the behavior of `C-l'
6582 ;; and `C-L'; if non-`nil', then, instead of cycling inputs, these
6583 ;; commands let you access previous inputs using completion.
6585 ;; You of course have the standard access to the minibuffer history,
6586 ;; via `M-p', `M-n', `M-r', and `M-s'. In addition to these, the
6587 ;; following minibuffer bindings let you use apropos completion on
6588 ;; the current minibuffer history list. For explanation, see
6589 ;; (@file :file-name "icicles-doc1.el" :to "History Enhancements").
6591 ;; `M-h' - `icicle-history'
6592 ;; `M-pause' - `icicle-keep-only-past-inputs'
6594 ;; Minibuffer binding `C-M-pause' lets you use a different minibuffer
6595 ;; history during the current input reading with completion.
6596 ;; Normally, you are prompted for the history to use. Starting with
6597 ;; Emacs 23, if option `icicle-populate-interactive-history-flag' is
6598 ;; non-`nil', then during command, abbrev, and keyboard-macro
6599 ;; completion, `C-M-pause' completes your input against the history
6600 ;; of all commands that were invoked interactively in any way,
6601 ;; `icicle-interactive-history'.
6603 ;; The following minibuffer bindings let you act on candidate
6604 ;; completions. For explanation, see
6605 ;; (@file :file-name "icicles-doc1.el" :to "Multi-Commands"),
6606 ;; (@file :file-name "icicles-doc1.el" :to "More about Multi-Commands"),
6607 ;; (@file :file-name "icicles-doc1.el" :to "Choose All Completion Candidates"),
6608 ;; and (@> "OO: Object-Action Interaction").
6610 ;; `C-RET' - `icicle-candidate-action': current candidate
6611 ;; `C-mouse-2' - `icicle-mouse-candidate-action': clicked candidate
6612 ;; `C-down', `C-wheel-down'
6613 ;; - `icicle-next-candidate-per-mode-action' (modal)
6614 ;; `C-up', `C-wheel-up'
6615 ;; - `icicle-previous-candidate-per-mode-action'(modal)
6616 ;; `C-next' - `icicle-next-apropos-candidate-action'
6617 ;; `C-prior' - `icicle-previous-apropos-candidate-action'
6618 ;; `C-end' - `icicle-next-prefix-candidate-action'
6619 ;; `C-home' - `icicle-previous-prefix-candidate-action'
6620 ;; `C-!' - `icicle-all-candidates-action': each candidate
6621 ;; `M-!' - `icicle-all-candidates-list-action': all, as list
6622 ;; `M-RET' - `icicle-candidate-read-fn-invoke': apply function
6623 ;; `M-mouse-2' - `icicle-mouse-yank-secondary' (in minibuffer)
6624 ;; `M-mouse-2' - `icicle-mouse-candidate-read-fn-invoke': apply fn
6625 ;; `S-delete' - `icicle-delete-candidate-object': delete object
6627 ;; (Some of these are only default key bindings. You can customize
6628 ;; the keys to use for `previous' and `next' actions, for instance.
6629 ;; The mouse-wheel bindings are only for Emacs 22 and later. The
6630 ;; notation used here for the wheel bindings is that for Emacs on
6631 ;; Windows; on other platforms different key notations are used for
6632 ;; the wheel. This same note applies to corresponding keys used with
6633 ;; modifiers `C-M-' and `C-S-' - see below.)
6635 ;; Except as noted, the bindings for `icicle-mouse-*' are actually in
6636 ;; the `*Completions*' buffer.
6638 ;; The following minibuffer bindings provide help on candidate
6639 ;; completions. For explanation, see
6640 ;; (@file :file-name "icicles-doc1.el" :to "Get Help on Candidates")
6641 ;; and (@file :file-name "icicles-doc1.el" :to "Multi-Commands").
6643 ;; `C-M-RET' - `icicle-help-on-candidate': current candidate
6644 ;; `C-M-mouse-2' - `icicle-mouse-help-on-candidate': clicked
6645 ;; `C-M-down', `C-M-wheel-down'
6646 ;; - `icicle-next-candidate-per-mode-help' (modal)
6647 ;; `C-M-up', `C-M-wheel-up'
6648 ;; - `icicle-previous-candidate-per-mode-help' (modal)
6649 ;; `C-M-next' - `icicle-help-on-next-apropos-candidate'
6650 ;; `C-M-prior' - `icicle-help-on-previous-apropos-candidate'
6651 ;; `C-M-end' - `icicle-help-on-next-prefix-candidate'
6652 ;; `C-M-home' - `icicle-help-on-previous-prefix-candidate'
6654 ;; The following minibuffer bindings provide an alternative action
6655 ;; for individual candidates. The alternative action is specific to
6656 ;; the given command. Most commands define no alternative action.
6658 ;; `C-S-RET' - `icicle-candidate-alt-action': current candidate
6659 ;; `C-S-mouse-2' - `icicle-mouse-candidate-alt-action': clicked
6660 ;; `C-S-down', `C-S-wheel-down'
6661 ;; - `icicle-next-candidate-per-mode-alt-action'
6663 ;; `C-S-up', `C-S-wheel-up'
6664 ;; - `icicle-previous-candidate-per-mode-alt-action'
6666 ;; `C-S-next' - `icicle-next-apropos-candidate-alt-action'
6667 ;; `C-S-prior' - `icicle-previous-apropos-candidate-alt-action'
6668 ;; `C-S-end' - `icicle-next-prefix-candidate-alt-action'
6669 ;; `C-S-home' - `icicle-previous-prefix-candidate-alt-action'
6670 ;; `C-|' - `icicle-all-candidates-alt-action': each
6671 ;; `M-|' - `icicle-all-candidates-list-alt-action': list
6673 ;; The following minibuffer bindings let you perform set operations
6674 ;; on sets of completion candidates. For explanation, see
6675 ;; (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates").
6677 ;; `C-~' - `icicle-candidate-set-complement'
6678 ;; `C--' - `icicle-candidate-set-difference'
6679 ;; `C-+' - `icicle-candidate-set-union'
6680 ;; `C-*' - `icicle-candidate-set-intersection'
6681 ;; `C-M-<' - `icicle-candidate-set-retrieve': retrieve saved set
6682 ;; `C-M->' - `icicle-candidate-set-save': save current set
6683 ;; `C-M-)' - `icicle-candidate-set-save-selected': save selected
6684 ;; `C-<' - `icicle-candidate-set-retrieve-more': add from saved
6685 ;; `C->' - `icicle-candidate-set-save-more': add to saved set
6686 ;; `C-)' - `icicle-candidate-set-save-more-selected': selected
6687 ;; `insert' - `icicle-save/unsave-candidate': save current cand
6688 ;; `C-%' - `icicle-candidate-set-swap': swap saved and current
6689 ;; `C-:' - `icicle-candidate-set-define': define current (Lisp)
6690 ;; `M-S-mouse-2' - `icicle-mouse-save/unsave-candidate': (un)save
6691 ;; `M-S-mouse-3' - `icicle-mouse-candidate-set-save': save selected
6692 ;; `M-mouse-3' - `icicle-mouse-candidate-set-save-more'
6694 ;; The following minibuffer bindings insert text in the minibuffer.
6696 ;; `M-.' - `icicle-insert-string-at-point'
6697 ;; `C-=' - `icicle-insert-string-from-variable'
6698 ;; `M-:' - `icicle-pp-eval-expression-in-minibuffer'
6699 ;; (with a prefix arg)
6701 ;; The following minibuffer bindings let you toggle Icicles options
6702 ;; or cycle among alternative Icicles behaviors.
6704 ;; `C-A' (that is, `C-S-a') - `icicle-toggle-case-sensitivity'
6705 ;; `C-.' - `icicle-toggle-ignored-extensions' (file completion)
6706 ;; `C-.' - `icicle-toggle-search-cleanup' (search)
6707 ;; `C-M-.' - `icicle-toggle-dot'
6708 ;; `C-x .' - `icicle-toggle-hiding-common-match'
6709 ;; `C-;' - `icicle-toggle-expand-to-common-match'
6710 ;; `M-;' - `icicle-toggle-search-replace-common-match'
6711 ;; `C-M-;' - `icicle-toggle-icicle-toggle-ignoring-comments'
6712 ;; `C-,' - `icicle-change-sort-order'
6713 ;; `M-,' - `icicle-change-alternative-sort-order'
6714 ;; `C-M-,' - `icicle-toggle-alternative-sorting'
6715 ;; `C-^' - `icicle-toggle-remote-file-testing'
6716 ;; `C-^' - `icicle-toggle-highlight-all-current' (search)
6717 ;; `C-#' - `icicle-toggle-incremental-completion'
6718 ;; `C-(' - `icicle-next-TAB-completion-method'
6719 ;; `C-`' - `icicle-toggle-regexp-quote'
6720 ;; `C-M-`' - `icicle-toggle-literal-replacement' (search)
6721 ;; `C-$' - `icicle-toggle-transforming' (removal of duplicates)
6722 ;; `C-pause' - `icicle-toggle-highlight-historical-candidates'
6723 ;; `S-pause' - `icicle-toggle-highlight-saved-candidates'
6724 ;; `M-g' - `icicle-toggle-C-for-actions'
6725 ;; `M-q' - `icicle-toggle-search-whole-word' (search)
6726 ;; `M-(' - `icicle-next-S-TAB-completion-method'
6727 ;; `M-~' - `icicle-toggle-~-for-home-dir'
6728 ;; `M-_' - `icicle-toggle-ignored-space-prefix'
6729 ;; `M-_' - `icicle-toggle-search-replace-whole' (search)
6730 ;; `C-M-_' - `icicle-toggle-proxy-candidates'
6732 ;; The following minibuffer bindings let you incrementally change
6733 ;; options that affect the `*Completions*' display columns and text
6734 ;; size. To take advantage of these, you must also use Do Re Mi
6735 ;; (libraries `doremi.el' and `doremi-frm.el'). `C-x -' requires
6736 ;; Emacs 23 or later.
6738 ;; `C-x w' - `icicle-doremi-candidate-width-factor+'
6739 ;; `C-x |' - `icicle-doremi-inter-candidates-min-spaces+'
6740 ;; `C-x -' - `icicle-doremi-zoom-Completions+'
6741 ;; `C-x #' - increment/decrement option `icicle-max-candidates'
6743 ;; When used in the minibuffer, the following Icicles global binding
6744 ;; lets you remove the `*Completions*' window.
6746 ;; `C-x 0' - `icicle-delete-window'
6748 ;; The following minibuffer bindings are in effect during Icicles
6751 ;; `C-.' - `icicle-toggle-search-cleanup'
6752 ;; `C-,' - `icicle-change-sort-order'
6753 ;; `M-_' - `icicle-toggle-search-replace-whole'
6754 ;; `M-,' - `icicle-search-define-replacement'
6755 ;; `M-;' - `icicle-toggle-search-replace-common-match'
6756 ;; `M-q' - `icicle-toggle-search-whole-word'
6757 ;; `C-^' - `icicle-toggle-highlight-all-current'
6758 ;; `C-M-`' - `icicle-toggle-literal-replacement'
6760 ;; The following minibuffer binding lets you evaluate an Emacs-Lisp
6761 ;; sexp at any time, using a recursive minibuffer. It displays the
6762 ;; result of evaluation in the echo area or in a pop-up buffer, `*Pp
6763 ;; Eval Output*'. With a prefix arg (`C-u M-:'), it inserts the
6764 ;; result into the minibuffer at point.
6766 ;; `M-:' - `icicle-pp-eval-expression-in-minibuffer'
6768 ;; Some additional bindings are made available in the minibuffer for
6769 ;; the duration of specific commands:
6771 ;; * During completion of names of some kinds of objects (files,
6772 ;; buffers, directories, Info nodes), `C-x m' lets you complete
6773 ;; against bookmarks that have the same type as those objects (file
6774 ;; bookmarks, buffer bookmarks, Dired bookmarks, Info bookmarks).
6775 ;; This feature requires use of package Bookmark+.
6777 ;; * During completion of file names, `C-backspace' is bound to
6778 ;; `icicle-up-directory', which navigates to the parent directory
6779 ;; and completes there instead.
6781 ;; * During completion of bookmark names, various keys with the
6782 ;; prefix `C-M-' are bound to commands that narrow the available
6783 ;; candidates to bookmarks of a specific type. For example,
6784 ;; `C-M-d' narrows the choices to Dired bookmarks.
6786 ;; The following bindings are made for `completion-list-mode', that
6787 ;; is, for buffer `*Completions*', which shows the list of candidate
6790 ;; `left', `right' (`TAB')
6791 ;; - `icicle-move-to-previous-completion',
6792 ;; `icicle-move-to-next-completion': Navigate
6793 ;; backward & forward among candidates
6794 ;; `up', `down' - `icicle-previous-line', `icicle-next-line':
6795 ;; Navigate up & down among candidates
6796 ;; `C-insert' - `icicle-insert-completion': Move cursor to the
6797 ;; minibuffer, with the current `*Completions*'
6798 ;; candidate as input
6799 ;; `C-a', `C-e' - `icicle-beginning-of-line+',
6800 ;; `icicle-end-of-line+' (repeatable)
6801 ;; `C-g', `q' - `icicle-abort-recursive-edit'
6802 ;; `mouse-2' - `icicle-mouse-choose-completion'
6803 ;; `C-mouse-2' - `icicle-mouse-candidate-action'
6804 ;; `M-mouse-2' - `icicle-mouse-candidate-read-fn-invoke'
6805 ;; `C-M-mouse-2' - `icicle-mouse-help-on-candidate'
6806 ;; `M-S-mouse-2' - `icicle-mouse-save/unsave-candidate'
6807 ;; `C-mouse-3' - `icicle-Completions-mouse-3-menu'
6808 ;; `M-mouse-3' - `icicle-mouse-candidate-set-save-more'
6809 ;; `M-S-mouse-3' - `icicle-mouse-candidate-set-save'
6810 ;; `wheel-down' - `icicle-scroll-Completions-backward'
6811 ;; `wheel-up' - `icicle-scroll-Completions-forward'
6813 ;;(@* "Customizing Key Bindings")
6815 ;; Customizing Key Bindings
6816 ;; ------------------------
6818 ;; See (@> "Key Bindings") for a description of the key bindings
6819 ;; defined by Icicles. The options mentioned here are also presented
6820 ;; there, in context. You can customize all of the key-binding user
6821 ;; options with `M-x customize-group RET Icicles-Key-Bindings'.
6823 ;; Key bindings are very personal choices, and reflect preferences
6824 ;; and habits, as well as keyboard and other configurations. You
6825 ;; might want to change some of the bindings that Icicles creates.
6826 ;; This section tells you how to do that.
6828 ;; However, before doing so, unless the default bindings present a
6829 ;; hardware or OS configuration problem for you, please try using the
6830 ;; default bindings for a while, before deciding that you want to
6831 ;; change them. Habit is a powerful persuader, but its advice is not
6832 ;; always the best ;-).
6834 ;; The main user option for customizing key bindings is
6835 ;; `icicle-top-level-key-bindings'. You use it to change or remove
6836 ;; any of the top-level bindings in Icicle mode.
6838 ;; There are some other user options that make it easy to customize
6839 ;; Icicles key bindings. Most of these are minibuffer bindings.
6841 ;; * `icicle-modal-cycle-down-keys' (`down', `wheel-down')
6842 ;; Cycle to the next candidate (modal).
6843 ;; * `icicle-modal-cycle-up-keys' (`up', `wheel-up')
6844 ;; Cycle to the previous candidate (modal).
6845 ;; * `icicle-apropos-cycle-next-keys' (`next')
6846 ;; Cycle to the next apropos-completion candidate.
6847 ;; * `icicle-apropos-cycle-previous-keys' (`prior')
6848 ;; Cycle to the previous apropos-completion candidate.
6849 ;; * `icicle-prefix-cycle-next-keys' (`end')
6850 ;; Cycle to the next prefix-completion candidate.
6851 ;; * `icicle-prefix-cycle-previous-keys' (`home')
6852 ;; Cycle to the previous prefix-completion candidate.
6853 ;; * `icicle-modal-cycle-down-action-keys' (`C-down', `C-wheel-down)
6854 ;; Cycle to next candidate and act on it (modal).
6855 ;; * `icicle-modal-cycle-up-action-keys' (`C-up', `C-wheel-up)
6856 ;; Cycle to previous candidate and act on it (modal).
6857 ;; * `icicle-apropos-cycle-next-action-keys' (`C-next')
6858 ;; Cycle to next apropos-completion candidate and act on it.
6859 ;; * `icicle-apropos-cycle-previous-action-keys' (`C-prior')
6860 ;; Cycle to previous apropos-completion candidate and act on it.
6861 ;; * `icicle-prefix-cycle-next-action-keys' (`C-end')
6862 ;; Cycle to next prefix-completion candidate and act on it.
6863 ;; * `icicle-prefix-cycle-previous-action-keys' (`C-home')
6864 ;; Cycle to previous prefix-completion candidate and act on it.
6865 ;; * `icicle-modal-cycle-down-alt-action-keys' (`C-S-down')
6866 ;; Cycle to next candidate and alternative-act on it (modal).
6867 ;; * `icicle-modal-cycle-up-alt-action-keys' (`C-S-up')
6868 ;; Cycle to previous candidate and alternative-act on it (modal).
6869 ;; * `icicle-apropos-cycle-next-alt-action-keys' (`C-S-next')
6870 ;; Cycle to next apropos-completion candidate and alternative-act
6872 ;; * `icicle-apropos-cycle-previous-alt-action-keys' (`C-S-prior')
6873 ;; Cycle to previous apropos-completion candidate and
6874 ;; alternative-act on it.
6875 ;; * `icicle-prefix-cycle-next-alt-action-keys' (`C-S-end')
6876 ;; Cycle to next prefix-completion candidate and alternative-act
6878 ;; * `icicle-prefix-cycle-previous-alt-action-keys' (`C-S-home')
6879 ;; Cycle to previous prefix-completion candidate and
6880 ;; alternative-act on it.
6881 ;; * `icicle-modal-cycle-down-help-keys' (`C-M-down')
6882 ;; Cycle to next candidate and show help for it (modal).
6883 ;; * `icicle-modal-cycle-up-help-keys' (`C-M-up')
6884 ;; Cycle to previous candidate and show help for it (modal).
6885 ;; * `icicle-apropos-cycle-next-help-keys' (`C-M-next')
6886 ;; Cycle to next apropos-completion candidate and show help for it.
6887 ;; * `icicle-apropos-cycle-previous-help-keys' (`C-M-prior')
6888 ;; Cycle to previous apropos-completion candidate and show help.
6889 ;; * `icicle-prefix-cycle-next-help-keys' (`C-M-end')
6890 ;; Cycle to next prefix-completion candidate and show help for it.
6891 ;; * `icicle-prefix-cycle-previous-help-keys' (`C-M-home')
6892 ;; Cycle to previous prefix-completion candidate and show help.
6893 ;; * `icicle-prefix-complete-keys' (`TAB')
6894 ;; Prefix-complete your input.
6895 ;; * `icicle-apropos-complete-keys' (`S-TAB')
6896 ;; Apropos-complete your input.
6897 ;; * `icicle-prefix-complete-no-display-keys' (`C-M-TAB')
6898 ;; Prefix-complete without showing `*Completions*'.
6899 ;; * `icicle-apropos-complete-no-display-keys' (`C-M-S-TAB')
6900 ;; Apropos-complete without showing `*Completions*'.
6901 ;; * `icicle-word-completion-keys' (`M-SPC')
6902 ;; Prefix-complete your input a word at a time.
6903 ;; * `icicle-key-complete-keys' (`S-TAB')
6904 ;; Complete key sequences.
6905 ;; * `icicle-previous-candidate-keys' (`S-TAB')
6906 ;; Move to the previous candidate in `*Completions*'.
6907 ;; * `icicle-completing-read+insert-keys' (`C-M-S-c')
6908 ;; Completion on demand.
6909 ;; * `icicle-read+insert-file-name-keys' (`C-M-S-f')
6910 ;; Completion on demand for file names.
6911 ;; * `icicle-search-from-isearch-keys' (`S-TAB')
6912 ;; Start `icicle-search' from Isearch.
6913 ;; * `icicle-isearch-complete-keys' (`M-TAB', `C-M-TAB', `M-o')
6914 ;; Complete incremental search string using search ring.
6916 ;; These are the main kinds of Icicles key bindings:
6918 ;; * Global bindings
6919 ;; . Additions to menu-bar menus
6920 ;; . Key completion keys (`S-TAB' by default)
6921 ;; * Icicle mode bindings
6922 ;; * Minibuffer bindings
6924 ;;(@* "Customizing Global Bindings")
6925 ;; ** Customizing Global Bindings **
6927 ;; Icicles normally adds items to appropriate existing menu-bar
6928 ;; menus, such as File and Options, as well as to menu-bar menus
6929 ;; Minibuf and Icicles. These items are placed in an Icicles submenu
6930 ;; (e.g. Files > Icicles). If you do not want to add an Icicles
6931 ;; submenu, then set option `icicle-touche-pas-aux-menus-flag' to
6932 ;; non-`nil' before loading Icicles. The menu items are then added
6933 ;; to the Icicles menu.
6935 ;; Icicles binds key completion (`icicle-complete-keys') to the keys
6936 ;; defined in option `icicle-key-complete-keys'. See
6937 ;; (@> "Key Bindings") for more information about this.
6939 ;;(@* "Customizing Icicle Mode Bindings")
6940 ;; ** Customizing Icicle Mode Bindings **
6942 ;; In the Icicle mode keymap, several top-level commands are bound by
6943 ;; default. You can use option `icicle-top-level-key-bindings' to
6944 ;; customize the keys that are used for these commands, or to remove
6945 ;; any such bindings.
6947 ;;(@* "Customizing Minibuffer Bindings")
6948 ;; ** Customizing Minibuffer Bindings **
6950 ;; There are user options for most Icicles minibuffer bindings that
6951 ;; you might want to change - see above for the list. This section
6952 ;; tells you how to change additional bindings.
6954 ;; To understand how you can modify Icicles minibuffer bindings, it
6955 ;; helps to know how Icicles creates the default bindings. For that,
6956 ;; the best advice is to consult the Emacs-Lisp code in library
6957 ;; `icicle-mode.el'. Even if you are not very familiar with
6958 ;; Emacs-Lisp, however, you should be able to do what you want by
6959 ;; adapting the example in this section.
6961 ;; Suppose that you want to bind `f11' and `f12' to traverse the
6962 ;; input history up and down whenever you are in Icicle mode. There
6963 ;; are no user options for this, but you can do it by inserting this
6964 ;; code into your init file (~/.emacs), before the code that requires
6965 ;; (loads) library `icicles.el':
6967 ;; (add-hook 'icicle-mode-hook 'bind-my-icicles-keys)
6968 ;; (defun bind-my-icicles-keys ()
6969 ;; "Replace some default Icicles minibuffer bindings with others."
6973 ;; (list minibuffer-local-completion-map
6974 ;; minibuffer-local-must-match-map)
6976 ;; 'minibuffer-local-filename-completion-map)
6977 ;; (list minibuffer-local-filename-completion-map))))
6978 ;; (when icicle-mode
6979 ;; (define-key map [f11] 'previous-history-element)
6980 ;; (define-key map [f12] 'next-history-element))))
6984 ;; * (@> "Key Bindings")
6985 ;; * (@> "Customization and General Tips") for information
6986 ;; about other customizations, besides key bindings.
6988 ;;(@* "Icicles Redefines Some Standard Functions")
6990 ;; Icicles Redefines Some Standard Functions
6991 ;; -----------------------------------------
6993 ;; User option `icicle-functions-to-redefine' is a list of functions
6994 ;; (typically commands) that are automatically redefined in Icicle
6995 ;; mode to enhance them for Icicles completion. The original
6996 ;; definitions are restored when you exit Icicle mode. The default
6997 ;; value of `icicle-functions-to-redefine' contains the following
7000 ;; `bbdb-complete-name' (from BBDB), `comint-dynamic-complete',
7001 ;; `comint-dynamic-complete-filename',
7002 ;; `comint-replace-by-expanded-filename', `customize-apropos',
7003 ;; `customize-apropos-faces', `customize-apropos-groups',
7004 ;; `customize-apropos-options', `customize-apropos-options-of-type'
7005 ;; (from `cus-edit+.el'), `customize-face',
7006 ;; `customize-face-other-window', `dabbrev-completion',
7007 ;; `dired-read-shell-command', `ess-complete-object-name' (from
7008 ;; ESS), `gud-gdb-complete-command', `lisp-complete-symbol',
7009 ;; `lisp-completion-at-point',
7010 ;; `minibuffer-default-add-completions', `read-color',
7011 ;; `read-from-minibuffer', `read-shell-command', `read-string',
7012 ;; `recentf-make-menu-items', `repeat-complex-command'.
7014 ;; Icicles unconditionally redefines these standard Emacs functions
7015 ;; while in Icicle mode:
7017 ;; `choose-completion', `choose-completion-string',
7018 ;; `completing-read', `completing-read-multiple',
7019 ;; `completion-setup-function', `dired-smart-shell-command',
7020 ;; `display-completion-list', `exit-minibuffer',
7021 ;; `face-valid-attribute-values', `minibuffer-complete-and-exit',
7022 ;; `mouse-choose-completion', `next-history-element',
7023 ;; `read-face-name', `read-file-name', `read-number',
7024 ;; `shell-command', `shell-command-on-region', `sit-for',
7025 ;; `switch-to-completions'.
7027 ;; When you exit Icicle mode, the standard definitions are restored.
7029 ;;(@* "Programming with Fancy Candidates")
7031 ;; Programming with Fancy Candidates
7032 ;; ---------------------------------
7034 ;; This section is for Emacs-Lisp programmers.
7036 ;; Icicles lets you program with several kinds of candidates that are
7037 ;; not supported by vanilla Emacs. For lack of a better word, I call
7038 ;; them all "fancy candidates". Multi-completions are fancy
7039 ;; candidates. So are ordinary string candidates that have text
7040 ;; properties such as `face'. And there are other kinds of fancy
7043 ;; Because they are not supported by vanilla Emacs, and because
7044 ;; Icicles uses Emacs functions such as `all-completions' to perform
7045 ;; the primitive completion operations, fancy candidates require some
7046 ;; extra processing.
7048 ;; All fancy candidates must first be converted to a form that such
7049 ;; primitives can understand. During completion, fancy candidates
7050 ;; must sometimes be displayed specially, for example using
7051 ;; particular faces. And after completion, the completion result
7052 ;; must sometimes be converted back again to retrieve some or all of
7053 ;; the original candidate information.
7055 ;; This conversion (encoding and decoding) can be costly, especially
7056 ;; when there are many candidates. For this reason, it is turned
7057 ;; off, by default, so it that does not represent overhead during
7058 ;; completion of non-fancy candidates.
7060 ;; In order to use `completing-read' with fancy candidates, you must
7061 ;; do one of the following in your code:
7063 ;; 1. Propertize at least the first character of the
7064 ;; `completing-read' PROMPT argument string with a non-`nil' text
7065 ;; property `icicle-fancy-candidates'. This turns on processing
7066 ;; of fancy candidates for the duration of the `completing-read'
7069 ;; 2. Bind variable `icicle-fancy-candidates-p' to non-`nil'.
7071 ;; 3. Bind variable `icicle-whole-candidate-as-text-prop-p' to
7074 ;; You use method 1 or 2 to handle multi-completion candidates or
7075 ;; candidates that have text properties or are otherwise to be
7076 ;; displayed specially. I recommend that you generally use text
7077 ;; property `icicle-fancy-candidates', not variable
7078 ;; `icicle-fancy-candidates-p'. The variable is provided so that you
7079 ;; can widen the scope of this feature beyond a given call to
7080 ;; `completing-read'. You will need to do that only rarely.
7082 ;; A use case for variable `icicle-fancy-candidates-p' would be, for
7083 ;; instance, if your code calls other code that calls
7084 ;; `completing-read', so you have no direct access to the
7085 ;; `completing-read' PROMPT argument in order to propertize it. If
7086 ;; you nevertheless want to use some fancy candidates, then you can
7087 ;; bind `icicle-fancy-candidates-p' with the scope you want.
7089 ;; You use method 3, `icicle-whole-candidate-as-text-prop-p', when
7090 ;; you need to save and later retrieve all of the information
7091 ;; contained in an alist COLLECTION entry. Completion returns only a
7092 ;; string. If the COLLECTION alist has only one entry with a given
7093 ;; string as its car, then you can simply use `assoc' to retrieve the
7096 ;; But if you use an alist that allows entries with different cdrs
7097 ;; for the same car, then you need some way to encode an entire alist
7098 ;; entry in a display string. When you have this need, set variable
7099 ;; `icicle-candidates-alist' to the alist, and bind
7100 ;; `icicle-whole-candidate-as-text-prop-p' to non-`nil'.
7102 ;; This has the effect of encoding, as a text property on the
7103 ;; candidate display string, the entire corresponding original alist
7104 ;; entry. You can then use `icicle-get-alist-candidate' to recover
7105 ;; that information.
7107 ;;(@* "Programming Multi-Completions")
7109 ;; Programming Multi-Completions
7110 ;; -----------------------------
7112 ;; This section is for Emacs-Lisp programmers.
7114 ;; Multi-completions are completion candidates that are composed of
7115 ;; parts separated by `icicle-list-join-string'. See
7116 ;; (@> "Multi-Completions") for information about how users interact
7117 ;; with multi-completions.
7119 ;; Multi-completions are examples of fancy candidates.
7120 ;; See (@> "Programming with Fancy Candidates").
7122 ;; You can define your own Icicles commands that use
7123 ;; multi-completions. You can bind `icicle-list-join-string' to any
7124 ;; string you like, depending on your needs. See
7125 ;; (@file :file-name "icicles-doc1.el" :to "Key Completion") for an
7126 ;; example where it is bound to " = ". This section describes two
7127 ;; additional variables that you can bind to affect the appearance
7128 ;; and behavior of multi-completions.
7130 ;;(@* "Variable icicle-list-use-nth-parts")
7131 ;; ** Variable icicle-list-use-nth-parts **
7133 ;; Variable `icicle-list-use-nth-parts' affects the minibuffer
7134 ;; behavior of multi-completions. If you bind this to a list of
7135 ;; whole numbers, then multi-completion candidates are transformed
7136 ;; using those numbers as indexes. During completion and cycling,
7137 ;; whenever a sole candidate matches the user input, if that
7138 ;; candidate is a multi-completion, then it is transformed by
7139 ;; extracting and possibly reordering its parts according to
7140 ;; `icicle-list-use-nth-parts'.
7142 ;; The actual candidate to match is still the original candidate; the
7143 ;; transformation takes place after matching, for final insertion in
7144 ;; the minibuffer. This means that you must use this feature only
7145 ;; with lax (permissive) completion, since strict completion requires
7146 ;; an exact match against the original completion candidate, and the
7147 ;; transformed candidate will normally not match the original.
7149 ;; Variable `icicle-list-use-nth-parts' works as follows. The
7150 ;; matching candidate is split at each `icicle-list-join-string' into
7151 ;; its component parts. The indexes in `icicle-list-use-nth-parts'
7152 ;; are then used to extract parts, in the same order as the indexes
7153 ;; appear. The extracted parts are joined back together in an order
7154 ;; that you specify, separated by the value of user option
7155 ;; `icicle-list-nth-parts-join-string'. An index greater than the
7156 ;; number of parts means to use the last part.
7158 ;; For example: If the value of `icicle-list-use-nth-parts' is (1),
7159 ;; then only the first part of the multi-completion is used as the
7160 ;; completion candidate. If the value is (2 1), then the resulting
7161 ;; candidate is the second part followed by the first part, the two
7162 ;; parts being joined by `icicle-list-nth-parts-join-string'. If the
7163 ;; value is (1 99) and the multi-completion has fewer than 99 parts,
7164 ;; then the first and last parts are used. If the value is (2 1 2),
7165 ;; then the resulting candidate is composed of the second part
7166 ;; followed by the first part followed by the second part again.
7168 ;; Thus, you can use a given part any number of times. You can also
7169 ;; mix multi-completions and single-string completions, and you can
7170 ;; mix multi-completions composed of different numbers of strings.
7171 ;; For example, a set of completions might be:
7173 ;; ((("cmd1" "description of cmd1"))
7174 ;; (("cmd2" "description of cmd" "more"))
7177 ;; If you use multi-completions with `icicle-list-use-nth-parts' in
7178 ;; your own commands, please make sure that their doc strings let
7179 ;; users know what to expect, and remind them of the behavior of
7180 ;; option `icicle-list-nth-parts-join-string'. Let them know, in
7181 ;; particular, that:
7183 ;; * They can match any part of a candidate as it is displayed in
7184 ;; buffer `*Completions*'.
7186 ;; * The candidate choice they make will in fact have the form that
7187 ;; you define in your command.
7189 ;; * They can control how the parts are joined, using option
7190 ;; `icicle-list-nth-parts-join-string'.
7192 ;;(@* "Variable icicle-candidate-properties-alist")
7193 ;; ** Variable icicle-candidate-properties-alist **
7195 ;; Whereas variable `icicle-list-nth-parts-join-string' affects the
7196 ;; appearance of multi-completions in the minibuffer, variable
7197 ;; `icicle-candidate-properties-alist' affects their appearance in
7198 ;; buffer `*Completions*'. You use it to apply text properties to
7199 ;; individual parts of a multi-completion, where the parts are
7200 ;; defined in the same way as for `icicle-list-use-nth-parts'.
7202 ;; This feature affects all candidates the same way. See also
7203 ;; (@> "Candidates with Text Properties") for ways to apply text
7204 ;; properties to individual candidates (which need not be
7205 ;; multi-completions).
7207 ;; The value of `icicle-candidate-properties-alist' is an alist whose
7208 ;; entries have either of these forms:
7210 ;; (NTH PROPERTIES) or (NTH PROPERTIES JOIN-TOO)
7212 ;; NTH is the number of the target multi-completion part.
7214 ;; PROPERTIES is a list of text properties to apply to the NTH part.
7216 ;; JOIN-TOO is optional. If it is present and non-`nil', then the
7217 ;; text properties are also applied to the join string that follows
7220 ;; You can use any text properties, including `invisible', `keymap',
7221 ;; `display', and properties that you define yourself and that have
7222 ;; meaning to only your code.
7224 ;; As an example of its use, commands `icicle-fundoc',
7225 ;; `icicle-vardoc', `icicle-doc', and `icicle-plist' bind
7226 ;; `icicle-candidate-properties-alist' to
7227 ;; ((1 (face 'icicle-candidate-part))), so that the first part of
7228 ;; each multi-completion candidate is highlighted using face
7229 ;; `icicle-candidate-part'.
7231 ;; Here is another example value of
7232 ;; `icicle-candidate-properties-alist':
7234 ;; ((3 (face 'underline))
7235 ;; (2 (invisible t) t))
7237 ;; The first entry underlines the third multi-completion part. The
7238 ;; second entry makes both the second part and the join string that
7239 ;; follows it invisible.
7241 ;; One use of making a completion part invisible is so that you can
7242 ;; sort candidates using it, and let users match input against it,
7243 ;; but not have it appear explicitly.
7245 ;; Recall that `completing-read' displays only the car of each
7246 ;; element present in its COLLECTION (alist) argument. For example,
7247 ;; if you pass `completing-read' an alist such as (("foo" . 2) ("bar"
7248 ;; . 3)), then only `foo' and `bar' are displayed as candidates.
7249 ;; However, the PREDICATE argument to `completing-read' applies to
7250 ;; the entire alist element, and your command that calls
7251 ;; `completing-read' might well use the chosen candidate (e.g. `foo')
7252 ;; to look up the entire element (e.g. ("foo" . 2)) for further
7253 ;; processing. Several Icicles commands, including `icicle-search',
7256 ;; However, sometimes you might want the user to be able to match
7257 ;; against the additional information (e.g. 2 and 3), and you might
7258 ;; want to use it to sort candidates. In that case, you can use the
7259 ;; alist (("foo 2") ("bar 3")). In cases where the additional
7260 ;; information can be distracting, you can use multi-completion with
7261 ;; `icicle-candidate-properties-alist' to hide it: Pass the alist
7262 ;; ((("foo "2")) (("bar" 3"))) and use ((2 (invisible t))) for
7263 ;; `icicle-candidate-properties-alist'.
7265 ;; Keep in mind that hiding completion parts can be confusing to
7266 ;; users. Do so with care, and let your users know what to expect.
7267 ;; Inform them that there are invisible parts that are nevertheless
7268 ;; taken into account for input matching and candidate sorting. When
7269 ;; you hide parts, you will often want to omit them from the
7270 ;; minibuffer as well, using `icicle-list-use-nth-parts', to avoid
7273 ;; Consider also the position of a hidden part: In some cases you
7274 ;; might want to place it first among the multi-completion parts, but
7275 ;; in many cases you will want to place it last, to minimize
7276 ;; interference with prefix-completion matching.
7278 ;; Similar considerations apply to other text properties, such as
7279 ;; `display' and `keymap', that change the appearance or behavior of
7280 ;; a completion candidate.
7282 ;;(@* "What You See Is Not What You Get")
7283 ;; ** What You See Is Not What You Get **
7285 ;; While on the subject of confusing users, let me point out a
7286 ;; general drawback that is common to both
7287 ;; `icicle-list-use-nth-parts' and
7288 ;; `icicle-candidate-properties-alist': *not* WYSIWYG. Keep this in
7289 ;; mind if you decide to take advantage of these variables. Users
7290 ;; see one thing, choose it, and they get something different as a
7291 ;; result. That promotes confusion that you will need to weigh
7292 ;; against the possible benefits.
7294 ;; Users are confused, because what they choose is not exactly what
7295 ;; they get. What's more, a user's completion choice is not
7296 ;; reflected in the input history, leading to further confusion. For
7297 ;; example, Icicles highlighting of previously used inputs in buffer
7298 ;; `*Completions*' does not apply to such a candidate, even though it
7299 ;; was previously entered using `RET'. It is the transformed
7300 ;; candidate that was entered, not the candidate as it was proposed
7301 ;; for choosing, so when that candidate is proposed again, it is not
7302 ;; recognized as having been previously chosen.
7304 ;; The bottom line here is this: variables
7305 ;; `icicle-list-use-nth-parts' and
7306 ;; `icicle-candidate-properties-alist' are useful in certain
7307 ;; contexts, but be aware of the downside: confusing your users.
7311 ;; * (@> "Multi-Completions")
7312 ;; * (@> "Programming with Fancy Candidates")
7313 ;; * (@> "Candidates with Text Properties")
7315 ;;(@* "Candidates with Text Properties")
7317 ;; Candidates with Text Properties
7318 ;; -------------------------------
7320 ;; This section is for Emacs-Lisp programmers.
7322 ;; Section (@> "Programming Multi-Completions") explains how to apply
7323 ;; text properties to specific parts of all multi-completion
7324 ;; candidates in buffer `*Completions*' at the same time. This
7325 ;; section tells you how to apply text properties to specific
7326 ;; candidates in `*Completions*'. The candidates need not be
7327 ;; multi-completions, but in some cases they can be.
7329 ;; When you use candidates with text properties such as `face' that
7330 ;; are visible, the display candidates in `*Completions*' show those
7331 ;; properties. In addition, the candidate string that the user
7332 ;; finally chooses can also be propertized.
7334 ;; There are four different methods for providing candidates with
7335 ;; text properties, in addition to the way presented in section
7336 ;; (@> "Programming Multi-Completions"):
7338 ;; 1. Apply face `icicle-special-candidate' to all candidates that
7339 ;; match a given regexp.
7341 ;; 2. Use a set of text properties as the `icicle-special-candidate'
7342 ;; property of the symbol that represents the candidate. The text
7343 ;; properties are transferred to the string candidate that is
7344 ;; displayed (and returned).
7346 ;; 3. Use a propertized string as the `icicle-display-string'
7347 ;; property of the symbol that represents the candidate. That
7348 ;; string replaces the candidate that would otherwise have been
7349 ;; displayed, completed against, and returned.
7351 ;; 4. Start with a propertized string in the COLLECTION argument
7352 ;; that you pass to `completing-read'.
7354 ;; All four methods use fancy candidates, in the sense that they go
7355 ;; beyond what vanilla Emacs offers. For methods 1-3, you must turn
7356 ;; on fancy-candidate handling. See
7357 ;; (@> "Programming with Fancy Candidates").
7359 ;; But method 4 does not require any costly fancy-candidate encoding
7360 ;; or decoding, because the Icicles implementation of
7361 ;; `completing-read' handles propertized string candidates, and they
7362 ;; are transparent to the Emacs primitive completion operations.
7364 ;; The following sections explain methods 1-4 individually.
7366 ;;(@* "Using Regexp `icicle-special-candidate-regexp'")
7367 ;; ** Using Regexp `icicle-special-candidate-regexp' **
7369 ;; If you just want several candidates to have face
7370 ;; `icicle-special-candidate' in `*Completions', you can simply
7371 ;; define (e.g. bind) option `icicle-special-candidate-regexp' to a
7372 ;; regexp that matches those candidates. The original candidates can
7373 ;; be strings or symbols. Unlike the other methods described here,
7374 ;; this one affects only the display in `*Completions'; the
7375 ;; completion return string does not have face
7376 ;; `icicle-special-candidate'.
7378 ;; The highlighting applies only to the part of a candidate that
7379 ;; matches the regexp. This selectivity is particularly useful when
7380 ;; dealing with multi-completions. Function `icicle-read-file-name'
7381 ;; provides an example: file names that match ".+/$", that is,
7382 ;; directory names, are highlighted as special candidates. Function
7383 ;; `icicle-read-color' provides another example (using the similar,
7384 ;; but internal, variable `icicle-proxy-candidate-regexp'): proxy
7385 ;; color-name candidates such as `*point foreground*' and
7386 ;; `'icicle-region-background'' are highlighted, but not their color
7389 ;;(@* "Using Property icicle-special-candidate")
7390 ;; ** Using Property icicle-special-candidate **
7392 ;; In this approach, you use the desired list of text properties as
7393 ;; the value of property `icicle-special-candidate' for the symbol
7394 ;; that represents the candidate. This method affects the candidates
7395 ;; that are used during completion, as well as the completion return
7398 ;; If the candidate is a string, not a symbol, then `intern' it and
7399 ;; put the property on the resulting symbol. If you want the effect
7400 ;; to be temporary, then set property `icicle-special-candidate' for
7401 ;; the candidate to `nil' when completion is finished.
7403 ;; As a shortcut, if you use the value `t' instead of a property list
7404 ;; for property `icicle-special-candidate', then face
7405 ;; `icicle-special-candidate' will be used as the `face' property of
7406 ;; the candidate. Using a value of `t' is thus equivalent to using a
7407 ;; value of (face icicle-special-candidate). This approach is used,
7408 ;; for instance, in the definition of command `icicle-complete-keys'
7411 ;;(@* "Using Property `icicle-display-string'")
7412 ;; ** Using Property `icicle-display-string' **
7414 ;; This method is similar to that of using property
7415 ;; `icicle-special-candidate'. The use case for both is
7416 ;; propertizing, in a general way, candidates that are symbols. Both
7417 ;; can be useful when you have an obarray as the COLLECTION argument
7418 ;; for `completing-read'.
7420 ;; In this method the symbol name is not used at all; the candidate
7421 ;; is entirely replaced by another string, which is typically
7424 ;; You use a propertized string as the value of property
7425 ;; `icicle-display-string' for the candidate symbol. The propertized
7426 ;; string is displayed in `*Completions*' and returned as the final
7427 ;; completion choice.
7429 ;; Note that multi-completion is not available when you use an
7430 ;; obarray. Using property `icicle-special-candidate' or
7431 ;; `icicle-display-string' you can propertize candidates and parts of
7432 ;; candidates, but you cannot manipulate multi-completion parts and
7433 ;; there are no join or end strings.
7435 ;;(@* "Applying Text Properties to a Candidate String")
7436 ;; ** Applying Text Properties to a Candidate String **
7438 ;; This is the most flexible approach, and it is explained in a bit
7439 ;; more detail. It can be used with multi-completions, and it
7440 ;; affects the `*Completions*' display and the completion return
7441 ;; value. However, it is limited to using an alist or list of
7442 ;; strings, not an obarray, as the COLLECTION argument to
7443 ;; `completing-read'.
7445 ;; In this approach, you simply apply the text properties to the
7446 ;; string(s) that represent the candidate, which you then pass to
7447 ;; `completing-read' in its COLLECTION parameter.
7449 ;; As with the other methods, you can use any text properties you
7450 ;; like, including these:
7452 ;; * `face' - to make some completion candidates stand out in
7455 ;; * `icicle-mode-line-help' - candidate help shown in the mode-line
7456 ;; when the candidate is current, provided option
7457 ;; `icicle-help-in-mode-line-delay' is greater than zero (only the
7458 ;; first character of a candidate string is tested for this text
7461 ;; * `help-echo' - candidate help shown in a mouseover tooltip,
7462 ;; provided `tooltip-mode' is on
7464 ;; * `keymap' and `pointer' - for individualized mouse treatment of
7467 ;; * `display' - to include images in candidates
7469 ;; * `invisible' - to hide part or all of particular candidates
7470 ;; (which are nevertheless available for completion)
7472 ;; As a convenience, you can use function
7473 ;; `icicle-candidate-short-help' to apply both
7474 ;; `icicle-mode-line-help' and `help-echo' text properties to a
7475 ;; candidate string.
7477 ;; How does this work? Icicles redefines the standard Emacs function
7478 ;; `display-completion-list' so that it retains text properties.
7479 ;; Emacs should do the same, but it does not (yet).
7481 ;; Icicles command `icicle-read-color' presents an illustration,
7482 ;; using the `face' property. (It also uses properties
7483 ;; `icicle-mode-line-help' and `help-echo', to provide RGB and HSV
7484 ;; information in the mode-line and via tooltip.)
7486 ;; In `icicle-read-color', a multi-completion candidate is used,
7487 ;; composed of an unpropertized string that names a color and a
7488 ;; propertized string that names its RGB (red, green, blue) value.
7489 ;; The RGB string, by default, has a background of the same color -
7490 ;; each completion candidate is thus accompanied by its own color
7493 ;; The code that does this is function `icicle-make-color-candidate',
7494 ;; which is used by `icicle-read-color' and other Icicles commands
7495 ;; that read colors. Here is a simplified definition:
7497 ;; (defun icicle-make-color-candidate (color-name)
7498 ;; "Return candidate of COLOR-NAME and its hex RGB string.
7499 ;; If `icicle-WYSIWYG-Completions-flag' is non-nil, then the hex RGB
7500 ;; string has the color as its background text property."
7501 ;; (let ((rgb-string (hexrgb-color-name-to-hex color-name)))
7502 ;; (when icicle-WYSIWYG-Completions-flag
7503 ;; (put-text-property
7504 ;; 0 (length rgb-string) 'face
7505 ;; (cons 'background-color rgb-string) rgb-string))
7506 ;; (list (list color-name rgb-string))))
7508 ;; You'll notice that the face property is added only when option
7509 ;; `icicle-WYSIWYG-Completions-flag' is non-`nil'. You can toggle
7510 ;; this option at any time during completion to change the behavior.
7511 ;; (The new value takes effect for the next act of completion.)
7513 ;; You can match any part of the multi-completion: color name or RGB
7514 ;; value. Command `icicle-read-color' defines a set of sort orders
7515 ;; that are pertinent to the color candidates.
7517 ;; You can use `C-,' to sort by color name, amount of red, blue,
7518 ;; green, all RGB components (in order), RGB distance from a base
7519 ;; color, hue, saturation, value, all HSV components (in order), or
7520 ;; HSV distance from a base color.
7522 ;; If option `icicle-add-proxy-candidates-flag' is non-`nil', then
7523 ;; command `icicle-read-color' includes proxy completion candidates
7524 ;; that are not color-name-and-RGB pairs. As always, you can toggle
7525 ;; the use of proxy candidates using `C-M-_' in the minibuffer.
7527 ;; The proxy candidates for colors include the single-quoted names of
7528 ;; user options (variables) whose custom type is `color'. So, for
7529 ;; example, option `icicle-region-background' appears as proxy color
7530 ;; candidate `'icicle-region-background''. Color proxies also include
7533 ;; * `*copied foreground*' - last copied foreground, if available
7534 ;; * `*copied background*' - last copied background, if available
7535 ;; * `*mouse-2 foreground*' - foreground where you click `mouse-2'
7536 ;; * `*mouse-2 background*' - background where you click `mouse-2'
7537 ;; * `*point foreground*' - foreground under the text cursor
7538 ;; * `*point background*' - background under the text cursor
7540 ;; When you choose a proxy color candidates, the color referred to is
7541 ;; used. For example, `*point foreground*' means to use the
7542 ;; foreground color at the cursor position (point), whatever it might
7543 ;; be. Choosing a `mouse-2' candidate lets you then click `mouse-2'
7544 ;; to pick up a color somewhere. If you use library `palette.el' or
7545 ;; `eyedropper.el', and you have already copied a color, then you can
7546 ;; choose `*copied foreground*' (or background) to use that color.
7548 ;; Icicles treats reading face names similarly to reading colors, by
7549 ;; redefining standard function `read-face-name' when you are in
7550 ;; Icicle mode. In this case, multi-completions are not used. The
7551 ;; pertinent function is `icicle-make-face-candidate', which provides
7552 ;; a WYSIWYG face sample whenever `icicle-WYSIWYG-Completions-flag'
7555 ;; A string value for `icicle-WYSIWYG-Completions-flag' presents the
7556 ;; face name accompanied by that string as a separate sample swatch.
7557 ;; A value of `t' presents the face name itself in the face it names.
7559 ;; (defun icicle-make-face-candidate (face)
7560 ;; "Return a completion candidate for FACE.
7561 ;; The value of option `icicle-WYSIWYG-Completions-flag' determines
7562 ;; the kind of candidate to use.
7563 ;; If nil, then the face name is used (a string).
7565 ;; If a string, then a multi-completion candidate is used, with the
7566 ;; face name followed by a sample swatch using FACE on the string's
7569 ;; If `t', then the candidate is the face name itself, propertized
7571 ;; (if (stringp icicle-WYSIWYG-Completions-flag)
7572 ;; (let ((swatch (copy-sequence
7573 ;; icicle-WYSIWYG-Completions-flag)))
7574 ;; (put-text-property
7575 ;; 0 (length icicle-WYSIWYG-Completions-flag)
7576 ;; 'face face swatch)
7577 ;; (list (list (symbol-name face) swatch)))
7578 ;; (let ((face-name (copy-sequence (symbol-name face))))
7579 ;; (when icicle-WYSIWYG-Completions-flag
7580 ;; (put-text-property 0 (length face-name)
7581 ;; 'face face face-name))
7582 ;; (list face-name))))
7586 ;; * (@> "Programming with Fancy Candidates")
7587 ;; * (@> "Programming Multi-Completions")
7588 ;; * (@file :file-name "icicles-doc1.el" :to "Sorting Candidates and Removing Duplicates")
7589 ;; for information about changing sort orders.
7591 ;; * (@file :file-name "icicles-doc1.el" :to "*Completions* Display") for
7592 ;; more about proxy candidates.
7594 ;;(@* "Defining Icicles Commands (Including Multi-Commands)")
7596 ;; Defining Icicles Commands (Including Multi-Commands)
7597 ;; ----------------------------------------------------
7599 ;; This section is for Emacs-Lisp programmers.
7601 ;;(@* "Nothing To It!")
7602 ;; ** Nothing To It! **
7604 ;; Defining a command that uses Icicles completion and cycling is
7605 ;; simple: just call `completing-read' or `read-file-name' to read
7606 ;; input, then act on that input.
7608 ;; Nothing could be simpler - just use `completing-read'or
7609 ;; `read-file-name'! Icicles does the rest. This is the most
7610 ;; important thing to learn about defining Icicles commands: you do
7611 ;; not need to do anything except call `completing-read' or
7612 ;; `read-file-name' as you would normally anyway.
7614 ;; Or at least as I HOPE you would normally. I fear that many
7615 ;; Emacs-Lisp programmers do not take sufficient advantage of
7616 ;; `completing-read' when they could, using instead a function such
7617 ;; as (quel horreur !) `read-string' to read user input.
7619 ;;(@* "Multi-Commands Are Easy To Define Too")
7620 ;; ** Multi-Commands Are Easy To Define Too **
7622 ;; If defining an Icicles command is trivial, so is defining an
7623 ;; Icicles multi-command. For the same effort it takes to define a
7624 ;; command that acts on a single input choice, you can have a command
7625 ;; that acts on any number of input choices. A multi-command takes
7626 ;; advantage of one or more action functions when cycling candidates,
7627 ;; as described in sections
7628 ;; (@file :file-name "icicles-doc1.el" :to "Multi-Commands"),
7629 ;; (@> "More about Multi-Commands"), and
7630 ;; (@file :file-name "icicles-doc1.el" :to "Choose All Completion Candidates").
7632 ;; In fact, there is no reason NOT to define your commands as
7633 ;; multi-commands - you lose nothing, and you gain a lot. Whenever
7634 ;; it is appropriate for a user to possibly want to act on multiple
7635 ;; objects, define a multi-command that does that.
7637 ;; An anecdote, to make the point. An Icicles user sent me an email
7638 ;; saying how much he appreciated Icicles multi-commands, and asking
7639 ;; if I would add a multi-command version of `insert-buffer'. I did
7640 ;; so, but I replied to him that the definition is trivial: it is
7641 ;; identical to the definition of `icicle-buffer', except that the
7642 ;; action function is `insert-buffer' instead of `switch-to-buffer'.
7644 ;; The point is to not be afraid of defining multi-commands yourself.
7645 ;; You do not really need to have me add a multi-command to Icicles
7646 ;; in most cases; you can easily define it yourself. Here is a
7647 ;; simple definition of `icicle-insert-buffer'. You will understand
7648 ;; it in detail after reading the next section.
7650 ;; (icicle-define-command icicle-insert-buffer
7651 ;; "Multi-command version of `insert-buffer'." ; Doc string
7652 ;; insert-buffer ; Action function
7653 ;; "Buffer: " ; `completing-read' args
7654 ;; (mapcar #'(lambda (buf) (list (buffer-name buf))) (buffer-list))
7655 ;; nil t nil 'buffer-name-history (icicle-default-buffer-names) nil)
7657 ;; Macros `icicle-define-command' and `icicle-define-file-command'
7658 ;; make it easy to define a multi-command. Without them, it is
7659 ;; sometimes not so easy, depending on the complexity of your action
7660 ;; functions. See (@> "Defining Multi-Commands the Hard Way") for a
7661 ;; taste of what is involved. If you read that section first, make
7662 ;; sure you come back here to see how easy things can be.
7664 ;; Here is how you might define a multi-command to delete one or more
7665 ;; files or directories:
7667 ;; 1. Define the multi-command, `my-delete-file':
7669 ;; (icicle-define-file-command
7670 ;; my-delete-file ; Command name
7671 ;; "Delete a file or directory." ; Doc string
7672 ;; my-delete-file-or-directory ; Function to perform the action
7673 ;; "Delete file or directory: " ; `read-file-name' arguments...
7674 ;; default-directory nil t)
7676 ;; 2. Define the action function that deletes a single file:
7678 ;; (defun my-delete-file-or-directory (file)
7679 ;; "Delete file (or directory) FILE."
7680 ;; (condition-case i-delete-file
7681 ;; (if (eq t (car (file-attributes file)))
7682 ;; (delete-directory file)
7683 ;; (delete-file file))
7684 ;; (error (message "%s" (error-message-string i-delete-file))
7685 ;; (error "%s" (error-message-string i-delete-file)))))
7687 ;; There are two parts to the definition of `my-delete-file':
7689 ;; 1. The definition of the command itself, using
7690 ;; `icicle-define-file-command'.
7692 ;; 2. The definition of an action function,
7693 ;; `my-delete-file-or-directory', which deletes a single file (or
7694 ;; directory), given its name.
7696 ;; It is #1 that is of interest here, because that is essentially
7697 ;; what you do to define any multi-command.
7699 ;; The details of #2 are less interesting, even if more complex in
7700 ;; this case: `my-delete-file-or-directory' checks whether its
7701 ;; argument is a file or directory, and then tries to delete it. If
7702 ;; an error occurs, it prints the error message and then returns the
7703 ;; message, so that the calling command can report on all deletion
7706 ;; In #1, the arguments to `icicle-define-file-command' are
7709 ;; * The name of the command being defined `my-delete-file'.
7711 ;; * Its doc string.
7713 ;; * The function that actually performs the action on the input file
7714 ;; name - `my-delete-file-or-directory'.
7716 ;; * The arguments that you would supply anyway to `read-file-name'
7717 ;; to read a single file name.
7719 ;; These are the SAME things you would need if you were defining a
7720 ;; simple command to delete a SINGLE file or directory. The only
7721 ;; differences here are that you:
7723 ;; * Use `icicle-define-file-command' instead of `defun' with an
7724 ;; `interactive' spec.
7726 ;; * Separate the action code into a separate function (here,
7727 ;; `my-delete-file-or-directory') that acts on a single object
7730 ;; When you use `icicle-define-file-command', the action function is
7731 ;; called on the result of `read-file-name', and it is also bound to
7732 ;; `icicle-candidate-action-fn', so that it will be applied to the
7733 ;; current candidate via `C-RET' or `C-mouse-2'.
7735 ;; Command `icicle-all-candidates-action' (`C-!' -- see
7736 ;; (@file :file-name "icicles-doc1.el" :to "Choose All Completion Candidates"))
7737 ;; can report in buffer `*Help*' on the objects that it did not act
7738 ;; upon successfully. For this reporting to work, the function bound
7739 ;; to `icicle-candidate-action-fn'
7740 ;; (e.g. `my-delete-file-or-directory', above) should return `nil'
7741 ;; for "success" and non-`nil' (for example, an error message) for
7742 ;; "failure", whatever "success" and "failure" might mean in the
7743 ;; particular context of use. This is not a requirement, except if
7744 ;; you want to take advantage of such reporting. For a command that
7745 ;; deletes files, it is important to let the user know which
7746 ;; deletions failed when s?he tries to delete all matching candidates
7749 ;; If the command you want to define acts on objects other than
7750 ;; files, then use `icicle-define-command' instead of
7751 ;; `icicle-define-file-command' - the only difference is that you
7752 ;; then supply the arguments for `completing-read' instead of those
7753 ;; for `read-file-name'.
7755 ;; To let users know that a command is a multi-command, and how to
7756 ;; use it as such, `icicle-define-command' and
7757 ;; `icicle-define-file-command' automatically add this explanation to
7758 ;; the doc string you provide for the multi-command:
7761 ;; Read input, then call `<your action function name>' to act on it.
7763 ;; Input-candidate completion and cycling are available. While
7764 ;; cycling, these keys with prefix `C-' are active:
7766 ;; `C-mouse-2', `C-RET' - Act on current completion candidate only
7767 ;; `C-down', `C-wheel-down' - Move to next completion candidate and act
7768 ;; `C-up', `C-wheel-up' - Move to previous completion candidate and act
7769 ;; `C-next' - Move to next apropos-completion candidate and act
7770 ;; `C-prior' - Move to previous apropos-completion candidate and act
7771 ;; `C-end' - Move to next prefix-completion candidate and act
7772 ;; `C-home' - Move to previous prefix-completion candidate and act
7773 ;; `C-!' - Act on *all* candidates, successively (careful!)
7775 ;; When candidate action and cycling are combined (e.g. `C-next'), user
7776 ;; option `icicle-act-before-cycle-flag' determines which occurs first.
7778 ;; With prefix `C-M-' instead of `C-', the same keys (`C-M-mouse-2',
7779 ;; `C-M-RET', `C-M-down', and so on) provide help about candidates.
7781 ;; Use `mouse-2', `RET' or `S-RET' to finally choose a candidate, or
7784 ;; This is an Icicles command - see `icicle-mode'.
7787 ;; Notice that the doc string of your new multi-command references
7788 ;; your action function (e.g. `my-delete-file-or-directory'). The
7789 ;; doc string you provide for the multi-command can thus be a little
7790 ;; more abstract, leaving any detailed explanation of the action to
7791 ;; the doc string of your action function.
7793 ;; To provide more flexibility, `icicle-define-command' and
7794 ;; `icicle-define-file-command' provide some predefined key bindings
7795 ;; and allow for additional arguments.
7797 ;; Here is a definition of a multi-command, `change-font', that reads
7798 ;; a font name and changes the selected frame to use that font.
7800 ;; 1 (icicle-define-command
7801 ;; 2 change-font "Change font of current frame."
7803 ;; 4 (modify-frame-parameters orig-frame
7804 ;; 5 (list (cons 'font font))))
7805 ;; 6 "Font: " (mapcar #'list (x-list-fonts "*"))
7806 ;; 7 nil t nil nil nil nil
7807 ;; 8 ((orig-frame (selected-frame))
7808 ;; 9 (orig-font (frame-parameter nil 'font)))
7810 ;; 11 (modify-frame-parameters orig-frame
7811 ;; 12 (list (cons 'font orig-font)))
7814 ;; The arguments to `icicle-define-command' here are as follows:
7816 ;; Command name (line 2)
7817 ;; Doc string (line 2)
7818 ;; Action function (lines 3-5)
7819 ;; Args passed to `completing-read' (lines 6-7)
7820 ;; Additional bindings (lines 8-9)
7821 ;; Additional initialization code (line 10)
7822 ;; "Undo" code to run in case of error or user quit (lines 11-12)
7823 ;; Additional code to run at the end (line 13)
7825 ;; The following bindings are predefined - you can refer to them in
7826 ;; the command body:
7828 ;; `icicle-orig-buff' is bound to (current-buffer)
7829 ;; `icicle-orig-window' is bound to (selected-window)
7831 ;; Before running any "undo" code that you supply, the original
7832 ;; buffer is restored, in case of error or user quit (`C-g').
7834 ;; Most of the arguments to `icicle-define-command' are optional. In
7835 ;; this case, optional arguments were provided to save (lines 8-9)
7836 ;; and then restore (lines 11-12) the original font and frame.
7838 ;; Several top-level Icicles commands have been defined using
7839 ;; `icicle-define-command' and `icicle-define-file-command'. You can
7840 ;; use their definitions as models for your own multi-commands.
7842 ;; `clear-option' (alias) - Set value of binary option to `nil'
7843 ;; `icicle-add-buffer-candidate' - Add buffer to those always shown
7844 ;; `icicle-add-buffer-config' - Add to `icicle-buffer-configs'
7845 ;; `icicle-bookmark' - Jump to a bookmark
7846 ;; `icicle-bookmark-all-tags' - Jump: bookmark with all matching tags
7847 ;; `icicle-bookmark-all-tags-regexp' - ... matching a regexp
7848 ;; `icicle-bookmark-bookmark-list-' - Jump: bookmark-list bookmark
7849 ;; `icicle-bookmark-desktop' - Jump: bookmarked desktop
7850 ;; `icicle-bookmark-dired' - Jump: bookmarked Dired state
7851 ;; `icicle-bookmark-file' - Jump: bookmarked file
7852 ;; `icicle-bookmark-gnus' - Jump: bookmarked Gnus message
7853 ;; `icicle-bookmark-info' - Jump: bookmarked Info node
7854 ;; `icicle-bookmark-list' - Choose a list of bookmark names
7855 ;; `icicle-bookmark-local-file' - Jump: bookmarked local file
7856 ;; `icicle-bookmark-man' - Jump: bookmarked `man' page
7857 ;; `icicle-bookmark-non-file' - Jump: bookmarked non-file buffer
7858 ;; `icicle-bookmark-region' - Jump: bookmarked region
7859 ;; `icicle-bookmark-remote-file' - Jump: bookmarked remote file
7860 ;; `icicle-bookmark-some-tags'- Jump: bookmark with some matching tag
7861 ;; `icicle-bookmark-some-tags-regexp'- matching a regexp
7862 ;; `icicle-bookmark-specific-buffers'- Jump: specific-buffer bookmark
7863 ;; `icicle-bookmark-specific-files' - Jump: specific-file bookmark
7864 ;; `icicle-bookmark-this-buffer' - Jump: bookmark for this buffer
7865 ;; `icicle-bookmark-url' - Jump: bookmarked URL
7866 ;; `icicle-bookmark-w3m' - Jump: W3M bookmark
7867 ;; `icicle-buffer' - Switch to another buffer
7868 ;; `icicle-buffer-config' - Choose a config for buffer commands
7869 ;; `icicle-buffer-list' - Choose a list of buffer names
7870 ;; `icicle-choose-faces' - Choose a list of face names
7871 ;; `icicle-choose-invisible-faces' - Choose list of invisible faces
7872 ;; `icicle-choose-visible-faces' - Choose list of visible faces
7873 ;; `icicle-clear-history' - Clear entries from minibuffer histories
7874 ;; `icicle-clear-current-history' - Clear current history entries
7875 ;; `icicle-color-theme' - Change color theme
7876 ;; `icicle-comint-command' - Reuse a previous command in comint mode
7877 ;; `icicle-command-abbrev' - Execute command or command abbreviation
7878 ;; `icicle-command-abbrev-command' - Execute command from abbrev
7879 ;; `icicle-completing-yank' - Yank text using completion
7880 ;; `icicle-delete-file' - Delete a file or directory
7881 ;; `icicle-delete-windows' - Delete windows showing a buffer anywhere
7882 ;; `icicle-describe-option-of-type' - Describe option of a given type
7883 ;; `icicle-directory-list' - Choose a list of directory names
7884 ;; `icicle-dired' - Visit a directory in Dired mode
7885 ;; `icicle-doc' - Display doc of function, variable, or face
7886 ;; `icicle-execute-extended-command' -
7887 ;; A multi-command version of `M-x'
7888 ;; `icicle-execute-named-keyboard-macro' - Execute named kbd macro
7889 ;; `icicle-face-list' - Choose a list of face names
7890 ;; `icicle-file-list' - Choose a list of file names
7891 ;; `icicle-file' - Visit a file or directory
7892 ;; `icicle-find-file' - Visit a file or directory (relative)
7893 ;; `icicle-find-file-absolute' - Visit a file (absolute)
7894 ;; `icicle-find-file-all-tags' - Visit a file with all matching tags
7895 ;; `icicle-find-file-all-tags-regexp' - ... matching a regexp
7896 ;; `icicle-find-file-in-tags-table' - Visit a file in a tags table
7897 ;; `icicle-find-file-read-only' - Visit a file in read-only mode
7898 ;; `icicle-find-file-some-tags'- Visit a file with some matching tags
7899 ;; `icicle-find-file-some-tags-regexp' - ... matching a regexp
7900 ;; `icicle-find-file-tagged' - Visit a file with matching tags
7901 ;; `icicle-find-first-tag' - Visit source-code definition with tag
7902 ;; `icicle-font' - Change the frame font
7903 ;; `icicle-frame-bg' - Change the frame background color
7904 ;; `icicle-frame-fg' - Change the frame foreground color
7905 ;; `icicle-fundoc' - Display the doc of a function
7906 ;; `icicle-Info-menu' - Go to an Info menu node
7907 ;; `icicle-increment-option' - Increment option value using arrows
7908 ;; `icicle-increment-variable' - Increment variable value
7909 ;; `icicle-insert-buffer'- Insert a buffer
7910 ;; `icicle-insert-thesaurus-entry' - Insert an entry from a thesaurus
7911 ;; `icicle-keyword-list' - Choose a list of keywords (regexps)
7912 ;; `icicle-kill-buffer' - Kill a buffer
7913 ;; `icicle-kmacro' - Execute a keyboard macro (Emacs 22+)
7914 ;; `icicle-locate-file' - Open a file located anywhere
7915 ;; `icicle-pick-color-by-name' - Set current highlighting color
7916 ;; `icicle-plist' - Choose a symbol and its property list
7917 ;; `icicle-recent-file' - Open a recently used file
7918 ;; `icicle-remove-buffer-candidate' -
7919 ;; Remove buffer from those always shown
7920 ;; `icicle-remove-buffer-config' -
7921 ;; Remove from `icicle-buffer-configs'
7922 ;; `icicle-remove-file-from-recentf-list' - Remove from recent files
7923 ;; `icicle-remove-saved-completion-set' - Remove a set from
7924 ;; `icicle-saved-completion-sets'
7925 ;; `icicle-reset-option-to-nil' -
7926 ;; Set value of binary option to `nil'
7927 ;; `icicle-search-all-tags-bookmark'- Search bookmark with given tags
7928 ;; `icicle-search-all-tags-regexp-bookmark'- ... tags matching regexp
7929 ;; `icicle-search-autofile-bookmark' - Search an autofile bookmark
7930 ;; `icicle-search-bookmark' - Search a bookmark
7931 ;; `icicle-search-bookmark-list-bookmark' - Search bookmark-list bmk
7932 ;; `icicle-search-desktop-bookmark' - Search a Desktop bookmark
7933 ;; `icicle-search-dired-bookmark' - Search a Dired bookmark
7934 ;; `icicle-search-file-bookmark' - Search a bookmarked file
7935 ;; `icicle-search-gnus-bookmark' - Search a bookmarked Gnus message
7936 ;; `icicle-search-info-bookmark' - Search a bookmarked Info node
7937 ;; `icicle-search-local-file-bookmark' - Search a local-file bookmark
7938 ;; `icicle-search-man-bookmark' - Search a bookmarked `man' page
7939 ;; `icicle-search-non-file-bookmark' - Search a bookmarked buffer
7940 ;; `icicle-search-region-bookmark' - Search a bookmarked region
7941 ;; `icicle-search-remote-file-bookmark' - Search a remote bookmark
7942 ;; `icicle-search-some-tags-bookmark'- Search bookmark with some tags
7943 ;; `icicle-search-some-tags-regexp-bookmark'- ... matching regexp
7944 ;; `icicle-search-specific-buffers-bookmark'- ...specific-buffers bmk
7945 ;; `icicle-search-specific-files-bookmark' - ... specific-files bmk
7946 ;; `icicle-search-this-buffer-bookmark' - ...bookmark for this buffer
7947 ;; `icicle-search-url-bookmark' - Search a bookmarked URL
7948 ;; `icicle-search-w3m-bookmark' - Search a W3M bookmark
7949 ;; `icicle-select-frame' - Select frame by name and raise it
7950 ;; `icicle-select-window' - Select window by its buffer name
7951 ;; `icicle-set-option-to-t' - Set the value of a binary option to `t'
7952 ;; `icicle-synonyms' - Show synonyms that match a regexp
7953 ;; `icicle-tag-a-file' - Add one or more tags to a file
7954 ;; `icicle-toggle-option' - Toggle the value of a binary option
7955 ;; `icicle-untag-a-file' - Remove one or more tags from a file
7956 ;; `icicle-vardoc' - Display the doc of a variable
7957 ;; `icicle-where-is' - Show key sequences that invoke a command
7959 ;; For simplicity, the descriptions of most of these commands are
7960 ;; singular actions (e.g. "kill a buffer"), but each of them can be
7961 ;; used to act on any number of items any number of times (e.g. kill
7962 ;; one or more buffers). I recommend that you follow a similar
7963 ;; naming convention - remember that the doc string will let users
7964 ;; know that the command can be used on multiple objects.
7966 ;; Macros `icicle-define-command' and `icicle-define-file-command'
7967 ;; define a multi-command in a simple way. Sometimes you will need a
7968 ;; little more flexibility. In that case, you can use higher-order
7969 ;; functions `icicle-explore' and `icicle-apply' to define a
7970 ;; multi-command. See (@> "Defining Icicles Tripping Commands").
7972 ;;(@* "Are Users Dependent on Icicles To Use Multi-Commands?")
7973 ;; ** Are Users Dependent on Icicles To Use Multi-Commands? **
7975 ;; For users to be able to take advantage of the Icicles features
7976 ;; that your multi-command provides, they must load Icicles. You can
7977 ;; do this for them, by adding (require 'icicles nil t) to your code.
7978 ;; The last two arguments mean that no error will be raised if for
7979 ;; some reason Icicles cannot be found or successfully loaded.
7981 ;; But that brings up another question: What happens to your
7982 ;; multi-command if Icicles is not available for a user, or s?he does
7983 ;; not want to load it? No problem - your multi-command then
7984 ;; automatically turns into a normal, single-choice command -
7985 ;; graceful degradation.
7987 ;; Similarly, users can always turn off `icicle-mode' at any time, to
7988 ;; return to the standard Emacs behavior.
7990 ;; Users will, in any case, need to load Icicles at compile time, in
7991 ;; order to byte-compile your library that calls macro
7992 ;; `icicle-define-command' or `icicle-define-file-command' - either
7993 ;; that, or you can duplicate the definition of the macro in your
7994 ;; library. To let users load Icicles at (only) compile time, add
7995 ;; this to your library that defines multi-commands:
7997 ;; (eval-when-compile '(require icicles))
8001 ;; * (@> "Defining Icicles Tripping Commands") for how to use
8002 ;; `icicle-apply' and `icicle-explore' to define browsing commands.
8004 ;; * (@> "Defining Multiple-Choice Menus").
8006 ;; * (@> "Note to Programmers") for further programming guidelines.
8008 ;; * Library `synonyms.el', which uses `icicle-define-command' to
8009 ;; define command `synonyms'. This command lets you use Icicles
8010 ;; completion on input regexps when you search a thesaurus.
8012 ;;(@* "Defining Icicles Tripping Commands")
8014 ;; Defining Icicles Tripping Commands
8015 ;; ----------------------------------
8017 ;; Section (@file :file-name "icicles-doc1.el" :to "Icicles Tripping")
8018 ;; describes the use of Icicles tripping (aka navigation or browsing)
8019 ;; multi-commands. This section tells you how to define your own
8020 ;; such commands for custom trips - it is thus for Emacs-Lisp
8023 ;; The best way to learn how to do this is to look at how the
8024 ;; existing tripping commands are defined. Some of them use macro
8025 ;; `icicle-define-command'; others do not. Some use the
8026 ;; building-block functions `icicle-explore' or `icicle-apply';
8027 ;; others do not. Several use `icicle-search' as a building block.
8029 ;;(@* "Using `icicle-define-command'")
8030 ;; ** Using `icicle-define-command' **
8032 ;; Those that use `icicle-define-command' take advantage of some
8033 ;; extraneous way to obtain trip location information from a display
8034 ;; candidate, which is just a string. For example, `icicle-bookmark'
8035 ;; ultimately uses the display string to look up location information
8036 ;; in a bookmarks file. Those that use `icicle-explore' or
8037 ;; `icicle-apply' make use of location information stored in the
8038 ;; alist COLLECTION argument to `completing-read'.
8040 ;; You can also use `icicle-define-command', `icicle-explore', and
8041 ;; `icicle-apply' to define multi-commands other than browsing
8042 ;; commands - the action function can do anything you like.
8044 ;;(@* "Using `icicle-explore'")
8045 ;; ** Using `icicle-explore' **
8047 ;; `icicle-explore' is a higher-order function that takes as
8048 ;; arguments the following functions, in addition to accepting
8049 ;; the optional `completing-read' arguments.
8051 ;; * A function to build a candidates alist (COLLECTION) for
8052 ;; completion. It fills `icicle-candidates-alist' with the
8053 ;; candidates, each of which is a cons with a display candidate
8054 ;; string as car and (typically) location information as cdr. For
8055 ;; example, `icicle-find-tag' uses the tag text as display
8056 ;; candidate and the standard tag-locating information as the cdr:
8057 ;; tag info, file path, and goto function.
8059 ;; * A function that acts on the candidate finally chosen (`RET'),
8060 ;; when completion is finished.
8062 ;; * A function to call if the user hits `C-g' during completion.
8064 ;; * A function to call if an error is raised during completion.
8066 ;; * A function to call after completion is finished, to clean things
8069 ;; If you also bind `icicle-candidate-action-fn' to a function that
8070 ;; takes a display candidate (string) as argument and navigates to
8071 ;; the corresponding location, then `icicle-explore' does everything
8072 ;; you need for an Icicles trip. You can use function
8073 ;; `icicle-get-alist-candidate' to get the location information for a
8074 ;; given display candidate.
8076 ;;(@* "Using `icicle-apply'")
8077 ;; ** Using `icicle-apply' **
8079 ;; `icicle-apply' binds `icicle-candidate-action-fn' appropriately
8080 ;; and calls `icicle-explore'. It applies its function argument to
8081 ;; completion candidates the user acts on (using `C-RET' etc.). It
8082 ;; applies the function to the full alist entry, that is, the display
8083 ;; candidate car plus any additional information in the cdr. For a
8084 ;; tripping command, the additional information provides a location
8085 ;; and the function applied takes you there.
8087 ;; This use of an alist that stores location information in the cdrs
8088 ;; is what makes `icicle-apply' and `icicle-explore' particularly
8089 ;; suitable for defining navigation multi-commands. The Icicles
8090 ;; macros `icicle-define-command' and `icicle-define-file-command'
8091 ;; make no such provision, but with suitable arguments you can use
8092 ;; them too to define tripping commands.
8094 ;;(@* "Using `icicle-search'")
8095 ;; ** Using `icicle-search' **
8097 ;; `icicle-search' is another high-level function for defining
8098 ;; tripping commands. Like `icicle-apply', it calls
8099 ;; `icicle-explore', but it also provides features for searching
8100 ;; bookmarks, buffers, and files. It takes as arguments the search
8101 ;; limits (region), if any, and either a regexp or a function that
8102 ;; determines the unfiltered search hits. It does everything else
8103 ;; needed to define a trip command that uses search hits as
8104 ;; completion candidates. Several predefined Icicles tripping
8105 ;; commands were defined using `icicle-search'.
8107 ;;(@* "Tripping on Foot")
8108 ;; ** Tripping on Foot **
8110 ;; You should be able to define any tripping commands you need using
8111 ;; `icicle-explore', `icicle-apply', or `icicle-search'.
8113 ;; If, however, for some reason you decide to define one at a lower,
8114 ;; pedestrian level (that is, without using any of those building
8115 ;; blocks), then bind `icicle-whole-candidate-as-text-prop-p' to `t'
8116 ;; around the call to `completing-read'. You can then use
8117 ;; `icicle-get-alist-candidate' to retrieve the candidate cdr
8118 ;; (e.g. location) information from the completion result.
8120 ;; However, if the action or alternate action function that you need
8121 ;; modifies the existing set of completion candidates on the fly, as
8122 ;; a side effect, then bind `icicle-whole-candidate-as-text-prop-p'
8123 ;; to `nil' in the action function. Then modify both
8124 ;; `minibuffer-completion-table' and `icicle-candidates-alist' as
8125 ;; needed to perform the side effect.
8127 ;; Icicles search-and-replace provides an example of this. When you
8128 ;; replace text, the original domain of search-hit candidates (with
8129 ;; their associated location information) is altered, so that you can
8130 ;; continue replacing coherently. (See the code for
8131 ;; `icicle-search-action' and
8132 ;; `icicle-search-highlight-and-maybe-replace'.)
8134 ;; Because such side effects can change the meaning of cycling state
8135 ;; information such as the current candidate number, Icicles does not
8136 ;; automatically save such state information before a candidate
8137 ;; action and then restore it afterward.
8139 ;; For example, search-and-replace removes a search-hit candidate, as
8140 ;; a side effect, if the replacement text no longer matches your
8141 ;; input. In that case, a current candidate number recorded before
8142 ;; the action would no longer correspond to the same candidate.
8144 ;; For this reason, if your action function does not perform any such
8145 ;; side effects on the candidates, and you want to restore the
8146 ;; cycling state as it was before a candidate action, then you might
8147 ;; want your action function to save and then restore the values of
8148 ;; Icicles variables such as `icicle-candidate-nb',
8149 ;; `icicle-last-completion-candidate', and
8150 ;; `icicle-completion-candidates'.
8154 ;; * (@file :file-name "icicles-doc1.el" :to "Icicles Tripping")
8155 ;; for information about using Icicles Trip commands
8157 ;; * (@> "Defining Icicles Commands (Including Multi-Commands)")
8158 ;; for general information about defining multi-commands
8160 ;; * (@> "Programming with Fancy Candidates") for information about
8161 ;; `icicle-whole-candidate-as-text-prop-p'
8163 ;;(@* "Defining Multiple-Choice Menus")
8165 ;; Defining Multiple-Choice Menus
8166 ;; ------------------------------
8168 ;; Icicles multi-commands (see
8169 ;; (@file :file-name "icicles-doc1.el" :to "Multi-Commands")) can be
8170 ;; used provide users with multiple-choice menus. While the possible
8171 ;; choices can be accessed by minibuffer completion or cycling, a
8172 ;; user can also display them in buffer `*Completions*' using `TAB'
8173 ;; or `S-TAB', and click them there to choose them.
8175 ;; That is, buffer `*Completions*' can act as a multiple-choice menu.
8177 ;; Simple use case: Suppose that you use special characters (Greek
8178 ;; letters, math symbols, accented letters in another language...),
8179 ;; but only occasionally - you do not want to take the trouble to
8180 ;; learn a special input method for them or flip to a different soft
8181 ;; keyboard. One simple way to handle this is to create a menu of
8182 ;; such special characters - Greek letters, for instance. You only
8183 ;; need to create the menu once, providing the necessary completions
8184 ;; as, say, Unicode characters. When you need to input such a
8185 ;; character, just use your command that pops up buffer
8186 ;; `*Completions*' with the available special characters. Even if
8187 ;; you do not know how to type them on your keyboard, you can cycle
8188 ;; through them or use `mouse-2' to choose them.
8190 ;; Here's a simple example of defining a command that uses a
8191 ;; multiple-choice menu. (Other examples given above, such as
8192 ;; `my-delete-file-or-directory' are also examples, but this one uses
8193 ;; menu items that look more like menu items.)
8195 ;; (icicle-define-command my-menu-command
8196 ;; "Display menu and act on choice(s)."
8198 ;; "`TAB' for menu. `C-mouse-2' to choose. "
8199 ;; my-menu-items nil t)
8201 ;; (defvar my-menu-items
8202 ;; '(("Foobar" . foobar-fn) ("Toto" . toto-fn) ("Titi" . titi-fn))
8203 ;; "Alist of menu items and their associated commands.")
8205 ;; (defun my-menu-action (item)
8206 ;; "Call function associated with menu-item ITEM."
8207 ;; (funcall (cdr (assoc item my-menu-items))))
8209 ;; (defun foobar-fn () (message "Foobar chosen"))
8210 ;; (defun toto-fn () (message "Toto chosen"))
8211 ;; (defun titi-fn () (message "Titi chosen"))
8213 ;; A user does `M-x my-menu-command' and hits `TAB' to display this
8214 ;; menu in the `*Completions*' buffer:
8216 ;; Click mouse-2 on a completion to select it. (C-h: help)
8218 ;; Possible completions are:
8222 ;; The user presses and holds the Control key. S?he clicks `Foobar'
8223 ;; - message "Foobar chosen" appears. S?he clicks `Toto - message
8224 ;; "Toto chosen" appears.
8226 ;; And so on - all while holding Control pressed. Any number of menu
8227 ;; items can be chosen, any number of times. The command is finally
8228 ;; exited with `RET' or `C-g'.
8230 ;; The COLLECTION argument passed to `completing-read' here is
8231 ;; `my-menu-items', an alist of key-value pairs, where the key is a
8232 ;; menu-item name and the value is the function that implements the
8233 ;; menu item. For example, menu item `Foobar' is implemented by
8234 ;; function `foobar-fn', and the alist element is therefore ("Foobar"
8237 ;; Function `my-menu-action' is executed when a user clicks
8238 ;; `C-mouse-2' on a menu item. It just looks up the menu item's
8239 ;; function in alist `my-menu-items', and then calls that function.
8241 ;; What? You think it's odd that the user must hit `TAB' to display
8242 ;; the menu? Then just use this code instead:
8244 ;; (icicle-define-command
8246 ;; "Display menu and act on choice(s)."
8248 ;; "`C-mouse-2' or `C-RET' to choose menu items"
8249 ;; my-menu-items nil t nil nil nil nil
8250 ;; ((icicle-show-Completions-initially-flag t)))
8252 ;; This just adds a binding for
8253 ;; `icicle-show-Completions-initially-flag', so that `*Completions*'
8254 ;; is displayed initially.
8256 ;; Granted, the `*Completions*' display does not exactly look like
8257 ;; your average menu. And the header line does not mention the
8258 ;; multiple-choice possibility (holding Control while clicking). But
8259 ;; the header does say to use `C-h' for help, and that help does
8260 ;; mention `C-mouse-2' (as does the prompt). And the menu does act
8261 ;; like a menu. And the doc string of `my-menu-command' can provide
8262 ;; more help, as needed.
8264 ;; There are also some freebie advantages of using such menus,
8265 ;; besides the feature of multiple-choice. These include choosing
8266 ;; menu items from the keyboard, with completion, and cycling among
8267 ;; menu items. The additional features are all explained when the
8270 ;; One common use of a multiple-choice menu is letting the user
8271 ;; select a list of items from a larger list of candidates. The list
8272 ;; is returned, with the items in the order selected. Examples of
8273 ;; this include these multi-commands:
8275 ;; * `icicle-bookmark-list' - bookmark names
8277 ;; * `icicle-buffer-list' - buffer names, selected from `buffer-list'
8278 ;; (possibly after filtering)
8280 ;; * `icicle-directory-list' - directory names, selected from
8281 ;; subdirectories in the current directory and any directories you
8284 ;; * `icicle-face-list' - face names, selected from `face-list'
8286 ;; * `icicle-file-list' - file names, selected from files in the
8287 ;; current directory and any directories you navigate to
8289 ;; * `icicle-keyword-list' - keywords (regexps), selected from those
8290 ;; you have previously entered
8292 ;; * `icicle-choose-faces', `icicle-choose-visible-faces',
8293 ;; `icicle-choose-invisible-faces' - face names, selected from the
8294 ;; (visible/invisible) highlighting faces in the buffer
8296 ;; Such commands can be used on their own, or they can be used in the
8297 ;; `interactive' specs of other commands that act on an entire list
8298 ;; of selected items. And do not forget that the set of "menu items"
8299 ;; (completion candidates) is susceptible to sorting in various ways,
8300 ;; as well as filtering in the usual ways: progressive completion,
8301 ;; chipping away the non-elephant, and so on.
8303 ;; Here as an example definition is `icicle-file-list':
8305 ;; (icicle-define-command icicle-file-list
8306 ;; "Choose a list of file names.
8307 ;; The list of names (strings) is returned."
8308 ;; (lambda (name) (push name file-names))
8309 ;; "Choose file (`RET' when done): "
8310 ;; (mapcar #'list (directory-files default-directory nil
8311 ;; icicle-re-no-dot))
8312 ;; nil nil nil 'file-name-history nil nil
8313 ;; ((file-names ())) ; Additional bindings
8315 ;; (prog1 (setq file-names (delete "" file-names)) ; Return list
8316 ;; (when (interactive-p) (message "Files: %S" file-names))))
8318 ;; See (@file :file-name "icicles-doc1.el" :to "Nutshell View of Icicles")
8319 ;; for information about progressive completion and chipping away.
8321 ;;(@* "Defining Icicles Multi `M-x'")
8323 ;; Defining Icicles Multi `M-x'
8324 ;; ----------------------------
8326 ;; This section is for Emacs-Lisp programmers. It explains how the
8327 ;; Icicles Multi `M-x' feature is implemented, providing an advanced
8328 ;; illustration of using macro `icicle-define-command'.
8330 ;;(@* "How Multi `M-x' is Defined")
8331 ;; ** How Multi `M-x' is Defined **
8333 ;; The definition of `icicle-execute-extended-command' provides an
8334 ;; interesting illustration of using `icicle-define-command'. The
8335 ;; candidate action function itself binds a candidate action
8336 ;; function, in case the candidate is a command that reads input with
8339 ;; (icicle-define-command
8340 ;; icicle-execute-extended-command ; `M-x' in Icicle mode.
8341 ;; "Read command name, then read its arguments and call it."
8342 ;; icicle-execute-extended-command-1 ; Action function
8343 ;; (format "Execute command%s: " ; `completing-read' args
8344 ;; (if current-prefix-arg
8345 ;; (format " (prefix %d)"
8346 ;; (prefix-numeric-value current-prefix-arg))
8348 ;; obarray 'commandp t nil 'extended-command-history nil nil
8349 ;; ((last-cmd last-command)) ; Save the last command
8350 ;; nil nil ; First code, undo code
8351 ;; (setq last-command last-cmd)) ; Last: restore last command
8353 ;; (defun icicle-execute-extended-command-1 (cmd-name)
8354 ;; "Action function for `icicle-execute-extended-command'."
8355 ;; (set-buffer icicle-orig-buff) ; bound by `icicle-define-command'.
8356 ;; (select-window icicle-orig-window)
8357 ;; (let ((icicle-candidate-action-fn
8358 ;; (lambda (x) (funcall (intern cmd-name) x))))
8359 ;; (run-hooks 'post-command-hook)
8360 ;; (setq this-command cmd)
8361 ;; (run-hooks 'pre-command-hook)
8362 ;; (let ((enable-recursive-minibuffers t))
8363 ;; (call-interactively (intern cmd-name) 'record-it))))
8365 ;; The last seven lines of this action function rebind
8366 ;; `icicle-candidate-action-fn' to a function that calls the
8367 ;; candidate `cmd-name' on a single argument that it reads. This is
8368 ;; useful if `cmd-name' is a command that, itself, reads an input
8369 ;; argument with completion. When that is the case, you can use
8370 ;; completion on that input, and if you do that, you can use `C-RET'
8371 ;; to use command `cmd-name' as a multi-command. In other words,
8372 ;; this binding allows for two levels of multi-commands.
8374 ;; There are a few things wrong with this definition, however. In
8375 ;; the action function, the candidate command is applied to a
8376 ;; candidate that is a string. What if it is a command, such as
8377 ;; `describe-variable', that expects a symbol argument? Or a number
8378 ;; argument? There is no way to know what kind of command will be
8379 ;; used, and what kind of argument it will need. The solution is to
8380 ;; first try a string candidate argument, then convert the string to
8381 ;; a symbol or number. That is, bind this to
8382 ;; `icicle-candidate-action-fn':
8385 ;; (condition-case nil
8386 ;; (funcall cmd x) ; Try to use a string candidate. If that
8387 ;; (wrong-type-argument ; did not work, use a symbol or number.
8388 ;; (funcall cmd (car (read-from-string x))))))
8390 ;; A similar problem occurs if the action function called does not
8391 ;; accept a (single) argument. The best thing to do in this case is
8392 ;; punt - call `icicle-help-on-candidate' to display help on the
8393 ;; candidate. To the code above, we add another error handler:
8395 ;; (wrong-number-of-arguments (funcall #'icicle-help-on-candidate))
8397 ;; And what if the command `cmd' does something that changes the
8398 ;; focus away from the minibuffer's frame? That's the case for
8399 ;; `describe-variable', for instance: it selects buffer `*Help*'. To
8400 ;; fix this potential problem, the action function needs to reset the
8401 ;; focus back to the minibuffer frame:
8404 ;; (condition-case nil
8406 ;; (wrong-type-argument (funcall cmd (car (read-from-string x))))
8407 ;; (wrong-number-of-arguments
8408 ;; (funcall #'icicle-help-on-candidate)))
8409 ;; (select-frame-set-input-focus
8410 ;; (window-frame (minibuffer-window))))
8412 ;; The actual definitions of the action function and the main command
8413 ;; are even more complex. They need to take into account various
8414 ;; subtleties, including those associated with recursive minibuffers
8415 ;; and multiple invocations of `completing-read'. Evaluate, for
8416 ;; example, (symbol-function 'icicle-execute-extended-command) to see
8417 ;; the real definition.
8421 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Multi `M-x'").
8423 ;;(@* "Defining Multi-Commands the Hard Way")
8425 ;; Defining Multi-Commands the Hard Way
8426 ;; ------------------------------------
8428 ;; This section is for Emacs-Lisp programmers. It gives you a taste
8429 ;; of what is involved behind the scene when you effortlessly use
8430 ;; `icicle-define-command' or `icicle-define-file-command' to define
8432 ;; See (@> "Defining Icicles Commands (Including Multi-Commands)").
8434 ;; It can be good to know this, if only for the case where you need
8435 ;; to define a multi-command that has special behavior not provided
8436 ;; by `icicle-define(-file)-command' out of the box. For example, if
8437 ;; you want the normal, single-choice `RET' behavior to be different
8438 ;; from the multiple-choice `C-RET' behavior, then you might want to
8439 ;; roll your own. Likewise, if you want to define your own help on
8440 ;; individual candidates, to be invoked when users use `C-M-RET' and
8443 ;; To write your own multi-command, you must make the command do
8446 ;; 1. Call `completing-read' or `read-file-name', and perform some
8447 ;; action on the completed input.
8449 ;; 2. Bind one or more of these variables to action functions, which
8450 ;; each take a completion candidate as argument:
8452 ;; a. `icicle-candidate-action-fn' - a function that performs an
8453 ;; action on a completion candidate - often the same action as
8456 ;; b. `icicle-candidates-list-action-fn' - a function that
8457 ;; performs an action on the list of all completion candidates.
8459 ;; c. `icicle-candidate-alt-action-fn' - a function that performs
8460 ;; an alternative action on a completion candidate.
8462 ;; d. `icicle-candidates-list-alt-action-fn' - a function that
8463 ;; performs an alternative action on the list of candidates.
8465 ;; e. `icicle-candidate-help-fn' - a function that displays
8466 ;; specialized help for a completion candidate.
8468 ;; (You can also provide mode-line help and tooltip help for
8469 ;; individual candidates.
8470 ;; See "Candidates with Text Properties".)
8472 ;; f. `icicle-delete-candidate-object' - a function that deletes
8473 ;; an object associated with (e.g. named by) a completion
8476 ;; #1 just lets people use the command normally, to perform the #1
8477 ;; action on a completion candidate entered with `RET'. Because of
8478 ;; #2, people can perform the #2 action(s) on any completion
8479 ;; candidates, while still continuing to cycle or complete
8480 ;; candidates. `icicle-candidate-action-fn' is often the same as the
8481 ;; action for #1, but nothing prevents you from using different
8484 ;; When internal variable `icicle-candidate-action-fn' is not bound,
8485 ;; the default action is performed: display help on the current
8486 ;; completion candidate. When `icicle-candidate-help-fn' is not
8487 ;; bound, the default help display is used.
8489 ;; Instead of binding `icicle-delete-candidate-object' to a deletion
8490 ;; action function, you can bind it to a symbol (variable) whose
8491 ;; value is a list of completion-candidate objects.
8492 ;; See (@> "More about Multi-Commands") for more information.
8494 ;; Here is a definition of a simple (not multi-) command that reads a
8495 ;; font name and then changes the selected frame to use that font.
8496 ;; By virtue of calling `completing-read', Icicles completion and
8497 ;; cycling are available, using all available font names as the pool
8500 ;; (defun change-font ()
8501 ;; "Change font of selected frame."
8502 ;; (modify-frame-parameters
8504 ;; (list (cons 'font (completing-read
8505 ;; "Font: " (mapcar #'list (x-list-fonts "*"))
8508 ;; Here's a definition of a multi-command `change-font' that takes
8509 ;; advantage of an action function when cycling candidates:
8511 ;; 1 (defun change-font ()
8512 ;; 2 "Change font of current frame."
8514 ;; 4 (let* ((orig-frame (selected-frame))
8515 ;; 5 (orig-font (frame-parameter nil 'font))
8516 ;; 6 (icicle-candidate-action-fn
8517 ;; 7 ;; Perform the action on a candidate, without leaving
8518 ;; 8 ;; `completing-read'. You can do this over and over.
8520 ;; 10 (modify-frame-parameters orig-frame
8521 ;; 11 (list (cons 'font font))))))
8522 ;; 12 (condition-case nil
8523 ;; 13 (modify-frame-parameters
8527 ;; 17 ;; Perform the action on your final choice.
8528 ;; 18 (completing-read
8530 ;; 20 (mapcar #'list (x-list-fonts "*")) nil t))))
8532 ;; 22 (modify-frame-parameters
8534 ;; 24 (list (cons 'font orig-font)))))))
8536 ;; As you can see, there is a lot more going on here than in the
8537 ;; simple-command version. These are the points to keep in mind,
8538 ;; when defining a multi-command by hand:
8540 ;; 1. Save anything you need to restore, so you can, in effect, undo
8541 ;; the action in case of `C-g' (lines 4-5).
8543 ;; 2. Bind `icicle-candidate-action-fn' to the action to perform
8546 ;; 3. Perform the action, using `completing-read' to provide the
8547 ;; target candidate (lines 13-20). Do this in the body of a
8548 ;; `condition-case' (lines 12-24).
8550 ;; 4. Restore the original context in the error-handling part of the
8551 ;; `condition-case' (lines 22-24). Include `quit' in the
8554 ;; The above definition is not quite complete, in fact. To let
8555 ;; `icicle-all-candidates' be able to report on failures, the
8556 ;; `icicle-candidate-action-fn' code should also trap errors and
8557 ;; return `nil' as a success indicator.
8559 ;; In fact, things can get even hairier (much hairier) still, if the
8560 ;; function at the core of your command does things like create a new
8561 ;; frame - especially on MS Windows, with its click-to-focus window
8562 ;; manager. The action of `change-font' does not do that, but if it
8563 ;; did, you would need to redirect the focus back to the minibuffer
8564 ;; frame, using `select-frame-set-input-focus'. As an illustration
8565 ;; of what's involved, here's a definition that would deal with such
8566 ;; problems. It also traps `icicle-candidate-action-fn' errors,
8567 ;; returning `nil' to report success and the error message to report
8570 ;; (defun change-font ()
8571 ;; "Change font of current frame."
8573 ;; (let* ((icicle-orig-buff (current-buffer))
8574 ;; (icicle-orig-window (selected-window))
8575 ;; (orig-frame (selected-frame))
8576 ;; (orig-font (frame-parameter nil 'font))
8577 ;; (icicle-candidate-action-fn
8578 ;; (lambda (candidate)
8579 ;; (condition-case action-fn-return
8581 ;; (modify-frame-parameters
8582 ;; orig-frame (list (cons 'font candidate)))
8583 ;; (select-frame-set-input-focus
8584 ;; (window-frame (minibuffer-window)))
8585 ;; nil) ; Return nil to report success.
8586 ;; ;; Return error message to report error.
8587 ;; (error (error-message-string action-fn-return))))))
8588 ;; (condition-case act-on-choice
8589 ;; (modify-frame-parameters
8591 ;; (list (cons 'font
8593 ;; "Font: " (mapcar #'list (x-list-fonts "*"))
8594 ;; nil t nil nil nil nil))))
8595 ;; (quit (switch-to-buffer icicle-orig-buff)
8596 ;; (modify-frame-parameters
8598 ;; (list (cons 'font orig-font))))
8599 ;; (error (switch-to-buffer icicle-orig-buff)
8600 ;; (modify-frame-parameters
8601 ;; orig-frame (list (cons 'font orig-font)))
8602 ;; (error "%s" (error-message-string act-on-choice))))))
8604 ;; That's a lot of (error-prone) work! You obviously do not want to
8605 ;; be doing that a lot. Whenever you can, you should use macro
8606 ;; `icicle-define-command' or `icicle-define-file-command' to define
8607 ;; your multi-commands.
8611 ;; * (@> "Defining Icicles Commands (Including Multi-Commands)") for
8612 ;; the easy way to define `change-font'.
8614 ;; * (@file :file-name "icicles-doc1.el" :to "Icicles Tripping")
8615 ;; for information about defining action functions that perform
8616 ;; side effects on candidates.
8618 ;;(@* "Global Filters")
8623 ;; This section is for Emacs-Lisp programmers.
8625 ;; Which completion candidates get displayed? To review:
8627 ;; 1. The domain of discourse, that is, all possible candidates, is
8628 ;; determined by the arguments to `completing-read',
8629 ;; `read-file-name', or `M-x'.
8631 ;; 2. A user types something in the minibuffer. This narrows the
8632 ;; possible candidates to those that match the input. Matching
8633 ;; can be prefix-matching or apropos-matching.
8635 ;; Wouldn't it sometimes be useful to filter #1 in a global way,
8636 ;; before filtering it with the user input (#2)? Functions
8637 ;; `completing-read' and `read-file-name' take a predicate argument,
8638 ;; so that can be used for global filtering. However, those
8639 ;; functions are usually called from some command, and it would also
8640 ;; be useful to give end users, not just programmers, some way to
8641 ;; globally filter candidates.
8643 ;; For example, if you have a command, such as `icicle-buffer', that
8644 ;; reads a buffer name and displays the buffer, some users might
8645 ;; always be interested only in buffers that are associated with
8646 ;; files. They do not want to see possible candidates such as
8647 ;; `*scratch*' and `*Messages*'. What they need is a way to apply a
8648 ;; global predicate that limits candidates to file-buffer names - but
8649 ;; they do not have access to the call to `completing-read' that is
8650 ;; inside the command definition.
8652 ;; For this reason, some global filtering variables are provided by
8655 ;; `icicle-must-match-regexp', `icicle-must-not-match-regexp',
8656 ;; `icicle-must-pass-predicate',
8657 ;; `icicle-must-pass-after-match-predicate',
8658 ;; `icicle-extra-candidates'.
8660 ;; The first and second of these are regexps that candidates must
8661 ;; match and must not match, respectively, in order for them to be
8662 ;; displayed. The third and fourth are predicates that candidates
8663 ;; must satisfy. The fifth is a list of extra candidates to display.
8664 ;; Any of the filters can be `nil', in which case it has no effect.
8666 ;; Each of these except `icicle-extra-candidates' filters not only
8667 ;; completion candidates but also the default values passed to
8668 ;; `completing-read' and `read-file-name'.
8670 ;; Variable `icicle-must-match-regexp' is similar to the standard
8671 ;; variable `completion-regexp-list', except:
8673 ;; * `completion-regexp-list' is a list of regexps, not just one.
8674 ;; * `icicle-must-match-regexp' is used after filtering using option
8675 ;; `icicle-transform-function'.
8677 ;; Variables `icicle-must-pass-predicate' and
8678 ;; `icicle-must-pass-after-match-predicate' act the same: they filter
8679 ;; display candidates. The former filters before the current user
8680 ;; input is matched. The latter filters after matching - it is
8681 ;; applied only to candidates that match.
8683 ;; Neither is like the PREDICATE argument to `completing-read' in
8684 ;; that they do not act on full candidates (e.g. alist entries) -
8685 ;; they apply only to display candidates (strings).
8687 ;; For apropos completion, the `completing-read' PREDICATE is applied
8688 ;; to all COLLECTION entries before matching those entries that
8689 ;; satisfy it against the user input. If the PREDICATE argument uses
8690 ;; only the candidate name (it does not make any use of the full
8691 ;; candidate) then it can sometimes be more efficient to pass `nil'
8692 ;; as the PREDICATE and use `icicle-must-pass-after-match-predicate'
8695 ;; Here's a gotcha to keep in mind if you use
8696 ;; `icicle-must-pass-predicate' or
8697 ;; `icicle-must-pass-after-match-predicate' with (non-absolute)
8698 ;; file-name candidates: Since the candidate file names have no
8699 ;; directory part, in many cases you will want to test the candidate
8700 ;; expanded relative to the directory shown in the minibuffer. One
8701 ;; way to do this is as follows:
8703 ;; (setq file (expand-file-name file
8704 ;; (icicle-file-name-directory-w-default
8705 ;; (icicle-input-from-minibuffer))))
8707 ;; This gotcha is nothing new - the same applies for standard Emacs
8708 ;; function `read-file-name', but it is still worth pointing out.
8710 ;; Variable `icicle-extra-candidates' is not really a "filter". It
8711 ;; does not restrict the set of possible candidates - rather, it
8712 ;; extends that set. The other filters do not act on the candidates
8713 ;; in `icicle-extra-candidates' - they are always added. Extra
8714 ;; candidates are displayed in buffer `*Completions*' using face
8715 ;; `icicle-extra-candidate'.
8717 ;; Note that an extra candidate need not have anything in common with
8718 ;; the normal (non-extra) candidates. In particular, because it is
8719 ;; provided explicitly, it does not follow the restrictions implied
8720 ;; by the current candidate-generation method.
8722 ;; In this, extra candidates are similar to proxy candidates. For
8723 ;; example, when option `icicle-guess-commands-in-path' is non-`nil',
8724 ;; the proxy shell-command candidates provided have no connection
8725 ;; with the file-name completion that is used to generate the other
8726 ;; candidates (see (@* "Icicles Shell-Command Enhancements")).
8728 ;; Note too that if an extra candidate is already a candidate anyway
8729 ;; then it will be present twice in the list of all candidates (that
8730 ;; is, unless `icicle-transform-function' removes duplicate
8733 ;; These global variables are internal variables, even though they
8734 ;; are defined as user options - they are not really meant to be
8735 ;; customized. If you are not an Emacs-Lisp programmer, you will not
8736 ;; use these variables, but some commands that you use might provide
8737 ;; corresponding global-filter user options. Icicles provides
8738 ;; customizable user options for Icicles buffer commands, such as
8739 ;; `icicle-buffer'. For example:
8741 ;; `icicle-buffer-match-regexp' - Regexp buffer names must match
8742 ;; `icicle-buffer-no-match-regexp' - Regexp buffers must not match
8743 ;; `icicle-buffer-predicate' - Predicate buffers must satisfy
8744 ;; `icicle-buffer-extras' - Extra buffer names to display
8746 ;; You might, for instance, customize `icicle-buffer-no-match-regexp'
8747 ;; to not display file-buffers whose names end in `.elc', and
8748 ;; customize `icicle-buffer-predicate' to show only buffers that are
8749 ;; associated with files. The former would use a value of "\\.elc$",
8750 ;; and the latter would use a value such as this:
8752 ;; (lambda (bufname) (buffer-file-name (get-buffer bufname)))
8754 ;; Similarly, Icicles provides user options for filtering and sorting
8755 ;; file names during completion:
8757 ;; `icicle-file-match-regexp' - Regexp file names must match
8758 ;; `icicle-file-no-match-regexp' - Regexp file names must not match
8759 ;; `icicle-file-predicate' - Predicate files must satisfy
8760 ;; `icicle-file-extras' - Extra file names to display
8762 ;; Note that `icicle-buffer-predicate' and `icicle-file-predicate'
8763 ;; correspond to `icicle-must-pass-after-match-predicate', not to
8764 ;; `icicle-must-pass-predicate'. They are applied after your current
8765 ;; input filters the candidates.
8767 ;; If you as a programmer write a command, and you want to expose
8768 ;; global filters to users of the command, you should:
8770 ;; 1. Create corresponding user options that can be customized.
8771 ;; 2. Bind the user options to the corresponding filtering variables.
8773 ;; If you use `icicle-define-command' or `icicle-define-file-command'
8774 ;; to define a command (recommended), then you can simply pass the
8775 ;; filter-variable bindings as part of the BINDINGS argument.
8777 ;; For convenience you can use macros `icicle-buffer-bindings' and
8778 ;; `icicle-file-bindings' to provide bindings that are appropriate
8779 ;; for buffer-name and file-name completion, respectively. For
8780 ;; example, macro `icicle-buffer-bindings' expands to include these
8781 ;; bindings, among others:
8783 ;; (icicle-must-match-regexp icicle-buffer-match-regexp)
8784 ;; (icicle-must-not-match-regexp icicle-buffer-no-match-regexp)
8785 ;; (icicle-must-pass-after-match-predicate icicle-buffer-predicate)
8786 ;; (icicle-require-match-flag icicle-buffer-require-match-flag)
8787 ;; (icicle-extra-candidates icicle-buffer-extras)
8788 ;; (icicle-ignore-space-prefix-flag
8789 ;; icicle-buffer-ignore-space-prefix-flag)
8790 ;; (icicle-delete-candidate-object 'icicle-kill-a-buffer)
8792 ;; As an example of using this macro, here is the core definition of
8795 ;; (icicle-define-command
8796 ;; icicle-buffer ; Command name
8797 ;; "Switch to a different buffer." ; Doc string
8798 ;; switch-to-buffer ; Action function
8799 ;; "Switch to buffer: " ; `completing-read' args
8800 ;; (mapcar (lambda (buf) (list (buffer-name buf))) (buffer-list))
8801 ;; nil nil nil 'buffer-name-history
8802 ;; (icicle-default-buffer-names) nil
8803 ;; ;; Filter bindings
8804 ;; (icicle-buffer-bindings)) ; Macro provides buffer bindings
8806 ;; If you define a command that uses completion, but you do not use
8807 ;; `icicle-define-command' or `icicle-define-file-command', then you
8808 ;; can just bind appropriate variables individually around a call to
8809 ;; `completing-read' or `read-file-name'.
8811 ;; Another way that users can apply predicates to completion
8812 ;; candidates is to use `M-&' while completing. These predicates
8813 ;; apply to the full alist-entry candidates that are supplied to
8814 ;; `completing-read' or `read-file-name', not just to the textual
8815 ;; candidates that are displayed in buffer `*Completions*'.
8816 ;; See (@file :file-name "icicles-doc1.el" :to "Progressive Completion").
8818 ;;(@* "Specifying Match Functions for Commands")
8820 ;; Defining Commands that Use Specific Match Functions
8821 ;; ---------------------------------------------------
8823 ;; This section is for Emacs-Lisp programmers.
8825 ;; By default, Icicles lets users use basic prefix completion (with
8826 ;; `TAB') or apropos completion (with `S-TAB'). They can
8827 ;; alternatively use other completion methods with `TAB' and `S-TAB':
8829 ;; * They can use `C-(' during completion to cycle among `TAB'
8830 ;; completion methods.
8832 ;; * They can use `M-(' to cycle among `S-TAB' completion
8835 ;; * They can customize options `icicle-TAB-completion-methods-alist'
8836 ;; and `icicle-S-TAB-completion-methods-alist', to define the
8837 ;; completion methods among which they can cycle.
8839 ;; When you define an Icicles command, you can specify which
8840 ;; string-matching functions the command uses during completion:
8842 ;; * If you want the command to use fuzzy completion for `TAB' by
8843 ;; default, then bind `icicle-fuzzy-completion-flag' to
8844 ;; non-`nil'. Users can still use `C-(' to toggle fuzzy completion
8847 ;; * If you want the command to use a particular string-matching
8848 ;; function for `S-TAB' completion by default, then bind variable
8849 ;; `icicle-apropos-complete-match-fn' to that function. Users can
8850 ;; still use `M-(' to cycle among the other matching functions for
8853 ;; You can bind `icicle-apropos-complete-match-fn' to any function
8854 ;; that matches strings. You will probably also want to ensure that
8855 ;; it is available for `M-(' cycling, by adding it to
8856 ;; `icicle-S-TAB-completion-methods-alist' in a `let' binding. For
8857 ;; example, to use matching function `my-match' in `my-cmd', you
8863 ;; (let ((icicle-apropos-complete-match-fn 'my-match)
8864 ;; (icicle-S-TAB-completion-methods-alist
8865 ;; (cons (cons "mine" 'my-match)
8866 ;; icicle-S-TAB-completion-methods-alist)))
8867 ;; (do-something (completing-read "Choose: " ...) ...)))
8869 ;;(@* "Defining Buffer-Text Completion for Comint Modes")
8871 ;; Defining Buffer-Text Completion for Comint Modes
8872 ;; ------------------------------------------------
8874 ;; This section is for Emacs-Lisp programmers.
8876 ;; Out of the box, Icicles provides completion for buffer text in
8877 ;; some contexts. This includes Shell mode, for example. Whenever
8878 ;; there are two or more candidate completions, you can use Icicles
8879 ;; completion, with all of its features (cycling, progressive
8880 ;; completion, apropos completion, and so on).
8881 ;; See (@> "Completion in Comint Modes").
8883 ;; Shell mode is an example of a mode that inherits from Comint mode.
8884 ;; Other libraries sometimes define modes that also extend Comint
8885 ;; mode in different ways. Library ESS does so, for example.
8887 ;; In such modes, the top-level completion command used is typically
8888 ;; `comint-dynamic-complete', and it is typically bound to `TAB'. In
8889 ;; Icicle mode, `TAB' in such a buffer is instead bound to the
8890 ;; Icicles version of this command, `icicle-comint-dynamic-complete'.
8892 ;; Icicles provides the infrastructure for you to take advantage of
8893 ;; Icicles completion with your own modes that inherit from Comint
8894 ;; mode. For that, just do the following:
8896 ;; 1. Define replacement functions for the functions that perform the
8897 ;; completion. The functions to be replaced themselves typically
8898 ;; call a Comint completion function, such as
8899 ;; `comint-dynamic-complete-filename'. You can typically use the
8900 ;; same definitions as the original functions, except replace the
8901 ;; call to a function that displays multiple matching candidates
8902 ;; by a call to a corresponding Icicles function that performs
8905 ;; 2. Customize option `icicle-comint-dynamic-complete-replacements',
8906 ;; adding the mappings that specify which standard functions to
8907 ;; replace with your completion functions (from #1). Take a look
8908 ;; at the default value of this option to see what I mean.
8910 ;; 3. Use `eval-after-load' to toggle Icicle mode when the vanilla
8911 ;; code for your mode is loaded, to ensure that the original
8912 ;; definitions are picked up. See the end of `icicles-mode.el'
8913 ;; for an example of this.
8915 ;; If you are interested in trying this, take a look at the Icicles
8916 ;; code for, say, `icicle-shell-dynamic-complete-command', comparing
8917 ;; it with the original code for `shell-dynamic-complete-command'.
8918 ;; You will see that the only change is to substitute a call to
8919 ;; `icicle-shell-dynamic-complete-as-command' for a call to
8920 ;; `shell-dynamic-complete-as-command'. Likewise,
8921 ;; `icicle-shell-dynamic-complete-as-command' is a trivial alteration
8922 ;; of `shell-dynamic-complete-as-command'.
8924 ;; The key is to ultimately call an Icicles completion command, such
8925 ;; as `icicle-comint-dynamic-simple-complete', whenever there are
8926 ;; multiple completion candidates. This has the effect of using
8927 ;; Icicles minibuffer completion instead of simply displaying the
8928 ;; alternatives in buffer `*Completions*'.
8930 ;; Icicles uses this same technique, of substituting Icicles
8931 ;; completion for simple display of alternatives, for all buffer-text
8932 ;; completion that it supports out of the box, even when there is no
8933 ;; relation with Comint mode.
8935 ;;(@* "Note to Programmers")
8937 ;; Note to Programmers
8938 ;; -------------------
8940 ;; Here are some simple guidelines for using Icicles in Emacs-Lisp
8943 ;; 1. *Use it*! Even if you do not do anything else, include this in
8946 ;; (require 'icicles nil t)
8948 ;; That has absolutely no consequences if Icicles is not present
8949 ;; in the user's `load-path' (there is no load error). If Icicles
8950 ;; is present, however, then users can take advantage of each use
8951 ;; you make of `completing-read' and `read-file-name' in your
8954 ;; 2. Use an input-completion read function, such as
8955 ;; `completing-read' or `read-file-name', when you read input!
8956 ;; There is almost never a reason not to use an input-completion
8957 ;; function when reading user input - especially considering that
8958 ;; you need not always provide a REQUIRE-MATCH argument.
8960 ;; Try also to find an appropriate PREDICATE argument, and a good
8961 ;; set of default values to pass to `completing-read' as its
8962 ;; COLLECTION argument. Too often, I think, we use an overly
8963 ;; general COLLECTION argument, such as the `obarray', and we do
8964 ;; not provide a (good) PREDICATE. Using an input-completion
8965 ;; function with an appropriate candidate completion list and
8966 ;; predicate can help users considerably.
8968 ;; If you want to also give users a way to customize a (different)
8969 ;; predicate that applies only to the textual candidates that are
8970 ;; displayed in buffer `*Completions*', as opposed to the full
8971 ;; alist-entry candidates that are supplied to `completing-read'
8972 ;; or `read-file-name', then you can define a new user option and
8973 ;; then bind internal variable `icicle-must-pass-predicate' to the
8974 ;; value of that option. See (@> "Global Filters").
8976 ;; 3. Avoid using a literal-string `interactive' spec (e.g.
8977 ;; (interactive "fFile: ")) that reads input with completion.
8978 ;; Instead, call `completing-read' or `read-file-name' within the
8979 ;; `interactive' spec. This saves Icicles users of progressive
8980 ;; completion the need to hit `RET' multiple times to pass their
8981 ;; input up through multiple levels of recursive minibuffers to
8982 ;; the top level. See
8983 ;; (@file :file-name "icicles-doc1.el" :to "Progressive Completion").
8985 ;; 4. In many cases, it makes sense to define a multi-command, rather
8986 ;; than a simple command. People can always use a multi-command
8987 ;; as a simple command, but not vice versa.
8988 ;; See (@file :file-name "icicles-doc1.el" :to "Multi-Commands"),
8989 ;; (@> "Defining Icicles Commands (Including Multi-Commands)"),
8990 ;; and (@> "Defining Multi-Commands the Hard Way").
8992 ;; 5. Consider using `icicle-completing-read-history' instead of
8993 ;; `read-from-minibuffer' or `read-string' for most purposes.
8994 ;; This lets users complete their input against previously entered
8995 ;; input. Completion is lax, so they can also enter new input.
8997 ;; 6. You can bind `icicle-sort-comparer' temporarily to any sort
8998 ;; function you need.
9000 ;; 7. Function `icicle-next-candidate' is a general framework for
9001 ;; letting users cycle completions of partial input strings. I
9002 ;; use it to define the cycling behavior for both prefix and
9003 ;; apropos completions. You can use it to easily define other,
9004 ;; application-specific input matching/completion/cycling
9005 ;; behavior. Just supply it with a function that takes the
9006 ;; current partial user input (a string) and returns a list of
9007 ;; candidate completions, however those might be defined.
9009 ;; 8. If the potential number of completion candidates is enormous,
9010 ;; then icompletion display in `*Completions*' can be slow. In
9011 ;; that case, consider turning it off for the duration of the
9012 ;; command, by binding `icicle-incremental-completion-flag' to
9013 ;; `nil'. An alternative to turning it off is the approach taken
9014 ;; in Icicles (e.g. `icicle-vardoc' and
9015 ;; `icicle-insert-thesaurus-entry'): Just add a reminder to the
9016 ;; doc string to tell users that they can toggle
9017 ;; `icicle-incremental-completion-flag' with `C-#'.
9019 ;; 9. Another of my libraries that can help programmers provide
9020 ;; default values is `thingatpt+.el'. It provides functions for
9021 ;; picking up symbols, sexps, numbers, words, and other sorts of
9022 ;; thing near the text cursor (`point').
9026 ;; * (@file :file-name "icicles-doc1.el" :to "Multi-Commands")
9027 ;; * (@> "Defining Icicles Commands (Including Multi-Commands)")
9028 ;; * (@> "Defining Multi-Commands the Hard Way")
9029 ;; * (@> "Defining Multiple-Choice Menus")
9030 ;; * (@> "Global Filters")
9031 ;; * (@> "Specifying Match Functions for Commands")
9032 ;; * (@> "Multi-Completions")
9034 ;;(@* "La Petite Histoire")
9036 ;; La Petite Histoire
9037 ;; ------------------
9039 ;; 1. This library started life as `elect-mbuf.el', by Hans Koomen.
9041 ;; Original posting:
9042 ;; From koomen@cs.rochester.edu Mon Jun 19 19:27:58 1989
9043 ;; To: info-gnu-emacs@prep.ai.mit.edu
9044 ;; Cc: Hans <Koomen@cs.rochester.edu>
9045 ;; Subject: elect-mbuf.el
9046 ;; Date: Tue, 13 Jun 89 15:17:07 -0400
9048 ;; 2. I hacked and enhanced the library in various relatively minor
9049 ;; ways over the years, maintaining it as `elect-mbuf.el' - see
9050 ;; details in file `icicles-chg.el'.
9052 ;; I did not change the main functionality of the library during this
9053 ;; period: it always cycled the COMPLETE list of (prefix) completion
9054 ;; candidates passed to `completing-read'; it did not update the
9055 ;; candidate list based on the current minibuffer contents.
9057 ;; So, for instance, if you had `M-x for' in the minibuffer, `down'
9058 ;; would cycle among ALL Emacs commands, not just those that start
9059 ;; with "for". I used the library this way for fifteen years without
9060 ;; thinking much about this behavior or the code behind it.
9062 ;; 3. In July 2005, Lennart Borgman gave `elect-mbuf.el' a quick try,
9063 ;; and intuitively expected to see behavior along the lines that you
9064 ;; see now for Icicles prefix completion:
9066 ;; a. `down' should cycle completions relative to the current input,
9067 ;; not all completions supplied to `completing-read'.
9068 ;; b. If buffer `*Completions*' is displayed, `down' should highlight
9069 ;; the current candidate there.
9071 ;; Good idea Lennart (<lennart.borgman.073@student.lu.se>). So I
9072 ;; implemented that behavior, and renamed the library "Icicles" (for,
9073 ;; I suppose, "input cycles" or some such - or because it's "cool").
9075 ;; 4. The code changes I made to implement #3 (completion cycling
9076 ;; relative to current input) made me realize that other completion
9077 ;; matchings could be implemented in a similar way. Prefix
9078 ;; completion (the completion provided by Emacs) is handy, but it is
9079 ;; also sometimes a bit limited. The idea of apropos completion
9080 ;; occurred to me, and I implemented that as well.
9082 ;; 5. I extended the library quite a bit more, in terms of
9083 ;; convenience (highlighting, treatment of buffer
9084 ;; `*Completions*',..., but also in terms of functionality. In
9085 ;; particular, it now treats file names too. And, because Emacs 21
9086 ;; and later versions use `read-file-name' for `find-file' and so on,
9087 ;; Icicles now treats `read-file-name' the same as `completing-read'.
9089 ;; 6. On another suggestion from LennartBorgman, I made Icicles take
9090 ;; advantage of Delete Selection mode. And I implemented it as a
9093 ;; 7, 8, 9,... One thing has led to another, and I've just kept
9094 ;; adding features. Feature creep, I guess. But the more I play
9095 ;; with Icicles, the more I imagine new ways it might be made more
9098 ;;(@* "Note on Non-`nil' `pop-up-frames' on MS Windows")
9100 ;; Note on Non-`nil' `pop-up-frames' on MS Windows
9101 ;; -----------------------------------------------
9103 ;; If you use `pop-up-frames' = `t', like I do, you might have
9104 ;; noticed that Emacs completion does not play well with using
9105 ;; separate frames for each buffer. In particular, it does not play
9106 ;; well with having a separate frame for buffer `*Completions*'.
9107 ;; When you try to complete input using `TAB', a new frame is created
9108 ;; for buffer `*Completions*', and, at least on MS Windows, it is
9109 ;; selected, taking the input focus away from the original frame's
9112 ;; This means that, once the `*Completions*' buffer has been
9113 ;; displayed in a separate frame, you cannot, for instance, cycle
9114 ;; completion candidates, without first reselecting the original
9115 ;; frame manually. You cannot even use normal completion - you
9116 ;; cannot add text in the minibuffer, or delete text there, because
9117 ;; the minibuffer in the original frame no longer has the input
9120 ;; In general, Emacs does not play too well with one-buffer-per-frame
9121 ;; (`pop-up-frames' = `t'), and this is a good example of that
9124 ;; I reported this Emacs bug. I've been hoping it will be corrected
9125 ;; since Emacs 21...
9127 ;; I do not have this problem of loss of frame input focus in my own
9128 ;; setup, even though I use `pop-up-frames' = `t', because I use my
9129 ;; library `oneonone.el'. (Try it!) If you need a solution while
9130 ;; waiting for the Emacs fix, you can try doing something similar to
9131 ;; what I do in `oneonone.el':
9133 ;; 1. Use dedicated frames for both `*Completions*' and the
9136 ;; 2. Display buffer `*Completions*' using a special-display function
9137 ;; that explicitly redirects the input focus from the
9138 ;; `*Completions*' frame back to the minibuffer frame.
9140 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
9142 ;; This program is free software; you can redistribute it and/or
9143 ;; modify it under the terms of the GNU General Public License as
9144 ;; published by the Free Software Foundation; either version 2, or (at
9145 ;; your option) any later version.
9147 ;; This program is distributed in the hope that it will be useful,
9148 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
9149 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
9150 ;; GNU General Public License for more details.
9152 ;; You should have received a copy of the GNU General Public License
9153 ;; along with this program; see the file COPYING. If not, write to
9154 ;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth
9155 ;; Floor, Boston, MA 02110-1301, USA.
9157 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
9161 ;; You need not load this file. It contains only documentation.
9163 (provide 'icicles-doc2)
9165 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
9166 ;;; icicles-doc2.el ends here