hyphenType is...

hyphenType is a Java library to make it easy for programmers to parse command line interface (CLI) arguments.

hyphenType is different from other solutions in that it parses command line arguments into an object. Instead of having to specify parsing arguments using a library, a programmer needs only to write a simple annotated Java interface and hyphenType will do the rest.

Feature list

You can add a number of documentation formatters to your CLI. The standard one, for instance, even formats the output to have a maximum number of columns.

Short arguments can coexist with long arguments

-h can be declared to be the same as --help

Short arguments can be combined

-xyz is the same as -x -y -z

Documentation can be added in Java annotations or external resource bundles

UTF-8 resource bundles

Easy to edit for non-European languages.

Built-in tool to generate configuration

Configurable input channels

If a mandatory argument was not given as CLI argument, hyphenType can ask the user to type the argument in the command line, or even show a dialog window.

Return codes

hyphenType can manage return codes (the number n in System.exit(n)), converting enumerations into integers. Also, it can convert exceptions into a certain return code.

Validators

Validation of CLI arguments can be made using built-in configurable validators. You can also easily create your own validator.

Advanced unit testing

Unit testing parsing or the application that reads parsing.

Generate usage documentation

Unit tests can easily write text files containing the result of executing your program, simulating a terminal. The outputs on this pages were all automatically generated using this feature.

A very fast start

Let's say that your application expects to receive only two arguments from the command line and ignore all other arguments. Both arguments should be plain strings. Let's take a look at a simple class that solves this problem using hyphenType:

Now if you run XApp as any ordinary stand alone Java application, the results will be:

_> java example.case1.XApp aaa bbb
aaa
bbb

_> java example.case1.XApp aaa bbb ccc ddd
aaa
bbb

What happens here is that we do not need to directly deal with the arguments received. In other words, the main class we wrote does not need to handle the standard String[] args. Instead, the arguments are read by hyphenType and transformed into simple Java objects.

As you may have already noticed, all arguments after the second were simply ignored.

Command line documentation

Now what if we want to show a help message every time we do not receive anything as arguments? We will only need to change our application a little bit:

_> java example.case3.XApp -h
usage: program [options] [a] [b]
Prints argA and argB to stdout.
Arguments
a This is a short description of argument a.
b This is the description of argument b. This is a very long
description to demonstrate the automated formatting
capability of hyphenType. As you can see, the output will
have line breaks that guarantee that text will only go until
a certain column, which ensures that documentation will look
great even in low resolution terminals.
Options
-h, --help Shows this help message

We can also notice that we added documentation to the two options. So hyphenType will automatically print the documentation and format long lines so it looks good in low resolution terminals.

_> java example.case3.XApp --help
usage: program [options] [a] [b]
Prints argA and argB to stdout.
Arguments
a This is a short description of argument a.
b This is the description of argument b. This is a very long
description to demonstrate the automated formatting
capability of hyphenType. As you can see, the output will
have line breaks that guarantee that text will only go until
a certain column, which ensures that documentation will look
great even in low resolution terminals.
Options
-h, --help Shows this help message

Note that so far we did not call any class of hyphenType directly. The only references to hyphenType were the SimpleArgument annotation and extending Options and StandAloneAppWrapper.

Another interesting thing to notice is that the main method is not static. In fact, adding a static modifier to this method will not change the outcome. Internally, hyphenType will check whether the main method is static or not. If it is static, then it will simply call the method. If the method is not static, then hyphenType will first create an instance of the class (in the example above, an instance of XApp) and call the main method from that instance.

Where to go next?

At this point you already know the basic idea behind hyphenType: you need to write an options interface and hyphenType will use it to both understand how command line arguments should be parsed, and to create an object that will give you easy access to the parsed data.

But hyphenType can parse arguments that are more complex then those of the examples we just saw. For instance, there are ways to tell hyphenType to create lists or parse arguments to custom classes.

We designed hyphenType to be not only a command line parsing tool, but also a tool to help unit test and document stand alone applications.