io7m | single-page | multi-page | epub | Quarrel User Manual 1.7.0
1. Introduction
Previous
Front Matter
Up
3. Example Application
Next

# 2. Usage

- 2.1. Overview
- 2.2. Design
- 2.3. Implementing QCommandType
  - 2.3.1. Overview
  - 2.3.2. Command Metadata
  - 2.3.3. Named Parameters
  - 2.3.4. Positional Parameters
  - 2.3.5. Executable
- 2.4. QStrings
- 2.5. Creating A QApplicationType
- 2.6. Calling The QApplicationType
- 2.7. Hidden Commands
- 2.8. The help command
- 2.9. The version command
- 2.10. @ Syntax
- 2.11. Value Converters

## 2.1. Overview

1
The quarrel package provides a simple API for producing command-line applications. Using the package consists of the following steps:

### 2.1.2. Usage Steps

1. Provide one implementation of QCommandType for each of the commands exposed by your application.
2. Create an instance of QApplicationType, registering each of the commands (or, optionally, grouping them into command groups). The application instance must also be provided metadata such as the name and version of the application.
3. Pass arguments to the application instance and either execute the returned command, or display the returned error information.

## 2.2. Design

1
The quarrel package does not intend to provide a fully generic command-line parser that can emulate the argument parsing style of every application ever conceived. It is patterned on a strict subset of the kind of command-line parsing used by programs such as podman.
2
Briefly, the command line interface is divided into discrete commands. Commands may be grouped into command groups. A command accepts a possibly empty list of named parameters, followed by a possibly empty list of positional parameters. Named parameters have a configurable cardinality; a named parameter can be declared as "must be specified exactly one", "may be specified any number of times", "must be specified at least once", and so on. A named parameter must be supplied with a value at run-time, but can also be specified to have a given default value if one is not provided. Both positional and named parameters are typed, with values being parsed by looking up a parser in a directory of value converters. The package comes with a useful set of value converters for many of the standard Java types, but new converters can be registered by the application developer.
3
The quarrel package provides an application abstraction that, given metadata such as the application name and version, automatically provides useful commands such as help and version to relieve the application developer of the burden of having to implement such standard commands. The application abstraction also handles the dispatching of arguments to a tree of nested commands/command groups.
4
The quarrel package also provides detailed, localized, and structured error reporting to assist users of command-line applications built using quarrel. For example, if the user fails to provide a required named argument, or provides a value that cannot be parsed as a value of the argument's declared type, they will receive an error message such as the following:

### 2.2.5. Example Error Messages

    quarrel: ERROR: The wrong number of values were provided for a parameter.
      Command          : example
      Error Code       : parameter-cardinality
      Maximum Values   : 1
      Minimum Values   : 1
      Parameter        : --number
      Provided Count   : 0
      Suggested Action : Provide the right number of arguments for the parameter.

    quarrel: ERROR: The value supplied for a parameter is unparseable.
      Command          : example
      Error Code       : parameter-unparseable-value
      Parameter        : --number
      Provided         : x
      Suggested Action : Provide a parseable value on the command-line.
      Syntax           : 0 | [1-9][0-9]+
      Type             : java.lang.Integer

## 2.3. Implementing QCommandType

## 2.3.1. Overview

1
Application programmers must provide an implementation of the QCommandType interface for each command in the application.
2
In order to implement the QCommandType interface, the following pieces of information must be provided:

### 2.3.1.3. QCommandType Requirements

- The command metadata such as the name of the command, the short one-line description of the command for help messages, the optional long description of the command, and etc.
- The set of named parameters the command accepts, if any.
- The set of positional parameters the command accepts, if any.
- The actual code executed when the command is invoked.

## 2.3.2. Command Metadata

1
The metadata for the command consists of the name of the command, a short one-line description of the command used in generated help messages, and an optional long description also used in help messages. The metadata must be returned by the implementation of the metadata method:

### 2.3.2.2. Metadata method

    @Override
    public QCommandMetadata metadata()
    {
      return new QCommandMetadata(
        "cat",
        new QConstant("Hear a cat speak."),
        Optional.empty()
      );
    }

3
Localizable strings such as the descriptions are specified as values of the QStringsType type so that the quarrel package knows whether to try to look up their value in resources, or use their string constant values directly. Command names are not localizable, because having a different command-line interface depending on locale would create severe problems when using applications from scripts.
4
Command names cannot begin with the @ character, because this would conflict with the provided @ syntax.
5
Command names cannot contain any characters in the Unicode \p{Z} set. This includes any kind of whitespace or invisible separator.
6
Command names must be non-empty.

## 2.3.3. Named Parameters

1
A command may accept zero or more named parameters. A command implementation must return zero or more parameter declarations from the onListNamedParameters method. The values returned are used later by the implemented onExecute method to retrieve the parsed values supplied to those parameters.
2
A named parameter is an instance of the sealed QParameterNamedType. Every named parameter has a name, a type, and descriptive metadata used for help messages. Named parameters may also declare alternative names (for example, to provide short versions of parameters such as -f in addition to --file). Parameter names must be unique within a given command (including alternative names). Each of the subclasses of QParameterNamedType encodes a different parameter cardinality:

### 2.3.3.3. Parameter Cardinality

Type | Cardinality
--- | ---
QParameterNamed0N | The parameter may be specified zero or more times, accumulating values into a list.
QParameterNamed1 | The parameter must be specified exactly once.
QParameterNamed1N | The parameter must be specified at least once, accumulating values into a list.
QParameterNamed01 | The parameter may be specified at most once, yielding an optional value.

### 2.3.3.4. onListNamedParameters method

    private static final QParameterNamed1<Path> FILE =
      new QParameterNamed1<>(
        "--file",
        List.of("-f"),
        new QConstant("The input file."),
        Optional.empty(),
        Path.class
      );

    private static final QParameterNamed01<Integer> COUNT =
      new QParameterNamed01<>(
        "--count",
        List.of(),
        new QConstant("The number of items to process."),
        Optional.of(100),
        Integer.class
      );

    @Override
    public List<QParameterNamedType<?>> onListNamedParameters()
    {
      return List.of(FILE, COUNT);
    }

5
A named parameter may have a value of any type for which there is an appropriate value converter registered.
6
Parameter names cannot begin with the @ character, because this would conflict with the provided @ syntax.
7
Parameter names cannot contain any characters in the Unicode \p{Z} set. This includes any kind of whitespace or invisible separator.
8
Parameter names must be non-empty.

## 2.3.4. Positional Parameters

1
A command may accept zero or more positional parameters. A command implementation must return a value of the QParametersPositionalType type from the implemented onListPositionalParameters method that indicates how the command accepts positional parameters:

### 2.3.4.2. Parameter Positionals

Type | Meaning
--- | ---
QParametersPositionalAny | Any sequence of positional parameters are acceptable. Essentially, no parsing occurs.
QParametersPositionalNone | No positional parameters are allowed. Passing anything results in an error.
QParametersPositionalTyped | The command requires the exact sequence of given parameters.

3
As with named parameters, positional parameters must have names and types, although the names are only used for documentation and are otherwise ignored. If a sequence of positional parameters are provided, all parameters must be supplied on the command-line; positional parameters cannot be optional - use named parameters for optional parameters.

### 2.3.4.4. onListNamedParameters method (None)

    @Override
    public QParametersPositionalType onListPositionalParameters()
    {
      return new QParametersPositionalNone();
    }

### 2.3.4.5. onListNamedParameters method (Any)

    @Override
    public QParametersPositionalType onListPositionalParameters()
    {
      return new QParametersPositionalAny();
    }

### 2.3.4.6. onListNamedParameters method (Typed)

    private static final QParameterPositional<Path> INPUT =
      new QParameterPositional<>(
        "input",
        new QConstant("The input file."),
        Path.class
      );

    private static final QParameterPositional<Path> OUTPUT =
      new QParameterPositional<>(
        "output",
        new QConstant("The output file."),
        Path.class
      );

    @Override
    public QParametersPositionalType onListPositionalParameters()
    {
      return new QParametersPositionalTyped(List.of(INPUT, OUTPUT));
    }

7
A positional parameter may have a value of any type for which there is an appropriate value converter registered.
8
Parameter names cannot begin with the @ character, because this would conflict with the provided @ syntax.
9
Parameter names cannot contain any characters in the Unicode \p{Z} set. This includes any kind of whitespace or invisible separator.
10
Parameter names must be non-empty.

## 2.3.5. Executable

1
The command implementation must implement the onExecute method. This method contains the actual code executed by the application after the command is invoked and all argument parsing has succeeded. The method is passed a value of type QCommandContextType that provides access to:

### 2.3.5.2. Command Context

- The PrintWriter output to which the command can write output. In typical application, this is attached to the standard output, but commands should use this instead of writing to standard output in order to facilitate unit testing of the commands.
- The values of the parsed named parameters (if any).
- The values of the parsed positional parameters.

3
To obtain access to the values of named parameters, the application code can call any of the various context methods, passing in the original parameter declarations. For example:

### 2.3.5.4. Named Parameter Values

    @Override
    public QCommandStatus onExecute(
      final QCommandContextType context)
    {
      final var w = context.output();

      final Path file = context.parameterValue(FILE);
      w.println(file);

      final Integer count = context.parameterValue(COUNT);
      w.println(count);

      final Path input = context.parameterValue(INPUT);
      w.println(input);

      final Path output = context.parameterValue(OUTPUT);
      w.println(output);

      w.flush();
      return SUCCESS;
    }

5
The command context contains methods specialized to each cardinality subclass in order to return values of an appropriate collection type without requiring the programmer to do any unsafe casting. For example a parameter declared with a value of type T with a cardinality of "exactly one" will return a value of T directly. However, a parameter declared with a value of type T with a cardinality of "zero or more times" will return a value of List<T>.
6
The onExecute method is defined to allow the raising of any subclass of Exception, but is also defined to require the returning of a value of type QCommandStatus. The value QCommandStatus.SUCCESS indicates that the command succeeded, and the value QCommandStatus.FAILURE indicates that the command failed. This may seem slightly counterintuitive, after all raising an exception clearly indicates failure. However, consider the standard POSIX utilities such as grep; the grep command returns a non-zero exit code on the command line if the input did not match a given regular expression. The command did not "fail" in a way that would justify raising an exception (such as the user asking grep to open a file that turned out not to exist), but it did return some feedback that justified adjusting the exit code such that scripts can easily observe the results without having to parse the command's output.

## 2.4. QStrings

1
The quarrel package has to accept and display arbitrary strings returned from code implemented by users. In order to properly support localization, the package needs to know whether it needs to localize a given returned string. The QStringType can refer to either of the following types:

### 2.4.2. QString Types

Type | Behaviour
--- | ---
QConstant | The value of the constant is used directly, without any kind of localization.
QLocalize | The value will be localized from the application's resources. The value will ultimately be used as a key to index into a ResourceBundle.

## 2.5. Creating A QApplicationType

1
The quarrel package provides a top-level application type that acts as a container for a tree of commands and command groups. Application developers should instantiate a value of type QApplicationType using the provided mutable builder type.
2
First, place the application metadata into a value of type QApplicationMetadata:

### 2.5.3. Metadata

    final var metadata =
      new QApplicationMetadata(
        "quarrel",
        "com.io7m.quarrel.example",
        "1.2.0",
        "eacd59a2",
        "The Quarrel example application.",
        Optional.of(URI.create("https://www.io7m.com/software/quarrel/"))
      );

4
Create an application builder and register some commands, and set the application's string resources (used to localize the strings returned by the application's commands):

### 2.5.5. Builder

    final ResourceBundle resources = ...;

    final var builder = QApplication.builder(metadata);
    builder.setApplicationResources(resources);
    builder.addCommand(new Command0());
    builder.addCommand(new Command1());
    builder.addCommand(new Command2());

6
For each QString the quarrel package encounters, it first tries to localize the string using the application's provided resource bundle. If the string does not exist there, it tries to localize the string using its own internal resource bundle.
7
Optionally, commands can be placed into groups:

### 2.5.8. Groups

    final var group =
      builder.createCommandGroup(
        new QCommandMetadata(
          "animal",
          new QConstant("Hear an animal speak."),
          Optional.of(new QConstant("A long description."))
        ));

    group.addCommand(new CommandCat());
    group.addCommand(new CommandDog());
    group.addCommand(new CommandCow());

9
Groups and commands form a tree structure, with the root of the tree effectively being an anonymous command group. The command-line arguments passed to an application instance are consumed left to right in order to walk the tree and locate a specific command. For example, if the given command line arguments are podman system connection list -q, assuming that the first argument "podman" is stripped away [1], then the application receives the arguments "system" "connection" "list" "-q". The application will look for a top-level command or group named "system". If "system" names a command, the command will be passed the arguments "connection" "list" "-q" and the search terminates. If "system" names a command group, then the command group will be inspected for a command or group named "connection". This procedure continues recursively until either a command is located, a group doesn't contain the given name (resulting in an error), or the argument list is exhausted (resulting in an error).
10
Finally, build an application. Application instances are immutable.

### 2.5.11. Groups

    final var application = builder.build();

## 2.6. Calling The QApplicationType

1
Given the application instance constructed previously, the instance can be passed a set of command line arguments. The application will either raise an exception indicating that arguments could not be parsed or were incorrect in some manner, or it will return a command context. The command context can be used to execute the parsed command.

### 2.6.2. Execute

    List<String> arguments = ...;

    try {
      var cmd = application.parse(arguments);
      return result = cmd.execute();
    } catch (final Exception e) {
      // Log errors
      return QCommandStatus.FAILURE;
    }

3
The quarrel package uses a QException type containing structured error information to produce useful error messages. The QApplicationType type contains a convenience method named run that effectively implements the above code with some provided error formatting. Given an SLF4J logger, the run method can reduce the above code to:

### 2.6.4. Run

    Logger LOG = ... ;

    return application.run(LOG, arguments)

5
Executing the example program with no arguments yields a generated usage page:

### 2.6.6. Example Usage

    $ quarrel
    quarrel: usage: quarrel [command] [arguments ...]

      The Quarrel example application.

      Use the "help" command to examine specific commands:

        $ quarrel help help.

      Command-line arguments can be placed one per line into a file, and
      the file can be referenced using the @ symbol:

        $ echo help > file.txt
        $ echo help >> file.txt
        $ quarrel @file.txt

      Commands:
        animal      Hear an animal speak.
        cmd-0       A command that does nothing.
        cmd-1       A command that does nothing.
        cmd-1       A command that does nothing.
        help        Show usage information for a command.
        version     Show the application version.

      Documentation:
        https://www.io7m.com/software/quarrel/

## 2.7. Hidden Commands

1
The QCommandType interface contains a default method isHidden that, if implemented to return true, will cause the command implementing it to be hidden in the listings produced by the help command. This can be useful if an application contains internal commands that are not intended to be user-facing.
2
The default behaviour for the method is to return false, thus making commands visible.

## 2.8. The help command

1
The help command is registered at the top level of the resulting application and can produce detailed usage messages when given the name of an existing command. For example, the cmd-everything command from the example application yields the following output when inspected using help cmd-everything:

### 2.8.2. help cmd-everything

    quarrel: usage: cmd-everything [named-arguments ...] <x> <y> <z>

      A command with everything.

      Named parameters:
        --0file
          Description       : A file.
          Type              : String
          Cardinality       : [0, 1]; Specify at most once.
          Syntax            : <any sequence of characters>
          Alternative names : -x, -y, -z
        --1number
          Description       : A number.
          Type              : Integer
          Cardinality       : [0, 1]; Specify at most once, or use the default.
          Default value     : 23
          Syntax            : 0 | [1-9][0-9]+
      * --2number-opt
          Description       : A number.
          Type              : Integer
          Cardinality       : [1]; Specify exactly once.
          Syntax            : 0 | [1-9][0-9]+
        --3date
          Description       : A date.
          Type              : OffsetDateTime
          Cardinality       : [1]; Specify exactly once, or use the default.
          Default value     : 2023-05-12T11:11:22.138315473Z
          Syntax            : yyyy-mm-ddThh:mm:ss+zz:zz (ISO 8601)
        --4net
          Description       : A network address.
          Type              : InetAddress
          Cardinality       : [0, N]; Specify zero or more times.
          Syntax            : Hostname, IPv4 or IPv6 address (RFC 2732)
        --5uuid
          Description       : A UUID.
          Type              : UUID
          Cardinality       : [0, N]; Specify at least once, or use the default.
          Default value     : [5552215f-253f-4391-bd07-7d87f57572ce]
          Syntax            : [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}
        --6path
          Description       : A path.
          Type              : Path
          Cardinality       : [1, N]; Specify at least once.
          Syntax            : <platform-specific path syntax>
        --7uri
          Description       : A URI.
          Type              : URI
          Cardinality       : [1, N]; Specify at least once, or use the default.
          Default value     : urn:x
          Syntax            : RFC 3986 URI

      Positional parameters:
        x
          Type              : Integer
          Description       : An x.
          Syntax            : 0 | [1-9][0-9]+
        y
          Type              : Integer
          Description       : A y.
          Syntax            : 0 | [1-9][0-9]+
        z
          Type              : Integer
          Description       : A z.
          Syntax            : 0 | [1-9][0-9]+

      Farmer Bertram was in bed when the stranger entered, having had a fall
      from his horse while hunting.

      The horseman said his business was of such pressing importance that he
      must see the farmer at once.

      Bertram recognized the name, and directed his old servant to admit the
      stranger to his chamber at once.

## 2.9. The version command

1
The version command is registered at the top level of the resulting application and prints version information based on the metadata provided to the application instance. For example, the version command from the example application yields the following output:

### 2.9.2. version

    com.io7m.quarrel.example 1.2.0 eacd59a2

3
The command outputs the application ID, followed by a space, followed by the version number, followed by a space, followed by the build identifier, followed by a newline.

## 2.10. @ Syntax

1
If the first character of the first argument passed to the application is @, then the argument (minus the @ character) is interpreted as a filename containing command-line arguments for the application.
2
The file named using @ is read line-by-line. Lines beginning with the character # are ignored. Leading and trailing whitespace is trimmed from each line, and empty/blank lines are ignored. After all lines have been read, each line is interpreted as being a single argument, and the resulting list of arguments is prepended onto the arguments following the @ argument.
3
The processing of @ syntax may be disabled by setting allowAtSyntax to false on the application builder.

## 2.11. Value Converters

1
A value converter is a class that can convert values to and from strings. Essentially, they combine a parsing function with a serialization function, and also allow for returning some descriptive information such as the expected syntax of string values. Value converters are collected into a value converter directory, represented by an instance of the QValueConverterDirectoryType type. The directory can be thought of as a map from Java Class values to values of type QValueConverterType.
2
The quarrel package includes a standard directory covering many of the scalar types within the JDK. The list includes but is not necessarily limited to:

### 2.11.3. Standard Types

    java.lang.Boolean
    java.lang.Double
    java.lang.Float
    java.lang.Integer
    java.lang.Long
    java.lang.String
    java.math.BigDecimal
    java.math.BigInteger
    java.net.InetAddress
    java.net.URI
    java.nio.file.Path
    java.time.Duration
    java.time.OffsetDateTime
    java.util.UUID

4
Additionally, the default implementation of the QValueConverterDirectoryType automatically supports the use of any Java enum type.

## Footnotes

1 | As it is the name of the program, and this is not present in the argument array passed to the mainfunction in Java. References to this footnote: 1

1. Introduction
Previous
Front Matter
Up
3. Example Application
Next
io7m | single-page | multi-page | epub | Quarrel User Manual 1.7.0