picard.cmdline

## Class CommandLineParser

- java.lang.Object
- - picard.cmdline.CommandLineParser

-     public class CommandLineParser
      extends Object

  Annotation-driven utility for parsing command-line arguments, checking for errors, and producing usage message.

  This class supports options of the form KEY=VALUE, plus positional arguments. Positional arguments must not contain an equal sign lest they be mistaken for a KEY=VALUE pair.

  The caller must supply an object that both defines the command line and has the parsed options set into it. For each possible KEY=VALUE option, there must be a public data member annotated with @Option. The KEY name is the name of the data member. An abbreviated name may also be specified with the shortName attribute of @Option. If the data member is a List<T>, then the option may be specified multiple times. The type of the data member, or the type of the List element must either have a ctor T(String), or must be an Enum. List options must be initialized by the caller with some kind of list. Any other option that is non-null is assumed to have the given value as a default. If an option has no default value, and does not have the optional attribute of @Option set, is required. For List options, minimum and maximum number of elements may be specified in the @Option annotation.

  A single List data member may be annotated with the @PositionalArguments. This behaves similarly to a Option with List data member: the caller must initialize the data member, the type must be constructable from String, and min and max number of elements may be specified. If no @PositionalArguments annotation appears in the object, then it is an error for the command line to contain positional arguments.

  A single String public data member may be annotated with @Usage. This string, if present, is used to construct the usage message. Details about the possible options are automatically appended to this string. If @Usage does not appear, a boilerplate usage message is used.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `CommandLineParser.ClpEnum`
    `protected static class` | `CommandLineParser.OptionDefinition`
    `protected static class` | `CommandLineParser.OptionDefinitionByPrintOrderComparator`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `File` | `IGNORE_THIS_PROPERTY` This attribute is here just to facilitate printing usage for OPTIONS_FILE

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CommandLineParser(Object callerOptions)` Prepare for parsing command line arguments, by validating annotations.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `String[]` | `getArgv()`
    `Object` | `getCallerOptions()`
    `String` | `getCommandLine()` The commandline used to run this program, including any default args that weren't necessarily specified.
    `static String` | `getFaqLink()`
    `static String` | `getStandardUsagePreamble(Class mainClass)` A typical command line program will call this to get the beginning of the usage message, and then append a description of the program, like this: \@Usage public String USAGE = CommandLineParser.getStandardUsagePreamble(getClass()) + "Frobnicates the freebozzle."
    `String` | `getVersion()`
    `static boolean` | `hasWebDocumentation(Class clazz)` Determines if a class has web documentation based on its package name
    `void` | `htmlPrintOptions(PrintStream stream, boolean printCommon)`
    `void` | `htmlUsage(PrintStream stream, String programName, boolean printCommon)`
    `boolean` | `parseOptions(PrintStream messageStream, String[] args)` Parse command-line options, and store values in callerOptions object passed to ctor.
    `boolean` | `parseOptionsFile(String optionsFile, boolean optionFileStyleValidation)`
    `void` | `setMessageStream(PrintStream messageStream)` This method is only needed when calling one of the public methods that doesn't take a messageStream argument.
    `void` | `usage(PrintStream stream, boolean printCommon)` Print a usage message based on the options object passed to the ctor.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### IGNORE_THIS_PROPERTY

          public File IGNORE_THIS_PROPERTY

      This attribute is here just to facilitate printing usage for OPTIONS_FILE

  - ### Constructor Detail

    - #### CommandLineParser

          public CommandLineParser(Object callerOptions)

      Prepare for parsing command line arguments, by validating annotations.
      Parameters:
        `callerOptions` - This object contains annotations that define the acceptable command-line options, and ultimately will receive the settings when a command line is parsed.

  - ### Method Detail

    - #### getStandardUsagePreamble

          public static String getStandardUsagePreamble(Class mainClass)

      A typical command line program will call this to get the beginning of the usage message, and then append a description of the program, like this:

      \@Usage public String USAGE = CommandLineParser.getStandardUsagePreamble(getClass()) + "Frobnicates the freebozzle."

    - #### hasWebDocumentation

          public static boolean hasWebDocumentation(Class clazz)

      Determines if a class has web documentation based on its package name
      Parameters:
        `clazz` -
      Returns:
        true if the class has web documentation, false otherwise

    - #### getFaqLink

          public static String getFaqLink()

      Returns:
        the link to a FAQ

    - #### getVersion

          public String getVersion()

    - #### usage

          public void usage(PrintStream stream,
                            boolean printCommon)

      Print a usage message based on the options object passed to the ctor.
      Parameters:
        `stream` - Where to write the usage message.

    - #### htmlUsage

          public void htmlUsage(PrintStream stream,
                                String programName,
                                boolean printCommon)

    - #### htmlPrintOptions

          public void htmlPrintOptions(PrintStream stream,
                                       boolean printCommon)

    - #### parseOptions

          public boolean parseOptions(PrintStream messageStream,
                                      String[] args)

      Parse command-line options, and store values in callerOptions object passed to ctor.
      Parameters:
        `messageStream` - Where to write error messages.
        `args` - Command line tokens.
      Returns:
        true if command line is valid.

    - #### parseOptionsFile

          public boolean parseOptionsFile(String optionsFile,
                                          boolean optionFileStyleValidation)

      Parameters:
        `optionFileStyleValidation` - true: unrecognized options are silently ignored; and a single-valued option may be overridden. false: standard rules as if the options in the file were on the command line directly.
      Returns:

    - #### getArgv

          public String[] getArgv()

    - #### getCommandLine

          public String getCommandLine()

      The commandline used to run this program, including any default args that weren't necessarily specified. This is used for logging and debugging.

      NOTE: `parseOptions(PrintStream, String[])` must be called before calling this method.
      Returns:
        The commandline, or null if `parseOptions(PrintStream, String[])` hasn't yet been called, or didn't complete successfully.

    - #### setMessageStream

          public void setMessageStream(PrintStream messageStream)

      This method is only needed when calling one of the public methods that doesn't take a messageStream argument.

    - #### getCallerOptions

          public Object getCallerOptions()