Quick Start Tutorial: Properties as command line arguments

Changing Help Settings

First though, let's add some CLC entries to do the following:

• Change the default usage section displayed when invoking help; and
• Change the header and footer for the help output.

To do so, we need to create a new file - let's call it overrides.clc - with the following contents:

global.help.command.usage = ${manifest:app-name} [options...] <files...>
global.help.command.header = Process files in the given input directory and \
    move them to the specified output directory.
global.help.command.footer = See some random URL for information

The global.help.command.usage will replace the top-section of the help output (that is, the usage section). global.help.command.header and global.help.command.footer will replace the header and footer text, respectively.

The ${manifest:app-name} declaration will substitute in the value within the manifest file for the manifest key app-name. An error will be created if the manifest entry is missing. When the Apache properties example is run, the following output will be produced for the usage line of the help output:

usage: apache-props-demo [options]  <files...>

Likewise, the Java properties example will output the following:

usage: java-props-demo [options]  <files...>

Notice that the global.help.command.header is split onto two lines for readability. Many of the configuration options can be treated this way. When defining multiline configurations, all trailing whitespace before the closing backslash will be preserved, and succeeding lines will have leading spaces stripped; the lines will then be joined together. Escaping lines in such a way is not mandatory and only used to aid readability, as stated previously.

We'll actually place the overrides.clc files at the same level as the properties file so it will be packaged into the JAR file at build time. All we need to do is add the following line after the call to create the builder but before the call to build(String[]), and rebuild the sources:

builder.withConfiguration(ApachePropertiesDemo.class.getResourceAsStream("/overrides.clc"));

Now, let's run the --help command again and observe the output for the Apache configuration properties demo:

usage: apache-props-demo [options] <in-dir> <out-dir>
Process files in the given input directory and move them to the specified
output directory.
    --file-extensions <arg>  Overrides property 'file.extensions', default
                             value 'mp3, jpeg'
    --file-mimeTypes <arg>   Overrides property 'file.mimeTypes', default
                             value 'text/html, media/jpg'
    --help                   Print this help then exit.
    --host-ip <arg>          Overrides property 'host.ip', default value
                             'localhost'
    --host-port <arg>        Overrides property 'host.port', default value
                             '1234'
    --host-protocol <arg>    Overrides property 'host.protocol', default
                             value 'https'
    --in-dir <arg>           Overrides property 'in.dir', default value
                             'media/processing-in'
    --out-dir <arg>          Overrides property 'out.dir', default value
                             'media/processing-out'
    --strip-exif             Overrides property 'strip.exif', default
                             value 'false'
See some random URL for information

Notice how, with just three custom CLC entries, we've now converted the help output to be a little (but not much) more useful.

We can also override the property descriptions and argument names (the latter of which default to <arg>); let's do that for one of the properties - file.mimeTypes. To override any property description for the individual help output, we need to add a CLC entry, however we must use the converted name (same as the command line switch without the -- prefix). Remember, the command switch names are the same as the property names with all non-alphanumeric characters converted to hyphens. So if we wish to add an entry for the file.mimeTypes property, we need to use the name file-mimeTypes.

Add the following entries to enable custom output for the file.mimeTypes property:

option.file-mimeTypes.argName=mimeTypes...
option.file-mimeTypes.description=MIME types to consider; files that do not \
    match any of the given MIME types will be left in place. Separate multiple \
    MIME types with commas; if there are spaces in the list, surround the \
    arguments with double quotes.

… And observe the output from running --help (trimmed for brevity):

    --file-mimeTypes <mimeTypes...>  MIME types to consider; files that do
                                     not match any of the given MIME types
                                     will be left in place. Separate
                                     multiple MIME types with commas; if
                                     there are spaces in the list,
                                     surround the arguments with double
                                     quotes.

There are other help-based options (detailed in the CLC format section below), not detailed here that enable formatting the resultant output so that it has wider columns etc. when invoking --help.

Adding Version

It's the exception rather than the rule for command line applications not to provide a version. The CLC API enables versioning out of the box for properties and is very simple to do.

To add versioning, simply call the builder with withVersion(). This adds the command line switch --version to the application, the version being determined according to the following rules:

1. If there is a version property in the properties, that value will be used; or
2. If the manifest file contains an Implementation-Version value, that value will be used.

When help is invoked, the version will be presented as follows (trimmed from the other options for brevity):

--version                        Print version then exit.

With only the Implementation-Version present the output will be rather terse, for example

apache-props-demo --version
1.0

We can make use of manifest entries and adding in a version property to the properties file, for example:

version = ${manifest:app-name}, version ${manifest:Implementation-Version}

The output when version is invoked will now be a little more verbose:

apache-props-demo --version
apache-props-demo, version 1.1

If the properties already has a version that is used for a different purpose, the withVersion(String propertyVersionKey) call can be used. This will use the specified property converted to a command line value. For example, calling withVersion("app.version") will enable the version to be called from the command line via the --app-version switch.

Overriding Properties and Types

Next, there are a few options that can be converted to non-string types. Using type inference we've already converted host.port to an integer. So let's add some extra error checking to make sure users enter a valid port number. Under the hood the library converts all inferred types to a value type - a non-string based value. Almost all value types have properties associated with them to enable out-of-the-box error checking, rather than having to do it ourselves.

Using type inferrence we already know that the host.port property has been inferred to be an int. We can add int-based properties to override any CLI argument by adding the following to our overrides.clc file:

option.<config-name>.properties = <properties...>

To override the properties for host.port we can add the following - we can supply either a min, max, or both together, separated by a comma (order doesn't matter):

option.host-port.properties = min = 1025, max = 65535

min and max are numeric value type properties that can be applied to all types that are considered numbers. They are both optional and only one of them needs to be supplied, if chosen. This enables callers to either add a minimum, maximum or both to ensure correct values when the application is run.

Defining a value that is less than the specified minimum, we'll get the following error when specifying --host-port 100:

Error: option host-port: 100 is less than specified minimum: 1025

Now let's continue by converting the in.dir and out.dir properties to be directories. To do so, add the following entries to the overrides.clc file:

option.in-dir.type = dir
option.in-dir.properties = dirType=exists

option.out-dir.type=dir
option.out-dir.properties = dirType=exists

The property defined on each directory type, dirType=exists, means the API will check that the specified directory exists, reducing the amount of code we need to generate - for example, specifying --in-dir as an invalid directory yields the following example output for a non-existant directory named audio-output-dir/:

Error: option in-dir: Specified directory audio-output-dir does not exist.

We can also take advantage of the list value type since two of the properties contain comma-separated values. In particular, file.extensions and file.mimeTypes both contain data separated by commas. To do so, adapt overrides.clc and add the following entries:

option.file-mimeTypes.type = list
option.file-extensions.type = list

Beware that once types are converted to the underlying property implementation, the calls to get the correct values will in fact change depending on the implementation.

For example with the new types in place, the calls for Apache configuration properties don't actually need to change; calling getString(String) will still return a Java string. However, if we want to get the actual value converted by the CLC API, the println calls need to be changed to:

System.out.println("IP address   : " + props.getString("host.ip"));
System.out.println("Port         : " + props.getInt("host.port"));
System.out.println("Protocol     : " + props.getString("host.protocol"));
System.out.println("MIME types   : " + props.getList("file.mimeTypes"));
List<String> list = props.getList(String.class, "file.mimeTypes");
for (int i = 0; i < list.size(); i++) {
    System.out.println("MIME type " + i + "  : " + list.get(i));
}
System.out.println("Extensions   : " + props.getList("file.extensions"));
List<String> list2 = props.getList(String.class, "file.extensions");
for (int i = 0; i < list2.size(); i++) {
    System.out.println("Extension " + i + "  : " + list2.get(i));
}
System.out.println("Strip EXIF   : " + props.getString("strip.exif"));
System.out.println("In-dir       : " + props.get(File.class, "iin.dir"));
System.out.println("Out-dir      : " + props.get(File.class, "out.dir"));

For the Java properties implementation, this will change to:

System.out.println("IP address   : " + props.getProperty("host.ip"));
System.out.println("Port         : " + (int) props.get("host.port"));
System.out.println("Protocol     : " + props.getProperty("host.protocol"));
System.out.println("MIME Types   : " + props.get("file.mimeTypes"));
List<String> list = (List<String>) props.get("file.mimeTypes");
for (int i = 0; i < list.size(); i++) {
    System.out.println("MIME type " + i + "  : " + list.get(i));
}
System.out.println("Extensions   : " + (List<String>) props.get("file.extensions"));
List<String> list2 = (List<String>) props.get("file.extensions");
for (int i = 0; i < list2.size(); i++) {
    System.out.println("Extension " + i + "  : " + list2.get(i));
}
System.out.println("Strip EXIF   : " + (boolean) props.get("strip.exif"));
System.out.println("In-dir       : " + (File) props.get("in-dir"));
System.out.println("Out-dir      : " + (File) props.get("out-dir"));

The changes for Java-based properties is because getProperty(String) returns String, and changing the value types to non-strings means we need to use the get(String) call which returns an object of the appropriate type.

Lists aren't just limited to string values: It is possible to convert list values to any other value type. Refer to the list type documentation in the Value Types section for more information.

Overriding Command Line Names

It's possible using CLC overrides to override the names of the command line arguments that have been generated from the underlying property names. This section focuses on standard options; overriding global option names (help, version) is discussed in the next section.

This can be desirable for large property files that use large namespaces to describe properties. For example, consider the property application.gui.panels.user-management.title - when displayed using help, the following output is producced:

    --application-gui-panels-user-management-title <arg>  Overrides
                                                          property
                                                          'application.gui
                                                          .panels.user-man
                                                          agement.title',
                                                          default value
                                                          '"User
                                                          Management
                                                          Panel"'

This would be unwieldly for the user to type out as well as making the help descriptions difficult to read.

Command line names can be overridden using the opts option; all that's required is to add an entry into the overrides CLC file of the form:

option.<config-name>.opts = <long-option-name>

Continuing the previous examples, to convert the host.port property to be able to be invoked using --port, we can add the following entry to the overrides CLC file:

option.host-port.opts = port

When running with --help, the following output is now produced (trimmed for brevity):

    --port <arg>                 Overrides property 'host.port', default
                                 value '1234'

Under the hood, the API maps the new name port to the property name host.port.

By default, all properties-based implementations use the global option declaration global.options.opts-type with value LONG, meaning all options available via the command line will be long options prefixed with two hyphens.

There are several other types available:

1. BOTH: All declared options must be come in short and long form using the declaration <short-name>/<long-name>. In such a case, each property must have an opts declaration;
2. SHORT: All declared options must be overridden and a short option (single character) defined for it - all properties must be overridden to contain a relevant short-option definition; and
3. ANY: Options can be a mix of short-only, long-only or short-and-long values. In this case all properties that are not overridden will continue to be long options; other properties can be modified to be a short option (single character), or a short and long option of the form <short-name>/<long-name>

Some examples:

To use global option type BOTH, we need to add the global definition, plus all options overridden with an opts definition of the form <short-name>/<long-name>. Continuing the previous example (and only including one property definition for brevity), the CLC overrides file would contain the following:

global.options.opts-type = BOTH
option.host-port.opts = p / port
# ^ Other opts omitted; you'd have to do this for every defined option because
# options type expects short AND long options to be defined for each property

Likewise, to use only short-name types, the following definition would be used:

global.options.opts-type = SHORT
option.host-port.opts = p
# ^ Other opts omitted; you'd have to do this for every defined option because
# options type expects short options to be defined for each property

Remember: When overriding BOTH and SHORT, all properties will require an opts override.

Finally, for the ANY global options type, we could mix and match the above short and short-and-long definitions, the definitions that are not overridden staying as long based options. This means that for any opts declaration, we can use just a short option, a long option or a short and long option. For example, the following shows one option using a short option, one using a long option and one using both a short and long option:

global.options.opts-type = ANY
option.host-port.opts = p
option.host-ip.opts = ip
option.host-protocol.opts = P / protocol
option.file-mimeTypes.opts = mimeTypes

When we invoke help the following output is produced:

usage: apache-props-demo [options] <in-dir> <out-dir>
Process files in the given input directory and move them to the specified
output directory.
    --extensions <arg>          Overrides property 'file.extensions',
                                default value 'mp3, jpeg'
 -h,--help                      Print this help then exit.
    --ip <arg>                  Overrides property 'host.ip', default
                                value 'localhost'
    --mimeTypes <mimeTypes...>  MIME types to consider; files that do not
                                match any of the given MIME types will be
                                left in place. Separate multiple MIME
                                types with commas; if there are spaces in
                                the list, surround the arguments with
                                double quotes.
 -P,--protocol <arg>            Overrides property 'host.protocol',
                                default value 'https'
 -p,--port <arg>                Overrides property 'host.port', default
                                value '1234'
    --strip-exif                Overrides property 'strip.exif', default
                                value 'false'
 -v,--version                   Print version then exit.
See some random URL for information

Overriding Global Command Line Names: Help & Version

Overriding command line names for help and versioning is slightly different to standard options.

To change the options for help options, override global.help.switch.opts with the required options. For example, to change the default long version from the default help to show-help, the following would be added to the overrides CLC file:

global.help.switch.opts = show-help

Versioning acts the same but version options are modified using the global.version.switch.opts global option. For example, to specify the version command line switch as get-version-info, add the following to the CLC overrides file:

global.help.switch.opts = get-version-info

Customising Help

Although help is provided out of the box, it is possible to define your own help if the provided help is not quite what is required.

To override the default help, ensure help(false) is added to the properties builder when building the properties - this will prevent the default help from being generated.

The next step is to add your application as an OptionListener and override the option method, as well as to add custom CLC entries to the CLC overrides file.

For the CLC overrides, add necessary CLC values, for example:

option.help.opts = help
option.help.description = Show some help.
option.help.ignoreCliArgs = true

ignoreCliArgs is set to ensure arguments are not parsed when the API is invoked; it's used to determine if to continue processing arguments.

The next step is to add the application as a listener for the help command.

The application must implement org.statefive.clic.OptionListener with the following implementation, adding in the custom help invocation where the comment is defined:

@Override
public void option(final String option, final Object value) {
    if ("help".equals(option)) {
        // Custom help code here
    }
}

It's also possible to pass an argument to the help command; for example a topic-based help command where a topic is passed to the help command line switch. To do so, modify the CLC definition as follows:

option.help.opts = help
option.help.description = Show some help for the given topic. Topics are 'foo' and 'bar'.
option.help.ignoreCliArgs = true
option.help.hasArg = true
option.help.argName = topic

We can now override the listener to filter on topic and display help accordingly:

@Override
public void option(final String option, final Object value) {
    if ("help".equals(option)) {
        String topic = value.toString();
        switch (topic) {
            case "foo":
                // display 'foo' based topic
                break;
            case "foo":
                // display 'bar' based topic
                break;
            default:
                System.err.println("Unknown topic: " + topic);
        }
    }
}