@Language annotation for JDK 13 text blocks

[Tagir Valeev]

Hello!

Here I share the IntelliJ IDEA experience without making any specific
suggestions about the proposal.

We have a Language annotation in JetBrains annotations pack:
https://github.com/JetBrains/java-annotations/blob/89bb0eb829bf7f63b6504009e592199fae45cac9/common/src/main/java/org/intellij/lang/annotations/Language.java

This accepts plain language name like "JAVA", "XML", "RegExp", "SQL",
etc. The complete list is not specified and actually what is
recognized depends on the installed IntelliJ IDEA plugins, so you can
support new language writing a plugin. Also, the annotation has a
prefix and a suffix, which are useful when we want to supply a part of
the valid program. E.g. `@Language(value="JAVA", prefix="class X {",
suffix="}")` allows to pass a Java method that will be properly
highlighted (however, any other Java member like field will be also
recognized, so it's not so easy to restrict to methods only).

Usually, we annotate method parameters. In this case, call-site
annotation is inferred using a sophisticated procedure. E.g.

ResultSet executeQuery(@Language("SQL") String query);

void foo() {
  String sql = "SELECT 1 FROM DUAL";
  executeQuery(sql);
}

In this case, we detect that the `sql` variable is later passed to the
method whose parameter is annotated as @Language("SQL"), so we
highlight the `sql` initializer. This is complex, not very fast and
hard to specify, but allows to greatly reduce the number of
annotations in user code, especially when the library code is
pre-annotated. We ship external annotations for standard Java library.

Also, it's allowed to annotate arrays of strings (in this case every
string inside the array is assumed to be annotated) and something
more.

With best regards,
Tagir Valeev.

On Sat, Feb 8, 2020 at 1:37 AM Anthony Vanelverdinghe
<anthonyv.be at outlook.com> wrote:
>
> [moving discussion to amber-dev]
>
> Hi Geertjan
>
> Not sure if there's been public mailing list discussions about it, but
> I'm pretty sure the amber team has already considered the idea of
> attaching this kind of metadata to text blocks. I don't know of any
> related decisions, though.
>
> One issue with annotations in particular, is that text blocks can appear
> in contexts where annotations can't, such as arguments to a method call,
> or annotation element values (JPA's @NamedQuery comes to mind).
> Another issue would be: where/how to standardize the set of "languages"?
> The IANA registry with media types doesn't contain things like SQL (let
> alone all its dialects), JSP, JSX, etc. And it's not Java SE's job to
> maintain such a registry either.
>
> Kind regards, Anthony
>
> PS: the Text Blocks JEP [1] specifies amber-dev as the mailing list for
> discussion, so I took the liberty to change the mailing lists. As I
> understand it, ide-support-dev is meant for IDE/tooling support when
> working on the OpenJDK codebase itself
>
> [1] http://openjdk.java.net/jeps/368
>
> On 07/02/2020 12:58, Geertjan Wielenga wrote:
> > Hi all,
> >
> > It would be of great support for IDEs, editors, and tools of various kinds
> > if a @Language annotation would be part of the support for text blocks, so
> > that tooling would be able to determine which editor should be injected
> > within the text block.
> >
> > For example, imagine this annotation on top of a text block:
> >
> > @Language="text/html"
> >
> > That would then be used by IDEs, editors, tools, etc, to determine that the
> > text within the block is HTML and that therefore, for the tools that
> > support this (e.g., NetBeans, IntelliJ IDEA), an HTML editor would then be
> > injected within the text block, which would make HTML-oriented syntax
> > coloring, code completion, etc, available within the text block.
> >
> > If this meets with enthusiasm, what would the next steps be? An addition to
> > the text block spec or a new spec or something different?
> >
> > Thanks,
> >
> > Geertjan