JEP 293: Guidelines for JDK Command-Line Tool Options

[Stuart Marks]

On 7/7/16 12:16 PM, mark.reinhold at oracle.com wrote:
> New JEP Candidate: http://openjdk.java.net/jeps/293

Hi Jon,

Good writeup and rundown of the issues.

I have a few questions to raise.

     options can allow an argument to be provided

This describes an option with an optional argument. I recommend disallowing or 
at least strongly discouraging this, as it leads to ambiguities in options 
parsing. For example, suppose <value> is optional:

     cmd --example-option <value>

Suppose we have a case where the value begins with a minus and it happens to 
look like a valid option:

     cmd --example-option -l

Is -l the argument to --example-option, or is it the separate -l option? One 
could define a disambiguation rule, but this doesn't seem like a very good idea. 
It will be confusing at best.

Suppose what follows isn't a valid option:

     cmd --example-option -x

There's no ambiguity here, at least not yet; "-x" would the argument for 
--example-option. But suppose a -x option were added in a later version of the 
tool. This could introduce an ambiguity and potential incompatibility with 
existing scripts.

     Single character options may be grouped into a single token. For
     example, if -a and -b are single character options, they may be
     specified together on the command line as -ab.

This might be reasonable for greenfield tools that support only "pure" GNU-style 
options and not any legacy JDK options. But for tools that support single-minus 
long options, such as "-cp", "-version", and so forth, this introduces a bunch 
of weirdness if not outright ambiguity.

For example, suppose an existing tool supports the -cp option, and it also 
supports -c and -p. Then -cp would mean --class-path, but -pc means -p -c. Given 
some other option like -l, then -cpl would mean -c -p -l. But if one wanted to 
remove the -l option, one couldn't simply remove the "l", since that would 
result in "-cp", yielding --class-path instead of -c -p.

This is acknowledged a few paragraphs later,

     Some forms on the command-line may be ambiguous; tools may try and be
     clever to disambiguate such cases. In general, tools are encouraged not
     to support combinations which might be ambiguous, and users are encouraged
     not to use forms which might be ambiguous. For example, tools which support
     the old short form option -cp for classpath may choose not to support both
     -c and -p as single-character forms for new options.

I think the recommendation should be stronger. I'd advise against tools trying 
to be clever; this leads directly to inconsistency and confusing behavior.

If users are discouraged from using ambiguous forms, maybe we shouldn't allow 
potentially ambiguous forms in the first place.

I observe that -p is the recommended short form for --module-path. Note that 
this takes an argument. So -pc would set the module path to "c". Hm.

An alternative restriction would be to disallow single-letter option grouping in 
cases where one of the options takes an argument.

     The use of -X as a prefix to indicate "non-standard" options will be
     discontinued for new options, although command-line help may continue to
     draw a distinction between more commonly used options and those for
     advanced use.

Is there a replacement convention? Sometimes it's useful to have "hidden" or 
diagnostic or debugging options that aren't supported, subject to change, etc. I 
thought the -X prefix was used for things like that. But if not -X, should there 
be something else?

     Given the existing support for -cp as a short form for -classpath, a
     single character form will not be introduced.

Is there a recommendation for new tools? Clearly --class-path should be 
supported, but what about a short form? One could use "-cp" but this brings in 
the grouping ambiguity issues into brand-new tools, almost implying that there 
will never be any tools with pure-GNU option syntax. (But maybe that's OK.)

On the other hand, I'm not sure what a reasonable single-letter option would be. 
Somebody would have to examine the existing tools to see if something like -c or 
-C is available.

     --add-reads <module>=<target-module>(,<target-module>)*

Just to clarify, is the = separator supported here as well, implying that the 
following would be permitted?

     --add-reads=modname=targetmod1,targetmod2

I don't think this is ambiguous; it merely looks a bit odd.

--

In summary, my two main issues are 1) options with optional arguments; and 2) 
grouping of single-letter options. I'd like to see these disallowed, or at the 
very least a stronger recommendation against them.

Thanks,

s'marks