Package org.evoludo.util

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

  • Field Details

    • uniqueID

      private static int uniqueID
      Counter to assign every option a unique identifier.

    • ID

      final int ID
      Unique identifier of command line option (currently unused).

    • 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 CLOption.Category 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 but no HTML or other formatting.

    • 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.

    • isSet

      boolean isSet
      true if option was set on command line.

    • delegate

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

  • Constructor Details

    • CLOption

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

      Note:

      Parameters:
      name - the name of the command line option
      delegate - delegate for processing command line argument

    • CLOption

      public CLOption(String name, CLOption.Category category, CLOption.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:

      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, CLOption.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.

      Note: on the command line option names need to be preceded by --, e.g. --help.

      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, CLOption.Category category, String description, CLOption.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.

      Note: on the command line option names need to be preceded by --, e.g. --help.

      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, CLOption.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.

      Note: on the command line option names need to be preceded by --, e.g. --help.

      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, CLOption.Category category, String description, CLOption.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.

      Note: on the command line option names need to be preceded by --, e.g. --help.

      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, CLOption.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.

      Note:

      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, CLOption.Category category, CLOption.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:

      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, CLOption.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.

      Note: on the command line option names need to be preceded by --, e.g. --help.

      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, CLOption.Category category, String description, CLOption.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.

      Note: on the command line options need to be preceded by --, e.g. --help.

      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

    • parseDefault

      public boolean parseDefault()
      Parses the default argument for this option. Typically called if parse() failed.
      Returns:
      true on successful parsing of default argument

    • 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

    • report

      public void report(PrintStream output)
      Print report for this option to output through delegate. If no delegate is available or output == null do nothing.
      Parameters:
      output - the PrintStream for the output

    • 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

    • isDefault

      public boolean isDefault()
      Check if no argument was set.
      Returns:
      true if no argument set.

    • 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.
      Returns:
      description of option and arguments.

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