Icicles - Customization and General Tips

iciclesimage
Previous: Icicles - Completion in Other BuffersIciclesIciclesIndexNext: Icicles - File-Name Completion Tips

Customization and General Tips

This page contains some tips on using Icicles and descriptions of Icicles user options.

See Also:

Using Icicles with Delete Selection Mode

Icicles works especially well with DeleteSelectionMode, which I use and recommend. (Likewise, for PC selection mode, which uses Delete Selection mode.) In Delete Selection mode, whenever the region (selection) is active (highlighted), you can simply type to replace text in the region, or hit ‘DEL’ (Backspace) or ‘C-d’ (Delete) to delete the region.

However, library delsel.el, which provides Delete Selection mode, binds key sequences in minibuffer maps that are also bound by Icicles. For this reason, if you use both Icicles and Delete Selection mode, you must turn on Icicle mode after you turn on Delete Selection mode. If you forget to do this, you will notice that ‘C-g’ does not abort minibuffer input. The remedy is simply to turn Icicle mode off, then on again.

Icicles User Options and Faces

There are many user options (user variables) and several faces that Icicles defines, and you can also use various standard Emacs user options, including IcompleteMode options, that control various aspects of completion.

Here is a screenshot from ‘list-faces-display’ that shows all of the Icicles faces, with their default appearances for a light background. Each of these faces is described below.

DrewsEmacsIciclesFaces

Here are screenshots of the Icicles and Customize submenus of the Emacs Options menu. Most of the items in the Icicles submenu let you modify specific Icicles options, which are described below. Those in the Customize submenu are Icicles operations for customizing anything – they are indicated by the prefix [Icy].

DrewsEmacsIciclesOptionsMenu

DrewsEmacsIciclesOptionsCustomizeMenu

One thing that can be important to understand is that if you customize an option, and if the default value of that option changes later in a more recent Icicles version, then your customization will preclude your taking advantage of any new features represented by that default option value.

This is important particularly for complex options such as `icicle-top-level-key-bindings’. Taking that option as an example, if Icicles later adds more commands with default key bindings then you will not see those bindings if you have a customized value of ‘icicle-top-level-key-bindings’. There is nothing wrong with that; I just want you to be aware of it.

In general, it can be a good idea to look at the latest change-log entry for icicles-opt.el in icicles-chg.el, to see what changes have been made. If you then want to take advantage of some change, you can use ‘M-x customize-option’ and visually compare your customized value with the new default value in icicles-opt.el, then edit your customized value as you like.


Option icicle-mode-hook

User option ‘icicle-mode-hook’ is a normal hook containing functions that are run after entering and exiting Icicle mode. This is ‘nil’, by default.


Option icicle-minibuffer-setup-hook

User option ‘icicle-minibuffer-setup-hook’ is a list of functions to be run at the end of minibuffer setup for Icicle mode. This is ‘nil’, by default.


Option icicle-update-input-hook

User option ‘icicle-update-input-hook’ is a list of functions to be run when minibuffer input is updated (typing or deleting). This is ‘nil’, by default.


Option icicle-no-match-hook

User option ‘icicle-no-match-hook’ is a list of functions to be run during completion (‘TAB’ or ‘S-TAB’) when there are no completion candidates that match the current input. This is ‘nil’, by default.


Case Sensitivity - Options completion-ignore-case, read-file-name-completion-ignore-case, read-buffer-completion-ignore-case, case-fold-search

The following standard user options control whether completion distinguishes between uppercase and lowercase letters:

In addition, you can toggle case-sensitivity at any time using ‘C-A’ (that is, ‘C-S-a’) in the minibuffer. This toggles ‘case-fold-search’ and ‘completion-ignore-case’. With a prefix argument, it also toggles ‘read-file-name-completion-ignore-case’ and ‘read-buffer-completion-ignore-case’.

More precisely, it toggles the default value of ‘case-fold-search’, and then it sets the other variables to the value of ‘case-fold-search’. Because the default value of ‘case-fold-search’ is changed, all buffers are affected. Note that because some Icicles commands bind one or more of these variables, toggling case-sensitivity during command execution will not necessarily toggle their global values.

You can tell whether completion is currently case-sensitive by looking at the Icicle minor mode lighter in the mode line, if ‘icicle-highlight-lighter-flag’ is non-‘nil’. If case-sensitive, then the lighter text (with or without the multi-command suffix `+’ and the multi-completion suffix `||’) is ‘Icy’; if not, it is ‘ICY’.


Option completion-ignored-extensions

See Icicles - File-Name Completion Tips


Options icicle-region-background, icicle-point-position-in-candidate, icicle-mark-position-in-candidate, icicle-change-region-background-flag

User options ‘icicle-region-background’, ‘icicle-point-position-in-candidate’, ‘icicle-mark-position-in-candidate’, and ‘icicle-change-region-background-flag’ are all used to define the region (the selected text) when cycling completion candidates. They are described below individually. The region is active when cycling, so you can easily delete it or replace it.

User option ‘icicle-point-position-in-candidate’ defines the minibuffer cursor position (point) while cycling candidate completions. By default, the cursor is placed at the end of the root being completed. You can instead place it at the root beginning or at the beginning or end of the complete minibuffer input. For file-name input, the beginning of minibuffer input starts after the directory name (which is inserted automatically).

Similarly, user option ‘icicle-mark-position-in-candidate’ defines the position of the mark; by default, it is at the end of the input. Together, these two options control the size and placement of the region in a flexible way. You can make the region include all of the input, only the root, from beginning to root, or from root to end. You can put the cursor at either end of the region. You can get rid of the region altogether, by making point and mark coincide (at any of the possible positions).

These screenshots show two of the sixteen possible position combinations of ‘icicle-point-position-in-candidate’ and ‘icicle-mark-position-in-candidate’. The first shows the default behavior:

The second shows point at the start of the input and mark at the end of the input. The position of point is indicated by the bar cursor; the position of mark is the other end of the cyan-colored region.

IciclesMinibufRegion1 IciclesMinibufRegion2

Because the region background color is often quite different from the frame background color (in order to have it stand out), it can be a bit hard to read the completion candidates when the region is highlighted in the minibuffer during input cycling. If user option ‘icicle-change-region-background-flag’ is non-‘nil’, however, then the region background is changed in the active minibuffer to a color that differs only slightly from the frame background, making it easier to read the completion candidates (see screenshots, above). The actual background color used is the value of ‘icicle-region-background’, which you can customize. (If you make this color the same as the frame background, then the region background is, in effect, invisible.)

The default value of ‘icicle-change-region-background-flag’ is determined by the current value of ‘delete-selection-mode’, that is, whether or not DeleteSelectionMode is enabled, when icicles.el is loaded. For this reason, if you use Delete Selection mode and you want the region background to change in the minibuffer, you should either turn on Delete Selection mode before loading icicles.el or explicitly customize ‘icicle-change-region-background-flag’ to non-‘nil’.


Option icicle-default-value

User option ‘icicle-default-value’ controls the treatment of a default value for minibuffer input. When the value is non-‘nil’ and the INITIAL-INPUT argument of minibuffer-reading functions is ‘nil’ or "", the DEFAULT-VALUE argument can be inserted into the minibuffer as the initial input.

For ‘completing-read’ and ‘read-file-name’, if the option value is ‘t’ then the default value is normally added to the prompt as a hint. However, for ‘read-file-name’, if option ‘insert-default-directory’ is non-‘nil’, then to avoid duplication:

Adding the default value to the prompt corresponds to the more or less conventional behavior of vanilla Emacs. But vanilla Emacs does not do this systematically for ‘completing-read’ (or for any of the input-reading functions). Instead, it hard-codes default values into prompts in the commands that call these functions.

By design, Icicles commands never add the default value to the prompt themselves. This includes Icicles versions of standard commands that might do so. Icicles instead tries to give you the choice, using option ‘icicle-default-value’.

Function ‘completing-read’ is the only input-reading function for which Icicles adds the default value to the prompt (for ‘icicle-default-value’ value ‘t’). Other such functions, like `(icicle-)read-from-minibuffer’ and `(icicle-)read-file-name’, treat empty input (just ‘RET’) specially — see their doc for details.

Non-‘nil’ and non-‘t’ means to automatically insert the default input value into the minibuffer as the initial value. I prefer to have it inserted, as I often use the default value (perhaps editing it). A value of ‘nil’ neither inserts the default value nor adds it to the prompt.

If the value is ‘t’ or ‘nil’, remember that you can always insert the default value manually using ‘M-n’. If the value is neither ‘t’ nor ‘nil’, you can always use ‘M-p’ to remove the default value from the minibuffer.

If you often want to use or edit the default value, then consider setting ‘icicle-default-value’ to non-‘nil’ and non-‘t’. If you rarely do so, then consider setting it to ‘nil’ or ‘t’.

A non-‘nil’, non-‘t’ value of ‘icicle-default-value’ controls also whether or not the initial value is preselected and where to leave the cursor: at the beginning or end of the value.

Preselecting the value can be useful in DeleteSelectionMode or PC Selection mode, because it makes it easy to replace that value by typing characters, or delete it by hitting ‘DEL’ (Backspace) or ‘C-d’ (Delete). However, all of the initial input is lost if you type or hit ‘C-d’ or ‘DEL’, which is inconvenient if you want to edit it only slightly. See Icicles - Inserting Text from Cursor.


Option icicle-default-in-prompt-format-function

If you use ‘t’ as the value of ‘icicle-default-value’ then you can use option ‘icicle-default-in-prompt-format-function’ to format the text that shows the (first) default value in the prompt. The option value is a function that accepts the default value (a string) and returns a string that is prepended to the first occurrence of “: ” in the prompt. This option has no effect unless ‘icicle-default-value’ is ‘t’.


Options icicle-thing-at-point-functions, icicle-default-thing-insertion

User options ‘icicle-thing-at-point-functions’ and ‘icicle-default-thing-insertion’ control the behavior of `M-.’ in the minibuffer, which grabs text from the current buffer and yanks it into the minibuffer. See Icicles - Inserting Text from Cursor and the doc string (‘C-h v’) of ‘icicle-thing-at-point-functions’ for more information.


Option icicle-comint-dynamic-complete-replacements

User option ‘icicle-comint-dynamic-complete-replacements’ specifies a list of function replacements for ‘icicle-comint-dynamic-complete’ to replace the functions in ‘comint-dynamic-complete-functions’. You can use this to provide Icicles completion for various modes that inherit from ComintMode. By default, it treats Comint mode and ShellMode.


Option icicle-input-string

User option ‘icicle-input-string’ is a regexp string that is inserted in the minibuffer when you use `C-=’. See Icicles - Inserting a Regexp from a Variable or Register.


Option icicle-Info-highlight-visited-nodes, Face icicle-historical-candidate-other

In buffer ‘*Completions*’ during completion for multi-command ‘icicle-Info-index’ (‘i’ in InfoMode), face ‘icicle-historical-candidate-other’ can be used to highlight index topics that refer to Info nodes that you have already visited. This highlighting is controlled by options ‘icicle-Info-highlight-visited-nodes’ and ‘icicle-highlight-historical-candidates-flag’. See Highlighting Index Topics for Visited Info Nodes.


Option icicle-highlight-historical-candidates-flag, Face icicle-historical-candidate

In buffer ‘*Completions*’, face ‘icicle-historical-candidate’ is used to highlight completion candidates that you have used (entered with ‘RET’) previously. This highlighting is controlled by user option ‘icicle-highlight-historical-candidates-flag’. You can toggle this option from the minibuffer at any time using ‘C-pause’. See Icicles - History Enhancements.


Option icicle-highlight-saved-candidates-flag, Face icicle-saved-candidate

In buffer ‘*Completions*’, face ‘icicle-saved-candidate’ is used to highlight completion candidates that you have saved (e.g., using `C-M->’). This highlighting is controlled by user option ‘icicle-highlight-saved-candidates-flag’. You can toggle this option from the minibuffer at any time using ‘S-pause’. See Saving and Retrieving Completion Candidates.


Faces icicle-current-candidate-highlight, icicle-common-match-highlight-Completions, icicle-annotation, icicle-match-highlight-Completions, icicle-match-highlight-minibuffer, icicle-complete-input

In buffer ‘*Completions*’, face ‘icicle-current-candidate-highlight’ highlights the current completion candidate, face ‘icicle-common-match-highlight-Completions’ highlights the expanded common match among all completions, and face ‘icicle-annotation’ is used for candidate annotations. Faces ‘icicle-match-highlight-Completions’ and ‘icicle-match-highlight-minibuffer’ highlight whatever your input matches, in buffer ‘*Completions*’ and in the minibuffer, respectively. In the minibuffer, face ‘icicle-complete-input’ highlights your input when it is complete. You can customize these, as well as the other Icicles faces.


Option icicle-touche-pas-aux-menus-flag

Non-‘nil’ user option ‘icicle-touche-pas-aux-menus-flag’ means that Icicles will not add menu items to menu bar menus, except for the Icicles and Minibuf menus. Default value ‘nil’ means that whenever a relevant menu already exists, Icicles items are added to it (when in Icicle mode). Put differently, non-‘nil’ means consolidate all Icicles menu items in a single Icicles menu.

For example, if ‘nil’ then item Delete File is added to the File menu; otherwise it is added to the Icicles menu.

The value of this option is used only when Icicle mode is initially established, so changing it has no effect after Icicles has been loaded. However, you can change it and save the new value, so that it will be used next time. See Icicles - Menus for more about the Icicles and Minibuf menus.


Option icicle-functions-to-redefine

User option ‘icicle-functions-to-redefine’ controls whether Icicles redefines some standard functions, enhancing them to use Icicles completion. You can specify which functions to redefine. The original function definitions are restored when you exit Icicle mode.


Option icicle-inhibit-advice-functions

Option ‘icicle-inhibit-advice-functions’ is a list of functions that Icicles redefines, and for which Icicle mode deactivates the advice. The advice for each is reactivated when you leave Icicle mode. Generally, it is a bad idea to use advice with functions that Icicles redefines, in particular minibuffer functions. If you want to allow some such advice or prohibit advice for additional functions, then customize this list.

Note: If you or a library you load advises one of these functions while you are in Icicle mode, then toggle Icicle mode twice, so that this option can have the proper effect.


Option icicle-widgets-to-redefine

Option ‘icicle-widgets-to-redefine’ is a list of widgets that Icicles redefines for Icicle mode. Widgets are Emacs objects used, in particular, by Customize. The default value is `(color file)’, meaning that the ‘color’ and ‘file’ widgets are redefined. They are redefined to allow Icicles completion on color and file-name fields.

With these redefinitions, when you edit a color or file-name field in Customize (in Icicle mode) ‘M-TAB’ performs Icicles completion. Initially, prefix completion is used, but you can then use apropos completion, progressive completion, and so on.

For file-name completion, the portion of the file name before point in the editing field is completed. By default, the rest of the field content, past point, is not deleted. If you use a prefix argument (i.e., ‘C-u M-TAB’) then the rest of the line is deleted.

For color completion, a prefix argument means to use the RGB value of the color, not its name, as the option value.

For color completion, if `icicle-WYSIWYG-Completions-flag’ is non-‘nil’ then completion is WYSIWYG. You can complete against the color name or its RGB value, or you can enter an RGB value with no name without completing. See function ‘icicle-widget-color-complete’ for more information.


Options icicle-top-level-when-sole-completion-delay, icicle-top-level-when-sole-completion-flag

Non-‘nil’ user option ‘icicle-top-level-when-sole-completion-flag’ means that whenever there is only one completion candidate that matches your input, that candidate is used immediately, without requiring you to hit ‘RET’ or ‘S-RET’.

When ‘icicle-top-level-when-sole-completion-flag’ is non-‘nil’, option ‘icicle-top-level-when-sole-completion-delay’ is the number of seconds Icicles waits, before returning to top level with the sole completion. (It has no effect if the flag is ‘nil’.) The delay gives you a chance to forestall acceptance of the sole completion: editing the completion (typing or deleting a character) before the delay expires prevents its automatic acceptance. The default value is 0 seconds (no delay).


Option icicle-top-level-key-bindings

User option ‘icicle-top-level-key-bindings’ specifies top-level commands and their bindings for Icicle mode. By default, this rebinds several standard Emacs keys (in Icicle mode only). For example, it substitutes ‘icicle-kill-buffer’ for ‘kill-buffer’ (binding it to whatever ‘kill-buffer’ is bound to globally). Top-level commands are commands that are not used only in the minibuffer. To change these bindings, customize ‘icicle-top-level-key-bindings’. If you do that, then you must exit and re-enter Icicle mode to ensure that the change takes effect. This is really necessary only if your changes would undefine a key.


Option icicle-minibuffer-key-bindings

User option ‘icicle-minibuffer-key-bindings’ specifies bindings for keys available during minibuffer input in Icicle mode. These bindings are in effect whether or not completion is available. This does not include keys concerned with completion, cycling, and help, which are covered by other user options. The value has the same form as for option `icicle-top-level-key-bindings’.


Option icicle-completion-key-bindings

User option ‘icicle-completion-key-bindings’ specifies keys to bind to various Icicles minibuffer commands that are used during completion. These are generally not commands that complete your minibuffer input, but commands that you use to edit that input or act on it in different ways. This option value has the same form as for option `icicle-top-level-key-bindings’.


Option icicle-buffer-candidate-key-bindings

User option ‘icicle-buffer-candidate-key-bindings’ specifies bindings for additional keys available during completion of buffer-name candidates. The default value of the option provides keys that filter (narrow) the set of available candidates.


Option icicle-completion-list-key-bindings

User option ‘icicle-completion-list-key-bindings’ specifies key bindings for buffer ‘*Completions*’. The value has the same form as for option `icicle-top-level-key-bindings’.


Option icicle-candidate-help-keys

User option ‘icicle-candidate-help-keys’ specifies the keys that display help about the current completion candidate. The default values are ‘C-M-RET’ (‘C-M-return’), ‘C-M-help’, ‘C-M-f1’, ‘C-help’, and ‘C-f1’.


Option icicle-candidate-action-keys

User option ‘icicle-candidate-action-keys’ specifies the keys that act on the current completion candidate. The default value is ‘C-RET’ (‘C-return’).


Options icicle-(apropos|prefix)-cycle-(previous|next)(help|(-alt)-action)-keys

The following user options specify the keys to use for mode-specific completion-candidate cycling The default bindings are in parentheses.


Options icicle-modal-cycle-(down|up)(-help|(-alt)-action)-keys

The following user options specify the keys to use for cycling candidates according to the current completion mode. The default bindings are in parentheses.

The completion mode, and hence the behavior of these keys, is changed only when you hit ‘TAB’ or ‘S-TAB’ during completion: the mode is prefix completion after ‘TAB’ and apropos completion after ‘S-TAB’.

Note: If your customizations of the modal and non-modal cycling keys conflict, the non-modal values win. For example, if you define both ‘icicle-modal-cycle-up-keys’ and ‘icicle-prefix-cycle-previous-keys’ as the list ([up]), then the ‘up’ key will perform prefix cycling, not modal cycling.


Option icicle-default-cycling-mode

User option ‘icicle-default-cycling-mode’ determines the completion mode to be used before you hit ‘TAB’ or ‘S-TAB’. This affects only modal cycling – e.g. using keys such as ‘down’ and ‘C-down’. Values:

For example, if the value is ‘apropos’ then you can immediately cycle apropos completions without first hitting ‘S-TAB’.

Once you have used ‘TAB’ or ‘S-TAB’, the only way to traverse the input history is to use ‘M-p’ and ‘M-n’.


Option icicle-use-~-for-home-dir-flag

See Icicles - File-Name Completion Tips


Option icicle-word-completion-keys

User option ‘icicle-word-completion-keys’ is a list of keys to use for word completion. By default, the only such key is ‘M-SPC’.


Options icicle-apropos-complete-no-display and `icicle-prefix-complete-no-display-keys'

User option ‘icicle-apropos-complete-no-display-keys’ is a list of keys to bind to ‘icicle-apropos-complete-no-display’. By default, these keys are ‘C-M-S-tab’ and ‘C-M-S-iso-lefttab’, which together implement ‘C-M-S-TAB’. Similarly, ‘icicle-prefix-complete-no-display-keys’ is the list of keys for ‘icicle-prefix-complete-no-display’. By default, the only such key is ‘C-M-tab’.


Option icicle-prefix-complete-keys

Option ‘icicle-prefix-complete-keys’ is the list of keys for ‘icicle-prefix-complete’. By default, these keys are ‘tab’ and ‘C-i’, which together implement ‘TAB’.


Option icicle-apropos-complete-keys

Option ‘icicle-apropos-complete-keys’ is the list of keys to bind to ‘icicle-apropos-complete’. By default, these keys are ‘S-tab’ and ‘S-iso-lefttab’, which together implement ‘S-TAB’. (In Emacs 22 and later, ‘backtab’ is the canonical key that represents both ‘S-tab’ and ‘S-iso-lefttab’, so that is used in the default value.)


Option icicle-key-complete-keys

Option ‘icicle-key-complete-keys’ is the list of keys to bind to ‘icicle-complete-keys’. By default, this is the singleton list ([backtab]). The ‘backtab’ key is the canonical key that represents both ‘S-tab’ and ‘S-iso-lefttab’. All three of these keys implement ‘S-TAB’.


Option icicle-key-complete-keys-for-minibuffer

Option ‘icicle-key-complete-keys-for-minibuffer’ is the list of keys that Icicles binds to ‘icicle-complete-keys’ in the minibuffer keymaps. By default, this is the list ([M-backtab] [ESC backtab]), which means ‘M-S-TAB’ and ‘ESC S-TAB’ (essentially equivalent to ‘M-S-TAB’). ‘S-TAB’ itself is of course used (by default) for apropos completion of your minibuffer input, so it cannot also be used for key completion in the minibuffer. If your window manager steals ‘M-S-TAB’ then try ‘ESC S-TAB’ or customize this option to choose another key.


Option icicle-complete-keys-ignored-prefix-keys

Option ‘icicle-complete-keys-ignored-prefix-keys’ is a list of prefix keys to be ignored by ‘icicle-complete-keys’ (‘S-TAB’). What this really means is that you can bind ‘icicle-complete-keys’ to a key sequence that uses one of these prefix keys, and when you invoke it that way it acts as if invoked at top level. Otherwise, it would show you only the keys bound on that prefix key. This gives you a way to invoke top-level key completion from a key sequence that uses a prefix key.


Option icicle-isearch-complete-keys

Option ‘icicle-isearch-complete-keys’ is the list of keys for ‘icicle-isearch-complete’. By default, these keys are ‘M-TAB’, ‘ESC TAB’ and ‘C-M-TAB’.


icicle-isearch-history-insert-keys

Option ‘icicle-isearch-history-insert-keys’ is the list of keys for ‘icicle-isearch-history’. By default, the list contains only ‘M-o’.


Options icicle-read+insert-file-name-keys, icicle-completing-read+insert-keys

Option `icicle-read+insert-file-name-keys’ is the list of keys for invoking file-name completion on demand. By default, ‘C-M-S-f’ is the only such key. Option `icicle-completing-read+insert-keys’ is the list of keys for invoking non file-name completion on demand. By default, ‘C-M-S-c’ is the only such key. See Icicles - Completion On Demand.


Option icicle-act-before-cycle-flag

User option ‘icicle-act-before-cycle-flag’ ‘nil’ means that keys such as ‘C-next’, which combine candidate action and cycling, cycle to the next (or previous) candidate and act on it. Non-‘nil’ means they act on the current candidate and then cycle to the next (or previous) candidate. When the value is ‘nil’, you can think of ‘C-next’ as an operation on the next candidate. When the value is non-‘nil’, you can think of ‘C-next’ as an operation on the current candidate, which ends by making the next candidate current. Similarly for the other cycling keys that act, alternative-act, or show help on a candidate The default value is ‘nil’. See also option `icicle-use-C-for-actions-flag’, which changes the keys affected by ‘icicle-act-before-cycle-flag’.


Option icicle-use-C-for-actions-flag

If option ‘icicle-use-C-for-actions-flag’ is ‘nil’, then the keys that cycle candidates are swapped with the keys that both cycle and act on a candidate. You can then use ‘down’, ‘up’, ‘next’, ‘prior’, ‘end’, and ‘home’ to both cycle and act, and ‘C-down’, ‘C-up’, ‘C-next’, ‘C-prior’, ‘C-end’, and ‘C-home’ to merely cycle, without acting (e.g. navigating). The option has no effect on other keys. You can toggle this option at any time using ‘M-g’ (‘icicle-toggle-C-for-actions’) in the minibuffer. See More about Multi-Commands.

The keys mentioned here are the default bindings. The actual keys swapped are those defined by these user options:


Option icicle-find-file-expand-directory-flag

Non-‘nil’ option ‘icicle-find-file-expand-directory-flag’ prevents the choice of a directory-name candidate using ‘RET’ or ‘mouse-2’ during file-name completion from opening Dired on the directory. Instead, Icicles cycles into the directory, presenting its contents as the completion candidates. It thus makes ‘RET’ behave like ‘C-M-/’. The option has no such effect on multi-command candidate-action keys such as ‘C-RET’ and ‘C-mouse-2’. You can toggle this option using ‘C-x /’.


Option icicle-TAB/S-TAB-only-completes-flag

Non-‘nil’ option ‘icicle-TAB/S-TAB-only-completes-flag’ inhibits ‘TAB’ and ‘S-TAB’ (actually the keys that are the values of options ‘icicle-prefix-complete-keys’ and ‘icicle-apropos-complete-keys’) from also cycling candidates.


Option icicle-TAB-shows-candidates-flag

Non-‘nil’ user option ‘icicle-TAB-shows-candidates-flag’ means that hitting ‘TAB’ for completion immediately shows the completion candidates in buffer ‘*Completions*’. If ‘nil’, then candidates are shown only after ‘TAB’ is hit a second time, which is the standard Emacs behavior. The default value is ‘t’. (Actually, the concerned keys are those defined by option `icicle-prefix-complete-keys’, not necessarily ‘TAB’.)


Option `icicle-max-candidates'

Non-‘nil’ option ‘icicle-max-candidates’ means truncate the list of completion candidates to at most this many. If you use library doremi.el then you can use `C-x #’ during completion to increment or decrement the option value using the vertical arrow keys or the mouse wheel. A numeric prefix argument for `C-x #’ sets the increment size. A plain prefix argument (‘C-u’) resets ‘icicle-max-candidates’ to ‘nil’, meaning no truncation.


Option icicle-expand-input-to-common-match

User option ‘icicle-expand-input-to-common-match’ controls whether completion expands your minibuffer input to (typically) the longest common substring common to all completion candidates and that matches your (complete) input pattern. The option controls whether and when such expansion takes place. The possible values are:

As the value increases there are thus more contexts in which your input can be expanded to the common match.

You can toggle the value of this option at any time using `C-"’ in the minibuffer. This in fact swaps the values of this option and option `icicle-expand-input-to-common-match-alt’. That is the only purpose of the latter option: to let you go switch ‘icicle-expand-input-to-common-match’ back and forth between two values.

You can cycle the value of ‘icicle-expand-input-to-common-match’ among all its possible values using `C-M-"’ in the minibuffer. Together with `C-"’, this also lets you change the value of ‘icicle-expand-input-to-common-match-alt’: Use `C-M-"’ to cycle to the value you want as the alternative, then use `C-"’ to swap. Then use `C-M-"’ to cycle to the value you want for ‘icicle-expand-input-to-common-match’.

Input expansion replaces your input in the minibuffer. If you want to edit your original, pre-expansion input, use ‘C-l’. If you are also cycling among candidates then you might need to hit ‘C-l’ twice. One reason you might want to set ‘icicle-expand-input-to-common-match’ to a value other than 4 is if you want to always work with a regexp in the minibuffer when you use apropos completion. (With a value of 4 the regexp is replaced automatically by the match expansion.)

See Also:


Option icicle-hide-common-match-in-Completions-flag

Non-‘nil’ user option ‘icicle-hide-common-match-in-Completions-flag’ hides, in buffer ‘*Completions*’, the common match for your current input from each candidate. You can toggle this anytime during completion using `C-x .’ (no prefix argument), which is bound to command ‘icicle-toggle-hiding-common-match’. The common match used is governed by option `icicle-expand-input-to-common-match’.


icicle-hide-non-matching-lines-flag

Non-‘nil’ option ‘icicle-hide-non-matching-lines-flag’ hides, in buffer ‘*Completions*’, all lines in multi-line candidates that do not match your current minibuffer input. In Emacs 22+, consecutive such lines are elided as `...’. You can toggle this option anytime during completion using `C-u C-x .’, which is bound to command ‘icicle-toggle-hiding-non-matching-lines’.

Hiding non-matching lines can be especially useful when candidates are large (many lines), such as full function definitions (e.g., from ‘icicle-imenu-full’).


Option icicle-show-Completions-initially-flag

User option ‘icicle-show-Completions-initially-flag’ controls whether or not buffer ‘*Completions*’ is shown initially, without your needing to hit ‘TAB’ or ‘S-TAB’ to show it. However, if you type something before `icicle-incremental-completion-delay’, then display is inhibited. The default value is ‘nil’, meaning that ‘*Completions*’ is not shown until you hit ‘TAB’ or ‘S-TAB’. More typical than setting this option to non-‘nil’ globally is to bind it to non-‘nil’ in EmacsLisp code, to display ‘*Completions*’ as a menu. For example, pass a non-‘nil’ binding to ‘icicle-define-command’ to create a command that displays a multiple-choice menu.

For an alternative but similar behavior to using non-‘nil’ for ‘icicle-show-Completions-initially-flag’, you can set option `icicle-incremental-completion’ to a value that is neither ‘nil’ nor ‘t’. That displays ‘*Completions*’ as soon as you type or delete input, but not initially.


Option icicle-incremental-completion

User option ‘icicle-incremental-completion-flag’ controls whether or not ‘*Completions*’ is updated incrementally (icompletion) as you type. You can cycle the option among its three possible values at any time using `C-#’. For more information, see Icicles - Icompletion.

Note: Several tripping (navigating) commands, including Icicles search commands, bind option ‘icicle-incremental-completion’ to ‘always’, because I think you typically want to start them out with incremental completion turned on. Remember that you can use `C-#’ (once or twice) to turn incremental completion off.


Options icicle-incremental-completion-delay, icicle-incremental-completion-threshold

User options ‘icicle-incremental-completion-delay’ and ‘icicle-incremental-completion-threshold’ together cause a delay before incremental completion takes effect. See Icicles - Icompletion.


Option icicle-sorting-max-candidates

User option ‘icicle-sorting-max-candidates’ automatically toggles candidate sorting off and on, depending on the current number of candidates. Set it to ‘nil’ to turn off such toggling. Set it to a larger or smaller maximum number of candidates to reduce or increase its effect. See also Icicles - Sorting Candidates.


Option icicle-icomplete-mode-max-candidates

User option ‘icicle-icomplete-mode-max-candidates’ automatically toggles Icomplete mode off and on, depending on the current number of candidates. Set it to ‘nil’ to turn off such toggling. Set it to a larger or smaller maximum number of candidates to reduce or increase its effect. This option has no effect for Emacs versions prior to Emacs 23. See also Using Icicles with Icomplete Mode .


Option icicle-Completions-display-min-input-chars

User option ‘icicle-Completions-display-min-input-chars’ is the minimum number of input characters that allow buffer ‘*Completions*’ to remain displayed. By default, this is zero (0), meaning that any number of input characters, even none, allows ‘*Completions*’ to remain displayed. If you use incremental completion (see options `icicle-incremental-completion-*’), and you are bothered by ‘*Completions*’ being automatically updated when, for instance, you empty the minibuffer, then you might want to set this option to, say, 1 or 2. With a value of 2, for instance, whenever the minibuffer input has less than 2 characters, incremental completion will remove the ‘*Completions*’ window. You can also remove the ‘*Completions*’ window at any time using ‘C-x 0’ in the minibuffer.


Option icicle-keep-Completions-for-sole-dir

Option ‘icicle-keep-Completions-for-sole-dir’ controls what happens during (non-absolute) file-name completion when the only match for your input is a directory name. If the value is ‘nil’ then remove the ‘*Completions*’ window. If it is the symbol ‘pop-up’ then update ‘*Completions*’ unconditionally to show the sole candidate — show ‘*Completions*’ if it was not yet showing. If it is any other non-‘nil’ value then update ‘*Completions*’ if it is showing, and do nothing otherwise. The default value is ‘t’, giving this update-if-shown-else-remove behavior.


Option icicle-show-Completions-help-flag, Faces icicle-Completions-instruction-1 and -2

Non-‘nil’ option ‘icicle-show-Completions-help-flag’ means display help (instructions) at the top of the buffer that shows completions (typically ‘*Completions*’). These instructions are shown in faces ‘icicle-Completions-instruction-1’ and ‘icicle-Completions-instruction-2’. If ‘nil’, the completion candidates are shown alone (no help text), but if there are no candidates then text stating that fact is printed in the buffer.


Option icicle-help-in-mode-line-delay

Option ‘icicle-help-in-mode-line-delay’ is the number of seconds to display help on individual completion candidates in the mode line as you cycle or your input is completed. The mode-line that is used is that of buffer ‘*Completions*’, if it is displayed, or the current buffer, otherwise. Typically, this mode-line candidate help is the first line of a doc string, but alternative help is available.

Regardless of the option value, a user event (e.g. a key press) always interrupts (terminates) this help display.

Note that ‘post-command-hook’ actions do not take place until this display is finished. For example, if the help is shown because your input is complete, then Icomplete will not show additional candidates (e.g. with the same input as a prefix) until the mode-line help has finished. This is because Icomplete display is a ‘post-command-hook’ action.


Face icicle-mode-line-help

Face ‘icicle-mode-line-help’ is used to highlight Icicles help shown in the mode line. This includes that controlled by option `icicle-help-in-mode-line-delay’ and the indication in ‘*Completions*’ of the total number of matching candidates.


Option icicle-Completions-mouse-3-menu-entries

User option ‘icicle-Completions-mouse-3-menu-entries’ defines the contextual menu that is popped up when you click ‘C-mouse-3’ on a candidate in ‘*Completions*’. As an aid to customizing it, refer to any of the constants ‘icicle-Completions-*’ that define its submenus. The submenu definitions are easier to understand in the source code (icicles-opt.el), because Customize does not pretty-print them. You can see screenshots of the default menu and its submenus here.


Option icicle-move-Completions-frame

Non-‘nil’ user option ‘icicle-move-Completions-frame’ means that ‘icicle-candidate-action’ moves the frame showing buffer ‘*Completions*’ to the edge of the display, out of the way of other frames. The possible non-‘nil’ values are ‘right’ and ‘left’, specifying the display edge to use. This option can be useful if you use one-buffer-per-frame (non-‘nil’ ‘pop-up-frames’). In that case, I recommend that you also try my library oneonone.el. See Icicles - pop-up-frames on MS Windows for more advice about non-‘nil’ ‘pop-up-frames’.


Option icicle-Completions-window-max-height

User option ‘icicle-Completions-window-max-height’ is the maximum height of the ‘*Completions*’ window, in lines. The window is fit to the buffer size, with this as maximum height. This is not used if ‘*Completions*’ is a special display buffer with its own frame, and it is not used in Emacs releases prior to 21.


Option icicle-Completions-text-scale-decrease

Starting with Emacs 23, you can use option ‘icicle-Completions-text-scale-decrease’ to change the size of the text used in buffer ‘*Completions*’.


Option icicle-candidate-width-factor

User option ‘icicle-candidate-width-factor’ controls how many columns of completion candidates are displayed in ‘*Completions*’. The widest current candidate is scaled by this percentage, and the window width is divided by that figure. Other things are taken into account also, but this gives you a way to tweak the number of columns: the larger this number, the fewer the columns.

If you use DoReMi (library doremi.el), then you can modify ‘icicle-candidate-width-factor’ incrementally during completion, seeing the effect as it changes. Use ‘C-x w’ from the minibuffer, then use the ‘right’ and ‘left’ arrow keys or the mouse wheel to increment and decrement the value. You can at the same time use the ‘up’ and ‘down’ keys to adjust the value of `icicle-inter-candidates-min-spaces’. WYSIWYG.


Option icicle-inter-candidates-min-spaces

User option ‘icicle-inter-candidates-min-spaces’ is the minimum number of spaces between candidates displayed in ‘*Completions*’. The default value is one space.

If you use DoReMi (library doremi.el), then you can modify ‘icicle-inter-candidates-min-spaces’ incrementally during completion, seeing the effect as it changes. Use `C-x |’ from the minibuffer, then use the ‘up’ and ‘down’ arrow keys or the mouse wheel to increment and decrement the value. You can at the same time use the ‘left’ and ‘right’ keys to adjust the value of `icicle-candidate-width-factor’. WYSIWYG.


Option icicle-Completions-max-columns

Option ‘icicle-Completions-max-columns’ imposes a maximum number of columns for the ‘*Completions*’ display, thus preventing Icicles from automatically calculating the number of columns. It is available in case you really want to do that, but I recommend that you leave the value of this option ‘nil’ and you use only options `icicle-inter-candidates-min-spaces and `icicle-candidate-width-factor to control columns and candidate spacing.


Option icicle-image-files-in-Completions

Non-‘nil’ option ‘icicle-image-files-in-Completions’ means that thumbnail images are shown in ‘*Completions*’ for candidates that are either (relative or absolute) names of image files or names of image-file bookmarks (see Bookmark+). The default value is ‘t’. If the value is ‘image-only’, then only the thumbnail images are shown. If it is otherwise non-‘nil’ then the file names are also shown. You can cycle the option value using ‘C-x t’ in the minibuffer at any time during completion. This feature is available starting with Emacs 22.


Option icicle-image-preview-in-tooltip

Non-‘nil’ option ‘icicle-image-preview-in-tooltip’ means that if ‘tooltip-mode’ is on then passing the mouse over an image-file candidate in ‘*Completions*’ can pop up a tooltip showing a preview of the image. If the value is ‘full’ then a full-size image is shown. If the value is a positive integer then a thumbnail image of that size is shown.

However, thumbnail tooltips are not shown if thumbnails are already shown in ‘*Completions*’, that is, if ‘icicle-image-files-in-Completions’ is non-‘nil’ and ‘icicle-image-preview-in-tooltip’ is not ‘full’.


Option icicle-completions-format

Option ‘icicle-completions-format’ controls whether candidates displayed in ‘*Completions*’ are laid out horizontally (the default) or vertically. Set the value to ‘vertical’ for the latter. Starting with Emacs 23.2, you can just use the vanilla option ‘completions-format’ for this, if you want the same type of layout with Icicle mode turned on or off.

Icicles always displays multi-line candidates in a single column, for readability. When this is the case, the completions format (horizontal or vertical) makes no difference – the effect is the same. (Icicles also inserts an empty line after each multi-line candidate, for readability.)

You can toggle the completions layout between horizontal and vertical at any time during completion, using `C-M-^’.


Option icicle-menu-items-to-history-flag

If option ‘icicle-menu-items-to-history-flag’ is non-‘nil’ (the default), then commands that you invoke using the menu bar menu are included in the command history for ‘M-x’.


Option icicle-populate-interactive-history-flag

Non-‘nil’ option ‘icicle-populate-interactive-history-flag’ means that any interactive use of a command causes it to be added to the history ‘icicle-interactive-history’. You can access this history by using ‘C-M-pause’ during completion. Be aware that addition of all interactive invocations to this history can slow Emacs down. (This option is only available starting with Emacs 23.)


Option icicle-sort-comparer

User option ‘icicle-sort-comparer’ controls the order of completion candidates during cyclingand in buffer ‘*Completions*’. If ‘nil’, then no sorting is done. If non-‘nil’, then the value must be a string-comparison function – the function is passed to the standard function ‘sort’ to do the sorting. The default value for ‘icicle-sort-comparer’ is ‘icicle-case-string-less-p’, which sorts alphabetically, possibly ignoring letter case. During completion, you can toggle sorting using `C-,’. If you are an Emacs-Lisp programmer and you write new commands using Icicles functionalities, you can bind this variable temporarily to any sort function you need. See Icicles - Sorting Candidates.


Option icicle-alternative-sort-comparer

User option ‘icicle-alternative-sort-comparer’ is an alternative to `icicle-sort-comparer’, providing a different sort order. By default, it is ‘icicle-historical-alphabetic-p’, a function that sorts previously used completion candidates before candidates that have not yet been used, and sorts alphabetically within each of these groups of candidates. In other words, it places inputs that you have used previously at the top of buffer ‘*Completions*’ and makes them available for completion first. During completion, you can toggle normal and alternative sorting using `M-,’. See also `toggle-alternative-sorting’ and Icicles - Sorting Candidates.


Option icicle-change-sort-order-completion

User option ‘icicle-change-sort-order-completion’ specifies whether `C-,’ and `M-,’ cycle among available sort orders or they let you choose a sort order using Icicles completion.

The default value is 7, meaning cycle to the next order if there are no more than 7 sort orders currently available, but use completion to choose a sort order if there more than 7. An option value of ‘nil’ means always cycle, and a non-integer, non-‘nil’ value means always complete.

However, you can override the current option setting at any time by using a plain prefix argument: `C-u C-,’ or `C-u M-,’. See Icicles - Sorting Candidates.


Option icicle-sort-orders-alist

User option ‘icicle-sort-orders-alist’ is an alist of possible sort orders for user to choose from using `C-,’ or `M-,’. See Icicles - Sorting Candidates.


Option icicle-transform-function

The value of user option ‘icicle-transform-function’ is a function that is applied to the list of completion candidates, to transform them before they are presented to the user. If ‘nil’, then no transformation is done. The default transformation is to remove duplicate candidates, when transformation is active, but the default value of this option is ‘nil’. You can toggle transformation at any time using command ‘icicle-toggle-transformation’, bound to `C-$’ in the minibuffer. Although this is a user option, you probably do not want to change its value by customizing it. Icicles commands already “do the right thing” when it comes to candidate transformation.

The value of this option can be changed by program locally, for use in particular contexts. For example, when you use ‘M-s M-s M-s’ or `C-c `’ (‘icicle-search-generic’) in a ‘*shell*’ buffer, Icicles uses this variable with a value of ‘icicle-remove-duplicates’, to remove duplicate shell commands from your input history list. Lisp programmers can use this variable to transform the list of candidates in any way they like. A typical use is to remove duplicates, by binding it to ‘icicle-remove-duplicates’ or ‘icicle-remove-dups-if-extras’.


Options icicle-require-match-flag, icicle-buffer-require-match-flag

User options ‘icicle-require-match-flag’, ‘icicle-buffer-require-match-flag’, and ‘icicle-file-require-match-flag’ let you override the value of the ‘REQUIRE-MATCH’ argument provided to ‘completing-read’ or ‘read-file-name’. They are provided mainly for use (binding) in ‘icicle-define-command’ and ‘icicle-define-file-command’, but you may also use them globally, if you wish. A typical use is made in the definition of command ‘icicle-buffer’: ‘icicle-buffer-require-match-flag’ is used to bind ‘icicle-require-match-flag’, so that you can, for example, match only existing buffers and be able to match on partial input without explicitly completing (hitting ‘TAB’ or ‘S-TAB’). Simply set the option to ‘partial-match-ok’ to get this behavior. To apropos-complete and exit the minibuffer, use ‘S-RET’ instead of ‘RET’. See Icicles - S-RET.


Option icicle-buffer-ignore-space-prefix-flag

Non-‘nil’ user option ‘icicle-buffer-ignore-space-prefix-flag’ means to ignore buffer-name completion candidates that start with a space. You can toggle ‘icicle-buffer-ignore-space-prefix-flag’ using `M-_’ in the minibuffer (except during ‘icicle-search’).


Option icicle-test-for-remote-files-flag

Non-‘nil’ user option ‘icicle-test-for-remote-files-flag’ means that Icicles tests for remote file names; ‘nil’ means that it does not. You can toggle this using `C-^’ in the minibuffer (except during Icicles search). Turning off remote file-name testing means that you cannot use remote files with Tramp; it disables Tramp’s remote file-name handling and completion. This can, for local files, slightly speed up incremental completion and the highlighting of the part of your current input that does not complete (see `icicle-highlight-input-completion-failure’).


Option icicle-network-drive-means-remote-flag

Non-‘nil’ user option ‘icicle-network-drive-means-remote-flag’ means that a file on a mapped MS Windows network drive is considered remote. This has an effect on things like incremental completion. You can toggle this option anytime during completion using `C-x :’.


Option icicle-regexp-quote-flag

Non-‘nil’ user option ‘icicle-regexp-quote-flag’ reduces apropos completion to simple substring completion and Icicles regexp search to literal search. Regexp special characters are no longer recognized as special in this case; they simply match themselves. You probably do not want to customize this option. Instead, you can toggle it at any time using `C-`’ in the minibuffer.


Options icicle-command-abbrev-match-all-parts-flag, icicle-command-abbrev-priority-flag, icicle-command-abbrev-alist

User options ‘icicle-command-abbrev-match-all-parts-flag’, ‘icicle-command-abbrev-priority-flag’, and ‘icicle-command-abbrev-alist’ control the behavior of multi-command ‘icicle-command-abbrev’ (‘M-ESC C-x’, aka ‘ESC ESC C-x’). The first option determines whether an abbreviation must match all parts of a command name. The second controls whether command names or abbreviations take precedence in case of conflict. The third is the persistent list of your command abbreviations.


Options icicle-S-TAB-completion-methods-alist and icicle-TAB-completion-methods

User options ‘icicle-S-TAB-completion-methods-alist’ and ‘icicle-TAB-completion-methods’ control which completion method is used by ‘S-TAB’ and ‘TAB’, respectively, to complete your input. By default, the first method in each list is used for matching. You can use `M-(’ and `C-(’ (commands ‘icicle-next-S-TAB-completion-method’ and ‘icicle-next-TAB-completion-method’) in the minibuffer to cycle among the ‘S-TAB’ and ‘TAB’ methods. See Icicles - Completion Methods and Styles.

For fuzzy completion (choice ‘fuzzy’ when cycling with `C-(’), ‘TAB’ completes non-filename input using fuzzy prefix matching as defined in library fuzzy-match.el. See the Commentary in fuzzy-match.el for details about fuzzy matching. Fuzzy completion is not available for file-name completion; it is always case-sensitive; leading spaces are taken into account; and completion candidates are always sorted by decreasing fuzzy match strength. In other words, fuzzy completion is not affected by ‘C-A’, `M-_’, or `C-,’.


Options icicle-S-TAB-completion-methods-per-command and icicle-TAB-completion-methods-per-command

User options ‘icicle-S-TAB-completion-methods-per-command’ and ‘icicle-TAB-completion-methods-per-command’ provide per-command control of the completion methods available when you cycle using `C-(’ and `M-(’. Use them if you want to specify which methods are available for particular commands that read input with completion.


Option icicle-completion-style-sets

User option ‘icicle-completion-style-sets’ (for Emacs 23 or later) is the set of ‘completion-styles’ values that can be used when ‘TAB’ completion method is ‘vanilla’. During completion you can use `C-M-(’ to cycle to the next the style set. You can use command ‘icicle-choose-completion-style-set’ anytime to choose the default style set and set option ‘completing-styles’ to it. With a prefix argument, the command also saves the new ‘completing-styles’ value.


Option icicle-levenshtein-distance

User option ‘icicle-levenshtein-distance’ is the Levenshtein distance allowed for strings to be considered as matching during N-off completion. This means that two strings match if they differ by at most this many character operations (insertion, deletion, replacement). This option is used only if you have library levenshtein.el. See Icicles - Completion Methods and Styles.


Option icicle-swank-timeout

User option ‘icicle-swank-timeout’ is the maximumum number of milliseconds that can elapse before swank (fuzzy symbol) completion gives up. If you use DoReMi (library doremi.el) then you can use multi-command ‘icicle-increment-option’ anytime to change the option value incrementally. See Swank (Fuzzy Symbol) Completion.


Option icicle-swank-prefix-length

User option ‘icicle-swank-prefix-length’ is the minimum number of characters that must match, for swank completion. If you use DoReMi (library doremi.el) then you can use multi-command ‘icicle-increment-option’ anytime to change the option value incrementally. See Swank (Fuzzy Symbol) Completion.


Faces icicle-search-main-regexp-current, icicle-search-main-regexp-others, icicle-search-current-input, icicle-search-context-level-1 to 8

Top-level command ‘icicle-search’ uses several faces to highlight found text that matches your input. Faces ‘icicle-search-main-regexp-current’ and ‘icicle-search-main-regexp-others’ highlight what your search-context regexp (entered with ‘RET’) matches. The former highlights the current search context; the latter highlights all other search contexts.

Face ‘icicle-search-current-input’ highlights what your current input matches (typically another regexp); that is, it highlights a match within a search context. Faces ‘icicle-search-context-level-1’ through ‘icicle-search-context-level-8’ highlight the first eight regexp subgroup matches, within a search context. This highlighting is done whenever `icicle-search-highlight-context-levels-flag’ is non-‘nil’ and the search context corresponds to the entire regexp. See Icicles - Search Commands, Overview.


Option icicle-search-highlight-context-levels-flag

User option ‘icicle-search-highlight-context-levels-flag’ controls highlighting of regexp subgroup matches within the search context. Non-‘nil’ (the default value) means highlight them. See Icicles - Search Commands, Overview.


Option icicle-search-highlight-threshold

User option ‘icicle-search-highlight-threshold’ controls highlighting with face `icicle-search-main-regexp-others’: this many matches, maximum, are highlighted. If ‘t’ then there is no maximum (no limit). If zero, then only the current match is highlighted. See Icicles - Search Commands, Overview.


Option icicle-search-highlight-all-current-flag

Non-‘nil’ user option ‘icicle-search-highlight-all-current-flag’ means highlight what your current input matches inside all main search hits at the same time. If `icicle-expand-input-to-common-match’ is 3 or 4 (which means your input can be automatically prefix-expanded or apropos-expanded, respectively), then what is highlighted for each input match is the expanded common match among all input matches throughout the search area. Otherwise, only the exact input match is highlighted.

The default value of ‘icicle-search-highlight-all-current-flag’ is ‘nil’, because non-‘nil’ can impact performance negatively if there are many search contexts – the highlighting is updated with each input change. You can toggle the value at any time using command ‘icicle-toggle-highlight-all-current’, bound to `C-^’ in the minibuffer during Icicles search. See Icicles - Search Commands, Overview.


Option icicle-search-replace-common-match-flag

If, in addition to `icicle-expand-input-to-common-match’ causing your input to be expanded and `icicle-search-highlight-all-current-flag’ being non-‘nil’, option ‘icicle-search-replace-common-match-flag’ is also non-‘nil’, then a search replacement replaces the expanded common match. Otherwise, it replaces only the exact match. You can toggle ‘icicle-search-replace-common-match-flag’ at any time using `M-;’ in the minibuffer.


Option icicle-search-cleanup-flag

Non-‘nil’ user option ‘icicle-search-cleanup-flag’ means that ‘icicle-search’ highlighting is removed after the search. This is the default behavior. If you set this to ‘nil’ then you can remove search highlighting manually later using command ‘icicle-search-highlight-cleanup’. You can toggle this search highlight removal at any time using command ‘icicle-toggle-search-cleanup’, which is bound to `C-.’ in the minibuffer during Icicles search.

One use of ‘nil’ ‘icicle-search-cleanup-flag’ is to highlight regexp matches throughout a region or buffer (or multiple files or…). In that capacity, Icicles search functions act like some of the highlighting commands in my library highlight.el (see HighLight). Note that when ‘icicle-search-cleanup-flag’ is ‘nil’, all Icicles search highlighting remains: last-visited search context, other context matches, current-input matches, and even regexp subgroups. The faces for these are, respectively:


Option icicle-search-whole-word-flag

Non-‘nil’ user option ‘icicle-search-whole-word-flag’ means that whole-word search is done. You can use ‘M-q’ while searching to toggle this option; the newvalue takes effect for the next complete search.

Whole-word searching here means that matches can contain embedded strings of non word-constituent chars (they are skipped over, when matching, included in the match), and any leading or trailing word-constituent chars in the search string are dropped (ignored for matching, not included in the match). This means, for instance, that you can match ‘foo-bar’ as a word, even in contexts (such as EmacsLisp) where ‘-’ is not a word-constituent character. Similarly, you can include embedded whitespace in a “word”, e.g., ‘foo bar’.

See also Icicles - Search Commands, Overview.


Option icicle-search-replace-whole-candidate-flag

If user option ‘icicle-search-replace-whole-candidate-flag’ is ‘nil’, then whatever matches your current input is replaced, within the current search context, when you perform replacement during Icicles searching (e.g. ‘S-C-RET’). If the value is non-‘nil’ (the default value), then the entire search context is replaced, instead. You can use `M-_’ at any time during searching and replacing, to toggle the value. See Icicles - Search-And-Replace.


Option icicle-search-replace-literally-flag

User option ‘icicle-search-replace-literally-flag’ determines whether Icicles search-and-replace replaces text literally or interprets `\’ specially in the replacement text, as in ‘query-replace-regexp’. Non-‘nil’ means to treat replacement text literally. The default value is ‘nil’. You can use `M-`’ to toggle this at any time during Icicles search. See Icicles - Search-And-Replace.


Option icicle-ignore-comments-flag

Non-‘nil’ option ‘icicle-ignore-comments-flag’ means that ‘icicle-search-thing’ and related commands (e.g. ‘icicle-search-xml-element’) ignore comments. That is, they hide comments temporarily while they scan the region or buffer for things of the given type to serve as search contexts (completion candidates). This prevents them, for example, from presenting as a candidate a sexp or a list that is commented out. You can toggle this option anytime using `C-M-;’ in the minibuffer, but to see the effect you might need to invoke the current command again. See also option `icicle-hide-whitespace-before-comment-flag' (next).


Option icicle-hide-whitespace-before-comment-flag

Non-‘nil’ option ‘icicle-hide-whitespace-before-comment-flag’ means that hiding comments (see option `icicle-ignore-comments-flag') also hides whitespace preceding a comment. Empty lines (newline chars) are not hidden, however.


Option icicle-search-hook

User option ‘icicle-search-hook’ is a list of functions to be run after searching and moving to an ‘icicle-search’ match, whether you move there by ‘RET’, ‘C-RET’, ‘C-next’, or ‘C-prior’. See Icicles - Search Commands, Overview.


Option icicle-recenter

User option ‘icicle-recenter’ is passed as argument to ‘recenter’ whenever the current navigation destination would be off-screen, to make it visible.


Option icicle-bookmark-name-length-max

User option ‘icicle-bookmark-name-length-max’ is the maximum number of characters to use when ‘icicle-bookmark-cmd’ (‘C-x r m’) with a non-negative numeric prefix argument automatically names a bookmark.


Option icicle-bookmark-refresh-cache-flag

User option ‘icicle-bookmark-refresh-cache-flag’ determines whether commands such as ‘icicle-bookmark’ and ‘icicle-search-bookmark’ refresh the bookmark-list cache. The default value of ‘t’, meaning refresh, ensures that the set of bookmark candidates is always up-to-date, but you can improve performance for a large bookmark list if you customize it to ‘nil’.

In any case, a plain prefix argument (‘C-u’) for these commands overrides the default setting of the option for the duration of the command. Thus, if the customized value is ‘nil’, you can use ‘C-u’ occasionally to refresh the list on demand. In addition, the cache is refreshed whenever you use ‘S-delete’ to delete a candidate bookmark.


Options icicle-buffer-match-regexp, icicle-buffer-no-match-regexp, icicle-buffer-predicate, icicle-buffer-extras, icicle-file-match-regexp, icicle-file-no-match-regexp, icicle-file-predicate, icicle-file-extras

User options ‘icicle-buffer-match-regexp’, ‘icicle-buffer-no-match-regexp’, ‘icicle-buffer-predicate’, and ‘icicle-buffer-extras’ determine the behavior of Icicles buffer commands, such as ‘icicle-buffer’ and ‘icicle-insert-buffer’. They determine the set of buffer-name candidates available for completion.

The first three restrict this set to names that satisfy the properties they specify. Option ‘icicle-buffer-extras’ lets you add additional buffer names to the set of candidates, after restriction by the other options. Extra buffer-name candidates are displayed in buffer ‘*Completions*’ using face `icicle-extra-candidate’. Note that if an extra candidate is already a candidate anyway then it will be present twice in the list of all candidates (that is, unless ‘icicle-transform-function’ removes duplicate candidates).

Note that ‘icicle-buffer-predicate’ is applied after matching against user input. It thus corresponds to `icicle-must-pass-after-match-predicate’, not to `icicle-must-pass-predicate’.

Options ‘icicle-file-match-regexp’, ‘icicle-file-no-match-regexp’, ‘icicle-file-predicate’, and ‘icicle-file-extras’ act similarly for file-name completion. You could use ‘icicle-file-no-match-regexp’ or ‘icicle-file-predicate’, for instance, to exclude files that are in or under the directories in ‘vc-directory-exclusion-list’:

   (defun my-locate-non-vc-file ()
     "`icicle-locate-file', but excluding stuff in VC directories."
     (interactive)
     (let ((icicle-file-predicate  'not-excluded-vc-file-p))
       (icicle-locate-file)))
   (defun not-excluded-vc-file-p (file)
     "nil if FILE is in a `vc-directory-exclusion-list' directory."
     (or (not (boundp 'vc-directory-exclusion-list))
         (not (consp vc-directory-exclusion-list))
         (not (let ((case-fold-search  completion-ignore-case))
                (catch 'nevfp
                  (dolist (dir  vc-directory-exclusion-list)
                    (when (string-match
                           (concat ".*" dir "\\(/.*\\)?")
                           file)
                      (throw 'nevfp t)))
                  nil)))))

Option icicle-buffer-prefix-arg-filtering

Option ‘icicle-buffer-prefix-arg-filtering’ defines the prefix-argument filtering behavior for Icicles buffer commands. It lets you choose what any given prefix argument (including lack of a prefix argument) does to filter buffer-name completion candidates.


Options icicle-buffer-include-cached-files-nflag and icicle-buffer-include-recent-files-nflag

Options ‘icicle-buffer-include-cached-files-nflag’ and ‘icicle-buffer-include-recent-files-nflag’ also determine the behavior of commands ‘icicle-buffer’ (‘C-x b’) and‘icicle-buffer-other-window’ (‘C-x 4 b’). They determine whether the candidates available for completion include not only existing buffer names but also the names of certain files that are not currently visited.

For the former, these are the names cached by the Emacs file-name cache. For the latter, these are the names of recently visited files. See the Emacs manual, nodes File Name Cache and File Conveniences, respectively.

You can toggle these options using ‘C-x F’ and ‘C-x R’, respectively, during buffer-name completion. The option values are not exactly Boolean, however. They are in fact non-zero integer values. Each option is turned on when positive and off when negative.

The absolute value of the option is the maximum number of such candidates to include when turned on. So for example, if the latter option value is 20, then the names of only the twenty most recently visited files are candidates.

A prefix argument to ‘C-x F’ or ‘C-x R’ sets the option value to the numeric prefix argument value.


Options `icicle-buffer-skip-functions' and `icicle-file-skip-functions'

Options ‘icicle-buffer-skip-functions’ and ‘icicle-file-skip-functions’ are lists of hook functions. They are used by commands that read buffer names or file names (for Emacs 23 and later) to test a candidate buffer name or file name, respectively. You can use them to skip content-searching of certain buffers and files when completing buffer and file names using multi-completion

The functions are passed to ‘run-hook-with-args-until-success’, so they are called in order until one returns non-‘nil’. If any function returns non-‘nil’ then the buffer or file content is not searched. This is relevant only when your multi-completion input has a second, content-matching part.


Option icicle-file-search-dir-as-dired-flag

If options ‘icicle-file-search-dir-as-dired-flag’ and ‘find-file-run-dired’ are both non-‘nil’, and if your input to an Icicles file-finding command such as ‘icicle-file’ has a content-matching part, then completion of a directory name visits the directory in Dired mode, and the Dired listing is searched as the content. Otherwise, the content-matching part is ignored for a directory-name candidate. By default, ‘icicle-file-search-dir-as-dired-flag’ is ‘nil’, preventing such searching.


Option icicle-ignored-directories

Option ‘icicle-ignored-directories’ is a list of directories that are ignored by various Icicles commands, including ‘icicle-locate-file’. By default, this is the value of ‘vc-directory-exclusion-list’.


Options icicle-buffer-sort, icicle-file-sort

User option ‘icicle-buffer-sort’ is a predicate used to sort buffer-name candidates in Icicles buffer commands, such as ‘icicle-buffer’ and ‘icicle-insert-buffer’. Option ‘icicle-file-sort’ acts similarly for file-name completion. The default value of ‘icicle-buffer-sort’ is `icicle-buffer-sort-*...*-last’, which sorts names of buffers that begin with ‘*’ after other buffer names. These options affect only the initial sort order used for buffer and file names, respectively, that is, the order used first in an Emacs session. The values are also put first in the list of possible sort orders for cycling (via `C-,’).


Option icicle-buffer-configs

User option ‘icicle-buffer-configs’ is a list of named configurations of options `icicle-buffer-match-regexp’, `icicle-buffer-no-match-regexp’, `icicle-buffer-predicate’, `icicle-buffer-extras’, and `icicle-buffer-sort’. You use command ‘icicle-buffer-config’ to choose one of the configurations to be current. You can use commands ‘icicle-add-buffer-config’ and ‘icicle-remove-buffer-config’ to add and remove configurations from the list. Example: A configuration such as the following, named “Files and Scratch”, defines ‘icicle-buffer-predicate’ to display only file buffers, and it defines ‘icicle-buffer-extras’ to include the extra buffer ‘*scratch*’:

  ("Files and Scratch" nil nil
   (lambda (bufname) (buffer-file-name (get-buffer bufname)))
   ("*scratch*") icicle-sort-comparer)

The idea of buffer-option configurations was borrowed from library `bs.el’, by Olaf Sylvester <olaf@geekware.de>.


Options icicle-dot-string and icicle-dot-show-regexp-flag

User option ‘icicle-dot-string’ is the regexp string inserted by ‘icicle-insert-dot-command’ (bound to `.’ in the minibuffer during completion). You can set it to a regexp that matches any character, including newline. The default value instead matches any character except newline. You can toggle between these two behaviors using command ‘icicle-toggle-dot’, bound to `C-M-.’ during completion.

Non-‘nil’ option ‘icicle-dot-show-regexp-flag’ means show the underlying regexp (value of constant ‘icicle-anychar-regexp’) explicitly for a multi-line dot (`.’). A ‘nil’ value works only for Emacs versions 21 and later.


Option icicle-show-annotations-flag

Non-‘nil’ user option ‘icicle-show-annotations-flag’ means show annotations, when available, next to candidates in ‘*Completions*’. You can toggle this option from the minibuffer using ‘C-x C-a’.


Option icicle-show-multi-completion-flag

Non-‘nil’ user option ‘icicle-show-multi-completion-flag’ means that for some commands additional information is shown along with each completion candidate. That is, a multi-completion is used. You can match against any parts of the multi-completion. The default value is ‘t’. (By contrast, you cannot match the text controlled by option ‘icicle-show-annotations-flag’.)

For example, for command ‘icicle-search’, the name of the buffer associated with each completion candidate is added to the candidate and highlighted. You can match against the buffer name, as well as the search hit within the buffer.

Note that even when the value of this option is ‘nil’, you can often see the multi-completion information in the mode line when you cycle candidates, and you can typically see it in the help that is displayed by ‘C-M-mouse-2’ and so on.

You can toggle this option from the minibuffer using ‘M-m’. The new value takes effect after you exit the minibuffer (i.e., for the next command).


Option icicle-kill-visited-buffers-flag

Non-‘nil’ user option ‘icicle-kill-visited-buffers-flag’ means kill buffers visited temporarily to search files. This applies to commands such as `icicle-file’ (for Emacs 23 or later), which search files that match your completion input. If non-‘nil’ then any such buffers for files that you do not actually choose are killed when the command is finished. If ‘nil’ then they are not killed. This option applies only to Emacs 23 and later.


Option icicle-auto-complete-key-delay

When ‘icicle-auto-complete-keys-mode’ is enabled, user option ‘icicle-auto-complete-key-delay’ is the number of seconds Icicles waits, before displaying key completions.


Option icicle-complete-keys-separator

User option ‘icicle-complete-keys-separator’ is the string that separates the two parts (key description and command name) of a key completion candidate during key completion. The default value is " = ". You could, for example, change this to, say, Unicode character RIGHT ARROW.


Options icicle-list-join-string, icicle-list-nth-parts-join-string

User options ‘icicle-list-join-string’ and ‘icicle-list-nth-parts-join-string’ are described in Icicles - Multi-Completions and Icicles - Programming Multi-Completions. Option ‘icicle-list-join-string’ is the separator string that joins together the parts of a multi-completion. The end string is appended to each multi-completion candidate. Option ‘icicle-list-nth-parts-join-string’ specifies how the multi-completion extracted parts are joined back together when a user chooses a multi-completion.

The default value of ‘icicle-list-join-string’ is `^G^J’. With Emacs 22 and later, the `^G’ part is hidden when it appears in ‘*Completions*’, and you can hide it in the minibuffer also by using ‘C-M-j’ instead of typing ‘C-q C-g C-j’. See the doc string for more information.


Face icicle-candidate-part

Face ‘icicle-candidate-part’ highlights one or more parts of a candidate, in buffer ‘*Completions*’. The candidate is typically a multi-completion.


Option icicle-special-candidate-regexp, Face icicle-special-candidate

Face ‘icicle-special-candidate’ highlights candidates, in ‘*Completions*’, that are considered “special”. Generally, these are candidates that match user option ‘icicle-special-candidate-regexp’.


Faces icicle-key-complete-menu-local and icicle-key-complete-menu

Faces ‘icicle-key-complete-menu-local’ and ‘icicle-key-complete-menu’ highlight menu items during key completion. The former is for local menu items (i.e., specific to the current mode). The latter is for non-local menu items.


Option icicle-add-proxy-candidates-flag, Face icicle-proxy-candidate

Similarly, face ‘icicle-proxy-candidate’ highlights proxy candidates. These are placeholders for real candidates. Non-‘nil’ user option ‘icicle-add-proxy-candidates-flag’ means include proxy candidates whenever there are any. You can toggle this option during completion using command ‘icicle-toggle-proxy-candidates’, which is bound to `C-M-_’ in the minibuffer. For performance reasons, you will in some cases need to re-invoke the command to make the proxy candidates available.


Face icicle-extra-candidate

Face ‘icicle-extra-candidate’ highlights extra candidates, that is, members of `icicle-extra-candidates’, `icicle-buffer-extras’, or `icicle-file-extras’.


Option icicle-kmacro-ring-max

User option ‘icicle-kmacro-ring-max’ acts as ‘kmacro-ring-max’ when you are in Icicle mode. (When you exit Icicle mode, ‘kmacro-ring-max’ is restored.) In Icicles, you will typically want to use a much larger number than the default value in vanilla Emacs.


Options icicle-search-ring-max, icicle-regexp-search-ring-max

User options ‘icicle-regexp-search-ring-max’ and ‘icicle-search-ring-max’ act as ‘regexp-search-ring-max’ and ‘search-ring-max’, respectively, when you are in Icicle mode. (When you exit Icicle mode, ‘regexp-search-ring-max’ and ‘search-ring-max’ are restored.) The reason for having these options is that with Icicles you will likely want to use a much longer search history. By default, these are as large as possible (virtually unlimited). See Icicles - Isearch Enhancements.

Suggestion: If you use SaveHist (recommended), then customize ‘savehist-additional-variables’ to include variables ‘search-ring’ and ‘regexp-search-ring’, so that your search histories will be saved between Emacs sessions.

Note: You can clear (empty) a given search history with command ‘clear-option’’ (aka ‘icicle-reset-option-to-nil’). For example, to clear the regular-expression search history, do this: ‘C-u M-x clear-option RET regexp-search-ring RET’ (the ‘C-u’ is needed because this variable is not a user option). If you use my library misc-cmds.el, you can clear search histories easier, using commands ‘clear-search-history’, ‘clear-regexp-search-history’, and ‘clear-search-histories’. See Icicles - Isearch Enhancements.


Options icicle-completion-history-max-length, icicle-C-l-uses-completion-flag

User option ‘icicle-completion-history-max-length’ limits the number of completion inputs to save. If you customize user option ‘icicle-C-l-uses-completion-flag’ to non-‘nil’, then, instead of cycling, ‘C-l’ lets you use Icicles completion to retrieve a past completion input. (‘C-L’ does the same thing.) If you use SaveHist (library savehist.el or savehist-20+.el), then you can save the history of completion inputs persistently by customizing user option ‘savehist-additional-variables’ to include the Icicles internal variables ‘icicle-previous-raw-file-name-inputs’ and ‘icicle-previous-raw-non-file-name-inputs’.


Option icicle-highlight-lighter-flag and faces icicle-completion, icicle-multi-command-completion, icicle-mustmatch-completion

Faces ‘icicle-completion’, ‘icicle-multi-command-completion’, and ‘icicle-mustmatch-completion’ indicate the status of minibuffer completion. During completion, Icicles uses them for a minibuffer indicator and, if user option ‘icicle-highlight-lighter-flag’ is non-‘nil’, for the ‘Icy’ mode-line lighter as well.


Option icicle-highlight-input-initial-whitespace-flag, Face icicle-whitespace-highlight

Non-‘nil’ option ‘icicle-highlight-input-initial-whitespace-flag’ uses face ‘icicle-whitespace-highlight’ to highlight any whitespace that starts your minibuffer input. This is done to help you recognize accidentally typing such whitespace. Otherwise, you might not understand the set of matching completion candidates (or lack thereof). There is not necessarily anything wrong with input that starts with whitespace – it might be what you want, but without this highlighting it is easy to not notice the whitespace.


Options icicle-highlight-input-completion-failure, icicle-highlight-input-completion-failure-delay, icicle-highlight-input-completion-failure-threshold, Faces icicle-input-completion-fail, icicle-input-completion-fail-lax

The part of your current input that does not complete can be highlighted automatically, and you can then remove that part using ‘C-M-l’. This highlighting is controlled by 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’. The highlighting uses face ‘icicle-input-completion-fail’ (for strict completion) or ‘icicle-input-completion-fail-lax’ (for lax completion) to highlight the part of your current input that does not complete. Possible values control when highlighting can occur. For details, see the option doc strings and Highlight Nonmatch.


Option icicle-define-alias-commands-flag

Non-‘nil’ option ‘icicle-define-alias-commands-flag’ defines a few top-level Icicles commands whose names do not begin with ‘icicle-’, for convenience when using ‘M-x’. For example, command ‘toggle’ is defined as an alias for command ‘icicle-toggle-option’. In any case, no such command is ever defined by Icicles if a function with the same name is already defined.


Option icicle-color-themes

User option ‘icicle-color-themes’ is a list of color themes to cycle through when you use command ‘icicle-color-theme’. You need library color-theme.el to use this command.


Options icicle-custom-themes, icicle-custom-themes-accumulate-flag, icicle-custom-themes-update-flag

Option ‘icicle-custom-themes’ is a list of Emacs custom themes to cycle through when you use command ‘icicle-custom-theme’. (This is available only for Emacs 24 and later.) Option ‘icicle-custom-themes-accumulate-flag’ determines whether such cycling keeps the effects of previously applied themes or replaces each theme with the next one. Option ‘icicle-custom-themes-update-flag’ determines whether the command automatically saves changes made. A prefix argument flips this option value for the invocation of the command.


Option icicle-saved-completion-sets

User option ‘icicle-saved-completion-sets’ is a persistent list of named sets of completion candidates. You can switch among such sets at any time. See Icicles - Persistent Completions


Option icicle-filesets-as-saved-completion-sets-flag

User option ‘icicle-filesets-as-saved-completion-sets-flag’ non-‘nil’ means you can use Emacs FileSets to save completion candidates persistently. This means that you can save file-name candidates in a persistent Icicles saved completion set (cache file) or in in an Emacs fileset. It also means that an Icicles persistent completion set can contain filesets, in addition to file names: any number of filesets, and filesets of different type. Available only for Emacs 22 and later, and you must load library filesets.el (and enable filesets using `(filesets-init)’ – see FileSets).


Option icicle-key-descriptions-use-angle-brackets-flag

User option `icicle-key-descriptions-use-<>-flag’ (aka ‘icicle-key-descriptions-use-angle-brackets-flag’) determines whether angle brackets (`<’, `>’) are used by Icicles for named keys, such as function keys (`<f9>’ vs ‘f9’) and pseudo keys (`<mode-line>’ vs ‘mode-line’). Non-‘nil’ means to use angle brackets. This option does not affect Emacs key descriptions outside of Icicles, and it has no effect for versions of Emacs prior to 21, because they never use angle brackets. The default value is ‘nil’, because I think angle brackets reduce readability. See also my library naked.el, which lets you use the no-angle-brackets style also outside of Icicles.


Option icicle-keymaps-for-key-completion

User option ‘icicle-keymaps-for-key-completion’ is a list of variables that are bound to keymaps in which you want to bind ‘S-TAB’ (actually, each of the keys in the value of option `icicle-key-complete-keys’) to ‘icicle-complete-keys’. Each such keymap should have at least one prefix key. ‘S-TAB’ is bound in each keymap, so that you can use it to complete the prefix keys. See also `icicle-complete-key-anyway-flag’.


Option icicle-complete-key-anyway-flag

Non-‘nil’ option ‘icicle-complete-key-anyway-flag’ means bind ‘S-TAB’ (actually, each of the keys in the value of option `icicle-key-complete-keys’) to ‘icicle-complete-keys’ in each keymap of option `icicle-keymaps-for-key-completion’, regardless of whether ‘S-TAB’ already has a binding in that keymap. A value of ‘nil’ (the default value) means bind ‘S-TAB’ only if there is not already a binding for it. For example, by default ‘icicle-keymaps-for-key-completion’ includes ‘help-mode-map’. If you customize ‘icicle-complete-key-anyway-flag’ to ‘t’ then ‘S-TAB’ in ‘*Help*’ buffers completes keys, instead of moving backward to the previous button..


Option icicle-complete-keys-self-insert-ranges

Non-nil option ‘icicle-complete-keys-self-insert-ranges’ means that ‘icicle-complete-keys’ includes some self-inserting keys as completion candidates. You will probably want to leave this ‘nil’. This option has no effect before Emacs 22. See Entering Special and Foreign Characters.


Option icicle-yank-function

User option ‘icicle-yank-function’ is a function to use to yank text. By default, it is ‘yank’. Command ‘icicle-yank-maybe-completing’ calls this function, except when it is called from the minibuffer or called with a negative prefix argument. (‘C-- C-y’ lets you choose yanks (kills) to insert using completion. It is a multi-command. You can of course sort the candidates in various ways.)


Option icicle-use-candidates-only-once-flag

Non-‘nil’ user option ‘icicle-use-candidates-only-once-flag’ means that acting on a candidate removes it from the set of available candidates, so that you do not see that it can be used again. (‘TAB’ or ‘S-TAB’ makes it available again.) The default value is ‘nil’, and you probably do not want to customize this. However, if you write EmacsLisp code that uses completion, then you can bind this to non-‘nil’ in contexts where that makes sense.


Option icicle-deletion-action-flag

Non-‘nil’ user option ‘icicle-deletion-action-flag’ means ‘S-delete’ during completion deletes the current object. More precisely, it deletes the object named by the current completion candidate, if a deletion action is defined for the current command. If no deletion action is defined, then the value of this option has no effect for that command.


Option icicle-alternative-actions-alist

User option ‘icicle-alternative-actions-alist’ is an alist that associates Emacs commands and alternative action functions. It overrides any alternative actions defined otherwise for the commands.


Option icicle-type-actions-alist

User option ‘icicle-type-actions-alist’ is an alist that associates Emacs object types, such as buffer, file, and process, with functions that accept an object of the given type as their only required object. This is used by some Emacs commands during completion to prompt for a function to apply to the current completion candidate. Each function can be a symbol or a lambda expression. At runtime, symbols that are not functions (‘functionp’) are ignored.


icicle-use-anything-candidates-flag

Non-‘nil’ user option ‘icicle-use-anything-candidates-flag’ means Anything actions are used for candidate alternative actions in some Icicles commands, and Anything types and actions are used by command ‘icicle-object-action’ (aka ‘what-which-how’ and ‘a’). The default value is ‘t’. This option has no effect if library anything.el cannot be loaded.


Option icicle-anything-transform-candidates-flag

Non-‘nil’ user option ‘icicle-anything-transform-candidates-flag’ means that Anything function ‘anything-transform-candidates’ is applied to displayed Anything candidates in Icicles. The default value is ‘nil’.

The advantage of a ‘nil’ value is that command ‘icicle-anything’ then acts as a multi-command: you can act on multiple candidates, or apply multiple actions for the same candidate, within a single invocation of ‘icicle-anything’ (or related commands). The advantage of a non-‘nil’ value is that some of the displayed Anything candidates might be more readable. The default value is ‘nil’. This option has no effect if library anything.el cannot be loaded.


Option icicle-WYSIWYG-Completions-flag

User option ‘icicle-WYSIWYG-Completions-flag’ controls how some completion candidates such as face, font, and color names are displayed as candidates in ‘*Completions*’. If the value is non-‘nil’, then a WYSIWYG (What You See Is What You Get) sample is shown for the candidate. For faces and colors, if the value is a string, then the name is accompanied by a separate swatch showing that string text. If the value is ‘t’, then the candidate name itself is shown using the face or color that it names.

You can use command ‘icicle-toggle-WYSIWYG-Completions’, bound to ‘C-S-pause’ during completion, to toggle this option, but the change takes effect only for the next act of completion; so, use ‘C-g’ and repeat the current command to see the effect.

Here are screen shots of face-name candidates for ‘icicle-WYSIWYG-Completions-flag’:

‘icicle-WYSIWYG-Completions-flag’ = ‘t’: IcicleWYSIWYGCompletionsflagWhole

‘icicle-WYSIWYG-Completions-flag’= ‘4’: IcicleWYSIWYGCompletionsflagSwatch


Option icicle-unpropertize-completion-result-flag

Non-‘nil’ user option ‘icicle-unpropertize-completion-result-flag’ means that ‘completing-read’ and (starting with Emacs 23) ‘read-file-name’ will strip all text properties from the result they return. Regardless of the option value, Icicles strips text properties that it adds for its internal use. See the doc string of function ‘icicle-unpropertize-completion’ for more information about this.

The default value of the option is ‘nil’. It is not likely that you will need to change this, but you might if you use some other library that cannot accept a propertized string as the result of completion.

Note: This is the case if you use GNUS – it has a known bug in this regard (reported 2008-06-21). It blindly prints the EmacsLisp string that is the result of completion into an MML attribute value: filename=#("~/.gnus/attach.el" 0 25 (face nil)). GNUS should ensure that whatever it uses for an attribute value is valid for MML (has normal "..." string syntax, with acceptable characters). But it simply calls a Lisp print function, which prints #("..."). See also GnusBugsAndWorkarounds.


Options icicle-pp-eval-expression-print-length, icicle-pp-eval-expression-print-level

User options ‘icicle-pp-eval-expression-print-length’ and ‘icicle-pp-eval-expression-print-level’ control the Lisp sexp print length and print level, respectively, for values printed by `M-:’ (‘icicle-pp-eval-expression’).


Option icicle-guess-commands-in-path

Non-‘nil’ option ‘icicle-guess-commands-in-path’ means that all executable files (or all files, if option ‘shell-completion-execonly’ is ‘nil’) in your search path are included among the completion candidates whenever a shell command is read. The particular non-nil value determines when this list of commands is updated from your current search path. The default value is ‘nil’. (The computed commands are cached in ‘icicle-shell-command-candidates-cache’.) See Icicles - Shell-Command Enhancements.


Option icicle-quote-shell-file-name-flag

Non-‘nil’ option ‘icicle-quote-shell-file-name-flag’ means that ‘icicle-read-shell-command-completing’ double-quotes the file name at the beginning of the shell command it reads. This affects several Emacs commands, such as `M-!’ that read a shell command and its arguments.

If this is ‘nil’, then such commands will not quote a shell-command file name such as `c:/Program Files/My Dir/mycmd.exe’. In that case, a shell such as ‘bash’ fails for a shell command such as `c:/Program Files/My Dir/mycmd.exe arg1 arg2 &’, because it interprets only `c:/Program’ as the shell command. That is, it interprets the space (‘SPC’) characters in the file name as separators.

If this is non-‘nil’ (the default value), then input such as `c:/Program Files/My Dir/mycmd.exe arg1 arg2 &’ is passed to the shell as `"c:/Program Files/My Dir/mycmd.exe" arg1 arg2 &’ (notice the double-quotes).

See the doc string of ‘icicle-quote-file-name-part-of-cmd’ for information about the characters that, like ‘SPC’, lead to file-name quoting.


Option icicle-inhibit-ding-flag

Non-‘nil’ user option ‘icicle-inhibit-ding-flag’ means Icicles never uses an audible bell (ding).


Option icicle-option-type-prefix-arg-list

A list of symbols that control prefix arguments for command ‘icicle-describe-option-of-type’ (bound to ‘C-h C-o’ by default). A list of six symbols taken from this list:

Choose the order you like. The list members map, in order from left to right, to these prefix-argument keys:

  1. ‘C-u C-u’
  2. ‘C-0’
  3. ‘C-u’
  4. ‘C-9’ (positive)
  5. no prefix arg
  6. ‘C--’ (negative)

For the meanings of the symbols, see the doc string of ‘icicle-describe-option-of-type’, which describes the default prefix-argument bindings for the command.


Option icicle-customize-save-flag

Non-‘nil’ user option ‘icicle-customize-save-flag’ means that Icicles will save the updated value of option `icicle-command-abbrev-alist’ when you quit Emacs. This is the normal behavior. If you for some reason do not want your custom file or init file updated in this way, then customize ‘icicle-customize-save-flag’ to ‘nil’.


Option icicle-buffers-ido-like-flag

If user option ‘icicle-buffers-ido-like-flag’ is ‘t’ then ‘icicle-buffer’ and similar commands act more Ido-like. Specifically, those commands then bind these options to ‘t’:


Option icicle-files-ido-like-flag

If option ‘icicle-files-ido-like-flag’ is ‘t’ then ‘icicle-file’ and similar commands act more Ido-like. Specifically, those commands then bind these options to ‘t’:


Options icicle-cmpl-max-candidates-to-cycle and icicle-cmpl-include-cdabbrev-flag

User options ‘icicle-cmpl-max-candidates-to-cycle’ and ‘icicle-cmpl-include-cdabbrev-flag’ control the behavior of Icicles command ‘icicle-complete’, which replaces Emacs command ‘complete’ from standard Emacs library completion.el when you are in Icicle mode. The first of these options controls how many completion matches are required for Icicles completion to be used instead of in-place cycling replacement. The second controls whether Icicles completion candidates can be found dynamically or should be limited to terms from your completions database.


Option icicle-customize-save-variable-function

The value of option ‘icicle-customize-save-variable-function’ is the function Icicles uses to automatically save user option changes made by some commands. I recommend that you do NOT change this option value. This is provided only for users who might want to disable such automatic saving of option changes, by setting this to ‘ignore’, or users who might want to manage such option saving using their own function instead of the default value, ‘customize-save-variable’.


Option icicle-read-char-by-name-multi-completion-flag

(Emacs 23-25 only.) Non-‘nil’ option ‘icicle-read-char-by-name-multi-completion-flag’ means that ‘icicle-read-char-by-name’ (which, by the default value of option ‘icicle-functions-to-redefine’, replaces vanilla ‘read-char-by-name’ in Icicle mode) uses multi-completion and shows helpful information about the current completion candidate in the mode line (the character name and code point, in hex, octal, and decimal notation).

The 3-part multi-completion, NAME CODE CHAR, shows three ways to represent the character as text:

Setting this option to ‘nil’ can speed up reading a character considerably, but it does not give you the advantages of seeing the character (WYSIWYG) or matching its code point.

Instead of using a ‘nil’ value, you can also speed things up by:


Option icicle-zap-to-char-candidates

(Emacs 23-25 only.) Option ‘icicle-zap-to-char-candidates’ determines which character names are used for ‘icicle-zap-to-char’ (bound to ‘M-z’ by default) when completing. The default value of ‘nil’ means complete against character names that you have already entered. You can instead set the value to ‘icicle-ucs-names’ to complete against all Unicode character names. Or you can set it to any function that returns a value of the same form at that returned by ‘icicle-ucs-names’ (hence ‘ucs-names’).


Options icicle-cand-preds-all, icicle-cand-preds-for-TYPE

The options whose names start with prefix ‘icicle-cand-preds-’ are lists of predefined predicates that are used to filter completion candidates when you narrow with `M-&’. Option ‘icicle-cand-preds-all’ includes all such predicates, across all types of candidate.

The other options, named ‘icicle-cand-preds-for-TYPE’, are each for a particular completion TYPE. For example, ‘icicle-cand-preds-for-bookmark’ provides predicates for narrowing bookmark candidates. Option ‘icicle-cand-preds-for-misc’, is an exception: its predicates apply to all candidate types.

These are the TYPE-specific options:

See also `M-&': Satisfying Additional Predicates.


Previous: Icicles - Completion in Other BuffersIciclesIciclesIndexNext: Icicles - File-Name Completion Tips

DrewsElispLibraries referenced here: Lisp:delsel.el, Lisp:icicles.el, Lisp:icicles-keys.el, Lisp:misc-cmds.el, Lisp:oneonone.el

CategoryBookmarking CategoryCommands CategoryComments CategoryBufferSwitching CategoryCompletion CategoryRegexp CategoryDocumentation CategoryHelp CategoryRegion CategoryModes CategoryDirectories CategoryFiles CategoryProgrammerUtils CategoryCode