net.sf.mmm.util.cli.api

Annotation Type CliOption

@Retention(value=RUNTIME)
 @Documented
 @Target(value={FIELD,METHOD})
public @interface 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.
If the annotated property is a Field it may NOT be static or final and by convention it should be private. Setters may NOT be static and by convention they should be public.
The annotated property should be initialized properly at construction in order to determine whether the option was triggered or not. For non-primitive types the property should be initialized with null.
When the main-program is invoked an CliOption can be triggered via its name or one of its aliases. Options with a type other than boolean need to be followed by a value as CLI parameter. This value has to be quoted in the commandline if it contains whitespaces or other characters that are interpreted by the shell (e.g. backslash in Unix).
The type of the annotated property has to be supported by the CLI implementation so the value can be converted properly. The following types are guaranteed to be supported:

Type	Comment
String	The given text as is.
boolean	Set to true if CliOption is present. Should be initialized with false at construction.
Boolean	If the option is present with a value of true or false the according Boolean is applied. Otherwise values are treated as invalid. According to CliStyle, true may be omitted.
Number	The subclasses of Number from the package java.lang are always supported.
File	A file created from the value of the option.
Enum	A concrete subclass of Enum. The value needs to match the Enum.name() but case is ignored and underscores may also be replaced by hyphen ("-") or whitespace (" ").

However the default implementation can handle any reasonable type via ComposedValueConverter

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

Fields

Modifier and Type	Fields and Description
static String	ALIAS_HELP The alias of the option to get help/usage.
static String	ALIAS_VERSION The alias of the option to get the program version.
static String	NAME_HELP The name() of the option to get help/usage.
static String	NAME_VERBOSE The name() of the option for verbose output.
static String	NAME_VERSION The name() of the option to get the program version.
static String	OPERAND_DEFAULT The default operand.

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
String	name The actual option (e.g.
String	usage The description of this option for help usage.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String[]	aliases The list of optional aliases that can be used instead of the name().
CliContainerStyle	containerStyle The style of this option if it has a container type.
String	mode The ID of the mode.
String	operand The name of the operand for the usage.
boolean	required The flag that indicates if this option is required.

Field Detail

OPERAND_DEFAULT

public static final String OPERAND_DEFAULT

The default operand.

NAME_HELP

public static final String NAME_HELP

The name() of the option to get help/usage.

ALIAS_HELP

public static final String ALIAS_HELP

The alias of the option to get help/usage.

NAME_VERSION

public static final String NAME_VERSION

The name() of the option to get the program version.

ALIAS_VERSION

public static final String ALIAS_VERSION

The alias of the option to get the program version.

NAME_VERBOSE

public static final String NAME_VERBOSE

The name() of the option for verbose output.

Element Detail

name

public abstract String name

The actual option (e.g. "--help").
By convention this should be a GNU long-named option starting with "--" followed by a self-explanatory name where terms may with separated with hyphens (e.g. "--with-extra-option").

usage

public abstract String usage

The description of this option for help usage. It should be an internationalized message that will be localized using NlsMessage. NLS-arguments are "operand" for the localized operand and "default" for the default value.

operand

public abstract String operand

The name of the operand for the usage. A CliOption can either be a switch (if type of annotated field is boolean/Boolean) or it takes an operand (e.g. "--delay 5"). The name of this operand for the usage output can be configured here.

Default:

"ARG"

aliases

public abstract String[] aliases

The list of optional aliases that can be used instead of the name(). E.g. for name() "--help" an alias could be "-h".

Default:

{}

required

public abstract boolean required

The flag that indicates if this option is required. Use a value of true to make this option required within it's mode.

See Also:

CliMode.parentIds()

Default:

false

mode

public abstract String mode

The ID of the mode. A typical main-program has different modes how it can be invoked.
The options of a program can be split into groups that represent such mode. The options are ordered by their mode in the help-usage-output and modes allow to express that an option is required only in a specific mode.
Options can only be combined as command-line arguments if their modes are compatible. This means that the modes have to be identical or one mode extends the other. In the latter case the most special mode is triggered. For each mode that is used in an CLI annotated class an according CliMode annotation has to be present in order to define the mode.

See Also:

CliMode

Default:

"default"

containerStyle

public abstract CliContainerStyle containerStyle

The style of this option if it has a container type. The default is CliContainerStyle.DEFAULT.

See Also:

CliStyle.containerStyle()

Default:

net.sf.mmm.util.cli.api.CliContainerStyle.DEFAULT