General solution to include token literals in code completion suggestions

[TysonMN]

I think it should be possible for the ANTLR adaptor to get the list of token literals that the user could be typing and allow a plugin to include these token literals as code completion suggestions.

Background

To be able to resolve a reference, we must implement the interface PsiReference, which has a method called getVariants that returns code completion suggestions:

  /**
   * Returns the array of String, {@link PsiElement} and/or {@link com.intellij.codeInsight.lookup.LookupElement}
   * instances representing all identifiers that are visible at the location of the reference. The contents
   * of the returned array are used to build the lookup list for basic code completion. (The list
   * of visible identifiers may not be filtered by the completion prefix string - the
   * filtering is performed later by the IDE.)
   * <p>
   * This method is default since 2018.3.
   *
   * @return the array of available identifiers.
   */
  default Object @NotNull [] getVariants()

Feature Request

I can implement PsiReference::getVariants to return suggested code completions for semantic references in my language. Sometimes I also return token literals that are possible at a certain location. However, I feel like I am duplicating information from my lexer's and parser's grammars.

Instead, I think it should be possible for (ANTLR's) parser to determine what token literals are possible at a specified location in the parse tree. Then I could give those token literals to IntelliJ as something the user might be trying to type.

For the ANTLR plugin, this functionality could suggest that the user completes

myRule r
--------^ cursor location

as

myRule returns

I just tested with the current version of ANTLR's plugin (version 1.20), and return is not a code completion suggestion in that case.