com.android.sdklib.util
Class CommandLineParser

java.lang.Object
  extended by 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:

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.