Clad User Manual

Internal

• clad

Overview

The framework scans the command line looking for the first argument that can be mapped to a command.

The mapping process involves scanning the classpath and looking for classes implementing the Command interface. The current version does not introspect all classes, but just those whose simple class name match the following pattern: <commandName>Command.

All arguments between the wrapper name and the command name are interpreted as global options.

All arguments following the command name are interpreted as command options.

   wrapper [global-options] command [command-options]

Options

The options use the GNU command line convention:

 -o <value> | --option=<value>

Universal Global Options

-v|--verbose

-v or --verbose turns on DEBUG on the underlying CONSOLE appender.

Configuration File

Each command line option has a configuration file correspondent. Command line value takes precedence over the configuration file value.

Implementing a Command Line Application

Implement ApplicationRuntime interface or extend ApplicationRuntimeBase

Package the application runtime implementation class and the commands in a JAR (or place them in a directory).

Set “application.name” as a system property. If the application runtime implementation class is BlueApplicationRuntime, the application.name must be “blue”.

Make sure the JAR or the directory is first on the class path (otherwise other <your-command-name>Command.class, if exist, will be instantiated first).

In-line Application Help

If a text file named <application-name>.txt is placed in the same package as the ApplicationRuntime implementation class, its content is rendered to stdout every time the in-line application help is invoked with no-argument "help" command:

   <app-name> help|--help|-h

Macros

The help renderer recognizes several macros, which are replaced by dynamically generated content at runtime.

@COMMANDS@ - inserts the list of commands available to the application. The runtime builds that list via introspection looking for classes that implement the Command interface.

Implementing a Command

Implement the Command interface or extend CommandBase (recommended).

The implementation class must be named <command-name>Command.

Example: PrintCommand will be matched to the "print" command. BusinessScenarioCommand will be matched to the "business-scenario" command.

Relationship between Command and ApplicationRuntime

If a specific command does not need an application runtime instance (thus the framework is not required to instantiate an application runtime for it), the Command.needsRuntime() implementation must return false. By default CommandBase.needsRuntime() returns true.

In-Line Command Help

If a text file named <command-name>.txt is placed in the same package as the command implementation class, the framework will send the content of the file to stdout when in-line command help is requested:

    <wrapper> help|--help|-h <command>

Default Command

If no command is specified, the framework will use the “default command”, if there is one. If not, the application should display:

 [error]: no command specified on command line and no default command was configured.

Instructions on how to configure the default command.

Command Execution

execute() will be called on the main thread.

Universal Commands

The framework comes with a set of universal commands that are available to any application:

Version and Release Date

The framework supports the "version" command by default. The "version" command pulls version and release date from the underlying application and displays it in a standard format:

version 1.0
release date 01/26/16