Update icicles

[emacs.git] / .emacs.d / elisp / icicle / icicles-mcmd.el

;;; icicles-mcmd.el --- Minibuffer commands for Icicles
;;
;; Filename: icicles-mcmd.el
;; Description: Minibuffer commands for Icicles
;; Author: Drew Adams
;; Maintainer: Drew Adams (concat "drew.adams" "@" "oracle" ".com")
;; Copyright (C) 1996-2015, Drew Adams, all rights reserved.
;; Created: Mon Feb 27 09:25:04 2006
;; Last-Updated: Wed Jan 21 09:01:17 2015 (-0800)
;;           By: dradams
;;     Update #: 19644
;; URL: http://www.emacswiki.org/icicles-mcmd.el
;; Doc URL: http://www.emacswiki.org/Icicles
;; Keywords: internal, extensions, help, abbrev, local, minibuffer,
;;           keys, apropos, completion, matching, regexp, command
;; Compatibility: GNU Emacs: 20.x, 21.x, 22.x, 23.x, 24.x, 25.x
;;
;; Features that might be required by this library:
;;
;;   `apropos', `apropos+', `apropos-fn+var', `avoid', `bookmark',
;;   `bookmark+', `bookmark+-1', `bookmark+-bmu', `bookmark+-key',
;;   `bookmark+-lit', `cl', `cmds-menu', `cus-theme', `doremi',
;;   `el-swank-fuzzy', `ffap', `ffap-', `fit-frame', `frame-fns',
;;   `fuzzy', `fuzzy-match', `help+20', `hexrgb', `icicles-fn',
;;   `icicles-opt', `icicles-var', `image-dired', `info', `info+20',
;;   `kmacro', `levenshtein', `menu-bar', `menu-bar+', `misc-cmds',
;;   `misc-fns', `mouse3', `mwheel', `naked', `package', `pp', `pp+',
;;   `regexp-opt', `ring', `second-sel', `strings', `thingatpt',
;;   `thingatpt+', `unaccent', `w32browser-dlgopen', `wid-edit',
;;   `wid-edit+', `widget'.
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;;; Commentary:
;;
;;  This is a helper library for library `icicles.el'.  It defines
;;  commands to be used mainly in the minibuffer or buffer
;;  `*Completions*' (and a few non-interactive functions used in those
;;  commands).  For top-level commands, see `icicles-cmd1.el' and
;;  `icicles-cmd2.el'.  For Icicles documentation, see
;;  `icicles-doc1.el' and `icicles-doc2.el'.
;;
;;  Commands defined here - (+) means a multi-command:
;;
;;    `cycle-icicle-expand-to-common-match',
;;    `cycle-icicle-image-file-thumbnail',
;;    `cycle-icicle-incremental-completion',
;;    `cycle-icicle-sort-order',
;;    `cycle-icicle-S-TAB-completion-method',
;;    `cycle-icicle-TAB-completion-method',
;;    `icicle-abort-recursive-edit', `icicle-add-file-to-fileset',
;;    `icicle-add/update-saved-completion-set',
;;    `icicle-all-candidates-action',
;;    `icicle-all-candidates-alt-action',
;;    `icicle-all-candidates-list-action',
;;    `icicle-all-candidates-list-alt-action',
;;    `icicle-apropos-complete', `icicle-apropos-complete-and-exit',
;;    `icicle-apropos-complete-and-narrow',
;;    `icicle-apropos-complete-and-widen',
;;    `icicle-apropos-complete-no-display',
;;    `icicle-backward-char-magic',
;;    `icicle-backward-delete-char-untabify',
;;    `icicle-backward-kill-paragraph',
;;    `icicle-backward-kill-sentence', `icicle-backward-kill-sexp',
;;    `icicle-backward-kill-word', `icicle-beginning-of-line+',
;;    `icicle-candidate-action', `icicle-candidate-alt-action',
;;    `icicle-candidate-read-fn-invoke',
;;    `icicle-candidate-set-complement',
;;    `icicle-candidate-set-define',
;;    `icicle-candidate-set-difference',
;;    `icicle-candidate-set-intersection',
;;    `icicle-candidate-set-retrieve',
;;    `icicle-candidate-set-retrieve-from-variable',
;;    `icicle-candidate-set-retrieve-more',
;;    `icicle-candidate-set-retrieve-persistent',
;;    `icicle-candidate-set-save', `icicle-candidate-set-save-more',
;;    `icicle-candidate-set-save-more-selected',
;;    `icicle-candidate-set-save-persistently',
;;    `icicle-candidate-set-save-selected',
;;    `icicle-candidate-set-save-to-variable',
;;    `icicle-candidate-set-swap', `icicle-candidate-set-truncate',
;;    `icicle-candidate-set-union',
;;    `icicle-change-alternative-sort-order',
;;    `icicle-change-history-variable', `icicle-change-sort-order',
;;    `icicle-choose-completion',
;;    `icicle-complete-current-candidate-as-input',
;;    `icicle-completing-read+insert',
;;    `icicle-Completions-mouse-3-menu',
;;    `icicle-cycle-expand-to-common-match',
;;    `icicle-cycle-image-file-thumbnail',
;;    `icicle-cycle-incremental-completion',
;;    `icicle-delete-backward-char', `icicle-delete-candidate-object',
;;    `icicle-delete-char', `icicle-delete-windows-on',
;;    `icicle-describe-file', `icicle-digit-argument',
;;    `icicle-dispatch-C-^', `icicle-dispatch-C-.',
;;    `icicle-dispatch-C-M-/', `icicle-dispatch-C-x.',
;;    `icicle-dispatch-M-_', `icicle-dispatch-M-comma',
;;    `icicle-dispatch-M-q',
;;    `icicle-display-candidates-in-Completions',
;;    `icicle-doremi-candidate-width-factor+',
;;    `icicle-doremi-increment-max-candidates+',
;;    `icicle-doremi-increment-swank-prefix-length+',
;;    `icicle-doremi-increment-swank-timeout+',
;;    `icicle-doremi-inter-candidates-min-spaces+',
;;    `icicle-doremi-zoom-Completions+', `icicle-end-of-line+',
;;    `icicle-erase-minibuffer',
;;    `icicle-erase-minibuffer-or-history-element',
;;    `icicle-exit-minibuffer', `icicle-file-all-tags-narrow',
;;    `icicle-file-all-tags-regexp-narrow',
;;    `icicle-file-some-tags-narrow',
;;    `icicle-file-some-tags-regexp-narrow',
;;    `icicle-forward-char-magic', `icicle-goto/kill-failed-input',
;;    `icicle-help-on-candidate',
;;    `icicle-help-on-next-apropos-candidate',
;;    `icicle-help-on-next-prefix-candidate',
;;    `icicle-help-on-previous-apropos-candidate',
;;    `icicle-help-on-previous-prefix-candidate',
;;    `icicle-help-string-completion',
;;    `icicle-help-string-non-completion', `icicle-history',
;;    `icicle-insert-completion', `icicle-insert-dot-command',
;;    (+)`icicle-insert-history-element',
;;    `icicle-insert-key-description',
;;    `icicle-insert-list-join-string',
;;    `icicle-insert-newline-in-minibuffer',
;;    `icicle-insert-string-at-point',
;;    `icicle-insert-string-from-variable', `icicle-isearch-complete',
;;    (+)`icicle-isearch-history-complete',
;;    (+)`icicle-isearch-history-insert',
;;    `icicle-keep-only-buffer-cands-for-derived-mode',
;;    `icicle-keep-only-buffer-cands-for-mode',
;;    `icicle-keep-only-buffer-cands-for-visible',
;;    `icicle-keep-only-past-inputs', `icicle-kill-line',
;;    `icicle-kill-paragraph', `icicle-kill-region',
;;    `icicle-kill-region-wimpy', `icicle-kill-sentence',
;;    `icicle-kill-sexp', `icicle-kill-word', `icicle-make-directory',
;;    `icicle-minibuffer-complete-and-exit', `icicle-minibuffer-help',
;;    `icicle-mouse-candidate-action',
;;    `icicle-mouse-candidate-alt-action',
;;    `icicle-mouse-candidate-read-fn-invoke',
;;    `icicle-mouse-candidate-set-save',
;;    `icicle-mouse-candidate-set-save-more',
;;    `icicle-mouse-choose-completion',
;;    `icicle-mouse-help-on-candidate',
;;    `icicle-mouse-remove-candidate',
;;    `icicle-mouse-save/unsave-candidate',
;;    `icicle-mouse-save-then-kill', `icicle-mouse-yank-secondary',
;;    `icicle-move-to-next-completion',
;;    `icicle-move-to-previous-completion', `icicle-multi-inputs-act',
;;    `icicle-multi-inputs-save', `icicle-narrow-candidates',
;;    `icicle-narrow-candidates-with-predicate',
;;    `icicle-negative-argument', `icicle-next-apropos-candidate',
;;    `icicle-next-apropos-candidate-action',
;;    `icicle-next-apropos-candidate-alt-action',
;;    `icicle-next-candidate-per-mode',
;;    `icicle-next-candidate-per-mode-action',
;;    `icicle-next-candidate-per-mode-alt-action',
;;    `icicle-next-history-element', `icicle-next-line',
;;    `icicle-next-prefix-candidate',
;;    `icicle-next-prefix-candidate-action',
;;    `icicle-next-prefix-candidate-alt-action',
;;    `icicle-next-S-TAB-completion-method',
;;    `icicle-next-TAB-completion-method',
;;    `icicle-ORIG-choose-completion', `icicle-ORIG-exit-minibuffer',
;;    `icicle-ORIG-minibuffer-complete-and-exit',
;;    `icicle-ORIG-mouse-choose-completion',
;;    `icicle-ORIG-next-history-element', `icicle-ORIG-sit-for',
;;    `icicle-ORIG-switch-to-completions', `icicle-other-history',
;;    `icicle-plus-saved-sort',
;;    `icicle-pp-eval-expression-in-minibuffer',
;;    `icicle-prefix-complete', `icicle-prefix-complete-no-display',
;;    `icicle-prefix-word-complete',
;;    `icicle-previous-apropos-candidate',
;;    `icicle-previous-apropos-candidate-action',
;;    `icicle-previous-apropos-candidate-alt-action',
;;    `icicle-previous-candidate-per-mode',
;;    `icicle-previous-candidate-per-mode-action',
;;    `icicle-previous-candidate-per-mode-alt-action',
;;    `icicle-previous-line', `icicle-previous-prefix-candidate',
;;    `icicle-previous-prefix-candidate-action',
;;    `icicle-previous-prefix-candidate-alt-action',
;;    `icicle-read+insert-file-name',
;;    `icicle-recomplete-from-original-domain',
;;    `icicle-regexp-quote-input', `icicle-remove-candidate',
;;    `icicle-remove-buffer-cands-for-derived-mode',
;;    `icicle-remove-buffer-cands-for-mode',
;;    `icicle-remove-buffer-cands-for-visible',
;;    `icicle-remove-Completions-window', `icicle-resolve-file-name',
;;    `icicle-retrieve-last-input', `icicle-retrieve-next-input',
;;    `icicle-retrieve-previous-input', `icicle-reverse-sort-order',
;;    (+)`icicle-roundup', `icicle-save-predicate-to-variable',
;;    `icicle-save/unsave-candidate',
;;    `icicle-scroll-Completions-backward',
;;    `icicle-scroll-Completions-forward', `icicle-scroll-backward',
;;    `icicle-scroll-forward', `icicle-search-define-replacement',
;;    `icicle-self-insert', `icicle-sit-for',
;;    `icicle-sort-alphabetical', `icicle-sort-by-abbrev-frequency',
;;    `icicle-sort-by-directories-first',
;;    `icicle-sort-by-directories-last', `icicle-sort-by-file-type',
;;    `icicle-sort-by-last-file-access-time',
;;    `icicle-sort-by-last-file-modification-time',
;;    `icicle-sort-by-last-use', `icicle-sort-by-last-use-as-input',
;;    `icicle-sort-by-last-use\,-dirs-first',
;;    `icicle-sort-by-previous-use-alphabetically',
;;    `icicle-sort-by-2nd-parts-alphabetically',
;;    `icicle-sort-case-insensitive',
;;    `icicle-sort-extra-candidates-first',
;;    `icicle-sort-proxy-candidates-first',
;;    `icicle-sort-special-candidates-first',
;;    `icicle-sort-turned-OFF', `icicle-switch-to-Completions-buf',
;;    `icicle-switch-to-completions',
;;    `icicle-switch-to/from-minibuffer', `icicle-toggle-.',
;;    `icicle-toggle-~-for-home-dir',
;;    `icicle-toggle-alternative-sorting',
;;    `icicle-toggle-angle-brackets', `icicle-toggle-annotation',
;;    `icicle-toggle-case-sensitivity', `icicle-toggle-C-for-actions',
;;    `icicle-toggle-completions-format', `icicle-toggle-dot',
;;    `icicle-toggle-expand-directory',
;;    `icicle-toggle-expand-to-common-match',
;;    `icicle-toggle-hiding-common-match',
;;    `icicle-toggle-hiding-non-matching-lines',
;;    `icicle-toggle-highlight-all-current',
;;    `icicle-toggle-highlight-historical-candidates',
;;    `icicle-toggle-highlight-saved-candidates',
;;    `icicle-toggle-icomplete-mode',
;;    `icicle-toggle-ignored-extensions',
;;    `icicle-toggle-ignored-space-prefix',
;;    `icicle-toggle-ignoring-comments',
;;    `icicle-toggle-include-cached-files',
;;    `icicle-toggle-include-recent-files',
;;    `icicle-toggle-literal-replacement',
;;    `icicle-toggle-network-drives-as-remote',
;;    `icicle-toggle-proxy-candidates', `icicle-toggle-regexp-quote',
;;    `icicle-toggle-remote-file-testing',
;;    `icicle-toggle-search-cleanup',
;;    `icicle-toggle-search-complementing-domain',
;;    `icicle-toggle-search-replace-common-match',
;;    `icicle-toggle-search-replace-whole',
;;    `icicle-toggle-search-whole-word',
;;    `icicle-toggle-show-multi-completion', `icicle-toggle-sorting',
;;    `icicle-toggle-transforming',
;;    `icicle-toggle-WYSIWYG-Completions', `icicle-top-level',
;;    `icicle-transpose-chars', `icicle-transpose-sexps',
;;    `icicle-transpose-words', `icicle-universal-argument',
;;    `icicle-universal-argument-minus',
;;    `icicle-universal-argument-more',
;;    `icicle-universal-argument-other-key', `icicle-up-directory',
;;    `icicle-use-interactive-command-history',
;;    `icicle-widen-candidates', `icicle-yank', `icicle-yank-pop',
;;    `icicle-yank-secondary', `toggle-icicle-.',
;;    `toggle-icicle-~-for-home-dir',
;;    `toggle-icicle-alternative-sorting',
;;    `toggle-icicle-angle-brackets', `toggle-icicle-annotation',
;;    `toggle-icicle-case-sensitivity', `toggle-icicle-C-for-actions',
;;    `toggle-icicle-completions-format', `toggle-icicle-dot',
;;    `toggle-icicle-expand-directory',
;;    `toggle-icicle-expand-to-common-match',
;;    `toggle-icicle-hiding-common-match',
;;    `toggle-icicle-hiding-non-matching-lines',
;;    `toggle-icicle-highlight-all-current',
;;    `toggle-icicle-highlight-historical-candidates',
;;    `toggle-icicle-highlight-saved-candidates',
;;    `toggle-icicle-icomplete-mode',
;;    `toggle-icicle-ignored-extensions',
;;    `toggle-icicle-ignored-space-prefix',
;;    `toggle-icicle-include-cached-files',
;;    `toggle-icicle-include-recent-files',
;;    `toggle-icicle-incremental-completion',
;;    `toggle-icicle-literal-replacement',
;;    `toggle-icicle-network-drives-as-remote',
;;    `toggle-icicle-proxy-candidates', `toggle-icicle-regexp-quote',
;;    `toggle-icicle-remote-file-testing',
;;    `toggle-icicle-search-cleanup',
;;    `toggle-icicle-search-complementing-domain',
;;    `toggle-icicle-search-replace-common-match',
;;    `toggle-icicle-search-replace-whole',
;;    `toggle-icicle-search-whole-word',
;;    `toggle-icicle-show-multi-completion', `toggle-icicle-sorting',
;;    `toggle-icicle-transforming',
;;    `toggle-icicle-WYSIWYG-Completions'.
;;
;;  Non-interactive functions defined here:
;;
;;    `icicle-all-candidates-action-1', `icicle-all-exif-data',
;;    `icicle-anychar-regexp', `icicle-apply-to-saved-candidate',
;;    `icicle-apropos-complete-1', `icicle-apropos-complete-2',
;;    `icicle-autofile-action',
;;    `icicle-backward-delete-char-untabify-magic',
;;    `icicle-bind-buffer-candidate-keys',
;;    `icicle-bind-file-candidate-keys', `icicle-candidate-action-1',
;;    `icicle-candidate-set-retrieve-1',
;;    `icicle-candidate-set-save-1',
;;    `icicle-candidate-set-save-selected-1', `icicle-cand-preds',
;;    `icicle-column-wise-cand-nb',
;;    `icicle-isearch-complete-past-string',
;;    `icicle-Completions-popup-choice',
;;    `icicle-Completions-popup-choice-1', `icicle-convert-dots',
;;    `icicle-current-completion-in-Completions',
;;    `icicle-current-sort-functions', `icicle-current-sort-order',
;;    `icicle-delete-backward-char-magic',
;;    `icicle-delete-candidate-object-1', `icicle-delete-char-magic',
;;    `icicle-delete-current-candidate-object',
;;    `icicle-ensure-overriding-map-is-bound',
;;    `icicle-help-on-candidate-symbol',
;;    `icicle-input-is-a-completion-p',
;;    `icicle-insert-candidate-action', `icicle-insert-dot',
;;    `icicle-insert-input', `icicle-insert-thing',
;;    `icicle-keep/remove-buffer-cands-for-visible',
;;    `icicle-looking-at-p', `icicle-looking-at-literally-p',
;;    `icicle-looking-back-at-literally-p',
;;    `icicle-markers-to-readable',
;;    `icicle-maybe-multi-completion-completing-p',
;;    `icicle-mouse-candidate-action-1', `icicle-nb-Completions-cols',
;;    `icicle-nb-of-cand-at-Completions-pos',
;;    `icicle-nb-of-cand-in-Completions-horiz',
;;    `icicle-prefix-complete-1', `icicle-prefix-complete-2',
;;    `icicle-raise-Completions-frame',
;;    `icicle-remove-cand-from-lists',
;;    `icicle-remove-candidate-display-others',
;;    `icicle-replace-input-w-parent-dir',
;;    `icicle-retrieve-candidates-from-set',
;;    `icicle-row-wise-cand-nb', `icicle-signum',
;;    `icicle-split-input', `icicle-substitute-keymap-vars',
;;    `icicle-successive-action', `icicle-transform-sole-candidate',
;;    `icicle-transpose-chars-magic',
;;    `icicle-unbind-buffer-candidate-keys',
;;    `icicle-unbind-file-candidate-keys',
;;    `icicle-universal-argument--mode' (Emacs 24.4+),
;;    `icicle-upcase-if-ignore-case', `icicle-update-and-next'.
;;
;;  Internal variables defined here:
;;
;;    `overriding-map-is-bound', `saved-overriding-map'.
;;
;;
;;  ***** NOTE: These EMACS PRIMITIVES have been REDEFINED HERE:
;;
;;  `exit-minibuffer'              - Remove *Completion* window and
;;                                   input mismatch highlighting
;;  `minibuffer-complete-and-exit' - Use Icicles prefix completion
;;
;;
;;  ***** NOTE: The following function defined in `mouse.el' has
;;              been REDEFINED HERE:
;;
;;  `choose-completion'       - Don't iconify frame or bury buffer.
;;  `mouse-choose-completion' - Return the number of the completion.
;;
;;
;;  ***** NOTE: The following function defined in `simple.el' has
;;              been REDEFINED HERE:
;;
;;  `switch-to-completions' - Always selects `*Completions*' window.
;;
;;
;;  Key bindings made by Icicles: See "Key Bindings" in
;;  `icicles-doc2.el'.
;;
;;  For descriptions of changes to this file, see `icicles-chg.el'.
 
;;(@> "Index")
;;
;;  If you have library `linkd.el' and Emacs 22 or later, load
;;  `linkd.el' and turn on `linkd-mode' now.  It lets you easily
;;  navigate around the sections of this doc.  Linkd mode will
;;  highlight this Index, as well as the cross-references and section
;;  headings throughout this file.  You can get `linkd.el' here:
;;  http://dto.freeshell.org/notebook/Linkd.html.
;;
;;  (@> "Redefined standard commands")
;;  (@> "Icicles commands")
;;    (@> "Minibuffer editing commands")
;;    (@> "Commands to sort completion candidates")
;;    (@> "Other commands to be used mainly in the minibuffer")
 
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;; This program is free software; you can redistribute it and/or
;; modify it under the terms of the GNU General Public License as
;; published by the Free Software Foundation; either version 2, or (at
;; your option) any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with this program; see the file COPYING.  If not, write to
;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth
;; Floor, Boston, MA 02110-1301, USA.
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;;; Code:

(eval-when-compile (require 'cl)) ;; case, flet, lexical-let, loop
                                  ;; plus, for Emacs < 21: dolist, push
(eval-when-compile (require 'filesets nil t)) ; Emacs 22+.
  ;; filesets-data, filesets-entry-get-files, filesets-entry-mode, filesets-entry-set-files,
  ;; filesets-files-equalp, filesets-init, filesets-member, filesets-set-config

(eval-when-compile
 (or (condition-case nil
         (load-library "icicles-mac")   ; Use load-library to ensure latest .elc.
       (error nil))
     (require 'icicles-mac)))           ; Require, so can load separately if not on `load-path'.
  ;; icicle-assoc-delete-all, icicle-define-sort-command
(require 'icicles-opt)                  ; (This is required anyway by `icicles-var.el'.)
  ;; icicle-act-before-cycle-flag, icicle-add-proxy-candidates-flag, icicle-alternative-sort-comparer,
  ;; icicle-anychar-regexp, icicle-buffer-ignore-space-prefix-flag, icicle-dot-string-internal,
  ;; icicle-move-Completions-frame, icicle-Completions-mouse-3-menu-entries, icicle-current-TAB-method,
  ;; icicle-default-cycling-mode, icicle-default-thing-insertion, icicle-delete-candidate-object,
  ;; icicle-expand-input-to-common-match, icicle-hide-common-match-in-Completions-flag,
  ;; icicle-hide-non-matching-lines-flag, icicle-incremental-completion, icicle-input-string, icicle-kbd,
  ;; icicle-key-descriptions-use-<>-flag, icicle-regexp-quote-flag, icicle-saved-completion-sets,
  ;; icicle-search-cleanup-flag, icicle-search-highlight-all-current-flag, icicle-sort-comparer,
  ;; icicle-sort-orders-alist, icicle-TAB-shows-candidates-flag, icicle-thing-at-point-functions,
  ;; icicle-transform-function
(eval-and-compile (require 'icicles-var)) ; (This is required anyway by `icicles-fn.el'.)
  ;; lacarte-menu-items-alist, icicle-abs-file-candidates, icicle-acting-on-next/prev,
  ;; icicle-all-candidates-list-action-fn, icicle-all-candidates-list-alt-action-fn,
  ;; icicle-allowed-sort-predicate, icicle-apropos-complete-match-fn, icicle-buffer-name-input-p,
  ;; icicle-bufflist, icicle-candidate-action-fn, icicle-candidate-alt-action-fn, icicle-candidate-help-fn,
  ;; icicle-candidate-nb, icicle-candidates-alist, icicle-cands-to-narrow, icicle-cmd-reading-input,
  ;; icicle-command-abbrev-history, icicle-complete-keys-alist, icicle-completing-keys-p,
  ;; icicle-completing-p, icicle-completing-read+insert-candidates, icicle-completion-candidates,
  ;; icicle-compute-narrowing-regexp-p, icicle-confirm-exit-commands,
  ;; icicle-current-completion-candidate-overlay, icicle-current-completion-mode, icicle-current-input,
  ;; icicle-current-raw-input, icicle-cycling-p, icicle-default-thing-insertion-flipped-p,
  ;; icicle-edit-update-p, icicle-extra-candidates-dir-insert-p, icicle-full-cand-fn,
  ;; icicle-general-help-string, icicle-get-alist-candidate-function, icicle-hist-var,
  ;; icicle-ignored-extensions, icicle-ignored-extensions-regexp, icicle-incremental-completion-p,
  ;; icicle-inhibit-sort-p, icicle-input-completion-fail-overlay, icicle-input-fail-pos,
  ;; icicle-insert-string-at-pt-end, icicle-insert-string-at-pt-start,
  ;; icicle-last-apropos-complete-match-fn, icicle-last-completion-candidate,
  ;; icicle-last-completion-command, icicle-last-input, icicle-last-sort-comparer,
  ;; icicle-last-top-level-command, icicle-last-transform-function, icicle-list-use-nth-parts,
  ;; icicle-minibuffer-message-ok-p, icicle-mode-line-help, icicle-multi-completing-p,
  ;; icicle-multi-inputs-action-fn, icicle-must-pass-after-match-predicate, icicle-narrow-regexp,
  ;; icicle-nb-of-other-cycle-candidates, icicle-next-apropos-complete-cycles-p,
  ;; icicle-next-prefix-complete-cycles-p, icicle-orig-buff, icicle-orig-must-pass-after-match-pred,
  ;; icicle-orig-window, icicle-other-window, icicle-pref-arg, icicle-pre-minibuffer-buffer,
  ;; icicle-previous-raw-file-name-inputs, icicle-previous-raw-non-file-name-inputs,
  ;; icicle-progressive-completing-p, icicle-require-match-p, icicle-reverse-sort-p,
  ;; icicle-saved-candidates-variables-obarray, icicle-saved-completion-candidates,
  ;; icicle-saved-completion-candidates-internal, icicle-saved-ignored-extensions,
  ;; icicle-saved-proxy-candidates, icicle-scroll-Completions-reverse-p, icicle-search-complement-domain-p,
  ;; icicle-searching-p, icicle-search-replacement, icicle-successive-grab-count,
  ;; icicle-thing-at-pt-fns-pointer, icicle-universal-argument-map, icicle-use-candidates-only-once-alt-p,
  ;; icicle-whole-candidate-as-text-prop-p
(require 'icicles-fn)
  ;; icicle-minibuf-input-sans-dir, icicle-read-regexp, icicle-scan-fn-or-regexp, icicle-string-match-p,
  ;; icicle-toggle-icicle-mode-twice, icicle-unlist

(require 'doremi nil t) ;; (no error if not found):
                        ;; doremi, doremi(-boost)-(up|down)-keys, doremi-limit, doremi-wrap
(when (> emacs-major-version 22) (require 'help-fns+ nil t)) ;; (no error if not found):
                                                             ;; help-commands-to-key-buttons

(eval-when-compile (require 'fit-frame nil t)) ;; (no error if not found): fit-frame
(eval-when-compile
 (when (> emacs-major-version 21) (require 'linkd nil t))) ;; (no error if not found): linkd-mode

;; Byte-compiling this file, you will likely get some byte-compiler warning messages.
;; These are probably benign - ignore them.  Icicles is designed to work with multiple
;; versions of Emacs, and that fact provokes compiler warnings.  If you get byte-compiler
;; errors (not warnings), then please report a bug, using `M-x icicle-send-bug-report'.

;; Some defvars to quiet byte-compiler a bit:

(when (< emacs-major-version 22)
  (defvar icicle-Info-highlight-visited-nodes) ; In `icicles-opt.el' (for Emacs 22+)
  (defvar read-file-name-completion-ignore-case) ; In `minibuffer.el'
  (defvar read-file-name-predicate)
  (defvar tooltip-mode))

(when (< emacs-major-version 23)
  (defvar read-buffer-completion-ignore-case)
  (defvar mouse-drag-copy-region))

(defvar completion-base-position)       ; Emacs 23.2+.
(defvar count)                          ; Here.
(defvar doremi-boost-down-keys)         ; In `doremi.el'
(defvar doremi-boost-up-keys)           ; In `doremi.el'
(defvar doremi-down-keys)               ; In `doremi.el'
(defvar doremi-up-keys)                 ; In `doremi.el'
(defvar filesets-data)                  ; In `filesets.el'.
(defvar icicle-cand-preds)              ; Here.
(defvar icicle-ido-like-mode)           ; In `icicles-cmd2.el' (implicit)
(defvar icicle-Info-hist-list)          ; In `icicles-cmd2.el'
(defvar ignore-comments-flag)           ; In `hide-comnt.el'.
(defvar minibuffer-confirm-exit-commands) ; In `minibuffer.el' in Emacs 23+.
(defvar minibuffer-local-filename-completion-map) ; In Emacs 22+.
(defvar minibuffer-local-filename-must-match-map) ; In Emacs 23.2 (but not Emacs 24+).
(defvar minibuffer-local-must-match-filename-map) ; In Emacs 22+.
(defvar overriding-map-is-bound)        ; In Emacs 22-23.
(defvar recentf-list)                   ; In `recentf.el' (Emacs 21+).
(defvar saved-overriding-map)           ; In Emacs 22-23.
(defvar to-insert)                      ; Here.
(defvar universal-argument-num-events)  ; Emacs 22-24.3.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
;;(@* "Redefined standard commands")

;;; Redefined standard commands --------------------------------------


;; REPLACE ORIGINAL `next-history-element' in `simple.el',
;; saving it for restoration when you toggle `icicle-mode'.
;;
;; Selects minibuffer contents and leaves point at its beginning.
;;
(unless (fboundp 'icicle-ORIG-next-history-element)
  (defalias 'icicle-ORIG-next-history-element (symbol-function 'next-history-element)))

(defun icicle-next-history-element (arg) ; Bound to `M-n' in minibuffer.
  "Insert the next element of the minibuffer history in the minibuffer.
With argument N, it uses the Nth following element."
  (interactive "p")
  (icicle-ORIG-next-history-element (prefix-numeric-value arg))
  (when (and icicle-mode  (memq icicle-default-value '(preselect-start preselect-end)))
    (icicle-select-minibuffer-contents)
    (setq deactivate-mark  nil)))


;; REPLACE ORIGINAL `exit-minibuffer' (built-in function),
;; saving it for restoration when you toggle `icicle-mode'.
;;
;; Remove input mismatch highlighting.
;; Remove *Completion* window.
;;
(unless (fboundp 'icicle-ORIG-exit-minibuffer)
  (defalias 'icicle-ORIG-exit-minibuffer (symbol-function 'exit-minibuffer)))

(defun icicle-exit-minibuffer ()        ; Bound to `C-m' (`RET') in minibuffer.
  "Terminate this minibuffer argument.
Remove `*Completions*' window.  Remove Icicles minibuffer faces."
  ;; This removal lets users retrieve candidates that have other faces, and saves input-history space.
  (interactive)
  (when (active-minibuffer-window)
    (with-current-buffer (window-buffer (minibuffer-window))
      (let ((pos                (icicle-minibuffer-prompt-end))
            (icy-minibuf-faces  '(icicle-input-completion-fail  icicle-input-completion-fail-lax
                                  icicle-whitespace-highlight   icicle-match-highlight-minibuffer
                                  icicle-complete-input))
            (keep-faces         ()))
        (while (< pos (point-max))
          (let ((faces  (get-text-property pos 'face)))
            (when (or (and (consp faces)  (cdr faces)  (atom (cdr faces))) ; (background-color . "abc")
                      (and faces  (atom faces))) ; face name
              (setq faces  (list faces))) ; No-op: (foo (background-color . "abc") (:foreground "abc"))
            (setq keep-faces  (icicle-set-union keep-faces
                                                (icicle-set-difference faces icy-minibuf-faces))))
          (setq pos  (1+ pos)))
        ;; If KEEP-FACES is (), use `remove-text-properties' instead of just `put-text-property',
        ;; so we do not add a nil `face' property.
        (if keep-faces
            (put-text-property (icicle-minibuffer-prompt-end) (point-max) 'face keep-faces)
          (remove-text-properties (icicle-minibuffer-prompt-end) (point-max) '(face nil))))
      ;; $$$$$  (let ((pos  (icicle-minibuffer-prompt-end)))
      ;;     (while (< pos (point-max))
      ;;       (when (memq (get-text-property pos 'face)
      ;;                   '(icicle-input-completion-fail icicle-input-completion-fail-lax))
      ;;         (remove-text-properties pos (point-max) '(face))
      ;;         (setq pos  (point-max)))
      ;;       (setq pos  (1+ pos))))
      ))
  (icicle-remove-Completions-window)
  (icicle-ORIG-exit-minibuffer))


;; REPLACE ORIGINAL `minibuffer-complete-and-exit' (built-in function),
;; saving it for restoration when you toggle `icicle-mode'.
;;
;; Use Icicles completion.
;;
(unless (fboundp 'icicle-ORIG-minibuffer-complete-and-exit)
  (defalias 'icicle-ORIG-minibuffer-complete-and-exit (symbol-function 'minibuffer-complete-and-exit)))

;; Bound to `C-m' (`RET') in must-match minibuffer completion maps.
(defun icicle-minibuffer-complete-and-exit ()
  "If the minibuffer contents is a valid completion, then exit.
Otherwise try to complete it."
  (interactive)
  (let ((last-cmd  last-command))
    (cond ((string= "" (if (icicle-file-name-input-p) ;  Empty input - exit.
                           (icicle-minibuf-input-sans-dir)
                         (icicle-input-from-minibuffer)))
           (icicle-exit-minibuffer))
          ;; This case serves when property `icicle-display-string' is used.
          ;; What's returned is the replacement display string, not the original candidate.
          ;; If you want to get the original candidate back, you'll need to search the obarray for a
          ;; symbol that has this `icicle-display-string' value.  Or put the symbol on the display
          ;; string as a text property.
          ((icicle-input-is-a-completion-p) (icicle-exit-minibuffer))
          ((eq minibuffer-completion-confirm 'confirm) ; User wants it anyway? - Emacs 23+.
           (if (eq last-cmd this-command)
               (icicle-exit-minibuffer)
             (minibuffer-message "Confirm")
             nil))
          ((eq minibuffer-completion-confirm 'confirm-after-completion) ; Emacs 23+.
           ;; Similar to `confirm', but only if trying to exit immediately
           ;; after completing (this catches most minibuffer typos).
           (if (not (memq last-cmd (and (boundp 'minibuffer-confirm-exit-commands)
                                        (append icicle-confirm-exit-commands
                                                minibuffer-confirm-exit-commands))))
               (icicle-exit-minibuffer)
             (minibuffer-message "Confirm")
             nil))
          (t
           (setq icicle-current-input  (icicle-input-from-minibuffer))
           (let* (;; Bind these first two to suppress (a) the throw or (b) the message, highlighting,
                  ;; mode-line help, and the wait involved in completing again.
                  (icicle-prefix-complete-and-exit-p   t)
                  (icicle-apropos-complete-and-exit-p  t)

                  (candidates
                   ;; If we're not using `icicle-candidates-alist', complete the input again.
                   ;; If we're using `icicle-candidates-alist', try filtering it against just the
                   ;; input.
                   ;;   If the input is already complete, then we're done.  If not, then filtering
                   ;;   will give nil and we will just continue to display the candidates.  If there
                   ;;   are multiple matches, then the user can either cycle or complete again.
                   (if (not icicle-candidates-alist)
                       (if (eq icicle-current-completion-mode 'apropos)
                           (icicle-apropos-complete-no-display 'nomsg)
                         (icicle-prefix-complete-no-display 'nomsg))
                     (icicle-filter-alist icicle-candidates-alist (list icicle-current-input)))))
             (cond ((and (eq icicle-require-match-p t) ; Don't exit if non-nil and non-t.
                         (icicle-input-is-a-completion-p))
                    (icicle-exit-minibuffer))
                   (t
                    (icicle-display-candidates-in-Completions))))))))

;;; $$$$$$ Should probably rename it.  It's no longer necessarily about apropos completion.
(defun icicle-apropos-complete-and-exit () ; Bound to `S-return' (`S-RET') in minibuffer completion maps.
  "If minibuffer content is a valid completion or has a single match, exit.
If the content is not complete, try to complete it.  If completion
leads to a valid completion, then exit.

This differs from `icicle-minibuffer-complete-and-exit' (bound to
`RET' in must-match minibuffer maps) in these ways:

 * If there is only one completion, this completes the input, rather
   than accepting it uncompleted.
 * This does not bother with the various special cases: empty input or
   non-nil `minibuffer-completion-confirm' values."
  (interactive)
  (setq icicle-current-input  (icicle-input-from-minibuffer))
  (let* (;; Bind these first two to suppress (a) the throw or (b) the message, highlighting,
         ;; mode-line help, and the wait involved in completing again.
         (icicle-prefix-complete-and-exit-p   t)
         (icicle-apropos-complete-and-exit-p  t)
         (candidates
          ;; If we're not using `icicle-candidates-alist', complete the input again.
          ;; If we're using `icicle-candidates-alist', try filtering it against just the
          ;; input.
          ;;   If the input is already complete, then we're done.  If not, then filtering
          ;;   will give nil and we will just continue to display the candidates.  If there
          ;;   are multiple matches, then the user can either cycle or complete again.
          (if (not icicle-candidates-alist)
              (if (eq icicle-current-completion-mode 'apropos)
                  (icicle-apropos-complete-no-display 'nomsg)
                (icicle-prefix-complete-no-display 'nomsg))
            (icicle-filter-alist icicle-candidates-alist (list icicle-current-input)))))
    (when (and candidates  (null (cdr candidates))) (icicle-ORIG-exit-minibuffer)))) ; Single candidate.


;; REPLACE ORIGINAL `choose-completion' in `simple.el',
;; saving it for restoration when you toggle `icicle-mode'.
;;
;; Return the number of the completion.
;; Do not remove text properties from candidate.
;; Respect `icicle-extra-candidates' and `icicle-extra-candidates-dir-insert-p'.
;; Adjust to `icicle-start-of-candidates-in-Completions'.
;; Do not use `completion-list-insert-choice-function'.
;; Do not iconify frame or bury buffer (in Emacs 23-24.2 code).
;; Do not quit *Completions* window (Emacs 24.3+).
;;
(unless (fboundp 'icicle-ORIG-choose-completion)
  (defalias 'icicle-ORIG-choose-completion (symbol-function 'choose-completion)))

(if (or (> emacs-major-version 23)
        (and (= emacs-major-version 23)  (> emacs-minor-version 1))) ; Emacs 23.2+
    (defun icicle-choose-completion (&optional event)
      "Choose the completion at point.
Return the number of the candidate: 0 for first, 1 for second, ..."
      (interactive (list last-nonmenu-event))
      ;; In case this is run via the mouse, give temporary modes such as Isearch a chance to turn off.
      (run-hooks 'mouse-leave-buffer-hook)
      (with-current-buffer (window-buffer (posn-window (event-start event)))
        (let ((buffer           completion-reference-buffer)
              (base-size        completion-base-size)
              (choice
               (save-excursion
                 (goto-char (posn-point (event-start event)))
                 (let (beg end)
                   (cond ((and (not (eobp))  (get-text-property (point) 'mouse-face))
                          (setq end  (point)
                                beg  (1+ (point))))
                         ((and (>= (point) (icicle-start-of-candidates-in-Completions))
                               (get-text-property (max (point-min) (1- (point))) 'mouse-face))
                          (setq end  (max (point-min) (1- (point)))
                                beg  (point)))
                         (t (icicle-user-error "No candidate here")))
                   (setq beg  (previous-single-property-change beg 'mouse-face)
                         end  (or (next-single-property-change end 'mouse-face)  (point-max)))
                   (buffer-substring beg end)))))
          (unless (or (not (member choice icicle-extra-candidates))  icicle-extra-candidates-dir-insert-p)
            (setq base-size  0))
          (setq icicle-candidate-nb  (icicle-nb-of-cand-at-Completions-pos
                                      (posn-point (event-start event))))
          (unless (buffer-live-p buffer) (icicle-user-error "Destination buffer is dead"))
          (when (and (icicle-file-name-input-p)  insert-default-directory
                     (or (not (member choice icicle-extra-candidates))
                         icicle-extra-candidates-dir-insert-p))
            (let ((dir  (icicle-file-name-directory-w-default icicle-current-input)))
              (with-current-buffer buffer
                (icicle-clear-minibuffer)
                (insert dir)
                (setq choice     (concat dir choice)
                      base-size  0))))
          ;; $$$$$$$$ (icicle-choose-completion-string choice buffer base-size))
          (with-current-buffer buffer (icicle-choose-completion-string choice buffer base-size)))
        icicle-candidate-nb))

  (defun icicle-choose-completion ()    ; Emacs < 23.2.
    "Choose the completion that point is in or next to."
    (interactive)
    (let ((buffer     completion-reference-buffer)
          (base-size  completion-base-size)
          beg end choice)
      (when (and (not (eobp))  (get-text-property (point) 'mouse-face))
        (setq end  (point)
              beg  (1+ (point))))
      (when (and (>= (point) (icicle-start-of-candidates-in-Completions))
                 (get-text-property (max (point-min) (1- (point))) 'mouse-face))
        (setq end  (max (point-min) (1- (point)))
              beg  (point)))
      (unless beg       (icicle-user-error "No completion here"))
      (setq beg     (previous-single-property-change beg 'mouse-face)
            end     (or (next-single-property-change end 'mouse-face)  (point-max))
            ;; $$$$ choice  (buffer-substring-no-properties beg end))
            choice  (buffer-substring beg end))
      ;; (let ((owindow  (selected-window)))
      ;;   (if (and (one-window-p t 'selected-frame)  (window-dedicated-p (selected-window)))
      ;;    (iconify-frame (selected-frame)) ; Iconify special buffer's frame
      ;;  (or (window-dedicated-p (selected-window))  (bury-buffer)))
      ;;   (select-window owindow))
      (unless (or (not (member choice icicle-extra-candidates))
                  icicle-extra-candidates-dir-insert-p)
        (setq base-size  0))
      (unless (buffer-live-p buffer) (icicle-user-error "Destination buffer is dead"))
      (icicle-choose-completion-string choice buffer base-size))))


;; REPLACE ORIGINAL `mouse-choose-completion' in `mouse.el',
;; saving it for restoration when you toggle `icicle-mode'.
;;
;; Return the number of the completion.
;; Don't strip text properties.
;;
(when (and (fboundp 'mouse-choose-completion)  (not (fboundp 'icicle-ORIG-mouse-choose-completion)))
  (defalias 'icicle-ORIG-mouse-choose-completion (symbol-function 'mouse-choose-completion)))

(unless (or (> emacs-major-version 23)  (and (= emacs-major-version 23) ; < Emacs 23.2
                                             (> emacs-minor-version 1)))
  (defun icicle-mouse-choose-completion (event) ; Bound to `mouse-2' in `*Completions*'.
    "Click a completion candidate in buffer `*Completions*', to choose it.
Return the number of the candidate: 0 for first, 1 for second, ..."
    (interactive "e")
    ;; $$$$$ (unless (active-minibuffer-window) (icicle-user-error "Minibuffer is not active"))
    ;; Give temporary modes such as isearch a chance to turn off.
    (run-hooks 'mouse-leave-buffer-hook)
    (let ((buffer  (window-buffer))
          ;; $$$$$$ (icicle-orig-buff  buffer)
          choice base-size)
      (with-current-buffer (window-buffer (posn-window (event-start event)))
        (save-excursion
          (when completion-reference-buffer (setq buffer  completion-reference-buffer))
          (setq base-size  completion-base-size)
          (save-excursion
            (goto-char (posn-point (event-start event)))
            (let (beg end)
              (when (and (not (eobp))  (get-text-property (point) 'mouse-face))
                (setq end  (point)
                      beg  (1+ (point))))
              (unless beg (icicle-user-error "No completion here"))
              (setq beg  (previous-single-property-change beg 'mouse-face)
                    end  (or (next-single-property-change end 'mouse-face)  (point-max)))
              ;; $$$$$$ (setq choice  (buffer-substring-no-properties beg end)))))
              (setq choice  (buffer-substring beg end))))))
      ;; $$$$$ (if (eq icicle-orig-buff (get-buffer "*Completions*"))
      ;;    (icicle-remove-Completions-window)
      ;;    (save-selected-window (icicle-remove-Completions-window)))
      (setq icicle-candidate-nb  (icicle-nb-of-cand-at-Completions-pos (posn-point (event-start event))))
      (unless (buffer-live-p buffer) (icicle-user-error "Destination buffer is dead"))
      (when (and (icicle-file-name-input-p)  insert-default-directory
                 (or (not (member choice icicle-extra-candidates))
                     icicle-extra-candidates-dir-insert-p))
        (let ((dir  (icicle-file-name-directory-w-default icicle-current-input)))
          (with-current-buffer buffer
            (icicle-clear-minibuffer)
            (insert dir)
            (setq choice     (concat dir choice)
                  base-size  0))))
      (icicle-choose-completion-string choice buffer base-size))
    icicle-candidate-nb))

(defun icicle-nb-of-cand-at-Completions-pos (position)
  "Return number of candidate at POSITION in `*Completions*'.
POSITION is a buffer position."
  (let ((hor-nb  (icicle-nb-of-cand-in-Completions-horiz position)))
    (save-excursion
      (with-current-buffer (get-buffer "*Completions*")
        (goto-char position)
        (if (memq icicle-completions-format '(horizontal nil))
            hor-nb
          (let* ((cols      (icicle-nb-Completions-cols))
                 (nb-cands  (length icicle-completion-candidates))
                 (rows      (/ nb-cands cols)))
            (unless (zerop (% nb-cands cols)) (setq rows  (1+ rows)))
            (icicle-column-wise-cand-nb hor-nb nb-cands rows cols)))))))

(defun icicle-nb-of-cand-in-Completions-horiz (position)
  "Return number of horizontal candidate at POSITION in `*Completions*'.
POSITION is a buffer position."
  (let ((compl-buf  (get-buffer "*Completions*")))
    (unless compl-buf (error "No `*Completions*' buffer"))
    (save-window-excursion
      (set-buffer compl-buf)
      (goto-char position)
      ;; If in a completion, move to its start, and set POSITION there.
      (let ((prop  (get-text-property (max (point-min) (1- (point))) 'mouse-face)))
        (when (and prop  (eq prop (get-text-property (point) 'mouse-face)))
          (goto-char (previous-single-property-change (point) 'mouse-face nil
                                                      (icicle-start-of-candidates-in-Completions)))))
      (setq position  (point))
      ;; Binary search.
      (let ((cand-nb                             (/ (length icicle-completion-candidates) 2))
            (last-nb                             0)
            (icicle-completions-format           'horizontal)
            delta)
        (goto-char (point-min))
        (icicle-move-to-next-completion cand-nb t)
        (while (/= (point) position)
          (setq delta    (max 1 (/ (abs (- cand-nb last-nb)) 2))
                last-nb  cand-nb)
          (cond ((< (point) position)
                 (icicle-move-to-next-completion delta t)
                 (setq cand-nb  (+ cand-nb delta)))
                (t
                 (icicle-move-to-next-completion (- delta) t)
                 (setq cand-nb  (- cand-nb delta)))))
        (set-buffer-modified-p nil)
        (1- cand-nb)))))

(defun icicle-nb-Completions-cols ()
  "Return the number of candidate columns in `*Completions*'."
  (let* ((start       (icicle-start-of-candidates-in-Completions))
         (eol         (save-excursion (goto-char start) (line-end-position)))
         (mouse-chgs  0)
         mousef)
    (save-excursion
      (goto-char start)
      (while (< (point) eol)
        (setq mousef  (next-single-property-change (point) 'mouse-face nil eol))
        (when mousef
          (goto-char mousef)
          (setq mouse-chgs  (1+ mouse-chgs)))))
    ;; Handle the case where the `while' loop is skipped so `mouse-chgs' is still 0.
    (max 1 (/ (1+ mouse-chgs) 2))))     ; Return # of columns.

(defun icicle-column-wise-cand-nb (horiz-nb nb-cands rows cols)
  "Column-wise number of horizontal candidate number HORIZ-NB."
  (let ((row-lim  (- rows (- (* rows cols) nb-cands)))
        (row      (/ horiz-nb cols))
        (col      (mod horiz-nb cols))
        nb)
    (setq nb  (+ row (* col rows)))
    (when (>= row row-lim)
      (setq cols      (1- cols)
            horiz-nb  (- horiz-nb row-lim)
            row       (/ horiz-nb cols)
            col       (mod horiz-nb cols)
            nb        (+ row (* col rows))))
    nb))

(defun icicle-row-wise-cand-nb (vert-nb nb-cands rows cols)
  "Row-wise number of vertical candidate number VERT-NB."
  (let* ((row  (mod vert-nb rows))
         (col  (/ vert-nb rows))
         (nb   (+ col (* row cols)))
         (lim  (- rows (- (* rows cols) nb-cands))))
    (when (> row lim) (setq nb  (- nb (- row lim))))
    nb))


;; REPLACE ORIGINAL `switch-to-completions' defined in `simple.el',
;; saving it for restoration when you toggle `icicle-mode'.
;;
;; Selects `*Completions*' window even if on another frame.
;;
(unless (fboundp 'icicle-ORIG-switch-to-completions)
  (defalias 'icicle-ORIG-switch-to-completions (symbol-function 'switch-to-completions)))

(defun icicle-switch-to-completions ()
  "Select the completion list window, `*Completions*'."
  (interactive)
  ;; Make sure we have a completions window.
  (or (get-buffer-window "*Completions*")  (minibuffer-completion-help))
  (let ((window  (get-buffer-window "*Completions*" 0))) ; Added 0 arg.
    (when window
      (select-window window)
      (goto-char (icicle-start-of-candidates-in-Completions)))))

;; The branch that deletes a history element is based on Juri Linkov's
;; `delete-history-element', proposed for Emacs 22 but rejected by RMS.
;;
(defun icicle-erase-minibuffer-or-history-element () ; Bound to `M-k' in minibuffer.
  "`icicle-erase-minibuffer' or, if using history, delete history element."
  (interactive)
  (if (not (memq last-command '(previous-history-element next-history-element
                                icicle-erase-minibuffer-or-history-element
                                previous-matching-history-element next-matching-history-element)))
      (icicle-erase-minibuffer)
    (let* ((curr-pos  (1- minibuffer-history-position))
           (current   (nth curr-pos (and (boundp minibuffer-history-variable)
                                         (symbol-value minibuffer-history-variable)))))
      (cond ((= minibuffer-history-position 1)
             (set minibuffer-history-variable (and (boundp minibuffer-history-variable)
                                                   (cdr (symbol-value minibuffer-history-variable)))))
            ((> minibuffer-history-position 1)
             (setcdr (nthcdr (- minibuffer-history-position 2)
                             (and (boundp minibuffer-history-variable)
                                  (symbol-value minibuffer-history-variable)))
                     (nthcdr minibuffer-history-position
                             (and (boundp minibuffer-history-variable)
                                  (symbol-value minibuffer-history-variable))))))
      (condition-case nil
          (cond ((memq last-command '(next-history-element next-matching-history-element))
                 (next-history-element 1)
                 (setq this-command  'next-history-element))
                ((memq last-command '(previous-history-element previous-matching-history-element))
                 (next-history-element 1)
                 (previous-history-element 1)
                 (setq this-command  'previous-history-element)))
        (error (icicle-condition-case-no-debug nil
                   (cond ((memq last-command '(next-history-element next-matching-history-element))
                          (previous-history-element 1)
                          (setq this-command  'previous-history-element))
                         ((memq last-command
                                '(previous-history-element previous-matching-history-element))
                          (next-history-element 1)
                          (setq this-command  'next-history-element)))
                 (error nil))))
      (when (and current  (wholenump curr-pos))
        (icicle-msg-maybe-in-minibuffer "Deleted `%s'"
                                        (icicle-propertize current 'face 'icicle-msg-emphasis))))))
 
;;(@* "Icicles commands")

;;; Icicles commands -------------------------------------------------


;;(@* "Minibuffer editing commands")

;;; Minibuffer editing commands  . . . . . . . . . . . . . . . . . . .
;;;
;;; All except `icicle-erase-minibuffer' are bound in the minibuffer to whatever the same
;;; command without `icicle-' is bound to globally.


;; Same as `bmkp-looking-at-p' in `bookmark+-bmu.el'.
;; Do not `defalias' to Emacs `looking-at-p' because it is a `defsubst'.
(defun icicle-looking-at-p (regexp)
  "Like `looking-at', but this saves and restores the match data."
  (save-match-data (looking-at regexp)))

(defun icicle-looking-at-literally-p (string)
  "Return non-nil if STRING immediately precedes point."
  (save-match-data (looking-at (regexp-quote string))))

(defun icicle-looking-back-at-literally-p (string)
  "Return non-nil if STRING immediately precedes point.  STRING is
matched literally - not as a regexp.  In this the function is like
`icicle-looking-at-literally-p', not `icicle-looking-at-p'.
Saves and restores the match data."
  (let ((len  (length string)))
    (save-excursion (save-match-data
                      (search-backward string (max (- (point) len) (icicle-minibuffer-prompt-end)) t)))))

;; Used only in `icicle-transpose-chars-magic'.
(defun icicle-forward-char-magic (&optional n)
  "Move forward N chars (backward if N is negative).
Handles Icicles dots (`.') and `icicle-list-join-string'."
  (interactive "p")
  (let ((len-dot   (length icicle-anychar-regexp))
        (len-join  (length icicle-list-join-string)))
    (save-restriction
      (narrow-to-region (icicle-minibuffer-prompt-end) (point-max))
      (condition-case nil               ; Ignore errors, e.g. `beginning-of-buffer' from `(forward-char -1)'.
          (dotimes (i  (abs n))
            (or (save-match-data
                  (if (wholenump n)
                      (search-forward icicle-anychar-regexp (min (+ (point) len-dot) (point-max)) t)
                    (search-backward icicle-anychar-regexp (max (- (point) len-dot) (point-min)) t)))
                (save-match-data
                  (if (wholenump n)
                      (search-forward icicle-list-join-string (min (+ (point) len-join) (point-max)) t)
                    (search-backward icicle-list-join-string (max (- (point) len-join) (point-min)) t)))
                (forward-char (if (wholenump n) 1 -1))))
        (error nil)))))

;; Not used.
(defun icicle-backward-char-magic (&optional n)
  "Move backward N chars (forward if N is negative).
Handles Icicles dots (`.') and `icicle-list-join-string'."
  (interactive "p")
  (icicle-forward-char-magic (- n)))


;; Make delete-selection mode recognize it, so region is deleted.
(put 'icicle-backward-delete-char-untabify 'delete-selection 'supersede)

(defun icicle-backward-delete-char-untabify (n &optional killflag)
  "`backward-delete-char-untabify' + update `*Completions*' with matches.
Handles Icicles dots (`.') and `icicle-list-join-string'."
  (interactive "*p\nP")
  (icicle-call-then-update-Completions #'icicle-backward-delete-char-untabify-magic n killflag))

(defun icicle-backward-delete-char-untabify-magic (n killflag)
  "`backward-delete-char-untabify', but also handle magic chars.
That is, handle dots (`.') and `icicle-list-join-string'."
  (let ((len-dot   (length icicle-anychar-regexp))
        (len-join  (length icicle-list-join-string)))
    (dotimes (i  (abs n))
      (cond ((icicle-looking-back-at-literally-p icicle-anychar-regexp)
             (backward-delete-char-untabify len-dot  killflag))
            ((icicle-looking-back-at-literally-p icicle-list-join-string)
             (backward-delete-char-untabify len-join killflag))
            (t
             (backward-delete-char-untabify 1        killflag))))))


;; Make delete-selection mode recognize it, so region is deleted.
(put 'icicle-delete-backward-char 'delete-selection 'supersede)

(defun icicle-delete-backward-char (n &optional killflag) ; Bound to `DEL' in minibuffer.
  "`delete-backward-char' and update `*Completions*' with input matches.
Handles Icicles dots (`.') and `icicle-list-join-string'."
  (interactive "*p\nP")
  (icicle-call-then-update-Completions #'icicle-delete-backward-char-magic n killflag))

(defun icicle-delete-backward-char-magic (n killflag)
  "`delete-backward-char', but also handle dots (`.') and join string."
  (let ((len-dot   (length icicle-anychar-regexp))
        (len-join  (length icicle-list-join-string)))
    (dotimes (i  (abs n))
      (cond ((icicle-looking-back-at-literally-p icicle-anychar-regexp)
             (delete-char (- len-dot)  killflag))
            ((icicle-looking-back-at-literally-p icicle-list-join-string)
             (delete-char (- len-join) killflag))
            (t
             (delete-char -1           killflag))))))


;; Make delete-selection mode recognize it, so region is deleted.
(put 'icicle-delete-char 'delete-selection 'supersede)

(defun icicle-delete-char (n &optional killflag) ; Bound to `C-d' in minibuffer.
  "`delete-char' and update `*Completions*' with input matches.
Handles Icicles dots (`.') and `icicle-list-join-string'."
  (interactive "*p\nP")
  (icicle-call-then-update-Completions #'icicle-delete-char-magic n killflag))

(defun icicle-delete-char-magic (n killflag)
  "`delete-char', but also handle dot (`.') and `icicle-list-join-string'."
  (let ((len-dot   (length icicle-anychar-regexp))
        (len-join  (length icicle-list-join-string)))
    (dotimes (i  (abs n))
      (cond ((icicle-looking-at-literally-p icicle-anychar-regexp)
             (delete-char len-dot  killflag))
            ((icicle-looking-at-literally-p icicle-list-join-string)
             (delete-char len-join killflag))
            (t
             (delete-char 1        killflag))))))

(defun icicle-backward-kill-word (arg)  ; Bound to `M-DEL' (`M-backspace') in minibuffer.
  "`backward-kill-word' and update `*Completions*' with input matches.
See description of `backward-kill-word'."
  (interactive "p")
  (icicle-call-then-update-Completions #'backward-kill-word arg))

(defun icicle-kill-word (arg)           ; Bound to `M-d' in minibuffer.
  "`kill-word' and update `*Completions*' with regexp input matches.
See description of `kill-word'."
  (interactive "p")
  (icicle-call-then-update-Completions #'kill-word arg))

(defun icicle-backward-kill-sexp (arg)  ; Bound to `C-M-backspace' in minibuffer.
  "`backward-kill-sexp' and update `*Completions*' with input matches.
See description of `backward-kill-sexp'."
  (interactive "p")
  (icicle-call-then-update-Completions #'backward-kill-sexp arg))

(defun icicle-kill-sexp (arg)           ; Bound to `C-M-delete' and `C-M-k' in minibuffer.
  "`kill-sexp' and update `*Completions*' with regexp input matches.
See description of `kill-sexp'."
  (interactive "p")
  (icicle-call-then-update-Completions #'kill-sexp arg))

(defun icicle-backward-kill-sentence (arg) ; Bound to `C-x DEL' in minibuffer.
  "`backward-kill-sentence' and update `*Completions*' with input matches.
See description of `backward-kill-sentence'."
  (interactive "p")
  (icicle-call-then-update-Completions #'backward-kill-sentence arg))

(defun icicle-kill-sentence (arg)
  "`kill-sentence' and update `*Completions*' with regexp input matches.
See description of `kill-sentence'."
  (interactive "p")
  (icicle-call-then-update-Completions #'kill-sentence arg))

(defun icicle-backward-kill-paragraph (arg) ; Bound to `C-backspace' in minibuffer, except for files.
  "`backward-kill-paragraph' and update `*Completions*' with input matches.
See description of `backward-kill-paragraph'."
  (interactive "p")
  (icicle-call-then-update-Completions #'backward-kill-paragraph arg))

(defun icicle-kill-paragraph (arg)      ; Bound to `C-delete' in minibuffer.
  "`kill-paragraph' and update `*Completions*' with regexp input matches.
See description of `kill-paragraph'."
  (interactive "p")
  (icicle-call-then-update-Completions #'kill-paragraph arg))

(defun icicle-kill-line (arg)           ; Bound to `C-k' and `deleteline' in minibuffer.
  "`kill-line' and update `*Completions*' with regexp input matches.
See description of `kill-line'."
  (interactive "P")
  (icicle-call-then-update-Completions #'kill-line arg))

(defun icicle-kill-region (beg end)     ; Bound to `C-w' in minibuffer.
;; Don't bother with Emacs 22 optional 3rd arg.
  "`kill-region' and update `*Completions*' with regexp input matches.
See description of `kill-region'."
  (interactive "r")
  (icicle-call-then-update-Completions #'kill-region beg end))

(when (fboundp 'kill-region-wimpy)
  (defun icicle-kill-region-wimpy (beg end) ; Bound to `C-w' in minibuffer.
    "`kill-region-wimpy' and update `*Completions*' with input matches.
See description of `kill-region-wimpy'."
    (interactive "r")
    (icicle-call-then-update-Completions #'kill-region-wimpy beg end)))

(defun icicle-complete-current-candidate-as-input ()
  "Complete the current candidate as if it were your input pattern.
Use this to descend into a directory candidate, replacing the current
set of candidates by the contents of that directory.

If not completing file names or the current candidate does not name a
directory, then this just makes the candidate the sole candidate."
  (interactive)
  (when (interactive-p) (icicle-barf-if-outside-Completions-and-minibuffer))
  (when (eq (current-buffer) (get-buffer "*Completions*")) (icicle-insert-completion))
  (setq icicle-cycling-p  nil)
  (end-of-line)
  (funcall (or icicle-last-completion-command  (if (eq icicle-current-completion-mode 'prefix)
                                                   #'icicle-prefix-complete
                                                 #'icicle-apropos-complete))))

(defun icicle-dispatch-C-M-/ ()
  "Do the right thing for `C-M-/'.
If the minibuffer is active then invoke
 `icicle-complete-current-candidate-as-input'.
Otherwise, invoke `icicle-dabbrev-completion' (or
 `dabbrev-completion')."
  (interactive)
  (call-interactively (if (active-minibuffer-window)
                          #'icicle-complete-current-candidate-as-input
                        (if (fboundp 'icicle-dabbrev-completion)
                            'icicle-dabbrev-completion
                          'dabbrev-completion))))
        
(defun icicle-make-directory (dir)      ; Bound to `C-c +' in minibuffer, for file-name completion.
  "Create a directory."
  (interactive
   (let ((candidates                     icicle-completion-candidates)
         (minibuffer-completion-confirm  minibuffer-completion-confirm) ; `read-directory-name' messes it.
         (enable-recursive-minibuffers   t))
     (unwind-protect
          (list (funcall
                 (if (fboundp 'read-directory-name) #'read-directory-name #'read-file-name)
                 "Create directory: " default-directory (icicle-file-name-directory-w-default
                                                         (icicle-input-from-minibuffer))))
       (setq icicle-completion-candidates  candidates))))
  (setq dir  (directory-file-name (expand-file-name dir)))
  (let ((candidates                      icicle-completion-candidates)
         (minibuffer-completion-confirm  minibuffer-completion-confirm) ; `read-directory-name' messes it.
        (enable-recursive-minibuffers    t))
    (while (file-exists-p dir)          ; This will cause Tramp to access if remote, but that's OK here.
      (message "%s already exists" dir) (sit-for 1)
      (unwind-protect
           (setq dir  (funcall (if (fboundp 'read-directory-name) #'read-directory-name #'read-file-name)
                               "Create directory: " default-directory (icicle-file-name-directory-w-default
                                                                       (icicle-input-from-minibuffer))))
        (setq icicle-completion-candidates  candidates))))
  ;;(setq dir  (directory-file-name (expand-file-name dir)))
  (if (not (y-or-n-p (format "Really create %s? " (file-name-as-directory dir))))
      (message "Directory creation canceled")
    (make-directory dir 'PARENTS-TOO)
    (unless (file-accessible-directory-p dir) (error "Could not create %s" (file-name-as-directory dir)))
    (message "Created %s" (file-name-as-directory dir))))

(defun icicle-up-directory () ; Bound to `C-backspace' in minibuffer, for file-name completion.
  "Replace minibuffer input with parent directory, then upate `*Completions*'."
  (interactive)
  (icicle-call-then-update-Completions #'icicle-replace-input-w-parent-dir))

(defun icicle-replace-input-w-parent-dir ()
  "Replace minibuffer input with the parent directory."
  (interactive)
  (goto-char (point-max))
  (let ((directoryp  (equal ?/ (char-before)))
        (bob         (icicle-minibuffer-prompt-end)))
    (while (and (> (point) bob)  (not (equal ?/ (char-before))))  (delete-char -1))
    (when directoryp
      (delete-char -1)
      (while (and (> (point) bob)  (not (equal ?/ (char-before))))  (delete-char -1)))))

(defun icicle-file-all-tags-narrow ()   ; Bound to `C-x C-t *' in minibuffer, for file-name completion.
  "Narrow file-name candidates to those with all of the tags you specify.
You are prompted for the tags.
You can add and remove tags for a file during completion, using
 `C-x a +' and `C-x a -', respectively.
See also top-level command `icicle-find-file-tagged'."
  (interactive)
  (unless icicle-completion-candidates
    (icicle-user-error "No completion candidates.  Did you use `TAB' or `S-TAB'?"))
  (unless (require 'bookmark+ nil t) (icicle-user-error "You need library `Bookmark+' for this command"))
  (let* ((candidates                    icicle-completion-candidates)
         (enable-recursive-minibuffers  t)
         (tags                          (bmkp-read-tags-completing nil nil current-prefix-arg))
         (pred                          `(lambda (ff)
                                          (let* ((bmk   (bmkp-get-autofile-bookmark ff))
                                                 (btgs  (and bmk  (bmkp-get-tags bmk))))
                                            (and btgs  (bmkp-every (lambda (tag) (bmkp-has-tag-p bmk tag))
                                                                   ',tags))))))
    (setq icicle-completion-candidates  candidates)
    (icicle-narrow-candidates-with-predicate pred)))

(defun icicle-file-all-tags-regexp-narrow () ; Bound to `C-x C-t % *' in minibuf, for file-name completion.
  "Narrow file-name candidates to those with all tags matching a regexp.
You are prompted for the regexp.
You can add and remove tags for a file during completion, using
 `C-x a +' and `C-x a -', respectively.
See also top-level command `icicle-find-file-all-tags-regexp'."
  (interactive)
  (unless icicle-completion-candidates
    (icicle-user-error "No completion candidates.  Did you use `TAB' or `S-TAB'?"))
  (unless (require 'bookmark+ nil t) (icicle-user-error "You need library `Bookmark+' for this command"))
  (bookmark-maybe-load-default-file)
  (let* ((candidates                    icicle-completion-candidates)
         (enable-recursive-minibuffers  t)
         (regexp                        (icicle-read-regexp "Regexp for tags: "))
         (pred                          `(lambda (ff)
                                          (let* ((bmk   (bmkp-get-autofile-bookmark ff))
                                                 (btgs  (and bmk  (bmkp-get-tags bmk))))
                                            (and btgs  (bmkp-every
                                                        (lambda (tag)
                                                          (string-match ',regexp (bmkp-tag-name tag)))
                                                        btgs))))))
    (setq icicle-completion-candidates  candidates)
    (icicle-narrow-candidates-with-predicate pred)))

(defun icicle-file-some-tags-narrow ()  ; Bound to `C-x C-t +' in minibuffer, for file-name completion.
  "Narrow file-name candidates to those with some of the tags you specify.
You are prompted for the tags.
You can add and remove tags for a file during completion, using
 `C-x a +' and `C-x a -', respectively.
See also top-level command `icicle-find-file-tagged'."
  (interactive)
  (unless icicle-completion-candidates
    (icicle-user-error "No completion candidates.  Did you use `TAB' or `S-TAB'?"))
  (unless (require 'bookmark+ nil t) (icicle-user-error "You need library `Bookmark+' for this command"))
  (let* ((candidates                    icicle-completion-candidates)
         (enable-recursive-minibuffers  t)
         (tags                          (bmkp-read-tags-completing nil nil current-prefix-arg))
         (pred                          `(lambda (ff)
                                          (let* ((bmk   (bmkp-get-autofile-bookmark ff))
                                                 (btgs  (and bmk  (bmkp-get-tags bmk))))
                                            (and btgs  (bmkp-some (lambda (tag) (bmkp-has-tag-p bmk tag))
                                                                  ',tags))))))
    (setq icicle-completion-candidates  candidates)
    (icicle-narrow-candidates-with-predicate pred)))

(defun icicle-file-some-tags-regexp-narrow () ; Bound to `C-x C-t % +' in minibuf, for file-name completion.
  "Narrow file-name candidates to those with some tags matching a regexp.
You are prompted for the regexp.
You can add and remove tags for a file during completion, using
 `C-x a +' and `C-x a -', respectively.
See also top-level command `icicle-find-file-some-tags-regexp'."
  (interactive)
  (unless icicle-completion-candidates
    (icicle-user-error "No completion candidates.  Did you use `TAB' or `S-TAB'?"))
  (unless (require 'bookmark+ nil t) (icicle-user-error "You need library `Bookmark+' for this command"))
  (bookmark-maybe-load-default-file)
  (let* ((candidates                    icicle-completion-candidates)
         (enable-recursive-minibuffers  t)
         (regexp                        (icicle-read-regexp "Regexp for tags: "))
         (pred                          `(lambda (ff)
                                          (let* ((bmk   (bmkp-get-autofile-bookmark ff))
                                                 (btgs  (and bmk  (bmkp-get-tags bmk))))
                                            (and btgs  (bmkp-some
                                                        (lambda (tag)
                                                          (string-match ',regexp (bmkp-tag-name tag)))
                                                        btgs))))))
    (setq icicle-completion-candidates  candidates)
    (icicle-narrow-candidates-with-predicate pred)))

;;; (defun icicle-kill-failed-input ()      ; Bound to `C-M-l' in minibuffer during completion.
;;;   "Kill (delete) the part of the input that does not complete.
;;; Repeat to delete more."
;;;   (interactive)
;;;   (goto-char (max (point-min) (1- (point))))
;;;   (while (and (not (bobp))
;;;               (memq (get-text-property (point) 'face)
;;;                     '(icicle-input-completion-fail icicle-input-completion-fail-lax)))
;;;     (delete-char 1)
;;;     (backward-char 1))
;;;   (unless (eobp) (forward-char))
;;;   (icicle-highlight-input-noncompletion))

(defun icicle-goto/kill-failed-input () ; Bound to `C-M-l' in minibuffer during completion.
  "Go to start of input portion that does not complete.  Repeat to kill.
Kill (delete) the part of the input that does not complete.
Repeat to delete more."
  (interactive)
  (if (eq last-command this-command)
      (unless (eobp) (kill-line))
    (when (and (overlayp icicle-input-completion-fail-overlay)
               (overlay-start icicle-input-completion-fail-overlay))
      (goto-char (overlay-start icicle-input-completion-fail-overlay)))))

(defun icicle-transpose-chars (arg)     ; Bound to `C-t' in minibuffer.
  "`transpose-chars' and update `*Completions*' with regexp input matches.
Handles Icicles dots (`.') and `icicle-list-join-string'."
  (interactive "*P")
  (icicle-call-then-update-Completions #'icicle-transpose-chars-magic arg))

(defun icicle-transpose-chars-magic (arg)
  "`transpose-chars', but handle dots (`.') and `icicle-list-join-string'."
  (and (null arg)  (eolp)  (icicle-forward-char-magic -1))
  (transpose-subr 'icicle-forward-char-magic (prefix-numeric-value arg)))

(defun icicle-transpose-words (arg)     ; Bound to `M-t' in minibuffer.
  "`transpose-words' and update `*Completions*' with regexp input matches.
See description of `transpose-words'."
  (interactive "*p")
  (icicle-call-then-update-Completions #'transpose-words arg))

(defun icicle-transpose-sexps (arg)    ; Bound to `C-M-t' in minibuffer.
  "`transpose-sexps' and update `*Completions*' with regexp input matches.
See description of `transpose-sexps'."
  (interactive "*p")
  (icicle-call-then-update-Completions #'transpose-sexps arg))

(defun icicle-yank (arg)                ; Bound to `C-y' and `S-insert' in minibuffer.
  "`yank' and update `*Completions*' with regexp input matches.
See description of `yank'."
  (interactive "*P")
  (icicle-call-then-update-Completions #'yank arg))

(defun icicle-yank-pop (arg)            ; Bound to `M-y' and `M-insert' in minibuffer.
  "`yank-pop' and update `*Completions*' with regexp input matches.
See description of `yank-pop'."
  (interactive "*p")
  (icicle-call-then-update-Completions #'yank-pop arg))

(eval-after-load "second-sel"
  '(progn (defun icicle-yank-secondary () ; Bound to `C-M-y' in minibuffer.
            "Insert the secondary selection at point.
Move point to the end of the inserted text.  Does not change mark."
            (interactive "*")
            (icicle-call-then-update-Completions #'yank-secondary))

    ;; Tell `delete-selection-mode' to replace active region by yanked secondary selection.
    (put 'icicle-yank-secondary 'delete-selection 'yank)))


;; Tell `delete-selection-mode' to replace active region by yanked secondary selection.
(put 'icicle-mouse-yank-secondary 'delete-selection 'yank)

(defun icicle-mouse-yank-secondary (event) ; Bound to `M-mouse-2' in minibuffer.
  "Insert the secondary selection where you click.
Move point to the end of the inserted text.
If `mouse-yank-at-point' is non-nil, insert at point
regardless of where you click."
  (interactive "*e")
  (if (fboundp 'yank-secondary)         ; In `mouse+.el'.
      (icicle-call-then-update-Completions #'mouse-yank-secondary event current-prefix-arg)
    (icicle-call-then-update-Completions #'mouse-yank-secondary event)))


;; Make delete-selection mode recognize self-insertion, so it replaces region text.
(if (or (> emacs-major-version 24)  (and (= emacs-major-version 24)  (> emacs-minor-version 2)))
    (put 'icicle-self-insert 'delete-selection
         (lambda () (not (run-hook-with-args-until-success 'self-insert-uses-region-functions))))
  (put 'icicle-self-insert 'delete-selection t))

(defun icicle-self-insert (ch) ;; Bound in minibuffer to stuff bound globally to `self-insert-command'.
  "Insert char CH and update `*Completions*' with regexp input matches.
See description of `self-insert-command'."
  (interactive "p")
  (if executing-kbd-macro
      (funcall #'self-insert-command ch)
    (icicle-call-then-update-Completions #'self-insert-command ch)))

(defun icicle-insert-a-space ()
  "Insert a space.
For convenience in the minibuffer - does the same thing as `C-q SPC'.
To use this, bind it to some key sequence in keymaps
`minibuffer-local-completion-map',
`minibuffer-local-filename-completion-map', and
`minibuffer-local-must-match-map'."
  (interactive) (insert ?\ ))

(defun icicle-insert-dot-command (&optional arg) ; Bound to `.' in minibuffer during completion.
  "Insert `icicle-dot-string': either `.' or `icicle-anychar-regexp'.
With a numeric prefix argument, insert the dot that many times.

With a plain prefix arg (`C-u'), insert the opposite kind of dot
\(once) from what is indicated by the current value of
`icicle-dot-string'."
  (interactive "P")
  (when (interactive-p) (icicle-barf-if-outside-minibuffer))
  (if (consp arg)
      (let ((opposite  (if (string= icicle-dot-string-internal ".")
                           (icicle-anychar-regexp)
                         (let ((strg  "."))
                           (add-text-properties
                            0 1 '(icicle-user-plain-dot t rear-nonsticky (icicle-user-plain-dot))
                            strg)
                           strg))))
        (if executing-kbd-macro
            (insert opposite)
          (icicle-call-then-update-Completions (lambda () (insert opposite)))))
    (setq arg  (prefix-numeric-value arg))
    (if executing-kbd-macro
        (funcall #'icicle-insert-dot arg)
      (icicle-call-then-update-Completions #'icicle-insert-dot arg))))

(defun icicle-insert-dot (n)
  "Insert `icicle-dot-string' N times."
  (dotimes (i n)
    (if (not (string= icicle-dot-string-internal "."))
        (insert (icicle-anychar-regexp))
      (insert ".")
      (add-text-properties (max (point-min) (1- (point))) (point)
                           '(icicle-user-plain-dot t rear-nonsticky t)))))

(defun icicle-anychar-regexp ()
  "Return a regexp that matches any single character, including newline.
The value returned is like that of constant `icicle-anychar-regexp',
but the `display' string is unique for each call."
  (let ((strg  (copy-sequence "\\(.\\|[\n]\\)")))
    (set-text-properties 0 (length strg)
                         (if icicle-dot-show-regexp-flag
                             '(face highlight rear-nonsticky t)
                           `(display ,(copy-sequence ".") face highlight rear-nonsticky t))
                         strg)
    strg))

(defun icicle-erase-minibuffer ()       ; Bound to `M-S-backspace', `M-S-delete' in minibuffer.
  "Delete all user input in the minibuffer, then update completions."
  (interactive)
  (icicle-call-then-update-Completions #'icicle-clear-minibuffer))
 
;;(@* "Commands to sort completion candidates")

;;; Commands to sort completion candidates . . . . . . . . . . . . . .

;; We don't bother to define a command for the sort functions `icicle-prefix-keys-first-p' and
;; `icicle-command-names-alphabetic-p'.  They are bound in `icicle-complete-keys'.

;; The order here defines the reverse order of `icicle-sort-orders-alist'.
;; The first here is also the default sort order.  Entries are traversed by `C-,' in
;; `icicle-sort-orders-alist' order.

(icicle-define-sort-command "alphabetical" ; `icicle-sort-alphabetical'
    icicle-case-string-less-p
  "Sort completion candidates alphabetically.
Ignore letter case if `completion-ignore-case' or `case-fold-search'
is non-nil.")

(icicle-define-sort-command "special candidates first" ; `icicle-sort-special-candidates-first'
    icicle-special-candidates-first-p
  "Sort completion candidates by putting special candidates first.
Otherwise, sorting is alphabetical.  Ignore letter case if
`completion-ignore-case' or `case-fold-search' is non-nil.")

(icicle-define-sort-command "extra candidates first" ; `icicle-sort-extra-candidates-first'
    icicle-extra-candidates-first-p
  "Sort completion candidates by putting extra candidates first.
Otherwise, sorting is alphabetical.  Ignore letter case if
`completion-ignore-case' or `case-fold-search' is non-nil.
An extra candidate is one that is a member of
`icicle-extra-candidates'.")

(icicle-define-sort-command "proxy candidates first" ; `icicle-sort-proxy-candidates-first'
    icicle-proxy-candidate-first-p
  "Sort completion candidates by putting proxy candidates first.
Otherwise, sorting is alphabetical.  Ignore letter case if
`completion-ignore-case' or `case-fold-search' is non-nil.")

(icicle-define-sort-command "case insensitive" ; `icicle-sort-case-insensitive'
    icicle-case-insensitive-string-less-p
  "Sort completion candidates alphabetically, but case-insenstively.")

(icicle-define-sort-command "by 2nd parts alphabetically" ; `icicle-sort-by-2nd-parts-alphabetically'
    icicle-2nd-part-string-less-p
  "Sort multi-completion candidates alphabetically by their second parts.
After that, sort alphabetically by the first parts.  Ignore letter
case if `completion-ignore-case' or `case-fold-search' is non-nil.")

(icicle-define-sort-command "by last use" ; `icicle-sort-by-last-use'
    icicle-latest-use-first-p
  "Sort file-name completion candidates in order of last use.
\"Use\" here refers, first, to use as your input, second, to access.")

(icicle-define-sort-command "by last file access time"
    icicle-latest-access-first-p        ; `icicle-sort-by-last-file-access-time'
  "Sort file-name completion candidates in order of last access.
If not doing file-name completion, then sort alphabetically.")

(icicle-define-sort-command "by last file modification time"
    icicle-latest-modification-first-p  ; `icicle-sort-by-last-file-modification-time'
  "Sort file-name completion candidates in order of last modification.
If not doing file-name completion, then sort alphabetically.")

(icicle-define-sort-command "by file type" ; `icicle-sort-by-file-type'
    icicle-file-type-less-p
  "Sort file-name completion candidates by file type.
Directories sort first, alphabetically.
Then sort by file type (extension), alphabetically.
Sort names that have the same extension alphabetically.
If not doing file-name completion, sort candidates alphabetically.")

(icicle-define-sort-command "by last use, dirs first" ; `icicle-sort-by-last-use\,-dirs-first'
    icicle-dirs-and-latest-use-first-p
  "Sort file-name completion candidates by last use, directories first.
If not doing file-name completion, then sort only by last use.
\"Use\" here refers, first, to use as your input, second, to access.")

(icicle-define-sort-command "by directories first" ; `icicle-sort-by-directories-first'
    icicle-dirs-first-p
  "Sort file-name completion candidates so that directories are first.
If not doing file-name completion, then sort alphabetically.")

(icicle-define-sort-command "by directories last" ; `icicle-sort-by-directories-last'
    icicle-dirs-last-p
  "Sort file-name completion candidates so that directories are last.
If not doing file-name completion, then sort alphabetically.")

(icicle-define-sort-command "by last use as input" ; `icicle-sort-by-last-use-as-input'
    icicle-latest-input-first-p
  "Sort completion candidates in order of last use as minibuffer input.")

(icicle-define-sort-command "by previous use alphabetically"
    icicle-historical-alphabetic-p      ; `icicle-sort-by-previous-use-alphabetically'
  "Sort completion candidates by previous use and alphabetically.
Candidates matching previous inputs are available first.  Candidates
are in two groups, each of which is sorted alphabetically separately:
those matching previous inputs, followed by those that have not yet
been used.")

(icicle-define-sort-command "by abbrev frequency" ; `icicle-sort-by-abbrev-frequency'
    icicle-command-abbrev-used-more-p
  "Sort abbrev completion candidates by frequency of use
Otherwise, sort alphabetically.  Ignore letter case if
`completion-ignore-case' or `case-fold-search' is non-nil.")

(icicle-define-sort-command "turned OFF" nil ; `icicle-sort-turned-OFF'
  "Do not sort completion candidates.")

(defun icicle-dispatch-M-_ ()           ; Bound to `M-_' in minibuffer.
  "Do the right thing for `M-_'.
During Icicles search, call `icicle-toggle-search-replace-whole'.
Otherwise, call `icicle-toggle-ignored-space-prefix'.
Bound to `M-_' in the minibuffer."
  (interactive)
  (if icicle-searching-p (icicle-toggle-search-replace-whole) (icicle-toggle-ignored-space-prefix)))

;;; No longer used.
;;; (defun icicle-dispatch-C-comma ()
;;;   "Do the right thing for `C-,'.
;;; When candidate sorting is possible, call `icicle-change-sort-order'.
;;; When searching, call `icicle-toggle-search-replace-whole'.
;;; Otherwise, do nothing.
;;;
;;; Bound to `C-,' in the minibuffer."
;;;   (interactive)
;;;   (cond (icicle-searching-p (icicle-toggle-search-replace-whole))
;;;         (icicle-inhibit-sort-p (message "Cannot sort candidates now"))
;;;         (t (call-interactively #'icicle-change-sort-order))))

;; Top-level commands.  Could instead be in `icicles-cmd2.el'.
;;
(defalias 'toggle-icicle-ignoring-comments 'icicle-toggle-ignoring-comments)
(defun icicle-toggle-ignoring-comments () ; Bound to `C-M-;' in minibuffer.
  "Toggle the value of option `icicle-ignore-comments-flag'.
If option `ignore-comments-flag' is defined (in library
`hide-comnt.el') then it too is toggled.
Bound to `C-M-;' in the minibuffer."
  (interactive)
  (setq icicle-ignore-comments-flag  (not icicle-ignore-comments-flag))
  (when (boundp 'ignore-comments-flag) (setq ignore-comments-flag  (not ignore-comments-flag)))
  (icicle-msg-maybe-in-minibuffer
   "Ignoring comments is now %s" (icicle-propertize (if icicle-ignore-comments-flag "ON" "OFF")
                                                    'face 'icicle-msg-emphasis)))

;; Top-level commands.  Could instead be in `icicles-cmd2.el'.
;;
(defalias 'toggle-icicle-search-replace-common-match 'icicle-toggle-search-replace-common-match)
(defun icicle-toggle-search-replace-common-match () ; Bound to `M-;' in minibuffer.
  "Toggle the value of `icicle-search-replace-common-match-flag'.
Note that that option has no effect if the value of option
`icicle-expand-input-to-common-match' does not imply expansion.
Bound to `M-;' in the minibuffer."
  (interactive)
  (setq icicle-search-replace-common-match-flag  (not icicle-search-replace-common-match-flag))
  (icicle-msg-maybe-in-minibuffer
   "Replacing expanded common match is now %s"
   (icicle-propertize (if icicle-search-replace-common-match-flag "ON" "OFF")
                      'face 'icicle-msg-emphasis)))

;; Top-level commands.  Could instead be in `icicles-cmd2.el'.
;;
(defalias 'toggle-icicle-search-replace-whole 'icicle-toggle-search-replace-whole)
(defun icicle-toggle-search-replace-whole ()
  "Toggle the value of `icicle-search-replace-whole-candidate-flag'.
Bound to `M-_' in the minibuffer when searching."
  (interactive)
  (setq icicle-search-replace-whole-candidate-flag  (not icicle-search-replace-whole-candidate-flag))
  (icicle-msg-maybe-in-minibuffer
   "Replacing whole search context is now %s"
   (icicle-propertize (if icicle-search-replace-whole-candidate-flag "ON" "OFF")
                      'face 'icicle-msg-emphasis)))

;; Top-level commands.  Could instead be in `icicles-cmd2.el'.
;;
(defalias 'toggle-icicle-dot 'icicle-toggle-dot)
(defalias 'toggle-icicle-.   'icicle-toggle-dot)
(defalias 'icicle-toggle-.   'icicle-toggle-dot)
(defun icicle-toggle-dot ()             ; Bound to `C-M-.' in minibuffer.
  "Toggle `icicle-dot-string' between `.' and `icicle-anychar-regexp'.
Bound to `C-M-.' in the minibuffer."
  (interactive)
  (setq icicle-dot-string  (if (string= icicle-dot-string ".") (icicle-anychar-regexp) "."))
  (icicle-msg-maybe-in-minibuffer
   (cond ((string= icicle-dot-string ".")
          (icicle-convert-dots (equal icicle-current-input icicle-last-input) t)
          (format "`%s' now matches any char %s newline"
                  (icicle-propertize "." 'face 'icicle-msg-emphasis)
                  (icicle-propertize "EXCEPT" 'face 'icicle-msg-emphasis)))
         (t
          (icicle-convert-dots (equal icicle-current-input icicle-last-input))
          (format "`%s' now matches any char, including %s"
                  (icicle-propertize "." 'face 'icicle-msg-emphasis)
                  (icicle-propertize "NEWLINE" 'face 'icicle-msg-emphasis)))))
  (setq icicle-dot-string-internal  icicle-dot-string))

(defun icicle-convert-dots (&optional no-confirm-p plainp)
  "Convert existing dots.
Optional arg NO-CONFIRM-P means don't ask user for confirmation.
Optional arg PLAINP means convert to plain `.'.
  Otherwise, convert to `icicle-anychar-regexp'."
  (if plainp
      (save-excursion
        (when (and (goto-char (icicle-minibuffer-prompt-end))
                   (search-forward icicle-anychar-regexp nil t))
          (goto-char (icicle-minibuffer-prompt-end))
          (while (search-forward icicle-anychar-regexp nil t)
            (replace-match "." nil t))))
    (save-excursion
      (when (and (goto-char (icicle-minibuffer-prompt-end))  (search-forward "." nil t))
        (goto-char (icicle-minibuffer-prompt-end))
        (let ((allp  nil))
          (while (search-forward "." nil t)
            ;; If we hit a plain dot inserted by user explicitly, ask if we should convert all such.
            (when (and (not allp)
                       (get-text-property (match-beginning 0) 'icicle-user-plain-dot)
                       (not no-confirm-p)
                       (y-or-n-p "Should all dots (`.') in current input match newlines too? "))
              (setq allp  t))
            (when (or allp  (not (get-text-property (match-beginning 0) 'icicle-user-plain-dot)))
              (replace-match (icicle-anychar-regexp) nil t))))))))

;; Top-level commands.  Could instead be in `icicles-cmd2.el'.
(when (require 'image-dired nil t)      ; Emacs 22+.
  (defalias 'cycle-icicle-image-file-thumbnail 'icicle-cycle-image-file-thumbnail)
  (defun icicle-cycle-image-file-thumbnail () ; Bound to `C-x t' in minibuffer.
    "Toggle `icicle-image-files-in-Completions'.
This has no effect if you do not have library `image-dired.el' (Emacs 23+).
Bound to `C-x t' in the minibuffer."
    (interactive)
    (if (not (require 'image-dired nil t))
        (message "No-op: this command requires library `image-dired.el'")
      (setq icicle-image-files-in-Completions  (case icicle-image-files-in-Completions
                                                 ((nil)       'image-only)
                                                 (image-only  t)
                                                 (t           nil)))
      (icicle-complete-again-update)
      (icicle-msg-maybe-in-minibuffer
       (case icicle-image-files-in-Completions
         ((nil)       (format "Image files in `*Completions*': showing only %s  Next: only IMAGES"
                              (icicle-propertize "NAMES" 'face 'icicle-msg-emphasis)))
         (image-only  (format "Image files in `*Completions*': showing only %s  Next: IMAGES and NAMES"
                              (icicle-propertize "IMAGES" 'face 'icicle-msg-emphasis)))
         (t           (format "Image files in `*Completions*': showing %s  Next: only NAMES"
                              (concat (icicle-propertize "IMAGES" 'face 'icicle-msg-emphasis)
                                      " and "
                                      (icicle-propertize "NAMES" 'face 'icicle-msg-emphasis)))))))))

;; This works hand in hand with `icicle-maybe-sort-maybe-truncate'.  Update both together.
;;
(defun icicle-doremi-increment-max-candidates+ (&optional increment) ; `C-x #' in minibuffer
  "Change `icicle-max-candidates' incrementally.
Use `up', `down' or the mouse wheel to increase or decrease.  You can
 use the `Meta' key (e.g. `M-up') to increment in larger steps.
You can use a numeric prefix arg to specify the increment.
A plain prefix arg (`C-u') resets `icicle-max-candidates' to nil,
 meaning no limit."
  (interactive "P")
  (cond ((consp increment)
         (setq icicle-max-candidates  'RESET) ; `icicle-maybe-sort-maybe-truncate' will reset to nil.
         (icicle-msg-maybe-in-minibuffer "No longer any limit on number of candidates"))
        (t
         (setq increment  (prefix-numeric-value increment))
         (unless (require 'doremi nil t)
           (icicle-user-error "You need library `doremi.el' for this command"))
         (let ((mini  (active-minibuffer-window)))
           (unwind-protect
                (save-selected-window
                  (select-window (minibuffer-window))
                  (unless icicle-completion-candidates (message "Hit `TAB' or `S-TAB'"))
                  (let ((enable-recursive-minibuffers  t)
                        (nb-cands                      (length icicle-completion-candidates)))
                    (when (or (not (integerp icicle-max-candidates)) ; Not `RESET' or nil.
                              (> icicle-max-candidates nb-cands))
                      (setq icicle-max-candidates  nb-cands))
                    (when (zerop icicle-max-candidates) (setq icicle-max-candidates  10))
                    (doremi (lambda (new-val)
                              (setq icicle-max-candidates  (setq new-val  (doremi-limit new-val 2 nil)))
                              (unless (input-pending-p)
                                (let ((icicle-edit-update-p  t)
                                      (icicle-last-input     nil))
                                  (funcall (or icicle-last-completion-command
                                               (if (eq icicle-current-completion-mode 'prefix)
                                                   #'icicle-prefix-complete
                                                 #'icicle-apropos-complete)))
                                  (run-hooks 'icicle-update-input-hook)))
                              new-val)
                            icicle-max-candidates
                            increment))
                  (setq unread-command-events  ()))
             (unless mini (icicle-remove-Completions-window)))))))

(defun icicle-doremi-increment-swank-timeout+ () ; Bound to `C-x 1' in minibuffer (swank only)
  "Change `icicle-swank-timeout' incrementally.
Use `up', `down' or the mouse wheel to increase or decrease.  You can
use the `Meta' key (e.g. `M-up') to increment in larger steps."
  (interactive)
  (icicle-doremi-increment-variable+ 'icicle-swank-timeout 1000))

(defun icicle-doremi-increment-swank-prefix-length+ () ; Bound to `C-x 2' in minibuffer (swank only)
  "Change `icicle-swank-prefix-length' incrementally.
Use `up', `down' or the mouse wheel to increase or decrease.  You can
use the `Meta' key (e.g. `M-up') to increment in larger steps."
  (interactive)
  (icicle-doremi-increment-variable+ 'icicle-swank-prefix-length 1))

;; Top-level commands.  Could instead be in `icicles-cmd2.el'.
;;
(defalias 'cycle-icicle-TAB-completion-method 'icicle-next-TAB-completion-method)
(defun icicle-next-TAB-completion-method (temporary-p) ; Bound to `C-(' in minibuffer.
  "Cycle to the next `TAB' completion method.
Bound to \\<minibuffer-local-completion-map>`\\[icicle-next-TAB-completion-method]' \
in the minibuffer.
Option `icicle-TAB-completion-methods' determines the TAB completion
methods that are available.

With a prefix argument, the newly chosen method is used only for the
current command.  More precisely, the previously active method is
restored as soon as you return to the top level."
  (interactive "P")
  (unless icicle-current-TAB-method     ; nil means the same as the default (first).
    (setq icicle-current-TAB-method  (car icicle-TAB-completion-methods)))
  (if temporary-p
      (unless (get 'icicle-last-top-level-command 'icicle-current-TAB-method)
        (put 'icicle-last-top-level-command 'icicle-current-TAB-method icicle-current-TAB-method))
    (put 'icicle-last-top-level-command 'icicle-current-TAB-method nil))

  (let ((now  (memq icicle-current-TAB-method icicle-TAB-completion-methods))
        following)
    (setq icicle-current-TAB-method  (or (cadr now)  (car icicle-TAB-completion-methods))
          following                  (or (cadr (memq icicle-current-TAB-method
                                                     icicle-TAB-completion-methods))
                                         (car icicle-TAB-completion-methods)))
    ;; Skip any method that is not currently supported.
    (while (or (and (eq icicle-current-TAB-method 'fuzzy)        (not (featurep 'fuzzy-match)))
               (and (eq icicle-current-TAB-method 'vanilla)      (not (boundp 'completion-styles)))
               (and (eq icicle-current-TAB-method 'swank)        (not (featurep 'el-swank-fuzzy))))
      (setq now                        (memq icicle-current-TAB-method icicle-TAB-completion-methods)
            icicle-current-TAB-method  (or (cadr now)  (car icicle-TAB-completion-methods))))
    ;; Skip any method that is not currently supported.
    (while (or (and (eq following 'fuzzy)    (not (featurep 'fuzzy-match)))
               (and (eq following 'vanilla)  (not (boundp 'completion-styles)))
               (and (eq following 'swank)    (not (featurep 'el-swank-fuzzy))))
      (setq following  (or (cadr (memq icicle-current-TAB-method icicle-TAB-completion-methods))
                           (car icicle-TAB-completion-methods))))
    ;; $$$$$$ Inhibiting sorting is not correct for file-name completion, and sorting would not be
    ;;        restored when change back to non-fuzzy.
    ;; (when (eq 'fuzzy icicle-current-TAB-method) (setq icicle-inhibit-sort-p  t))
    (icicle-msg-maybe-in-minibuffer
     "TAB completion is %s %s  Next: %s"
     (icicle-propertize (icicle-upcase (symbol-name icicle-current-TAB-method))
                        'face 'icicle-msg-emphasis)
     (if temporary-p (concat "for " (icicle-propertize "this command" 'face 'icicle-msg-emphasis)) "now.")
     (if temporary-p "" (icicle-upcase (symbol-name following)))))
  (cond ((and (eq icicle-current-TAB-method 'swank)  (fboundp 'doremi))
         (define-key minibuffer-local-completion-map (icicle-kbd "C-x 1")
           'icicle-doremi-increment-swank-timeout+)
         (define-key minibuffer-local-must-match-map (icicle-kbd "C-x 1")
           'icicle-doremi-increment-swank-timeout+)
         (define-key minibuffer-local-completion-map (icicle-kbd "C-x 2")
           'icicle-doremi-increment-swank-prefix-length+)
         (define-key minibuffer-local-must-match-map (icicle-kbd "C-x 2")
           'icicle-doremi-increment-swank-prefix-length+))
        ((fboundp 'doremi)
         (define-key minibuffer-local-completion-map (icicle-kbd "C-x 1") nil)
         (define-key minibuffer-local-must-match-map (icicle-kbd "C-x 1") nil)
         (define-key minibuffer-local-completion-map (icicle-kbd "C-x 2") nil)
         (define-key minibuffer-local-must-match-map (icicle-kbd "C-x 2") nil))))

;; Top-level commands.  Could instead be in `icicles-cmd2.el'.
;;
(defalias 'cycle-icicle-S-TAB-completion-method 'icicle-next-S-TAB-completion-method)
(defun icicle-next-S-TAB-completion-method (temporary-p) ; Bound to `M-(' in minibuffer.
  "Cycle to the next `S-TAB' completion method.
Bound to `M-(' in the minibuffer.
Option `icicle-S-TAB-completion-methods-alist' customizes the
available TAB completion methods.

With a prefix argument, the newly chosen method is used only for the
current command.  More precisely, the previously active method is
restored as soon as you return to the top level."
  (interactive "P")
  (if temporary-p
      (unless (get 'icicle-last-top-level-command 'icicle-apropos-complete-match-fn)
        (put 'icicle-last-top-level-command 'icicle-apropos-complete-match-fn
             icicle-apropos-complete-match-fn))
    (put 'icicle-last-top-level-command 'icicle-apropos-complete-match-fn nil))
  (let ((entry  (rassq icicle-apropos-complete-match-fn icicle-S-TAB-completion-methods-alist))
        following)
    (setq icicle-apropos-complete-match-fn       (or (cdadr (member
                                                             entry icicle-S-TAB-completion-methods-alist))
                                                     (cdar icicle-S-TAB-completion-methods-alist))
          following                              (or (caadr (member
                                                             (rassq icicle-apropos-complete-match-fn
                                                                    icicle-S-TAB-completion-methods-alist)
                                                             icicle-S-TAB-completion-methods-alist))
                                                     (caar icicle-S-TAB-completion-methods-alist))
          icicle-last-apropos-complete-match-fn  icicle-apropos-complete-match-fn) ; Backup copy.
    (icicle-msg-maybe-in-minibuffer
     "S-TAB completion is %s%s %s  Next: %s"
     (icicle-propertize (icicle-upcase (car (rassq icicle-apropos-complete-match-fn
                                                   icicle-S-TAB-completion-methods-alist)))
                        'face 'icicle-msg-emphasis)
     (if (memq icicle-apropos-complete-match-fn
               '(icicle-levenshtein-match icicle-levenshtein-strict-match))
         (icicle-propertize (format " (%d)" icicle-levenshtein-distance) 'face 'icicle-msg-emphasis)
       "")
     (if temporary-p (concat "for " (icicle-propertize "this command" 'face 'icicle-msg-emphasis)) "now.")
     (if temporary-p "" (icicle-upcase following)))))
    ;; (icicle-complete-again-update) ; No - too slow for some completion methods.

;; Top-level commands.  Could instead be in `icicles-cmd2.el'.
;;
(defalias 'cycle-icicle-sort-order 'icicle-change-sort-order)
(defun icicle-change-sort-order (&optional arg alternativep) ; Bound to `C-,' in minibuffer.
  "Choose a sort order using completion or by cycling to the next one.
With a numeric prefix arg, just reverse the current sort order.

Option `icicle-change-sort-order-completion' determines whether to use
completion or cycling to choose the new sort order, as follows:

 - nil means cycle to the next order; do not use completion to choose
   the new order.

 - An integer means use completion if there are currently more than
   that number of sort orders to choose from.  Otherwise, cycle next.

 - Any other non-nil value means use completion.

However, a plain prefix argument (`C-u') flips the behavior defined
thus between cycling and completion.  That is, if the option would
normally lead to completion then `C-u' causes cycling instead, and
vice versa.

This command updates `icicle-sort-comparer'.  Non-interactively,
optional arg ALTERNATIVEP means change the current alternative sort
order instead, updating `icicle-alternative-sort-comparer'.

NOTE: If sorting has been turned off automatically for the current
minibuffer invocation because there are more candidates than
`icicle-sorting-max-candidates', this does not turn sorting back on.
The newly chosen sort order takes effect only when sorting is turned
on again (e.g. because there are fewer candidates)."
  (interactive "P")
  (setq icicle-sort-orders-alist  (delq nil icicle-sort-orders-alist)) ; Purge any nil entries.
  (if (and (interactive-p)  icicle-inhibit-sort-p)
      (icicle-msg-maybe-in-minibuffer "Cannot sort candidates now")
    (if (and arg  (not (consp arg)))
        (icicle-reverse-sort-order)
      (let* ((following-order   nil)
             (use-completion-p  (if (integerp icicle-change-sort-order-completion)
                                    (> (length (icicle-current-sort-functions))
                                       icicle-change-sort-order-completion)
                                  icicle-change-sort-order-completion))
             (use-completion-p  (or (and (not arg)  use-completion-p) ; Use completion.
                                    (and arg        (not use-completion-p))))
             next-order)
        (cond (use-completion-p
               (setq next-order  (let ((icicle-whole-candidate-as-text-prop-p   nil)
                                       (icicle-must-pass-after-match-predicate  nil)
                                       (icicle-show-Completions-initially-flag  t)
                                       (enable-recursive-minibuffers            t)
                                       (icicle-default-value                    t) ; Put current in prompt.
                                       (icicle-default-in-prompt-format-function
                                        (lambda (def) (format " (NOW: %s)" def))))
                                   (save-selected-window
                                     (completing-read
                                      (format "New %ssort order: " (if alternativep "alternative " ""))
                                      (icicle-current-sort-functions)
                                      nil t nil nil
                                      (car (rassoc (if alternativep
                                                       icicle-alternative-sort-comparer
                                                     icicle-sort-comparer)
                                                   icicle-sort-orders-alist))))))
               (when (if alternativep icicle-alternative-sort-comparer icicle-sort-comparer)
                 (setq icicle-last-sort-comparer  (if alternativep ; Save current as last.
                                                      icicle-alternative-sort-comparer
                                                    icicle-sort-comparer)))
               (set (if alternativep 'icicle-alternative-sort-comparer 'icicle-sort-comparer)
                    (cdr (assoc next-order icicle-sort-orders-alist))))
              (t                        ; Cycle to next sort order.
               (let ((orders  (mapcar #'car (icicle-current-sort-functions))))
                 (setq next-order       (or (cadr (memq (icicle-current-sort-order alternativep) orders))
                                            (car orders))
                       following-order  (or (cadr (memq next-order orders))  (car orders)))
                 (when (if alternativep icicle-alternative-sort-comparer icicle-sort-comparer)
                   (setq icicle-last-sort-comparer  (if alternativep ; Save current as last.
                                                        icicle-alternative-sort-comparer
                                                      icicle-sort-comparer)))
                 (set (if alternativep 'icicle-alternative-sort-comparer 'icicle-sort-comparer)
                      (cdr (assoc next-order icicle-sort-orders-alist))))))
        (icicle-complete-again-update)
        (icicle-msg-maybe-in-minibuffer
         "%sorting is now %s.  Reverse: `C-9 C-,'%s"
         (if alternativep "Alternative s" "S")
         (icicle-propertize (concat next-order (and icicle-reverse-sort-p  ", REVERSED"))
                            'face 'icicle-msg-emphasis)
         (if following-order (format ".  Next: %s" following-order) "")))
      (when (fboundp 'completion--flush-all-sorted-completions) ; E.g., so Icomplete+ recomputes order.
        (completion--flush-all-sorted-completions)))))

(defun icicle-current-sort-functions ()
  "Subset of `icicle-sort-orders-alist' that is currently appropriate.
For some common kinds of completion, remove simple sort functions (not
multi-sort comparers) that are not pertinent for the current kind of
completion."
  (icicle-remove-if (lambda (pred)
                      (setq pred  (cdr pred))
                      (and pred
                           (symbolp pred) ; Do not handle multi-sort comparers.
                           (not (eq pred icicle-allowed-sort-predicate))
                           (or (and (get pred 'icicle-proxy-sort-predicate)
                                    (not icicle-add-proxy-candidates-flag))
                               (and (get pred 'icicle-file-name-sort-predicate)
                                    (not (or (icicle-file-name-input-p)  icicle-abs-file-candidates)))
                               ;; Not really needed yet, because we only add such sorts dynamically.
                               (and (get pred 'icicle-buffer-name-sort-predicate) ; Better than nothing.
                                    (not (eq minibuffer-history-variable 'buffer-name-history)))
                               (and (get pred 'icicle-command-sort-predicate)
                                    (not (and (eq minibuffer-completion-table obarray)
                                              ;; But this will fail if predicate is more complex.
                                              ;; So be sure to bind `icicle-allowed-sort-predicate'
                                              ;; in that case, to avoid this restriction.
                                              (eq minibuffer-completion-predicate 'commandp))))
                               ;; Sort order for multi-completions. `minibuffer-completion-table'
                               ;; could be a function (e.g. `icicle-describe-opt-of-type-complete')
                               ;; or it could be a list of multi-completions.
                               (and (get pred 'icicle-multi-completion-sort-predicate)
                                    (not (icicle-maybe-multi-completion-completing-p))))))
                    icicle-sort-orders-alist))

(defun icicle-maybe-multi-completion-completing-p ()
  "Returns non-nil if we might currently be multi-completion completing.
Note: If `minibuffer-completion-table' is a function, multi-completion
is possible but not sure.  Return non-nil in that case."
  (or (functionp minibuffer-completion-table)  icicle-list-use-nth-parts))

(defun icicle-dispatch-M-comma ()       ; Bound to `M-,' in minibuffer.
  "Do the right thing for `M-,'.
If sorting is possible, call `icicle-change-alternative-sort-order'.
If using `icicle-search', call `icicle-search-define-replacement'.
Otherwise, do nothing.

Bound to `M-,' in the minibuffer."
  (interactive)
  (cond (icicle-searching-p (icicle-search-define-replacement))
        (icicle-inhibit-sort-p (message "Cannot sort candidates now"))
        (t (icicle-change-alternative-sort-order))))

;; Free vars here: `icicle-scan-fn-or-regexp' is bound in `icicle-search'.
;;
(defun icicle-search-define-replacement () ; Bound to `M-,' in minibuffer during `icicle-search'.
  "Prompt user and set new value of `icicle-search-replacement'.
Bound to `M-,' in the minibuffer."
  (interactive)
  (save-selected-window
    (icicle-remove-Completions-window)) ; Prevent incremental completion kicking in from the get-go.
  (setq icicle-search-replacement
        (let ((enable-recursive-minibuffers   t)
              (icicle-incremental-completion  t) ; Override current upgrade to `always'.
              (icicle-completion-candidates   icicle-completion-candidates)
              (icicle-current-input           icicle-current-input)
              (icicle-candidate-nb            icicle-candidate-nb)
              (icicle-update-input-hook       nil))
          (icicle-completing-read-history "Replacement string: " 'icicle-search-replacement-history)))
  ;; Just a sanity check.  Cannot really test equivalence of two regexps.
  (while (if icicle-search-replace-whole-candidate-flag
             (equal icicle-search-replacement icicle-scan-fn-or-regexp)
           (equal icicle-search-replacement icicle-current-input))
    (setq icicle-search-replacement
          (let ((enable-recursive-minibuffers   t)
                (icicle-incremental-completion  t) ; Override current upgrade to `always'.
                (icicle-completion-candidates   icicle-completion-candidates)
                (icicle-current-input           icicle-current-input)
                (icicle-candidate-nb            icicle-candidate-nb)
                (icicle-update-input-hook       nil))
            (icicle-completing-read-history "Replacement = replaced.  Replacement string: "
                                            'icicle-search-replacement-history)))))

(defun icicle-change-alternative-sort-order (&optional arg) ; Bound to `M-,' in minibuffer (not search).
  "Choose an alternative sort order.
Similar to command `icicle-change-sort-order', but change the
alternative sort order, not the current sort order."
  (interactive "P")
  (if (and (interactive-p)  icicle-inhibit-sort-p)
      (icicle-msg-maybe-in-minibuffer "Cannot sort candidates now")
    (icicle-change-sort-order arg t)))

(defun icicle-current-sort-order (alternativep)
  "Current sort order, or nil if sorting is inactive.
If ALTERNATIVEP is non-nil, the alternative sort order is returned."
  (car (rassq (if alternativep icicle-alternative-sort-comparer icicle-sort-comparer)
              icicle-sort-orders-alist)))

(defun icicle-reverse-sort-order ()
  "Reverse the current sort order."
  (interactive)
  (if (and (interactive-p)  icicle-inhibit-sort-p)
      (icicle-msg-maybe-in-minibuffer "Cannot sort candidates now")
    (setq icicle-reverse-sort-p  (not icicle-reverse-sort-p))
    (icicle-display-candidates-in-Completions icicle-reverse-sort-p)
    (icicle-complete-again-update)
    (icicle-msg-maybe-in-minibuffer
     "Sort order is %s" (icicle-propertize (concat (icicle-current-sort-order nil)
                                                   (and icicle-reverse-sort-p  ", REVERSED"))
                                           'face 'icicle-msg-emphasis))))

(defun icicle-plus-saved-sort ()        ; Bound to `C-M-+' during completion.
  "Sort candidates by combining their current order with the saved order."
  (interactive)
  (let ((icicle-sort-comparer  'icicle-merge-saved-order-less-p)
        (cands                 (copy-sequence icicle-completion-candidates)))
    (setq icicle-completion-candidates
          (if (or (icicle-file-name-input-p)  icicle-abs-file-candidates)
              (icicle-strip-ignored-files-and-sort cands)
            (icicle-maybe-sort-maybe-truncate cands))))
  (when (get-buffer-window "*Completions*" 0) (icicle-display-candidates-in-Completions))
  (when (interactive-p) (icicle-msg-maybe-in-minibuffer "Added in the saved sort order")))

 
;;(@* "Other commands to be used mainly in the minibuffer")

;;; Other commands to be used mainly in the minibuffer . . . . . . . .


;; Used as a command only in `icicle-Info-index', currently.  Used mainly as a utility function - the main
;; function for displaying completion candidates.  This was in `icicles-fn.el' originally.
;;
(defun icicle-display-candidates-in-Completions (&optional reverse-p no-display-p)
  "Refresh the current set of completion candidates in `*Completions*'.
REVERSE-P non-nil means display the candidates in reverse order.
NO-DISPLAY-P non-nil means do not display the candidates; just
  recompute them.  If the value is `no-msg', then do not show a
  minibuffer message indicating that candidates were updated.
By default, this is bound to `C-x C-M-l' during completion."

  ;; FREE var used here (bound in `icicle-Info-index'): `icicle-Info-hist-list'.

  ;;$$   ;; Pred is special if `minibuffer-completion-table' is a function.
  ;;   (when (and (not (functionp minibuffer-completion-table))
  ;;              (functionp minibuffer-completion-predicate))
  ;;     (setq icicle-completion-candidates
  ;;           (icicle-remove-if-not
  ;;            (lambda (cand)
  ;;              (funcall minibuffer-completion-predicate
  ;;                       (if (arrayp minibuffer-completion-table) (intern cand) (list cand))))
  ;;            icicle-completion-candidates)))

  ;; $$$  (case icicle-incremental-completion
  ;;     ((t always) (setq icicle-incremental-completion-p  'always))
  ;;     ((nil) (setq icicle-incremental-completion-p  nil)))

  ;; $$$$$ (unless (input-pending-p)             ; Do nothing if user hit a key.

  ;; Upgrade `icicle-incremental-completion-p' if we are redisplaying, so that completions will
  ;; be updated by `icicle-call-then-update-Completions' when you edit.
  (interactive)
  (setq icicle-incremental-completion-p  icicle-incremental-completion)
  (when (and (eq t icicle-incremental-completion-p)  (get-buffer-window "*Completions*" 0))
    (setq icicle-incremental-completion-p  'always))
  (let ((nb-cands  (length icicle-completion-candidates)))
    ;; $$$$$$ Could use this binding to prevent frame fitting, to allow room for images.
    ;; But that is not really the solution.  Really should fit the frame or window in such a way
    ;; that it takes image sizes into account.  Might need to wait for a fix to Emacs bug #7822.
    ;; (autofit-frames-flag  (not icicle-image-files-in-Completions)))
    (cond ((eq no-display-p 'no-msg))   ; No-op.
          (no-display-p
           (icicle-msg-maybe-in-minibuffer
            "Candidates updated (%s matching): %s" icicle-current-completion-mode
            (icicle-propertize (format "%d" nb-cands) 'face 'icicle-msg-emphasis)))
          ((null icicle-completion-candidates)
           (save-selected-window (icicle-remove-Completions-window))
           (icicle-msg-maybe-in-minibuffer
            (if (eq 'apropos icicle-current-completion-mode)
                (let ((typ  (car (rassq icicle-apropos-complete-match-fn
                                        icicle-S-TAB-completion-methods-alist))))
                  (concat "No " typ (and typ  " ") "completions"))
              (case (icicle-current-TAB-method)
                (fuzzy        "No fuzzy completions")
                (swank        "No swank (fuzzy symbol) completions")
                (vanilla      "No vanilla completions")
                (t            "No prefix completions")))))
          (t
           (when (> nb-cands icicle-incremental-completion-threshold)
             (message "Displaying completion candidates..."))
           ;; Display `*Completions*' now, so we can get its window's width.
           ;; We don't wait for `with-output-to-temp-buffer' to display it, because displaying it
           ;; might lead to splitting the display window, which would change its width.
           ;; We need to know the width in order to calculate the proper candidate formatting.
           (when (consp icicle-completion-candidates)
             (let ((fit-frame-inhibit-fitting-flag  t)
                   (comp-buf                        (get-buffer-create "*Completions*")))
               (unless (get-buffer-window comp-buf 'visible)
                 (save-selected-window (display-buffer comp-buf t 0)
                                       (deactivate-mark))))) ; Remove any leftover mouse selection.
           (with-output-to-temp-buffer "*Completions*"
             ;; Each candidate in `icicle-completion-candidates' is a string, regardless of the
             ;; original type of candidate used (e.g. symbol, string, alist candidate,...).  Here,
             ;; provided `icicle-fancy-cands-internal-p' is non-nil, we transform these candidates,
             ;; replacing each by a string that takes into account symbol properties
             ;; `icicle-display-string' and `icicle-special-candidate'.
             ;;
             ;; Because `icicle-completion-candidates' is affected, changes to the candidate strings
             ;; (e.g. propertizing) are also reflected in the completion return value chosen by the
             ;; user.  It is not only the display in `*Completions*' that is affected.
             ;;
             ;; The symbol whose properties are used is the one in the current obarray that is named
             ;; by the string candidate to be transformed.  If there is no such symbol, then no
             ;; transformation occurs.  Unless `minibuffer-completion-table' is an obarray, the
             ;; global obarray is used to get the symbol.
             ;;
             ;; 1. If the symbol has an `icicle-display-string' property, then that property value
             ;;    must be a string (possibly propertized).  We replace the candidate by that string.
             ;;
             ;; 2. If the symbol has an `icicle-special-candidate' property, then we transfer the
             ;;    property to the candidate string as a set of text properties.  (If the value is
             ;;    not a plist, and `icicle-special-candidate-regexp' is nil, then just apply face
             ;;    `icicle-special-candidate'.)  The effect is similar to using
             ;;    `icicle-special-candidate-regexp', but the completion return value is also
             ;;    affected.
             (when icicle-fancy-cands-internal-p
               (setq icicle-completion-candidates
                     (mapcar (lambda (cand)
                               (let* ((symb          (intern-soft
                                                      cand (and (arrayp minibuffer-completion-table)
                                                                minibuffer-completion-table)))
                                      (display-strg  (and symb
                                                          (stringp (get symb 'icicle-display-string))
                                                          (get symb 'icicle-display-string)))
                                      (new-cand      (or display-strg  cand))
                                      (spec-prop     (and symb  (get symb 'icicle-special-candidate))))
                                 ;; Apply `icicle-special-candidate' property's value.
                                 ;; If the value is a plist, then apply the properties as text props.
                                 ;; Else (the value is t), apply face `icicle-special-candidate'.
                                 (when spec-prop
                                   (setq new-cand  (copy-sequence new-cand))
                                   (if (consp spec-prop)
                                       (add-text-properties 0 (length new-cand) spec-prop new-cand)
                                     (unless icicle-special-candidate-regexp
                                       (add-text-properties 0 (length new-cand)
                                                            '(face icicle-special-candidate)
                                                            new-cand))))
                                 new-cand))
                             icicle-completion-candidates)))
             (icicle-display-completion-list (if reverse-p
                                                 (reverse icicle-completion-candidates)
                                               icicle-completion-candidates)
                                             nil ; IGNORED
                                             nb-cands))
           (save-excursion
             (save-window-excursion
               (with-current-buffer (get-buffer "*Completions*")
                 (let* ((buffer-read-only  nil)
                        (eob               (point-max))
                        (filep             (or (icicle-file-name-input-p)  icicle-abs-file-candidates))
                        (dir               (and filep  icicle-last-input
                                                (icicle-file-name-directory icicle-last-input)))
                        (histvar           (and (symbolp minibuffer-history-variable)
                                                (boundp minibuffer-history-variable)
                                                minibuffer-history-variable))
                        (hist              (and histvar
                                                (if filep
                                                    ;; Need (or DIR  default-directory) instead of DIR
                                                    ;; because Emacs 20 `expand-file-name' crashes.
                                                    (let ((default-directory  (or dir  default-directory)))
                                                      (mapcar #'expand-file-name (symbol-value histvar)))
                                                  (symbol-value histvar))))
                        (case-fold-search
                         ;; Don't bother with buffer completion, `read-buffer-completion-ignore-case'.
                         (if (and filep  (boundp 'read-file-name-completion-ignore-case))
                             read-file-name-completion-ignore-case
                           completion-ignore-case)))
                   (when (fboundp 'remove-images)  (remove-images (point-min) (point-max)))
                   (goto-char (icicle-start-of-candidates-in-Completions))
                   (while (not (eobp))
                     (let* ((beg    (point))
                            (end    (next-single-property-change beg 'mouse-face nil eob))
                            (next   (next-single-property-change end 'mouse-face nil eob))
                            (faces  ()))

                       ;; Highlight candidate specially if it is a proxy candidate.
                       (let ((candidate  (icicle-current-completion-in-Completions)))
                         ;;$$$ (when dir (setq candidate  (expand-file-name candidate dir)))
                         (when (member candidate icicle-proxy-candidates)
                           (setq faces  (cons 'icicle-proxy-candidate faces))
                           (if (not icicle-proxy-candidate-regexp)
                               (add-text-properties beg end (cons 'face (list faces)))
                             (save-match-data
                               (when (string-match icicle-proxy-candidate-regexp candidate)
                                 (add-text-properties (+ beg (match-beginning 0)) (+ beg (match-end 0))
                                                      (cons 'face (list faces))))))))

                       ;; Highlight candidate specially if it is an extra candidate.
                       (let ((candidate  (icicle-current-completion-in-Completions)))
                         ;;$$$ (when dir (setq candidate  (expand-file-name candidate dir)))
                         (save-match-data
                           (when (member candidate icicle-extra-candidates)
                             (setq faces  (cons 'icicle-extra-candidate faces))
                             (add-text-properties beg end (cons 'face (list faces))))))

                       ;; Highlight candidate specially if it is a special candidate.
                       (let ((candidate  (icicle-current-completion-in-Completions)))
                         ;;$$$ (when dir (setq candidate  (expand-file-name candidate dir)))
                         (save-match-data
                           (when (and icicle-special-candidate-regexp
                                      (string-match icicle-special-candidate-regexp candidate))
                             (setq faces  (cons 'icicle-special-candidate faces))
                             (add-text-properties (+ beg (match-beginning 0)) (+ beg (match-end 0))
                                                  (cons 'face (list faces))))))

                       ;; Highlight candidate (`*-historical-candidate') if it was used previously.
                       (when icicle-highlight-historical-candidates-flag
                         (let ((candidate  (icicle-current-completion-in-Completions)))
                           (when (and (consp hist)  (not (member candidate icicle-hist-cands-no-highlight)))
                             ;; Need (or DIR  default-directory) instead of DIR
                             ;; because Emacs 20 `expand-file-name' crashes.
                             (let ((default-directory  (or dir  default-directory)))
                               (when (member (if filep
                                                 (expand-file-name (icicle-transform-multi-completion
                                                                    candidate))
                                               candidate)
                                             hist)
                                 (add-text-properties
                                  beg end `(face ,(setq faces  (cons 'icicle-historical-candidate faces)))))))))

                       ;; Highlight Info index-entry cand (using face `icicle-historical-candidate-other')
                       ;; if its node has been visited.
                       ;;
                       ;; FREE var here (bound in `icicle-Info-index'): `icicle-Info-hist-list'.
                       (when (and (> emacs-major-version 21)
                                  (memq icicle-last-top-level-command '(Info-index icicle-Info-index))
                                  (boundp 'icicle-Info-hist-list)  (consp icicle-Info-hist-list)
                                  (or (eq this-command 'icicle-display-candidates-in-Completions)
                                      (and icicle-highlight-historical-candidates-flag
                                           icicle-Info-highlight-visited-nodes
                                           (or (not (numberp icicle-Info-highlight-visited-nodes))
                                               (<= nb-cands icicle-Info-highlight-visited-nodes)))))
                         (message "Highlighting topics in all visited nodes...")
                         (let ((candidate  (icicle-current-completion-in-Completions)))
                           (when (or (assoc candidate icicle-Info-index-cache)
                                     (icicle-some (mapcar 'cadr icicle-Info-hist-list)
                                                  candidate
                                                  #'icicle-Info-node-is-indexed-by-topic))
                             (add-text-properties
                              beg end `(face ,(setq faces  (cons 'icicle-historical-candidate-other faces)))))))

                       ;; Highlight, inside the candidate, the expanded common match.
                       (when (and icicle-current-input  (not (string= "" icicle-current-input)))
                         (save-excursion
                           (save-restriction
                             (narrow-to-region beg end) ; Restrict to the completion candidate.
                             (when (re-search-forward (regexp-quote (icicle-minibuf-input-sans-dir
                                                                     icicle-current-input))
                                                      nil t)
                               (setq faces  (cons 'icicle-common-match-highlight-Completions faces))
                               (put-text-property (match-beginning 0) (point) 'face faces)))))

                       ;; Hide match for `icicle-current-input' (expanded common match, if available),
                       ;; if `icicle-hide-common-match-in-Completions-flag' is non-nil.
                       (save-excursion
                         (save-restriction
                           (narrow-to-region beg end) ; Restrict to the completion candidate.
                           (when (and icicle-hide-common-match-in-Completions-flag  icicle-common-match-string)
                             (when (re-search-forward (regexp-quote icicle-common-match-string) nil t)
                               (if (> emacs-major-version 20)
                                   (put-text-property (match-beginning 0) (point) 'display "...")
                                 (put-text-property (match-beginning 0) (point) 'invisible t))))))

                       ;; Highlight, inside the candidate, what the input expression matches.
                       (unless (and icicle-current-raw-input  (string= "" icicle-current-raw-input)
                                    icicle-apropos-complete-match-fn)
                         (save-excursion
                           (save-restriction
                             (narrow-to-region beg end) ; Restrict to the completion candidate.
                             (let ((fn  (if (and (eq 'prefix icicle-current-completion-mode)
                                                 (not (memq (icicle-current-TAB-method) '(fuzzy swank))))
                                            ;; $$$$$$ What is best for `vanilla' (Emacs 23) completion?
                                            'search-forward
                                          (case icicle-apropos-complete-match-fn
                                            (icicle-scatter-match
                                             (lambda (input bound noerr)
                                               (re-search-forward (icicle-scatter input) bound noerr)))
                                            (icicle-levenshtein-match
                                             (if (= icicle-levenshtein-distance 1)
                                                 (lambda (input bound noerr)
                                                   (re-search-forward (icicle-levenshtein-one-regexp input)
                                                                      bound noerr))
                                               're-search-forward))
                                            (otherwise 're-search-forward)))))
                               (save-excursion
                                 (when (and (funcall fn (icicle-minibuf-input-sans-dir icicle-current-raw-input)
                                                     nil t)
                                            (not (eq (match-beginning 0) (point))))
                                   (setq faces  (cons 'icicle-match-highlight-Completions faces))
                                   (put-text-property (match-beginning 0) (point) 'face faces)))

                               ;; If `icicle-hide-non-matching-lines-flag' then hide all lines
                               ;; of candidate that do not match current input.
                               (let ((candidate  (icicle-current-completion-in-Completions))
                                     (input      (icicle-minibuf-input-sans-dir
                                                  icicle-current-raw-input))
                                     (cbeg       beg))
                                 (when (and icicle-hide-non-matching-lines-flag
                                            (string-match "\n" candidate)
                                            (not (string= "\n" candidate)))
                                   (goto-char cbeg)
                                   (while (not (eobp))
                                     (unless (funcall fn input (line-end-position) t)
                                       (if (> emacs-major-version 20)
                                           (put-text-property (line-beginning-position)
                                                              (min (1+ (line-end-position)) (point-max))
                                                              'display "...\n")
                                         (put-text-property (line-beginning-position)
                                                            (min (1+ (line-end-position)) (point-max))
                                                            'invisible t)))
                                     (forward-line 1))))))))

                       ;; Highlight candidate if it has been saved.
                       (when (and icicle-highlight-saved-candidates-flag  icicle-saved-completion-candidates)
                         (let ((candidate  (icicle-current-completion-in-Completions)))
                           (when (member candidate icicle-saved-completion-candidates)
                             (let ((ov  (make-overlay beg end)))
                               (push ov icicle-saved-candidate-overlays)
                               (overlay-put ov 'face 'icicle-saved-candidate)
                               (overlay-put ov 'priority '10)))))

                       ;; Treat `icicle-candidate-properties-alist'.
                       ;; A `face' prop will unfortunately wipe out any `face' prop we just applied.
                       (when icicle-candidate-properties-alist
                         (save-excursion
                           (save-restriction
                             (narrow-to-region beg end) ; Restrict to the completion candidate.
                             (let* ((candidate  (buffer-substring (point-min) (point-max)))
                                    (orig-pt    (point))
                                    (start      0)
                                    (end        0)
                                    (partnum    1)
                                    (join       (concat "\\(" icicle-list-join-string "\\|\\'\\)"))
                                    (len-cand   (length candidate))
                                    (len-join   (length icicle-list-join-string))
                                    (first      t))
                               (save-match-data
                                 (while (and (or first
                                                 (not (= end (match-beginning 0)))
                                                 (< (+ end len-join) len-cand))
                                             (string-match join candidate (if (and (not first)
                                                                                   (= end (match-beginning 0))
                                                                                   (< end len-cand))
                                                                              (+ end len-join)
                                                                            end))
                                             (< end len-cand))
                                   (setq first  nil
                                         end    (or (match-beginning 0)  len-cand))
                                   (let* ((entry                   (assq partnum
                                                                         icicle-candidate-properties-alist))
                                          (properties              (cadr entry))
                                          (propertize-join-string  (car (cddr entry))))
                                     (when properties
                                       (add-text-properties (+ start orig-pt) (+ end orig-pt) properties))
                                     (when propertize-join-string
                                       (add-text-properties (+ end orig-pt) (+ end orig-pt len-join)
                                                            properties)))
                                   (setq partnum  (1+ partnum)
                                         start    (match-end 0))))))))

                       ;; Thumbnail image for an image file or image-file bookmark (Bookmark+): Maybe show it
                       ;; in `*Completions*'; maybe show it only in `*Completions*' mouseover tooltip.
                       (when (or (and icicle-image-files-in-Completions
                                      (if (fboundp 'display-graphic-p) (display-graphic-p) window-system)
                                      (or (and filep  (fboundp 'image-file-name-regexp))
                                          (and icicle-show-multi-completion-flag
                                               (symbolp icicle-last-top-level-command)
                                               (string-match "^icicle-bookmark-"
                                                             (symbol-name icicle-last-top-level-command)))))
                                 (and (boundp 'tooltip-mode)  tooltip-mode  icicle-image-preview-in-tooltip))
                         (let ((image-file
                                (if (and icicle-show-multi-completion-flag
                                         (symbolp icicle-last-top-level-command)
                                         ;; We could alternatively put a property on such symbols and
                                         ;; test that.  But just matching the cmd name is OK so far.
                                         (string-match "^icicle-bookmark-"
                                                       (symbol-name icicle-last-top-level-command)))
                                    ;; This is bound by the bookmark commands to `(1)': bookmark name.
                                    ;; The file name is part #2, so we rebind this here.
                                    (let ((icicle-list-use-nth-parts  '(2)))
                                      (icicle-transform-multi-completion
                                       (icicle-current-completion-in-Completions)))
                                  (icicle-transform-multi-completion
                                   (icicle-current-completion-in-Completions)))))
                           (when (and (require 'image-dired nil t)
                                      (icicle-string-match-p (image-file-name-regexp) image-file))
                             (let* ((thumb-img  (image-dired-get-thumbnail-image image-file))
                                    (thumb-img  (and thumb-img
                                                     (append (image-dired-get-thumbnail-image image-file)
                                                             '(:margin 2)))))
                               (when thumb-img
                                 ;; In `tooltip-mode', show image preview on mouseover,
                                 ;; unless it is a thumbnail and `*Completions*' already shows thumbnails.
                                 (when (and (boundp 'tooltip-mode)  tooltip-mode
                                            (or (not icicle-image-files-in-Completions)
                                                (not (numberp icicle-image-preview-in-tooltip))))
                                   (with-current-buffer "*Completions*"
                                     (put-text-property
                                      (point) (+ (point) (length (icicle-current-completion-in-Completions)))
                                      'help-echo 'icicle-mouseover-help)))
                                 (when icicle-image-files-in-Completions
                                   (let ((img-ov  (overlays-in (point) (min (point-max) (1+ (point))))))
                                     (if img-ov
                                         (delete-overlay (car img-ov))
                                       (put-image thumb-img beg)
                                       (setq img-ov  (loop for ov in (overlays-in
                                                                      (point) (min (point-max) (1+ (point))))
                                                           when (overlay-get ov 'put-image) collect ov into ovs
                                                           finally return (car ovs)))
                                       (overlay-put img-ov 'image-file image-file)
                                       (overlay-put img-ov 'thumb-img thumb-img)
                                       (overlay-put img-ov 'image-size (image-size thumb-img))))
                                   ;; `image-only'.  Replace file name with a space.
                                   ;;                And hide mouse-face highlighting, as it just confuses.
                                   (when (eq 'image-only icicle-image-files-in-Completions)
                                     (with-current-buffer "*Completions*"
                                       (put-text-property
                                        (point) (+ (point) (length (icicle-current-completion-in-Completions)))
                                        'mouse-face 'default))
                                     (let ((name-ov  (overlays-in end end)))
                                       (if name-ov
                                           (delete-overlay (car name-ov))
                                         (setq name-ov  (make-overlay beg end))
                                         (overlay-put name-ov 'display " "))))))))))
                       (goto-char next)))

                   ;; Remove all newlines for images-only display.
                   (when (eq icicle-image-files-in-Completions 'image-only)
                     (save-excursion (goto-char (icicle-start-of-candidates-in-Completions))
                                     (while (and (re-search-forward "$")  (not (eobp))) (delete-char 1)))))
                 (set-buffer-modified-p nil)
                 (setq buffer-read-only  t))))

           ;; Put lighter, number of candidates, completion mode, and sort order in mode line.
           (with-current-buffer (get-buffer "*Completions*")
             (set (make-local-variable 'mode-line-format)
                  (format "  %s%s%s, sorting %s%s"
                          (icicle-propertize (format "%d" nb-cands) 'face 'icicle-mode-line-help)
                          (if (and icicle-max-candidates
                                   (integerp icicle-max-candidates) ; Not `RESET'.
                                   (< icicle-max-candidates icicle-nb-candidates-before-truncation))
                              (format "%s candidates shown"
                                      (icicle-propertize (format "/%d" icicle-nb-candidates-before-truncation)
                                                         'face 'icicle-mode-line-help))
                            " candidates")
                          (if (memq icicle-current-completion-mode '(prefix apropos))
                              (format ", %s completion"
                                      (icicle-propertize
                                       (cond ((eq 'apropos icicle-current-completion-mode)
                                              ;; If nil, COLLECTION arg is probably a fn and we set it to nil
                                              ;; to prevent automatic input matching in
                                              ;; `icicle-unsorted-apropos-candidates', because COLLECTION fn
                                              ;; does everything.  So here we treat nil like `apropos'.
                                              (if icicle-apropos-complete-match-fn
                                                  (or (car (rassq icicle-apropos-complete-match-fn
                                                                  icicle-S-TAB-completion-methods-alist))
                                                      "")
                                                "apropos"))
                                             ((eq 'prefix icicle-current-completion-mode)
                                              (case (icicle-current-TAB-method)
                                                (fuzzy    "fuzzy")
                                                (swank    "swank (fuzzy symbol)")
                                                (vanilla  "vanilla")
                                                (t        "prefix"))))
                                       'face 'icicle-mode-line-help))
                            "")
                          (icicle-propertize (or (car (rassoc icicle-sort-comparer icicle-sort-orders-alist))
                                                 "turned OFF")
                                             'face 'icicle-mode-line-help)
                          (if (and icicle-reverse-sort-p  icicle-sort-comparer)
                              (icicle-propertize " (reversed)" 'face 'icicle-mode-line-help)
                            "")))
             (let* ((lighter  (cadr (assoc 'icicle-mode minor-mode-alist)))
                    (regexp   (and lighter  (concat (regexp-quote icicle-lighter-truncation) "$")))
                    props)
               (when lighter
                 (setq lighter  (concat lighter " ")
                       props    (text-properties-at 0 lighter))
                 (when (string-match regexp lighter) (setq lighter  (substring lighter 0 (match-beginning 0))))
                 (add-text-properties 0 (length lighter) props lighter))
               (setq mode-line-format  (concat lighter mode-line-format)))
             (goto-char (icicle-start-of-candidates-in-Completions))
             (set-window-point (get-buffer-window "*Completions*" 0) (point))
             (icicle-fit-completions-window))

           ;; Use the same font family as the starting buffer.  This is particularly for picking up
           ;; the proper font for Unicode chars in `*Completions*'.  Emacs 23+ only.
           ;; But skip this if using `oneonone.el', since `1on1-display-*Completions*-frame' does it.
           (when (and (not (fboundp '1on1-display-*Completions*-frame))
                      (get-buffer-window "*Completions*" 'visible)
                      icicle-pre-minibuffer-buffer
                      (> emacs-major-version 22))
             (save-window-excursion
               (select-window (get-buffer-window "*Completions*" 'visible))
               (when (one-window-p t)   ; $$$$$ Also this? (window-dedicated-p (selected-window))
                 (let* ((orig-win       (get-buffer-window icicle-pre-minibuffer-buffer 'visible))
                        (orig-font-fam  (and (window-live-p orig-win)
                                             (save-window-excursion (select-window orig-win)
                                                                    (face-attribute 'default :family)))))
                   (when orig-font-fam (set-face-attribute 'default (selected-frame) :family orig-font-fam))))))
           (message nil)))))            ; Clear out any "Looking for..."


;; $$ Probably need to do something to work around problem of Windows
;; selecting the new frame, when `pop-up-frames' is non-nil.  Need to
;; redirect focus back to the frame with the minibuffer.  Leave it as
;; is, for now, in hopes Emacs will eventually fix this.
;;
(defun icicle-minibuffer-help ()        ; Bound to `M-?' in the minibuffer.
  "Describe Icicles minibuffer and *Completion* buffer bindings."
  (interactive)
  (let ((cur-buf        (current-buffer))
        (icicles-cmd-p  (or icicle-candidate-action-fn icicle-multi-completing-p)))
    (icicle-with-help-window "*Help*"
      (help-setup-xref (list #'icicle-minibuffer-help) (interactive-p))
      (when (icicle-completing-p)
        (princ (format "You are completing input%s.%s"
                       (if icicles-cmd-p
                           (format " for an Icicles %scommand%s"
                                   (if icicle-candidate-action-fn "multi-" "")
                                   (if icicle-multi-completing-p " that uses multi-\ncompletion" ""))
                         "")
                       (if (and icicles-cmd-p  (not icicle-multi-completing-p)) "\n" "  ")))
        (princ "To show help on individual candidates:\n")
        (princ "
     Current candidate                       C-M-RET, C-M-mouse-2
     Next, previous candidate                C-M-down, C-M-up,
                                              C-M- plus mouse wheel
                    prefix-match candidate   C-M-end, C-M-home
                    apropos-match candidate  C-M-next, C-M-prior\n\n")
        (when icicle-candidate-action-fn
          (princ "To act on individual candidates:
     Current candidate                       C-RET, C-mouse-2
     Next, previous candidate                C-down, C-up,
                                              C- plus mouse wheel
                    prefix-match candidate   C-end, C-home
                    apropos-match candidate  C-next, C-prior
     All candidates at once                  C-! (each) or M-! (list)
     Delete object named by candidate        S-delete
     Object-action: apply a fn to candidate  M-RET"))
        (when icicle-candidate-alt-action-fn
          (princ "\n\nFor alt action, use `C-S-' instead of `C-', but use `C-|' or `M-|',\n\
     instead of `C-!' or `M-!', to act on all.\n")))
      (if icicle-completing-p
          (with-current-buffer standard-output
            (insert (concat "\n" (icicle-help-string-completion))))
        (princ (icicle-help-string-non-completion))))
    ;; Don't bother to do this for Emacs 21.3.  Its `help-insert-xref-button' signature is different.
    (when (and (> emacs-major-version 21)
               (require 'help-mode nil t)
               (fboundp 'help-insert-xref-button)) ; In `help-mode.el'.
      (save-excursion
        (with-current-buffer (get-buffer "*Help*")
          (let ((buffer-read-only  nil))
            (goto-char (point-min))
            (help-insert-xref-button "[Icicles Help on the Web]" 'icicle-help-button)
            (insert "                        ")
            (help-insert-xref-button "[Icicles Doc, Part 1]" 'icicle-commentary1-button)
            (insert "\n")
            (help-insert-xref-button "[Icicles Options & Faces]" 'icicle-customize-button)
            (insert "                        ")
            (help-insert-xref-button "[Icicles Doc, Part 2]" 'icicle-commentary2-button)
            (insert "\n\n")
            (goto-char (point-max))
            (insert (make-string 70 ?_))
            (insert (funcall
                     (if (fboundp 'help-commands-to-key-buttons) ; In `help-fns.el'.
                         #'help-commands-to-key-buttons
                       #'substitute-command-keys)
                     "\n\nSend an Icicles bug report: `\\[icicle-send-bug-report]'.\n\n"))
            (help-insert-xref-button "[Icicles Help on the Web]" 'icicle-help-button)
            (insert "                        ")
            (help-insert-xref-button "[Icicles Doc, Part 1]" 'icicle-commentary1-button)
            (insert "\n")
            (help-insert-xref-button "[Icicles Options & Faces]" 'icicle-customize-button)
            (insert "                        ")
            (help-insert-xref-button "[Icicles Doc, Part 2]" 'icicle-commentary2-button)
            (insert "\n\n")
            (goto-char (point-min))))))
    (when (memq cur-buf (list (window-buffer (minibuffer-window)) (get-buffer "*Completions*")))
      (select-window (minibuffer-window))
      (select-frame-set-input-focus (selected-frame)))))

(defun icicle-help-string-completion ()
  "Update the bindings within the Icicles completion help string."
  (icicle-S-iso-lefttab-to-S-TAB
   (funcall
    (if (fboundp 'help-commands-to-key-buttons) ; In `help-fns+.el'.
        #'help-commands-to-key-buttons
      #'substitute-command-keys)
    (concat
     (format "\\<minibuffer-local-completion-map>

                    Icicles Minibuffer Completion
                    -----------------------------

Completion indicators:

  Mode line `Icy' lighter (additive):
    red = Completion available      (use `TAB' or `S-TAB' to complete)
    +   = Multi-command completion   (use `C-RET' to act on candidate)
    ||  = Multi-completion candidates  (use `C-M-j' to separate parts)
    ... = `icicle-max-candidates' shown        (use `C-x #' to change)

  Prompt prefix (exclusive):
    . = Simple completion
    + = Multi-command completion

You can complete your minibuffer input in several ways.
These are the main Icicles actions and their minibuffer key bindings:

 * Show Icicles minibuffer help (this).      \\[icicle-minibuffer-help]
     For help on individual completion candidates, see \"Show help on
     individual completion candidates\", below.

 * Abandon or commit your input.
     Abandon input                           \\[icicle-abort-recursive-edit]
     Commit input to Emacs                   RET
       Complete partial input, then commit   \\<minibuffer-local-must-match-map>\
\\[icicle-apropos-complete-and-exit]\\<minibuffer-local-completion-map>

 * Toggle/cycle Icicles options on the fly.  Key:   \tCurrently:
     Highlighting of past inputs             \\[icicle-toggle-highlight-historical-candidates]\t%S
     Highlighting of saved candidates        \\[icicle-toggle-highlight-saved-candidates]\t%S
     Showing candidates with WYSIWYG         \\[icicle-toggle-WYSIWYG-Completions]\t%S
     Removal of duplicate candidates         \\[icicle-toggle-transforming]\t%s
     Sort order                              \\[icicle-change-sort-order]\t%s
     Alternative sort order                  \\[icicle-dispatch-M-comma]\t%s
     Swap alternative/normal sort            \\[icicle-toggle-alternative-sorting]
     Case sensitivity                        \\[icicle-toggle-case-sensitivity]\t%S
     `.' matching newlines too (any char)    \\[icicle-toggle-dot]\t%S
     Escaping of special regexp chars        \\[icicle-toggle-regexp-quote]\t%S
     Incremental completion                  \\[icicle-cycle-incremental-completion]\t%s
     Input expansion to common match (toggle)\\[icicle-toggle-expand-to-common-match]\t%S
     Input expansion to common match (cycle) \\[icicle-cycle-expand-to-common-match]\t%s
     Hiding common match in `*Completions*'  \\[icicle-dispatch-C-x.]\t%S
     Hiding no-match lines in `*Completions*' C-u \\[icicle-dispatch-C-x.]\t%s
     Horizontal/vertical candidate layout    \\[icicle-toggle-completions-format]\t%s
     S-TAB completion method                 \\[icicle-next-S-TAB-completion-method]\t%s
     TAB completion method                   \\[icicle-next-TAB-completion-method]\t%s
     Showing image-file thumbnails (E22+)    C-x t\t%s
     Showing candidate annotations           \\[icicle-toggle-annotation]\t%S
     Inclusion of proxy candidates           \\[icicle-toggle-proxy-candidates]\t%S
     Ignoring certain file extensions        \\[icicle-dispatch-C-.]\t%S
     Expansion of directory candidates       \\[icicle-toggle-expand-directory]\t%S
     Checking for remote file names          \\[icicle-dispatch-C-^]\t%S"
             (if icicle-highlight-historical-candidates-flag 'yes 'no)
             (if icicle-highlight-saved-candidates-flag 'yes 'no)
             (if icicle-WYSIWYG-Completions-flag 'yes 'no)
             (cond ((not icicle-transform-function) "no")
                   ((or (eq icicle-transform-function 'icicle-remove-duplicates)
                        (and icicle-extra-candidates
                             (eq icicle-transform-function 'icicle-remove-dups-if-extras)))
                    "yes")
                   ((eq 'icicle-remove-dups-if-extras icicle-transform-function)
                    "yes in general, but not now")
                   (t icicle-transform-function))
             (icicle-current-sort-order nil)
             (icicle-current-sort-order 'ALTERNATIVE)
             (if case-fold-search 'no 'yes)
             (if (string= icicle-dot-string icicle-anychar-regexp) 'yes 'no)
             (if icicle-regexp-quote-flag 'yes 'no)
             (case icicle-incremental-completion
               ((nil) "no")
               ((t)   "yes, if *Completions* showing")
               (t     "yes, always (eager)"))
             (if (eq icicle-expand-input-to-common-match 0) 'no 'yes)
             (case icicle-expand-input-to-common-match
               (0 "never")
               (1 "explicit completion")
               (2 "only one completion")
               (3 "`TAB' or only one")
               (t "always"))
             (if icicle-hide-common-match-in-Completions-flag 'yes 'no)
             (if icicle-hide-non-matching-lines-flag 'yes 'no)
             icicle-completions-format
             (car (rassq icicle-apropos-complete-match-fn icicle-S-TAB-completion-methods-alist))
             (icicle-current-TAB-method)
             (case icicle-image-files-in-Completions
               ((nil) "no")
               (image "image only")
               (t "image and name"))
             (if icicle-show-annotations-flag 'yes 'no)
             (if icicle-add-proxy-candidates-flag 'yes 'no)
             (if completion-ignored-extensions 'yes 'no)
             (if icicle-find-file-expand-directory-flag 'yes 'no)
             (if icicle-test-for-remote-files-flag 'yes 'no))

     (and (memq system-type '(ms-dos windows-nt cygwin)) ; MS Windows only.
          (format "\\<minibuffer-local-completion-map>
     Considering network drives as remote    \\[icicle-toggle-network-drives-as-remote]\t%S"
                  (if icicle-network-drive-means-remote-flag 'yes 'no)))

     (format "\\<minibuffer-local-completion-map>
     Ignoring space prefix for buffer names  \\[icicle-dispatch-M-_]\t%S
     Using `C-' for multi-command actions    \\[icicle-toggle-C-for-actions]\t%S
     Using `~' for your home directory       \\[icicle-toggle-~-for-home-dir]\t%S
     `icicle-search' all-current highlights  \\[icicle-dispatch-C-^]\t%S
     Whole-word searching                    \\[icicle-dispatch-M-q]\t%S
     Removal of `icicle-search' highlighting \\[icicle-dispatch-C-.]\t%S
     Replacement of whole search hit         \\[icicle-dispatch-M-_]\t%S
     Replacement of expanded common match    \\[icicle-toggle-search-replace-common-match]\t%S
     Searching complements of contexts       \\[icicle-toggle-search-complementing-domain]\t%S

 * Regexp-quote input, then apropos-complete \\[icicle-regexp-quote-input]

 * Change the set of completion candidates.  Modify your input.
     Edit your input                         (just edit in minibuffer)
     Erase your input (clear minibuffer)     \\[icicle-erase-minibuffer-or-history-element]
     Goto/kill non-matching portion of input \\[icicle-goto/kill-failed-input]
     Retrieve previous completion inputs     \\[icicle-retrieve-previous-input], \
\\[icicle-retrieve-next-input]
     Match another regexp (chaining)         \\[icicle-narrow-candidates]
     Satisfy another predicate (chaining)    \\[icicle-narrow-candidates-with-predicate]
     Remove a candidate from set of matches  delete, S-mouse-2
     Yank text at cursor into minibuffer     \\[icicle-insert-string-at-point]
     Insert text (string) from a variable    \\[icicle-insert-string-from-variable]
     Insert `icicle-list-join-string'        \\[icicle-insert-list-join-string]
     Insert previously entered input(s)      \\[icicle-insert-history-element]
     Insert completion candidates(s)         \\[icicle-roundup]
     Insert key description (key completion) \\[icicle-dispatch-M-q]

 * Complete your current input in the minibuffer.
     Apropos (regexp) completion             \\[icicle-apropos-complete]
       Without displaying candidates         \\[icicle-apropos-complete-no-display]
       Complete and match another regexp     \\[icicle-apropos-complete-and-narrow]
     Prefix completion
       As much as possible                   \\[icicle-prefix-complete]
         Without displaying candidates       \\[icicle-prefix-complete-no-display]
       A word at a time                      \\[icicle-prefix-word-complete]
     Complete and commit \\<minibuffer-local-must-match-map>\
\\[icicle-apropos-complete-and-exit]\\<minibuffer-local-completion-map>
     Complete search string using past input \\[icicle-apropos-complete]

 * Display/navigate completions for current input (in `*Completions*').
     Show completion candidates
       Prefix completion                     \\[icicle-prefix-complete] (repeat)
       Apropos completion                    \\[icicle-apropos-complete]
     Move between minibuffer and list        \\<completion-list-mode-map>\
\\[icicle-insert-completion]
     Cycle among completion candidates       right, left, \
\\[icicle-move-to-next-completion], \\[icicle-move-to-previous-completion]
       Within a `*Completions*' column       down, up
     Choose a completion candidate           \\[choose-completion], \
\\[mouse-choose-completion]\\<minibuffer-local-completion-map>

 * Cycle among input candidates.
     Completion candidates
       Current mode                          down, up, mouse wheel
       Prefix completion                     end, home
       Apropos completion                    next, prior
     Minibuffer history items                \\[next-history-element], \
\\[previous-history-element]
     Completion history items                \\[icicle-retrieve-previous-input], \
\\[icicle-retrieve-next-input]

 * Show help on individual completion candidates.
     Current candidate                       C-M-RET, C-M-mouse-2
     Next, previous candidate                C-M-down, C-M-up,
                                              C-M- plus mouse wheel
                    prefix-match candidate   C-M-end, C-M-home
                    apropos-match candidate  C-M-next, C-M-prior

 * Choose a previous input from the minibuffer history.
     Complete to insert a previous input     \\[icicle-insert-history-element]
     Complete against history items          \\[icicle-history], \
\\[icicle-keep-only-past-inputs]
     Restrict candidates to history items    \\[icicle-keep-only-past-inputs]
     Change to another history               \\[icicle-other-history]
     List history items first in Completions \\[icicle-toggle-alternative-sorting]
     Cycle among minibuffer history items    \\[next-history-element], \
\\[previous-history-element]

 * Delete history entries
     Delete current entry (cycling)          \\[icicle-erase-minibuffer-or-history-element]
     Delete any or all entries               \\[icicle-clear-current-history]

 * Multi-commands: Act on completion candidates.
   For alternative action, use `C-S-' instead of `C-', but
   `C-|' and `M-|' are alternative action versions of `C-!' and `M-!'.
     Current candidate                       C-RET, C-mouse-2
     Next, previous candidate                C-down, C-up,
                                             C- with mouse wheel
                    prefix-match candidate   C-end, C-home
                    apropos-match candidate  C-next, C-prior
     Act on each matching candidate, in turn C-!
     Act on the list of matching candidates  M-!
     Delete object named by candidate        S-delete
     Remove candidate from set of matches    delete, S-mouse-2
     Save candidate (add to those saved)     insert, M-S-mouse-2
     Object-action: apply a fn to candidate  M-RET

 * Act on multiple minibuffer inputs         \\[icicle-multi-inputs-act]

 * Search and replace (e.g. `C-c `').  See also `icicle-search'.
     Use action keys (prefix `C-') to navigate.
     Use alternative action keys (prefix `C-S-') to replace matches.
     Toggle input highlighting at all hits   \\[icicle-dispatch-C-^]
     Toggle whole-word searching             \\[icicle-dispatch-M-q]
     Toggle `.' matching newlines too        \\[icicle-toggle-dot]
     Toggle escaping of special regexp chars \\[icicle-toggle-regexp-quote]
     Toggle removal of search highlighting   \\[icicle-dispatch-C-.]

     Replace all                             M-|
     Redefine the replacement string         \\[icicle-dispatch-M-comma]
     Toggle literal replacement              \\[icicle-toggle-literal-replacement]
     Toggle replacement of whole search hit  \\[icicle-dispatch-M-_]
     Toggle replacement of common match      \\[icicle-toggle-search-replace-common-match]

 * Perform set operations on candidate sets.
     Remove candidate from current set       delete, S-mouse-2
     Add current candidate to saved set      insert, M-S-mouse-2
     Retrieve saved candidates from...
       `icicle-saved-completion-candidates'  \\[icicle-candidate-set-retrieve]
       another variable                      \\[icicle-candidate-set-retrieve-from-variable]
       a cache file                          \\[icicle-candidate-set-retrieve-persistent]
     Retrieve more saved candidates          \\[icicle-candidate-set-retrieve-more]
     Save candidates in current set to...
       `icicle-saved-completion-candidates'  \\[icicle-candidate-set-save]
       another variable                      \\[icicle-candidate-set-save-to-variable]
       a cache file                          \\[icicle-candidate-set-save-persistently]
     Save more candidates to current set     \\[icicle-candidate-set-save-more]
     Save, save more selected candidates     \\[icicle-candidate-set-save-selected], \
\\[icicle-candidate-set-save-more-selected]  with region
     Save multiple minibuffer inputs         \\[icicle-multi-inputs-save]
     Clear all saved candidates              \\[icicle-candidate-set-save-selected] \
with empty region
     Add new or update existing saved set
       \\[icicle-add/update-saved-completion-set]
     Remove a saved completion set
       \\[icicle-remove-saved-completion-set]
     Swap current and saved sets             \\[icicle-candidate-set-swap]
     Define current set by evaluating sexp   \\[icicle-candidate-set-define]
     Restrict candidates to history items    \\[icicle-keep-only-past-inputs]
     Set complement                          \\[icicle-candidate-set-complement]
     Set difference                          \\[icicle-candidate-set-difference]
     Set union                               \\[icicle-candidate-set-union]
     Set intersection                        \\[icicle-candidate-set-intersection]
     Set intersection using regexp           \\[icicle-narrow-candidates]
     Set intersection using predicate        \\[icicle-narrow-candidates-with-predicate]
       Save current predicate to a variable  \\[icicle-save-predicate-to-variable]
       Insert string variable as input       \\[icicle-insert-string-from-variable]

 * Adjust Icicles options incrementally on the fly (uses Do Re Mi).
     `icicle-candidate-width-factor'        \\[icicle-doremi-candidate-width-factor+]
     `icicle-max-candidates'                \\[icicle-doremi-increment-max-candidates+]
     `icicle-swank-timeout'                 C-x 1
     `icicle-swank-prefix-length'           C-x 2
     `icicle-inter-candidates-min-spaces'   \\[icicle-doremi-inter-candidates-min-spaces+]
     Zoom `*Completions*' (not an option)   C-x -   (Emacs 23+)

Remember: You can always input any character (e.g. \\[icicle-prefix-complete]) that is bound
          to a command by preceding it with \\<global-map>\\[quoted-insert].

Though it has no direct connection with completion, you can use \
`\\<minibuffer-local-completion-map>\\[icicle-pp-eval-expression-in-minibuffer]'
in the minibuffer at any time to evaluate an Emacs-Lisp expression.
This calls `icicle-pp-eval-expression-in-minibuffer', which displays
the result in the echo area or a popup buffer, *Pp Eval Output*.
It also provides some of the Emacs-Lisp key bindings during expression
editing."
             (if icicle-buffer-ignore-space-prefix-flag 'yes 'no)
             (if icicle-use-C-for-actions-flag 'yes 'no)
             (if icicle-use-~-for-home-dir-flag 'yes 'no)
             (if icicle-search-highlight-all-current-flag 'yes 'no)
             (if icicle-search-whole-word-flag 'yes 'no)
             (if icicle-search-cleanup-flag 'yes 'no)
             (if icicle-search-replace-whole-candidate-flag 'yes 'no)
             (if icicle-search-replace-common-match-flag 'yes 'no)
             (if icicle-search-complement-domain-p 'yes 'no))
     icicle-general-help-string
     "

These are all of the minibuffer bindings during completion:

\\{minibuffer-local-completion-map}"))))

(defun icicle-help-string-non-completion ()
  "Description of Icicles minibuffer bindings when not completing input."
  (icicle-S-iso-lefttab-to-S-TAB
   (substitute-command-keys
    (concat "\\<minibuffer-local-completion-map>\
              Icicles Minibuffer Input when Not Completing
              --------------------------------------------

These are the main Icicles minibuffer key bindings when completion is
not available:

 * Show this help.                           \\[icicle-minibuffer-help]

 * Abandon your input.                       \\[icicle-abort-recursive-edit]

 * Commit your input to Emacs.               RET

 * Modify your input.
     Edit your input                         (just edit in minibuffer)
     Erase your input (clear minibuffer)     \\[icicle-erase-minibuffer-or-history-element]
     Yank text at cursor into minibuffer     \\[icicle-insert-string-at-point]
     Insert text (string) from a variable    \\[icicle-insert-string-from-variable]
     Insert previously entered input(s)      \\[icicle-insert-history-element]
     Insert completion candidates(s)         \\[icicle-roundup]

 * Act on multiple minibuffer inputs         \\[icicle-multi-inputs-act]

 * Save multiple inputs for later completion \\[icicle-multi-inputs-save]

 * Choose a previous input from the minibuffer history.
     Complete to insert a previous input     \\[icicle-insert-history-element]
     Cycle among minibuffer history items    \\[next-history-element], \
\\[previous-history-element]

 * Delete history entries
     Delete current entry (cycling)          \\[icicle-erase-minibuffer-or-history-element]
     Delete any or all entries               \\[icicle-clear-current-history]

 * Evaluate an Emacs-Lisp sexp on the fly    \\[icicle-pp-eval-expression-in-minibuffer]

Remember: You can always input any character that is bound to a
          command by preceding it with \\<global-map>\\[quoted-insert]."
            icicle-general-help-string

            "
These are the minibuffer bindings when not completing input:

\\{minibuffer-local-map}"))))

(when (and (> emacs-major-version 21)
           (require 'help-mode nil t)
           (get 'help-xref 'button-category-symbol)) ; In `button.el'
  (define-button-type 'icicle-help-button
      :supertype 'help-xref
      'help-function (lambda () (browse-url "http://www.emacswiki.org/cgi-bin/wiki/Icicles"))
      'help-echo
      (purecopy "mouse-2, RET: Icicles documentation on the Emacs Wiki (requires Internet access)"))
  (define-button-type 'icicle-commentary1-button
      :supertype 'help-xref
      'help-function (lambda ()
                       (finder-commentary "icicles-doc1")
                       (when (require 'linkd nil t) (linkd-mode 1))
                       (when (require 'fit-frame nil t) (fit-frame)))
      'help-echo (purecopy "mouse-2, RET: Icicles documentation, Part 1 (no Internet needed)"))
  (define-button-type 'icicle-commentary2-button
      :supertype 'help-xref
      'help-function (lambda ()
                       (finder-commentary "icicles-doc2")
                       (when (require 'linkd nil t) (linkd-mode 1))
                       (when (require 'fit-frame nil t) (fit-frame)))
      'help-echo (purecopy "mouse-2, RET: Icicles documentation, Part 2 (no Internet needed)"))
  (define-button-type 'icicle-customize-button
      :supertype 'help-xref
      'help-function (lambda () (customize-group-other-window 'Icicles))
      'help-echo (purecopy "mouse-2, RET: Customize/Browse Icicles Options & Faces")))


;; This is just the macro expansion of the following:
;; `(def-completion-wrapper icicle-abort-recursive-edit :minibuffer-separator)'.
;; Taken from the definition of `def-completion-wrapper' in `completion.el'.
(put 'icicle-abort-recursive-edit 'completion-function 'use-completion-minibuffer-separator)

(defun icicle-abort-recursive-edit ()   ; Bound to `C-]',`C-g' in minibuf, `C-g',`q' in `*Completions*'.
  "Abort recursive edit or minibuffer input, or just deactivate region.
If called from the minibuffer, the region is active there, and
`delete-selection-mode' is turned on, then just deactivate the region.

Otherwise, call `abort-recursive-edit' after killing buffer
`*Completions*' or (if called from the minibuffer) after removing its
window.

By default, Icicle mode remaps all key sequences that are normally
bound to `abort-recursive-edit' to `icicle-abort-recursive-edit'.  If
you do not want this remapping, then customize option
`icicle-top-level-key-bindings'."
  (interactive)
  (if (and mark-active  (boundp 'delete-selection-mode)  delete-selection-mode
           (eq (selected-window) (minibuffer-window))  (active-minibuffer-window))
      (deactivate-mark)
    (if (not (active-minibuffer-window))
        (when (get-buffer "*Completions*") (kill-buffer (get-buffer "*Completions*")))
      (when (and (boundp '1on1-fit-minibuffer-frame-flag) ; In `oneonone.el'.
                 1on1-fit-minibuffer-frame-flag  (require 'fit-frame nil t))
        (1on1-fit-minibuffer-frame 'RESET))
      (icicle-remove-Completions-window 'FORCE))
    (abort-recursive-edit)))

(unless (fboundp 'save&set-overriding-map) ; Only Emacs 20-23 use `ensure-overriding-map-is-bound'.
  (defun icicle-ensure-overriding-map-is-bound ()
    "Set `overriding-terminal-local-map' to `icicle-universal-argument-map'."
    (if (not (boundp 'overriding-map-is-bound)) ; Emacs 20, 21.
        (setq overriding-terminal-local-map  icicle-universal-argument-map)
      (unless overriding-map-is-bound   ; Emacs 22+.
        (setq saved-overriding-map           overriding-terminal-local-map
              overriding-terminal-local-map  icicle-universal-argument-map
              overriding-map-is-bound        t)))))

(defun icicle-digit-argument (arg)      ; Bound to `C-<0-9>', `M-<0-9>', `C-M-<0-9>' in minibuffer.
  "`digit-argument', but also echo the prefix."
  (interactive "P")
  (let* ((char   (if (integerp last-command-event)
                     last-command-event
                   (icicle-get-safe last-command-event 'ascii-character)))
         (digit  (- (logand char ?\177) ?0)))
    (setq prefix-arg  (cond ((integerp arg)  (+ (* arg 10) (if (< arg 0) (- digit) digit)))
                            ;; Treat -0 as just -, so that -01 will work.
                            ((eq arg '-)     (if (zerop digit) '- (- digit)))
                            (t               digit))))
  (if (fboundp 'universal-argument--mode)
      (icicle-universal-argument--mode)
    (setq universal-argument-num-events  (length (this-command-keys)))
    (if (fboundp 'save&set-overriding-map) ; Emacs 24.1 to 24.3.
        (save&set-overriding-map icicle-universal-argument-map)
      (icicle-ensure-overriding-map-is-bound)))
  (icicle-msg-maybe-in-minibuffer "prefix %S" prefix-arg))

(defun icicle-negative-argument (arg)   ; Bound to `M--', `C-M--' in minibuffer.
  "`negative-argument', but also echo the prefix."
  (interactive "P")
  (setq prefix-arg  (cond ((integerp arg) (- arg))
                          ((eq arg '-)    nil)
                          (t              '-)))
  (if (fboundp 'universal-argument--mode)
      (icicle-universal-argument--mode)
    (setq universal-argument-num-events  (length (this-command-keys)))
    (if (fboundp 'save&set-overriding-map) ; Emacs 24.1 to 24.3.
        (save&set-overriding-map icicle-universal-argument-map)
      (icicle-ensure-overriding-map-is-bound)))
  (icicle-msg-maybe-in-minibuffer "prefix %S" prefix-arg))

(when (fboundp 'universal-argument--mode) ; Emacs 24.4+.
  (defun icicle-universal-argument--mode ()
    "Like `universal-argument--mode', but use `icicle-universal-argument-map'."
    (let ((fun  (if (fboundp 'set-transient-map) ; Make it work also for Emacs 24.3.50 snapshots
                    #'set-transient-map ;          prior to the renaming of `set-temporary-overlay-map'.
                  #'set-temporary-overlay-map)))
      (funcall fun icicle-universal-argument-map))))

(defun icicle-universal-argument ()     ; Bound to `C-u' in minibuffer.
  "`universal-argument', but also echo the prefix."
  (interactive)
  (cond ((fboundp 'universal-argument--mode) ; Emacs 24.4+.
         (setq prefix-arg  (list 4))
         (icicle-universal-argument--mode))
        (t
         (setq prefix-arg                     (list 4)
               universal-argument-num-events  (length (this-command-keys)))
         (if (fboundp 'save&set-overriding-map)
             (save&set-overriding-map icicle-universal-argument-map) ; Emacs 24.1 to 24.3.
           (icicle-ensure-overriding-map-is-bound)))) ; Emacs < 24.1.
  (icicle-msg-maybe-in-minibuffer "prefix %S" prefix-arg))

(defun icicle-universal-argument-more (arg)
  "`universal-argument-more', but also echo the prefix."
  (interactive "P")
  (universal-argument-more arg)
  (icicle-msg-maybe-in-minibuffer "prefix %S" prefix-arg))

(when (fboundp 'universal-argument-other-key) ; Emacs < 24.4.
  (defun icicle-universal-argument-other-key (arg)
    "`universal-argument-other-key', but also echo the prefix."
    (interactive "P")
    (universal-argument-other-key arg)
    (icicle-msg-maybe-in-minibuffer "prefix %S" prefix-arg)))

(unless (fboundp 'universal-argument--mode)
  (defun icicle-universal-argument-minus (arg) ; Emacs < 24.4.
    "`universal-argument-minus', but also echo the prefix."
    (interactive "P")
    (universal-argument-minus arg)
    (icicle-msg-maybe-in-minibuffer "prefix %S" prefix-arg)))


;; REPLACE ORIGINAL `sit-for' in `subr.el',
;; saving it for restoration when you toggle `icicle-mode'.
;;
;; 1. Ensure that `sit-for' after `C-u' in the minibuffer is immediately interrupted by user input.
;;    This fix is not needed for Emacs < 23.
;;
;; 2. Bind `inhibit-quit' to t, so `C-g' is handled after `sit-for', by `icicle-abort-recursive-edit'.
;;
(unless (fboundp 'icicle-ORIG-sit-for)
  (defalias 'icicle-ORIG-sit-for (symbol-function 'sit-for)))

(when (> emacs-major-version 22)
  (defun icicle-sit-for (seconds &optional nodisp obsolete)
    "Perform redisplay, then wait for SECONDS seconds or until input is available.
SECONDS may be a floating-point value.
\(On operating systems that do not support waiting for fractions of a
second, floating-point values are rounded down to the nearest integer.)

If optional arg NODISP is t, don't redisplay, just wait for input.
Redisplay does not happen if input is available before it starts.

Value is t if waited the full time with no input arriving, and nil otherwise.

An obsolete, but still supported form is
\(sit-for SECONDS &optional MILLISECONDS NODISP)
where the optional arg MILLISECONDS specifies an additional wait period,
in milliseconds; this was useful when Emacs was built without
floating point support."
    (if (numberp nodisp)
        (setq seconds  (+ seconds (* 1e-3 nodisp))
              nodisp   obsolete)
      (when obsolete (setq nodisp  obsolete)))
    (cond (noninteractive
           (sleep-for seconds)
           t)
          ((input-pending-p)
           nil)
          ((<= seconds 0)
           (or nodisp  (redisplay)))
          (t
           (or nodisp  (redisplay))
           (let* ((inhibit-quit  t)
                  (read          (read-event nil nil seconds)))
             (or (null read)
                 (progn
                   ;; If last command was a prefix arg, e.g. C-u, push this event onto
                   ;; `unread-command-events' as (t . EVENT) so it will be added to
                   ;; `this-command-keys' by `read-key-sequence'.
                   (when (memq overriding-terminal-local-map
                               (list universal-argument-map icicle-universal-argument-map))
                     (setq read  (cons t read)))
                   (push read unread-command-events)
                   nil)))))))

(defun icicle-retrieve-next-input (&optional arg) ; Bound to `C-S-l' (`C-L') in minibuffer.
  "Retrieve next minibuffer input.
Like `icicle-retrieve-previous-input', but traverses history toward
the present.

You can use this command only from the minibuffer (`\\<minibuffer-local-completion-map>\
\\[icicle-retrieve-next-input]')."
  (interactive "P")
  (icicle-retrieve-previous-input arg 'interactive-p)) ; Must be `interactive-p'.

(defun icicle-retrieve-previous-input (&optional arg reversep allow-empty-p) ; `C-l' in minibuffer.
  "Retrieve previous minibuffer input.
The possible inputs were not necessarily those entered with `RET'.
With a negative prefix arg, this just empties the completion history.
Otherwise:
 Use completion if `icicle-C-l-uses-completion-flag' is non-nil and no
   prefix arg is used, or if it is nil and a prefix arg is used, or if
   `icicle-retrieve-previous-input' is not used interactively.
 Otherwise, just cycle to the previous input.

Non-interactively:
 Non-nil argument REVERSEP means reverse the history order: return the
  next, not the previous, input.
 Non-nil ALLOW-EMPTY-P means the retrieved input can be \"\".

You can use this command only from buffer *Completions or from the
minibuffer (`\\<minibuffer-local-completion-map>\
\\[icicle-retrieve-previous-input]')."
  (interactive "P")
  (let ((interactive-p       (or (interactive-p)  (eq reversep 'interactive-p)))
        (prev-inputs-var     (if (icicle-file-name-input-p)
                                 'icicle-previous-raw-file-name-inputs
                               'icicle-previous-raw-non-file-name-inputs))
        ;; `irpi-was-cycling-p' is used to remember, for the second `C-l' in a row, that the first
        ;; `C-l' came after cycling.  In that case, the second `C-l' restores the current raw input.
        (irpi-was-cycling-p  icicle-cycling-p))
    (when interactive-p (icicle-barf-if-outside-Completions-and-minibuffer))
    (cond ((wholenump (prefix-numeric-value arg))
           (let ((input  ""))
             (save-selected-window
               (select-window (minibuffer-window))
               (icicle-clear-minibuffer)
               (let ((prev-inputs
                      (if allow-empty-p
                          (symbol-value prev-inputs-var)
                        (icicle-remove-if (lambda (x) (string= "" x)) ; Exclude "".
                                          (symbol-value prev-inputs-var)))))
                 (setq input
                       (if (and interactive-p  (or (and icicle-C-l-uses-completion-flag        (not arg))
                                                   (and (not icicle-C-l-uses-completion-flag)  arg)))
                           (let ((icicle-whole-candidate-as-text-prop-p   nil)
                                 (enable-recursive-minibuffers            t)
                                 (icicle-show-Completions-initially-flag  t))
                             (prog1 (completing-read
                                     "Retrieve input: " (mapcar #'list prev-inputs) nil t)
                               (setq icicle-last-input  nil)))
                         (if (or (not interactive-p)
                                 (not (memq last-command '(icicle-retrieve-next-input
                                                           icicle-retrieve-previous-input))))
                             ;; We use this one, to exclude common-match expansions from completion
                             ;; history, and to save the typed input only when you complete.
                             (let ((try  (if icicle-cycling-p
                                             icicle-last-input
                                           icicle-current-raw-input)))
                               (if (or allow-empty-p  (not (equal "" try))) try (car prev-inputs)))

                           ;; You can use this one instead, if you want to include common-match
                           ;; expansions and save the typed input even when you don't complete.
                           ;; (or icicle-last-input  icicle-current-raw-input)

                           (let ((next  (member icicle-current-raw-input prev-inputs)))
                             (unless next (setq next  prev-inputs))
                             (if reversep
                                 (or (let ((res     ())
                                           (inputs  prev-inputs))
                                       (while (and (consp inputs)  (not (eq inputs next)))
                                         (push (pop inputs) res))
                                       (car res))
                                     (car (last prev-inputs)))
                               ;; If we were cycling before the first `C-l', then need to pick up the
                               ;; current raw input.  Otherwise, we need to pick up the previous one.
                               (prog1 (if irpi-was-cycling-p (car next) (cadr next))
                                 (setq irpi-was-cycling-p  nil))))))) ; So third `C-l' acts normally.

                 ;; $$$$ (when input (icicle-call-then-update-Completions #'insert input))))
                 ;; $$$$$$ (when input (insert input))))

;;; $$$$$$ REPLACED by previous line only.
                 (when input
                   (setq icicle-current-raw-input  input)
                   (insert input)
                   (icicle-highlight-initial-whitespace input) ; (e.g. user typo).
                   (icicle-place-cursor input 'deactivate-mark))))

;;;              (let ((icicle-edit-update-p  t))
;;;                (funcall (or icicle-last-completion-command  'icicle-apropos-complete))
;;;                ;; Restore raw input.  Cycling resets it to "", so `icicle-save-or-restore-input'
;;;                ;; doesn't use out-of-date raw input (cycling does not necessarily follow completion
;;;                ;; or completion of the same kind).
;;;                (setq icicle-current-raw-input  input))

             (setq icicle-current-raw-input  input ; So we can keep cycling.
                   icicle-last-input         nil ; So `TAB' expands it - `icicle-save-or-restore-input'.
                   icicle-cycling-p          irpi-was-cycling-p))) ; Let next `C-l' know the state.
          (t
           (set prev-inputs-var nil)
           (setq icicle-current-raw-input  "")
           (icicle-msg-maybe-in-minibuffer "Cleared completion history")))))

;; $$ No longer bound.  Now we bind `icicle-retrieve-previous-input', instead, to `C-l'.
;;
(defun icicle-retrieve-last-input ()
  "Put the last real input into the minibuffer.
Use this to replace a completion candidate inserted during cycling or
because of input expansion due to the value of option
`icicle-expand-input-to-common-match'.

If you are cycling and expansion is also in effect, then use this
twice in succession: once to restore the expanded common match string,
and a second time to restore your unexpanded original input.

You can use this command only from buffer `*Completions' or from the
minibuffer."
  (interactive)
  (when (interactive-p) (icicle-barf-if-outside-Completions-and-minibuffer))
  (save-selected-window
    (select-window (minibuffer-window))
    (icicle-clear-minibuffer)
    (if (and (eq last-command 'icicle-retrieve-last-input)
             (or (and (eq icicle-current-completion-mode 'apropos)
                      (eq icicle-expand-input-to-common-match 4))
                 (and (eq icicle-current-completion-mode 'prefix)
                      (memq icicle-expand-input-to-common-match '(3 4)))))
        (insert icicle-current-raw-input)
      (insert icicle-current-input))
    ;;$$$ (when (interactive-p) (setq icicle-last-completion-command  nil))
    (let ((input  (if (and (eq last-command this-command)
                           (or (and (eq icicle-current-completion-mode 'apropos)
                                    (eq icicle-expand-input-to-common-match 4))
                               (and (eq icicle-current-completion-mode 'prefix)
                                    (memq icicle-expand-input-to-common-match '(3 4)))))
                      icicle-current-raw-input
                    icicle-current-input)))
      (icicle-highlight-initial-whitespace input) ; Highlight initial whitespace (e.g. user typo).
      (icicle-place-cursor input 'deactivate-mark))))

;; $$ No longer used.  It was originally used in `icicle-retrieve-last-input'.
(defun icicle-insert-input (input)
  "Insert INPUT.  Prepend the directory if appropriate."
  (insert (if (and (icicle-file-name-input-p)
                   insert-default-directory
                   (or (not (member input icicle-extra-candidates))
                       icicle-extra-candidates-dir-insert-p))
              (icicle-expand-file-or-dir-name input (icicle-file-name-directory input))
            input)))

(icicle-define-command icicle-insert-history-element ; Bound to `M-o' in minibuffer.
  "Use completion to insert previously entered inputs in the minibuffer.
Insert a space character after each (but see below, to prevent this).
Always available for any minibuffer input, not just during completion.
With a non-negative prefix arg, wrap candidate to insert with \"...\".
With a non-positive prefix arg, do not append a space char.

If you use a prefix argument also for an individual candidate
insertion action then that overrides any prefix argument or lack
thereof that you used for this command.  For example, with no prefix
argument, \\<minibuffer-local-map>`\\[icicle-insert-history-element]' \
does not wrap candidates with \"...\", but if you use,
e.g., `C-u C-RET' then that candidate is so wrapped."
  icicle-insert-candidate-action        ; Action function
  "Choose past input (`C-g' to end): "  ; `completing-read' args
  (mapcar #'list hist-val) nil nil nil nil nil nil
  ((enable-recursive-minibuffers  t)    ; Bindings
   (hist-val                      (and (boundp minibuffer-history-variable)
                                       (consp (symbol-value minibuffer-history-variable))
                                       (symbol-value minibuffer-history-variable)))
   (hist-val                      (and hist-val  (icicle-remove-duplicates hist-val)))
   (icicle-pref-arg               (and current-prefix-arg  (prefix-numeric-value current-prefix-arg)))
   (count                         0)
   (to-insert                     ()))
  (progn                                ; First code
    (when (interactive-p) (icicle-barf-if-outside-minibuffer))
    (when (and (consp hist-val)  (not (stringp (car hist-val)))) ; Convert, e.g. `comand-history'.
      (setq hist-val  (mapcar #'prin1-to-string hist-val)))
    ;; $$$$$$ (icicle-clear-minibuffer)
    )
  nil                                   ; Undo code
  (progn                                ; Last code
    (apply #'insert (nreverse to-insert))
    (when (and icicle-mode  (memq icicle-default-value '(preselect-start preselect-end)))
      (icicle-select-minibuffer-contents)
      (setq deactivate-mark  nil))))

(icicle-define-command icicle-roundup   ; Bound to `M-r' in minibuffer.
  "Insert one or more completion candidates in the minibuffer.
Insert a space character after each (but see below, to prevent this).
With a non-negative prefix arg, wrap candidate to insert with \"...\".
With a non-positive prefix arg, do not append a space char.

If you use a prefix argument also for an individual candidate
insertion action then that overrides any prefix argument or lack
thereof that you used for this command.  For example, with no prefix
argument, \\<minibuffer-local-map>`\\[icicle-roundup]' \
does not wrap candidates with \"...\", but if you use,
e.g., `C-u C-RET' then that candidate is so wrapped."
  icicle-insert-candidate-action        ; Action function
  "Roundup - choose (`C-g' to end): "   ; `completing-read' args
  (and icicle-completion-candidates  (mapcar #'list icicle-completion-candidates))
  nil nil nil nil nil nil
  ((enable-recursive-minibuffers  t)    ; Bindings
   (icicle-pref-arg               (and current-prefix-arg  (prefix-numeric-value current-prefix-arg)))
   (count                         0)
   (to-insert                     ()))
  (progn                                ; First code
    (when (interactive-p) (icicle-barf-if-outside-minibuffer))
    (unless icicle-completion-candidates
      (icicle-user-error "No completion candidates - did you hit `TAB' or `S-TAB'?"))
    (icicle-clear-minibuffer))
  nil                                   ; Undo code
  (progn                                ; Last code
    (apply #'insert (nreverse to-insert))
    (when (and icicle-mode  (memq icicle-default-value '(preselect-start preselect-end)))
      (icicle-select-minibuffer-contents)
      (setq deactivate-mark  nil))))

(defun icicle-insert-candidate-action (cand)
  "Action function for `icicle-insert-history-element' and `icicle-roundup'."
  ;; FREE here: TO-INSERT, COUNT.
  (unless (equal cand "")
    (let ((prefix-arg  (if current-prefix-arg (prefix-numeric-value current-prefix-arg) icicle-pref-arg)))
      (push (if (and prefix-arg  (natnump prefix-arg)) (format "\"%s\"" cand) cand) to-insert)
      (unless (and prefix-arg  (<= prefix-arg 0)) (push " " to-insert))
      (message "Inserted: %s%s"
               (icicle-propertize (format "%d" (setq count  (1+ count))) 'face 'icicle-msg-emphasis)
               (if (not prefix-arg)
                   ""
                 (format "  [%s]" (concat (and (natnump prefix-arg) "\"...\"-wrapped")
                                          (and (zerop prefix-arg)   " and ")
                                          (and (<= prefix-arg 0)    "NOT `SPC'-separated"))))))))

(defun icicle-insert-string-at-point (&optional arg) ; Bound to `M-.' in minibuffer.
  "Insert text at the cursor into the minibuffer.
Each time this command is called, some text at or near the cursor is
inserted into the minibuffer.  One of two things happens, depending on
the value of option `icicle-default-thing-insertion' and whether or
not you use `C-u'.

See the doc for option `icicle-thing-at-point-functions' for a
complete description of its behavior.  What follows is an overview.

`icicle-thing-at-point-functions' is a cons of two parts - call them
ALTERNATIVES and FORWARD-THING.

If ALTERNATIVES is not nil and one of the following is true:
 - FORWARD-THING is nil
 - the value of `icicle-default-thing-insertion' is `alternatives' and
   you have not used plain `C-u' in this series of `M-.'
 - the value of `icicle-default-thing-insertion' is `more-of-the-same'
   and you have used plain `C-u' in this series of `M-.'
then the next function in ALTERNATIVES is used to retrieve the text to
be inserted.

If FORWARD-THING is not nil and one of the following is true:
 - ALTERNATIVES is nil
 - the value of `icicle-default-thing-insertion' is `more-of-the-same'
   and you have not used `C-u' in this series of `M-.'
 - the value of `icicle-default-thing-insertion' is `alternatives' and
   you have used `C-u' in this series of `M-.'
then function FORWARD-THING is used to retrieve the text to be
inserted.

If you use a numeric prefix arg (not just plain `C-u'), the behavior
is as follows.

* If a function in ALTERNATIVES is used (see above), then the text
  that is grabbed at or near point is read as a Lisp sexp and
  evaluated, and the value is inserted instead of the grabbed text.

  Yes, this means you need to know when the particular ALTERNATIVES
  function that you want is coming up next, and use, say, `C-9' just
  before hitting `M-.' for that alternative.  So if, e.g., you want to
  evaluate the active region and insert the value, then you use
  `M-. C-9 M-.', since it is the second `M-.' that grabs the region.

* If the FORWARD-THING is being used, then the prefix arg determines
  the number of things to grab, and the direction of grabbing.: A
  negative argument grabs text to the left of the cursor; a positive
  argument grabs text to the right.

You can use this command only from the minibuffer (`\\<minibuffer-local-completion-map>\
\\[icicle-insert-string-at-point]')."
  (interactive "P")
  (when (interactive-p) (icicle-barf-if-outside-minibuffer))
  (when (consp icicle-thing-at-point-functions) ; Option should always be a cons cell.
    (unless (eq last-command this-command) (setq icicle-default-thing-insertion-flipped-p  nil))
    (let ((alt-fns       (car icicle-thing-at-point-functions))
          (fwd-thing-fn  (cdr icicle-thing-at-point-functions))
          (flipped       (or icicle-default-thing-insertion-flipped-p ; Already flipped.
                             (setq icicle-default-thing-insertion-flipped-p  (consp arg)))))
      (cond
        ;; Use alternative text-grabbing functions successively.
        ((and alt-fns  (or (if (eq 'alternatives icicle-default-thing-insertion)
                               (not flipped) ; Normal behavior for `alternatives'.
                             flipped)    ; Flipped behavior for `more-of-the-same'.
                           (not fwd-thing-fn))) ; No alternative.
         (setq icicle-successive-grab-count  1 ; In this mode, reset other mode's accumulator.
               icicle-thing-at-pt-fns-pointer
               (if (eq last-command this-command) ; If repeated, get next text-grabbing function.
                   (mod (1+ icicle-thing-at-pt-fns-pointer) (length alt-fns))
                 0))
         (let ((thing   "")
               (alt-fn  (nth icicle-thing-at-pt-fns-pointer alt-fns)))
           (save-excursion (with-current-buffer icicle-pre-minibuffer-buffer
                             (setq thing  (funcall alt-fn))))
           (setq thing  (or thing  "nil"))
           (when (and arg  (atom arg))   ; Numeric prefix arg.
             (setq thing  (condition-case err
                              (format "%s" (eval (car (read-from-string thing))))
                            (error thing))))
           (icicle-insert-thing thing)
           (icicle-msg-maybe-in-minibuffer (format "`%s'" alt-fn))))

        ;; Use same text-grabbing function successively.
        ((and fwd-thing-fn  (or (if (eq 'alternatives icicle-default-thing-insertion)
                                    flipped ; Flipped behavior for `alternatives'.
                                  (not flipped)) ; Normal behavior for `more-of-the-same'.
                                (not alt-fns))) ; No alternative.
         (if (and arg  (atom arg))

             ;; Explicit numeric arg.  If it doesn't change direction, then increment
             ;; existing count.  Otherwise, set count absolutely.
             (if (eq last-command this-command)
                 (if (= (icicle-signum icicle-successive-grab-count) ; Repeated `M-.'.
                        (icicle-signum (prefix-numeric-value arg)))
                     (setq icicle-successive-grab-count ; Same direction - increment count.
                           (* (icicle-signum icicle-successive-grab-count)
                              (+ (abs icicle-successive-grab-count)
                                 (abs (prefix-numeric-value arg)))))
                   (setq icicle-successive-grab-count  (prefix-numeric-value arg))) ; New dir - set.
               (setq icicle-successive-grab-count  (prefix-numeric-value arg))) ; First `M-.' - set.

           ;; No explicit numeric arg.
           ;; If first `M-.' or plain `C-u', set count. Otherwise, increment count.
           (if (eq last-command this-command)
               (setq icicle-successive-grab-count ; Repeated `M-.'.
                     (if (consp arg)
                         ;; We're here from plain `C-u' with `alternatives' - use 1, not 4.
                         (if (wholenump icicle-successive-grab-count) 1 -1)
                       (if (wholenump icicle-successive-grab-count) ; Increment count.
                           (+ icicle-successive-grab-count (abs (prefix-numeric-value arg)))
                         (- icicle-successive-grab-count (abs (prefix-numeric-value arg))))))
             (setq icicle-successive-grab-count  1))) ; First `M-.' - reset count.
         (let ((things  ""))
           (save-excursion
             (with-current-buffer (cadr (buffer-list))
               (setq things  (buffer-substring-no-properties
                              (point)
                              (save-excursion (funcall fwd-thing-fn icicle-successive-grab-count)
                                              (point))))))
           (icicle-insert-thing things)))))))

(defun icicle-signum (num)
  "Return 1 if NUM is positive, -1 if negative, 0 if zero."
  (cond ((< num 0) -1) ((> num 0) 1) (t 0)))

(defun icicle-insert-thing (text &optional no-replace-p)
  "Insert TEXT in the minibuffer.
TEXT replaces the last text that was inserted, if this command repeats
the last and NO-REPLACE-P is nil."
  (when (and (stringp text)  (not (string= "" text)))
    (remove-text-properties 0 (length text) '(face nil) text)
    (when (and (eq last-command this-command)
               (not no-replace-p)
               icicle-insert-string-at-pt-start) ; Ensure that we've defined the ends.
      (delete-region icicle-insert-string-at-pt-start icicle-insert-string-at-pt-end))
    (setq icicle-insert-string-at-pt-start  (point))
    (insert text)
    (setq icicle-insert-string-at-pt-end  (point))))

(defun icicle-insert-string-from-variable (askp) ; Bound to `C-=' in minibuffer.
  "Insert text into the minibuffer from a variable.
By default, the variable is user option `icicle-input-string'.  To
insert from a different variable, use a prefix argument.  You are then
prompted for the variable to use.  Completion candidates for this
include all string-valued variables.

You can use command `icicle-save-string-to-variable' to save a string
to a variable.  Typically, you store a regexp or part of a regexp in
the variable.  This command is bound in the minibuffer to `C-=', by
default.  This is especially useful when used with command
`icicle-search'.

Some regexps that you might want to assign to variables:

 \"[A-Za-z0-9_.-]+@[A-Za-z0-9_.-]+\"          ; Email address
 \"\\\\([0-9]+\\\.[0-9]+\\\.[0-9]+\\\.[0-9]+\\\\)\"     ; IP address
 \"[0-9]\\\\\\\={4\\\\}-[0-9]\\\\\\\={2\\\\}-[0-9]\\\\\\\={2\\\\}\"   ; Date: 2006-04-14, Time:
 \"^[ \\\=\\t]*[0-9]?[0-9]\\\\([:.]?[0-9][0-9]\\\\)?\\\\(am\\\\|pm\\\\|AM\\\\|PM\\\\)?\"
 \"`\\\\(\\\\sw\\\\sw+\\\\)'\"                        ; Words inside `_'
 \"\\\\*.*\\\\*\"                                 ; Special buffer name: *_*

Standard Emacs Lisp libraries are full of regexps that you can assign
to variables for use with `C-='.
 See `align.el' for regexps for programming languages.
 See `url-dav.el' for regexps matching iso8601 dates.
 See `rmail.el', `sendmail.el', and `mh-show.el' for regexps matching
 mail-header fields.

Imenu regexps occurring as parts of different values of
`imenu-generic-expression' for different buffer types can be used as
variable values for `C-='.  They all work fine with `icicle-search',
turning it into a browser or navigator for the given mode.

See, for example, `generic-x.el' and `lisp-mode.el'.  Here is a regexp
for Javascript function definitions from `generic-x.el':

 \"^function\\\\s-+\\\\([A-Za-z0-9_]+\\\\)\"

And `lisp-imenu-generic-expression' (in `lisp-mode.el') provides
regexps for Lisp function, variable, and type definitions.  Here is
the variable-definition regexp:

 \"^\\\\s-*(\\\\(def\\\\(c\\\\(onst\\\\(ant\\\\)?\\\\|ustom\\\\)\\\\|ine-symbol-macro\\\\|
 parameter\\\\|var\\\\)\\\\)\\\\s-+\\\\(\\\\(\\\\sw\\\\|\\\\s_\\\\)+\\\\)\"

Command `icicle-imenu' exploits this to automatically let you browse
definitions.  It is a specialization of `icicle-search' for Imenu.

For more useful regexps, grep for `font-lock-keywords' in Emacs `lisp'
directory and subdirs.

You can use this command only from the minibuffer (`\\<minibuffer-local-completion-map>\
\\[icicle-insert-string-from-variable]')."
  (interactive "P")
  (when (interactive-p) (icicle-barf-if-outside-Completions-and-minibuffer))
  (save-selected-window
    (select-window (minibuffer-window))
    (if askp
        (let* ((icicle-whole-candidate-as-text-prop-p   nil)
               ;; If we didn't use this here we'd at least have to bind it to
               ;; `orig-must-pass-after-match-predicate', because of `icicle-execute-extended-command'.
               (icicle-must-pass-after-match-predicate  (lambda (s)
                                                          (let ((sym  (intern-soft s)))
                                                            (and sym  (boundp (intern s))
                                                                 (condition-case nil
                                                                     (icicle-var-is-of-type-p
                                                                      sym '(string color regexp)
                                                                      'inherit-or-value)
                                                                   (error nil))))))
               (enable-recursive-minibuffers            t)
               (var
                (intern (completing-read "Insert text from variable: " obarray  nil  nil nil
                                         (if (boundp 'variable-name-history)
                                             'variable-name-history
                                           'icicle-variable-name-history))))
               ;; Make sure we use the buffer-local value of the variable, if there is one.
               (text
                (with-current-buffer (cadr (buffer-list)) (symbol-value var))))
          (icicle-insert-thing text 'no-replace))
      (icicle-insert-thing icicle-input-string 'no-replace))))

(defun icicle-insert-list-join-string () ; Bound to `C-M-j' in minibuffer during completion.
  "Insert `icicle-list-join-string' in the minibuffer.
Then, if `1on1-fit-minibuffer-frame-flag' is defined and non-nil, fit
a standalone minibuffer frame to the new minibuffer contents.
You need library `fit-frame.el' for the frame-fitting part."
  (interactive)
  (icicle-insert-thing icicle-list-join-string 'no-replace)
  (let ((len  (length icicle-list-join-string)))
    (when (and (string= "\C-j" (substring icicle-list-join-string (1- len) len))
               (boundp '1on1-fit-minibuffer-frame-flag) ; In `oneonone.el'.
               1on1-fit-minibuffer-frame-flag
               (require 'fit-frame nil t))
      (1on1-fit-minibuffer-frame))))

(defun icicle-dispatch-M-q (&optional arg) ; Bound to `M-q' in minibuffer.
  "Do the right thing for `M-q'.
If searching, call `icicle-toggle-search-whole-word'.
Otherwise, call `icicle-insert-key-description'.
Bound to `M-q' in the minibuffer."
  (interactive "P") ; Argument is ignored for `icicle-toggle-search-whole-word'.
  (cond (icicle-searching-p (icicle-toggle-search-whole-word))
        (t (icicle-insert-key-description arg))))

;; Top-level commands.  Could instead be in `icicles-cmd2.el'.
;;
(defalias 'toggle-icicle-search-whole-word 'icicle-toggle-search-whole-word)
(defun icicle-toggle-search-whole-word () ; Bound to `M-q' in minibuffer during Icicles search.
  "Toggle the value of `icicle-search-whole-word-flag'.
The new value takes effect for the next Icicles search command.
Bound to `M-q' in the minibuffer when searching."
  (interactive)
  (setq icicle-search-whole-word-flag  (not icicle-search-whole-word-flag))
  (icicle-msg-maybe-in-minibuffer
   "Whole-word searching is now %s, starting with next search"
   (icicle-propertize (if icicle-search-whole-word-flag "ON" "OFF") 'face 'icicle-msg-emphasis)))

(defun icicle-insert-key-description (toggle-angle-brackets-p) ; Bound to `M-q' in minibuffer.
  "Read key and insert its description.
For example, if the key read is ^F, then \"C-f\" is inserted.

For Emacs 21+, `icicle-key-descriptions-use-<>-flag' determines
whether angle brackets (`<', `>') are used for named