underline

underline is a command-line parser for Java. It allows for creating command-line programs with a Git-like interface. It is lightweight and has no dependencies to external libraries (“no strings attached”). underline supports Java 1.6 and higher.

The library is really low-level but extremely flexible. There are a number of alternatives (such as JCommander or Apache Commons CLI) but underline enables you to fully control how your command-line arguments are parsed and handled. If you're stuck with one of the existing libraries and need more flexibility then underline may be the right tool for you.

Download

If your application's build is based on Maven add the following lines to your pom.xml:

<dependency>
    <groupId>de.undercouch</groupId>
    <artifactId>underline</artifactId>
    <version>1.0.0</version>
</dependency>

If you use Gradle add the following to your build.gradle:

dependencies {
    compile 'de.undercouch:underline:1.0.0'
}

Usage

Specify options using annotations.

@OptionDesc(longName = "help", shortName = "h",
    description = "display this help and exit")
public void setDisplayHelp(boolean displayHelp) {
  this.displayHelp = displayHelp;
}

Specify command and sub-commands using annotations.

@CommandDescList({
    @CommandDesc(longName = "subcommand",
        description = "my sub-command",
        command = MySubCommand.class),
    @CommandDesc(longName = "othercmd",
        description = "another command",
        command = MyOtherCommand.class)
})
public void setCommand(Command command) {
  this.command = command;
}

Use OptionIntrospector to inspect your classes and generate a model for all specified command line options.
```
 OptionGroup<ID> options = OptionIntrospector.introspect(this.getClass());
```

OptionParser parses command-line arguments according to the model created by the introspector.

OptionParser.Result<ID> parsedOptions = OptionParser.parse(args,
    options, OptionIntrospector.DEFAULT_ID);

Use OptionIntrospector to inject the parsed results into your class.
```
OptionIntrospector.evaluate(parsedOptions.getValues(), this);
```

Display usage information.

String unknownArg = OptionIntrospector.getUnknownArgumentName(this.getClass());
OptionParser.usage("mycommand", "My own command", options,
    unknownArg, new PrintWriter(System.out, true));

This will output:

Usage: mycommand [OPTION]... [COMMAND]
My own command

  -h,--help   display this help and exit

Commands:
  subcommand  my sub-command
  othercmd    another command

Real-world example

citeproc-java uses underline for its command-line interface. This is a very complex example that demonstrates how flexible underline is.

Building

Execute the following command to compile the library and to run the unit tests:

./gradlew test

The script automatically downloads the correct Gradle version, so you won't have to do anything else. If everything runs successfully, you may create a .jar library:

./gradlew jar

The library will be located under the build/libs directory.

License

underline is licensed under the Apache License, Version 2.0.