State 5 :: libclic

CLIC - Command Line Configuration

• Home

Quick-Start

• Properties as CLI Arguments
• CLIC Application Example

CLIC Format

• Introduction
• Global Options
• Option Configurations
• Arguments Configurations
• Top-Level Listeners
• Commands
• Command Listeners
• Value Types

Other

• About
• Future Plans

Get libclic

• License

Command Line Configuration (CLIC) Library

A library to provide two different methods of incorporating command line arguments into an application:

1. Convert properties to and from command line arguments using any number of predefined properties files, as well as convert the properties to enable printing help using --help; and
2. An API that enables configuration files to be written to define options, arguments and commands for an application that are baked in to the application. On application start, the configuration file is read and command line arguments passed to the API for processing; custom listeners are written and updated as each argument is read from the command line.

The terms CLIC and CLC can be used interchangeably and mean the same thing: command line configuration.

Under the hood the project uses Apache commons-cli to parse command line arguments. Supported properties implementations are java.util.Properties and org.apache.commons.configuration2.PropertiesConfiguration.

In more detail, the API enables properties-based and configuration-based methods to utilise command line arguments for any given application:

1. Loading of properties files and convert them into command line arguments, enabling rapid prototyping of new (and existing) applications. In turn any command line arguments supplied will be used to override the property that the command line switch represents. Callers provide at least one properties file and the properties are then parsed into a valid CLC file. Once parsed, all command line switches that are supplied on the command line override the properties that have been read in. Using the API it is possible to convert properties to different types other than strings such as booleans, integer and floating point types. In addition custom CLC entries can be inserted using an overrides file to further customise properties on an individual basis; and

2. Provides the CLC format for defining a configuration that is used to define command line options and arguments as well as commands; all that's needed is to create a custom CLC format file for use within an application and to write required listeners to be informed of updates as command line arguments are processed.

   The CLC format can be packaged directly into the application and code written to load the CLC at application start. All that's required (when not using properties, outlined above) is to write a listener class to receive updated options from the CLC as it loads and command line arguments are passed to it. Callers can then simply access the listener to get the values of the arguments once they've been processed.

In both cases, CLC offers some of the following benefits (the rest are outlined in the main CLC format section, below):

• Auto-generated help and basic help formatting to be able to make the most of generated help contents, as well as options to easily embed application version into an application (and callable from the command line options that are built up);
• Define option configurations that are used to determine what command line switches the application supports;
• Define argument configurations that are consumed once all command line options have been processed; like command line options, these can also be cast to non-string types. Furthermore limits can be set on arguments such that an application can directly control how many arguments should be provided for a given application, even capping them at zero if the application does not take arguments;
• Associate value types with command line options and arguments such that they are pre-cast into any number of non-string types, such as Java primitive types, files, directories, lists and a number of other non-primitive types. These value types can also have properties associated them that offer a form of error checking out of the box, such as limiting (for example) numbers to have minimum and maximum values, ensuring that a file or directory does or doesn't exist, etc.;
• Add commands and nested commands that enable applications to define different sets of command line options on a per-command basis. An example of an application that uses commands is the git command: for example, diff, checkout, branch, stash and status (among many others) are examples of commands that git provides that each have their own unique command line options. The git stash command has many other sub-commands - such as list, drop, apply etc - which the CLC API deems nested commands.