com.twitter.common.args
Class ArgScanner

java.lang.Object
  extended by com.twitter.common.args.ArgScanner

public final class ArgScanner
extends Object

Argument scanning, parsing, and validating system. This class is designed recursively scan a package for declared arguments, parse the values based on the declared type, and validate against any constraints that the arugment is decorated with. The supported argument formats are: -arg_name=arg_value -arg_name arg_value Where arg_value may be single or double-quoted if desired or necessary to prevent splitting by the terminal application. A special format for boolean arguments is also supported. The following syntaxes all set the bool_arg to true: -bool_arg -bool_arg=true -no_bool_arg=false (double negation) Likewise, the following would set bool_arg to false: -no_bool_arg -bool_arg=false -no_bool_arg=true (negation) As with the general argument format, spaces may be used in place of equals for boolean argument assignment. TODO(William Farner): Make default verifier and parser classes package-private and in this package.


Nested Class Summary
static class ArgScanner.ArgScanException
          Indicates a problem scanning @CmdLine arg definitions.
 
Field Summary
static Ordering<OptionInfo> ORDER_BY_NAME
           
 
Constructor Summary
ArgScanner()
          Equivalent to calling ArgScanner(PrintStream) passing System.out.
ArgScanner(PrintStream out)
          Creates a new ArgScanner that prints help on arg parse failure or when help is requested to out or else prints applied argument information to out when parsing is successful.
 
Method Summary
 boolean parse(com.twitter.common.args.Args.ArgumentInfo argumentInfo, Iterable<String> args)
          Parse command line arguments given a Args.ArgumentInfo
 boolean parse(Iterable<String> args)
          Applies the provided argument values to all @CmdLine Arg fields discovered on the classpath.
 boolean parse(Predicate<Field> filter, Iterable<String> args)
          Applies the provided argument values to any @CmdLine or @Positional Arg fields discovered on the classpath and accepted by the given filter.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ORDER_BY_NAME

public static final Ordering<OptionInfo> ORDER_BY_NAME
Constructor Detail

ArgScanner

public ArgScanner()
Equivalent to calling ArgScanner(PrintStream) passing System.out.


ArgScanner

public ArgScanner(PrintStream out)
Creates a new ArgScanner that prints help on arg parse failure or when help is requested to out or else prints applied argument information to out when parsing is successful.

Parameters:
out - An output stream to write help and parsed argument info to.
Method Detail

parse

public boolean parse(Iterable<String> args)
Applies the provided argument values to all @CmdLine Arg fields discovered on the classpath.

Parameters:
args - Argument values to map, parse, validate, and apply.
Returns:
true if the given args were successfully applied to their corresponding Arg fields.
Throws:
ArgScanner.ArgScanException - if there was a problem loading @CmdLine argument definitions
IllegalArgumentException - If the arguments provided are invalid based on the declared arguments found.

parse

public boolean parse(Predicate<Field> filter,
                     Iterable<String> args)
Applies the provided argument values to any @CmdLine or @Positional Arg fields discovered on the classpath and accepted by the given filter.

Parameters:
filter - A predicate that selects or rejects scanned @CmdLine fields for argument application.
args - Argument values to map, parse, validate, and apply.
Returns:
true if the given args were successfully applied to their corresponding Arg fields.
Throws:
ArgScanner.ArgScanException - if there was a problem loading @CmdLine argument definitions
IllegalArgumentException - If the arguments provided are invalid based on the declared arguments found.

parse

public boolean parse(com.twitter.common.args.Args.ArgumentInfo argumentInfo,
                     Iterable<String> args)
Parse command line arguments given a Args.ArgumentInfo

Parameters:
argumentInfo - A description of any optional and positional arguments
args - A sequence of strings from the command-line
Returns:
true if the given args were successfully applied to their corresponding Arg fields.
Throws:
ArgScanner.ArgScanException - if there was a problem loading @CmdLine argument definitions
IllegalArgumentException - If the arguments provided are invalid based on the declared arguments found.