ArgsOptionParser

public class ArgsOptionParser
extends OptionSetter

java.lang.Object
   ↳ com.android.tradefed.config.OptionSetter
     ↳ com.android.tradefed.config.ArgsOptionParser


Populates Option fields from parsed command line arguments.

Strings in the passed-in String[] are parsed left-to-right. Each String is classified as a short option (such as "-v"), a long option (such as "--verbose"), an argument to an option (such as "out.txt" in "-f out.txt"), or a non-option positional argument.

Each option argument must map to one or more Option fields. A long option maps to the Option name, and a short option maps to Option short name. Each option name and option short name must be unique with respect to all other Option fields within the same object.

A single option argument can get mapped to multiple Option fields with the same name across multiple objects. Option arguments can be namespaced to uniquely refer to an Option field within a single object using that object's full class name or its OptionClass alias value separated by ':'. ie

 --classname:optionname optionvalue or
 --optionclassalias:optionname optionvalue.
 

A simple short option is a "-" followed by a short option character. If the option requires an argument (which is true of any non-boolean option), it may be written as a separate parameter, but need not be. That is, "-f out.txt" and "-fout.txt" are both acceptable.

It is possible to specify multiple short options after a single "-" as long as all (except possibly the last) do not require arguments.

A long option begins with "--" followed by several characters. If the option requires an argument, it may be written directly after the option name, separated by "=", or as the next argument. (That is, "--file=out.txt" or "--file out.txt".)

A boolean long option '--name' automatically gets a '--no-name' companion. Given an option "--flag", then, "--flag", "--no-flag", "--flag=true" and "--flag=false" are all valid, though neither "--flag true" nor "--flag false" are allowed (since "--flag" by itself is sufficient, the following "true" or "false" is interpreted separately). You can use "yes" and "no" as synonyms for "true" and "false".

Each String not starting with a "-" and not a required argument of a previous option is a non-option positional argument, as are all successive Strings. Each String after a "--" is a non-option positional argument.

The fields corresponding to options are updated as their options are processed. Any remaining positional arguments are returned as a List<String>.

Here's a simple example:

 // Non-@Option fields will be ignored.
 class Options {
     @Option(name = "quiet", shortName = 'q')
     boolean quiet = false;

     // Here the user can use --no-color.
     @Option(name = "color")
     boolean color = true;

     @Option(name = "mode", shortName = 'm')
     String mode = "standard; // Supply a default just by setting the field.

     @Option(name = "port", shortName = 'p')
     int portNumber = 8888;

     // There's no need to offer a short name for rarely-used options.
     @Option(name = "timeout" )
     double timeout = 1.0;

     @Option(name = "output-file", shortName = 'o' })
     File output;

     // Multiple options are added to the collection.
     // The collection field itself must be non-null.
     @Option(name = "input-file", shortName = 'i')
     List<File> inputs = new ArrayList<File>();

 }

 Options options = new Options();
 List<String> posArgs = new OptionParser(options).parse("--input-file", "/tmp/file1.txt");
 for (File inputFile : options.inputs) {
     if (!options.quiet) {
        ...
     }
     ...

 }

 
See also:
  • the getopt(1) man page
  • Python's "optparse" module (http://docs.python.org/library/optparse.html)
  • the POSIX "Utility Syntax Guidelines" (http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap12.html#tag_12_02)
  • the GNU "Standards for Command Line Interfaces" (http://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfaces)

See also:

Summary

Constants

String OPTION_NAME_PREFIX

String SHORT_NAME_PREFIX

Fields

static final Pattern BOOL_FALSE_DEVICE_PATTERN

Public constructors

ArgsOptionParser(Collection<Object> optionSources)

Creates a ArgsOptionParser for a collection of objects.

ArgsOptionParser(Object... optionSources)

Creates a ArgsOptionParser for one or more objects.

Public methods

static String getOptionHelp(boolean importantOnly, Object optionObject)

Output help text for all Option fields in optionObject.

List<String> parse(List<String> args)

Alternate parse(String) method that takes a List of arguments

List<String> parse(String... args)

Parses the command-line arguments 'args', setting the @Option fields of the 'optionSource' provided to the constructor.

List<String> parseBestEffort(List<String> args)

Alternate parseBestEffort(String) method that takes a List of arguments

List<String> parseBestEffort(String... args)

A best-effort version of parse(String).

void validateMandatoryOptions()

Validates that all fields marked as mandatory have been set.

Constants

OPTION_NAME_PREFIX

String OPTION_NAME_PREFIX

Constant Value: "--"

SHORT_NAME_PREFIX

String SHORT_NAME_PREFIX

Constant Value: "-"

Fields

BOOL_FALSE_DEVICE_PATTERN

Pattern BOOL_FALSE_DEVICE_PATTERN

Public constructors

ArgsOptionParser

ArgsOptionParser (Collection<Object> optionSources)

Creates a ArgsOptionParser for a collection of objects.

Parameters
optionSources Collection: the config objects.

Throws
ConfigurationException if config objects is improperly configured.

ArgsOptionParser

ArgsOptionParser (Object... optionSources)

Creates a ArgsOptionParser for one or more objects.

Parameters
optionSources Object: the config objects.

Throws
ConfigurationException if config objects is improperly configured.

Public methods

getOptionHelp

String getOptionHelp (boolean importantOnly, 
                Object optionObject)

Output help text for all Option fields in optionObject.

The help text for each option will be in the following format

   [-option_shortname, --option_name]          [option_description] Default:
   [current option field's value in optionObject]
 
The 'Default..." text will be omitted if the option field is null or empty.

Parameters
importantOnly boolean: if true only print help for the important options

optionObject Object: the object to print help text for

Returns
String a String containing user-friendly help text for all Option fields

parse

List<String> parse (List<String> args)

Alternate parse(String) method that takes a List of arguments

Parameters
args List

Returns
List<String> a List of the positional arguments left over after processing all options.

Throws
ConfigurationException if error occurred parsing the arguments.

parse

List<String> parse (String... args)

Parses the command-line arguments 'args', setting the @Option fields of the 'optionSource' provided to the constructor.

Parameters
args String

Returns
List<String> a List of the positional arguments left over after processing all options.

Throws
ConfigurationException if error occurred parsing the arguments.

parseBestEffort

List<String> parseBestEffort (List<String> args)

Alternate parseBestEffort(String) method that takes a List of arguments

Parameters
args List

Returns
List<String> a List of the left over arguments

parseBestEffort

List<String> parseBestEffort (String... args)

A best-effort version of parse(String). If a ConfigurationException is thrown, that exception is captured internally, and the remaining arguments (including the argument which caused the exception to be thrown) are returned. This method does not throw.

Parameters
args String

Returns
List<String> a List of the left over arguments

validateMandatoryOptions

void validateMandatoryOptions ()

Validates that all fields marked as mandatory have been set.

Throws
ConfigurationException