Class Options

  • All Implemented Interfaces:
    OptionListener, OptionModuleRegistrar, OptionRegistrar

    public class Options
    extends java.lang.Object
    implements OptionRegistrar, OptionModuleRegistrar, OptionListener
    This class functions as a repository for options and their modules. It facilitates registration of options and modules, as well as processing of arguments.

    Information such as help, usage, and versions are displayed when the respective --help and --version options are specified. The --menu option will invoke the built-in menu.

    In the example below, the program processes three simple options.

     public class AboutMe {
    
        private static StringOption name = new StringOption( "Ryan" );
        private static IntOption age = new IntOption( 19 );
        private static DoubleOption bankBalance = new DoubleOption( 15.15 );
    
        public static void main( String args[] ) {
           Options repo = new Options( "java AboutMe" );
           repo.register( "name", 'n', name, "The person's name." );
           repo.register( "age", 'a', age, "The person's age." );
           repo.register( "balance", 'b', "The person's bank balance.",
                           bankBalance );
           repo.process( args );
    g *       System.err.println( "" + name + ", age " + age + " has a " +
                               " bank balance of " + bankBalance + "." );
        }
     }
     

     Copyright (C) Damian Ryan Eads, 2001. All Rights Reserved.
    
     ritopt is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.
    
     ritopt is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
    
     You should have received a copy of the GNU General Public License
     along with ritopt; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
     
    • Constructor Summary

      Constructors 
      Constructor Description
      Options()
      Create an option repository.
      Options​(java.lang.String programName)
      Create an option repository and associated it with a program name.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void displayHelp()
      Displays the program's help which includes a description of each option.
      void displayVersion()
      Displays the version of the program.
      boolean getDebugFlag()
      Returns whether debugging information should be displayed.
      java.lang.String getDefaultOptionFilename()
      Returns the option filename to load or write to if one is not specified.
      java.lang.String getHelp()
      Returns the help information as a string.
      OptionModule getModule​(java.lang.String name)
      Retrieves an option module based on the name passed.
      java.lang.String getUsage()
      Returns usage information of this program.
      java.lang.String getUsageProgram()
      Returns the program name displayed in the usage.
      java.lang.String getVersion()
      Returns the version of the program.
      void loadOptionFile​(java.lang.String filename)
      Loads all options and their modules from an options file.
      boolean moduleExists​(java.lang.String name)
      Returns a boolean indicating whether an option module exists.
      void optionInvoked​(OptionEvent event)
      Receives NotifyOption events.
      java.lang.String[] process​(java.lang.String str)
      Process a string representing the invoked options.
      java.lang.String[] process​(java.lang.String[] args)
      Process a string of values representing the invoked options.
      void register​(char shortOption, Option option)
      Register an option into the repository as a short option.
      void register​(OptionModule module)
      Register an option module based on its name.
      void register​(java.lang.String longOption, char shortOption, Option option)
      Register an option into the repository both as a short and long option.
      void register​(java.lang.String longOption, char shortOption, java.lang.String description, Option option)
      Register an option into the repository both as a short and long option.
      void register​(java.lang.String longOption, char shortOption, java.lang.String description, Option option, boolean deprecated)
      Register an option into the repository both as a short and long option.
      void register​(java.lang.String longOption, Option option)
      Register an option into the repository as a long option.
      void register​(java.lang.String name, OptionModule module)
      Register an option module and associate it with the name passed.
      void setDebugFlag​(boolean flag)
      Sets the debugging flag.
      void setDefaultOptionFilename​(java.lang.String fn)
      Sets the option file to use when an option file is not specified.
      void setDisplayUsage​(boolean b)
      Sets whether usage can be displayed.
      void setUsageProgram​(java.lang.String program)
      Sets the program to display when the usage is displayed.
      void setUseMenu​(boolean b)
      Sets whether the built-in menu system can be used.
      void setVersion​(java.lang.String version)
      Sets the version of the program.
      boolean shouldDisplayUsage()
      Returns whether the help information should display usage.
      boolean shouldUseMenu()
      Returns whether the built-in menu system can be invoked.
      java.lang.String[] split​(java.lang.String str)
      Splits a string representing command line arguments into several strings.
      void writeOptionFile​(java.lang.String filename)
      Writes all options and their modules out to an options file.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • DEFAULT_VERBOSITY

        public static final int DEFAULT_VERBOSITY
        The default verbosity.
        See Also:
        Constant Field Values
      • DEFAULT_DEPRECATED

        public static final boolean DEFAULT_DEPRECATED
        This boolean defines whether options are deprecated by default.
        See Also:
        Constant Field Values
      • DEFAULT_REASON

        public static final java.lang.String DEFAULT_REASON
        The default reason for deprecation.
        See Also:
        Constant Field Values
      • DEFAULT_GENERAL_MODULE_NAME

        public static final java.lang.String DEFAULT_GENERAL_MODULE_NAME
        The default general module name.
        See Also:
        Constant Field Values
      • DEFAULT_DISPLAY_USAGE

        public static final boolean DEFAULT_DISPLAY_USAGE
        This boolean defines whether usage should be displayed.
        See Also:
        Constant Field Values
      • DEFAULT_USE_MENU

        public static final boolean DEFAULT_USE_MENU
        This boolean defines whether the menu should be used.
        See Also:
        Constant Field Values
      • DEFAULT_PROGRAM_NAME

        public static final java.lang.String DEFAULT_PROGRAM_NAME
        The default program name that is display in the usage.
        See Also:
        Constant Field Values
      • DEFAULT_OPTION_FILENAME

        public static final java.lang.String DEFAULT_OPTION_FILENAME
        The default option file.
        See Also:
        Constant Field Values
    • Constructor Detail

      • Options

        public Options()
        Create an option repository.
      • Options

        public Options​(java.lang.String programName)
        Create an option repository and associated it with a program name.
        Parameters:
        programName - A program name like "java Balloons".
    • Method Detail

      • getHelp

        public java.lang.String getHelp()
        Returns the help information as a string.
        Returns:
        The help information.
      • getUsage

        public java.lang.String getUsage()
        Returns usage information of this program.
        Returns:
        The usage information.
      • getUsageProgram

        public java.lang.String getUsageProgram()
        Returns the program name displayed in the usage.
        Returns:
        The program name.
      • getVersion

        public java.lang.String getVersion()
        Returns the version of the program.
        Returns:
        The version.
      • getDefaultOptionFilename

        public java.lang.String getDefaultOptionFilename()
        Returns the option filename to load or write to if one is not specified.
        Returns:
        The default option filename.
      • getDebugFlag

        public boolean getDebugFlag()
        Returns whether debugging information should be displayed.
        Returns:
        A boolean indicating whether to display help information.
      • shouldDisplayUsage

        public boolean shouldDisplayUsage()
        Returns whether the help information should display usage.
        Returns:
        A boolean indicating whether help should display usage.
      • shouldUseMenu

        public boolean shouldUseMenu()
        Returns whether the built-in menu system can be invoked.
        Returns:
        A boolean indicating whether the build-in menu system can be invoked.
      • setDisplayUsage

        public void setDisplayUsage​(boolean b)
        Sets whether usage can be displayed.
        Parameters:
        b - A boolean value indicating that usage can be displayed.
      • setUseMenu

        public void setUseMenu​(boolean b)
        Sets whether the built-in menu system can be used.
        Parameters:
        b - A boolean value indicating whether the built-in menu system can be used.
      • setUsageProgram

        public void setUsageProgram​(java.lang.String program)
        Sets the program to display when the usage is displayed.
        Parameters:
        program - The program displayed during usage.
      • setVersion

        public void setVersion​(java.lang.String version)
        Sets the version of the program.
        Parameters:
        version - The version.
      • setDefaultOptionFilename

        public void setDefaultOptionFilename​(java.lang.String fn)
        Sets the option file to use when an option file is not specified.
        Parameters:
        fn - The filename of the default option file.
      • setDebugFlag

        public void setDebugFlag​(boolean flag)
        Sets the debugging flag.
        Parameters:
        flag - The value to set the debugging flag.
      • displayHelp

        public void displayHelp()
        Displays the program's help which includes a description of each option. The usage is display if the usage flag is set to true.
      • displayVersion

        public void displayVersion()
        Displays the version of the program.
      • register

        public void register​(java.lang.String longOption,
                             Option option)
        Register an option into the repository as a long option.
        Specified by:
        register in interface OptionRegistrar
        Parameters:
        longOption - The long option name.
        option - The option to register.
      • register

        public void register​(char shortOption,
                             Option option)
        Register an option into the repository as a short option.
        Specified by:
        register in interface OptionRegistrar
        Parameters:
        shortOption - The short option name.
        option - The option to register.
      • register

        public void register​(java.lang.String longOption,
                             char shortOption,
                             Option option)
        Register an option into the repository both as a short and long option.
        Specified by:
        register in interface OptionRegistrar
        Parameters:
        longOption - The long option name.
        shortOption - The short option name.
        option - The option to register.
      • register

        public void register​(java.lang.String longOption,
                             char shortOption,
                             java.lang.String description,
                             Option option)
        Register an option into the repository both as a short and long option. Initialize its description with the description passed.
        Specified by:
        register in interface OptionRegistrar
        Parameters:
        longOption - The long option name.
        shortOption - The short option name.
        description - The description of the option.
        option - The option to register.
      • register

        public void register​(java.lang.String longOption,
                             char shortOption,
                             java.lang.String description,
                             Option option,
                             boolean deprecated)
        Register an option into the repository both as a short and long option. Initialize its description with the description passed.
        Specified by:
        register in interface OptionRegistrar
        Parameters:
        longOption - The long option name.
        shortOption - The short option name.
        description - The description of the option.
        option - The option to register.
        deprecated - A boolean indicating whether an option should be deprecated.
      • register

        public void register​(OptionModule module)
        Register an option module based on its name.
        Specified by:
        register in interface OptionModuleRegistrar
        Parameters:
        module - The option module to register.
      • register

        public void register​(java.lang.String name,
                             OptionModule module)
        Register an option module and associate it with the name passed.
        Specified by:
        register in interface OptionModuleRegistrar
        Parameters:
        name - The name associated with the option module.
        module - The option module to register.
      • process

        public java.lang.String[] process​(java.lang.String[] args)
        Process a string of values representing the invoked options. After all the options are processed, any leftover arguments are returned.
        Parameters:
        args - The arguments to process.
        Returns:
        The leftover arguments.
      • getModule

        public OptionModule getModule​(java.lang.String name)
        Retrieves an option module based on the name passed.
        Parameters:
        name - The name referring to the option module.
        Returns:
        The option module. Null is returned if the module does not exist.
      • moduleExists

        public boolean moduleExists​(java.lang.String name)
        Returns a boolean indicating whether an option module exists.
        Parameters:
        name - The name referring to the option module.
        Returns:
        A boolean value indicating whether the module exists.
      • optionInvoked

        public void optionInvoked​(OptionEvent event)
        Receives NotifyOption events. If the event command equals "help" or "version", the appropriate display methods are invoked.
        Specified by:
        optionInvoked in interface OptionListener
        Parameters:
        event - The event object containing information about the invocation.
      • process

        public java.lang.String[] process​(java.lang.String str)
        Process a string representing the invoked options. This string gets split according to how they would be split when passed to a main method. The split array of options gets passed to a private method for processing. After all the options are processed, any leftover arguments are returned.
        Parameters:
        str - The arguments to process.
        Returns:
        The leftover arguments.
      • split

        public java.lang.String[] split​(java.lang.String str)
        Splits a string representing command line arguments into several strings.
        Parameters:
        str - The string to split.
        Returns:
        The splitted string.
      • writeOptionFile

        public void writeOptionFile​(java.lang.String filename)
        Writes all options and their modules out to an options file.
        Parameters:
        filename - The options filename to write.
      • loadOptionFile

        public void loadOptionFile​(java.lang.String filename)
        Loads all options and their modules from an options file.
        Parameters:
        filename - The options filename to write.