Icicles - Icompletion

Previous: Icicles - Completions DisplayIciclesIciclesIndexNext: Icicles - Sorting Candidates


Emacs incremental completion, or icompletion, provided by Icomplete mode from standard library `icomplete.el’, displays matching completions in the minibuffer. The completions are, however, what vanilla Emacs thinks they are.

In general, this means prefix completions, but whatever it might mean in any context, the point is that these completions might not be those that you see when you use Icicles completion. For example, if you use Icicles apropos completion (‘S-TAB’) then the candidates are typically not reflected in the candidates that Icomplete mode shows in the minibuffer.

Icomplete mode provides completion help, letting you know which (prefix) completions are available. The display of candidates shown by Icomplete mode is updated incrementally as you type characters.

Icicles enhances Emacs incremental completion in these ways:

1. It plays well with standard Icomplete mode.

2. It highlights the part of your input that does not match any completion candidate.

3. It provides a new kind of incremental completion, using buffer ‘*Completions*’.

Using Icicles with Icomplete Mode

Icicles interacts with Icomplete mode in a number of ways.

You can control this behavior by customizing user option `icicle-icomplete-mode-max-candidates’. Set it to ‘nil’ to turn off this automatic Icomplete mode toggling. Set it to a larger or smaller maximum number of candidates to reduce or increase its effect.
It is the act of displaying completion candidates that causes Icicles to check the number of candidates against the option value and thus perhaps toggle the mode. This is the case regardless of how completion is initiated: whether manually (‘TAB’ or ‘S-TAB’) or automatically. But it is not the case for Icicles completion that does not display candidates (‘C-M-TAB’, ‘C-M-S-TAB’). (See also Apropos and Prefix Completion, below).
You can control which commands do this automatic toggling, by adding/removing property ‘icicle-turn-off-icomplete-mode’ to/from the command symbol. For example, command ‘icicle-locate-file’ has the non-‘nil’ property by default. If you do not want this command to turn off Icomplete mode then add this to your init file (~/.emacs):
    (put 'icicle-locate-file 'icicle-turn-off-icomplete-mode nil)
M-x forward-line [Matched] (13 more)

See also: Icomplete+

Icompletion in *Completions*: Apropos and Prefix Completion

Buffer ‘*Completions*’ shows you the current set of candidates for either prefix or apropos completion. Together, user options `icicle-incremental-completion’, `icicle-incremental-completion-delay’, and `icicle-incremental-completion-threshold’ control incremental updating of ‘*Completions*’.

And together with option `icicle-expand-input-to-common-match’ they control incremental expansion (completion) of your input in the minibuffer.

If option `icicle-incremental-completion’ is non-‘nil’, then ‘*Completions*’ is automatically updated whenever you change your input in the minibuffer – that is, with each character that you type or delete. This incremental completion is another form of icompletion. Unlike vanilla icompletion, it uses buffer ‘*Completions*’, not the minibuffer, to show the completion help.

The particular non-‘nil’ value of ‘icicle-incremental-completion’ determines when ‘*Completions*’ is displayed and updated. The default value, ‘t’, means that ‘*Completions*’ is updated only if it is already displayed. Use ‘t’ if you do not want ‘*Completions*’ to be too intrusive, but you want it to provide the most help when you ask for help (via ‘TAB’ or ‘S-TAB’).

Any other non-‘nil’ value is more eager. It displays and updates ‘*Completions*’ whenever there is more than one completion candidate. That can be more helpful, but it can also be more distracting. A value of ‘nil’ turns off automatic updating altogether – ‘*Completions*’ is then displayed only upon demand. I find that ‘t’ represents a good compromise, providing help when I ask for it, and then continuing to help until I’ve finished choosing a candidate.

A completion behavior even more eager than that produced by setting ‘icicle-incremental-completion’ to non‘nil’ and non-‘t’ can be had by setting option `icicle-show-Completions-initially-flag’ to non-‘nil’. In that case, completions are shown even before you type any input. You see all of the possible candidates initially, unfiltered by any typed input. In this regard, see also Icicles - Ido and IswitchB.

When you are editing, Icicles normally does not interrupt you to recalculate and redisplay the matches after each character you type or delete. Option `icicle-incremental-completion-delay’ is the number of seconds to wait before updating ‘*Completions*’ incrementally. It has an effect only when the number of completion candidates is greater than `icicle-incremental-completion-threshold’. This delay can improve performance when there are many candidates. It lets you type ahead before any candidate redisplay occurs.

You can cycle Icicles incremental completion at any time (changing ‘icicle-incremental-completion’ among ‘nil’, ‘t’, and ‘always’) using command ‘icicle-cycle-incremental-completion’, which is bound to `C-#’ in the minibuffer. If the number of completion candidates is very large, then use `C-#’ to turn off incremental completion – that will save time by not updating ‘*Completions*’. See also Icicles - Large Candidate Sets for other ways to deal with a large number of candidates.

Note: Incremental completion is effectively turned off whenever a remote file name is read, that is, whenever your file-name input matches a remote-file syntax.

There are several advantages of using ‘*Completions*’ for icompletion, as opposed to the minibuffer as in vanilla Emacs (Icomplete mode):

1. Many more candidates can be displayed in ‘*Completions*’ than can be displayed by Icomplete mode, which uses the minibuffer for feedback.

2. Icomplete mode provides feedback wrt vanilla Emacs completions, which do not necessarily correspond to the current Icicles completions (e.g., for ‘S-TAB’). If you use both Icomplete mode and Icicles incremental completion then you can have incremental help for both prefix completion and apropos completion at the same time, one in the minibuffer and the other in ‘*Completions*’.

3. The other Icicles ‘*Completions*’ features are available for the current set of matching candidates: cycling, highlighting of match root, highlighting of previously used candidates, and so on. See Icicles - Completions Display.

Although you can cycle Icicles incremental completion at any time using `C-#’, Icicles multi-commands that typically display a large number of completion candidates automatically turn off incremental completion. When this happens, a message informs you. Just use `C-#’ to turn it back on.

You can control which commands do this, by adding/removing property ‘icicle-turn-off-incremental-completion’ to/from the command symbol. For example, command ‘icicle-locate-file’ has the non-‘nil’ property by default. If you do not want this command to turn off Icicles incremental completion then add this to your init file (~/.emacs):

    (put 'icicle-locate-file 'icicle-turn-off-incremental-completion nil)

Incremental Completion (Input Expansion) in the Minibuffer

As mentioned in Icompletion in *Completions*, another Icicles option, `icicle-expand-input-to-common-match’, controls whether Icicles completes your input in the minibuffer. There are five levels of this expansion behavior to choose from: option values 0 to 4. When expansion occurs it is always the same. See Icicles - Expanded-Common-Match Completion for the description. What this option controls is whether and when expansion takes place.

At one extreme (value 0), your input is never expanded (except when you use ‘C-M-TAB’ or ‘C-M-S-TAB’, which do not display ‘*Completions*’). This is unlike vanilla Emacs but similar to Ido and IswitchB: you look to ‘*Completions*’ for the matches, and you keep typing (or you cycle) to narrow things down and choose. If you use a non-‘nil’, non-‘t’ value for ‘icicle-incremental-completion’ then you might also want to try a value of 0 for ‘icicle-expand-input-to-common-match’.

At the other extreme (value 4), your input is expanded in the minibuffer whenever it is completed in ‘*Completions*’. This includes automatic, incremental expansion, analogous to incremental completion.

A value of 1 means expand your input only when you explicitly request completion, using ‘TAB’ or ‘S-TAB’.

A value of 2 means do that, but also expand your input whenever it matches only one completion candidate. This lets you hit ‘RET’ to choose it (instead of having to hit ‘S-RET’).

A value of 3 means do what 2 does, but also expand your input each time prefix completion occurs. It is the same as 4, except that it does not incrementally expand your input for apropos completion.

For a long time Icicles had only the equivalent of values 3 and 4, and I consider them the most useful. Sometimes you will want to temporarily turn off expansion for apropos completion. You can do that using `C-"’ in the minibuffer: it toggles between any two of the behaviors (3 and 4, by default - see option `icicle-expand-input-to-common-match-alt’). You can use `C-M-"’ in the minibuffer to cycle among all behaviors.

See Also:

Icicles Highlights the Input that Won't Complete

When you are typing or correcting your input during completion, Icicles highlights the part of your minibuffer input that prevents it from matching any completion candidates, by default. This works for both prefix completion and apropos completion. For both, it highlights your input from the leftmost mismatch through the input end.

Here are screenshots showing the highlighting –

Prefix completion – only ‘cha’ matches a command prefix: IciclesHighlightInputFailurePrefix

Apropos completion – ‘char-u’ matches a command substring: IciclesHighlightInputFailureApropos

You can use ‘C-M-l’ to move the cursor to the start of the highlighted, mismatched part of your input. Repeat ‘C-M-l’ to kill the highlighted portion. (Because it is killed, you can use ‘C-y’ to yank it back.)

User options `icicle-incremental-completion’, `icicle-test-for-remote-files-flag’, `icicle-highlight-input-completion-failure’, `icicle-highlight-input-completion-failure-delay’, and `icicle-highlight-input-completion-failure-threshold’ control this highlighting, which is done using face ‘icicle-input-completion-fail’ (for strict completion) or ‘icicle-input-completion-fail-lax’ (for lax completion).

If either ‘icicle-incremental-completion’ or ‘icicle-highlight-input-completion-failure’ is ‘nil’, then no such highlighting is done. Remember that you can cycle incremental completion on and off using `C-#’ in the minibuffer.

Because this highlighting can have a negative impact on performance, you can fine-tune when you want it to occur. The value of ‘icicle-highlight-input-completion-failure’ determines when this highlighting can take place.

In particular, highlighting the non-matching part of remote file names can be slow. Two values of the option allow remote file name highlighting: ‘always’ and ‘explicit-remote’. The other values do not highlight remote file names. You probably do not want to use a value of ‘always’.

If the value is ‘nil’, then highlighting never occurs. If the value is ‘explicit-strict’, ‘explicit’, or ‘explicit-remote’, then highlighting occurs only upon demand: when you hit ‘TAB’ or ‘S-TAB’ to request completion. If the value is ‘implicit-strict’, ‘implicit’, or ‘always’, then highlighting occurs also when you update input during incremental completion (if incremental completion is turned on).

I use a value of ‘implicit’ myself, but the default value is ‘implicit-strict’ because, depending on your setup and use cases, ‘implicit’ can impact performance for file-name completion (which is lax, not strict). I suggest you try ‘implicit’ to see – this feature is especially useful for file names.

TIP: An alternative way to be informed about a file name mismatch (when you use ‘TAB’ or ‘S-TAB’) is to use ‘icicle-no-match-hook’ to signal you using a visual or audible cue. For example:
       (add-hook 'icicle-no-match-hook
                 (lambda () (when (icicle-file-name-input-p) (ding))))

Summary of ‘icicle-highlight-input-completion-failure’ choices:

  • ‘nil’ – Never
  • ‘explicit-strict’ – Only on demand and only during strict completion
  • ‘explicit’ – Only on demand (lax and strict completion)
  • ‘explicit-remote’ – Only on demand, even for remote file names
  • ‘implicit-strict’ – Incremental or explicit completion – strict completion only
  • ‘implicit’ – Incremental/explicit, lax/strict completion
  • ‘always’ – Always (including for remote file names)

These values are listed here in terms of increasing permissiveness, which also can mean increasing performance impact. That is, a value of ‘implicit’ is more likely to affect performance than a value of ‘explicit’. The greatest performance hit comes from file-name matching, in particular if remote files are involved.

If you know that you will not be using remote file names for a while, you can let Icicles and Tramp know this by using the toggle `C-^’ in the minibuffer to turn off option ‘icicle-test-for-remote-files-flag’. When this is off, you cannot use remote files.

Turning off ‘icicle-test-for-remote-files-flag’ using `C-^’ also turns off Tramp’s remote file-name completion and remote file handling. If you turn off the option using `C-^’, then turn it back on using `C-^’ also (instead of just setting the option to non-‘nil’), in order to re-enable Tramp’s file-name handling and completion.

Turning off ‘icicle-test-for-remote-files-flag’ can slightly speed up file-name completion for local files, by avoiding any check for remote file names. If you seldom use remote files, then you might want to customize ‘icicle-test-for-remote-files-flag’ to ‘nil’ and use `C-^’ to toggle it back on whenever you do use remote files.

A ‘nil’ value of ‘icicle-test-for-remote-files-flag’ also overrides the ‘icicle-highlight-input-completion-failure’ values ‘implicit-strict’, and ‘explicit-strict’ for file-name completion, treating them the same as ‘implicit’. It is assumed that you use those values only to avoid the cost of remote file-name matching.

See Also: IsearchPlus for similar highlighting of the non-matching portion of your input during Isearch.

Finally, whether to treat files on MS Windows mapped network drives as remote or local for things like incremental completion is controlled by option `icicle-network-drive-means-remote-flag’. Customize it to ‘nil’ if you would like such files to be treated as local files. You can toggle this option anytime during completion, using `C-x :’.

Previous: Icicles - Completions DisplayIciclesIciclesIndexNext: Icicles - Sorting Candidates

DrewsElispLibraries referenced here: Lisp:icicles.el, Lisp:icomplete+.el

CategoryCommands CategoryCompletion CategoryDocumentation CategoryHelp CategoryProgrammerUtils