Package ml.options

Class OptionSet

  • All Implemented Interfaces:
    Constrainable
    public class OptionSet
extends java.lang.Object
implements Constrainable
    This class holds the information for a set of options. A set can hold any number of OptionData instances which are checked together to determine success or failure.

    The approach to use this class looks like this:

    1. The user uses any of the Options.addSet() methods (e. g. Options.addSet(String)) to create any number of sets required (or just relies on the default set, if only one set is required)
    2. The user adds all required option definitions to each set
    3. Using any of the Options.check() methods, each set can be checked whether the options that were specified on the command line satisfy its requirements
    4. If the check was successful for a given set, several data items are available from this class:
      • All options defined for the set (through which e. g. values, details, and multiplicity are available)
      • All data items found (these are the items on the command line which do not start with the prefix, i. e. non-option arguments)
      • All unmatched arguments on the command line (these are the items on the command line which start with the prefix, but do not match to one of the options). Programs can elect to ignore these, or react with an error

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int INF
      A constant indicating an unlimited number of supported data items

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean acceptsData()
      Indicate whether this set accepts data (which means that maxData is 1 or larger).
      void addConstraint​(Constraint constraint)
      Add a constraint for this option set
      OptionData addOption​(OptionData.Type type, java.lang.String key)
      Add the given option to the set.
      OptionData addOption​(OptionData.Type type, java.lang.String key, java.lang.String altKey)
      Add the given option to the set.
      OptionData addOption​(OptionData.Type type, java.lang.String key, java.lang.String altKey, Options.Multiplicity multiplicity)
      Add the given option to the set.
      OptionData addOption​(OptionData.Type type, java.lang.String key, Options.Multiplicity multiplicity)
      Add the given option to the set.
      java.util.List<Constraint> getConstraints()
      Get the constraints defined for this option set
      java.util.List<java.lang.String> getData()
      Return the data items found (these are the items on the command line which do not start with the prefix, i.
      java.lang.String getData​(int index)
      Return a specific data item.
      int getDataCount()
      Return the number of data items found (these are the items on the command line which do not start with the prefix, i.
      java.lang.String getDataText​(int index)
      Get the data text for a data item on the command line.
      java.lang.String getHelpText​(int index)
      Get the help text for a data item on the command line.
      int getMaxData()
      Getter method for maxData property
      int getMinData()
      Getter method for minData property
      java.lang.String getName()
      Return the name of the set
      OptionData getOption​(java.lang.String key)
      Get the data for a specific option, identified by its key name (which is unique)
      java.util.List<OptionData> getOptionData()
      Get a list of all the options defined for this set
      java.util.List<java.lang.String> getUnmatched()
      Return all unmatched items found (these are the items on the command line which start with the prefix, but do not match to one of the options)
      java.lang.String getUnmatched​(int index)
      Return a specific unmatched item.
      int getUnmatchedCount()
      Return the number of unmatched items found (these are the items on the command line which start with the prefix, but do not match to one of the options)
      boolean hasUnlimitedData()
      Indicate whether this set has no upper limit for the number of allowed data items
      boolean isDefault()
      Indicate whether this set is the default set or not
      boolean isSet​(java.lang.String key)
      Check whether a specific option is set, i.
      void printResults()
      A convenience method that prints all the results obtained for this option set to System.out.
      OptionSet setDataText​(int index, java.lang.String text)
      Set the data text for a data item on the command line.
      OptionSet setHelpText​(int index, java.lang.String text)
      Set the help text for a data item on the command line.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • INF

        public static final int INF
        A constant indicating an unlimited number of supported data items
        See Also:
        Constant Field Values

    • Method Detail

      • hasUnlimitedData

        public boolean hasUnlimitedData()
        Indicate whether this set has no upper limit for the number of allowed data items

        Returns:
        A boolean indicating whether this set has no upper limit for the number of allowed data items

      • isDefault

        public boolean isDefault()
        Indicate whether this set is the default set or not

        Returns:
        A boolean indicating whether this set is the default set or not

      • getConstraints

        public java.util.List<Constraint> getConstraints()
        Get the constraints defined for this option set

        Specified by:
        getConstraints in interface Constrainable
        Returns:
        The defined constraints for this option (or null if no constraints have been defined)

      • setDataText

        public OptionSet setDataText​(int index,
                             java.lang.String text)
        Set the data text for a data item on the command line. This is exploited e. g. in HelpPrinter instances.

        Parameters:
        index - The index for this data item on the command line. Must be within the allowed range of 0 ... maxData - 1 for this set. If this set supports an unlimited number of data items, the allowed range is 0 ... minData.
        text - The text to use for this data item in the command line syntax

        Returns:
        This set to allow for invocation chaining

      • setHelpText

        public OptionSet setHelpText​(int index,
                             java.lang.String text)
        Set the help text for a data item on the command line. This is exploited e. g. in HelpPrinter instances.

        Parameters:
        index - The index for this data item on the command line. Must be within the allowed range of 0 ... maxData - 1 for this set. If this set supports an unlimited number of data items, the allowed range is 0 ... minData.
        text - The help text to use to describe the purpose of the data item

        Returns:
        This set to allow for invocation chaining

      • getDataText

        public java.lang.String getDataText​(int index)
        Get the data text for a data item on the command line. This is only useful if such a data text is used.

        Parameters:
        index - The index for this data item on the command line. Must be within the allowed range of 0 ... maxData - 1 for this set. If this set supports an unlimited number of data items, the allowed range is 0 ... minData.

        Returns:
        The text used for this data item in the command line syntax

      • getHelpText

        public java.lang.String getHelpText​(int index)
        Get the help text for a data item on the command line. This is only useful if such a help text is used.

        Parameters:
        index - The index for this data item on the command line. Must be within the allowed range of 0 ... maxData - 1 for this set. If this set supports an unlimited number of data items, the allowed range is 0 ... minData.

        Returns:
        The help text used to describe the purpose of the data item

      • getOptionData

        public java.util.List<OptionData> getOptionData()
        Get a list of all the options defined for this set

        Returns:
        A list of OptionData instances defined for this set

      • getOption

        public OptionData getOption​(java.lang.String key)
        Get the data for a specific option, identified by its key name (which is unique)

        Parameters:
        key - The key for the option

        Returns:
        The OptionData instance

      • isSet

        public boolean isSet​(java.lang.String key)
        Check whether a specific option is set, i. e. whether it was specified at least once on the command line.

        Parameters:
        key - The key for the option

        Returns:
        true or false, depending on the outcome of the check

      • getName

        public java.lang.String getName()
        Return the name of the set

        Returns:
        The name of the set

      • getMinData

        public int getMinData()
        Getter method for minData property

        Returns:
        The value for the minData property

      • getMaxData

        public int getMaxData()
        Getter method for maxData property

        Returns:
        The value for the maxData property

      • acceptsData

        public boolean acceptsData()
        Indicate whether this set accepts data (which means that maxData is 1 or larger).

        Returns:
        A boolean indicating whether this set accepts data

      • getData

        public java.util.List<java.lang.String> getData()
        Return the data items found (these are the items on the command line which do not start with the prefix, i. e. non-option arguments)

        Returns:
        A list of strings with all data items found

      • getDataCount

        public int getDataCount()
        Return the number of data items found (these are the items on the command line which do not start with the prefix, i. e. non-option arguments)

        Returns:
        The number of all data items found

      • getData

        public java.lang.String getData​(int index)
        Return a specific data item.

        Parameters:
        index -
        Returns:
        The requested data item

      • getUnmatched

        public java.util.List<java.lang.String> getUnmatched()
        Return all unmatched items found (these are the items on the command line which start with the prefix, but do not match to one of the options)

        Returns:
        A list of strings with all unmatched items found

      • getUnmatchedCount

        public int getUnmatchedCount()
        Return the number of unmatched items found (these are the items on the command line which start with the prefix, but do not match to one of the options)

        Returns:
        The number of all unmatched items found

      • getUnmatched

        public java.lang.String getUnmatched​(int index)
        Return a specific unmatched item.

        Parameters:
        index -
        Returns:
        The requested unmatched item

      • addOption

        public OptionData addOption​(OptionData.Type type,
                            java.lang.String key)
        Add the given option to the set.

        Parameters:
        type - The type of the option
        key - The name of the option

        Returns:
        The newly created option (to support invocation chaining)

      • addOption

        public OptionData addOption​(OptionData.Type type,
                            java.lang.String key,
                            Options.Multiplicity multiplicity)
        Add the given option to the set.

        Parameters:
        type - The type of the option
        key - The name of the option
        multiplicity - The multiplicity of the option

        Returns:
        The newly created option (to support invocation chaining)

      • addOption

        public OptionData addOption​(OptionData.Type type,
                            java.lang.String key,
                            java.lang.String altKey)
        Add the given option to the set.

        Parameters:
        type - The type of the option
        key - The name of the option
        altKey - The alternate name of the option

        Returns:
        The newly created option (to support invocation chaining)

      • addOption

        public OptionData addOption​(OptionData.Type type,
                            java.lang.String key,
                            java.lang.String altKey,
                            Options.Multiplicity multiplicity)
        Add the given option to the set.

        Parameters:
        type - The type of the option
        key - The name of the option
        altKey - The alternate name of the option
        multiplicity - The multiplicity of the option

        Returns:
        The newly created option (to support invocation chaining)

      • printResults

        public void printResults()
        A convenience method that prints all the results obtained for this option set to System.out. This is quite handy to quickly check whether a set definition yields the expected results for a given set of command line arguments.