Class Option
- java.lang.Object
-
- gnu.dtools.ritopt.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
-
-
Field Summary
Fields Modifier and Type Field Description static int
DEFAULT_FILE_COMMENT_SIZE
The default width of the comment in an option file.static int
DEFAULT_FILE_COMPLETE_OPTION_SIZE
The default width of the option assignment in an option file.static int
DEFAULT_HELP_DEPRECATED_SIZE
The default width of the deprecated field when the help usage is displayed.static int
DEFAULT_HELP_DESCRIPTION_SIZE
The default width of the description when the help usage is displayed.static int
DEFAULT_HELP_OPTION_SIZE
The default width of the option field when the help usage is displayed.static int
DEFAULT_HELP_TYPENAME_SIZE
The default width of the type name field when the help usage is display.static int
DEFAULT_MENU_DEPRECATED_SIZE
The default width of the deprecated field when the menu usage is displayed.static int
DEFAULT_MENU_DESCRIPTION_SIZE
The default width of the description field when the menu usage is displayed.static int
DEFAULT_MENU_OPTION_SIZE
The default width of the option field when the menu usage is displayed.static int
DEFAULT_MENU_TYPENAME_SIZE
The default width of the type name field when the menu usage is displayed.protected boolean
invoked
A field indicating whether an option has been invoked.
-
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
-
Methods inherited from interface gnu.dtools.ritopt.OptionModifiable
modify
-
-
-
-
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.
-
-