Annotations

Airline uses a variety of different annotations to allow you to declaratively define various aspects of your CLIs. This section of the user guide covers each annotation in-depth with examples of their practical usage.

CLI Annotations

The following annotations are used to define the high level aspects of your CLIs:

• The @Command annotation defines classes as being commands
• The @Option annotation defines fields of a class as denoting options
• The @Arguments annotation defines a field of a class as denoting arguments
• The @Cli annotation defines a class as being a CLI which consists of potentially many commands
  • The @Group annotation defines a command group within a CLI
  • The @Groups annotation defines an @Command annotated class as belonging to some command groups within a CLI
• The @Parser annotation defines the parser behaviour
  • The @Alias annotation defines command aliases for a parser configuration
• The @DefaultOption annotation defines an @Option annotated field as being able to also be populated as if it were @Arguments annotated

Restriction Annotations

The following annotations are used to define various restrictions on options and arguments that cause Airline to automatically enforce restrictions on their usage e.g. requiring an option take a value from a restricted set of values.

All these annotations are applied to fields that are annotated with @Option or @Arguments and are automatically discovered during meta-data extraction. If you are overriding the definition of an option then restrictions are automatically inherited unless you specify new restrictions further as part of your override. In the case where you wish to remove inherited restrictions you can use the special @Unrestricted annotation to indicate that.

Requirement Restrictions

The following annotations are used to specify that options/arguments (or combinations thereof) are required:

• The @Required annotation indicates that an option/argument must be specified
• The @RequireSome annotation indicates that one/more from some set of options must be specified
• The @RequireOnlyOne annotation indicates that precisely one of some set of options must be specified
• The @MutuallyExclusiveWith annotation indicates that precisely one of some set of options may be specified

Occurrence Restrictions

The following annotations are used to specify the number of times that options/arguments can be specified:

• The @Once annotation indicates that at option/argument may be specified only once
• The @MinOccurrences annotation indicates that an option/argument must be specified a minimum number of times
• The @MaxOccurrences annotation indicates that an option/argument may be specified a maximum number of times

Value Restrictions

The following annotations are used to specify restrictions on the values for options/arguments:

• The @AllowedRawValues annotation specifies a set of strings that may be specified as the value
• The @AllowedValues annotation specifies a set of values that may be specified as the value
• The @MaxLength annotation specifies the maximum length of the value that may be given
• The @MinLength annotation specifies the minimum length of the value that may be given
• The @NotBlank annotation specifies that a value may not consist entirely of white space
• The @NotEmpty annotation specifies that the value may not be an empty string
• The @Path annotation specifies restrictions on values that refer to files and/or directories
• The @Pattern annotation specifies that a value must match a regular expression
• The @Port annotation specifies restrictions on values that represent port numbers

Range Value Restrictions

A further subset of annotations specify restrictions on the values for options/arguments in terms of ranges of acceptable values:

• The @ByteRange annotation specifies a range of byte values that are acceptable
• The @DoubleRange annotation specifies a range of double values that are acceptable
• The @FloatRange annotation specifies a range of float values that are acceptable
• The @IntegerRange annotation specifies a range of int values that are acceptable
• The @LexicalRange annotation specifies a range of string values that are acceptable
• The @LongRange annotation specifies a range of long values that are acceptable
• The @ShortRange annotation specifies a range of short values that are acceptable

Special Restrictions

The following are special purpose restrictions:

• The @Unrestricted annotation indicates that no restrictions apply to the option. Used in conjunction with option overriding to clear restrictions.
• The @Partials/@Partial annotation is used to apply restrictions to only some parts of options/arguments where multiple values are accepted by those fields

Global Restrictions

The following are Global restrictions which apply over the final parser state:

• The @CommandRequired annotation indicates that a command must be specified.
• The @NoMissingOptionValues annotation indicates that specifying an option without its corresponding value(s) is not permitted.
• The @NoUnexpectedArguments annotation indicates that any unrecognised inputs are not permitted.

Help Annotations

The following annotations are used to add additional help information to commands that may be consumed by the various help generators provided by Airline by producing additional help sections.

All these annotations are added to an @Command annotated class or a parent class in the commands hierarchy. They are automatically discovered from a command classes inheritance hierarchy, where an annotation occurs more than once the annotation specified furthest down the hierarchy is used. This can be used to specify a default for some help annotation with the option of overriding it if necessary, the special @HideSection annotation may be used to suppress an inherited help annotation.

• The @Copyright annotation adds a copyright statement
• The @Discussion/@ExternalDiscussion annotations add extended discussion
• The @ExitCodes/@ExternalExitCodes annotations adds documentation on exit codes
• The @Examples/@ExternalExamples/@ExternalTabularExamples annotations add usage examples
• The @HideSection annotation is used to hide an inherited help section
• The @License annotation adds a license statement
• The @ProseSection/@ExternalProse annotations adds custom titled text sections
• The @Version annotation adds a version statement

---

Improving this Documentation

This documentation is itself open source and lives in GitHub under the docs/ directory.

I am not a professional technical writer and as the developer of this software I can often make assumptions of knowledge that you as a user reading this may not have. Improvements to the documentation are always welcome, if you have suggestions for the documentation please submit pull requests to the main branch.