Re: Completions in Semantic

[Lluís]

On Sat, 31 Oct 2009 16:18:17 -0400, Stefan Monnier wrote:
[...]
> > * Completion candidates
> > ** Information Contains whatever information the system could gather
> >    about the symbol. When programming with semantic activated, this could
> >    be the semantic tag structure.
> 
> If you don't know what that info is going to be, then it is useless in
> the generic API since anybody using the generic API will expect to work
> for any kind of candidate and so can't use this value since it has no
> idea what it might be.

I was thinking on a scenario where each completion source provides its own
implementation of "Actions", and "Information" is thus not publicly visible
but for the "Actions".


> > ** Actions
> >    Various actions that can be applied on a candidate.
> >    This is basically the interface to view the candidate information.
> 
> In the generic completion code, we currently have 4 actions:
> test-completion, try-completion, all-completions, and the new
> completion-boundaries (which in the case of function-name completion is
> always trivial).
> 
> For reasons of backward compatibility, it's difficult to add new actions
> in the generic code (the new completion-boundaries is the first time we
> add an action since ... before 1993), but one could easily imagine
> adding actions for specific kinds of completions, which could then only
> be used for completion tables that support those extra actions.

So, any higher-level code could attach new actions as it sees fits. That's
just what I was thinking about.


> > **** get-return
> >      Return type of the candidate (only meaningful on programming 
> > candidates)
> > **** get-arguments
> >      Arguments of the candidate (idem)
> 
[...]
> All this to say: if you conflate "get-return" and "get-arguments"
> together, you'll get a system that will fit many more languages.

You're right, this might be reduced to something like:
       - get-signature
       - get-definition

The difference is that the first provides just a type signature, while the
latter provides the whole definition (including the symbol name). But still
it should be selectable whether you want argument names or just types.

On the other hand, if the implementation of all the actions is provided by
each completion source, the "get-*" actions simply are internal
source-specific helpers, and thus out of the question.


[...]
> > *** insert-*
> >     Insert "something" at point (cannot think of use-cases where insertion 
> > takes
> >     place in other places other than point).
> 
> I think side-effects have no business being here.  Let the client code
> do the insertion, and limit the candidate object to returning the
> info necessary to figure out what to insert.

I completely agree, but like show, this was more on the conceptual level
where you can show and/or insert a specific candidate.


> > * UI
> > ** Types
> >    The completion-ui package has implementations for some (if not all) of 
> > them.
> >    The UI
> > *** buffer
> >     Is the current *Completions* buffer.
> > *** minibuffer
> >     The completion system used by, e.g., predictive-mode.
> > *** overlay
> >     That's the one I prefer, see company-mode as an example.
> > *** others
> >     There are many others, like menus, etc.
> 
> Or icomplete-mode, yes.  These seem to only affect
> minibuffer-completion-help (the standard function that displays the list
> of possible completions, usually in *Completions*).  When I use
> completion, I generally try to avoid getting to that point, tho.

Sorry, I don't understand what you mean here.


> This points to a more important aspect: when is this list displayed,
> when is it updated, and when is it brought down.  For each kind of
> completion-list, those choices are not always the same
> (e.g. icomplete-mode brings is up right away and updates it after each
> keystroke, whereas what you call "buffer" only brings it up on a few
> specific operations and only updates it on those same operations).
> This behavior-variation depending on the display-style is something that
> makes it trickier to write the generic code.

Ok, I might say something totally stupid, but you just need to map the UI
actions to specific keys, which can be selected by the user. And on the
case of "continuous completion" the specific UI catches all keystrokes to
issue the refresh action (the obvious option is to remap all keys, but I
don't know how is this really implemented).


> > *** start
> >     Start the completion process. E.g.:
> >         (show current-ui get-return get-name get-arguments)
> >     would show the full signature of a function.
> 
> I don't understand it: when I start completion, I don't have any
> function chosen yet (that's the whole reason for me to try to complete
> it, usually), so there's no signature to show yet.

Sorry, this was not detailed enough. What I meant is that you somehow tell
the framework that each candidate must be shown as:
    return name arguments


> > *** focus
> >     Let's the user "highlight" an entry of the possible candidates. It's the
> >     good old next/prev in an overlay UI.
> >     Focusing an element can trigger other actions. This will mainly be
> >         (show <where> ...)
> >     The <where> could be any of minibuffer, another buffer, tooltip, etc.
> 
> Oh, so "show" is not a method that returns a string, it's a method that
> has some side-effect that hopefully "shows" the candidate?  That makes
> more sense now.

Yes, that's the idea I tried to express.


> > *** completion-map
> >     Extra actions the user can trigger through keyboard when the completion 
> > UI
> >     is "active".
> >     E.g., i can focus to an interesting symbol and trigger
> >         (show some-buffer get-long-help)
> 
> That might be tricky to support in a generic way, since depending on the
> UI, it's not necessarily clear where the completion-map should be active
> and with which other keybindings it might collide.

As I see it, there are two types of interfaces:
- in-buffer: this includes overlays, menus, etc.
- in another buffer: the minibuffer is just a specific case of using
  another buffer for the completion UI.

In the first case, once started, the user is interacting directly with the
UI: moving focus, triggering "extra actions", etc. This UI can, in turn,
modify the underlying buffer (partial completions, the user who keeps
writing, etc.).

On the second case, the user can indirectly interact with the UI through
its current buffer (e.g., accept completion, stop completion, partial
completion, etc.), or either switch to the completion buffer and trigger
the rest of actions (e.g., move to a specific candidate and trigger the
"show extended help" action).

What I see more problematic is that some actions simply have no meaning in
some specific candidate sources. E.g., yasnippet has no use for a "extended
help" action. But at least, we can always ignore the action if the
source/backend of a specific candidate provides no implementation for it.


Read you,
     Lluis

--
 "And it's much the same thing with knowledge, for whenever you learn
 something new, the whole world becomes that much richer."
 -- The Princess of Pure Reason, as told by Norton Juster in The Phantom
 Tollbooth