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

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

[Drew Adams]

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.

This feature would make it easier for callers of `completing-read',
`read-file-name', etc. to do something at that point with that sole
match, while the user can still change her minibuffer input.  For
example, the caller could display additional information about that sole
match.

This could alternatively be done in `completion--done', before it calls
`exit-fun', but it would also need to be done in the case where there is
no exit function.  `try-completion' is the logical place to do this, I
think, but it is coded in C.  I'm not sure which Lisp place would be
best as an alternative, if it's not `completion--done'.

A hook is handier for this than, say, defining an exit function that
tests for `finished' and binding `completion-extra-properties' to a list
that contains `:exit-function' with that function as value.  A hook lets
you add any number of such "sole completion" functions, and their use is
not tied to just one call of a completion function.

Here's a quick implementation using `completion--done'.  It may be all
that's required - not sure about the use of `unknown' as
`completion--done' arg FINISHED.  It just adds these two lines:

  (when (eq finished 'finished)
    (run-hook-with-args 'completion-sole-match-functions string))

(defun completion--done (string &optional finished message)
  (let* ((exit-fun (plist-get completion-extra-properties :exit-function))
         (pre-msg (and exit-fun (current-message))))
    (cl-assert (memq finished '(exact sole finished unknown)))
    (when (eq finished 'finished)
      (run-hook-with-args 'completion-sole-match-functions string))
    (when exit-fun
      (when (eq finished 'unknown)
        (setq finished
              (if (eq (try-completion string
                                      minibuffer-completion-table
                                      minibuffer-completion-predicate)
                      t)
                  'finished 'exact)))
      (funcall exit-fun string finished))
    (when (and message
               ;; Don't output any message if the exit-fun already did so.
               (equal pre-msg (and exit-fun (current-message))))
      (completion--message message))))

(defvar completion-sole-match-functions ()
  "Functions to be run when completion results in only one match.
Each function must accept that completion as its first arg.")

In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 10.0.16299
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 3484 bytes --]

The attached patch implements this enhancement.

Simple example use cases:

(defun my-find-file-other-window (filename &optional wildcards)
  "`find-file-other-window', but show file info if only one completion matches."
  (interactive
   (unwind-protect
       (progn
         (add-hook 'completion-sole-match-functions 'describe-file)
         (find-file-read-args "Find file in other window: "
                              (confirm-nonexistent-file-or-buffer)))
     (remove-hook 'completion-sole-match-functions 'describe-file)))
  (find-file-other-window filename wildcards))

(defun my-describe-function (function)
  "`describe-function', but show output if only one completion matches."
  (interactive
   (unwind-protect
       (progn
         (add-hook 'completion-sole-match-functions
                   (lambda (fn) (describe-function (intern fn))))
         (let* ((fn (function-called-at-point))
                (enable-recursive-minibuffers t)
                (val (completing-read
                      (if fn
                          (format "Describe function (default %s): " fn)
                        "Describe function: ")
                      #'help--symbol-completion-table
                      (lambda (f)
                        (or (fboundp f) (get f 'function-documentation)))
                      t nil nil
                      (and fn (symbol-name fn)))))
           (unless (equal val "")
             (setq fn (intern val)))
           (unless (and fn (symbolp fn))
             (user-error "You didn't specify a function symbol"))
           (unless (or (fboundp fn) (get fn 'function-documentation))
             (user-error "Symbol's function definition is void: %s" fn))
           (list fn))))
   (remove-hook 'completion-sole-match-functions
                (lambda (fn) (describe-function (intern fn)))))
  (describe-function function))

----

Or, using macro `with-hook-added' (see bug #33601):

(defun my-find-file-other-window (filename &optional wildcards)
  "`find-file-other-window', but show file info if only one completion matches."
  (interactive
   (with-hook-added completion-sole-match-functions
     describe-file
     (find-file-read-args "Find file in other window: "
                          (confirm-nonexistent-file-or-buffer))))
  (find-file-other-window filename wildcards))

(defun my-describe-function (function)
  "`describe-function', but show output if only one completion matches."
  (interactive
   (with-hook-added completion-sole-match-functions
     (lambda (fn) (describe-function (intern fn)))
     (let* ((fn (function-called-at-point))
            (enable-recursive-minibuffers t)
            (val (completing-read
                  (if fn
                      (format "Describe function (default %s): " fn)
                    "Describe function: ")
                  #'help--symbol-completion-table
                  (lambda (f)
                    (or (fboundp f) (get f 'function-documentation)))
                  t nil nil
                  (and fn (symbol-name fn)))))
       (unless (equal val "")
         (setq fn (intern val)))
       (unless (and fn (symbolp fn))
         (user-error "You didn't specify a function symbol"))
       (unless (or (fboundp fn) (get fn 'function-documentation))
         (user-error "Symbol's function definition is void: %s" fn))
       (list fn))))
  (describe-function function))

[-- Attachment #2: minibuffer-2018-12-03a.patch --]
[-- Type: application/octet-stream, Size: 1003 bytes --]

diff -u minibuffer.el minibuffer-2018-12-03a-patched.el
--- minibuffer.el	2018-12-03 09:23:45.858608200 -0800
+++ minibuffer-2018-12-03a-patched.el	2018-12-03 09:27:17.862397300 -0800
@@ -753,6 +753,10 @@
 the second failed attempt to complete."
   :type '(choice (const nil) (const t) (const lazy)))
 
+(defvar completion-sole-match-functions ()
+  "Functions to be run when completion results in only one match.
+Each function must accept that completion as its first arg.")
+
 (defconst completion-styles-alist
   '((emacs21
      completion-emacs21-try-completion completion-emacs21-all-completions
@@ -1769,6 +1773,8 @@
   (let* ((exit-fun (plist-get completion-extra-properties :exit-function))
          (pre-msg (and exit-fun (current-message))))
     (cl-assert (memq finished '(exact sole finished unknown)))
+    (when (eq finished 'finished)
+      (run-hook-with-args 'completion-sole-match-functions string))
     (when exit-fun
       (when (eq finished 'unknown)
         (setq finished

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

[Drew Adams]

ping.

Would someone please consider committing this patch?  Thx.

------------------

diff -u minibuffer.el minibuffer-2018-12-03a-patched.el
--- minibuffer.el	2018-12-03 09:23:45.858608200 -0800
+++ minibuffer-2018-12-03a-patched.el	2018-12-03 09:27:17.862397300 -0800
@@ -753,6 +753,10 @@
 the second failed attempt to complete."
   :type '(choice (const nil) (const t) (const lazy)))
 
+(defvar completion-sole-match-functions ()
+  "Functions to be run when completion results in only one match.
+Each function must accept that completion as its first arg.")
+
 (defconst completion-styles-alist
   '((emacs21
      completion-emacs21-try-completion completion-emacs21-all-completions
@@ -1769,6 +1773,8 @@
   (let* ((exit-fun (plist-get completion-extra-properties :exit-function))
          (pre-msg (and exit-fun (current-message))))
     (cl-assert (memq finished '(exact sole finished unknown)))
+    (when (eq finished 'finished)
+      (run-hook-with-args 'completion-sole-match-functions string))
     (when exit-fun
       (when (eq finished 'unknown)
         (setq finished

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

[Eli Zaretskii]

> Date: Fri, 28 Dec 2018 10:56:08 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> ping.
> 
> Would someone please consider committing this patch?  Thx.

Stefan, any comments?  If okay, I'd like to push this to master.

> diff -u minibuffer.el minibuffer-2018-12-03a-patched.el
> --- minibuffer.el	2018-12-03 09:23:45.858608200 -0800
> +++ minibuffer-2018-12-03a-patched.el	2018-12-03 09:27:17.862397300 -0800
> @@ -753,6 +753,10 @@
>  the second failed attempt to complete."
>    :type '(choice (const nil) (const t) (const lazy)))
>  
> +(defvar completion-sole-match-functions ()
> +  "Functions to be run when completion results in only one match.
> +Each function must accept that completion as its first arg.")
> +
>  (defconst completion-styles-alist
>    '((emacs21
>       completion-emacs21-try-completion completion-emacs21-all-completions
> @@ -1769,6 +1773,8 @@
>    (let* ((exit-fun (plist-get completion-extra-properties :exit-function))
>           (pre-msg (and exit-fun (current-message))))
>      (cl-assert (memq finished '(exact sole finished unknown)))
> +    (when (eq finished 'finished)
> +      (run-hook-with-args 'completion-sole-match-functions string))
>      (when exit-fun
>        (when (eq finished 'unknown)
>          (setq finished
> 
> 
> 
> 

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

[Stefan Monnier]

> Stefan, any comments?  If okay, I'd like to push this to master.

I'll take a look at it later today.  From where I sit, I think I won't
like it, but I need to look more closely to be sure,


        Stefan

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

[Stefan Monnier]

> 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?

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

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


        Stefan


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

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

[Drew Adams]

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

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

[Stefan Monnier]

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

Not sure what you mean by "kind of completion" but a completion table
describes the "kind" of completion in the sense of describing the set of
possible completions (i.e. either a set of function names, or a set of
file names, or ...).

In your example, the hook function calls `describe-function` so it only
makes sense when the completion table is a set of function names, an
becomes absurd when it's a set of file names, or Git revisions, ...

So in your example, your hook function is very tightly linked to the
completion table.  I still don't understand this example well enough to
understand if/how it's linked to the UI (e.g. what should happen if the
user happens to use, say, ido-ubiquitous to complete his function names).

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

What do you mean by "relevant"?  It would require the code to be a bit
different but you could get the exact same behavior with it.

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

One part I don't fully understand is why this code wants to call
`describe-function` only and exactly when the user hits TAB and it
completes to an sole match.  Why should the user not want to see that
same result when typing the name explicitly instead of completing to it?
Why should the user not want to see the same result when completing to
an exact-but-not-sole match?

Another thing I don't understand about your example is: what is the user
expected to do after hitting TAB (which completed to a sole match)?
The only thing left to do seems to be RET but that's redundant since
`describe-function` was already called.

> [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).]

It's not as simple as it seems: if the user goes to some other buffer in
the middle of the completion, your completion-sole-match-functions will
not wreak havoc in unrelated completions.

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

Why only in that specific case?

> Hitting TAB again at that point does nothing now - it's a no-op.
> If this hook were bound it would instead do something.

Ah, so you want this hook to be run when TAB is hit a second time, in
which case it normally does nothing (tho that depends on the config, it
may also display the *Completions* buffer)?

I think I'm beginning to understand.  But I think it belongs in the
completion data (i.e. alongside :exit-function).


        Stefan

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

[Drew Adams]

> >> 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.
> 
> Not sure what you mean by "kind of completion" but a completion table
> describes the "kind" of completion in the sense of describing the set of
> possible completions (i.e. either a set of function names, or a set of
> file names, or ...).
> 
> In your example, the hook function calls `describe-function` so it only
> makes sense when the completion table is a set of function names, an
> becomes absurd when it's a set of file names, or Git revisions, ...

If that's what you meant by your question then yes,
I think I answered that when I said that the person
who writes the code that invokes `completing-read',
say, is the person who adds a function to the hook,
or binds the hook - or not (does not use the hook).

What you put on the hook typically is specific to
the completion candidates you provide, and to the
command that uses the candidate the user chooses.

If that's what you meant by "tightly linked to the
completion table", then yes.  But the hook does not
change the completion table or change completion in
any way.  It's only about what a user does with a
completion (the "UI" you mentioned?).

> So in your example, your hook function is very tightly linked to the
> completion table.  I still don't understand this example well enough to
> understand if/how it's linked to the UI (e.g. what should happen if the
> user happens to use, say, ido-ubiquitous to complete his function names).

Ido?  Idon't.  I don't know either.  Try it, to see. ;-)

> >> 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.
> 
> What do you mean by "relevant"?  It would require the code to be a bit
> different but you could get the exact same behavior with it.

It's not clear yet that you are clear about what this
is about.  But if you feel you are, and if you think
there's a better way to provide such behavior to users,
go for it.

As I said, I don't use this myself.  It's just something
simple that I saw as possible, easy, and (I expect)
likely to be of some (limited) use.

If you want to close the bug, I won't cry.

> >> 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.
> 
> One part I don't fully understand is why this code wants to call
> `describe-function` only and exactly when the user hits TAB and it
> completes to an sole match.  Why should the user not want to see that
> same result when typing the name explicitly instead of completing to it?

I never said a user could not want that.  But there is
a difference between typing something and knowing that
it is one of a set of provided choices.

Doing this only for a sole completion (which is what
I'd recommend here) avoids having it kick in at a
zillion places where a user likely doesn't want it.

In my view of this it would be only on demand, and
only when a user knows that what's in the minibuffer
is a full completion (what Emacs calls completed and
unique).

That's the goal here.  But feel free to design
something different, for some different, but perhaps
related, purpose.

> Why should the user not want to see the same result when completing to
> an exact-but-not-sole match?

A user might.  See above.  Users can want all kinds
of things.  Different users, and the same user, can
want different things at different times.

This simple suggestion is not trying to do more than
what I suggested.  It's not trying to provide an
extended eldoc or a partial Icicles/Helm or anything
of the sort.

The hook function can do pretty much anything with
the completion, and it can ignore it.  It's not
limited to providing more info about the completion.

This just lets a user, on demand, invoke an action
(defined by whoever wrote the code invoking the
input-reading function) on user input that has
already been completed (the input is complete and
unique).  That's all.  Really not a big deal.

> Another thing I don't understand about your example is: what is the user
> expected to do after hitting TAB (which completed to a sole match)?
> The only thing left to do seems to be RET but that's redundant since
> `describe-function` was already called.
> 
> > [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).]
> 
> It's not as simple as it seems: if the user goes to some other buffer in
> the middle of the completion, your completion-sole-match-functions will
> not wreak havoc in unrelated completions.

I don't know what you mean.  Maybe give a specific
example (e.g. recipe, using the patch)?  Or not.

I haven't tried to look for problems this might
introduce, as none came to mind spontaneously.
Do you really see something problematic here?

I don't want to spend a lot of time on this.  If
you don't get it, or you don't think it's helpful,
or you think it's problematic, please feel free
to drop it and close the bug.  No harm done.

But I'm happy to answer questions about what the
behavior or intention is, if I know the answers.
IOW, if you're interested then we can continue
to chat if something's not clear or there's a
problem, but if you're not interested then let's
call it quits.

> > 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.
> 
> Why only in that specific case?

See above.  Did I answer that sufficiently?

> > Hitting TAB again at that point does nothing now - it's a no-op.
> > If this hook were bound it would instead do something.
> 
> Ah, so you want this hook to be run when TAB is hit a second time, in
> which case it normally does nothing (tho that depends on the config, it
> may also display the *Completions* buffer)?

Absolutely.  If you just try the code I think it will
become clear what the behavior and intention are.
It's harder to describe than to experience.  If you
try it then maybe it will be easier to discuss any
problems you see or further questions you have.

> I think I'm beginning to understand.  But I think it belongs in the
> completion data (i.e. alongside :exit-function).

I don't.  But you're the expert on that.  Go for it,
if you think it's useful and that's a better approach.

Do you think that's easier for someone writing a call
to `completing-read' or `read-file-name', while giving
users the same behavior?  You're not just trying to
promote uptake of `completion-extra-properties', are
you? ;-)  Really, I have no problem with your providing
this some other way, or with deciding not to provide
it at all.

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

[Stefan Monnier]

>> So in your example, your hook function is very tightly linked to the
>> completion table.  I still don't understand this example well enough to
>> understand if/how it's linked to the UI (e.g. what should happen if the
>> user happens to use, say, ido-ubiquitous to complete his function names).
>
> Ido?  Idon't.  I don't know either.  Try it, to see. ;-)

More generally, the code you wrote shouldn't presume exactly which
completion UI is used, so the API should let you provide some "show
extra info" function, and then separately some UI may opt to use this
function for example when completing a sole match.

>> It's not as simple as it seems: if the user goes to some other buffer in
>> the middle of the completion, your completion-sole-match-functions will
>> not wreak havoc in unrelated completions.
   ^^^
   now

> I don't know what you mean.  Maybe give a specific
> example (e.g. recipe, using the patch)?  Or not.

The hook function is active as long as the minibuffer is active, so if
the user uses recursive minibuffers, the hook function will apply not
just to the originally planned completion but also to other completions
that take place in recursive minibuffers.

It's basically the same problem as the usual problem of passing extra
parameters via dynamic scoping, where the dynamic let-binding doesn't
apply only to the first call, but to all nested calls that may occur.

Anyway, thanks, I think I see how to introduce that feature (and
I suspect it's actually already covered by the company-compatibility
extra properties).


        Stefan