diff options
Diffstat (limited to 'third_party/java/jopt-simple/src/site/apt/examples.apt')
| -rw-r--r-- | third_party/java/jopt-simple/src/site/apt/examples.apt | 462 |
1 files changed, 462 insertions, 0 deletions
diff --git a/third_party/java/jopt-simple/src/site/apt/examples.apt b/third_party/java/jopt-simple/src/site/apt/examples.apt new file mode 100644 index 0000000000..3b43dee995 --- /dev/null +++ b/third_party/java/jopt-simple/src/site/apt/examples.apt @@ -0,0 +1,462 @@ + ----------------- + Examples of Usage + ----------------- + +Preamble + + The simplicity in JOpt "Simple" arises from two guiding principles: + + * Stick as often as possible to supporting conventional Unix option syntaxes. + + * Keep the surface area of the published API as small and simple as possible. + + [] + + To the first principle: You will not see support in JOpt Simple for option "groups", + alternative option prefixes (<<<+>>>, <<</>>>), enforced multiplicity of option + arguments, etc. JOpt Simple believes you can create a useful and understandable CLI + without all that stuff. If you feel as though you need any of those features, there + are lots of other choices out there. The author of JOpt Simple believes you'll want + to leverage its easy configuration, parsing, and option interrogation APIs instead of + using more feature-laden, but perhaps more confusing libraries. + + To the second principle: JOpt Simple will make every attempt to keep the API free + of clutter. The API is well factored, making it intuitive to use, and the entire + library is well tested, making it more reliable and predictable. If you cannot look + at the Javadoc and quickly get a sense of what you need to do to use JOpt Simple, + then JOpt Simple has failed. So by all means, let the author know what needs + improved. + + With that said, let's take a tour through JOpt Simple's features. + +Options + + JOpt Simple supports short options and long options, using a syntax that attempts to + take from the best of POSIX <<<getopt()>>> and GNU <<<getopt_long()>>>. + +* Short Options + + Short options begin with a single hyphen (<<<->>>) followed by a single letter or + digit, or question mark (<<<?>>>), or dot (<<<.>>>). + ++---------------------------------------------------------------------------------------- +@SHORT_OPTIONS_EXAMPLE@ ++---------------------------------------------------------------------------------------- + + When you construct an <<<OptionParser>>> with a string of short option characters, + you configure that parser to recognize the options with those characters. + +** Arguments of Options + + Short options can accept single arguments. The argument can be made required or + optional. When you construct an <<<OptionParser>>> with a string of short option + characters, append a single colon (<<<:>>>) to an option character to configure + that option to require an argument. Append two colons (<<<::>>>) to an option + character to configure that option to accept an optional argument. Append an + asterisk (<<<*>>>) to an option character, but before any "argument" indicators, + to configure that option as a "help" option. + + The syntax of the option specification string given to the <<<OptionParser>>> + constructor should look familiar to you if you have used GNU's <<<getopt()>>> + before. + ++---------------------------------------------------------------------------------------- +@SHORT_OPTIONS_WITH_ARGUMENTS_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +*** Specifying Arguments for a Short Option on the Command Line + + A short option's argument can occur: + + * in the position on the command line after the option + + * right up against the option + + * right up against the option separated by an equals sign (<<<=>>>) + + [] + ++---------------------------------------------------------------------------------------- +@SHORT_OPTIONS_WITH_ARGUMENT_POSITIONING_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +*** Multiple Arguments for a Single Option + + To specify <n> arguments for a single option, specify the option <n> times on the + command line, once for each argument. JOpt Simple reports the arguments given to the + option in the order in which they were encountered on the command line. + ++---------------------------------------------------------------------------------------- +@SHORT_OPTIONS_WITH_MULTIPLE_ARGUMENTS_FOR_SINGLE_OPTION_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +** Clustering Short Options + + Short options can be <clustered> in a single argument. + ++---------------------------------------------------------------------------------------- +@SHORT_OPTIONS_CLUSTERING_EXAMPLE@ ++---------------------------------------------------------------------------------------- + + If one of the short options can accept an argument, the remaining characters are interpreted + as the argument for that option. + ++---------------------------------------------------------------------------------------- +@SHORT_OPTIONS_CLUSTERING_WITH_ARGUMENT_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +* Long Options/Fluent Interface + + Long options begin with two hyphens (<<<-->>>), followed by multiple letters, + digits, hyphens, question marks, or dots. A hyphen cannot be the first character of + a long option specification when configuring the parser. + + Whereas short options can be configured using a constructor argument to + <<<OptionParser>>>, both long and short options can be configured using a "fluent + interface" API, that enables some very descriptive and powerful features. + ++---------------------------------------------------------------------------------------- +@LONG_OPTIONS_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +** Arguments of Options + + Like short options, long options can accept single arguments. The argument can be + made required or optional. Use the methods <<<withRequiredArg()>>> and + <<<withOptionalArg()>>> on the return value of <<<OptionParser.accepts()>>> to signal + that an option takes a required or optional argument. + ++---------------------------------------------------------------------------------------- +@LONG_OPTIONS_WITH_ARGUMENTS_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +** Abbreviating Long Options + + Notice in the example above that the command line uses abbreviations of command line + options. You can abbreviate options so long as the abbreviation is unambiguous. + Even though you can abbreviate the options on the command line, you cannot address + the <<<OptionSet>>> using those abbreviations. You can use a special constructor + for the <<<OptionParser>>> that turns off abbreviation matching. + +** Using Single Hyphen on Long Options + + As demonstrated in the example above, you can use a single hyphen instead of a + double hyphen to specify a long option -- but be careful that doing so doesn't + introduce ambiguity. + +*** Specifying Arguments for a Long Option on the Command Line + + A long option's argument can occur: + + * in the position on the command line after the option + + * right up against the option separated by an equals sign (<<<=>>>) + + [] + ++---------------------------------------------------------------------------------------- +@LONG_OPTIONS_WITH_ARGUMENT_POSITIONING_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +*** Multiple Arguments for a Single Option + + Specify multiple arguments for a long option in the same manner as for short options + (see above). + +** Alternative Form of Long Options + + The option <<<-W>>> is reserved. If you tell the parser to recognize alternative + long options, then it will treat, for example, <<<-W foo=bar>>> as the long option + <<<foo>>> with argument bar, as though you had written <<<--foo=bar>>>. + + You can specify <<<-W>>> as a valid short option, or use it as an abbreviation for a + long option, but recognizing alternative long options will always supersede this + behavior. + + To recognize alternative long options, either construct an <<<OptionParser>>> with a + string of short option characters containing the sequence <<<W;>>> (a capital W + followed by a semicolon), or call the method + <<<OptionParser.recognizeAlternativeLongOptions()>>>. + ++---------------------------------------------------------------------------------------- +@ALTERNATIVE_LONG_OPTIONS_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +* Other Features + +** Converting Option Arguments to Other Types + + Without action other than the <<<with*Arg()>>> methods, arguments of options are + returned as <<<String>>>s. For backwards compatibility, + <<<OptionSet.valueOf(String)>>> and <<<OptionSet.valuesOf(String)>>> return + <<<Object>>> and <<<List<?>>>>, respectively, so to get the values out as + <<<String>>>s, you will need to downcast the results of those methods. + + You can tell JOpt Simple to convert the arguments of options to different Java types + via the <<<ofType()>>> method on the return value of <<<with*Arg()>>>. The + <<<Class>>> argument of <<<ofType()>>> must represent a Java class that has either: + + * a <<<public static>>> method called <<<valueOf()>>> which accepts a single + <<<String>>> argument and whose return type is the type itself, or + + * a <<<public>>> constructor which takes a single <<<String>>> argument. + + [] + + If the class has both, the <<<valueOf()>>> method is used. + + Note that <<<enum>>>s have a <<<valueOf()>>> method. + ++---------------------------------------------------------------------------------------- +@OPTION_ARGUMENT_VALUE_TYPE_EXAMPLE@ ++---------------------------------------------------------------------------------------- + + Another way to convert arguments of options is to specify a converter object via + <<<withValuesConvertedBy()>>>. This is useful when the desired type for the arguments + does not meet the requirements that <<<ofType()>>> sets forth. Such objects may not + perform any "conversion" at all, but rather can validate that arguments conform to + certain restrictions before passing through as-is. + + You can also do this for the non-option arguments of your command line, if you desire + to treat them all as a single type. + ++---------------------------------------------------------------------------------------- +@OPTION_ARGUMENT_CONVERTER_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +** Retrieving Arguments of Options in a Type-Safe Manner + + In the previous examples, we have been discarding the return values of the methods + of JOpt Simple's fluent interface. If instead you retain them in variables of type + <<<OptionSpec>>>, you can use them to retrieve arguments of options in a type-safe + manner. + + You can also do this for the non-option arguments of your command line, if you desire + to treat them all as a single type. + ++---------------------------------------------------------------------------------------- +@TYPESAFE_OPTION_ARGUMENT_RETRIEVAL_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +** Exporting Options and Arguments to other Code + + As an integration aid for other libraries, you can use <<<OptionSet.asMap()>>> to + obtain a mapping of <<<OptionSpec>>> to option values, for example to create a + properties map of options. + + Here is sample code to create properties whose keys have a common prefix. The key is + choosen as the first non-short option: + ++---------------------------------------------------------------------------------------- +@EXPORTING_OPTIONS_AND_ARGUMENTS_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +** Default Values for Option Arguments + + Often it is convenient to specify default values for the arguments of certain + command line options. To do this, call the <<<defaultsTo()>>> method. + ++---------------------------------------------------------------------------------------- +@DEFAULT_VALUES_FOR_OPTION_ARGUMENTS_EXAMPLE@ ++---------------------------------------------------------------------------------------- + + You can see that <<<defaultsTo()>>> should relieve you of the burden of having to + check <<<has()>>> and/or <<<hasArgument()>>> on an <<<OptionSet>>> for a given option, + and has no bearing on the return values of those methods. Specifying a default value + for an option with a required argument does not mean that you can elide an argument for + the option on the command line. + + The type of values <<<defaultsTo()>>> expects is dictated by the class given by a + previous call to <<<ofType()>>> or <<<withValuesConvertedBy()>>>; if no such call has + been made, the type is <<<String>>>. + +** "Required" Options + + You can indicate that a given option must be present on the command line via the + <<<required()>>> method. Only options that accept arguments can be made "required". + + An option designated as a "help" option via <<<forHelp()>>>, when present on the + command line, causes missing "required" options not to reject the command line. + ++---------------------------------------------------------------------------------------- +@REQUIRED_OPTIONS_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +** "Required" Dependent Options + + You can indicate that a given option must be present on the command line if some + other option is present on the command line via the <<<requiredIf()>>> method. + Any option can be made "required if". + + An option designated as a "help" option via <<<forHelp()>>>, when present on the + command line, causes missing "required if" options not to reject the command line. + ++---------------------------------------------------------------------------------------- +@REQUIRED_IF_OPTIONS_EXAMPLE@ ++---------------------------------------------------------------------------------------- + + You can also indicate that a given option must be present on the command line if some + other option is NOT present on the command line via the <<<requiredUnless()>>> method. + Any option can be made "required unless", but, to avoid potential conflicts, it should + not be "required if" at the same time. + ++---------------------------------------------------------------------------------------- +@REQUIRED_UNLESS_OPTIONS_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +** "Available" Dependent Options + + Similarly to <<<requiredIf()>>> and <<<requiredUnless()>>>, you can indicate that a + given option can be present on the command line only if/unless some other option is + present on the command line, via the <<<availableIf()>>> and <<<availableUnless()>>> + methods. + + +** Synonyms of Options + + Sometimes it is useful to allow many different options to share the same meaning in + the program that uses them. To specify that options are to be treated as synonymous, + use the <<<acceptsAll()>>> method of <<<OptionParser>>>. + ++---------------------------------------------------------------------------------------- +@OPTION_SYNONYM_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +** Concise Specification of Multiple Arguments for an Option + + Another way to specify multiple arguments for an option is to tell the parser to + treat a single argument containing multiple delimited values as multiple arguments + for the option using the <<<withValuesSeparatedBy()>>> method. + ++---------------------------------------------------------------------------------------- +@MULTIPLE_DELIMITED_ARGUMENTS_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +** Signalling End of Options + + An argument consisting only of two hyphens (<<<-->>>) signals that the remaining + arguments are to be treated as non-options. + + An argument consisting only of a single hyphen is considered a non-option argument + (though it can be an argument of an option). Many Unix programs treat single hyphens + as stand-ins for the standard input or standard output stream. + +*** Non-Option Arguments + + Any arguments which are not options or arguments of options can be retrieved via + method <<<nonOptionArguments()>>> on <<<OptionSet>>>. If the double hyphen is an + argument, it is ignored and is not a non-option argument. + ++---------------------------------------------------------------------------------------- +@SIGNALLING_END_OF_OPTIONS_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +** "POSIX-ly Correct"-ness + + By default, as with GNU <<<getopt()>>>, JOpt Simple allows intermixing of options and + non-options. If, however, the parser has been created to be "POSIX-ly correct", then + the first argument that does not look lexically like an option, and is not a required + argument of a preceding option, signals the end of options. You can still bind + optional arguments to their options using the abutting (for short options) or + <<<=>>> syntax. + + Unlike GNU <<<getopt()>>>, JOptSimple does not honor the environment variable + <<<POSIXLY_CORRECT>>>. "POSIX-ly correct" parsers are configured by either: + + * using the method <<<OptionParser.posixlyCorrect()>>> + + * using the <<<OptionParser>>> constructor with an argument whose first character is + a plus sign (<<<+>>>) + + [] + ++---------------------------------------------------------------------------------------- +@POSIXLY_CORRECT_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +** Special Optional Argument Handling + + If the parser detects an option whose argument is optional, and the next argument + "looks like" an option, that argument is not treated as the argument to the option, + but as a potentially valid option. If, on the other hand, the optional argument is + typed as a derivative of <<<Number>>>, then that argument is treated as the negative + number argument of the option, even if the parser recognizes the corresponding numeric + option. + ++---------------------------------------------------------------------------------------- +@SPECIAL_OPTIONAL_ARGUMENT_HANDLING_EXAMPLE@ ++---------------------------------------------------------------------------------------- + +Generating Command Line Help + + When you call method <<<OptionParser.printHelpOn()>>>, JOpt Simple will write a + help screen (80-column width) describing all the options it is configured with, + along with types of option arguments, whether the option is required (in angle + brackets) or optional (in square brackets), etc. To give an option a description, + use <<<OptionParser.accepts*()>>> with a description argument. To give an option + argument a description, use <<<describedAs()>>> on the return value of + <<<with*Arg()>>>. + ++---------------------------------------------------------------------------------------- +@HELP_SCREEN_EXAMPLE@ ++---------------------------------------------------------------------------------------- + + Here is what the help screen looks like for the example above: + ++---------------------------------------------------------------------------------------- +@HELP_SCREEN_EXAMPLE_HELP@ ++---------------------------------------------------------------------------------------- + + If you want to create your own help screen, give method + <<<OptionParser.formatHelpWith()>>> a <<<HelpFormatter>>> that builds the help screen + as a String. When you call <<<OptionParser.printHelpOn()>>>, JOpt Simple will use + your <<<HelpFormatter>>> to produce the help and write it to the given stream. + + For example, this program: + ++---------------------------------------------------------------------------------------- +@HELP_FORMATTER_EXAMPLE@ ++---------------------------------------------------------------------------------------- + + yields the following output: + ++---------------------------------------------------------------------------------------- +@HELP_FORMATTER_EXAMPLE_OUTPUT@ ++---------------------------------------------------------------------------------------- + +Handling Exceptions + + JOpt Simple's classes raise some derivative of <<<OptionException>>> if they encounter + problems during parsing. These exceptions are unchecked, so you don't have to do + anything with such an exception if you don't want to. The rationale behind this + decision is that you will most likely be invoking JOpt Simple's functionality from a + <<<main()>>> method or very near to it, where a failure such as unrecognized arguments + can just stop down the JVM and yield a stack trace without much user or programmer + inconvenience. So, without any exception handling at all, a user would see something + like this: + ++---------------------------------------------------------------------------------------- +@EXAMPLE_STACK_TRACE@ ++---------------------------------------------------------------------------------------- + + If you want to handle the exception yourself, you can catch <<<OptionException>>> in + your code, and do whatever you please with the contents of the exception, perhaps + using the help generation facility. + +* Suppressing <<<UnrecognizedOptionException>>> + + Sometimes you want to ignore unrecognized options on the command line. + + For example, you might be interested in handling only a part of the arguments given. + Or you might want to pass on options to another program and not bother the user with + providing two hyphens (<<<-->>>) to indicate the end of known options. Or maybe + you want to provide future forwards/backwards compatibility when you foresee passing + in new options to old code (or old code invoking new code with "old" arguments). + + You can achieve this by using the method <<<OptionParser.allowsUnrecognizedOptions()>>>. + When you call this method, then any unrecognized options handed to <<<parse()>>> are + treated as non-option arguments, rather than causing an exception to be raised. + ++---------------------------------------------------------------------------------------- +@UNRECOGNIZED_OPTIONS_ALLOWED_EXAMPLE@ ++---------------------------------------------------------------------------------------- |