jbang group-id:artifact-id:version call syntax should offer selecting the main class in the referenced jar file

[lukaseder]

Describe the solution you'd like

I'd like to be able to run:

jbang org.jooq:jooq:3.15.4 --class org.jooq.ParserCLI [args...]

There are several classes containing a main() method, and none of them are more relevant than the other, so the manifest doesn't contain them.

[lukaseder]

(Could be that this is already possible? But I couldn't find it from the docs or jbang --help output)

[quintesse]

Can't really test it right now because I don't have a JAR with multiple mains at hand, but can you try with the --main option?

[lukaseder]

Ah yes, that does the trick, and it's even documented here: https://www.jbang.dev/documentation/guide/latest/usage.html#running-jars

I think I've tried --main but placed it after the GAV. Is that worth mentioning in the --help output, or would that make --help too crowded?

[maxandersen]

Everything that comes after the "runnable" thing is arguments to your own main.

Not sure how to make it more explicit in the help ?

[lukaseder]

A section in Other: perhaps?

[quintesse]

Yeah, same thing happened to my wife, she didn't understand that either and thought it was a bug in JBang. Thing is that I'm not sure she would have read the --help so thoroughly to have noticed a remark like that in the Other: section :-) Perhaps something more obvious like a: IMPORTANT: All JBang flags must appear before the name of the program! Any that appear after are considered arguments to the program somewhere at the top of the help output.

[lukaseder]

Thing is that I'm not sure she would have read the --help so thoroughly to have noticed a remark like that in the Other: section :-)

Different types of documentation for different audiences... I clearly haven't read the website doc thoroughly enough.

IMPORTANT: All JBang flags must appear before the name of the program! Any that appear after are considered arguments to the program somewhere at the top of the help output.

That sounds reasonable. To me, the various argument styles seem a bit inconsistent. The usage claims:

jbang [-hV] [--verbose | --quiet] [-o | [--fresh]] [COMMAND]

So here, we can clearly see that all flags are located before the command, but then:

jbang edit --open=code --live hello.java

There are flags located after the command edit and before the Java program, whereas with these:

jbang hello.java [args...]
jbang gavsearch@jbangdev [args...]
jbang group-id:artifact-id:version [args...]

There is no such thing as a command (implicit run). I mean, in hindsight, it's logical to place --init before the GAV, because everything after the GAV can only be parameters for the jar file itself...

[quintesse]

So here, we can clearly see that all flags are located before the command, but then:

The issue here is that jbang --help doesn't actually tell you that doing jbang <scriptOrFile> is the same as jbang run <scriptOrFile>. In fact it says:

  or  jbang hello.java [args...]
        (to run a .java file)

which might, wrongly, suggest that hello.java is what the [COMMAND] in jbang [-hV] [--verbose | --quiet] [-o | [--fresh]] [COMMAND] stands for.

So perhaps we should:

1. Give at least one example with jbang run, to show that's what the command is called
2. Make sure that in the examples without run it's made clear that the command is still implicitly run

Hopefully that would make it more obvious that if you want to know more about how to run code you'd have to do jbang run --help.

[lukaseder]

Hopefully that would make it more obvious that if you want to know more about how to run code you'd have to do jbang run --help.

Aah, good to know! It would not have occurred to me to look for that command, so perhaps, since you already use [args...] as a notation for optional args, how about:

  or  jbang [run] hello.java [args...]
        (to run a .java file)
  or  jbang [run] gavsearch@jbangdev [args...]
        (to run a alias from a catalog)
  or  jbang [run] group-id:artifact-id:version [args...]
        (to run a .jar file found with a GAV id)

[maxandersen]

Adding the [run] makes it "correct" but now no longer copy/pasteable.... I get what you are saying but ...gah. it nags me to have to make the explanation more complex :)

Maybe:

jbang --help
jbang is a tool for building and running .java/.jsh scripts and jar packages.
Usage: jbang [-hV] [--verbose | --quiet] [-o | [--fresh]] [COMMAND]

  jbang init hello.java [args...]
        (to initialize a script)
  or  jbang edit --open=code --live hello.java
        (to edit a script in IDE with live updates)
  or  jbang hello.java [args...]
        (to run a .java file)
  or  jbang gavsearch@jbangdev [args...]
        (to run a alias from a catalog)
  or  jbang group-id:artifact-id:version [args...]
        (to run a .jar file found with a GAV id)

To get more help on how to run: 

jbang run --help

?

[lukaseder]

What's the likelihood of someone being able to copy-paste hello.java, gavsearch@jbangdev or group-id:artifact-id:version verbatim?

[quintesse]

What's the likelihood

Indeed.

I'd even suggest:

  or  jbang run hello.java [args...]
        (to run a .java file)
  or  jbang hello.java [args...]
        (to do the same but shorter)
  or  jbang [run] gavsearch@jbangdev [args...]
        (to run a alias from a catalog)
  or  jbang [run] group-id:artifact-id:version [args...]
        (to run a .jar file found with a GAV id)

We can also change the command line parser to accept [run] 😁

[maxandersen]

Your suggestion work @quintesse