Usage Introduction
As with other command line processing libraries there are three stages to command line processing; the definition stage, the parsing stage and the interrogation stage.
The other important facility provided by command line processing libraries is error reporting and usage help.
Definition Stage
JewelCli uses an annotated Java interface definition to describe the Command Line Interface in a declarative style. The main annotation is the Option Annotation
Option Annotation
The option annotation is used to mark a method as an option method, and to give additional information to JewelCli. In JewelCli, defining an option is as simple as:
public interface MyExample { @Option String getMyOption(); }
This produces a Command Line with a single option --myOption which takes a single string value
Short Name
It is often convenient to allow your users to specify options using a short hand notation. JewelCli supports this through an argument to the Option annotation:
public interface MyExample { @Option(shortName="m") String getMyOption(); }
This produces a Command Line with a single option, however, the option may be specified using either --myOption or -m
Multiple short names may be defined for each option
public interface MyExample { @Option(shortName={"m","x"}) String getMyOption(); }
Now the option may be specified using either --myOption, -m or -x
Long Name
Sometimes the option name does not make a very good method name, or vice-versa, in this situation the longName argument can be used:
Multiple long names may be defined for each option
public interface MyExample { @Option(longName="alternateName") String getMyOption(); }
This produces a Command Line with a single option --alternateName
Help Request
Many applications have an option which will print usage help. JewelCli supports this with the helpRequest argument:
public interface MyExample { @Option String getMyOption(); @Option(helpRequest = true) boolean getHelp(); }
If --help is specified, an exception will be thrown during parsing, with the usage help in the exception message. This will occur even if other argument validation problems are present.
Return Type
The return type of the option method describes what arguments the option takes. There are four general classes of return type; boolean, other primitive, Class, generic List.
boolean
A boolean return makes the option behave as a flag: an option that takes no arguments and is only optionally specified.
other primitive
All of the java primitive types, and there Object equivalents, are supported, numbers will automatically be parsed.
Class
Any class which has a constructor that takes a single java.lang.String argument can be used as a return type.
List
A list will produce an option that takes a variable length list of arguments. The generic type of the list will define the type of each individual argument in the list.
public interface MyExample { @Option List<Integer> getMyOption(); }
This produces a Command Line with a single option --myOption that takes a list of integers, for example --myOption 1 2 3 4
Optional Options
There are two main ways to produce an optional option using jewelCli, one is using a boolean query method, the other is by specifying a (possibly null) default value.
One way to produce an optional option with JewelCli has been to define it as a flag by using a boolean return type. Some optional options need to take, arguments so another two facilities are provided. To make an option optional, define a bean style "is" method with the same suffix as the getter for the option:
public interface MyExample { @Option List<Integer> getMyOption(); boolean isMyOption(); }
Another way to have an optional option is to define a default value for the option. If the option is not specified JewelCli will use the specified default value.
public interface MyExample { @Option(defaultValue="3") int getMyOption(); @Option(defaultValue={"3","4","5"}) List<Integer> getMyList(); }
If you need the default value to be null you can do it like this:
public interface MyExample { @Option(defaultToNull=true) Integer getMyOption(); }
Unparsed arguments
In some applications, the last arguments on the command line are not arguments to any option, but are arguments to the central function of the program itself. The Unparsed Annotation annotation is used to mark a method as the accessor for these unparsed options.
The Unparsed method may use any of the return types that normal Option methods may, with the exception of the boolean (flag) return type
public interface MyExample { @Unparsed List<Files> getFiles(); }
Option Inheritance
Interface inheritance is supported. Options defined in a super interface will work in the same way as options defined directly in the interface.
public interface MySuperExample { @Option String getMySuperOption(); } public interface MySubExample extends MySuperExample { @Option String getMySubOption(); }
MySubExample will produce a Command Line with a two options --mySuperOption and --mySubOption
Parsing Stage
JewelCli's parsing stage is very simple. Use the CliFactory to produce an instance of your annotated Java interface.
public static void main(String [] args) { try { MyExample result = CliFactory.parseArguments(MyExample.class, args); [...] } catch(ArgumentValidationException e) { [...] } }
- Error Handling
If any errors are found during parsing an ArgumentValidationException is thrown. The message of the ArgumentValidationException can be displayed to the user to inform them of the problem.