Package adams.core.option

Class OptionUtils

  • public class OptionUtils
extends Object
    A helper class for option-related things.
    Author:
    fracpete (fracpete at waikato dot ac dot nz)

    • Field Detail

      • OPTION_PREFIX

        public static final String OPTION_PREFIX
        the prefix for a regular option, instead of a hook.
        See Also:
        Constant Field Values

      • LOGGER

        protected static Logger LOGGER
        the logger to use.

      • m_PropertyDescriptorCache

        protected static Map<String,​PropertyDescriptor> m_PropertyDescriptorCache
        for caching the property descriptors.

      • m_HooksValueOf

        protected static Map<Class,​Method> m_HooksValueOf
        the hooks for "valueOf". A hook takes a class and a string as parameter.

      • m_HooksToString

        protected static Map<Class,​Method> m_HooksToString
        the hooks for "toString". A hook takes a class and the object as parameter.

      • m_HooksRegistered

        protected static boolean m_HooksRegistered
        whether the hooks got already registered.

      • m_Properties

        protected static Properties m_Properties
        the properties in use.

      • m_Debug

        protected static Boolean m_Debug
        whether debugging is on.

      • m_SuppressDefaultValues

        protected static Boolean m_SuppressDefaultValues
        whether to suppress default options (toArray/toString).

    • Constructor Detail

      • OptionUtils

        public OptionUtils()

    • Method Detail

      • addValueOfHook

        public static void addValueOfHook​(Class key,
                                  Method method)
        Adds the given hook for converting strings into objects (low-level).
        Parameters:
        key - the superclass to store the hook method under
        method - the hook method

      • addValueOfHook

        public static void addValueOfHook​(Class key,
                                  Class hookCls,
                                  String hookMethod)
        Adds the given hook for converting strings into objects, automatically adds the handling of arrays.
        Parameters:
        key - the superclass to store the hook method under
        hookCls - the class containing the hook method
        hookMethod - the name of the hook method

      • getValueOfHook

        public static Method getValueOfHook​(Class key)
        Returns the "valueOf" hook for the specified class.
        Parameters:
        key - the class to get the hook for
        Returns:
        the hook, or null if none available

      • addToStringHook

        public static void addToStringHook​(Class key,
                                   Method method)
        Adds the given hook for converting objects into strings (low-level).
        Parameters:
        key - the superclass to store the hook method under
        method - the hook method

      • addToStringHook

        public static void addToStringHook​(Class key,
                                   Class hookCls,
                                   String hookMethod)
        Adds the given hook for converting objects into strings (low-level).
        Parameters:
        key - the superclass to store the hook method under
        hookCls - the class containing the hook method
        hookMethod - the name of the hook method

      • getToStringHook

        public static Method getToStringHook​(Class key)
        Returns the "toString" hook for the specified class.
        Parameters:
        key - the class to get the hook for
        Returns:
        the hook, or null if none available

      • getProperties

        protected static Properties getProperties()
        Returns the properties file with the custom editors.
        Returns:
        the props file

      • getSuppressDefaultValues

        public static boolean getSuppressDefaultValues()
        Returns whether default values should be suppressed in toArray/toNested.
        Returns:
        true if default values suppressed

      • getDebug

        public static boolean getDebug()
        Returns whether to output debugging information.
        Returns:
        true if debugging output is on

      • registerCustomHooks

        public static void registerCustomHooks()
        Registers all hooks.

      • splitOptions

        public static String[] splitOptions​(String quotedOptionString)
                             throws Exception
        Split up a string containing options into an array of strings, one for each option.
        Parameters:
        quotedOptionString - the string containing the options
        Returns:
        the array of options
        Throws:
        Exception - in case of an unterminated string, unknown character or a parse error

      • joinOptions

        public static String joinOptions​(String[] optionArray)
        Joins all the options in an option array into a single string, as might be used on the command line.
        Parameters:
        optionArray - the array of options
        Returns:
        the string containing all options.

      • getCommandLine

        public static String getCommandLine​(Object obj)
        Returns the classname and, if the object is an option handler, the options as a single string.
        Parameters:
        obj - the handler to turn into a string
        Returns:
        the generated string
        See Also:
        getShortCommandLine(Object)

      • getCommandLines

        public static String[] getCommandLines​(Object[] obj)
        Returns the classname and, if the object is an option handler, the options as a single string.
        Parameters:
        obj - the handler to turn into a string
        Returns:
        the generated string
        See Also:
        getShortCommandLine(Object)

      • getShortCommandLine

        public static String getShortCommandLine​(Object obj)
        Returns the classname and, if the object is an option handler, the options as a single string. Shortened version.
        Parameters:
        obj - the handler to turn into a string
        Returns:
        the generated string
        See Also:
        getCommandLine(Object)

      • getOptions

        public static String[] getOptions​(Object obj)
        Returns the options as array if the object in an option handler.
        Parameters:
        obj - the handler to get the options array for
        Returns:
        the generated string

      • getOptions

        public static String[] getOptions​(Object obj,
                                  boolean addClass)
        Returns the options as array if the object in an option handler.
        Parameters:
        obj - the handler to get the options array for
        addClass - whether to add the classname as well
        Returns:
        the generated string

      • setOptions

        public boolean setOptions​(Object obj,
                          String[] args)
        Applies the options to the supplied object.
        Parameters:
        obj - the object to set the options for
        args - the options to set
        Returns:
        true if successfully set

      • forString

        public static Object forString​(Class classType,
                               String str)
                        throws Exception
        Returns an object generated from the string representation. The string representation can either be a commandline or a nested (multi-line) representation.
        Parameters:
        classType - the class that the instantiated object should be assignable to -- an exception is thrown if this is not the case
        str - the string to use for generating the object
        Returns:
        the newly created object, ready for use.
        Throws:
        Exception - if the class name is invalid, or if the class is not assignable to the desired class type, or the options supplied are not acceptable to the object

      • fromFile

        public static Object fromFile​(Class classType,
                              File file)
                       throws Exception
        Returns an object generated from the string representation loaded from the specified file. The string representation can either be a commandline or a nested (multi-line) representation.
        Parameters:
        classType - the class that the instantiated object should be assignable to -- an exception is thrown if this is not the case
        file - the file to load the string representation from
        Returns:
        the newly created object, ready for use.
        Throws:
        Exception - if the class name is invalid, or if the class is not assignable to the desired class type, or the options supplied are not acceptable to the object, or failed to load representation from file
        See Also:
        forString(Class, String)

      • forAnyCommandLine

        public static Object forAnyCommandLine​(Class classType,
                                       String cmdline)
                                throws Exception
        Creates a new instance of an object given its command-line, including class name and (optional) arguments to pass to its setOptions method. If the object implements OptionHandler and the options parameter is non-null, the object will have its options set. NB: works for WEKA and ADAMS option handlers, but is also slower.
        Parameters:
        classType - the class that the instantiated object should be assignable to -- an exception is thrown if this is not the case
        cmdline - the fully qualified class name and the (optional) options of the object
        Returns:
        the newly created object, ready for use.
        Throws:
        Exception - if the class name is invalid, or if the class is not assignable to the desired class type, or the options supplied are not acceptable to the object
        See Also:
        forCommandLine(Class, String)

      • forCommandLine

        public static OptionHandler forCommandLine​(Class classType,
                                           String cmdline)
                                    throws Exception
        Creates a new instance of an option handler given its command-line, including class name and (optional) arguments to pass to its setOptions method. NB: works only with ADAMS option handlers.
        Parameters:
        classType - the class that the instantiated object should be assignable to -- an exception is thrown if this is not the case
        cmdline - the fully qualified class name and the (optional) options of the object
        Returns:
        the newly created object, ready for use.
        Throws:
        Exception - if the class name is invalid, or if the class is not assignable to the desired class type, or the options supplied are not acceptable to the object
        See Also:
        forAnyCommandLine(Class, String)

      • forCommandLine

        public static OptionHandler forCommandLine​(Class classType,
                                           String cmdline,
                                           MessageCollection warnings,
                                           MessageCollection errors,
                                           boolean quiet)
                                    throws Exception
        Creates a new instance of an option handler given its command-line, including class name and (optional) arguments to pass to its setOptions method. NB: works only with ADAMS option handlers.
        Parameters:
        classType - the class that the instantiated object should be assignable to -- an exception is thrown if this is not the case
        cmdline - the fully qualified class name and the (optional) options of the object
        warnings - for collecting warnings, can be null
        errors - for collecting errors, can be null
        quiet - suppressed logging output if set to true
        Returns:
        the newly created object, ready for use.
        Throws:
        Exception - if the class name is invalid, or if the class is not assignable to the desired class type, or the options supplied are not acceptable to the object
        See Also:
        forAnyCommandLine(Class, String)

      • forCommandLines

        public static OptionHandler[] forCommandLines​(Class classType,
                                              String[] cmdlines)
                                       throws Exception
        Creates new instances of option handlers given their command-line, including class name and (optional) arguments to pass to its setOptions method. NB: works only with ADAMS option handlers.
        Parameters:
        classType - the class that the instantiated object should be assignable to -- an exception is thrown if this is not the case
        cmdlines - the fully qualified class names and the (optional) options of the objects
        Returns:
        the newly created object, ready for use.
        Throws:
        Exception - if the class name is invalid, or if the class is not assignable to the desired class type, or the options supplied are not acceptable to the object
        See Also:
        forAnyCommandLine(Class, String)

      • forName

        public static Object forName​(Class classType,
                             String className,
                             String[] options)
                      throws Exception
        Creates a new instance of an object given its class name and (optional) arguments to pass to its setOptions method. If the object implements OptionHandler and the options parameter is non-null, the object will have its options set.
        Parameters:
        classType - the class that the instantiated object should be assignable to -- an exception is thrown if this is not the case
        className - the fully qualified class name of the object
        options - an array of options suitable for passing to setOptions. May be null.
        Returns:
        the newly created object, ready for use.
        Throws:
        Exception - if the class name is invalid, or if the class is not assignable to the desired class type, or the options supplied are not acceptable to the object

      • extractClassname

        public static String extractClassname​(String cmdline)
        Extracts the classname from the commandline.
        Parameters:
        cmdline - the commandline to get the classname from
        Returns:
        the classname, null if not extracted

      • canInstantiate

        public static boolean canInstantiate​(String cmdline)
        Checks whether the command-line is likely to succeed to be instantiated, i.e., the class can be loaded.
        Parameters:
        cmdline - the commandline with the class to check
        Returns:
        true if class can be loaded

      • valueOf

        public static Object valueOf​(Class cls,
                             String value)
                      throws Exception
        Returns the string value converted into the appropriate class.
        Parameters:
        cls - the required class
        Returns:
        the instantiated object
        Throws:
        Exception - if conversion goes wrong or object cannot be instantiated

      • toString

        public static String toString​(Object obj)
        Turns the object into the appropriate string.
        Parameters:
        obj - the object to convert
        Returns:
        the generated string, null if null string

      • shallowCopy

        public static OptionHandler shallowCopy​(OptionHandler o,
                                        boolean expand)
        Creates an OptionHandler object with the same options as the specified one. Also transfers the database connection object, if the object implements the DatabaseConnectionHandler interface.
        Parameters:
        o - the template
        expand - whether to expand variables to their current value instead of using the placeholders
        Returns:
        the copy with the same options, null in case of an error
        See Also:
        DatabaseConnectionHandler

      • shallowCopy

        public static OptionHandler shallowCopy​(OptionHandler o,
                                        boolean expand,
                                        boolean transferVars)
        Creates an OptionHandler object with the same options as the specified one. Also transfers the database connection object, if the object implements the DatabaseConnectionHandler interface.
        Parameters:
        o - the template
        expand - whether to expand variables to their current value instead of using the placeholders
        transferVars - if not expanding variables, whether to transfer the variables
        Returns:
        the copy with the same options, null in case of an error
        See Also:
        DatabaseConnectionHandler

      • shallowCopy

        public static OptionHandler[] shallowCopy​(OptionHandler[] o,
                                          boolean expand)
        Creates an OptionHandler array with the same options as the specified one. Also transfers the database connection object, if the object implements the DatabaseConnectionHandler interface.
        Parameters:
        o - the template
        expand - whether to expand variables to their current value instead of using the placeholders
        Returns:
        the copy with the same options, null in case of an error
        See Also:
        DatabaseConnectionHandler

      • shallowCopy

        public static OptionHandler[] shallowCopy​(OptionHandler[] o,
                                          boolean expand,
                                          boolean transferVars)
        Creates an OptionHandler array with the same options as the specified one. Also transfers the database connection object, if the object implements the DatabaseConnectionHandler interface.
        Parameters:
        o - the template
        expand - whether to expand variables to their current value instead of using the placeholders
        transferVars - if not expanding variables, whether to transfer the variables
        Returns:
        the copy with the same options, null in case of an error
        See Also:
        DatabaseConnectionHandler

      • shallowCopy

        public static Object shallowCopy​(Object[] o)
        Attempts to create an object array with the same options as the specified one. Works for objects implementing OptionHandler and other command-line handling objects.
        Parameters:
        o - the object array
        Returns:
        the copy with the same options, null in case of an error
        See Also:
        shallowCopy(Object)

      • checkRemainingOptions

        public static String checkRemainingOptions​(String[] options)
        Checks whether are any options left over and returns a string listing them.
        Parameters:
        options - the options array to check for unparsed options
        Returns:
        null if no options found, otherwise listing the unparsed options

      • helpRequested

        public static boolean helpRequested​(String[] options)
        Checks whether help was requested (either -h or -help).
        Parameters:
        options - the options to check
        Returns:
        true if a help flag is among the options

      • helpRequested

        public static boolean helpRequested​(List<String> options)
        Checks whether help was requested (either -h or -help).
        Parameters:
        options - the options to check
        Returns:
        true if a help flag is among the options

      • hasFlag

        public static boolean hasFlag​(String[] options,
                              String flag)
        Checks whether the flag is in the option string.
        Parameters:
        options - the options to check
        flag - the flag to look for (incl. "-")
        Returns:
        true if a help flag is among the options

      • hasFlag

        public static boolean hasFlag​(List<String> options,
                              String flag)
        Checks whether the flag is in the option string.
        Parameters:
        options - the options to check
        flag - the flag to look for (incl. "-")
        Returns:
        true if a help flag is among the options

      • removeFlag

        public static boolean removeFlag​(String[] options,
                                 String flag)
        Checks whether the flag is in the option string and removes the flag if present.
        Parameters:
        options - the options to check
        flag - the flag to look for (incl. "-")
        Returns:
        true if a help flag is among the options

      • removeFlag

        public static boolean removeFlag​(List<String> options,
                                 String flag)
        Checks whether the flag is in the option string and removes the flag if present.
        Parameters:
        options - the options to check
        flag - the flag to look for (incl. "-")
        Returns:
        true if a help flag is among the options

      • getOption

        public static String getOption​(String[] options,
                               String option)
        Returns the arguments of the specified option, if available.
        Parameters:
        options - the options to check
        option - the option to look for (incl. "-")
        Returns:
        the argument or null if not found

      • getOption

        public static String getOption​(List<String> options,
                               String option)
        Returns the arguments of the specified option, if available.
        Parameters:
        options - the options to check
        option - the option to look for (incl. "-")
        Returns:
        the argument or null if not found

      • removeOption

        public static String removeOption​(String[] options,
                                  String option)
        Returns the arguments of the specified option, if available, and removes the option and argument from the array.
        Parameters:
        options - the options to check
        option - the option to look for (incl. "-")
        Returns:
        the argument or null if not found

      • removeOption

        public static String removeOption​(List<String> options,
                                  String option)
        Returns the arguments of the specified option, if available, and removes the option and argument from the array.
        Parameters:
        options - the options to check
        option - the option to look for (incl. "-")
        Returns:
        the argument or null if not found

      • list

        public static String list​(OptionHandler handler)
        Returns a string with all the options listed.
        Parameters:
        handler - the option handler which options to list
        Returns:
        the generated overview

      • transferOptions

        public static boolean transferOptions​(OptionHandler source,
                                      OptionHandler dest)
        Transfers the option from one OptionHandler to another.
        Parameters:
        source - the object to get the options from
        dest - the object to update with the retrieved options
        Returns:
        true if options successfully set

      • hasPropertyDescriptor

        protected static boolean hasPropertyDescriptor​(Class cls,
                                               String property)
        Checks whether the property descriptors are already available.
        Parameters:
        cls - the class to look for
        property - the name of the property to look for
        Returns:
        true if already cached

      • getPropertyDescriptor

        protected static PropertyDescriptor getPropertyDescriptor​(Class cls,
                                                          String property)
        Returns the property descriptors for the given class/property combination.
        Parameters:
        cls - the class to look for
        property - the name of the property to look for
        Returns:
        the descriptor, null if not found

      • addPropertyDescriptor

        protected static void addPropertyDescriptor​(Class cls,
                                            String property,
                                            PropertyDescriptor descriptor)
        Adds the descriptor to the cache.
        Parameters:
        cls - the class to add the descriptor for
        property - the name of the property to add the descriptor for
        descriptor - the descriptor to add

      • getDescriptor

        public static PropertyDescriptor getDescriptor​(OptionHandler owner,
                                               String property)
        Returns the bean property descriptor for the get/set methods. Should never be null, unless the property cannot be found in the owner.
        Parameters:
        owner - the owner to get the descriptor for
        property - the name of the Java Beans property
        Returns:
        the bean property descriptor

      • pasteSetupFromClipboard

        public static String pasteSetupFromClipboard()
        Obtains a setup string from the clipboard. This command can be spread across several lines, each line (apart from last one) ending with a "\". If that is the case, then the lines are collapsed into a single line.
        Returns:
        the obtained string, null if not available