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) {
        ...
     }
     ...

 }

Summary

Public constructors
`ArgsOptionParser( optionSources)` Creates a `ArgsOptionParser` for a collection of objects.
`ArgsOptionParser(Object... optionSources)` Creates a `ArgsOptionParser` for one or more objects.

Public methods
	`getInopOptions()` Returns the set of options that did not change any default values.
`static String`	`getOptionHelp(boolean importantOnly, Object optionObject)` Output help text for all `Option` fields in optionObject.
	`parse(String... args)` Parses the command-line arguments 'args', setting the @Option fields of the 'optionSource' provided to the constructor.
	`parse( args)` Alternate `parse(String)` method that takes a `ERROR(/List)` of arguments
	`parseBestEffort( args)` Alternate `parseBestEffort(String)` method that takes a `ERROR(/List)` of arguments
	`parseBestEffort( args, boolean forceContinue)` Alternate `parseBestEffort(String)` method that takes a `ERROR(/List)` of arguments, and can be forced to continue parsing until the end, even if some args do not parse.
	`parseBestEffort(String... args)` A best-effort version of `parse(String)`.
`void`	`validateMandatoryOptions()` Validates that all fields marked as mandatory have been set.

Public constructors

ArgsOptionParser

public ArgsOptionParser ( optionSources)

Creates a ArgsOptionParser for a collection of objects.

Parameters
`optionSources`	: the config objects.

Throws
`ConfigurationException`	if config objects is improperly configured.

ArgsOptionParser

public 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

getInopOptions

public  getInopOptions ()

Returns the set of options that did not change any default values.

Returns

getOptionHelp

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`	`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

public  parse (String... args)

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

Parameters
`args`	`String`

Returns
	a `ERROR(/List)` of the positional arguments left over after processing all options.

Throws
`ConfigurationException`	if error occurred parsing the arguments.

parse

public  parse ( args)

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

Parameters
`args`

Returns
	a `ERROR(/List)` of the positional arguments left over after processing all options.

Throws
`ConfigurationException`	if error occurred parsing the arguments.

parseBestEffort

public  parseBestEffort ( args)

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

Parameters
`args`

Returns
	a `ERROR(/List)` of the left over arguments

parseBestEffort

public  parseBestEffort ( args, 
                boolean forceContinue)

Alternate parseBestEffort(String) method that takes a ERROR(/List) of arguments, and can be forced to continue parsing until the end, even if some args do not parse.

Parameters
`args`	: list that will contain the left over args.
`forceContinue`	`boolean`: True if it should continue to parse even if some args do not parse.

Returns
	a `ERROR(/List)` of the left over arguments

parseBestEffort

public  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
	a `ERROR(/List)` of the left over arguments

validateMandatoryOptions

public void validateMandatoryOptions ()

Validates that all fields marked as mandatory have been set.

Throws
	com.android.tradefed.config.ConfigurationException
`ConfigurationException`