remkop / picocli Goto Github PK

Add convenience methods that parse command line arguments, and execute a Callable on success, or print a usage message to the console and exit on failure.

That would give more fine grained control & allow splitting a comma-separated list of values

option parameter name: use field name or use field type (class SimpleName)?
option and parameter separated by space or by '='?

The decode method accepts not just decimal-format strings, but also hex, octal etc.
Also works for Long, Short and Byte.

Current full usage is:

public static void main(String... args) {
   try {
       MyClass myClass = CommandLine.parse(new MyClass(), args);
       if (myClass.help) {
           CommandLine.usage(MyClass.class, System.out);
       } else if (myClass.version) {
           System.out.println("MyProgram version 1.2.3");
       } else {
           runProgram(myClass);
       }
   } catch (ParameterException ex) { // command line arguments could not be parsed
       System.err.println(ex.getMessage());
       CommandLine.usage(MyClass.class, System.err);
   }
}

Can we reduce the try/catch boilerplate with a convenience method?

public static void main(String... args) {
   MyClass myClass = CommandLine.parseOrPrintUsage(new MyClass(), System.err, args);
   if (myClass == null) { // parsing failed
       return; 
   }
   if (myClass.help) {
       CommandLine.usage(MyClass.class, System.out);
   } else if (myClass.version) {
       System.out.println("MyProgram version 1.2.3");
   } else {
       runProgram(myClass);
   }
}

Currently array fields (Params or option) are always initialized to a new array instance, regardless of what the current value is.

Collections however are only instantiated when they are initially null, otherwise values are added to the original collection instance.

This asymmetry is undesirable.

Note: we may want to support map-like options like -Da=b -Dx=y. Behaviour for map-like containers should be consistent with arrays and collections.

For example, currently for a TimeUnit, "DAY" is valid, but "Day" or "day" results in a ParameterException. More lenient parsing would be easier for users.

Shorter and clarifies usage.

http://bailando.berkeley.edu/papers/psb03.pdf

Example

@Option(names="-words") String[] words;
@Option(names="-v") boolean verbose;

Given command line args -words a b c -v,
the current implementation interprets the "-v" as one of the parameters for word.

An application using picoCLI should be able to designate whether arguments following the option should be greedily consumed or not. This is what the varargs attribute is for. The default for @option is false (as it should be), but the implemented behavior is different.

@option(name = "-p", description = "A path") public String p = null;

value must be "a-p"

When parsing varargs arrays, we add values until we encounter an option.
Do we correctly recognize a clustered short option group as an option?

Example:

usage: nc [-46CDdhklnrtUuvz] [-I length] [-i interval] [-O length]
          [-P proxy_username] [-p source_port] [-s source] [-T ToS]
          [-V rtable] [-w timeout] [-X proxy_protocol]
          [-x proxy_address[:port]] [destination] [port]

required options: show '*' in front of option name, or print 'Required' on 2nd line or print '(Required)' before or after the option description

Ideas:

• @option(..., i18nKey="myKey") -look up myKey in ResourceBundle
• @option(..., description="A b c d") -look up A_b_c_d in ResourceBundle
• look up fully qualified field name in ResourceBundle

The default Columns in a TextTable have a fixed predefined width.
The 3rd column is 24 characters wide by default. Consider adjusting this to a smaller value if all values are less than this width, or if 80-90% of values are less than this width.

Potential drawback is that it may be less predictable for applications to write their description lines in a way that lays out nicely.

This allows positional parameters to be assigned to separate fields with separate types.
usage example: <program> "header text" file1 23 file2 43

class Args {
  @Parameter(position=0, helpText="header text")       String headerText;
  @Parameter(position=1, helpText="binary input file") File binaryInput;
  @Parameter(position=2, helpText="record length")     int recordLength;
  @Parameter(position=3, helpText="text output file")  File output;
  @Parameter(position=4, helpText="max output lines")  int maxLines;
  ...
}

Definition:

@Parameter {
  int position;
  boolean required;
  String helpText;
  boolean hidden;
}

(Introduce a "positional parameters in progress" field?)

list of java CLI parsers.

• Airline
  • Active Fork: https://github.com/rvesse/airline
• argparse4j
• argparser
• args4j
• clajr
• cli-parser
• CmdLn
• Commandline
• DocOpt.java
• dolphin getopt
• DPML CLI (Jakarta Commons CLI2 fork)
• Dr. Matthias Laux
• Jakarta Commons CLI
• jargo
• jargp
• jargs
• java-getopt
• JCLAP
• jcmdline
• jcommander
• jcommando
• jewelcli (written by me)
• JOpt simple
• jsap
• naturalcli
• Object Mentor CLI article (more about refactoring and TDD)
• parse-cmd
• ritopt
• Rop
• TE-Code Command

How to make this customizable?

• ideally with annotation attribute so it is purely declarative. Use hidden attribute?
• Do we need separate attributes for inclusion/exclusion from header and from details?

Ideally programmers should be able to specify a UsageFormatter interface implementation that gives complete freedom over the usage message layout.

Expose picoCLI usage layout functionality so custom formatters can reuse it.

Customizable:

• "Usage" line: mention option short form with [-v] optional and mandatory elements, or a generic [OPTIONS] [PARAMETERS]
• option columns: show in declared order or sort short options first
• option rows: sort alphabetically or show in declared order
• required options: show '*' in front of option name, or print 'Required' on 2nd line or print '(Required)' before or after the option description
• option parameter name: use field name or use field type (class SimpleName)
• option and parameter separated by space or by '='
• option parameter default value: print 'Default: VALUE' on 2nd line or print '(default: VALUE)' after the option description

"Usage" line: mention option short form with [-v] optional and mandatory elements, or a generic [OPTIONS] [PARAMETERS]

option parameter default value: print 'Default: VALUE' on 2nd line or print '(default: VALUE)' after the option description

A CommandLine instance may be reused to parse multiple command line arrays. Ensure any state in the Interpreter is reset to the default at the start of the parse() method.
Especially if a "positional parameters in progress" field is introduced for the proposed @parameter annotation.

Remove Default option renderer, parameter renderer, layout and minimal option renderer. Replace with factory methods on Help.

See argparse4j

enable if { "ja", "zh", "ko" }.contains(Locale.getDefault().getLanguage())

Apply to Unicode characters having East Asian Width property Wide/Full/Ambiguous.

• options vs positional parameters
• standalone options are booleans
• options can take parameters
• parameters are strongly typed
• built-in type converters
• registering custom type converters
• option short form
• short form options can be grouped
• last option in a short option group can take a parameter
• varargs
• optional parameters
• use arity to specify number of required parameters
  (Only allows min, consider supporting max also)
• option parameters are separated from option name or attached with configurable separator '='