Class CLOption

Object
CLOption
All Implemented Interfaces:
Comparable<CLOption>
public class CLOption extends Object implements Comparable<CLOption>
Command line option and argument.
Author:
Christoph Hauert

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    CLOption.Argument
    Types of command line options: REQUIRED required argument.
    static interface 
    CLOption.Key
    The interface for keys of command line options.
    static class 
    CLOption.SimpleKey
    Simple key for command line options.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) final CLOCategory
    category
    The category of the command line option.
    (package private) String
    defaultArg
    The default argument for option (if applicable).
    private CLODelegate
    delegate
    The delegate for parsing arguments, reporting settings and retrieving customized descriptions.
    (package private) String
    description
    the short description of the command line option.
    (package private) boolean
    inheritedKeys
    The flag to indicate if keys were inherited from another option.
    (package private) HashMap<String, CLOption.Key>
    keys
    The list of valid keys (if applicable).
    (package private) final String
    name
    The name of the command line option (required).
    (package private) String
    optionArg
    The argument provided on the command line (if any).
    (package private) final CLOption.Argument
    type
    The type of the command line option with no, optional, or required argument.

  • Constructor Summary

    Constructors
    Constructor
    Description
    CLOption(String name, String defaultArg, String description, CLODelegate delegate)
    Creates command line option with the name name (with required argument), which defaults to defaultArg, and brief description description as well as the delegate delegate to process the argument and optionally retrieve the description.
    CLOption(String name, String defaultArg, CLOCategory category, String description, CLODelegate delegate)
    Creates command line option with the name name (with required argument), which defaults to defaultArg, of catgeory category and brief description description as well as the delegate delegate to process the argument and optionally retrieve the description.
    CLOption(String name, String description, CLODelegate delegate)
    Creates command line option with the name name (no arguments) and short description description as well as the delegate delegate to process the argument and optionally retrieve the description.
    CLOption(String name, String defaultArg, CLOption.Argument type, String description, CLODelegate delegate)
    Creates command line option with the name name of type type, which defaults to defaultArg, and brief description description as well as the delegate delegate to process the argument and optionally retrieve the description.
    CLOption(String name, String defaultArg, CLOption.Argument type, CLOCategory category, String description, CLODelegate delegate)
    Creates command line option with the name name of type type, which defaults to defaultArg, in category category and brief description description as well as the delegate delegate to process the argument and optionally retrieve the description.
    CLOption(String name, String defaultArg, CLOption.Argument type, CLOCategory category, CLODelegate delegate)
    Creates command line option with the name name of type type, which defaults to defaultArg, and catgeory category as well as the delegate delegate to process the argument and retrieve the description.
    CLOption(String name, String defaultArg, CLOption.Argument type, CLODelegate delegate)
    Creates command line option with the name name of type type, which defaults to defaultArg, as well as the delegate delegate to process the argument and retrieve the description.
    CLOption(String name, CLOCategory category, String description, CLODelegate delegate)
    Creates command line option with the name name (no arguments) with category category and brief description description as well as the delegate delegate to process the argument and optionally retrieve the description.
    CLOption(String name, CLOCategory category, CLODelegate delegate)
    Creates command line option with the name name (no arguments) with category category and the delegate to process the argument and retrieve the description.
    CLOption(String name, CLODelegate delegate)
    Creates command line option with the name name and the delegate to process the argument and provide the description.

  • Method Summary

    Modifier and Type
    Method
    Description
    CLOption.Key
    addKey(String key, String title)
    Add a CLOption.Key to option with name key and description title.
    CLOption.Key
    addKey(CLOption.Key key)
    Add CLOption.Key key to option.
    void
    addKeys(CLOption.Key[] chain)
    Add all CLOption.Keys in the array chain to this option.
    private String
    buildArgKeys()
    Construct the user-facing representation of the argument when keys are defined; mirrors previous loop logic but extracted to reduce complexity.
    private StringBuilder
    buildBaseDescription()
    Build the base description string, using either the stored description or asking the delegate and appending key descriptions if applicable.
    private StringBuilder
    buildCurrent(StringBuilder sb, String currentArg)
    Append the current and default argument description to the provided builder.
    private CLOption.Key
    buildKey(StringBuilder sb, CLOption.Key key, String[] args, int pos)
    Append the resolved key value and remaining arguments to the builder.
    void
    clearKeys()
    Clear all keys from the option.
    int
    compareTo(CLOption opt)
     
    static int
    differAt(String a, String b)
    Compare two strings and return the index of the first character that differs.
    boolean
    equals(Object obj)
     
    String
    getArg()
    Get the option argument.
    String
    getDefault()
    Return the default argument for command line option.
    String
    getDescription()
    Retrieve short description of option and include the default as well as the current arguments.
    String
    getDescriptionKey()
    Get the description of all keys of this option.
    String
    getDescriptionKey(String aKey)
    Get the description of the key with name aKey.
    CLOption.Key
    getKey(String aKey)
    Get the key with name aKey.
    Collection<CLOption.Key>
    getKeys()
    Gets all keys of this option.
    String
    getName()
    Get the name of the option.
    CLOption.Argument
    getType()
    Get the type of the option.
    int
    hashCode()
     
    void
    inheritKeysFrom(CLOption option)
    Inherit keys from another option.
    boolean
    isSet()
    Check if option was set on command line (regardless of whether an argument was provided).
    boolean
    isValidKey(String aKey)
    Check if the key with name aKey is a valid key for this option.
    boolean
    isValidKey(CLOption.Key key)
    Check if key is a valid key for this option.
    CLOption.Key
    match(String keyname)
    Returns the key that best matches name.
    CLOption.Key
    match(String keyname, int min)
    Returns the key that best matches name with at least min characters matching.
    boolean
    parse()
    Parses the option and its argument, if applicable, through the delegate.
    private boolean
    parse(boolean isOptional)
    Delegate parsing helper that handles optional vs required arguments.
    CLOption.Key
    removeKey(String aKey)
    Remove key with name aKey from the option's key collection.
    CLOption.Key
    removeKey(CLOption.Key key)
    Remove key from the option's key collection.
    void
    reset()
    Reset option.
    void
    setArg(String arg)
    Set the argument for the command line option.
    void
    setDefault(String defaultArg)
    Set the default argument.
    void
    setDescription(String descr)
    Set short description of option.
    static String
    stripKey(String key, String arg)
    Strips the key from the argument.
    static String
    stripKey(CLOption.Key key, String arg)
    Strips the name of the key from the argument.

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • name

      final String name
      The name of the command line option (required).

    • type

      final CLOption.Argument type
      The type of the command line option with no, optional, or required argument.

    • category

      final CLOCategory category
      The category of the command line option. Used to structure the help screen.

    • description

      String description
      the short description of the command line option. May include newline's '\n' for basic formatting.

      Note: the description string may contain any UTF-8 characters as well as HTML character entities. If necessary they will be escaped and converted to UTF-8 for display in XML documents.

    • optionArg

      String optionArg
      The argument provided on the command line (if any).

    • defaultArg

      String defaultArg
      The default argument for option (if applicable).

    • keys

      HashMap<String, CLOption.Key> keys
      The list of valid keys (if applicable).

    • inheritedKeys

      boolean inheritedKeys
      The flag to indicate if keys were inherited from another option. If true the keys will not be printed as part of the description.

    • delegate

      private CLODelegate delegate
      The delegate for parsing arguments, reporting settings and retrieving customized descriptions.

  • Constructor Details

    • CLOption

      public CLOption(String name, CLODelegate delegate)
      Creates command line option with the name name and the delegate to process the argument and provide the description.

      Note:

      • on the command line option names need to be preceded by --, e.g. --help.
      • delegate must implement CLODelegate.getDescription() to provide option description.
      Parameters:
      name - the name of the command line option
      delegate - delegate for processing command line argument

    • CLOption

      public CLOption(String name, CLOCategory category, CLODelegate delegate)
      Creates command line option with the name name (no arguments) with category category and the delegate to process the argument and retrieve the description.

      Note:

      • on the command line option names need to be preceded by --, e.g. --help.
      • delegate must implement CLODelegate.getDescription() to provide option description.
      Parameters:
      name - the name of the command line option
      category - the category of option
      delegate - delegate for processing command line argument

    • CLOption

      public CLOption(String name, String description, CLODelegate delegate)
      Creates command line option with the name name (no arguments) and short description description as well as the delegate delegate to process the argument and optionally retrieve the description.

      Notes:

      • on the command line option names need to be preceded by --, e.g. --help.
      • the description string may contain any UTF-8 characters as well as HTML character entities. If necessary they will be escaped and converted to UTF-8 for display in XML documents.
      Parameters:
      name - the name of the command line option
      description - short description of command line option
      delegate - delegate for processing command line argument

    • CLOption

      public CLOption(String name, CLOCategory category, String description, CLODelegate delegate)
      Creates command line option with the name name (no arguments) with category category and brief description description as well as the delegate delegate to process the argument and optionally retrieve the description.

      Notes:

      • on the command line option names need to be preceded by --, e.g. --help.
      • the description string may contain any UTF-8 characters as well as HTML character entities. If necessary they will be escaped and converted to UTF-8 for display in XML documents.
      Parameters:
      name - the name of the command line option
      category - the category of option
      description - short description of command line option
      delegate - delegate for processing command line argument

    • CLOption

      public CLOption(String name, String defaultArg, String description, CLODelegate delegate)
      Creates command line option with the name name (with required argument), which defaults to defaultArg, and brief description description as well as the delegate delegate to process the argument and optionally retrieve the description.

      Notes:

      • on the command line option names need to be preceded by --, e.g. --help.
      • the description string may contain any UTF-8 characters as well as HTML character entities. If necessary they will be escaped and converted to UTF-8 for display in XML documents.
      Parameters:
      name - the name of the command line option
      defaultArg - the default argument if option is not specified on command line
      description - short description of command line option
      delegate - delegate for processing command line argument

    • CLOption

      public CLOption(String name, String defaultArg, CLOCategory category, String description, CLODelegate delegate)
      Creates command line option with the name name (with required argument), which defaults to defaultArg, of catgeory category and brief description description as well as the delegate delegate to process the argument and optionally retrieve the description.

      Notes:

      • on the command line option names need to be preceded by --, e.g. --help.
      • the description string may contain any UTF-8 characters as well as HTML character entities. If necessary they will be escaped and converted to UTF-8 for display in XML documents.
      Parameters:
      name - the name of the command line option
      defaultArg - the default argument if option is not specified on command line
      category - the category of option
      description - short description of command line option
      delegate - delegate for processing command line argument

    • CLOption

      public CLOption(String name, String defaultArg, CLOption.Argument type, CLODelegate delegate)
      Creates command line option with the name name of type type, which defaults to defaultArg, as well as the delegate delegate to process the argument and retrieve the description.

      Notes:

      • on the command line option names need to be preceded by --, e.g. --help.
      • delegate must implement CLODelegate.getDescription() to provide option description.
      Parameters:
      name - the name of the command line option
      defaultArg - the default argument if option is not specified on command line
      type - of command line option (whether argument required)
      delegate - delegate for processing command line argument

    • CLOption

      public CLOption(String name, String defaultArg, CLOption.Argument type, CLOCategory category, CLODelegate delegate)
      Creates command line option with the name name of type type, which defaults to defaultArg, and catgeory category as well as the delegate delegate to process the argument and retrieve the description.

      Note:

      • on the command line option names need to be preceded by --, e.g. --help.
      • delegate must implement CLODelegate.getDescription() to provide option description.
      Parameters:
      name - the name of the command line option
      defaultArg - the default argument if option is not specified on command line
      type - of command line option (whether argument required)
      category - the category of option
      delegate - delegate for processing command line argument

    • CLOption

      public CLOption(String name, String defaultArg, CLOption.Argument type, String description, CLODelegate delegate)
      Creates command line option with the name name of type type, which defaults to defaultArg, and brief description description as well as the delegate delegate to process the argument and optionally retrieve the description.

      Notes:

      • on the command line option names need to be preceded by --, e.g. --help.
      • the description string may contain any UTF-8 characters as well as HTML character entities. If necessary they will be escaped and converted to UTF-8 for display in XML documents.
      Parameters:
      name - the name of the command line option
      defaultArg - default argument if option is not specified on command line
      type - of command line option (whether argument required)
      description - short description of command line option
      delegate - delegate for processing command line argument

    • CLOption

      public CLOption(String name, String defaultArg, CLOption.Argument type, CLOCategory category, String description, CLODelegate delegate)
      Creates command line option with the name name of type type, which defaults to defaultArg, in category category and brief description description as well as the delegate delegate to process the argument and optionally retrieve the description.

      Notes:

      • on the command line option names need to be preceded by --, e.g. --help.
      • the description string may contain any UTF-8 characters as well as HTML character entities. If necessary they will be escaped and converted to UTF-8 for display in XML documents.
      Parameters:
      name - name of command line option
      defaultArg - default argument if option is not specified on command line
      type - of command line option (whether argument required)
      category - the category of command line option
      description - short description of command line option
      delegate - delegate for processing command line argument

  • Method Details

    • setDefault

      public void setDefault(String defaultArg)
      Set the default argument. This argument is parsed by the delegate if option is not specified on command line or if the parsing of the provided argument failed. If the parsing of defaultArg fails, the option settings are undefined.
      Parameters:
      defaultArg - default argument for command line option

    • getDefault

      public String getDefault()
      Return the default argument for command line option.
      Returns:
      default argument

    • setArg

      public void setArg(String arg)
      Set the argument for the command line option.
      Parameters:
      arg - the argument

    • parse

      public boolean parse()
      Parses the option and its argument, if applicable, through the delegate. If this option was not specified on command line, the default argument is passed to the delegate.
      Returns:
      true on successful parsing of argument

    • parse

      private boolean parse(boolean isOptional)
      Delegate parsing helper that handles optional vs required arguments.
      Parameters:
      isOptional - true if the option argument is optional
      Returns:
      true if parsing succeeds

    • addKeys

      public void addKeys(CLOption.Key[] chain)
      Add all CLOption.Keys in the array chain to this option. Note, this ignores keys starting with '-', except if '-' is the key. If needed, those keys can still be added by calling addKey(Key) or #addKey(String, String).
      Parameters:
      chain - the array of CLOption.Keys to be added
      See Also:

    • addKey

      public CLOption.Key addKey(String key, String title)
      Add a CLOption.Key to option with name key and description title.
      Parameters:
      key - the name of the key
      title - the description of the key
      Returns:
      the previous value associated with key, or null if there was no mapping for key. (A null return can also indicate that the map previously associated null with key.)

    • addKey

      public CLOption.Key addKey(CLOption.Key key)
      Add CLOption.Key key to option.
      Parameters:
      key - the CLOption.Key to be added
      Returns:
      the previous value associated with key, or null if there was no mapping for key. (A null return can also indicate that the map previously associated null with key.)

    • getKey

      public CLOption.Key getKey(String aKey)
      Get the key with name aKey. Returns null if the option has no keys or no key with the name aKey.
      Parameters:
      aKey - the name of the key
      Returns:
      the key with name aKey or null if no such key exists

    • match

      public CLOption.Key match(String keyname)
      Returns the key that best matches name. If several keys are equally good matches the first match is returned. If name perfectly matches one key, i.e. name.startsWith(key.getName()) is true, then a better match must match at least one more character of name.
      Parameters:
      keyname - the name of the key to match
      Returns:
      matching Key or null if no match was found

    • match

      public CLOption.Key match(String keyname, int min)
      Returns the key that best matches name with at least min characters matching. If several keys are equally good matches the first match is returned. If name perfectly matches one key, i.e. name.startsWith(key.getName()) is true, then a better match must match at least one more character of name.
      Parameters:
      keyname - the name of the key to match
      min - minimum number of characters that must match
      Returns:
      matching Key or null if no match was found

    • removeKey

      public CLOption.Key removeKey(CLOption.Key key)
      Remove key from the option's key collection. Returns null if the option has no keys or the key is not part of the collection.
      Parameters:
      key - the key to remove
      Returns:
      the key that was removed or null if no such key exists

    • removeKey

      public CLOption.Key removeKey(String aKey)
      Remove key with name aKey from the option's key collection.
      Parameters:
      aKey - the name of the key to remove
      Returns:
      the key that was removed or null if no such key exists

    • clearKeys

      public void clearKeys()
      Clear all keys from the option.

    • isValidKey

      public boolean isValidKey(CLOption.Key key)
      Check if key is a valid key for this option.
      Parameters:
      key - the key to check
      Returns:
      true if key is a valid key

    • isValidKey

      public boolean isValidKey(String aKey)
      Check if the key with name aKey is a valid key for this option. This test is very lenient and passes if aKey and one of the keys start at least with one identical character. This allows abbreviating keys as well as appending options.
      Parameters:
      aKey - the name of the key to check
      Returns:
      true if the name aKey is valid
      See Also:

    • differAt

      public static int differAt(String a, String b)
      Compare two strings and return the index of the first character that differs.
      Parameters:
      a - the first string
      b - the second string
      Returns:
      the index of the first differing character

    • stripKey

      public static String stripKey(CLOption.Key key, String arg)
      Strips the name of the key from the argument. If the key is not found, the argument is returned unchanged.
      Parameters:
      key - the key to strip
      arg - the argument to strip the key from
      Returns:
      the argument without the key

    • stripKey

      public static String stripKey(String key, String arg)
      Strips the key from the argument. If the key is not found, the argument is returned unchanged.
      Parameters:
      key - the name of the key to strip
      arg - the argument to strip the key from
      Returns:
      the argument without the key

    • getKeys

      public Collection<CLOption.Key> getKeys()
      Gets all keys of this option.
      Returns:
      the key collection

    • inheritKeysFrom

      public void inheritKeysFrom(CLOption option)
      Inherit keys from another option. This is useful if options share the same keys.
      Parameters:
      option - the option to inherit keys from

    • getDescriptionKey

      public String getDescriptionKey(String aKey)
      Get the description of the key with name aKey.
      Parameters:
      aKey - the name of the key
      Returns:
      the description of the key

    • getDescriptionKey

      public String getDescriptionKey()
      Get the description of all keys of this option. Minimal formatting is applied with the name of the key and a brief description of the key separated by '\n'. No HTML or other formatting can be applied.
      Returns:
      the description of all keys

    • reset

      public void reset()
      Reset option. Clear argument, if applicable, and mark as not isSet.

    • getName

      public String getName()
      Get the name of the option.
      Returns:
      the name

    • getType

      public CLOption.Argument getType()
      Get the type of the option.
      Returns:
      the type

    • getArg

      public String getArg()
      Get the option argument. If no argument was set, the default argument is returned.
      Returns:
      the argument

    • isSet

      public boolean isSet()
      Check if option was set on command line (regardless of whether an argument was provided).
      Returns:
      true if option set

    • getDescription

      public String getDescription()
      Retrieve short description of option and include the default as well as the current arguments. If no description was provided at initialization, the delegate is queried for an up-to-date description.

      Note: the description string may contain any UTF-8 characters. If necessary they will be escaped for display in HTML or XML documents.

      Returns:
      description of option and arguments.

    • buildCurrent

      private StringBuilder buildCurrent(StringBuilder sb, String currentArg)
      Append the current and default argument description to the provided builder.
      Parameters:
      sb - builder to append to
      currentArg - textual representation of the current argument
      Returns:
      the supplied builder for chaining

    • buildBaseDescription

      private StringBuilder buildBaseDescription()
      Build the base description string, using either the stored description or asking the delegate and appending key descriptions if applicable.
      Returns:
      builder containing the base description text

    • buildArgKeys

      private String buildArgKeys()
      Construct the user-facing representation of the argument when keys are defined; mirrors previous loop logic but extracted to reduce complexity.
      Returns:
      textual representation of the key-based arguments

    • buildKey

      private CLOption.Key buildKey(StringBuilder sb, CLOption.Key key, String[] args, int pos)
      Append the resolved key value and remaining arguments to the builder.
      Parameters:
      sb - builder to append to
      key - resolved key
      args - tokenized argument list
      pos - position of the key token within args
      Returns:
      the key that was appended (for chaining)

    • setDescription

      public void setDescription(String descr)
      Set short description of option.
      Parameters:
      descr - description of option

    • compareTo

      public int compareTo(CLOption opt)
      Specified by:
      compareTo in interface Comparable<CLOption>

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object