JEP 293: Guidelines for JDK Command-Line Tool Options
stuart.marks at oracle.com
Wed Jul 13 20:12:54 UTC 2016
On 7/7/16 12:16 PM, mark.reinhold at oracle.com wrote:
> New JEP Candidate: http://openjdk.java.net/jeps/293
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
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
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.
Just to clarify, is the = separator supported here as well, implying that the
following would be permitted?
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.
More information about the core-libs-dev