: [[image:iciclesimage]]

|| *Previous:*  [[Icicles - Completions Display]] || '''[[Icicles]]''' || IciclesIndex || *Next:* [[Icicles - Sorting Candidates]] ||

----

== Icompletion ==

Emacs incremental completion, or '''icompletion''', provided by
[[IcompleteMode|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 completion]]s, 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*'.















[:icomplete+.el]
[:UsingIciclesWithIcomplete]
=== Using Icicles with Icomplete Mode ===

'''Icicles''' interacts with [[IcompleteMode|Icomplete mode]] in a number of ways.

* In ''Icicle'' mode you can toggle Icomplete mode on and off using
'''`<tt>C-M-#</tt>'''' (command '''`icicle-toggle-icomplete-mode'''')  anytime in the minibuffer (assuming you have already
loaded library `##icomplete.el##' or <tt>[[icomplete+.el]]</tt>).    For Emacs versions prior to Emacs 23, the
change takes effect only at the next minibuffer invocation.

* Starting with Emacs 23, '''Icicles''' can automatically turn Icomplete mode off and on,
depending on the number of current candidates.  This is a
performance optimization, to eliminate the (independent)
calculation by Icomplete mode of a large set of candidates.

: You can control this behavior by customizing [[user option]]
'''`<tt>[[Icicles - Customization and General Tips#icicle-icomplete-mode-max-candidates|icicle-icomplete-mode-max-candidates]]</tt>''''.
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 [[#CompletionsIcompletion|Apropos and Prefix Completion]], below).

* In addition to this automatic toggling, '''Icicles''' [[multi-command]]s
that typically display a large number of completion candidates
automatically turn off Icomplete mode.  When this happens, a
message informs you.  Just use `<tt>C-M-#</tt>' (command
'''`icicle-toggle-icomplete-mode'''') to turn it back on.

: 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)


* '''Icicles''' works with my library <tt>[[icomplete+.el]]</tt> to provide minibuffer feedback on the number of Icomplete-completion
candidates when you cycle.    This
number is displayed whenever you change direction when [[Icicles - Cycling Completions | cycling]].  For example:

[new]
: ##M-x forward-line   [Matched]  ##'''''<tt>(13 more)</tt>'''''
[new]


'''See also:''' [[IcompleteMode#IcompleteModePlus|Icomplete+]]










[:IncrementalCompletion]
[:CompletionsIcompletion]
=== Icompletion in *Completions*: Apropos and Prefix Completion ===

Buffer `*Completions*' shows you the current set of candidates for
either prefix or apropos completion.  Together, [[user option]]s
'''`<tt>[[Icicles - Customization and General Tips#icicle-incremental-completion|icicle-incremental-completion]]</tt>'''', 
'''`<tt>[[Icicles - Customization and General Tips#icicle-incremental-completion-delay|icicle-incremental-completion-delay]]</tt>'''', and
'''`<tt>[[Icicles - Customization and General Tips#icicle-incremental-completion-threshold|icicle-incremental-completion-threshold]]</tt>'''' control incremental
updating of `*Completions*'.

And together with option
'''`<tt>[[Icicles - Customization and General Tips#icicle-expand-input-to-common-match|icicle-expand-input-to-common-match]]</tt>'''' they control incremental expansion (completion) of your input in the minibuffer.


If option '''`<tt>[[Icicles - Customization and General Tips#icicle-incremental-completion|icicle-incremental-completion]]</tt>'''' 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 '''`<tt>[[Icicles - Customization and General Tips#icicle-show-Completions-initially-flag|icicle-show-Completions-initially-flag]]</tt>'''' 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 '''`<tt>[[Icicles - Customization and General Tips#icicle-incremental-completion-delay|icicle-incremental-completion-delay]]</tt>'''' 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 '''`<tt>[[Icicles - Customization and General Tips#icicle-incremental-completion-threshold|icicle-incremental-completion-threshold]]</tt>''''.  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
'''`<tt>C-#</tt>'''' in the minibuffer.  If the number of completion candidates
is very large, then use `<tt>C-#</tt>' 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 ([[IcompleteMode|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 `<tt>C-#</tt>', '''Icicles''' [[multi-command]]s that typically display a large
number of completion candidates ''automatically turn off'' incremental
completion.  When this happens, a message informs you.  Just use
`<tt>C-#</tt>' 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)








[:InputExpansion]
=== Incremental Completion (Input Expansion) in the Minibuffer ===

As mentioned in [[#CompletionsIcompletion|Icompletion in *Completions*]],
another '''Icicles''' option, '''`<tt>[[Icicles - Customization and General Tips#icicle-expand-input-to-common-match|icicle-expand-input-to-common-match]]</tt>'''', 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 '''`<tt>[[Icicles - Customization and General Tips#icicle-expand-input-to-common-match-alt|icicle-expand-input-to-common-match-alt]]</tt>'''').  You can use '''`##C-M-"##''''
in the minibuffer to cycle among all behaviors.

See Also:

* [[Icicles - Expanded-Common-Match Completion]]

* [[Icicles - History Enhancements#Which|What Input, What History?]]

* [[Icicles - Customization and General Tips#icicle-expand-input-to-common-match|icicle-expand-input-to-common-match]]










[:HighlightNonmatch]
=== 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:
[[image:IciclesHighlightInputFailurePrefix]]

Apropos completion -- `char-u' matches a command substring:
[[image: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 '''`<tt>[[Icicles - Customization and General Tips#icicle-incremental-completion|icicle-incremental-completion]]</tt>'''', '''`<tt>[[Icicles - Customization and General Tips#icicle-test-for-remote-files-flag|icicle-test-for-remote-files-flag]]</tt>'''',
'''`<tt>[[Icicles - Customization and General Tips#icicle-highlight-input-completion-failure|icicle-highlight-input-completion-failure]]</tt>'''', '''`<tt>[[Icicles - Customization and General Tips#icicle-highlight-input-completion-failure-delay|icicle-highlight-input-completion-failure-delay]]</tt>'''', and '''`<tt>[[Icicles - Customization and General Tips#icicle-highlight-input-completion-failure-threshold|icicle-highlight-input-completion-failure-threshold]]</tt>'''' 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 `<tt>C-#</tt>' 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.

[new]
: 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))))
[new]

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.

[:icicle-test-for-remote-files-flag]
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.


[:icicle-network-drive-means-remote-flag]
Finally, whether to treat files on MS Windows mapped network
drives as remote or local for things like incremental completion
is controlled by option '''`<tt>[[Icicles - Customization and General Tips#icicle-network-drive-means-remote-flag|icicle-network-drive-means-remote-flag]]</tt>''''.  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 Display]] || '''[[Icicles]]''' || IciclesIndex || *Next:* [[Icicles - Sorting Candidates]] ||



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

CategoryCommands 
CategoryCompletion
CategoryDocumentation
CategoryHelp
CategoryProgrammerUtils