RE: Completion

[Drew Adams]

> 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'.