Class CLOParser

Object
CLOParser
public class CLOParser extends Object
Parser for command line options. Inspired by UNIX style command line options.
Author:
Christoph Hauert

  • Field Details

    • parameters

      ArrayList<String> parameters
      List of command line options as provided.
      See Also:

    • options

      List<CLOption> options
      List of command line options available (after parsing).
      See Also:

    • providers

      Set<CLOProvider> providers
      List of providers of command line options.
      See Also:

    • logger

      protected Logger logger
      Logger for reporting errors, warnings or other information (optional). Without a logger parsing is quiet (same as with logging level Level.OFF).
      See Also:

    • SPLIT_ARG_REGEX

      public static final String SPLIT_ARG_REGEX
      The regular expression to split the command line arguments for parsing.
      See Also:

    • OPTION_PREFIX

      public static final String OPTION_PREFIX
      The prefix for reporting issues with command line options
      See Also:

    • SPECIES_DELIMITER

      public static final String SPECIES_DELIMITER
      The delimiter for separating options in multi-species models.
      See Also:

    • TRAIT_DELIMITER

      public static final String TRAIT_DELIMITER
      The delimiter for separating options in continuous models with multiple traits.

      Note: same as MATRIX_DELIMITER ";".

      See Also:

    • MATRIX_DELIMITER

      public static final String MATRIX_DELIMITER
      The delimiter for separating rows when passing a matrix as an option.

      Note: same as TRAIT_DELIMITER ";".

      See Also:

    • VECTOR_DELIMITER

      public static final String VECTOR_DELIMITER
      The delimiter for separating entries when passing a vector as an option.
      See Also:

    • COLOR_KEYS

      private static final Map<String,Color> COLOR_KEYS
      Lookup table for predefined colors.
      See Also:

  • Constructor Details

    • CLOParser

      public CLOParser(CLOProvider provider)
      New command line option parser. Register provider for supplying options through the CLOParser interface.
      Parameters:
      provider - of command line options

    • CLOParser

      public CLOParser(Set<CLOProvider> providers)
      New command line option parser. Register the list of providers for supplying options through the CLOParser interface.
      Parameters:
      providers - list of command line option providers

  • Method Details

    • addCLOProvider

      public boolean addCLOProvider(CLOProvider provider)
      Add provider to the list of providers.
      Parameters:
      provider - to add to list of command line option providers
      Returns:
      true if provider added to set, false if provider already exists or is null

    • removeCLOProvider

      public boolean removeCLOProvider(CLOProvider provider)
      Remove provider from the list of providers.
      Parameters:
      provider - to remove from list of command line option providers
      Returns:
      true if provider removed from set, false if provider did not exist or is null

    • clearCLO

      public void clearCLO()
      Clears current collection of options.

    • initCLO

      public void initCLO()
      Initializes parser. Clears current collection of options and creates new list by contacting all registered providers. Options are stored in alphabetical order in the List options.
      See Also:

    • updateCLO

      public void updateCLO()
      Updates current collection of options by contacting all registered providers. Options are stored in alphabetical order in the List options.
      See Also:

    • resetCLO

      public void resetCLO()
      Reset current collection of options to their respective defaults.
      See Also:

    • parseCLO

      public int parseCLO(String[] cloargs)
      Parses String array of command line arguments in two stages. In the first stage all entries in the array are split into the option name and its (potential) arguments, separated by ' ' or '='. In the second stage the current list of options is consulted and if the name of an option matches, the option is parsed accordingly. For unknown options a warning is logged and the option is ignored.

      Note: the option identifier (such as '--') must already be stripped such that each entry starts with the name of the option.

      Parameters:
      cloargs - the String array with command line options
      Returns:
      the number of issues that have occurred durin parsing

    • parseCommandLineOption

      private Integer parseCommandLineOption(String clo)
      Parses a single command line option.
      Parameters:
      clo - the command line option string
      Returns:
      the number of issues (0, 1, or null if option was found and processed)

    • processMatchedOption

      private int processMatchedOption(CLOption opt, String[] args, String clo)
      Processes a matched option with its arguments.
      Parameters:
      opt - the matched option
      args - the split arguments
      clo - the original command line option string
      Returns:
      the number of issues (0 or 1)

    • logParseFailure

      private void logParseFailure(CLOption opt)
      Logs a parse failure for an option.
      Parameters:
      opt - the option that failed to parse

    • getCLOptions

      public List<CLOption> getCLOptions()
      Get the current list of command line options.
      Returns:
      list of command line options

    • getCLO

      public String getCLO()
      Return String containing all currently set command line options. Command line arguments that had been set using short options are converted to their long counterpart and all arguments are separated by ' '.

      Note: using String.split(String) the returned string is ready to be parsed again parseCLO(String[]).

      Returns:
      all current command line options formatted as String

    • helpCLO

      public String helpCLO(boolean categories)
      Returns a short description of every command line option in the options list, including its default value as well as the current setting (if different). This string typically serves as a quick help and reminder of the different command line options available.
      Parameters:
      categories - if true categories are printed separately
      Returns:
      help for command line options
      See Also:

    • appendCategorizedHelp

      private void appendCategorizedHelp(StringBuilder help)
      Appends help text for all options grouped by category.
      Parameters:
      help - the StringBuilder to append to

    • findNextCategory

      private CLOCategory findNextCategory(int priority)
      Finds the next category with highest priority less than the given priority.
      Parameters:
      priority - the current priority threshold
      Returns:
      the next category or null if none found

    • appendOptionsForCategory

      private void appendOptionsForCategory(StringBuilder help, CLOCategory category)
      Appends help text for options in the specified category.
      Parameters:
      help - the StringBuilder to append to
      category - the category to filter by (null for uncategorized options)

    • appendUncategorizedHelp

      private void appendUncategorizedHelp(StringBuilder help)
      Appends help text for all options without category grouping.
      Parameters:
      help - the StringBuilder to append to

    • addCLO

      public void addCLO(CLOption option)
      Adds option to current list of command line options. If option has already been added the request is ignored and options remains unchanged. If an option of the same name already exists in options then option is not added and a warning is logged. Finally, if option does not exist, it is reset to its default values and added to the options list.
      Parameters:
      option - to be added to the list of options

    • removeCLO

      public boolean removeCLO(CLOption option)
      Remove option from current list of command line options.
      Parameters:
      option - to be removed from list of options, if present
      Returns:
      true if options contained option

    • removeCLO

      public boolean removeCLO(String name)
      Remove option with name from current list of command line options. Does nothing if no option with name exists.
      Parameters:
      name - of option to be removed from list of options
      Returns:
      true if options contained option with name

    • removeCLO

      public boolean removeCLO(String[] names)
      Remove all options with names listed in names.
      Parameters:
      names - of options to remove
      Returns:
      true if options contained all options listed in names; false if at least one name could not be found

    • getCLO

      public CLOption getCLO(String name)
      Return option with name from current list of command line options. Leaves options unchanged.
      Parameters:
      name - of option to retrieve
      Returns:
      option if found; null otherwise

    • providesCLO

      public boolean providesCLO(String name)
      Check if current list of command line options includes option with name.
      Parameters:
      name - of option to check
      Returns:
      true if included in options

    • setLogger

      public void setLogger(Logger logger)
      Sets the logger for reporting warnings while parsing options.
      Parameters:
      logger - to use for warnings
      See Also:

    • logError

      private void logError(String msg)
      Helper method for logging errors.
      Parameters:
      msg - the error message

    • logWarning

      private void logWarning(String msg)
      Helper method for logging warnings.
      Parameters:
      msg - the warning message

    • parseDim

      public static int parseDim(String aDim)
      Parse string arg as an integer. If arg contains 'x' or 'X' the number is assumed to refer to the side of a square. For example "42x" returns 42*42=1764.

      Note: any digits following 'x' or 'X' are currently ignored. For example "42x37" also returns 42*42=1764.

      Parameters:
      aDim - string to convert to an int
      Returns:
      int representation of aDim

    • parseInteger

      public static int parseInteger(String anInteger)
      Parse string anInteger as an int.
      Parameters:
      anInteger - string to convert to an int
      Returns:
      int representation of anInteger or 0 if anInteger is null or an empty string.
      See Also:

    • parseLong

      public static long parseLong(String aLong)
      Parse string aLong as a long.
      Parameters:
      aLong - string to convert to a long
      Returns:
      long representation of aLong or 0 if aLong is null or an empty string.
      See Also:

    • parseFloat

      public static float parseFloat(String aFloat)
      Parse string aFloat as a float.
      Parameters:
      aFloat - string to convert to an float
      Returns:
      float representation of aFloat or 0 if aFloat is null or an empty string.
      See Also:

    • parseDouble

      public static double parseDouble(String aDouble)
      Parse string aDouble as a double.
      Parameters:
      aDouble - string to convert to an double
      Returns:
      double representation of aDouble or 0 if aDouble is null or an empty string.
      See Also:

    • parseBoolVector

      public static boolean[] parseBoolVector(String aVector)
      Parse string aVector as a boolean[] array. Vector entries are separated by ",". Any invalid entries default to false.
      Parameters:
      aVector - string to convert to boolean[]
      Returns:
      boolean[] representation of aVector
      See Also:

    • parseIntVector

      public static int[] parseIntVector(String aVector)
      Parse string aVector as an int[] array. Vector entries are separated by ",". Returns an array of zero length if aVector is null, an empty string, or any entry caused a NumberFormatException.
      Parameters:
      aVector - string to convert to int[]
      Returns:
      int[] representation of aVector
      See Also:

    • parseIntVector

      public static int[] parseIntVector(String aVector, String separator)
      Parse string aVector as a int[] array. Vector entries are separated by separator, which can be any valid regular expression. Returns an array of zero length if aVector is null, an empty string, or any entry caused a NumberFormatException.
      Parameters:
      aVector - string to convert to int[]
      separator - regular expression string used to split aVector
      Returns:
      int[] representation of aVector
      See Also:

    • parseVector

      public static double[] parseVector(String aVector)
      Parse string aVector as a double[] array. Vector entries are separated by ",". Returns an array of zero length if aVector is null, an empty string, or any entry caused a NumberFormatException.
      Parameters:
      aVector - string to convert to double[]
      Returns:
      double[] representation of aVector
      See Also:

    • parseVector

      public static double[] parseVector(String aVector, String separator)
      Parse string aVector as a double[] array. Vector entries are separated by separator, which can be any valid regular expression. Returns an array of zero length if aVector is null, an empty string, or any entry caused a NumberFormatException.
      Parameters:
      aVector - string to convert to double[]
      separator - regular expression string used to split aVector
      Returns:
      double[] representation of aVector.
      See Also:

    • parseIntMatrix

      public static int[][] parseIntMatrix(String aMatrix)
      Parse string aMatrix as a int[][] matrix (two dimensional array). For each row entries are separated by "," and rows are separated by ";". Returns an empty matrix new int[0][0] if aMatrix is null, an empty string, or any entry caused a NumberFormatException.
      Parameters:
      aMatrix - string to convert to int[][]
      Returns:
      int[][] representation of aMatrix
      See Also:

    • parseMatrix

      public static double[][] parseMatrix(String aMatrix)
      Parse string aMatrix as a double[][] matrix (two dimensional array). For each row entries are separated by "," and rows are separated by ";". Returns an empty matrix new double[0][0] if aMatrix is null, an empty string, or any entry caused a NumberFormatException.
      Parameters:
      aMatrix - string to convert to double[][]
      Returns:
      double[][] representation of aMatrix.
      See Also:

    • parseColor

      public static Color parseColor(String aColor)
      Parse string aColor as a Color. The color string can have different formats:
      • named color
      • a single number [0,255] specifying a gray scale color
      • a triplet of numbers in [0,255] (separated by ,) specifying the red, green and blue components of the color, respectively.
      • a quadruple of numbers in [0,255] (separated by ,) specifying the red, green, blue and alpha components of the (transparent) color, respectively.
      Parameters:
      aColor - string to convert to Color
      Returns:
      Color representation of aColor and null if aColor is null, an empty or a malformed string.