bug#33595: 26; Have `try-completion' or `completion--done' run abnormal hook if sole completion

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

> > Enhancement request: When `try-completion' returns `t' there is a
> > "unique match which is exact".  Please add an abnormal hook at this
> > point, which accepts that sole completion as argument.
> 
> I'm not sure exactly what's the intention behind this: would it be an
> option that influences the UI or the completion table?

Not sure what that dichotomy is, but it doesn't influence
the completion table at all.  It's about what gets done
with a completion, not how completion is done.

> More concretely, do you expect a hook function places on this variable
> to apply for "any completion table" or would it be specific to
> a particular completion table?

The former.  At least I don't see how this has anything to
do with what kind of completion is used or how it's done.

> The example you give in `my-describe-function` gives me the impression
> that those would inevitably be tightly linked to the completion table.
> So instead of a hook variable, it would probably make more sense to add
> a new `completion-extra-properties` alongside to :exit-function.

No, I don't think that's relevant.

> Do you have other example applications than `my-describe-function` (to
> be honest, I found this example not very compelling).
> 
> > no exit function.  `try-completion' is the logical place to do this, I
> 
> Definitely not: try-completion can be used in lots of other
> non-completion uses, can be called many times for a single completion
> operation, etc...  try-completion should be renamed to `find-common-
> prefix`.

Fine.  Not `try-completion'.  Please try the simple,
one-line patch I sent.  It's really not a big deal.

> PS: I'm not sure I completely understand the intended behavior of
>     `my-describe-function`, but I get the impression that for this
>     particular example, a maybe even better approach is to use
>     minibuffer-with-setup-hook to set a post-command-hook that calls
>     describe-function whenever the minibuffer names a valid function
>     (whether we get there via completion or plain typing, and regardless
>     if it's the sole completion).

No, that's something else.  This is not about describing
everything that shows up in the minibuffer.  It's about
a user asking to do something with a (full) completion - on
demand.  Something defined by the person who wrote the code
calling for completion.  Something specific for the command
that is asking for user input, or at least for its candidates.

What you say is not clear to me.  I don't know whether there
are particular completion tables to which this should not
apply.  I don't see why there would be.  This doesn't affect
completion at all.  It just takes a (full) completion and
does something with it - it takes effect when completion is
done, but before the function that initiates completion, such
as `completing-read', is finished reading user input.  The
user has not hit RET or C-g.  The user can still change the
minibuffer input.

I don't think what I described or showed in code is complex,
so it's not clear to me what's unclear to you. ;-)

[To be clear about one thing: This is not at all for _me_, as
it has no effect with my setup, which uses Icicles, which (1)
completes and uses TAB differently and (2) has a different
mechanism for optionally doing something when there is a sole
completion.  I just thought/think that this might be useful
for some users (and it is simple).]

When TAB tells you that there is only one completion for your
input (and completes to it), you can hit RET to choose that
completion (act on it).  But in some cases you might want to
first, or instead, take some other action on it - in particular,
maybe get some more info about it.  This lets you do that.

Hitting TAB again at that point does nothing now - it's a no-op.
If this hook were bound it would instead do something.  I
imagine that typically its action would be to display some info
about that completion or what will happen if you choose it (RET).
But the action could be anything, and it could even ignore the
completion.

She who writes a command that calls `completing-read' or
`read-file-name' would decide what sole-completion action, if
any, to provide (and document it as part of the command).

For one thing, seeing such additional info might help a user
decide whether she really wants to choose (RET) that completion.
Sometimes it's not obvious from the completed text (e.g. a
command or file name) just what is involved.

The second of the two simple examples didn't impress you.  OK.
(Did you try it at all?)  The first example depends on a
function `describe-file'.  I have such a command but forgot
that vanilla Emacs doesn't.  Here's what `describe-file' shows
for file `help-fns+.el' (where it's defined):

~/foobar/help-fns+.el
---------------------

File Type:                  Normal file
Permissions:                -rw-rw-rw-
Size in bytes:              174435
Time of last access:        Wed Jul 25 07:59:09 2018 (Pacific Daylight Time)
Time of last modification:  Thu May 10 15:48:56 2018 (Pacific Daylight Time)
Time of last status change: Wed Jul 25 07:59:09 2018 (Pacific Daylight Time)
Number of links:            1
User ID (UID):              37786
Group ID (GID):             513
Inode:                      281474976869587
Device number:              315267003

And here's the doc string:

 Describe the file named FILENAME.
 If FILENAME is nil, describe current directory ('default-directory').

 If the file is an image file then:
  * Show a thumbnail of the image as well.
  * If you have command-line tool 'exiftool' installed and in your
    '$PATH' or 'exec-path', then show EXIF data (metadata) about the
    image.  See standard Emacs library 'image-dired.el' for more
    information about 'exiftool'.

 If FILENAME is the name of an autofile bookmark and you use library
 'Bookmark+', then show also the bookmark information (tags etc.).  In
 this case, a prefix arg shows the internal form of the bookmark.

So the idea behind this simple example would be that you could
see the file permissions and timestamps, which might help you
decide whether you want to hit RET and act on the file (however
your command might act on it).  The alternative is to hit `C-g'
and fiddle a bit to find out such info, and then, if you're
reassured it's the right thing to do, invoke your command again.

The second example does the same kind of thing, for a function
instead of a file - before you choose a function, to do
something with it, you might want to check its doc to be more
sure.

This example has nothing to do with the function that's a
completion candidate being "inevitably ... tightly linked to
the completion table."  It's just an example of choosing among
some names (in this case function names).  You could as easily
be choosing among names "flobitz", "orndorf", and "ornplissle",
and want to see some more info about one of them.  You can
first complete to orndorf, thinking that's probably what you
want, but if unsure, hit TAB again to see some more info, then
change your input to "ornplissle" and hit RET.

It's really trivial - a one-line change, which has no effect
at all unless you hit TAB an extra time, and even then it has
no effect unless the hook is not empty.

Now, it's also possible that a hook function would do the
same thing as what RET does - or something similar.  I don't
expect that that will be common, but it's possible.  When
completing to an Info node name for `g', a hook function
could take you to that node (just like hitting RET will do),
for a peek.  But as the input-reading command isn't finished
you could change your input (or hit C-g) to cancel that
movement (e.g. moving back where you were).  If you just
changed your input you could then move to a different node.

Again, not a real example.  The point here is just that
the extra-TAB action _could_ be the same as or similar to
the RET action (which ends inputting).  It's up to the
code that reads the user input to decide what, if anything,
to put on the hook.