Package org.apache.commons.cli.avalon

Utility code for parsing command-line options.

See: Description

Interface Summary

Interface	Description
ParserControl	ParserControl is used to control particular behaviour of the parser.

Class Summary

Class	Description
AbstractParserControl	Class to inherit from so when in future when new controls are added clients will no have to implement them.
CLArgsParser	Parser for command line arguments.
CLOption	Basic class describing an instance of option.
CLOptionDescriptor	Basic class describing an type of option.
CLUtil	CLUtil offers basic utility operations for use both internal and external to package.

Package org.apache.commons.cli.avalon Description

Utility code for parsing command-line options.

These classes were originally in the Avalon project in the package org.apache.avalon.excalibur.cli

Introduction

The utilities in org.apache.commons.cli.avalon assist you in parsing command line options during startup time. It allows you to associate a short option and a long option to the same command, and then test for it in a switch statement.

Usage Example

import java.util.List;

import org.apache.commons.cli.avalon.CLArgsParser;
import org.apache.commons.cli.avalon.CLOption;
import org.apache.commons.cli.avalon.CLOptionDescriptor;
import org.apache.commons.cli.avalon.CLUtil;

/**
* Demonstrates the excalibur command-line parsing utility.
*
*/
public class CLDemo {
    // Define our short one-letter option identifiers.
    protected static final int HELP_OPT = 'h';
    protected static final int VERSION_OPT = 'v';
    protected static final int MSG_OPT = 'm';

    /**
     *  Define the understood options. Each CLOptionDescriptor contains:
     * - The "long" version of the option. Eg, "help" means that "--help" will
     * be recognised.
     * - The option flags, governing the option's argument(s).
     * - The "short" version of the option. Eg, 'h' means that "-h" will be
     * recognised.
     * - A description of the option.
     */
    protected static final CLOptionDescriptor [] options = new CLOptionDescriptor [] {
        new CLOptionDescriptor("help",
                CLOptionDescriptor.ARGUMENT_DISALLOWED,
                HELP_OPT,
                "print this message and exit"),
        new CLOptionDescriptor("version",
                CLOptionDescriptor.ARGUMENT_DISALLOWED,
                VERSION_OPT,
                "print the version information and exit"),
        new CLOptionDescriptor("msg",
                CLOptionDescriptor.ARGUMENT_REQUIRED,
                MSG_OPT,
                "the message to print"),
    };

    public static void main(String args[]) {
        // Parse the arguments
        CLArgsParser parser = new CLArgsParser(args, options);

        if( null != parser.getErrorString() ) {
           System.err.println( "Error: " + parser.getErrorString() );
           return;
        }

        // Get a list of parsed options
        List clOptions = parser.getArguments();
        int size = clOptions.size();

        for (int i = 0; i < size; i++) {
            CLOption option = (CLOption) clOptions.get(i);

            switch (option.getId()) {
                case CLOption.TEXT_ARGUMENT:
                    System.out.println("Unknown arg: "+option.getArgument());
                    break;

                case HELP_OPT:
                    printUsage();
                    break;

                case VERSION_OPT:
                    printVersion();
                    break;


                case MSG_OPT:
                    System.out.println(option.getArgument());
                    break;
            }
        }
    }

    private static void printVersion() {
        System.out.println("1.0");
        System.exit(0);
    }

    private static void printUsage() {
        String lSep = System.getProperty("line.separator");
        StringBuffer msg = new StringBuffer();
        msg.append("------------------------------------------------------------------------ ").append(lSep);
        msg.append("Excalibur command-line arg parser demo").append(lSep);
        msg.append("Usage: java "+CLDemo.class.getName()+" [options]").append(lSep).append(lSep);
        msg.append("Options: ").append(lSep);
        msg.append(CLUtil.describeOptions(CLDemo.options).toString());
        System.out.println(msg.toString());
        System.exit(0);
    }
}

Parsing Rules

The command line is parsed according to the following rules. There are two forms of options in this package, the Long form and the Short form. The long form of an option is preceded by the '--' characters while the short form is preceded by a single '-'. Some example options would be; "--an-option", "-a", "--day", "-s -f -a".

In the tradition of UNIX programs, the short form of an option can occur immediately after another short form option. So if 'a', 'b' and 'c' are short forms of options that take no parameters then the following command lines are equivalent: "-abc", "-a -bc", "-a -b -c", "-ab -c", etc.

Options can also accept arguments if specified. You can specify that an option requires an argument in which the text immediately following the option will be considered to be an argument to the option. So if 'a' was an option that required an argument then the following would be equivalent; "-abc", "-a bc" (namely the option 'a' with argument 'bc').

Options can also specify optional arguments. In this case if there is any text immediately following the option character then it is considered an argument. Otherwise, the option has no arguments. For example if 'a' was an option that required an optional argument then "-abc" is an option 'a' with argument "bc" while "-a bc" is an option 'a' with no argument, followed by the text "bc".

It is also possible to place an '=' sign between the option and its argument. So if we assume that a is an option that requires an argument then the following are equivalent; "-a=bc" and "-abc".

In the case of a long option with an optional argument, the '=' sign is required. For example. --optarg=1, not --optarg 1.

In some cases it is also necessary to disable command line parsing so that you can pass a text argument to the program that starts with a '-' character. To do this insert the sequence '--' onto the command line with no text immediately following it. This will disable processing for the rest of the command line. The '--' characters will not be passed to the user program. For instance the line "-- -b" would result in the program being passed the text "-b" (ie. not as an option).