Icicles - Nutshell View

iciclesimage
Previous: Icicles - ScreenshotsIciclesIciclesIndexNext: Icicles - Inserting Text from Cursor

README for NON-Readers

Load library icicles.el, turn on Icicle mode, and you’re good to go. You can turn Icicle mode off or on at any time with command ‘icy-mode’. When you turn it off, you’re back in vanilla Emacs.

Beyond that, the most important thing to know about Icicles is that you can get help on Icicle mode during minibuffer input. You can do that by using item Help of the menu bar Icicles menu or Minibuf menu, or by hitting `M-?’ (‘icicle-minibuffer-help’).

(To see the keys that are bound when you are in the minibuffer, you can also use ‘M-S-TAB’, which completes keys in the minibuffer. If your window manager steals ‘M-S-TAB’ then try ‘ESC S-TAB’ or customize option `icicle-key-complete-keys-for-minibuffer’.)

You now know enough to use Icicles. If you have doc-phobia or are easily overwhelmed by explanations, then read no more – just try it!

If you want a little more explanation than the help page (`M-?’), then read the rest of this page, but no more. This page shows a sample of what you can do in Icicle mode.

If you want to know more about Icicles by reading instead of just trying, then read beyond this page. There is a lot you can learn, but there is not much that you need to learn, to use Icicles usefully. Do not be afraid to get in and get wet. Above all, do not be overwhelmed by the doc – if it helps, fine.

Menus

One good way to start with Icicles is to explore menu-bar menus Icicles and Minibuf. You can access most Icicles features using these menus, without at the same time struggling to learn new key bindings.

Menu Icicles is available all of the time (that is, whenever you are in Icicle mode). Menu Minibuf is available whenever the minibuffer is active. It is enhanced for Icicle mode.

Menu Icicles offers top-level commands of all sorts that are available in Icicle mode. Instead of grouping these all in the same menu, Icicles, by default they are spread among appropriate existing menus such as File and Edit, on Icicles submenus. Whether this is done is controlled by user option `icicle-touche-pas-aux-menus-flag’. When it is done, menu-bar menu Icicles contains only menu items that do not fit elsewhere.

During minibuffer input completion, you can also press Control and right-click (‘C-mouse-3’) on a completion candidate in buffer ‘*Completions*’, and choose from a contextual popup menu, Completion.

You can customize this menu. By default, its submenu This Candidate has menu items that apply to the candidate you clicked to pop up the menu. The other submenus have items that apply to all candidates, candidates you have selected (the region in ‘*Completions*’), or candidates you have saved (marked).

Altogether, there are many menu items in the popup menu. Think of this menu as a learning device and a way to remind you of possible operations on completion candidates and the keys they are bound to. In this it is similar to the help you get when you use `M-?’ in the minibuffer, but with the menu you can also act, not just be reminded.

See Also: Icicles - Completions Display.

README

This README gives you an idea what Icicles is for, what it does. For information about how to obtain and install Icicles see Icicles - Libraries. For information about how to use Icicles read the other sections on this page and the following pages. For quick help during completion, you can use `M-?’ in the minibuffer and ‘C-mouse-3’ on a candidate in buffer ‘*Completions*’.

Icicles enhances minibuffer completion. It does so generally, throughout Emacs. It does this by improving the basic Emacs functions that read minibuffer input with completion: ‘completing-read’, ‘read-file-name’, and ‘read-from-minibuffer’.

This means that Icicles affects every kind of minibuffer completion, not just buffers or files or commands or variables or faces or… Every kind. (You can even complete key sequences.) Lisp code need not call a special completion function to get this advantage – each call to ‘completing-read’ etc. benefits automatically.

Icicles has this effect only when you are in Icicle minor mode. Turn off Icicle mode and Emacs behaves as usual (vanilla).

To best understand what Icicles offers you, you need to think a bit differently about minibuffer completion.

During (vanilla) Emacs completion:

v1. You type some input. Then you ask Emacs (‘TAB’) to look for a match of your input against the domain of input possibilities: the completion candidates. If a match is found, your input is completed and you hit ‘RET’ to accept it (commit it as your final input). If there are several matches you type some more text and recomplete … until there is only one match. Then you hit ‘RET’.

v2. The goal here is to complete and then enter your input, as easily and rapidly as possible.

v3. The process starts with a domain of possible inputs: the initial set of candidates. This domain can be realized intensionally, via a function, or more commonly extensionally, via an explicit set.
v4. Sometimes completion is “lax” instead of “strict”, meaning that you can input any text you like in the end (‘RET’), but a set of candidates is still provided for the convenience of completion (‘TAB’).

v5. When you hit ‘TAB’ to complete, your current input in the minibuffer (the contents) filters the domain, narrowing it down to the set of matching candidates, which is shown in buffer ‘*Completions*’.
(See also Icicles - Background on Input Completion.)

For Icicles it is the completion process that is important, and this process can serve several goals. So instead of focusing on the goal of entering a final input (v2), let’s consider the overall process: There is a set (domain) of possible candidates (v3) that you filter with your input (v1).

If you edit your input and recomplete using ‘TAB’, then the domain is refiltered to a different set of matching completion candidates. Each time you do this your input corresponds to a different set. The process of completion thus provides a great way to filter a set interactively.

Now if all you do in the minibuffer at the end of the day is enter your final input (‘RET’), then changing your input and recompleting (‘TAB’) is pretty much a waste of time, a detour. But if you can do more along the way, if you can make use of the current set of matches in some way, then the story is different.

This is the key to understanding what Icicles offers. Think of minibuffer completion as a pattern-matching user interface, a general way to interact with sets of named objects.

No doubt you have already used completion sometimes as more than just a means toward the end of inputting a value. Perhaps you have used ‘TAB’ during file-name completion to take a look at the nearby directory structure, possibly even finishing with ‘C-g’ instead of entering any file name definitively (‘RET’). In that scenario, you are exploring the set of file-name candidates, using minibuffer completion as a help feature.

Icicles binds different keys in the minibuffer keymaps to provide different ways to interact with the current set of matches (completion candidates). To exploit the possibilities of filtering a set dynamically by pattern matching, Icicles provides different features that work together.

These are the most important Icicles features:

i1. Incremental completion. By default, each change you make to your minibuffer input automatically rematches and recompletes it (v5). IOW, the set of current candidates is updated dynamically, incrementally. You can always see (in the ‘*Completions*’ window) what your current input (the minibuffer content) matches. This is a help and exploration feature.

i2. Cycling and the current candidate. You can cycle among the current set of candidates (minibuffer matches). The current candidate is placed in the minibuffer as you do this, for possible editing. You can of course hit ‘RET’ to commit the current candidate, edited or not, as final input.

i3. Help, multiple actions, alternative actions. But you can also instead hit a key to provide information (help) about the current candidate, hit a key to act on it (accept it as input but without ending the minibuffer), hit a key to perform some alternative action on it (without ending the minibuffer), and so on. Candidate help is perhaps the Icicles feature used most often.

i4. Multi-commands and multi-inputs. A multi-command is one that lets you act on a completion candidate without exiting the minibuffer, so that you can thus act on several candidates. Not every command is a multi-command. In addition to acting on multiple candidates that you choose (perhaps all of them), you can act on multiple inputs in the same minibuffer (called multi-inputs), all at once.

i5. Multi-completions. Use completion to match two different things at once. The completion candidates are multi-part, so your input can also be multi-part or can match only particular parts. An example of using multi-completions is matching both file name and file content, in parallel.

i6. Set operations. You can hit a key to act not on any particular matching candidate but on each of them individually or on all of them collectively. Among the collective set operations are union, intersection, difference/complementing, and saving for later reuse.

i7. Progressive completion. Set intersection can take a couple of forms. The most useful is “progressive completion”: use the current set of matching candidates as the domain for a recursive minibuffer. That is, start over and match different inputs against a subset of the original domain that was defined by the previous matching operation. This is analogous to piping ‘grep’ outputs through additional ‘grep’ filters.

i8. More powerful matching. Using your input (minibuffer content) as a dynamic filter is very important in Icicles. In line with this, you can employ different matching methods. The most powerful is regexp matching (which includes substring matching).

i9. Candidate sorting. You can sort the current candidates on the fly in different ways, so that you can cycle them in different orders. The possible sort orders at any time depend on the context and type of candidates. You can define your own sort orders.

Most of these features are unique to Icicles. Others were original with Icicles but have since been copied by vanilla Emacs or other libraries. But only Icicles offers these features (and more) together, combining them cooperatively.

Icicles is very general. It affects many aspects of minibuffer completion. As you learn to take advantage of its features it can change how you use Emacs. But Icicles also stays out of the way if you do not ask for its help. If you just use ‘TAB’ completion and you use none of the keys bound specially during completion (for cycling, progressive completion, etc.), then you will hardly notice Icicles.

All Lisp code that uses minibuffer completion automatically takes advantage of Icicles. But some other libraries go beyond this by defining Icicles multi-commands or otherwise making some special use of Icicles features. None of these libraries are required in order to use Icicles, but they are recommended because of the synergy they provide. See Recommended Libraries.


Flashy Demo to Pique Your Curiosity

This section shows a few examples to get you started and hopefully interested. Subsequent sections in this nutshell view show more Icicles features in more detail, but still giving an overview.

First Example: Multi-Inputs

In vanilla Emacs you can do this to visit all files whose names match the glob pattern `ici*.el’:

C-x 4 f i c i * . e l RET

In Icicle mode you can also do the following, to visit all `ici*.el’ files, file `my file.txt’, and file `bookmark+.el’, just as if you had used ‘C-x 4 f’ three separate times [*]:

C-x 4 f ici*.el "my file.txt" bookmark+.el M-R C-g

Your multi-input here is split into separate file-name patterns, which are then acted on individually. You wrap the second pattern with "..." because the file name contains a space character, which is otherwise used to separate patterns.

The ‘C-g’ at the end just ends the command. Without it you can continue to enter the names of more files to visit. This is because ‘C-x 4 f’ is bound to a multi-command (‘icicle-file-other-window’).

[*] (For brevity, spaces were not used here to separate each printable character typed: `ici*.el’ instead of `i c i * . e l’.)

Second Example: Multi-Completions

Suppose that you do this:

C-x 4 f i c i C-M-j c o l o r S-SPC

The completion candidates, shown in ‘*Completions*’, are the files (a) whose name contains ‘icicles’ (completed from ‘ici’) and (b) whose content includes ‘color’ — that is, the files themselves contain the text ‘color’.

The file content is in fact part of the two-part completion candidate, but of course it is not shown. It is used only for filtering. Only the file names are shown in ‘*Completions*’.

Then you do this, with the previous candidates still current:

c m C-M-j i n e - f

As you type, the candidates shown in ‘*Completions*’ are updated. When you finish typing, the set of candidates is reduced to just `icicles-cmd1.el’ and `icicles-cmd2.el’, the files whose name contains also ‘cm’ and whose content contains also ‘ine-f’ (as in ‘icicle-define-file-command’).

Then you hit `C-!’ to visit each of those files.

(Yes, it’s a toy example to show you some features. Clearly you could just as well have used only ‘icicles-cm’ as your input, or even `ici.*cm’, or ‘s-cm’, or perhaps only ‘cm’, depending on the files in your directory.)

You have just used the following Icicles features:

Using ‘C-M-j’ followed by a content-matching pattern in your input is optional. If you do not provide it then no content-searching is done.

The file-name pattern is also optional: you can search content without having any idea about the file names — just start with ‘C-M-j’. Obviously, content-searching is much slower than file-name matching. If you can match names, that reduces the number of files whose content needs to be searched.

Most of the behavior you see in this example is available for most Icicles commands. The name+content behavior is available for only some Icicles commands, including those that choose files, buffers, or some other type of object that has contents (a “container”).

See Also:

Third Example: Narrowing a Manual

The second example showed how you can match either the name or the contents of a file, or both. The same behavior of matching both the name and the contents of a container is available for visiting an Info node (chapter of a manual) or a buffer. In Icicle mode, by default, ‘g’ in Info mode is bound to ‘icicle-Info-goto-node’, and ‘C-x b’ is bound to ‘icicle-buffer’.

These multi-commands act just as described in the second example, but using buffer-name/contents and node-name/contents candidates instead of file name/contents.

In this example you look up information about indenting text to a column in the Emacs manual (‘C-h r’).

Using the indexes of the manual is always a good way to start. And Icicles helps with that too, by letting you match index entries using patterns (e.g., ‘indent’) that are substrings and regexps.

You could use incremental search to search the whole manual for terms like ‘indent’, but that would be quite laborious. (You can also use Icicles search to search a manual.)

But this example uses the same approach as in the second one: match node names and node content.

1. Start by searching all nodes of the Emacs manual for ‘indent’:
     C-h r
     g C-M-j indent S-TAB
That takes a moment, and shows lots of matching nodes.
2. Search also for ‘column’:
     S-SPC C-M-j column
There are a lot fewer nodes in ‘*Completions*’ now. But still too many to browse.
3. There are a bunch of nodes whose names all start with ‘Glossary’, and they just get in the way, so get rid of them. First match only those nodes, by name:
     S-SPC loss S-TAB
Then toss those nodes out and ask to match something else:
     C-~
4. You’re down to just these nodes now, in ‘*Completions*’:
    Acknowledgments      Basic Indent        Command Index
    Comment Commands     Concept Index       Directory Variables
    Directory Variables-Footnote-1           Enriched Indentation
    Fill Prefix          ForIndent Cont      ForIndent Num
    Fortran              Fortran Autofill    Fortran Columns 
    Fortran Comments     Fortran Indent      Indentation Commands
    Just Spaces          Key Index           Left Margin Paren
    Lisp Indent          Multi-Line Comments Multi-line Indent
    Options for Comments Picture Mode        Program Modes
    Selective Display    Tab Stops           Table Conversion 
    Text                 Top                 Variable Index 
5. There’s a lot of Fortran stuff there, which you can remove:
      S-SPC fortr S-TAB C-~
6. Now selectively remove some of the other ones individually. You can do that by clicking them with ‘S-mouse-2’ or by cycling to them and hitting the ‘delete’ key. Click ‘Acknowledgments’ and ‘Top’ to begin with.
7. Not being too sure about some of the others, you can take a quick look at them and hit ‘delete’ if they don’t look interesting. Use ‘down’ or ‘up’ to cycle among them. Use ‘C-RET’ to take a look at the node that is the current candidate (highlighted in ‘*Completions*’). Use ‘C-M-s’ in the Info window to check occurrences of the content pattern, if you want. Use ‘delete’ (in the minibuffer) to remove the current candidate node if not pertinent.
8. Now you’re down to just these node names:
    Basic Indent        Command Index         Comment Commands
    Concept Index       Enriched Indentation  Indentation Commands 
    Just Spaces         Key Index             Multi-line Indent
    Program Modes       Tab Stops             Text
    Variable Index 
That might seem like a lot of trouble, but each of the operations is simple and you will soon make use of them everywhere in Icicles.
What you have now is essentially a customized, mini-manual about indenting text. You can visit any of its nodes by cycling to them and hitting ‘C-RET’, or by just clicking ‘C-mouse-2’ on the node name in ‘*Completions*’.
9. You can “save”, or “mark”, this set of nodes, so you can easily come back and reuse it later.
      C-M->
The nodes are now shaded/highlighted, showing that they are “saved” for the current Emacs session. Hit ‘RET’ to end at one of the nodes or repeat ‘C-g’ or `C-]’ to cancel the command and return to ‘Top’.
10. To restore the mini-manual:
      g C-M-<
11. You can save the mini-manual persistently, so you can come back to it in a later Emacs session. Retrieve the node-name candidates, then use `C-}’ to save them. You are prompted for a saved-candidates-set name and the cache file location, which can be anything you like.
      g C-M-< C-} Indentation Topics RET /here/IndentationTopics.icy RET
12. To restore the mini-manual in any Emacs session:
      g C-{
Alternatively, you could have just saved the candidates persistently to begin with, using `C-}’ instead of `C-M->’.

These are the features used in this example, which you did not use in the second example:

See Also:

Fourth Example: Tagged Files

This feature works only if you also use library Bookmark+, which lets you tag files with arbitrary labels (delicious-style tags) that you come up with.

Suppose you have previously tagged some files, and now you want to visit one or more of the files that have both of the tags ‘2013’ and ‘mountains’. If you also have some idea of the file names or file contents, then you can match those too, as explained in the second example. But let’s suppose you do not and you just want to match tags.

C-x 4 f TAB C-x C-t * 2013 RET mountains RET RET

During file-name completion, ‘C-x C-t *’ narrows the current candidates to those naming files that have been tagged with each of the tags you enter. You type each tag to be matched, followed by ‘RET’, then you add a second ‘RET’ after the last tag.

In this case, the current candidates before using ‘C-x C-t *’ included all files in the current directory (you hit ‘TAB’ immediately, without typing anything to match file names or file contents).

Besides narrowing candidates during ordinary file-visiting commands (e.g., ‘C-x C-f’), you can use multi-command ‘icicle-find-file-tagged’ (‘C-x j t C-f C-f’) to directly visit a file that has tags matching the second part of your multi-completion input, the part after ‘C-M-j’. For example:

C-x j t C-f C-f C-M-j 2013 S-SPC mountains C-! C-g C-g C-g

(The ‘C-M-j’ is not needed if neither tag matches a file name.)

Tagging the files in the first place is also easy. Here is how to tag the files whose names match both ‘ici’ and ‘doc’ with the tags ‘Icicles’ and ‘help’:

C-x p t + a Icicles RET help RET RET ici S-SPC doc C-! C-g C-g

`C-x p t + a’ runs multi-command ‘icicle-tag-a-file’, which adds the tags you type (ending the last with ‘RET RET’ instead of ‘RET’) to the files whose candidate names you act on. In this case, you hit `C-!’, which acts on all candidates, which in this case are the file names matching both ‘ici’ and ‘doc’.

You can also tag files on the fly during file-name completion. To tag the current candidate, hit `C-x a +’, then enter the tags to add.

See Using Tagged Files.

Top Level to Minibuffer ... and Back Again

While the minibuffer is active, waiting for you to finish your input, you can optionally perform various side actions, interacting with Emacs in pretty much the usual ways. For example, you can move to another buffer, type some text there, check the definition of a key using ‘C-h k’, and then return to typing your input in the minibuffer. This is true of vanilla Emacs, not just Icicles.

In other words, the Emacs minibuffer is not modal, in the sense that while it is interacting with you it does not force you to stop interacting with Emacs in other ways. You can select some other window, edit some text there, hit keys that perform various actions, and so on.

You can tell by now that Icicles uses the minibuffer heavily. It takes advantage of and enhances such side-trip interaction. It does this in part by binding lots of keys in the minibuffer keymaps. The examples seen so far exhibit some of those keys:

  M-?          Show Icicles minibuffer help
  M-R          Act on multiple minibuffer inputs
  C-M-j        Separate multi-completion component patterns
  S-SPC        Initiate progressive completion
  C-!          Act on each matching candidate, in turn
  S-TAB        Apropos-complete (regexp or substring matching)
  down, up     Cycle to the next or previous candidate
  C-RET        Act on the current candidate
  delete       Remove the current candidate from the matches
  C-~          Remove all of the current candidates (complement)
  C-M->        Save (mark) the current candidates, for later reuse
  C-M-<        Retrieve (reuse) the saved (marked) candidates
  C-}          Save the current candidates persistently
  C-{          Retrieve a persistently saved set of candidates
  C-x C-t *    Narrow to files having each of the tags you specify
  C-x a +      Add tags to the current file-name candidate

(How to remember all of this? You don’t need to. You will learn some of the keys little by little. And `M-?’ in the minibuffer lists many of them. And the keys you don’t know won’t hurt you. You can also use ‘C-h M-k’ from library help-fns+.el to list the keys in any keymap, including the minibuffer maps.)

Sometimes this temporary, side-track, or parallel interaction can itself involve inputting something different in a separate minibuffer. That is, in some cases it can mean that you are prompted for minibuffer input at a different level.

A recursive minibuffer is used for this interaction: the original minibuffer interaction disappears from view temporarily, replaced by the new, recursive one. The original minibuffer interaction is not shown, but it is still there, waiting for the new, recursive minibuffer interaction to finish before showing itself again.

Node Recursive Editing Levels in the Emacs manual covers the general topic of recursive editing levels, of which recursive minibuffer levels is a particular case. You will want to read this.

Unfortunately however, though it is worth reading it says next to nothing about the case of recursive minibuffers, because vanilla Emacs makes little use of this feature. The Elisp manual, node Recursive Minibuffers, says a little about the topic, but still not much.

Whereas Emacs provides a special indication of recursive editing in the mode line, using nested `[...]’ to show the current recursive-edit depth, It offers less to show you the depth of minibuffer recursion. To get it to show anything at all, you need to turn on ‘minibuffer-depth-indicate-mode’. Then it prepends a depth indicator to the minibuffer prompt.

Emacs bug #14147 asks Emacs Dev to turn on ‘minibuffer-depth-indicate-mode’ by default. In any case, it is turned on automatically whenever you are in Icicle mode, because a recursive minibuffer is not uncommon in Icicles. In addition, if you use library mb-depth+.el then you can customize the appearance of the depth indicator.

Canceling Minibuffer Interaction

Whether or not the minibuffer is active, ‘C-g’ cancels the current Emacs operation, essentially the current command. If the current command is reading your input from the minibuffer, then ‘C-g’ exits the minibuffer. If this is a recursive minibuffer then you pop up a level, either to a shallower minibuffer or, if there is none, to the top level of Emacs (no active minibuffer).

But sometimes when the minibuffer is active the current command is something other than the command that initiated reading input from the minibuffer. This is common in Icicles, but not so common in vanilla Emacs. When you hit a key during minibuffer input, the command bound to that key becomes the current command until it is finished. If it is a self-inserting key like ‘e’ then the command (‘self-insert-command’) finishes immediately, of course.

But sometimes the command expects more interaction on your part, or perhaps it performs an operation that takes a while. If you then hit ‘C-g’, it is that command, the now current command, that is interrupted (canceled), and not the minibuffer.

Repeating ‘C-g’ a few times can in many cases cancel the minibuffer as well. But you can always cancel a minibuffer immediately and pop up to the previous level by hitting `C-]’ (‘icicle-abort-recursive-edit’).

So ‘C-g’ cancels the current command, which sometimes means canceling the minibuffer. And `C-]’ cancels the current minibuffer, popping up to the previous one or to the top level if there is no other minibuffer level.

But suppose you are in a fairly deep recursive minibuffer (for example, you have used progressive completion several times, where each time pushes you down another minibuffer level). How can you jump directly all the way up to the top level, instead of hitting `C-]’ once for each minibuffer level?

Answer: use ‘C-M-T’ (that is, ‘C-M-S-t’), which is bound to ‘icicle-top-level’. That brings you directly to the top level (“without passing GO”), but it first allows Icicles multi-commands to perform any necessary cleanup.

So you have three degrees of canceling when you are in the minibuffer: ‘C-g’ (cancel the current command), `C-]’ (cancel the current minibuffer), and ‘C-M-T’ (cancel all minibuffers).

Which you use depends on what you want. Sometimes you want to cancel the current operation and resume editing the same minibuffer. Sometimes you want to cancel the current minibuffer level. And sometimes you want to get out of the minibuffer altogether.

For example, suppose you are using ‘g’ in Info to look up some information and you use progressive completion with a content search, such as in Third Example: Narrowing a Manual. You might decide that the current search is taking too long, or that perhaps you change your mind about which pattern to search for.

In this case, you might hit ‘C-g’ to cancel the current matching operation. After ‘C-g’, you can type the pattern you really want and hit ‘S-TAB’ again. Alternatively, you could hit `C-]’ to cancel the current minibuffer, and then hit ‘S-SPC’ to create another recursive minibuffer.

The effect is the same: you abandon the current search and start another, without starting over from scratch. You keep the progressive-completion filtering already accomplished at previous minibuffer levels. If you instead decide to stop searching altogether then you hit ‘C-M-T’.

Finally, there is another wrinkle to using ‘C-g’ (as ‘icicle-abort-recursive-edit’) if you use DeleteSelectionMode. If the region is active in ‘delete-selection-mode’ when you hit a self-inserting key or a deleting key, then the region is deleted (killed, actually) so that it can be replaced by your edits. That’s a good thing, in general.

When you cycle among completion candidates, depending on your value of options `icicle-point-position-in-candidate’ and `icicle-mark-position-in-candidate’, the text between point and the mark is selected: the region is active. And you might otherwise activate the region in the minibuffer while editing.

In this situation, ‘C-g’ in the minibuffer just deactivates the region, so you can edit without losing the region text. In particular, this means that when you cycle you can more easily edit the text of the current candidate (e.g. during lax completion). Just repeat ‘C-g’ to get its usual behavior (since the region has been deactivated).

See Also: Recompleting Using the Original Domain

Toggle Options on the Fly

There are many user options that affect the behavior of Icicles features. Some of these are Boolean (on/off) or allow for simple alternation or cycling of the possible values. Many of those options are associated with toggle commands that are bound to keys whenever the minibuffer is active, or at least active for completion.

Throughout this doc you will see references to such options and their toggles. For example: “You can toggle case-sensitivity at any time using ‘C-A’ (that is, ‘C-S-a’) in the minibuffer.”

The reason for making it so easy to change the values of these options on the fly is that different kinds of completion, in different contexts, can take advantage of different option values. Icicles completion is very general, and a single option value is not always optimal for all contexts.

You will become acquainted with a few of these toggle keys and remember them, but you will forget others. What is important to point out here is that `M-?’ (‘icicle-minibuffer-help’) is your friend in the minibuffer. During completion, the help it displays includes, near the top, a list of the toggle keys and the corresponding current values of their options.

Whenever you use an Icicles toggle command, a momentary message shows you the new option value. So as an alternative to using `M-?’ to see the current value of an option, you can just toggle it twice.

Cycle Completion Candidates

M-x t o o l next

That is, type “tool” and then hit the ‘next’ key, which is often labeled Page Down. Each time you hit ‘next’, another match for your input (‘tool’) replaces it in the minibuffer:

M-x ediff-toggle-usetoolbar next → 
M-x scroll-bar-toolkit-scroll next → 
M-x tool-bar-mode next → 
M-x tooltip-mode next → 
M-x ediff-toggle-use-toolbar – Back to the beginning

Keys ‘next’ and ‘prior’ (Page Up) cycle among all of the commands that contain (match) the minibuffer input pattern – ‘tool’, in this case. Just hit ‘RET’ (Return) when you get to the command you want.

(Note: The particular candidates shown here and in other examples might be different from what you see, depending on your version of Emacs and what other libraries you might have loaded.)

You can use a regular expression (regexp) to narrow the field of matching inputs:

M-x i s e . + c h a r next → 
M-x isearch-delete-char next → 
M-x isearch-other-control-char next

Note that when you cycle, a one-line description of the current candidate is shown in the mode line (of buffer ‘*Completions*’ if visible; otherwise of the current buffer). You can get more detailed info about individual candidates by holding the Control and Meta keys (e.g. ‘C-M-next’) while you cycle – see Icicles - Completions Display and Get Help on Completion Candidates.

Try cycling candidates for ‘C-h v’ for instance, using ‘next’. Look for their descriptions in the mode line. Now try cycling using ‘C-M-next’ - complete candidate help is shown in buffer ‘*Help*’.

See Icicles - Cycling Completions for more about cycling completion candidates.

Display Completion Candidates

You can display all of the matches for the current minibuffer input, in the ‘*Completions*’ buffer, using ‘S-TAB’ (Shift TAB). So, for instance, ‘S-TAB’ with M-x ise.+char in the minibuffer displays all commands whose names contain ‘ise’ followed (somewhere) by ‘char’.

IciclesRegexpCompletions

When you cycle among matching candidates as described above, if buffer ‘*Completions*’ is displayed, then the current candidate is highlighted there. In this screenshot taken while cycling, the current candidate is ‘isearch-forward-exit-minibuffer’. (The other screenshot annotations shown here are covered in Icicles - Apropos Completions.)

iciclesscreenshot

See Icicles - Completions Display for more about using the ‘*Completions*’ window.

Prefix Completion and Apropos Completion

You can get the standard Emacs prefix completion, instead of the apropos completion just described, by using ‘TAB’ instead of ‘S-TAB’. You can cycle prefix-completion candidates by using the ‘end’ and ‘home’ keys instead of ‘next’ and ‘prior’. (All four of these keys are typically together in a central keypad to the right of the main keyboard.)

You can also cycle candidates according to the current completion mode, prefix or apropos, using either the mouse wheel or the arrow keys ‘down’ and ‘up’. These are all called the modal cycling keys because they respect the current completion mode.

The current completion mode is determined by the last completion key you used, ‘TAB’ or ‘S-TAB’. If you have not used either so far during the current minibuffer invocation, then the modal keys cycle according to the value of option `icicle-default-cycling-mode’. By default the option value is ‘prefix’, which means that you can use ‘down’, ‘up’, or the mouse wheel to cycle prefix completions without needing to first hit ‘TAB’.

The non-modal cycling keys, ‘next’, ‘prior’, ‘end’, and ‘home’ automatically set the completion mode and update the candidate completions. The modal cycling keys just cycle according to the current completion mode, whether it is apropos or prefix.

To cycle using the mouse wheel, the mouse must not be over the ‘*Completions*’ window; if it is, then the wheel scrolls that window instead of cycling candidates – see Icicles - Completions Display.

As an alternative to using ‘end’ or ‘next’, you can cycle candidates downward (forward) by just repeating the same completion key: ‘TAB’ or ‘S-TAB’. For example:

M-x tool TAB → Display candidates with prefix ‘tool’ in ‘*Completions*’
M-x tool-bar-mode TAB → 
M-x tooltip-mode TAB → 
M-x tool-bar-mode – Back to the beginning

Or:

M-x tool S-TAB → Display matching candidates in ‘*Completions*’
M-x ediff-toggle-usetoolbar S-TAB → 
M-x scroll-bar-toolkit-scroll S-TAB → 
M-x tool-bar-mode S-TAB → 
M-x tooltip-mode S-TAB → 
M-x ediff-toggle-use-toolbar – Back to the beginning

Changing to a different completion key (‘TAB’ to ‘S-TAB’ or vice versa) always switches completion type and completes, but you can then repeat that new completion key to cycle among the candidates.

Note: In vanilla Emacs, repeating ‘TAB’ scrolls the ‘*Completions*’ window. In Icicles, you can use ‘C-v’ to scroll `*Completions*’ down and ‘M-v’ to scroll up. You can also use the mouse wheel to scroll ‘*Completions*’.

See Icicles - Apropos Completions for more about apropos and prefix completion.

Chains of Simple Match Patterns - Progressive Completion

To see which functions contain ‘char’, ‘delete’, and ‘back’ in their names, in any order:

C-h f c h a r S-TAB – Display all function names that contain ‘char’.
M-* d e l e t e – Narrow that set of names to those that also contain ‘delete’ (somewhere).
M-* b a c k – Narrow the set of matching names further, to those that also contain ‘back’ (somewhere).

This displays a list of functions like this in buffer ‘*Completions*’ (your list might be somewhat different):

     backward-delete-char             backward-delete-char-untabify
     delete-backward-char             icicle-backward-delete-char-untabify
     icicle-delete-backward-char      quail-conversion-backward-delete-char

Since you are completing input to ‘C-h f’ in this case, you can then cycle to a name using ‘next’ and hit ‘RET’, or click ‘mouse-2’, to see the doc for that function. If, instead, you were completing input to ‘M-x’, you could choose a command to execute. And so on.

The thing to notice here is that you can use ‘M-*’ to input chains of multiple simple regexps, to narrow down the set of completion candidates progressively, that is, step by step. This is analogous to piping the result of ‘grep’ to another ‘grep’, and piping that result to another ‘grep’, and so on.

Here are a couple others to try (I’m always forgetting the order in these compound names):

C-h f w i n d o w S-TAB M-* f r a m e
C-h f w i n d o w S-TAB M-* b u f f e r

As a shortcut, you can use just ‘S-SPC’ instead of ‘S-TAB M-*’.

See Icicles - Progressive Completion for more about progressive completion with ‘M-*’.

See Locane Powder for someone else’s description of the joys of Icicles progressive completion.

Chip Away the Non-Elephant

There’s a joke about a sculptor who, when asked how he created such a life-like statue of an elephant, said that he just chipped steadily away, removing marble that did not resemble an elephant. (Actually, Michelangelo supposedly said something similar.)

Icicles lets you sculpt this way too – it is in fact a common Icicles usage idiom. There are two ways to say, “I do not want that” when it comes to possible completions:

In other words, instead of coming up with input that you want a completion to match, get rid of one or all of the candidates that do match. You can keep clicking ‘mouse-2’ while holding Shift, or keep hitting ‘delete’ (without Shift), to chip away at the set of possible completions. If there are several candidates in a row that you want to eliminate, just hold down the ‘delete’ key until they’re gone.

So that you can use ‘delete’ this way to delete candidates one after the other, in order, the next candidate is chosen each time you delete one. This means that it becomes the current candidate in the minibuffer. You can, however, use ‘M-k’ to clear the minibuffer or use ‘C-l’ (bound to command ‘icicle-retrieve-previous-input’) to clear the minibuffer and retrieve your last real input – see Icicles - History Enhancements.

‘delete’ works well to delete isolated candidates or groups of candidates that are in order (the current sort order), one right after the other, and you can of course combine it with positive matching.

Note: In Emacs releases prior to Emacs 22, ‘delete’ has no real effect on file-name completion candidates (but it works fine on non file-name candidates). It removes them temporarily, but they are not really removed as possible candidates, so ‘TAB’ and ‘S-TAB’ will still show them as candidates.

`C-~’ is particularly handy in combination with progressive completion (‘M-*’ or ‘S-SPC’) to narrow down a set of candidates, especially when you are not exactly sure what you are looking for. You can repeat `C-~’ with different inputs to eliminate everything matched by each of them. In other words, this is a variable-size chisel, and you can use it to remove very large chips.

For instance, suppose you are looking for a standard Emacs command involving buffers. You try ‘M-x buff S-TAB’, but that shows zillions of matches. Suppose that you know you do not want a command in some 3rd-party package. You proceed to eliminate those, progressively, using something like this:

  S-SPC ediff C-~ ibuffer C-~ icicle C-~ Buffer-menu C-~ ps- C-~
        ido C-~ search-buffers C-~ moccur C-~ swbuff C-~

And so on. That is, instead of using ‘M-*’ or ‘S-SPC’ repeatedly to specify multiple patterns that candidates must match, you use `C-~’ repeatedly (after an initial ‘M-*’ or ‘S-SPC’), to chip away candidates you do not want. You could, alternatively, hold down the ‘delete’ key to eliminate each of these groups of command names. There are over 100 commands whose names begin with ‘ediff’, however, so `S-SPC C-~’ can be quicker in that case. It can definitely be quicker when apropos matching is involved. And you can of course combine the fine chiseling of ‘delete’ with the variable-size chiseling of `C-~’.

Choose Before You Act

The opposite operation from chipping away at a set of candidates to refine it is to build up a set of candidates that you want to act on. This too is easy with Icicles.

In some user interfaces, including DiredMode in Emacs, you can mark items in a checklist and then, when you’ve selected the items you want and verified the list, act on those that are selected. You might do this, for instance, if you were deleting some files. Icicles lets you interact with completion candidates this same way.

You do this by building up a saved set of candidates, and then retrieving these saved candidates later. You can use the retrieved candidates just as you would any current set of candidates. One of the things you can do is act on all of them, that is, act on each, in turn. You do that with `C-!’.

Of course, if you can use a regexp to match exactly the candidates you want to act on, then you need not bother to save and retrieve them, before acting on them: you can see them all alone in buffer ‘*Completions*’. Here’s an exercise in choosing candidates to save with the mouse in ‘*Completions*’:

C-x C-f i c i TAB – Match all file names that begin with ici.
Click ‘mouse-1’ inside (or to the left of) `icicles-face.el’. [*]
Click ‘mouse-3’ inside (or to the right of) `icicles-mode.el’.
Click ‘mouse-3’ again, in the same place.
Click ‘M-S-mouse-2’ on each of `icicles.el’ and `icicles-cmd1.el’.

[* If you click ‘mouse-1’ on a candidate and (starting with Emacs 22) ‘mouse-1-click-follows-link’ is an integer, then you will need to hold the mouse button depressed longer than that many seconds, or else that candidate will simply by chosen. If the value is ‘t’, then this will not work at all. Any other value presents no problem. (Personally, I use ‘nil’.)]

The candidates that you selected – those between `icicles-face.el’ and `icicles-mode.el’, inclusive, plus `icicles.el’ and `icicles-cmd1.el’, are highlighted specially in buffer ‘*Completions*’, and feedback in the minibuffer tells you that they were “saved”, which you can also think of as “marked”.

Next, use `C-M-<’. This retrieves the set of saved candidates; that is, it replaces the current set of candidates with the saved candidates. If you now use `C-!’, it applies the action to each candidate. In this case, the action is to visit the file (‘C-x C-f’).

The combination of saving (marking) candidates and then retrieving only those you have saved is like progressive completion or chipping away: it is another way of progressively narrowing the set of candidates that you act on.

This screenshot shows the highlighting of saved candidates (in this case, command names, not file names):

DrewsEmacsSavedCandidates

See Icicles - Choose All Candidates for more about `C-!’. See Icicles - Candidate Sets for more about saving and retrieving sets of candidates.

Get Help on Completion Candidates

Sometimes, you’d like to be able to ask for help about individual completion candidates while you’re in the process of choosing one. That is the purpose of the Icicles ‘C-M-’ key bindings available during completion.

The simplest such bindings are ‘C-M-RET’ and ‘C-M-mouse2’. They each do the same thing: provide help on the current candidate. You can use them during cycling or whenever you’ve narrowed the choice down to a single candidate. You can check this way, before you execute a command you’re unsure of.

During completion, you can also cycle among the doc strings for the candidates that match your input, by holding ‘C-M-’ while using any of the cycling keys:

See Prefix Completion and Apropos Completion.

This gives you a very useful on-the-fly apropos feature – use it while you’re completing a command, to check the difference between several possible commands. Or just use it to browse doc strings, to learn more about Emacs.

The ‘C-M-’ keys give you complete help on a candidate, but you get a one-line help summary without doing anything, when you cycle or complete a candidate (entirely). This help is shown in the mode line of buffer ‘*Completions*’ (or of the current buffer, when ‘*Completions*’ is not displayed). It is typically the first line of a doc string. This screenshot shows mode-line help (Replace nonprinting characters...) for the current candidate (highlighted):

lacarte-w-icicles

See Icicles - Help on Candidates.

Perform Multiple Operations In One Command

C-x C-f i c i TAB – Find a file whose name starts with ici.
down (that is, the down arrow) … until you get to candidate icicles-cmd1.el
RET – Open file icicles-cmd1.el.

Nothing new here. Now try the same thing, but use ‘C-RET’ (‘C-return’) instead of ‘RET’ (`return). The command is not ended, and you can continue to choose files to open:

C-x C-f i c i TAB – Find a file whose name starts with ici.
down … until you get to icicles-cmd1.el
C-RET – Open file icicles-cmd1.el.
down … until you get to icicles-opt.el
C-RET – Open file icicles-opt.el.
down … until you get to icicles.el
RET – Open file icicles.el (end).

You just opened three files in a single command. Command ‘icicle-file’ (‘C-x C-f’) is an Icicles multi-command. You can tell if a command is a multi-command when you execute it – if so, the input prompt is prefixed by `+’. So, for example, when you used ‘C-x C-f’, the prompt was “+ File or directory:”. Icicles menu items that are multi-commands are also prefixed by `+’.

In addition to using ‘down’ (or ‘end’ or ‘next’) and choosing (acting on) candidates with ‘C-RET’, you can combine these operations by using ‘C-down’ (or ‘C-next’): act on candidates in succession. And, as mentioned, you can use `C-!’ to act on all candidates at once.

There are many possible uses of multi-commands. They all make use of the same key bindings, which begin with ‘C-’. These keys are analogous to the ‘C-M-’ keys that provide help on completion candidates.

Match Multiple Things Together

Some Icicles commands that ask for your input provide completion candidates that are multi-part, called multi-completions.

For instance, with a non-positive prefix argument (or with ‘C-u C-u’), command ‘icicle-locate-file’ lets you find files anywhere under a given directory (or under each of a set of directories you choose) by matching the file name or the last-modification date, or both. The first part of the multi-completion is the file name; the second part is the date. The two-part candidates are shown in ‘*Completions*’ like this:

  c:/foo/bar.el
  2012 09 24 16:20:14
  c:/foo/bar-none.el
  2012 08 06 10:02:17

You use the key sequence ‘C-M-j’ to separate the two parts of your input. So if you type `.* C-M-j .*14 S-TAB’ then your input matches only the first candidate above. The first `.*’ matches any file name, and the `.*14’ matches the date of only the first candidate.

If you instead type `.*on S-TAB’ then only the second candidate is matched, by its file name this time. In this case you do not bother matching a date – no ‘C-M-j’ or second part, just a first part to match.

Notice that I said ‘S-TAB’, not ‘TAB’. You use apropos, not prefix, completion with multi-completion candidates, at least whenever you use an input pattern that matches other than just the first multi-completion part.

Command ‘icicle-fundoc’ describes a function. You match the function name or the function documentation or both, as the two multi-completion parts. Sometimes it is easy to choose by name, sometimes by doc content, sometimes by a combination.

By default, ‘C-x b’ is bound to ‘icicle-buffer’ in Icicle mode. Here, the second multi-completion part is never shown. The first part matches buffer names, so if you do not input a second part then ‘C-x b’ just matches buffer names, as you are used to (except that Icicles completion is available – apropos, progressive, etc.).

The second multi-completion part is buffer content. Matching searches the available buffers (whose names match the first part of your input, if present), and only those whose contents match the second part of your input remain candidates. You see the buffer-name matches in ‘*Completions*’, but not the content matches.

For example:

  C-x b foo             ; Match buffer names against `foo'
  C-x b C-M-j toto      ; Match buffer contents against `toto'
  C-x b foo C-M-j toto  ; Match both buffer name and contents

See Icicles - Multi-Completions.

Perform Alternative Operations on the Fly

(If this section seems a bit weird or advanced to you, just skip it the first time through.)

C-x C-f i c i TAB – Find a file whose name starts with ici.
down … until you get to candidate icicles-cmd1.el
C-S-RET – You are prompted to choose a function to apply.
f i n d e TAB RET – Choose function finder-commentary.
down … until you get to candidate icicles-fn.el
C-S-RET TAB TAB … until you get to find-file-read-only.
RET – Visit file icicles-fn.el in read-only mode.
C-k TAB – Kill rest of input, then complete the prefix ici.
C-| b y t e - c TAB – Byte-compile all files matching ici.
TAB … until you get to icicles-doc1.el, then RET to visit.

What’s going on? ‘C-S-RET’ (‘C-S-return’) invokes an alternative action on the current completion candidate. Here, you do this, in turn, for the file-name candidates icicles-cmd1.el and icicles-fn.el. `C-|’ invokes an alternative action on each of the current completion candidates. Here, you do this for each file name that begins with ici. Finally, you cycle to icicles-doc1.el and hit ‘RET’ to visit that file.

The alternative action for ‘C-x C-f’ (command ‘icicle-file’) prompts you for a function to apply to the current completion candidate (for ‘C-S-RET’) or to all candidates (for `C-|’).

Here, you choose function ‘finder-commentary’ to visit the Commentary of file icicles-cmd1.el, function ‘find-file-read-only’ to visit icicles-fn.el in read-only mode, and function ‘byte-compile-file’ to byte-compile all files whose names start with ici.

You can use ‘C-u’ with a function you choose, to pretty-print its result (in buffer ‘*Pp Eval Output*’, if too large for the echo area). That is useful for functions that have no side effects. For this to work, use ‘C-RET’, not ‘RET’, to choose the function.

Each command defines its own alternative action, but many Icicles commands have the behavior described here for ‘icicle-file’: their alternative action is to let you apply any function that is appropriate for the given type of candidate (here, file names).

You can even enter an appropriate lambda expression, instead of completing to one of the function candidates provided. For example, you could use `C-|’ with the following input to copy all Icicles libraries to directory ‘ICICLES’:

  (lambda (f) (copy-file f "ICICLES" t))

Note that function ‘copy-file’ is effectively curried here, to create a function of a single argument on the fly.

See Also: Alternative Actions.

Completion Status Indicators

You can always know whether completion is possible when you are inputting text in the minibuffer and, if so, what kind of completion. Completion status is indicated in two places: (1) at the beginning of the minibuffer prompt and (2) in the ‘Icy’ minor mode lighter in the mode line. The second is optional, controlled by option `icicle-highlight-lighter-flag’.

Whenever input completion is available, the prompt is prefixed by `.’ or `+’, indicating simple or multi-command completion, respectively. If completion is strict (your input must match one of the candidates), then this character is enclosed in a box. If completion is lax (permissive), there is no box.

The ‘Icy’ minor-mode lighter text is highlighted red during completion. `+’ is appended to the lighter (`Icy+’) for multi-command completion, `||’ is appended if completion candidates are multi-completions, and the lighter is boxed for strict completion. When minibuffer input is read without completion, the lighter is not highlighted in any way.

If the list of candidates shown in ‘*Completions*’ is truncated (because of option `icicle-max-candidates’) then the lighter text is suffixed by `...’. So if you see `...’ then you know that if you increase ‘icicle-max-candidates’ (e.g. by using `C-x #’ during completion) then more candidates will be available.

In addition, the lighter text (with or without `+’, `||’, and `...’) is ‘Icy’ if completion is case-sensitive and ‘ICY’ if not. You can toggle case-sensitivity at any time using ‘C-A’ (that is, ‘C-S-a’) in the minibuffer.

The faces used for this highlighting in the minibuffer and the mode line are ‘icicle-completion’, ‘icicle-multi-command-completion’, and ‘icicle-mustmatch-completion’. Consult their doc strings for more information. These faces are combined to produce the various highlighting effects – keep that in mind if you customize them.

When you are inputting, keep an eye out for this highlighting. If you do not see it when you are prompted for input, it means that Icicles input completion is not available. This in turn means that ‘S-TAB’ is available, not for input completion, but for Icicles key completion.

Here is a screenshot of the mode-line ‘Icy’ highlighting during strict multi-command completion. The box indicates strict completion. The green highlighting and the `+’ indicate multi-command completion. ‘Icy’ indicates case-sensitivity (‘ICY’ would indicate case-insensitivity).

DrewsEmacsIcyModeLine

Here is a screenshot of the minibuffer, showing the `+’ indicating a multi-command and the box indicating strict completion:

DrewsEmacsMinibufActive

Here’s a screenshot showing lax multi-command completion (no box):

DrewsEmacsMinibufLax

Here’s a screenshot showing the `.’ that indicates a normal command (not a multi-command). It shows strict completion, but lax completion looks similar: `.’, but without the box.

DrewsEmacsMinibufNotMultiCmd

Here’s a screenshot showing strict multi-command progressive completion:

DrewsEmacsMinibufLevel1

Incidentally, the change in minibuffer background shown here is provided by OneOnOneEmacs (library oneonone.el) to provide orientation for recursive minibuffer levels, such as progressive completion uses – see Dedicated Minibuffer Frame.

In addition to using ‘down’ (or ‘next’) and choosing (acting on) candidates with ‘C-RET’, you can combine these operations by using ‘C-down’ (or ‘C-next’): act on candidates in succession. And, as mentioned, you can use `C-!’ to act on all candidates at once.

There are many possible uses of multi-commands. They all make use of the same key bindings, which begin with ‘C-’. These keys are analogous to the ‘C-M-’ keys that provide help on completion candidates.

See Icicles - Multi-Commands for more information about Icicles multi-commands.

Icicles Search

Icicles provides a unique way of searching incrementally. Command ‘icicle-search’ (`C-c `’) is a multi-command. In this case, the completion candidates are the buffer occurrences that match a regexp that you input. ‘C-RET’ visits a search-hit candidate, and ‘C-next’ visits a candidate and prepares to visit the next in succession. If you visit file icicles-doc1.el, which contains the text you are reading now, do this in that buffer:

C-c ` → Search within contexts (regexp): . * r e c u r s i v e . * RET
Search within contexts defined by the regexp `.*recursive.*’.
Choose an occurrence: S-TAB
Show the search hits, in buffer ‘*Completions*’ (optional).
C-next
Cycle among the search hits, navigating to them in turn.
S-TAB next
Cycle among the search hits without navigating.
nextC-RET nextC-RET
Cycle to particular hits and visit (only) those hits.
nextRET
Cycle to a hit and stay there (end).
   
C-c ` → Search within contexts (regexp): M-p RET
Search again within `.*recursive.*’ (‘M-p’ uses input history).
S-TAB e d i t C-next
Search for the substring ‘edit’ within all search hits for `.*recursive.*’. Cycle among the matches. The substring ‘edit’ is highlighted inside the (differently) highlighted `.*recursive.*’ hits. Whatever you type filters the initial set of hits.
M-k
Empty the minibuffer, then S-TAB. All `.*recursive.*’ hits are restored as candidates. Again, whatever your input is (nothing, now), the set of candidates is dynamically updated to match it.
t \ w + n S-TAB C-next ...
Search for matches of the regexp `t\w+n’ within all search hits for `.*recursive.*’ – that is, ‘t’ followed by at least one other word character, followed by ‘n’. Whatever the regexp `t\w+n’ matches (‘thin’, ‘then’, ‘traighten’, ‘tion’) is highlighted inside each candidate.
RET
Stop searching at the current candidate (end).

Now try the same thing, but first use `C-^’ in the minibuffer (e.g. after you enter `.*recursive.*’). That toggles an Icicles search option for highlighting your input matches. The behavior is the same as before, except that all matches to your input are highlighted at once, not just the current match. And not only the exact match is highlighted, but the longest common match among all input matches is highlighted: If your input is ‘edi’, then ‘edi’ is highlighted (there is no longer common match), but if you input the four characters ‘e d i t’, then ``abort-recursive-edit'’ is highlighted. You can use `C-^’ at any time during searching to change the highlighting behavior.

Now try the same thing, but first select some text. The search is confined to the active region (selection) instead of the entire buffer.

Now try the same thing (without a region), but use a negative prefix argument such as ‘C--’ with `C-c `’. This time, after you input the regexp to search for, you are prompted for one or more files to search. This too is multi-command input: you can input any number of file names, using completion.

C-- C-c ` → Search within contexts (regexp): . * r e c u r s i v e . * RET
Search within contexts defined by the regexp `.*recursive.*’.
Choose file (`RET' when done): i c i TAB
Choose among candidates that begin with ici (shown in ‘*Completions*’).
C-!
Choose all matching file names: icicles-cmd1.el, icicles-cmd2.el, icicles-doc1.el, icicles-doc2.el, icicles-face.el, icicles-fn.el, icicles-mac.el, icicles-mcmd.el, icicles-opt.el, icicles-var.el, and icicles.el.
Choose an occurrence: S-TAB
Show the hits in buffer ‘*Completions*’ (optional).
C-next
Cycle among the search hits in all chosen files…

Just as you can choose particular search hits to visit, using ‘C-RET’, so you can use ‘C-RET’ to choose particular files (whose names match the input, e.g. ici) to search. Just as you can visit search hits in order, using ‘C-next’ (or ‘C-end’ or ‘C-down’), so you can use ‘C-next’ (or ‘C-end’ or ‘C-down’) to choose files to visit, one after the other.

When you input the initial regexp (`.*recursive.*’ in the example above) to ‘icicle-search’, you can use completion to retrieve a regexp that you entered previously.

You can use `C-`’ in the minibuffer to toggle escaping of regexp special characters. Use that if you want to find a literal string – for example, if you want to search for the string `form.’ and not text that matches the regexp `form.’ (‘form’ followed by any character except newline). If you use `C-`’ during Icicles search, start the search over again for the toggle to take effect.

Oh, can you use progressive completion with Icicles search? Sure. And chipping away the non-elephant (complementing)? Yep. Try using vanilla Emacs incremental search to find a line that contains a given set of words in any (unknown) order and that also does not contain another given set of words. No can do. But that is simple using Icicles search. (Yes, you can do it using ‘grep’.)

And while you’re searching, you can perform on-the-fly, on-demand replacement. You tell Emacs whenever you want to replace text, instead of replying to an endless litany of ‘query-replace’ queries. Unlike ‘query-replace’, you need not visit search matches successively or exhaustively. You can visit and replace selected matches in any order. And you can even change the order (using `C-,’) in which search hits appear and are navigated sequentially.

In addition to Icicles search (which is also incremental), Icicles offers some enhancements to the standard Emacs incremental search, Isearch:

(The actual keys for this are those defined by user options `icicle-isearch-complete-keys’ and `icicle-isearch-history-insert-keys’, respectively.)

See Also:

Complete Key Sequences Too

Try ‘S-TAB’ at the top level (without first invoking a command that reads input). Icicles presents all of the possible keys and their bindings in the current context – for completion. For example, if you are in DiredMode, the completion candidates include all key sequences in the global map and the DiredMode map (and any current minor-mode maps, such as Icicle mode).

(The documentation always refers to the key that performs key completion as ‘S-TAB’. Actually, it is ‘S-TAB’ only by default. You can customize it, using option `icicle-key-complete-keys’.)

You can then type part of a key name or a command name, and hit ‘S-TAB’ again to apropos-complete your input. You can navigate down the key-sequence hierarchy by completing a key sequence piece by piece:

S-TAB to see the available keys at top level
Click (using ‘mouse-2’) candidate `C-x = ...’, to see the keys that start with ‘C-x’
Click `r = ...’, to see the keys that start with ‘C-x r’
Click `b = bookmark-jump’, to invoke that command and visit a bookmark

Whenever you’re completing a prefix key, such as ‘C-x’, you can click `..’ to navigate back up the key-sequence hierarchy. For instance, if you are completing ‘C-x p’, click `..’ to go back to completing ‘C-x’, and then click `..’ to go back to the top level.

The available keys at any level include the following important keys, which means that you can use Icicles key completion to do almost anything in Emacs:

You can start directly with a key prefix, and then hit ‘S-TAB’ to complete it – you need not start with ‘S-TAB’. You can use Icicles key completion to learn key bindings – ‘C-M-mouse-2’ displays help on any key.

Instead of clicking a completion candidate with ‘mouse-2’, you can of course type part of the key name or command name, and then complete the name and enter it. Gotcha: ‘S-TAB’ uses apropos completion, by default, so remember that typing `.’ matches any character (except a newline). To match only `..’ (to go up a level), either use prefix completion (‘TAB’) or escape the regexp special character: `\.\.’ (or use `^\.’). Or cycle to it.

Icicles key completion is also available in the minibuffer, but there, since ‘S-TAB’ performs apropos completion of your input, the key that initiates key completion is ‘M-S-TAB’, not ‘S-TAB’. (If your window manager steals ‘M-S-TAB’ then try ‘ESC S-TAB’ or customize option `icicle-key-complete-keys-for-minibuffer’.)

See Icicles - Key Completion for more about completing key sequences.

Available for Almost Any Input

All of this works not only for the input of commands, with ‘M-x’, and key sequences, with ‘S-TAB’, but for the input of nearly anything. For instance, you can use ‘C-x b’ (‘switch-to-buffer’) and cycle among buffer names. Or use ‘C-h v’ (‘describe-variable’) and cycle among variable names. Or use ‘C-x f’ (‘find-file’) and cycle among file names. It works whenever a command reads input with completion.

Whenever you’re in Icicle mode, you see “Icy” in the mode line.

If You Are an Emacs-Lisp Programmer

If you are an EmacsLisp programmer, this is the no-brainer, nutshell view of how to take advantage of Icicles in your own code that calls ‘completing-read’ or ‘read-file-name’:

Add this line to your library: (require 'icicles nil t)

That is really all you need to do. And there is no consequence if users do not have Icicles (no load error is raised, because of the non-‘nil’ third argument). In other words, there is no reason not to add this soft ‘require’, unless your library somehow conflicts with Icicles features. (Even then, users will not be affected unless they turn on Icicle mode.)


For more (and there is a lot more), follow the Next links… Have fun!

Oh – did you bypass EmacsNewbieWithIcicles? That’s really the best place to start. This page (Nutshell View) gives you an idea what you can do with Icicles. But read EmacsNewbieWithIcicles to find out how Icicles can help you improve your Emacs expertise.


Previous: Icicles - ScreenshotsIciclesIciclesIndexNext: Icicles - Inserting Text from Cursor

DrewsElispLibraries referenced here: Lisp:icicles.el

CategoryCommands CategoryCompletion CategoryRegexp