Complement "g:java_ignore_javadoc" with "g:java_ignore_html"
and "g:java_ignore_markdown" to allow selectively disabling
the recognition of HTML and CommonMark respectively.
(Note that this is not a preview feature.)
======================== LIMITATION ========================
According to the syntactical details of JEP 467:
> Any leading whitespace and the three initial / characters
> are removed from each line.
>
> The lines are shifted left, by removing leading whitespace
> characters, until the non-blank line with the least
> leading whitespace has no remaining leading whitespace.
>
> Additional leading whitespace and any trailing whitespace
> in each line is preserved, because it may be significant.
the following example:
------------------------------------------------------------
/// A summary sentence.
/// A list:
/// - Item A.
/// - Item B.
///
/// Some code span, starting here `
/// 1 + 2 ` and ending at the previous \`.
------------------------------------------------------------
should be interpreted as if it were written thus:
------------------------------------------------------------
///A summary sentence.
/// A list:
/// - Item A.
/// - Item B.
///
/// Some code span, starting here `
/// 1 + 2 ` and ending at the previous \`.
------------------------------------------------------------
Since automatic line rewriting will not be pursued, parts of
such comments having significant whitespace may be ‘wrongly’
highlighted. For convenience, a &fex function is defined to
‘correct’ it: g:javaformat#RemoveCommonMarkdownWhitespace()
(:help ft-java-plugin).
References:
https://openjdk.org/jeps/467https://spec.commonmark.org/0.31.2closes: vim/vim#1574085f054aa3f
Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
Co-authored-by: Tim Pope <code@tpope.net>
Define "g:java_syntax_previews" and include number 476 in
its list to enable this recognition:
------------------------------------------------------------
let g:java_syntax_previews = [476]
------------------------------------------------------------
Reference:
https://openjdk.org/jeps/476closes: vim/vim#1570950423ab808
Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
Define "g:java_syntax_previews" and include number 455 in
its list to enable this recognition:
------------------------------------------------------------
let g:java_syntax_previews = [455]
------------------------------------------------------------
Reference:
https://openjdk.org/jeps/455closes: vim/vim#1569823079450a8
Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
Stop assigning by default the NonText highlighting group for
javaConceptKind modifiers since its colour is hardly
distinguishable from a background colour for a range of
colour schemes.
fixesvim/vim#15237
related vim/vim#15238closes: vim/vim#156645e95c8f637
Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
Co-authored-by: Dexter Gaon-Shatford <dexter@gaonshatford.ca>
Introduce a new API variable "g:java_syntax_previews" whose
value must be a list of syntax preview feature numbers.
Enumerate the currently supported numbers in a table at the
end of the documentation entry for "ft-java-syntax".
Also, disable the recognition of String Templates. Despite
the withdrawal of this preview feature in its proposed form
from the upcoming JDK 23 release and the fact that the JDK
22 release is coming to EOL this September, an earlier
iteration of this preview feature was included in JDK 21
(LTS) whose EOL is projected to fall due in late 2028 and,
therefore, retain the current implementation.
Define "g:java_syntax_previews" and include number 430 in
its list to enable the recognition of String Templates:
------------------------------------------------------------
let g:java_syntax_previews = [430]
------------------------------------------------------------
References:
https://openjdk.org/jeps/430 (Preview)
https://openjdk.org/jeps/459 (Second Preview)
https://openjdk.org/jeps/465 (Third Preview)
https://mail.openjdk.org/pipermail/amber-spec-experts/2024-April/004106.htmlcloses: vim/vim#155798556e23ee9
Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
- Obtain and pass through translated messages with this
function.
- If "g:java_foldtext_show_first_or_second_line" is defined,
assign this function to &foldtext.
closes: vim/vim#155492750b83fa1
Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
- Prefix all global variables with "g:".
- Add spaces around each variable assignment operator.
- Remove extraneous whitespace characters.
- Remove a spurious _serializable_ Java keyword (since v1.1,
java.io.Serializable and java.io.Externalizable interfaces
provide an API for object serialization; see vim-6-0j).
- Normalise the syntax definition argument order by making
_contained_ the first argument of each such definition.
- Normalise the argument tabulation for highlighting group
definitions.
Reference:
https://web.archive.org/web/20010821025330/java.sun.com/docs/books/jls/first_edition/html/1.1Update.html
related: vim/vim#153999aabcef1c8
Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
- Reword a few sentences and reformat a few paragraphs.
- Supply absent capitalisation and punctuation.
- Make listed highlighting groups and code stand out.
- Prefix all Java-related global variables with "g:".
- Add spaces around each variable assignment operator.
- Acknowledge that some Javadoc variables are maintained in
the HTML syntax file.
Also, move the overridable _default_ HTML group links before
the HTML syntax file inclusion in order to implement the
documented diverged settings.
related: vim/vim#153993749dff093
Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
This token will be highlighted, similar to the arrow of
lambda expressions, whenever "g:java_highlight_functions" is
defined.
Also:
- Improve the recognition of _switch-case_ labels
(D-Cysteine).
- Remove insignificant empty statements in syntax test
files.
closes: vim/vim#15322
References:
https://docs.oracle.com/javase/specs/jls/se21/html/jls-15.html#jls-15.13https://github.com/fleiner/vim/pull/1e73e5b889b
Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
Co-authored-by: D-Cysteine <54219287+D-Cysteine@users.noreply.github.com>
With the variables defined, distinctly highlight parts of
a method declaration header: its name and parameter list
parens, from its type parameters, return type, and formal
parameters; and distinctly highlight parts of a lambda
expression: its parameter list parens and the arrow, from
its formal parameters and identifiers.
closes: vim/vim#1508301a4fb104d
Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
In the presence of parameterised types whose names begin
with a capital letter and end with a less-than sign "<" that
introduces a type argument or a list of comma-separated type
arguments, followed by a greater-than sign ">", a variable
"g:java_highlight_generics" can be defined to have some
components of such types uniformly coloured (by picking
highlight groups for javaGenericsC{1,2}, javaWildcardBound).
For example,
------------------------------------------------------------
java.io.InputStream stream = java.io.InputStream.nullInputStream();
java.util.function.Function<String,
java.util.function.BiFunction<String, String, String>> updater =
property -> (oldValue, newValue) -> oldValue;
java.util.logging.LogManager.getLogManager()
.updateConfiguration(stream, updater);
------------------------------------------------------------
Note that the diamond form and explicit type arguments do
not qualify for this kind of recognition.
For example,
------------------------------------------------------------
new java.util.HashSet<>().<String>toArray(new String[0]);
------------------------------------------------------------
References:
https://docs.oracle.com/javase/specs/jls/se21/html/jls-4.html#jls-4.5https://docs.oracle.com/javase/specs/jls/se21/html/jls-15.html#jls-15.9https://docs.oracle.com/javase/specs/jls/se21/html/jls-15.html#jls-15.12.2.1closes: vim/vim#15050beb02ed674
Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
Instances of anonymous classes can be passed as method
arguments and should be subject to line folding as well.
closes: vim/vim#1504894c5d8a5e2
Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
Also:
- Restore the capability to mark as an error braces nested
in parens with g:javaInParen.
- Try not to fold top-level-type bodies. (Defining multiple
package-private top level types in a single source file is
not recommended as it can impose order among compilation
units; so it is assumed that only one such top level type
is usually defined.)
- Compose ‘method header’ highlighting and block braces
folding.
- Do not highlight block braces whenever ‘method header’
highlighting is requested.
This bundling of ‘method headers’ and block braces for
highlighting can be traced back to Vim v5.0; however, no
comment or documentation entry conveys any justification.
For example, it is hard to discover the connection between
block braces for "while", "if", etc., statements and method
body block braces. The former behaviour can be attained in,
e.g. ~/.vim/after/syntax/java.vim:
------------------------------------------------------------
if exists("g:java_highlight_functions")
syn clear javaBlock javaInParen
syn match javaBlockOther "[{}]"
syn region javaBlock transparent matchgroup=javaBlockStart
\ start="\%(^\|^\S[^:]\+\)\@120<!{" end="}" fold
hi def link javaBlockStart javaFuncDef
hi def link javaBlockOther javaBlockStart
if exists("g:java_mark_braces_in_parens_as_errors")
syn match javaInParen contained "[{}]"
endif
endif
------------------------------------------------------------
Note: Read ‘a method header omitting a _throws_ clause’ for
every ‘method header’ appellation used above.
371bab0594
Co-authored-by: Aliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com>
Make a formal definition for normal and single-element kinds
of annotations that otherwise require for their containment
to repeat each time all syntax groups that describe element
values.
Reference:
https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-9.7902b766858
Co-authored-by: Aliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com>
runtime(java): Strive to remain compatible for at least Vim 7.0 (vim/vim#14744)
Also:
- Limit all look-behind regexp patterns.
- Cache regexp capabilities for [:upper:] and [:lower:].
d3952e8cfe
Co-authored-by: Aliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com>
runtime(java): Stop handpicking syntax groups for @javaTop (vim/vim#14727)
* runtime(java): Stop handpicking syntax groups for @javaTop
Also:
- Remove the obsolete comment for g:java_allow_cpp_keywords.
- Remove the commented out groups java\%[Debug\]StringError.
- Infer and set the preferred formatting Vim options from
the modeline.
Since vim-6-0u, non-contained syntax groups can be referred
to by using the "contains=TOP..." argument.
* Set &encoding and &termencoding to "utf-8" for test files
* Limit non-ASCII charset to [§ƒɐɘʬʭΑ-Τα-μ] for test files
06bdac1580
Co-authored-by: Aliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com>
runtime(java): Improve the recognition of the "indent" method declarations (vim/vim#14659)
There is a flaw in the current implementation that has been
exacerbated around v5.2. It lies in the recognition of all
three indentation styles simultaneously: a tab, two space,
and eight space character(s). With it, it is not uncommon
to misidentify various constructs as method declarations
when they belong to two-space indented members and other
blocks of a type and are offset at eight space characters or
a tab from the start of the line.
For example,
------------------------------------------------------------
class Test
{
static String hello() { return "hello"; }
public static void main(String[] args)
{
try {
if (args.length > 0) {
// FIXME: eight spaces.
System.out.println(args[0]);
} else {
// FIXME: a tab.
System.out.println(hello());
}
} catch (Exception e) {
throw new Error(e);
}
}
}
------------------------------------------------------------
------------------------------------------------------------
:let g:java_highlight_functions = 'indent'
:doautocmd Syntax
------------------------------------------------------------
A better approach is to pick an only indentation style out
of all supported styles (so either two spaces _or_ eight
spaces _or_ a tab). Note that tabs and spaces can still be
mixed, only the leading tab or the leading run of spaces
matters for the recognition. And there is no reason to not
complement the set of valid styles with any number of spaces
from 1 to 8, inclusively.
Please proceed with the necessary change as follows:
- rename from "indent" to "indent2" for a 2-space run;
- rename from "indent" to "indent8" for an 8-space run;
- continue to have "indent" for a tab run;
- define an "indent" variable with a suffix number denoting
the preferred amount of indentation for any other run of
spaces [1-8].
As before, this alternative style of recognition of method
declarations still does not prescribe naming conventions and
still cannot recognise method declarations in nested types
that are conventionally indented.
The proposed changes also follow suit of "style" in stopping
the claiming of constructor and enum constant declarations.
c4d0c8c812
Co-authored-by: Aliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com>
runtime(java): Improve the recognition of the "style" method declarations
- Request the new regexp engine (v7.3.970) for [:upper:] and
[:lower:].
- Recognise declarations of in-line annotated methods.
- Recognise declarations of _strictfp_ methods.
- Establish partial order for method modifiers as shown in
the MethodModifier production; namely, _public_ and
friends should be written the leftmost, possibly followed
by _abstract_ or _default_, or possibly followed by other
modifiers.
- Stop looking for parameterisable primitive types (void<?>,
int<Object>, etc., are malformed).
- Stop looking for arrays of _void_.
- Acknowledge the prevailing convention for method names to
begin with a small letter and for class/interface names to
begin with a capital letter; and, therefore, desist from
claiming declarations of enum constants and constructors
with javaFuncDef.
Rationale:
+ Constructor is distinct from method:
* its (overloaded) name is not arbitrary;
* its return type is implicit;
* its _throws_ clause depends on indirect vagaries of
instance (variable) initialisers;
* its invocation makes other constructors of its type
hierarchy invoked one by one, concluding with the
primordial constructor;
* its explicit invocation, via _this_ or _super_, can
only appear as the first statement in a constructor
(not anymore, see JEP 447); else, its _super_ call
cannot appear in constructors of _record_ or _enum_;
and neither invocation is allowed for the primordial
constructor;
* it is not a member of its class, like initialisers,
and is never inherited;
* it is never _abstract_ or _native_.
+ Constructor declarations tend to be few in number and
merit visual recognition from method declarations.
+ Enum constants define a fixed set of type instances
and more resemble class variable initialisers.
Note that the code duplicated for @javaFuncParams is written
keeping in mind for g:java_highlight_functions a pending 3rd
variant, which would require none of the :syn-cluster added
groups.
closes: vim/vim#14620a4c085a3e6
Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
runtime(java): Recognise non-ASCII identifiers (vim/vim#14543)
* runtime(java): Recognise non-ASCII identifiers
Also:
- Remove the already commented out and less general in its
definition javaFuncDef alternative.
- Stop recognising some bespoke {p,trace} debugging API.
Non-ASCII identifiers have been supported from the outset
of the Java language.
> An _identifier_ is an unlimited-length sequence of _Java
> letters_ and _Java digits_, the first of which must be a
> Java letter. An identifier cannot have the same spelling
> (Unicode character sequence) as a keyword . . . Boolean
> literal . . . or the null literal . . .
> . . . . . . . .
> Letters and digits may be drawn from the entire Unicode
> character set . . .
> . . . . . . . .
> A Java letter is a character for which the method
> Character.isJavaLetter . . . returns true. A Java
> letter-or-digit is a character for which the method
> Character.isJavaLetterOrDigit . . . returns true.
> . . . . . . . .
> The Java letters include . . . for historical reasons, the
> ASCII underscore (_) . . . and dollar sign ($) . . .
(Separate syntax tests will be written when particular parts
now touched will have been further improved.)
Reference:
https://javaalmanac.io/jdk/1.0/langspec.pdf [§3.8]
* Take on the maintenance of Java filetype and syntax files
4052474a1b
Co-authored-by: Aliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com>
runtime(java): Improve the matching of contextual keywords
- Recognise a _record_ contextual keyword.
- Recognise _non-sealed_, _sealed_, and _permits_ contextual
keywords.
- Admit _$_ to keyword characters.
- Group _abstract_, _final_, _default_, _(non-)sealed_
(apart from _(non-)sealed_, the incompossibility of these
modifiers calls for attention).
- Remove another _synchronized_ keyword redefinition.
I have also replaced a function with an expression. Before
patch 8.1.0515, it should have been declared :function! to
work with repeatable script sourcing; there is less to worry
about with an expression.
References:
https://openjdk.org/jeps/395 (Records)
https://openjdk.org/jeps/409 (Sealed Classes)
https://docs.oracle.com/javase/specs/jls/se21/html/jls-3.html#jls-3.8closes: vim/vim#144035ccdcc482e
Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
runtime(java): Recognise the inline kind of the {@return} tag (vim/vim#14284)
Also:
- Refine comment matching (javaComment{Error\ and,Start}).
- Continue rewriting regexps (prefer atom grouping with
non-capturing parens; factor out common prefixes in
alternations).
- Allow for relative paths with the _file_ attribute of
{@snippet}.
- Anticipate HTML in the @see tags.
- Match the nullary method parens in javaDocSeeTagParam.
- Improve the boundary patterns for summary sentences of
documentation.
> This sentence ends at ... or at the first tag (as defined
> below).
There are Java documentation tags (@) and there are HTML
tags (<?>) (with Markdown looming large; see JEP 467). With
block tags, e.g. @param, @return, @see, we begin another
documentation "sentence" whether or not the author has
terminated the summary sentence with a period; with
.<!-- -->, we may follow abbreviations, enumerations,
initials, (but instead consider @literal or ) _within_
the summary sentence. On the other hand, inline tags, e.g.
@code, @link, @literal, should not terminate the summary
sentence.
References:
https://bugs.openjdk.org/browse/JDK-8075778https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#firstsentencehttps://docs.oracle.com/en/java/javase/21/docs/specs/javadoc/doc-comment-spec.html8e59a7ba88
Co-authored-by: Aliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com>
runtime(java): Recognise the {@snippet} documentation tag (vim/vim#14271)
Remember that ‘code fragments are typically Java source
code, but they may also be fragments of properties files,
source code in other languages, or plain text.’ Therefore,
with these changes, markup tags are highlighted in the Java
source files (as external snippets) and in the {@snippet}
tags.
Also:
- Improve matching of the multi-line {@code} documentation
tag with any contained balanced braces.
- Recognise the {@literal} documentation tag.
- Highlight stray blanks in comments.
Related to an enhancement proposal for PCRE-like callouts
discussed at https://github.com/vim/vim/issues/11217.
References:
https://openjdk.org/jeps/413https://docs.oracle.com/en/java/javase/21/docs/specs/javadoc/doc-comment-spec.html3e72bf10a0
Co-authored-by: Aliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com>
runtime(java): Recognise string templates (vim/vim#14150)
As this is encouraged in the referenced JEPs, "to visually
distinguish a string template from a string literal, and
a text block template from a text block", the default
colours for java\%[Debug]StrTempl are made distinct from
java\%[Debug]String.
According to §3.2 Lexical Translations (JLS, c. 1996 or any
more recent version), line terminators, white space, and
comments are discarded before tokens are accepted. Since
a template expression comprises a template processor, a dot,
and a template, it may be visually appealing to break up
its head across a few lines whenever its tail already spans
multiple lines. Curiously, no allowance for it is made in
the distributed tests for OpenJDK 21; the proposed regexp
patterns take in consideration a line terminator and white
space after a dot.
References:
https://openjdk.org/jeps/430 (Preview)
https://openjdk.org/jeps/459 (Second Preview)
https://openjdk.org/jeps/465a2c65809da
Co-authored-by: Aliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com>
runtime(java): Recognise text blocks (vim/vim#14128)
Also, accept as valid the space escape sequence `\s`.
Also, consistently use the claimed `javaDebug` prefix for
syntax group definitions kept under `g:java_highlight_debug`.
Since `javaStringError` is commented out for its generality,
let's comment out `javaDebugStringError`, its copy, as well.
References:
https://openjdk.org/jeps/378https://docs.oracle.com/javase/specs/jls/se17/html/jls-3.html#jls-3.10.7Closesvim/vim#10910.
b3030b653b
Co-authored-by: Aliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com>
runtime(java): Recognise _when_ clauses in _switch_ blocks
Also:
- distinguish _yield_ when used as a contextual keyword from
when used qualified as a method or a method reference (as
can be seen in testdir/input/java_switch.java, variables
and method declarations named _yield_ will be recognised
as the namesake keyword--consider picking other names for
variables, and defining g:java_highlight_functions to have
method names painted; since _yield_ statements can have
trailing parens, they must be recognised as statements,
for only qualified _yield_ method calls are supported);
- recognise grouped _default_ _case_ labels;
- describe primitive types for _case_ labels (JLS, §14.11,
§3.10.1);
- recognise some non-ASCII identifiers (see javaLambdaDef,
javaUserLabel) (further improvement for better recognition
of identifiers will be arranged in a separate PR).
Because the arrow '->' is used in two kinds of expressions,
lambda (abstractions) and _switch_, necessary changes were
made for the recognition of either (and further improvement
touching lambda expressions will be separately arranged).
Because 'default' is used for instance method declarations
in interfaces and in _switch_ labels, necessary changes were
made for the recognition of either (and further improvement
touching method declarations will be separately arranged).
Finally, it deemed appropriate to put 'yield' in the syntax
group of javaOperator rather than javaStatement, for its
member 'var' is also another contextual keyword (e.g., this
is valid syntax: "var var = var(test.var);").
References:
https://openjdk.org/jeps/361 (Switch Expressions)
https://openjdk.org/jeps/440 (Record Patterns)
https://openjdk.org/jeps/441 (Pattern Matching for switch)
Also, add a Java specific filetype plugin for the syntax
test, so that no soft-wrapping of long indented lines occur.
Otherwise the syntax scripts would miss a few lines during
scrolling and verification of the screen dumps.
closes: vim/vim#141059ecf02cd5f
Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
Vim runtime files based on 7.4.384 / hg changeset 7090d7f160f7
Excluding:
Amiga icons (*.info, icons/)
doc/hangulin.txt
tutor/
spell/
lang/ (only used for menu translations)
macros/maze/, macros/hanoi/, macros/life/, macros/urm/
These were used to test vi compatibility.
termcap
"Demonstration of a termcap file (for the Amiga and Archimedes)"
Helped-by: Rich Wareham <rjw57@cam.ac.uk>
Helped-by: John <john.schmidt.h@gmail.com>
Helped-by: Yann <yann@yann-salaun.com>
Helped-by: Christophe Badoit <c.badoit@lesiteimmo.com>
Helped-by: drasill <github@tof2k.com>
Helped-by: Tae Sandoval Murgan <taecilla@gmail.com>
Helped-by: Lowe Thiderman <lowe.thiderman@gmail.com>
