antlraux.clparse
Class CommandLineParser

java.lang.Object
  |
  +--antlraux.clparse.CommandLineParser

public class CommandLineParser

extends java.lang.Object

This is the main class of the package antlraux.clparse. Basically it parses a command line (or a string) searching for some structs previously specified and invoques methods passing them the parsed parameters.

The first thing to do is create a parser. The simplest constructor admits only the application name (this is usually the name of the class that holds the public static void main() method). Let's suppose that it's called "Main". Then the code for creating the CommandLineParser will be:

   CommandLineParser clp = new CommandLineParserException("Main");
 

Next thing to do is specifying the commands that Main can have.

Let's imagine that it admits the following commands:

• -d + String for specifying an output path.
• -log + integer used for log purposes.

The way CommandLineParser acts is this one: it "links" each command spec to a certain method in a certain instance of a class. This instance is called the "executer".

A CommandLineParser can have many executers (even one for each command spec). However, most of the time the executer will be the same for every command (and it will usually be the pointer "this").

The executor for the two commands that we're coding will be very simple:

   public class Main{
     private String outputPath = ".";
     private int logLevel = 5;
     public Main() {}
     public void setLogLevel(Integer ll)
     { this.logLevel = ll.intValue(); }
     public void setOutputPath(String outputPath)
     { this.outputPath = outputPath; }
   }
 

There are some important facts to take in account when using executers:

• executers must be declared as public classes (with public class...)
• executer methods that will be linked to command line commands must have parameters of type Integer, Float, Character and Boolean instead of int, float, char and boolean.
• executer methods must be public
• command names (-d, -logmust include ANY important symbols, including the minus sign (-) or the anti - slash (\). Commands with no initial symbol are also allowed.

The method that registers command specifications in the parser is addCommand(Object, String, String, String, String)

In the following peace of code an instance of Main is created, and used as executor for a CommandLineParser's commands specifications:

    Main executer = new Main();
    CommandLineParser clp = new CommandLineParser("Main");
    clp.addCommand(executer, "-d", "setOutputPath", "s", "Sets the output path");
    clp.addCommand(executer, "-log", "setLogLevel", "i", "Sets the log level");
 

The params of addCommand are:

• The executer.
• The command "name". In other words, the string that idenfies the command in the command line
• The name of the executer's method associated with the command
• The parameter specification (see the comments on the TypeDealer class
• A description of what the command does.

You can allways read addCommand(Object,String,String,String,String) for further information about them.

The next step is launching the recognition process. This can be done in several ways, being the easiest one using the method parseWhilePossible():

    clp.parseWhilePossible();
 

After parsing the command line, not a single action is taken (no methods are called on the executer). In order to perform the actions coded in the command line, it is necesary to invoke the method executeWhilePossible():

    clp.parseWhilePossible();
 

Both parseWhilePossible() and parseWhilePossible() can throw CommandLineParserException, so it must be caught.

Finally, a bonus: CommandLineParser is capable of generating an authomatic usage message with the command's specs. In order to obtain it, use getUsageMessage(boolean):

    String usageMsg = clp.getUsageMessage(true);
 

Author:

Enrique José García Cota

Constructor Summary

CommandLineParser(CommandLineParser parser)
Builds a CommandLineParser by copy.

CommandLineParser(java.lang.String appName)
Builds a CommandLineParser with a specified parser name.

CommandLineParser(java.lang.String appName, java.lang.String arg)
Builds a CommandLineParser with a specified parser name, and a string to parse.

CommandLineParser(java.lang.String appName, java.lang.String[] args)
Builds a CommandLineParser with a specified parser name, and a string to parse.

Method Summary

void	addCommand(java.lang.Object executer, java.lang.String commandName, java.lang.String methodName, java.lang.String paramTypes, java.lang.String description) Adds a new command specification to the parser.
java.lang.Object	executeNext() Executed the next task to be executed, and erases it from the task vector.
java.lang.Object[]	executeWhilePossible() Executes any pending task in order.
java.lang.String	getCurrentCommandName() Gets the name of the command that generated the task that is being currently executed (the current task is the last task executed, or currently executing).
java.lang.String	getUsageMessage(boolean includeFirstLine) Returns an string that can be used as ussage message.
boolean	hasMoreToExecute() Tests if there are more tasks to be executed.
boolean	hasMoreToParse() Tests if the parser has finished parsing the command Line or not.
void	parseNext() Tries to parse a new command and its params.
void	parseWhilePossible() Parses the commandLine that has not been parsed until its end is reached.
void	setParsingParams(java.lang.String arg) Changes the command line that the parser must parse.
void	setParsingParams(java.lang.String[] args) Changes the command line that the parser must parse.

Methods inherited from class java.lang.Object

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

Constructor Detail

CommandLineParser

public CommandLineParser(java.lang.String appName)

Builds a CommandLineParser with a specified parser name.

Parameters:

appName - The parser name

CommandLineParser

public CommandLineParser(java.lang.String appName,
                         java.lang.String arg)
                  throws CommandLineParserException

Builds a CommandLineParser with a specified parser name, and a string to parse.

Parameters:

appName - The parser name

arg - The String to parse. Before parsing, the parser whill split it in tokens, respecting spaces and quotation marks a la command line

Throws:

CommandLineParserException - If arg could not be split.

CommandLineParser

public CommandLineParser(java.lang.String appName,
                         java.lang.String[] args)

Builds a CommandLineParser with a specified parser name, and a string to parse.

Parameters:

appName - The parser name

args - The command line to parse.

CommandLineParser

public CommandLineParser(CommandLineParser parser)

Builds a CommandLineParser by copy.

Parameters:

parser - The parser whom its name, args, and specs will be copied

Method Detail

addCommand

public void addCommand(java.lang.Object executer,
                       java.lang.String commandName,
                       java.lang.String methodName,
                       java.lang.String paramTypes,
                       java.lang.String description)
                throws CommandLineParserException

Adds a new command specification to the parser.

Parameters:

executer - The object that will execute the method called methodName

commandName - The command name

paramTypes - An string specificating the types of the method called methodName The way types are specified is very simple: each char of the String represents a type. The correspondences between chars and Types can be found in TypeDealer. An empty string (not null!) maps a method with no parameters.

description - A string that will appear in the usage, as an additional help

Throws:

CommandLineParserException - If another command with the same name already exists, or paramTypes contains a non valid char for specificating types.

setParsingParams

public void setParsingParams(java.lang.String arg)
                      throws CommandLineParserException

Changes the command line that the parser must parse. This function also resets the parsing and erases any task that remained unexecuted.

Parameters:

arg - The String to parse. Before parsing, the parser whill split it in tokens, respecting spaces and quotation marks a la command line

Throws:

CommandLineParserException - if arg could not be slit.

setParsingParams

public void setParsingParams(java.lang.String[] args)

Changes the command line that the parser must parse. This function also resets the parsing and erases any task that remained unexecuted.

Parameters:

args - The new commandLine to parse.

parseNext

public void parseNext()
               throws CommandLineParserException

Tries to parse a new command and its params. If succesfull, a new task is added.

Throws:

CommandLineParserException - If a parsing error ocurred.

hasMoreToParse

public boolean hasMoreToParse()

Tests if the parser has finished parsing the command Line or not.

Returns:

false if the end of command line has been reached, false otherwise

parseWhilePossible

public void parseWhilePossible()
                        throws CommandLineParserException

Parses the commandLine that has not been parsed until its end is reached. Stores the tasks to execute in a vector of tasks, whith their params.

Throws:

CommandLineParserException - If a parsing error ocurred.

executeNext

public java.lang.Object executeNext()
                             throws CommandLineParserException

Executed the next task to be executed, and erases it from the task vector.

Returns:

The object that the function executed by the task returns.

Throws:

CommandLineParserException - If there are not mor tasks to execute or if the task throwed an exception.

hasMoreToExecute

public boolean hasMoreToExecute()

Tests if there are more tasks to be executed.

Returns:

true if there are more tasks to execute, false otherwise.

executeWhilePossible

public java.lang.Object[] executeWhilePossible()
                                        throws CommandLineParserException

Executes any pending task in order.

Returns:

All the objects that the differents tasks have returned.

Throws:

CommandLineParserException - if any task has thrown an exception.

getCurrentCommandName

public java.lang.String getCurrentCommandName()

Gets the name of the command that generated the task that is being currently executed (the current task is the last task executed, or currently executing).

Returns:

The name of the command of the current task. null if there is no current task.

getUsageMessage

public java.lang.String getUsageMessage(boolean includeFirstLine)

Returns an string that can be used as ussage message.

Parameters:

includeFirstLine - Setting this to true, whe asure that a title line (containing the application name followed with the parser properties names) will appear.

Returns:

The usage message.