vim-patch:8556e23: runtime(java): Provide support for syntax preview features

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

closes: vim/vim#15579

https://github.com/vim/vim/commit/8556e23ee90448f01b612d337599f6e8f86679ea

Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>

2 files changed, 39 insertions, 11 deletions

diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 7f4b4495be..8037a3bbbc 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -1692,6 +1692,22 @@ This will make the syntax synchronization start 50 lines before the first
 displayed line.  The default value is 10.  The disadvantage of using a larger
 number is that redrawing can become slow.
 
+Significant changes to the Java platform are gradually introduced in the form
+of JDK Enhancement Proposals (JEPs) that can be implemented for a release and
+offered as its preview features.  It may take several JEPs and a few release
+cycles for such a feature to become either integrated into the platform or
+withdrawn from this effort.  To cater for early adopters, there is optional
+support in Vim for syntax related preview features that are implemented.  You
+can request it by specifying a list of preview feature numbers as follows: >
+	:let g:java_syntax_previews = [430]
+
+The supported JEP numbers are to be drawn from this table:
+	`430`: String Templates [JDK 21]
+
+Note that as soon as the particular preview feature will have been integrated
+into the Java platform, its entry will be removed from the table and related
+optionality will be discontinued.
+
 
 JSON			*json.vim* *ft-json-syntax* *g:vim_json_conceal*
 					       *g:vim_json_warnings*
diff --git a/runtime/syntax/java.vim b/runtime/syntax/java.vim
index 51ef8395b9..8aa053d522 100644
--- a/runtime/syntax/java.vim
+++ b/runtime/syntax/java.vim
@@ -3,7 +3,7 @@
 " Maintainer:		Aliaksei Budavei <0x000c70 AT gmail DOT com>
 " Former Maintainer:	Claudio Fleiner <claudio@fleiner.com>
 " Repository:		https://github.com/zzzyxwvut/java-vim.git
-" Last Change:		2024 Aug 22
+" Last Change:		2024 Aug 26
 
 " Please check :help java.vim for comments on some of the options available.
 
@@ -30,6 +30,10 @@ function! s:ff.RightConstant(x, y) abort
   return a:y
 endfunction
 
+function! s:ff.IsRequestedPreviewFeature(n) abort
+  return exists("g:java_syntax_previews") && index(g:java_syntax_previews, a:n) + 1
+endfunction
+
 if !exists("*s:ReportOnce")
   function s:ReportOnce(message) abort
     echomsg 'syntax/java.vim: ' . a:message
@@ -367,9 +371,14 @@ syn match   javaSpecialChar	contained "\\\%(u\x\x\x\x\|[0-3]\o\o\|\o\o\=\|[bstnf
 syn region  javaString		start=+"+ end=+"+ end=+$+ contains=javaSpecialChar,javaSpecialError,@Spell
 syn region  javaString		start=+"""[ \t\x0c\r]*$+hs=e+1 end=+"""+he=s-1 contains=javaSpecialChar,javaSpecialError,javaTextBlockError,@Spell
 syn match   javaTextBlockError	+"""\s*"""+
-syn region  javaStrTemplEmbExp	contained matchgroup=javaStrTempl start="\\{" end="}" contains=TOP
-exec 'syn region javaStrTempl start=+\%(\.[[:space:]\n]*\)\@' . s:ff.Peek('80', '') . '<="+ end=+"+ contains=javaStrTemplEmbExp,javaSpecialChar,javaSpecialError,@Spell'
-exec 'syn region javaStrTempl start=+\%(\.[[:space:]\n]*\)\@' . s:ff.Peek('80', '') . '<="""[ \t\x0c\r]*$+hs=e+1 end=+"""+he=s-1 contains=javaStrTemplEmbExp,javaSpecialChar,javaSpecialError,javaTextBlockError,@Spell'
+
+if s:ff.IsRequestedPreviewFeature(430)
+  syn region javaStrTemplEmbExp	contained matchgroup=javaStrTempl start="\\{" end="}" contains=TOP
+  exec 'syn region javaStrTempl start=+\%(\.[[:space:]\n]*\)\@' . s:ff.Peek('80', '') . '<="+ end=+"+ contains=javaStrTemplEmbExp,javaSpecialChar,javaSpecialError,@Spell'
+  exec 'syn region javaStrTempl start=+\%(\.[[:space:]\n]*\)\@' . s:ff.Peek('80', '') . '<="""[ \t\x0c\r]*$+hs=e+1 end=+"""+he=s-1 contains=javaStrTemplEmbExp,javaSpecialChar,javaSpecialError,javaTextBlockError,@Spell'
+  hi def link javaStrTempl	Macro
+endif
+
 syn match   javaCharacter	"'[^']*'" contains=javaSpecialChar,javaSpecialCharError
 syn match   javaCharacter	"'\\''" contains=javaSpecialChar
 syn match   javaCharacter	"'[^\\]'"
@@ -441,11 +450,16 @@ if exists("g:java_highlight_debug")
   syn match   javaDebugSpecial		contained "\\\%(u\x\x\x\x\|[0-3]\o\o\|\o\o\=\|[bstnfr"'\\]\)"
   syn region  javaDebugString		contained start=+"+ end=+"+ contains=javaDebugSpecial
   syn region  javaDebugString		contained start=+"""[ \t\x0c\r]*$+hs=e+1 end=+"""+he=s-1 contains=javaDebugSpecial,javaDebugTextBlockError
-  " The highlight groups of java{StrTempl,Debug{,Paren,StrTempl}}\,
-  " share one colour by default. Do not conflate unrelated parens.
-  syn region  javaDebugStrTemplEmbExp	contained matchgroup=javaDebugStrTempl start="\\{" end="}" contains=javaComment,javaLineComment,javaDebug\%(Paren\)\@!.*
-  exec 'syn region javaDebugStrTempl contained start=+\%(\.[[:space:]\n]*\)\@' . s:ff.Peek('80', '') . '<="+ end=+"+ contains=javaDebugStrTemplEmbExp,javaDebugSpecial'
-  exec 'syn region javaDebugStrTempl contained start=+\%(\.[[:space:]\n]*\)\@' . s:ff.Peek('80', '') . '<="""[ \t\x0c\r]*$+hs=e+1 end=+"""+he=s-1 contains=javaDebugStrTemplEmbExp,javaDebugSpecial,javaDebugTextBlockError'
+
+  if s:ff.IsRequestedPreviewFeature(430)
+    " The highlight groups of java{StrTempl,Debug{,Paren,StrTempl}}\,
+    " share one colour by default. Do not conflate unrelated parens.
+    syn region javaDebugStrTemplEmbExp	contained matchgroup=javaDebugStrTempl start="\\{" end="}" contains=javaComment,javaLineComment,javaDebug\%(Paren\)\@!.*
+    exec 'syn region javaDebugStrTempl contained start=+\%(\.[[:space:]\n]*\)\@' . s:ff.Peek('80', '') . '<="+ end=+"+ contains=javaDebugStrTemplEmbExp,javaDebugSpecial'
+    exec 'syn region javaDebugStrTempl contained start=+\%(\.[[:space:]\n]*\)\@' . s:ff.Peek('80', '') . '<="""[ \t\x0c\r]*$+hs=e+1 end=+"""+he=s-1 contains=javaDebugStrTemplEmbExp,javaDebugSpecial,javaDebugTextBlockError'
+    hi def link javaDebugStrTempl	Macro
+  endif
+
   syn match   javaDebugTextBlockError	contained +"""\s*"""+
   syn match   javaDebugCharacter	contained "'[^\\]'"
   syn match   javaDebugSpecialCharacter contained "'\\.'"
@@ -471,7 +485,6 @@ if exists("g:java_highlight_debug")
 
   hi def link javaDebug			Debug
   hi def link javaDebugString		DebugString
-  hi def link javaDebugStrTempl		Macro
   hi def link javaDebugTextBlockError	Error
   hi def link javaDebugType		DebugType
   hi def link javaDebugBoolean		DebugBoolean
@@ -580,7 +593,6 @@ hi def link javaSpecial			Special
 hi def link javaSpecialError		Error
 hi def link javaSpecialCharError	Error
 hi def link javaString			String
-hi def link javaStrTempl		Macro
 hi def link javaCharacter		Character
 hi def link javaSpecialChar		SpecialChar
 hi def link javaNumber			Number