jbang
jbang copied to clipboard
jbangdev
Java 18 Snippet support
JBang extracts snippet code by id and run it. How about jbang --snippet demo App.java ? I can add run icon for snippet in IDEA and invoke JBang to run the snippet.
JEP 413: Code Snippets in Java API Documentation https://openjdk.java.net/jeps/413
Programmer's Guide to Snippets https://docs.oracle.com/en/java/javase/18/code-snippet/index.html
You mean like a variation of .md support to extract code ?
First, it cannot be jbang App.java --snippet demo as then --snippet demo are arguments to App.java
It would need to be something before App.java, i.e. jbang --snippet demo App.java
btw. reading the jep it seems it is not id but region that is used for giving a name?
But how would we reliably find those snippets? look for "{@snippet .*}" and then parse out file/region ?
@maxandersen my fault, and it should be jbang --snippet demo App.java :) @snippet has id and language tags, and it's useful for JBang because JBang has Java, Kotlin and Groovy support now. file tag is not necessary, and developers can use JBang to run directly.
How about line:11 for anonymous snippet? almost like jbang --snippet line:11 App.java, JBang should parse the snippet around the line 11. It's good for IDE integration, and vim user can call JBang to run snippet too without plugin support.
Maybe as a special syntax for jbang -c @snippet:myid:App.java ?
That currently implies it's done via jshell.
But it avoids introducing yet another concept.
jbang -c @snippet:myid:App.java is nice :) I'm not sure line number style good or not, and a Neovim user talked to me, and they almost use Command and KeyMap to execute almost everything. Move the cursor to snippet, and invoke :JBang to execute the snippet. I think it's not necessary to use Lua to parse snippet id and context information, then call jbang -c @snippet:myid:App.java command in Neovim plugin. line number style is also good for markdown to run the snippet.
JBang can parse all snippets and record snippet's line range, then match line number to run the snippet.
The ide side is the easy part :)
It's the activation and parsing on jbang side that is the challenge here.
Make the parsing happen and we can figure out exact way of hooking it up after that.
You wanna take a stab at the parsing and grabbing right code for the snippet ?
Implementing this as definitely a possibility and does make it somewhat easier. We do have to take care with the format of that special reference though:
- we need to make sure it's not ambiguous with other syntaxes we support, eg: aliases with
@, GAVs with multiple:and URLs with:as well - it must work with the other formats as well, not only
@snippet:id:File.javabut also@snippet:id:http://url/to/File.javaor@snippet:id:classpath:/some/File.java
(The second item should be easy enough by creating something like a SnippetResourceResolver which strips the @snippet:id: from the resource reference and then passes the rest on to other resolvers)
Another thing to take into account is that snippets can be external files!
The ide side is the easy part :)
It's the activation and parsing on jbang side that is the challenge here.
Yes, IDE side is very easy, no parse at all, and just grab PsiSnippetDocTag type, and mark it with JBang icon.
will these snippets have full imports/classnames? without it they won't run much ?
Not sure now. In IDEA, if you want to use Language Injection feature, and snippet should contain full imports, class name, otherwise snippet code will be marked as error.
will these snippets have full imports/classnames? without it they won't run much ?
AFAIK the snippets should be compilable and testable, otherwise you could just stick with the old <code> tags.
The problem we might have is that dependencies aren't part of the snippets.
But I'm assuming you can literally put //DEPS comments inside the snippets.
And you can put them in the "hidden" part if you don't want them to show up in the generated docs.
Yeah, at last in the external ones: https://openjdk.java.net/jeps/413#External-snippets
But there's this explanation in the JEP:
For inline snippets, especially those that are not a full compilation unit, it will be up to the test infrastructure to wrap the code fragment in a full compilation unit so that it can be compiled and possibly run.
So inline snippets don't need to be fully contained.
I could imagine that those fragments could be seen as inheriting the package and imports from the enclosing file, but that's not defined by the spec.
I build a demo with JBang IntelliJ IDEA plugin. Now I use File.createTempFile("Temp",".java"); to create a temp file, then execute jbang /var/11234/Temp1w34w34.java
Nice.
that's IntelliJ specific though. We wanna avoid doing one-IDE only features.
Anything preventing it being done as a jbang pr so we enable the ability in jbang to target snippets in .java?
@linux-china where can I find the demo btw? I thought you added it to jbang-idea but not seeing any pull request/commits related to it?
It's in my forked repository, and not merged yet. https://github.com/linux-china/jbang-idea/blob/main/src/main/kotlin/dev/jbang/idea/run/JavaSnippetLineMarkerProvider.kt
The best solution is that JBang supports snippet by default.