completing-read enhancement

[Paul Landes]

This isn't a patch to completing-read, instead it is a new function.  I think
of it more as a facade with bells and whistles.  In summary, it makes prompting
for user input easy requiring terse, in the context of a function invocation,
code for this purpose.

(defun read-completing-choice (prompt choices &optional return-as-string
                                      require-match initial-contents
                                      history default allow-empty-p
                                      no-initial-contents-on-singleton-p
                                      add-prompt-default-p)
  "Read from the user a choice.

See `completing-read'.

PROMPT is a string to prompt with; normally it ends in a colon and a space.

CHOICES the list of things to auto-complete and allow the user to choose
  from.  Each element is analyzed independently If each element is not a
  string, it is written with `prin1-to-string'.

RETURN-AS-STRING is non-nil, return the symbol as a string
  (i.e. `symbol-name).

If REQUIRE-MATCH is non-nil, the user is not allowed to exit unless
  the input is (or completes to) an element of TABLE or is null.
  If it is also not t, Return does not exit if it does non-null completion.

If INITIAL-CONTENTS is non-nil, insert it in the minibuffer initially.
  If it is (STRING . POSITION), the initial input
  is STRING, but point is placed POSITION characters into the string.

HISTORY, if non-nil, specifies a history list
  and optionally the initial position in the list.
  It can be a symbol, which is the history list variable to use,
  or it can be a cons cell (HISTVAR . HISTPOS).
  In that case, HISTVAR is the history list variable to use,
  and HISTPOS is the initial position (the position in the list
  which INITIAL-CONTENTS corresponds to).
  If HISTORY is `t', no history will be recorded.
  Positions are counted starting from 1 at the beginning of the list.

DEFAULT, if non-nil, will be returned when the user enters an empty
  string.

ALLOW-EMPTY-P, if non-nil, allow no data (empty string) to be returned.  In
  this case, nil is returned, otherwise, an error is raised.

NO-INITIAL-CONTENTS-ON-SINGLETON-P, if non-nil, don't populate with initialial
  contents when there is only one choice to pick from.

ADD-PROMPT-DEFAULT-P, if non-nil, munge the prompt using the default notation
  \(i.e. `<Prompt> (default CHOICE)')."
  (let* ((choice-alist-p (listp (car choices)))
         (choice-options (if choice-alist-p (mapcar #'car choices) choices))
         (sym-list (mapcar #'(lambda (arg)
                               (list
                                (typecase arg
                                  (string arg)
                                  (t (prin1-to-string arg))
                                  )))
                           choice-options))
         (initial (if initial-contents
                      (if (symbolp initial-contents)
                          (symbol-name initial-contents)
                        initial-contents)))
         (def (if default
                  (typecase default
                    (nil nil)
                    (symbol default (symbol-name default))
                    (string default)
                    )))
         res-str)
    (when (not no-initial-contents-on-singleton-p)
      (if (and (null initial) (= 1 (length sym-list)))
          (setq initial (car (car sym-list))))
      (let (tc)
        (if (and (null initial)
                 ;; cases where a default is given and the user can't then just
                 ;; press return; instead, the user has to clear the minibuffer
                 ;; contents first
                 (null def)
                 (setq tc (try-completion "" sym-list)))
            (setq initial tc))))
    (if (and add-prompt-default-p def)
        (setq prompt
              (concat prompt (format " (default %s): " def))))
    (block wh
      (while t
        (setq res-str (completing-read prompt sym-list nil
                                       require-match initial
                                       history def))
        (if (or allow-empty-p (> (length res-str) 0))
            (return-from wh)
          (ding)
          (message (substitute-command-keys
                    "Input required or type `\\[keyboard-quit]' to quit"))
          (sit-for 5))))
    (when (> (length res-str) 0)
      (if choice-alist-p
          (let ((choices (if (symbolp (caar choices))
                             (mapcar #'(lambda (arg)
                                         (cons (symbol-name (car arg))
                                               (cdr arg)))
                                     choices)
                           choices)))
            (setq res-str (cdr (assoc res-str choices))))
        (setq res-str
              (if return-as-string
                  res-str
                (intern res-str)))))
    res-str))