Re: Completions in Semantic

[Stefan Monnier <monnier@iro.umontreal.ca>]

>> > Are you looking for examples of hooks that would be needed, or examples
>> > of behaviors that need hooks to be designed?
>> Examples of hooks that could make such things possible.

> Ok, so here's a high-level shot on a possible completion infrastructure.
> Note that much of what I describe is oriented towards programming.

Yes, this discussion is difficult because my main interest is in reusing
the current standard completion code (used for most minibuffer
completions) for most/all other "in-buffer" completions.  OTOH you're
only interested in completion of variables and method/function
identifiers, which is itself just a special case of
"in-buffer" completion.

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

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

> **** get-return
>      Return type of the candidate (only meaningful on programming candidates)
> **** get-arguments
>      Arguments of the candidate (idem)

This is very specialized.  It doesn't even apply to all programming
languages (e.g. Prolog).  Also even in functional programming languages,
we usually keep the two together, i.e. we'd rather see that + has type
"int * int -> int" than that it has args of types "int, int" and return
type "int", and there's a good reason for that: sometimes it's not so
clear where's the boundary between args and return values: the function
"map" (aka "mapcar" in Elisp) has typically type "(a -> b) -> List a ->
List b" (with an implicit "∀ a,b" around it), but that can be read as
"map take a function argument of type (a -> b) and returns a new
function of type (List a -> List b)", or it can be read equivalently as
"map takes a function argument of type (a -> b) and a list of type List
a and returns a list of type List b".

All this to say: if you conflate "get-return" and "get-arguments"
together, you'll get a system that will fit many more languages.

> **** get-short-help
>      Short version of candidate help
> **** get-long-help
>      Long version of candidate help
> *** show
>     Shows an arbitrary composition of get-*.
>     E.g., (concat (get-signature candidate) "\n" (get-long-help candidate))
>     Where that sould be shown, must be user selectable (see below

Isn't this "show" redundant with get-short-help or get-long-help?

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

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

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.

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

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

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


        Stefan