Fork me on GitHub

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.

hyphenType is licensed under the GNU Lesser General Public License (LGPL), therefore you can use this tool free of charge, even commercially.

This is the documentation site. Our GitHub site is https://github.com/aamm/hyphenType/.

Please use our mailing list to contact us.

Feature list

  • Arguments are parsed into Java objects
  • Easy --help

    Simply annotate a Java interface with descriptions and call a method.

  • Documentation formatters

    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:

package example.case1;

import org.hyphenType.wrapper.StandAloneAppWrapper;

public class XApp extends StandAloneAppWrapper {

    public void main(XOpt opt) {
        System.out.println(opt.argA());
        System.out.println(opt.argB());
    }
}

The source code of the interface XOpt is:

package example.case1;

import org.hyphenType.datastructure.Options;
import org.hyphenType.datastructure.annotations.SimpleArgument;

@SuppressWarnings("unchecked")
public interface XOpt extends Options {

    @SimpleArgument(index = 0)
    public String argA();

    @SimpleArgument(index = 1)
    public String argB();
}

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:

package example.case2;

import org.hyphenType.wrapper.StandAloneAppWrapper;

public class XApp extends StandAloneAppWrapper {

    public void main(XOpt opt) {
        if (opt.argA() == null) {
            opt.printDocumentation();
            return;
        }
        System.out.println(opt.argA());
        System.out.println(opt.argB());
    }
}

The opt object not only comes with the values of the arguments, but can also output a documentation on how to call your program.

Adding a --help option

What if we want to add some interesting message that actually explains what our simple program does?

We need only to change the interface XOpt.

package example.case2;

import org.hyphenType.datastructure.Options;
import org.hyphenType.datastructure.annotations.ArgumentsObject;
import org.hyphenType.datastructure.annotations.SimpleArgument;

@SuppressWarnings("unchecked")
@ArgumentsObject(description = "Prints argA and argB to stdout.")
public interface XOpt extends Options {

    @SimpleArgument(index = 0)
    public String argA();

    @SimpleArgument(index = 1)
    public String argB();
}

So now if we try to run our application again we will see:

_> java example.case2.XApp
usage: program [argA] [argB] 

Prints argA and argB to stdout.

Arguments




Options

What if we want to show a help message only where there is an argument -h or --help, which is a standard followed by several command line tools?

Again, we will only need add and change a few lines of source code. We need to add an extra method to our interface:

package example.case3;

import org.hyphenType.datastructure.Options;
import org.hyphenType.datastructure.annotations.ArgumentsObject;
import org.hyphenType.datastructure.annotations.Option;
import org.hyphenType.datastructure.annotations.SimpleArgument;

@SuppressWarnings("unchecked")
@ArgumentsObject(description = "Prints argA and argB to stdout.")
public interface XOpt extends Options {
    
    @Option(names = { "h", "help" }, description = "Shows this help message")
    boolean h();
    
    @SimpleArgument(index = 0, name = "a", description = "This is a short description of argument a.")
    public String argA();
    
    @SimpleArgument(index = 1, name = "b", description = "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.")
    public String argB();
    
}

And change one line of our class:

package example.case3;

import org.hyphenType.wrapper.StandAloneAppWrapper;

public class XApp extends StandAloneAppWrapper {

    public void main(XOpt opt) {
        if (opt.h()) {
            opt.printDocumentation();
            return;
        }
        System.out.println(opt.argA());
        System.out.println(opt.argB());
    }
}

Let's run it again. This time, passing the arguments -h or --help:

_> 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.

Check the menu on the left for more resources regarding hyphenType.