RE: Completion

[Drew Adams <drew.adams@oracle.com>]

> I've been looking at the completion functions and documentation for
> pretty much the first time in my life this morning, and I've got some
> questions.  :-/

Replying quickly to some of them -

> 2) The entire `completing-read' machinery is based on prefix, matches
> and nothing else; is that right?  

No. See variable `completion-styles'. Literal prefix completion is the `basic' completion style.

In vanilla Emacs there is only one set of completion styles that is ever in effect, defined by option `completion-styles'.  It is a list of different ways to match your input.  Each style in the list is tried, in turn, until one of them successfully completes your input.

All completion candidates you see come from the same style.  You have no control over which style will actually be used for any given input, other than ordering the list ahead of time. And you have no way of knowing which style was actually used to produce a given set of candidates. The relation between your input pattern and the matches is thus sometimes not so clear. There is no way to know, for example, that initial matching failed and partial matching succeeded.

That is, in vanilla Emacs the styles of `completion-styles' can only be used together - all or none; they are never alternatives that you can choose at runtime.

Icicles respects vanilla Emacs `completion-styles' as one of several possible completion "methods" (the method called `vanilla'). Unlike completion styles, Icicles completion methods are alternatives - only one is used at a time to complete your input, and you can switch from one method to another easily.

For method `vanilla', which uses `completion-styles', Icicles gives you ways to change the current set of styles on the fly. Option `icicle-completion-style-sets' is a list of possible `completion-styles' values to choose from. You can flip among these during completion.

Among other things, this means that you can try completing using one style set and, if that doesn't succeed, switch to another.

Any of the sets in `icicle-completion-style-sets' can contain any number of styles, in any order.  In particular, a set can be a singleton, which means that you can selectively try to complete using different individual styles.

> 3) The completion selection machinery in simple.el is nice, but it would
> be nice to be able to pass more information about the strings into it
> and get it all back after the user has chosen something.  The obvious
> thing is to put a text property on the strings, and that almost, almost
> works, except for this:
> 
> (defun choose-completion (&optional event) ...
>    (buffer-substring-no-properties beg end)))))
> 
> If that had been just `buffer-substring', then the information would
> survive back to the caller.

I proposed this for Emacs many years ago. It is what Icicles does. Option `icicle-unpropertize-completion-result-flag' controls this (nil by default).

   Non-nil means strip text properties from the completion result.
   Set or bind this option to non-nil only if you need to ensure, for
   some other library, that the string returned by `completing-read' and
   `read-file-name' has no text properties.

   Typically, you will not use a non-nil value.  Internal text properties
   added by Icicles are always removed anyway.  A non-nil value lets you
   also remove properties such as `face'.

And yes, with Icicles you often put the complete alist-entry (or other value), as a text property, on the string that is displayed as a candidate, and then you retrieve that full value. This can be done automatically.

    (defun icicle-put-whole-cand-prop (cand)
     "Put cdr of CAND on its car, as text property `icicle-whole-candidate'.
   This has no side effects.
   Returns a new propertized string corresponding to (car CAND)."
     (let ((text-cand  (copy-sequence (car cand))))
       (put-text-property 0 (length text-cand) 
                          'icicle-whole-candidate (cdr cand) text-cand)
       (setcar cand text-cand)
       text-cand))

It can also be useful sometimes to allow multiple full candidates that have the same display-candidate string (apart from the full-candidate text property). 

For example, command `icicle-search' uses completion to navigate among search hits.  Duplicate search hits are retained.  Although some search-hit candidates might have the same text, they are located at different buffer positions (and perhaps in different buffers). The position is available in the full-candidate info.

There are many other `completing-read' enhancements that Icicles uses, each of which I've proposed for Emacs in the past.

> `minibuffer-allow-text-properties' exists. 

Icicles binds it to t for `completing-read' (but not for `read-from-minibuffer'). Icicles uses `icicle-unpropertize-completion-result-flag' instead to control this for `completing-read'.