CLC Global Options (including help and version)

Global options are used to define the type of options used (short options, long options or both) as well as help and versioning.

Both help and version are ubiquitous to command line applications, which is why the API offers support for them. API users don't need to take advantage of this

Options Type: global.options.opts-type

The opts-type value can be one of three values (case-sensitive):

  • SHORT: All defined options will consist of a single character, for example valid options would be -h, -L, -5 etc.;
  • LONG: All defined options will consist of one or more characters, for example --help, --limit, --with-some-value etc.;
  • BOTH: All options will come in both short and long format of the form <short-option>/<long-option>.
  • ANY: Options can be defined in one of three ways: Either a short option, a long option, or a short and long option together.

global.options.opts-type is optional; if not defined, the configuration will wait until the first option is defined and auto-detect whether short, long, or both types are supported.

Help: global.help

In order to take advantage of the baked-in help support, the CLC key global.help.option.name must be defined; all other global.help options are optional. Defining any other global.help options without global.help.option.name being present will produce an error.

Key Name Type Description
global.help.option.name string The value of the generated help option configuration name; this will generate an option named option.<config-name> for all help-based options. For example, setting this to show-help will generate several option entries starting with option.show-help.
global.help.command.usage string The command usage that will be printed with the usage at the top of the help section. Typically consists of the command name followed by options and/or arguments.
global.help.switch.opts string short, long or short and long options separated by a forward slash. Defaults to h for short options and help for long options.
global.help.command.header string Text for the header of the help output.
global.help.command.footer string Text for the footer of the help output.
global.help.format.auto-usage boolean Whether to print auto-usage for the command at the top of the output; defaults to false.
global.help.format.column-spacing int Help output column spacing; defaults to 5.
global.help.format.left-pad int Help output left-pad; defaults to 1.
global.help.format.width int Help output format width; defaults to 74.
global.help.format.width-from-env boolean Whether to set the help output width from the environment, specifically the COLUMNS value. Defaults to false.
global.help.format.sort-options boolean Whether to sort options alphabetically; defaults to false. If not set help output will display options in the order they are defined in the configuration.

When the help option is invoked via the command line, the API will generate the help text and then output it to standard output; ensure when the listener is created that System.exit(0) is called when the option is encountered; this is dealt with in the listeners section.

It's worth noting that with the global.help.command.usage property, it's possible to add the application name programmatically by using manifest file text substitution. For example if the manifest entry Application-Name can be embedded into the manfiest file, then the global.help.command.usage entry can be defined as follows:

global.help.command.usage = ${manifest:Application-Name} <options...> <args...>

Version: global.version

Versioning comes out of the box using the following options:

Key Name Type Description
global.version.name string The value of the generated version option configuration name; this will generate an option named option.<config-name> for all version-based options. For example, setting this to show-version will generate several option entries starting with option.show-version.
global.version.text string Text that will be displayed when version is invoked.
global.version.switch.opts string short, long or short and long options separated by a forward slash. Defaults to v for short options and version for long options.

Like with the help option, when the version switch is invoked via the command line, the API will generate the version text and then output it to standard output; ensure when the listener is created that System.exit(0) is called when the option is encountered; this is dealt with in the listeners section.

Like global.help.command.usage, it's also possible to programmatically embed the application version into the global.version.text property. For example if the manifest entries Implementation-Version and Application-License can be embedded into the manfiest file, the global.version.text entry can be defined as follows:

global.version.text = ${manifest:Implementation-Version}, License: ${manifest:Application-License}