[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Sat, 1 Sep 2018 07:49:55 -0700 (PDT)
> 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'
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
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
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)
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
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