net.sf.mmm.util.cli.api (JavaDocs for mmm-all dev-SNAPSHOT)

Interface Summary
Interface	Description
CliModeObject	This is a container for a `CliMode` together with additional associated information.
CliParser	This is the interface used to `parse` the command-line arguments of a main-program.
CliParserBuilder	This is the interface used to `build` a `CliParser` from a given object.

Class Summary
Class	Description
AbstractMain	This is the abstract base class for a main-program.
AbstractVersionedMain	This is the abstract base class for a `main-program` that has a version.
CliOptionNameDefaultFilter	This is the default `Filter` used to decide if the `name` or `alias` of a `CliOption` is `acceptable`.
CliOutputSettings	This class represents the settings for the `help output`.

Enum Summary
Enum	Description
CliContainerStyle	This enum contains the available styles for container types.
CliStyleHandling	This enum contains the available ways to handle a specific CLI-style.

Exception Summary
Exception	Description
CliArgumentMissingException	A `CliArgumentMissingException` is thrown if a `required` `argument` is missing.
CliArgumentReferenceMissingException	A `CliArgumentReferenceMissingException` is thrown if a `referenced` `argument` is missing.
CliClassNoPropertyException	A `CliClassNoPropertyException` is thrown if a `CLI-class` is illegal because it has no property annotated with `CliOption` or `CliArgument`.
CliException	A `CliException` is thrown, if the commandline arguments are invalid for a specific main-program.
CliModeUndefinedException	A `CliModeUndefinedException` is thrown if a `CliOption` or `CliArgument` defines a `mode` that is NOT `defined`.
CliOptionAndArgumentAnnotationException	A `CliOptionAndArgumentAnnotationException` is thrown if a property is annotated with both `CliOption` and `CliArgument`.
CliOptionDuplicateException	A `CliOptionDuplicateException` is thrown if the same `option` occurred multiple times as commandline-argument.
CliOptionIllegalNameOrAliasException	A `CliOptionIllegalNameOrAliasException` is thrown if the `name` or `alias` of a `CliOption` is illegal.
CliOptionIncompatibleModesException	A `CliOptionIncompatibleModesException` is thrown if two `options` are used together that have incompatible `modes`.
CliOptionMisplacedException	A `CliOptionMisplacedException` is thrown if an option is misplaced, meaning that it occurred after the first `argument` has been detected.
CliOptionMissingException	A `CliOptionMissingException` is thrown if a `required` `option` is missing.
CliOptionMissingValueException	A `CliOptionMissingValueException` is thrown if an option requires a value that is missing (no proper value is specified as commandline argument).
CliOptionUndefinedException	A `CliOptionUndefinedException` is thrown if an `option` is given as commandline-argument if NOT defined.
CliParameterListEmptyException	A `CliParameterListEmptyException` is thrown if `CliParser.parseParameters(String...)` is called without a single parameter.
CliParserExcepiton	A `CliParserExcepiton` is thrown if a `state class` could NOT be parsed.

Annotation Types Summary
Annotation Type	Description
CliArgument	A `CliArgument` is used to annotate a property (member variable of some class or setter-method) that should be set from a main-program via a commandline argument.
CliClass	A `CliClass` is used to annotate a Java-class that holds the parameters of a main-program that are parsed from the commandline arguments.
CliMode	A `CliMode` is used to annotate a `CLI annotated class` in order to define a operational mode.
CliModes	This annotation is used to annotate a `CLI-Class` with multiple `CliMode`-annotations.
CliOption	A `CliOption` is used to annotate a property (member variable of some class or setter-method) that should be set from a main-program via a commandline option.
CliStyle	A `CliStyle` is used to annotated a Java-class that holds the parameters of a main-program that are parsed from the commandline arguments.

Package net.sf.mmm.util.cli.api Description

Provides the API for utilities that help to build command-line-interfaces (CLI).

CLI API

This package provides the API to create a command-line interface (CLI) for a main program easily.

The Problem

Typical java-applications start with a main-class - a class with a method with this magic signature:

 public static void main(String[] args)

However you quickly notice that this was NOT the end of wisdom when designing an object-oriented language as java. A main-program often starts easy and then over the time options and arguments are added. When you want to write a maintainable main-program you want to have more infrastructure than just having a string-array lost in a static method.

The Solution

As a solution we provide AbstractMain and AbstractVersionedMain that you can extend to build your main program. For each option and argument there are Annotations to annotate your regular Fields. Via CliMode multiple modes can be defined to realize complex scenarios. Everything integrates with javax.validation (BV) and our excellent native-language-support including text wrapping and hyphenation. So you do not have to maintain any usage or help output that is all done for you.

Example

Here you can see a simple example to get started:

  @CliMode(id = CliMode.ID_DEFAULT, usage = NlsBundleMyExampleRoot.MSG_MAIN_MODE_USAGE_DEFAULT)
 public class MyCoolMain extends AbstractVersionedMain {

    @CliOption(name = "--flag", aliases = "-f", usage = NlsBundleMyExampleRoot.MSG_MAIN_OPTION_FLAG)
   private boolean flag;

    @Override
   public int runDefaultMode() {
     if (this.flag) {
       // ... do this ...
     } else {
       // ... do that ...
     }
   }

   public static void main(String[] args) {
     new MyCoolMain().runAndExit(args);
   }
 }

History

After using commons-cli, gnu-getopts and finally args4j, we created this library that brings the best ideas together (with most from args4j).
In the context of CLI we use the term parameter for a string given on the commandline (out of String[] args). Such parameter is either an option or a value. A value can belong to an option or an argument. E.g. the parameters --port 8080 start consist of the option --port with its value 8080 and the argument start.