com.android.sdklib.util
Class CommandLineParser

java.lang.Object
  com.android.sdklib.util.CommandLineParser

public class CommandLineParser
extends java.lang.Object

Parses the command-line and stores flags needed or requested.

This is a base class. To be useful you want to:

• override it.
• pass an action array to the constructor.
• define flags for your actions.

To use, call parseArgs(String[]) and then call getValue(String, String, String).

Nested Class Summary

protected static class	CommandLineParser.Accept
protected static class	CommandLineParser.Arg An argument accepted by the command-line, also called "a flag".
protected static class	CommandLineParser.Mode The mode of an argument specifies the type of variable it represents, whether an extra parameter is required after the flag and how to parse it.

Field Summary

static java.lang.String	GLOBAL_FLAG_VERB Internal verb name for internally hidden flags.
static java.lang.String	KEY_HELP The global help flag.
static java.lang.String	KEY_SILENT The global silent flag.
static java.lang.String	KEY_VERBOSE The global verbose flag.
static java.lang.String	NO_VERB_OBJECT String to use when the verb doesn't need any object.

Constructor Summary

CommandLineParser(com.android.utils.ILogger logger, java.lang.String[][] actions)
Constructs a new command-line processor.

Method Summary

boolean	acceptLackOfVerb() Indicates if this command-line can work when no verb is specified.
protected void	define(CommandLineParser.Mode mode, boolean mandatory, java.lang.String verb, java.lang.String directObject, java.lang.String shortName, java.lang.String longName, java.lang.String description, java.lang.Object defaultValue) Internal helper to define a new argument for a give action.
protected void	exit() Exits in case of error.
protected CommandLineParser.Arg	findLongArg(java.lang.String verb, java.lang.String directObject, java.lang.String longName) Finds an CommandLineParser.Arg given an action name and a long flag name.
protected CommandLineParser.Arg	findShortArg(java.lang.String verb, java.lang.String directObject, java.lang.String shortName) Finds an CommandLineParser.Arg given an action name and a short flag name.
java.lang.String	getDirectObject() Returns the direct object name from the command-line.
protected com.android.utils.ILogger	getLog() Returns the logger object.
java.lang.Object	getValue(java.lang.String verb, java.lang.String directObject, java.lang.String longFlagName) Raw access to parsed parameter values.
java.lang.String	getVerb() Returns the verb name from the command-line.
boolean	isHelpRequested() Helper that returns true if --help was requested.
boolean	isSilent() Helper that returns true if --silent was requested.
boolean	isVerbose() Helper that returns true if --verbose was requested.
protected void	listOptions(java.lang.String verb, java.lang.String directObject) Internal helper to print all the option flags for a given action name.
void	parseArgs(java.lang.String[] args) Parses the command-line arguments.
void	printHelpAndExit(java.lang.String errorFormat, java.lang.Object... args) Prints the help/usage and exits.
void	printHelpAndExitForAction(java.lang.String verb, java.lang.String directObject, java.lang.String errorFormat, java.lang.Object... args) Prints the help/usage and exits.
protected void	setValue(java.lang.String verb, java.lang.String directObject, java.lang.String longFlagName, java.lang.Object value) Internal setter for raw parameter value.
protected void	stderr(java.lang.String format, java.lang.Object... args) Prints a line to stderr.
protected void	stdout(java.lang.String format, java.lang.Object... args) Prints a line to stdout.

Methods inherited from class java.lang.Object

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

Field Detail

GLOBAL_FLAG_VERB

public static final java.lang.String GLOBAL_FLAG_VERB

Internal verb name for internally hidden flags.

See Also:

Constant Field Values

NO_VERB_OBJECT

public static final java.lang.String NO_VERB_OBJECT

String to use when the verb doesn't need any object.

See Also:

Constant Field Values

KEY_HELP

public static final java.lang.String KEY_HELP

The global help flag.

See Also:

Constant Field Values

KEY_VERBOSE

public static final java.lang.String KEY_VERBOSE

The global verbose flag.

See Also:

Constant Field Values

KEY_SILENT

public static final java.lang.String KEY_SILENT

The global silent flag.

See Also:

Constant Field Values

Constructor Detail

CommandLineParser

public CommandLineParser(com.android.utils.ILogger logger,
                         java.lang.String[][] actions)

Constructs a new command-line processor.

Parameters:

logger - An SDK logger object. Must not be null.

actions - The list of actions recognized on the command-line. See the javadoc of mActions for more details.

See Also:

mActions

Method Detail

acceptLackOfVerb

public boolean acceptLackOfVerb()

Indicates if this command-line can work when no verb is specified. The default is false, which generates an error when no verb/object is specified. Derived implementations can set this to true if they can deal with a lack of verb/action.

isVerbose

public boolean isVerbose()

Helper that returns true if --verbose was requested.

isSilent

public boolean isSilent()

Helper that returns true if --silent was requested.

isHelpRequested

public boolean isHelpRequested()

Helper that returns true if --help was requested.

getVerb

public java.lang.String getVerb()

Returns the verb name from the command-line. Can be null.

getDirectObject

public java.lang.String getDirectObject()

Returns the direct object name from the command-line. Can be null.

getValue

public java.lang.Object getValue(java.lang.String verb,
                                 java.lang.String directObject,
                                 java.lang.String longFlagName)

Raw access to parsed parameter values.

The default is to scan all parameters. Parameters that have been explicitly set on the command line are returned first. Otherwise one with a non-null value is returned.

Both a verb and a direct object filter can be specified. When they are non-null they limit the scope of the search.

If nothing has been found, return the last default value seen matching the filter.

Parameters:

verb - The verb name, including GLOBAL_FLAG_VERB. If null, all possible verbs that match the direct object condition will be examined and the first value set will be used.

directObject - The direct object name, including NO_VERB_OBJECT. If null, all possible direct objects that match the verb condition will be examined and the first value set will be used.

longFlagName - The long flag name for the given action. Mandatory. Cannot be null.

Returns:

The current value object stored in the parameter, which depends on the argument mode.

setValue

protected void setValue(java.lang.String verb,
                        java.lang.String directObject,
                        java.lang.String longFlagName,
                        java.lang.Object value)

Internal setter for raw parameter value.

Parameters:

verb - The verb name, including GLOBAL_FLAG_VERB.

directObject - The direct object name, including NO_VERB_OBJECT.

longFlagName - The long flag name for the given action.

value - The new current value object stored in the parameter, which depends on the argument mode.

parseArgs

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

Parses the command-line arguments.

This method will exit and not return if a parsing error arise.

Parameters:

args - The arguments typically received by a main method.

findLongArg

protected CommandLineParser.Arg findLongArg(java.lang.String verb,
                                            java.lang.String directObject,
                                            java.lang.String longName)

Finds an CommandLineParser.Arg given an action name and a long flag name.

Returns:

The CommandLineParser.Arg found or null.

findShortArg

protected CommandLineParser.Arg findShortArg(java.lang.String verb,
                                             java.lang.String directObject,
                                             java.lang.String shortName)

Finds an CommandLineParser.Arg given an action name and a short flag name.

Returns:

The CommandLineParser.Arg found or null.

printHelpAndExit

public void printHelpAndExit(java.lang.String errorFormat,
                             java.lang.Object... args)

Prints the help/usage and exits.

Parameters:

errorFormat - Optional error message to print prior to usage using String.format

args - Arguments for String.format

printHelpAndExitForAction

public void printHelpAndExitForAction(java.lang.String verb,
                                      java.lang.String directObject,
                                      java.lang.String errorFormat,
                                      java.lang.Object... args)

Prints the help/usage and exits.

Parameters:

verb - If null, displays help for all verbs. If not null, display help only for that specific verb. In all cases also displays general usage and action list.

directObject - If null, displays help for all verb objects. If not null, displays help only for that specific action In all cases also display general usage and action list.

errorFormat - Optional error message to print prior to usage using String.format

args - Arguments for String.format

listOptions

protected void listOptions(java.lang.String verb,
                           java.lang.String directObject)

Internal helper to print all the option flags for a given action name.

define

protected void define(CommandLineParser.Mode mode,
                      boolean mandatory,
                      @NonNull
                      java.lang.String verb,
                      @NonNull
                      java.lang.String directObject,
                      @NonNull
                      java.lang.String shortName,
                      @NonNull
                      java.lang.String longName,
                      @NonNull
                      java.lang.String description,
                      @Nullable
                      java.lang.Object defaultValue)

Internal helper to define a new argument for a give action.

Parameters:

mode - The CommandLineParser.Mode for the argument.

mandatory - The argument is required (never if CommandLineParser.Mode.BOOLEAN)

verb - The verb name. Never null. Can be GLOBAL_FLAG_VERB.

directObject - The action name. Can be NO_VERB_OBJECT.

shortName - The one-letter short argument name. Can be empty but not null.

longName - The long argument name. Can be empty but not null.

description - The description. Cannot be null.

defaultValue - The default value (or values), which depends on the selected CommandLineParser.Mode.

exit

protected void exit()

Exits in case of error. This is protected so that it can be overridden in unit tests.

stdout

protected void stdout(java.lang.String format,
                      java.lang.Object... args)

Prints a line to stdout. This is protected so that it can be overridden in unit tests.

Parameters:

format - The string to be formatted. Cannot be null.

args - Format arguments.

stderr

protected void stderr(java.lang.String format,
                      java.lang.Object... args)

Prints a line to stderr. This is protected so that it can be overridden in unit tests.

Parameters:

format - The string to be formatted. Cannot be null.

args - Format arguments.

getLog

protected com.android.utils.ILogger getLog()

Returns the logger object.

Returns:

the logger object.