Class Option

  • All Implemented Interfaces:
    OptionModifiable
    Direct Known Subclasses:
    ArrayOption, BooleanOption, ByteOption, CharOption, DoubleOption, FloatOption, IntOption, LongOption, NotifyOption, ShortOption, StringOption

    public abstract class Option
    extends java.lang.Object
    implements OptionModifiable
    This is the principal base class for all Option classes. It contains constructors for short and long option initialization, utility members for help reporting and file writing, and deprecation facilities.

    Options that provide array support should inherit from the ArrayOption class, and follow the guidelines defined both in the Option and ArrayOption class descriptions.

    Non-abstract subclasses should implement the modify method. When an option is invoked, the value of the option is passed to the modify method.

    Subclasses should provide several constructors so that registration is simple and uniform. Recommended constructors include a default constructor, an interface for initialization of short and long options, and one that allows both short and long option fields to be initialized. If the subclass implementation provides constructors which initialize its members then the member parameters must be before the short and long option initialization parameters.

    Event driven option processing is provided in the NotifyOption class. In order to use a NotifyOption, the recipient object must implement the OptionListener class. Although it is not required, subclass implementations of NotifyOption should implement the OptionNotifier interface.

    By default, the Option class considers the width of an output device to be eighty characters. It initializes the width of the help fields based on this figure. If a field exceeds its field width, it is truncated. The width constraints can be changed by invoking the appropriate static mutators.

    Similar to the help reporting facilities, the same constraints are placed on the listing of options provided by the built-in menu interface. These constraints can be modified by executing the appropriate static mutators.

    The Option class provides a facility for writing options files. For option file writing, there are only two field width constraints; the assignment and the comment.

     Assignment:                           Comment:
     --longOrShortOption=optionValue       ;description goes here [d]
     
    As shown above, an assignment includes the long or short option text, an equal sign, and the option's value. The comment includes the description, and "[d]" if the option is deprecated.

    If the assignment exceeds its field width, the comment is placed before the assignment on a separate line. The comment is truncated if it exceeds eighty characters when it is placed before the assignment. However, if the assignment does not exceeds its field width and the comment does, the comment is truncated, and continued on the next line at the columnar position defined by the assignment's field width. Field widths may be modified by invoking the appropriate static mutator.

    This class also provides a facility for deprecating options. An option is deprecated to discourage its use without removing the functionality it provides. An option is deprecated by invoking the deprecate method.


     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
      Option()
      Constructs an option with no initial short or long option value, and is by default uninvoked and undeprecated, and has a description initialized to the empty string.
      Option​(char shortOption)
      Constructs an option by initializing its short option with the value passed.
      Option​(Option option)
      Constructs an option by copying the option passed.
      Option​(java.lang.String longOption)
      Constructs an option by initializing its long option with the value passed.
      Option​(java.lang.String longOption, char shortOption)
      Constructs an option by initializing its short and long options with the values passed.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void action()
      Prepares the option for modification.
      void deprecate()
      Deprecates this option.
      java.lang.String getDescription()
      The description explaining the meaning of this option.
      static int getFileCommentSize()
      Returns the field width for assignment portion of a option file line.
      static int getFileCompleteOptionSize()
      Returns the field width for assignment portion of a option file line.
      java.lang.String getHashKey()
      The hash key of this option.
      static java.lang.String getHashKey​(char shortOption)
      The hash key of an option if there is no long option.
      static java.lang.String getHashKey​(java.lang.String longOption)
      The hash key of an option if there is no short option.
      static java.lang.String getHashKey​(java.lang.String longOption, char shortOption)
      The hash key of an option if there both short and long options are defined.
      java.lang.String getHelp()
      Return a line used for help reporting.
      java.lang.String getHelpDeprecated()
      Return the deprecated field used during help reporting.
      static int getHelpDeprecatedSize()
      Returns the field width for the deprecated flag displayed in the help report.
      java.lang.String getHelpDescription()
      Return the description field used during help reporting.
      static int getHelpDescriptionSize()
      Returns the field width for the description displayed in the help report.
      static java.lang.String getHelpHeader()
      Return the header displayed at the top of the help report.
      java.lang.String getHelpOptionSpecification()
      Return the option specification field used during help reporting.
      static int getHelpOptionSpecificationSize()
      Returns the field width for the option specification displayed in the help report.
      java.lang.String getHelpTypeName()
      Return the type name field used during help reporting.
      static int getHelpTypenameSize()
      Returns the field width for the type name displayed in the help report.
      java.lang.String getLongOption()
      Return the long option key.
      static int getMenuDeprecatedSize()
      Returns the field width for the deprecated flag displayed in the menu listing of options.
      static int getMenuDescriptionSize()
      Returns the field width for the description displayed in the menu listing of options.
      static int getMenuOptionSpecificationSize()
      Returns the field width for the option specification displayed in the menu listing of options.
      static int getMenuTypenameSize()
      Returns the field width for the type name displayed in the menu listing of options.
      java.lang.String getName()
      Return the name of this option.
      abstract java.lang.Object getObject()
      Returns this option's value as an Object.
      java.lang.String getOptionFileLine()
      Returns (a) line(s) representing this option.
      char getShortOption()
      Return the short option key.
      abstract java.lang.String getStringValue()
      Returns the option's value as a String.
      abstract java.lang.String getTypeName()
      Returns the type name of this option.
      boolean isDeprecated()
      Returns whether this option is deprecated.
      boolean isInvoked()
      Returns whether this option has been invoked.
      void setDeprecated​(boolean deprecated)
      Sets the deprecated flag to the value passed.
      void setDescription​(java.lang.String description)
      Sets the description of this option.
      static void setFileCommentSize​(int newSize)
      Sets the assignment field width used when options files are written.
      static void setFileCompleteOptionSize​(int newSize)
      Sets the assignment field width used when options files are written.
      static void setHelpDeprecatedSize​(int newSize)
      Sets the field width for the deprecated flag displayed in the help report.
      static void setHelpDescriptionSize​(int newSize)
      Sets the field width for the description displayed in the help report.
      static void setHelpOptionSpecificationSize​(int newSize)
      Sets the field width for the option specification displayed in the help report.
      static void setHelpTypenameSize​(int newSize)
      Sets the field width for the type name displayed in the help report.
      void setInvoked​(boolean b)
      Sets whether this option has been invoked.
      void setKey​(char shortOption)
      Sets the short option.
      void setKey​(java.lang.String longOption)
      Sets the long option.
      void setLongOption​(java.lang.String longOption)
      Sets the long option.
      static void setMenuDeprecatedSize​(int newSize)
      Sets the field width for the deprecated flag displayed in the menu listing of options.
      static void setMenuDescriptionSize​(int newSize)
      Sets the field width for the option description displayed in the menu listing of options.
      static void setMenuOptionSpecificationSize​(int newSize)
      Sets the field width for the option specification displayed in the menu listing of options.
      static void setMenuTypenameSize​(int newSize)
      Sets the field width for the type name displayed in the menu listing of options.
      void setShortOption​(char shortOption)
      Sets the short option.
      • Methods inherited from class java.lang.Object

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

      • DEFAULT_HELP_OPTION_SIZE

        public static final int DEFAULT_HELP_OPTION_SIZE
        The default width of the option field when the help usage is displayed.
        See Also:
        Constant Field Values
      • DEFAULT_HELP_TYPENAME_SIZE

        public static final int DEFAULT_HELP_TYPENAME_SIZE
        The default width of the type name field when the help usage is display.
        See Also:
        Constant Field Values
      • DEFAULT_HELP_DESCRIPTION_SIZE

        public static final int DEFAULT_HELP_DESCRIPTION_SIZE
        The default width of the description when the help usage is displayed.
        See Also:
        Constant Field Values
      • DEFAULT_HELP_DEPRECATED_SIZE

        public static final int DEFAULT_HELP_DEPRECATED_SIZE
        The default width of the deprecated field when the help usage is displayed.
        See Also:
        Constant Field Values
      • DEFAULT_MENU_OPTION_SIZE

        public static final int DEFAULT_MENU_OPTION_SIZE
        The default width of the option field when the menu usage is displayed.
        See Also:
        Constant Field Values
      • DEFAULT_MENU_TYPENAME_SIZE

        public static final int DEFAULT_MENU_TYPENAME_SIZE
        The default width of the type name field when the menu usage is displayed.
        See Also:
        Constant Field Values
      • DEFAULT_MENU_DESCRIPTION_SIZE

        public static final int DEFAULT_MENU_DESCRIPTION_SIZE
        The default width of the description field when the menu usage is displayed.
        See Also:
        Constant Field Values
      • DEFAULT_MENU_DEPRECATED_SIZE

        public static final int DEFAULT_MENU_DEPRECATED_SIZE
        The default width of the deprecated field when the menu usage is displayed.
        See Also:
        Constant Field Values
      • DEFAULT_FILE_COMPLETE_OPTION_SIZE

        public static final int DEFAULT_FILE_COMPLETE_OPTION_SIZE
        The default width of the option assignment in an option file.
        See Also:
        Constant Field Values
      • DEFAULT_FILE_COMMENT_SIZE

        public static final int DEFAULT_FILE_COMMENT_SIZE
        The default width of the comment in an option file. If the option and the comment exceeds the width of the device, the comment is truncated to the next line at the same columnar position of the previous comment line. If the option assignment line is longer than the width, the comment line is put before the option assignment it refers.
        See Also:
        Constant Field Values
      • invoked

        protected boolean invoked
        A field indicating whether an option has been invoked.
    • Constructor Detail

      • Option

        public Option()
        Constructs an option with no initial short or long option value, and is by default uninvoked and undeprecated, and has a description initialized to the empty string.
      • Option

        public Option​(Option option)
        Constructs an option by copying the option passed.
        Parameters:
        option - The option to copy for this object's construction.
      • Option

        public Option​(java.lang.String longOption)
        Constructs an option by initializing its long option with the value passed. The short option is equal to the null character, and the description is equal to the empty string.
        Parameters:
        longOption - The value of the long option
      • Option

        public Option​(char shortOption)
        Constructs an option by initializing its short option with the value passed. The long option is equal to null, and the description is equal to the empty string.
        Parameters:
        shortOption - The value of the short option.
      • Option

        public Option​(java.lang.String longOption,
                      char shortOption)
        Constructs an option by initializing its short and long options with the values passed. The description is set to the empty string.
        Parameters:
        longOption - The value of the long option.
        shortOption - The value of the short option.
    • Method Detail

      • getObject

        public abstract java.lang.Object getObject()
        Returns this option's value as an Object.
        Returns:
        An object representation of this option.
      • getStringValue

        public abstract java.lang.String getStringValue()
        Returns the option's value as a String. This String should conform to the formatting requirements prescribed by a modify method.
        Returns:
        The option's value as a String conforming to formatting requirements.
      • setKey

        public void setKey​(java.lang.String longOption)
        Sets the long option.
        Parameters:
        longOption - The value to set the long option.
      • setKey

        public void setKey​(char shortOption)
        Sets the short option.
        Parameters:
        shortOption - The value to set the short option.
      • setShortOption

        public void setShortOption​(char shortOption)
        Sets the short option.
        Parameters:
        shortOption - The value to set the short option.
      • setLongOption

        public void setLongOption​(java.lang.String longOption)
        Sets the long option.
        Parameters:
        longOption - The value to set the long option.
      • setDescription

        public void setDescription​(java.lang.String description)
        Sets the description of this option.
        Parameters:
        description - The description of this option.
      • setDeprecated

        public void setDeprecated​(boolean deprecated)
        Sets the deprecated flag to the value passed.
        Parameters:
        deprecated - A flag indicating whether the option is deprecated.
      • setHelpOptionSpecificationSize

        public static void setHelpOptionSpecificationSize​(int newSize)
        Sets the field width for the option specification displayed in the help report.
        Parameters:
        newSize - The size to set the field width.
      • setHelpTypenameSize

        public static void setHelpTypenameSize​(int newSize)
        Sets the field width for the type name displayed in the help report.
        Parameters:
        newSize - The size to set the field width.
      • setHelpDescriptionSize

        public static void setHelpDescriptionSize​(int newSize)
        Sets the field width for the description displayed in the help report.
        Parameters:
        newSize - The size to set the field width.
      • setHelpDeprecatedSize

        public static void setHelpDeprecatedSize​(int newSize)
        Sets the field width for the deprecated flag displayed in the help report.
        Parameters:
        newSize - The size to set the field width.
      • setMenuOptionSpecificationSize

        public static void setMenuOptionSpecificationSize​(int newSize)
        Sets the field width for the option specification displayed in the menu listing of options.
        Parameters:
        newSize - The size to set the field width.
      • setMenuTypenameSize

        public static void setMenuTypenameSize​(int newSize)
        Sets the field width for the type name displayed in the menu listing of options.
        Parameters:
        newSize - The size to set the field width.
      • setMenuDescriptionSize

        public static void setMenuDescriptionSize​(int newSize)
        Sets the field width for the option description displayed in the menu listing of options.
        Parameters:
        newSize - The size to set the field width.
      • setMenuDeprecatedSize

        public static void setMenuDeprecatedSize​(int newSize)
        Sets the field width for the deprecated flag displayed in the menu listing of options.
        Parameters:
        newSize - The size to set the field width.
      • setFileCompleteOptionSize

        public static void setFileCompleteOptionSize​(int newSize)
        Sets the assignment field width used when options files are written.
        Parameters:
        newSize - The size to set the field width.
      • setFileCommentSize

        public static void setFileCommentSize​(int newSize)
        Sets the assignment field width used when options files are written.
        Parameters:
        newSize - The size to set the field width.
      • setInvoked

        public void setInvoked​(boolean b)
        Sets whether this option has been invoked.
        Parameters:
        b - A boolean indicating whether this option has been invoked.
      • deprecate

        public void deprecate()
        Deprecates this option.
      • getName

        public java.lang.String getName()
        Return the name of this option. This method returns the same value as the getLongOption accessor.
        Returns:
        The name of this otpion.
      • getShortOption

        public char getShortOption()
        Return the short option key. There is no short option when this character is the null character.
        Returns:
        The short option key of this option.
      • getLongOption

        public java.lang.String getLongOption()
        Return the long option key. There is no long option when this value is null.
        Returns:
        The long option key of this option.
      • getHelp

        public java.lang.String getHelp()
        Return a line used for help reporting.
        Returns:
        A line used for help reporting.
      • getHelpOptionSpecification

        public java.lang.String getHelpOptionSpecification()
        Return the option specification field used during help reporting.
        Returns:
        The option specification field.
      • getHelpTypeName

        public java.lang.String getHelpTypeName()
        Return the type name field used during help reporting.
        Returns:
        The type name field.
      • getHelpDescription

        public java.lang.String getHelpDescription()
        Return the description field used during help reporting.
        Returns:
        The description field.
      • getHelpDeprecated

        public java.lang.String getHelpDeprecated()
        Return the deprecated field used during help reporting.
        Returns:
        The deprecated field.
      • getHelpHeader

        public static java.lang.String getHelpHeader()
        Return the header displayed at the top of the help report.
        Returns:
        The header displayed at the top of the help report.
      • getDescription

        public java.lang.String getDescription()
        The description explaining the meaning of this option.
        Returns:
        This options description.
      • getHashKey

        public java.lang.String getHashKey()
        The hash key of this option. This is used by classes that implement the option registrar class. This method should not be overrided.
        Returns:
        The hash key of this option.
      • getHashKey

        public static java.lang.String getHashKey​(java.lang.String longOption)
        The hash key of an option if there is no short option. This method should not be overrided.
        Parameters:
        longOption - The long option.
        Returns:
        The hash key of this option based on the long option.
      • getHashKey

        public static java.lang.String getHashKey​(char shortOption)
        The hash key of an option if there is no long option. This method should not be overrided.
        Parameters:
        shortOption - The short option.
        Returns:
        The hash key of this option based on the short option.
      • getHashKey

        public static java.lang.String getHashKey​(java.lang.String longOption,
                                                  char shortOption)
        The hash key of an option if there both short and long options are defined.
        Parameters:
        shortOption - The short option.
        longOption - The long option.
        Returns:
        The hash key of this option based on both the short and long options.
      • isDeprecated

        public boolean isDeprecated()
        Returns whether this option is deprecated.
        Returns:
        A boolean indicating whether this option is deprecated.
      • isInvoked

        public boolean isInvoked()
        Returns whether this option has been invoked.
        Returns:
        A boolean indicating whether this option has been invoked.
      • getOptionFileLine

        public java.lang.String getOptionFileLine()
        Returns (a) line(s) representing this option. This line is usually later written to an options file.
        Returns:
        Line(s) representing this option.
      • getHelpOptionSpecificationSize

        public static int getHelpOptionSpecificationSize()
        Returns the field width for the option specification displayed in the help report.
        Returns:
        The field width.
      • getHelpTypenameSize

        public static int getHelpTypenameSize()
        Returns the field width for the type name displayed in the help report.
        Returns:
        The field width.
      • getHelpDescriptionSize

        public static int getHelpDescriptionSize()
        Returns the field width for the description displayed in the help report.
        Returns:
        The field width.
      • getHelpDeprecatedSize

        public static int getHelpDeprecatedSize()
        Returns the field width for the deprecated flag displayed in the help report.
        Returns:
        The field width.
      • getMenuOptionSpecificationSize

        public static int getMenuOptionSpecificationSize()
        Returns the field width for the option specification displayed in the menu listing of options.
        Returns:
        The field width.
      • getMenuTypenameSize

        public static int getMenuTypenameSize()
        Returns the field width for the type name displayed in the menu listing of options.
        Returns:
        The field width.
      • getMenuDescriptionSize

        public static int getMenuDescriptionSize()
        Returns the field width for the description displayed in the menu listing of options.
        Returns:
        The field width.
      • getMenuDeprecatedSize

        public static int getMenuDeprecatedSize()
        Returns the field width for the deprecated flag displayed in the menu listing of options.
        Returns:
        The field width.
      • getFileCompleteOptionSize

        public static int getFileCompleteOptionSize()
        Returns the field width for assignment portion of a option file line.
        Returns:
        The field width.
      • getFileCommentSize

        public static int getFileCommentSize()
        Returns the field width for assignment portion of a option file line.
        Returns:
        The field width.
      • getTypeName

        public abstract java.lang.String getTypeName()
        Returns the type name of this option.
        Returns:
        The type name of this option.
      • action

        public void action()
        Prepares the option for modification.