Fork me on GitHub

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();
}

Optional unparsed arguments

Optional Unparsed arguments are supported by the same method as normal Option options:

public interface MyExample
{
  @Unparsed
  List<Files> getFiles();

  boolean isFiles();
}

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.

Interogation Stage

JewelCli's interogation stage is even simpler than the parsing stage. The parsing stage creates an instance of your annotated interface populated with the processed command line, all that is left is for you to use it!