puremourning/rfc.md

## rfc.md

      
    Raw
  

              rfc.md
            
          
    TL;DR

This RFC proposes introducing a second popup menu in insert mode to display
method argument hints, current parameter, etc. similar to a number of IDEs and
editors. The proposal is to allow scripts to control this (such as on insert of
( and ) characters) and for it to be non-interractive and not to interfere
with insert-mode completion.
The purpose of the RFC is to guage the appetite from Bram and the community for
such a feature, and to discuss the design/functional behaviours prior to
committing to an implementation/etc.
Motivation

There are a number of Vim plugins which attempt to provide some IDE-like
features using Vim's completion system, in combination with omnifuncs and
insert-mode completion that is built-in. Examples:

YouCompleteMe - https://github.com/Valloric/YouCompleteMe
neocomplete, deoplete, neocomplcache, and other friends
eclim?
any number of hundreds of omnifuncs
Microsoft language server client?
Various other "async complete" plugins
possibly any number of other completion plugins, including implementations
specific to particular languages (e.g. using omnifunc), or using l

In their simplest form, these provide a list of identifiers which are
semantically valid to be inserted at the current cursor position (or the result
of the equivalent of omnifunc's 'findstart' request), using the insert-mode
completion APIs provided by Vim.
One of the most commonly requested features for YouCompleteMe is the ability to
display the valid arguments for function calls, as well as semantically correct
identifiers. This feature is known as "argument hints", "parameter
completions", "signature help" or suchlike.
Microsoft's Language Server Protocol refers to them as "Signature Help".
Illustrative example

For example, the user types something like the following, with the cursor on
^:
typedef struct pum_T 
{
  int pum_item_count;
  int pum_selected;
  pumitem_T* items[];
} pum;

void pum_display_item( pum_T* pum,
                       char_u* message,
                       pumitem_T* item_list );

void pum_display_item( pum_T* pum,
                       int selected_item,
                       pumitem_T* item );

void main(void)
{
  pum_T pum = init_pum();
  pum_display_item( pum, pum.^
}
Current completion systems (or omni-completion, invoked with <C-x><C-o>) would
typically present a popup menu with the valid options from the definition,
such as:

int pum_selected
int pum_item_count

Methods often have many more arguments than this toy example, and
the declaration is not likely visible when it is used. Instead, many IDEs and
other editors provide a second "popup" when the user types the (. Typically,
this is above rather than below the current line and contains the list of
overloads of the fucntion and their arguments, often highlighting (one way or
another) the "current" argument being entered.
For example, it might look like this:
|------------------------------------------------------------------------|
| pum_display_item( pum_T* pum, **char_u *message**, pumitem_T* item )   |
| pum_display_item( pum_T* pum, **int selected_item**, pumitem_T* item ) |
|------------------------------------------------------------------------|
pum_display_item( pum, pum.^
                           |---------------------------|
                           | pum_selected         int  |
                           | int pum_item_count   int  |
                           |---------------------------|

Known existing attempts in Vim


The preview window.
By using the extra data in the completion menu item structure, we can show
some static information in the preview window. The drawbacks are that the
preview window has to always be visible (taking up valuable screen real
estate), or it pops in and out of visibility, causing the current row to
shift disconcertingly on the screen. Requires preview in the completeopt
and other autocmds etc. to show/hide it. Cursor moving into and out of
the preview window triggers BufEnter autocoms, which causes meaningful lag
when the completion menu is visible (OK, this could be blamed mostly on the
plugins using BufEnter autocommand, but you get the picture).


Oblitum/YouCompleteMe.
This is an approach using the standard PUM 100% with no hacks. The drawback is
that only the current argument is displayed, and mutually exclusively with
suggestions for the current identifier.


a YouCompleteMe test which also uses the command line (user experience is not
good using the command line, as the text can be clobbered by other things,
timers, etc.)


jedi-vim.
A python omnifunc plugin uses conceal highlighting to simulate a second menu.
The conceal apprach seems to involve actually changing the buffer contents and
relying on special highlight groups to make the appearance of a second
"menu".  Ingenious, perhaps, but probably not fun to implement or maintain.
With no disrespect to the author, it seems like a hack.


There are probably others; I just listed the ones I researched.
Proposal

Vim currently supports a single popup menu, which is used for:

insert-mode completion
balloons (a more recent addition, only in the terminal)

In the GUI, balloons are implemented as a popover window via a GUI-specific
mechanism.
The proposal is to allow 2 (mostly) independent popup menus to be displayed
insert mode:

the interractive completion menu, controlled without changes (via CTRL-X mode)
a second menu not overlapping the completion menu controlled only by scripts.

For the purposes of this RFC (and brevity), I will refer to the menus as:

the completion menu, and
the hint menu

respectively.
Display

Priority in terms of display is always given to the completion menu, as that is
the one the user interracts with. The completion menu prefers to draw below the
cursor (if there is room), above otherwise.
The hint menu prefers (for example):

if there is no completion menu:

if there is room above, above the cursor line
otherwise if there is blow, below the cursor
otherwise not at all


if there is a completion menu, and it wants to be below the cursor:

if there is room above, above the cursor line
otherwise, not at all


if there is a completion menu, and it wants to be above the cursor:

if there is room below, below the cursor line
otherwise, not at all


Both the completion menu and the hint menu are cleared when a balloon is
displayed.
Content

Discussion point: This is open for debate and I would love to hear thoughts on
it. I see there are a couple of options here:


"Pass-through".  The contents of the hint menu are at the discretion of
the script. Borrowing from the approach taken for balloons, the menu supports
a list of strings, but does not perform any additional formatting (such as
spacing/splitting).


"Call a spoon a spoon". The purpose of the feature is argument hints, so
we make the API specific to that. Anything else is YAGNI.
e.g. The API is passed a list of signatures, including the active signature
and argument. Vim then handles the display and highlighting, allowing the
script interface to be relatively simple, while restricting (perhaps) the
amount of innovation.


Implementation

One could argue that parameter hints are a special case of balloons. The special
case is that they are visible at the same time as completions in insert mode.
However, I'm not totally convinced that's the right approach. In particular,
balloons are very different in the terminal and GUI, and I feel like this feels
more similar to insert-mode completion than any existing expected use case for
balloons.
So instead, the proposal is to actualy just add (yet) another popupmenu, whose
data is independent of the existing popopmenu and balloon data.
The general idea would be to re-use most (if not all) of the existing popupmenu
code, by factoring its data out and passing an instance of "a" pum to most
functions. A vimscript API controls the hint pum, and the API for completion is
unchanged.
Here's a (very) brief idea of how I think it could be done:


Phase 1, refactor so that pum data isn't quite-so global

store all pum-related state in a struct pum_T
declare a single instance of this  called compl_pum
use compl_pum for completion and balloons exactly as it is used today
No functional change.


Phase 2, add the second pum

create a vimscript API that allows a script to display the hint pum in
insert mode
provide experrimental support for:

hint_pum_set( {arg} )  = set the contents of the hint menu

arg contents TBD, but a list of strings, maybe or something else...


hint_pum_show( column ) = enable display of the hint menu
hint_pum_hide()         = disable display of the hint menu
hint_pum_visible()      = return whether hint menu is displayed


hint the hint pum when exiting insert mode (and probably a load of other
things i haven't thought of)


Phase 3, allow hint menu to highlight the current argument

Details sketchy, as they depend on some of the previous discussion points.
One option is to embed something, perhaps using magic string markers in the
menu input strings, to "bold" some section.
Another option might be to somehow use new specific highlighting groups,
or something along those lines, combined with knowledge about which argument
is selected.


Comments

I'd welcome comments on anything including:

The welcomeness/appetite for such functionality
The generality of the proposal (or otherwise)
The overall approach, related ideas/works/etc.
Niggly bikeshedding; the more the merrirer

Of course nothing is set in stone at this stage, but I did write a proof of
concept about 12 months ago as part of the research into the idea.
Some demos are attached to the gist as comments. I can point to the code in
Vim and YouCompleteMe, but it is very hacky and exploratorys, so it would be
completely re-engineered before any PR/patch is sent.