org.openmdx.base.application.control
Class CmdLineProcessor

java.lang.Object
  org.openmdx.base.application.control.CmdLineProcessor

public class CmdLineProcessor
extends Object

The CmdLineProcessor parses command line arguments

Definitions:

   foo   -a  -b 100 --noLog --port=8080  file1  file2  file3

     Executable            :  foo

     Command line options  :   -a   -b   --noLog   --port

     Command line arguments:   '100' is an argument for the short option '-b'
                               '8080' is an argument for the long option '--port'

     Free arguments        :   arguments that do not belong to an option
                               'file1'  'file2'  'file3'
 

A sample application using the command line processor:

 
 public class Application
 {
   public int main(String args[])
   {
           ArrayList             options; 
           CmdLineProcessor              cmdLineProcessor(args);


     // Command line option definition
           options.add(new CmdLineOption("delete", "Option --delete")); 

           // Attach the command line options 
           cmdLineProcessor.setOptions("An overiew help text", options);

     // Process the command line parameters and let the command line processor
     // handle any error conditions.
           cmdLineProcessor.parse(true);        

           // Get the parsed command line arguments
           CmdLineArgs  args = cmdLineProcessor.getCmdLineArgs();
        
     // Lookup
           if ( args.hasArg("delete") ) {
             ... any action ...
           }

     return 0;
   }
 }
 

Field Summary

static int	PARSER_FAILED Command line parsing failed
static int	PARSER_HELP Parser recognized a help request
static int	PARSER_NO_ARGS No raw arguments set for the parser
static int	PARSER_SUCCESS Command line parsing was successful

Constructor Summary

CmdLineProcessor()
The Command Line Processor

CmdLineProcessor(String[] args)
The Command Line Processor

Method Summary

CmdLineArgs	getCmdLineArgs() Get the parsed command lin arguments
String	getHelp() Returns the help overview string provided by the application and a help string for all application options.
String	getUsage() Returns the combined usage string for all application options
int	parse(boolean handleErrors) Parse the command line.
int	parse(boolean handleErrors, List traceMessages) Parse the command line.
void	setApplicationName(String name) Set an application name
void	setApplicationVersion(String version) Set an application version
void	setFreeArgsOption(CmdLineFreeArgOption freeArgOption) Set the desired free argument options and passes a usage string that describes the free arguments.
void	setOptions(String helpOverview, List options) Set the desired command line options and passes a help overview string that describes the applications functionality.
void	setRawArgs(String[] args) Set the command line arguments

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PARSER_FAILED

public static final int PARSER_FAILED

Command line parsing failed

See Also:

Constant Field Values

PARSER_NO_ARGS

public static final int PARSER_NO_ARGS

No raw arguments set for the parser

See Also:

Constant Field Values

PARSER_SUCCESS

public static final int PARSER_SUCCESS

Command line parsing was successful

See Also:

Constant Field Values

PARSER_HELP

public static final int PARSER_HELP

Parser recognized a help request

See Also:

Constant Field Values

Constructor Detail

CmdLineProcessor

public CmdLineProcessor()

The Command Line Processor

CmdLineProcessor

public CmdLineProcessor(String[] args)

The Command Line Processor

Parameters:

args - The cmd line arguments from main()

Method Detail

setApplicationName

public void setApplicationName(String name)

Set an application name

Parameters:

name - An application name

setApplicationVersion

public void setApplicationVersion(String version)

Set an application version

Parameters:

version - An application version

setRawArgs

public void setRawArgs(String[] args)

Set the command line arguments

Parameters:

args - The cmd line arguments from main()

setOptions

public void setOptions(String helpOverview,
                       List options)

Set the desired command line options and passes a help overview string that describes the applications functionality.

Parameters:

pgmHelpOverview - The program's help overview string

options - A list of cmd line options (class CmdLineOption)

setFreeArgsOption

public void setFreeArgsOption(CmdLineFreeArgOption freeArgOption)

Set the desired free argument options and passes a usage string that describes the free arguments.

Parameters:

freeArgOption - The free argument option

parse

public int parse(boolean handleErrors)

Parse the command line. Preconditions:

• The raw command line arguments (argc, argv) must have be set
• The command line options must have been set optionally using a call to setOptions("help overview", options)
• The free args options must have been set optionally using a call to setFreeArgsOption("usage", minArgs, maxArgs)

If 'handleErrors' is set to true, the command line processor handles any command line parsing errors on behalf of the application and exits the application with the exitCode 255 on any error.

If an application must handle the parsing state itself it can use the snippet listed below (actually this snippet is used when 'handleErrors' is set to 'true'):

 
        parserState = cmdLineProcessor.parse(false);
        switch (parserState) {
                case CmdLineProcessor.PARSER_FAILED:
                        System.out.println("Command line parsing failed!");
                        System.out.println("Usage:");
                        System.out.println(cmdLineProcessor.getUsage());
                        System.exit(1); 
                        break;
                case CmdLineProcessor.PARSER_NO_ARGS:
                        System.out.println(
                                "Internal ERROR: Command line arguments have not been " +
                                "supplied to the CommandLineProcessor");
                        System.exit(1); 
                        break;
                case CmdLineProcessor.PARSER_HELP:
                        System.out.println(cmdLineProcessor.getHelp());
                        System.exit(1); 
                        break;
                case CmdLineProcessor.PARSER_SUCCESS:
                        break;
        }
 

Parameters:

handleErrors - if true the parser handles the errors itself

Returns:

The parser's result code

See Also:

parse(boolean, List)

parse

public int parse(boolean handleErrors,
                 List traceMessages)

Parse the command line.

Parameters:

handleErrors - if true the parser handles the errors itself

traceMessages - if not null filled up with parse trace messages (strings)

Returns:

The parser's result code

See Also:

parse(boolean)

getUsage

public String getUsage()

Returns the combined usage string for all application options

E.g

 NAME
 Application 1.0

 OPTIONS
   --aaa arg [1..2]       -  Option --aaa
   --bbb arg [0..2]       -  Option --bbb
   -h                     -  print a help text. 
   --help                 -  print a help text. 
  
   Free args [1..4]       -  Files to convert
 



Returns:
A string

getHelp

public String getHelp()

Returns the help overview string provided by the application and a help string for all application options.

E.g

 NAME
 Application 1.0

 DESCRIPTION
 The help overview text provided by the application    

 OPTIONS
   --aaa arg [1..2]       -  Option --aaa
   --bbb arg [0..2]       -  Option --bbb
   -h                     -  print a help text. 
   --help                 -  print a help text. 
 
   Free args [1..4]       -  Files to convert
 



Returns:
A string

getCmdLineArgs

public CmdLineArgs getCmdLineArgs()

Get the parsed command lin arguments

Returns:

The cmd line args