public class

ArgsOptionParser

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

Class Overview

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 ERROR(/Option#name), and a short option maps to ERROR(/Option#shortName). Each ERROR(/Option#name()) and ERROR(/Option#shortName()) 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 ERROR(/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)

Summary

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(String... args)
Parses the command-line arguments 'args', setting the @Option fields of the 'optionSource' provided to the constructor.
List<String> parse(List<String> args)
Alternate parse(String) method that takes a List of arguments
void validateMandatoryOptions()
Validates that all fields marked as ERROR(/Option#mandatory()) have been set.
[Expand]
Inherited Methods
From class com.android.tradefed.config.OptionSetter
From class java.lang.Object

Public Constructors

public ArgsOptionParser (Collection<Object> optionSources)

Creates a ArgsOptionParser for a collection of objects.

Parameters
optionSources the config objects.
Throws
ConfigurationException if config objects is improperly configured.

public ArgsOptionParser (Object... optionSources)

Creates a ArgsOptionParser for one or more objects.

Parameters
optionSources the config objects.
Throws
ConfigurationException if config objects is improperly configured.

Public Methods

public static 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 if true only print help for the important options
optionObject the object to print help text for
Returns
  • a String containing user-friendly help text for all Option fields

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

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

Returns
  • a List of the positional arguments left over after processing all options.
Throws
ConfigurationException if error occurred parsing the arguments.

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

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

Returns
  • a List of the positional arguments left over after processing all options.
Throws
ConfigurationException if error occurred parsing the arguments.

public void validateMandatoryOptions ()

Validates that all fields marked as ERROR(/Option#mandatory()) have been set.