Logo Search packages:      
Sourcecode: jabref version File versions  Download package

Option.java

package gnu.dtools.ritopt;

/**
 * Option.java
 *
 * Version
 *    $Id: Option.java 2209 2007-08-01 18:23:38Z coezbek $
 */


/**
 * 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.<p>
 *
 * Options that provide array support should inherit from the ArrayOption
 * class, and follow the guidelines defined both in the Option and
 * ArrayOption class descriptions.<p>
 *
 * Non-abstract subclasses should implement the modify method. When an option
 * is invoked, the value of the option is passed to the modify method.<p>
 *
 * 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.<p>
 *
 * 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.<p>
 *
 * 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.<p>
 *
 * 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.
 * <p>
 *
 * 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.
 * <pre>
 * Assignment:                           Comment:
 * --longOrShortOption=optionValue       ;description goes here [d]
 * </pre>
 * 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.<p>
 *
 * 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.<p>
 *
 * 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.
 * <hr>
 *
 * <pre>
 * 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
 * </pre>
 *
 * @author Damian Eads
 */

00092 public abstract class Option implements OptionModifiable {

    /**
     * The default width of the option field when the help usage is displayed.
     */

00098     public static final int DEFAULT_HELP_OPTION_SIZE = 22;

    /**
     * The default width of the type name field when the help usage is
     * display.
     */

00105     public static final int DEFAULT_HELP_TYPENAME_SIZE = 10;

    /**
     * The default width of the description when the help usage is displayed.
     */

00111     public static final int DEFAULT_HELP_DESCRIPTION_SIZE = 48;

    /**
     * The default width of the deprecated field when the help usage is
     * displayed.
     */

00118     public static final int DEFAULT_HELP_DEPRECATED_SIZE = 3;

    /**
     * The default width of the option field when the menu usage is displayed.
     */

00124     public static final int DEFAULT_MENU_OPTION_SIZE = 15;

    /**
     * The default width of the type name field when the menu usage is
     * displayed.
     */

00131     public static final int DEFAULT_MENU_TYPENAME_SIZE = 10;

    /**
     * The default width of the description field when the menu usage is
     * displayed.
     */

00138     public static final int DEFAULT_MENU_DESCRIPTION_SIZE = 48;

    /**
     * The default width of the deprecated field when the menu usage is
     * displayed.
     */

00145     public static final int DEFAULT_MENU_DEPRECATED_SIZE = 3;

    /**
     * The default width of the option assignment in an option file.
     */

00151     public static final int DEFAULT_FILE_COMPLETE_OPTION_SIZE = 60;

    /**
     * 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.
     */

00162     public static final int DEFAULT_FILE_COMMENT_SIZE = 16;

    /**
     * The String holding the value of the long option. If there is no
     * long option, this value is set to null.
     */

00169     private String longOption;

    /**
     * The character holding the value of the short option. If there is no
     * short option,t his value is set to '\0'.
     */

00176     private char shortOption;

    /**
     * The String holding the description of this option.
     */

00182     private String description;

    /**
     * A flag identifying whether this option is deprecated.
     */

00188     private boolean deprecated;

    /**
     * The field width for the option specification that is reporter for
     * help.
     */

00195     private static int helpOptionSpecificationSize = DEFAULT_HELP_OPTION_SIZE;

    /**
     * The field width for the type name that is reported for help.
     */

00201     private static int helpTypenameSize = DEFAULT_HELP_TYPENAME_SIZE;

    /**
     * The field width for the description that is reported during help.
     */

00207     private static int helpDescriptionSize = DEFAULT_HELP_DESCRIPTION_SIZE;

    /**
     * The field width for the deprecated flag that is reported during
     * help.
     */

00214     private static int helpDeprecatedSize = DEFAULT_HELP_DEPRECATED_SIZE;

    /**
     * The field width for the option specification that is reported when
     * the options are listed in the built-in menu.
     */

00221     private static int menuOptionSpecificationSize = DEFAULT_MENU_OPTION_SIZE;

    /**
     * The field width for the type name that is reported when the options
     * are listed in the built-in menu.
     */

00228     private static int menuTypenameSize = DEFAULT_MENU_TYPENAME_SIZE;

    /**
     * The field width for the description that is reported when the options
     * are listed in the built-in menu.
     */

00235     private static int menuDescriptionSize = DEFAULT_MENU_DESCRIPTION_SIZE;

    /**
     * The field width for the deprecated flag that is reported when the
     * options are listed in the build-in menu.
     */

00242     private static int menuDeprecatedSize = DEFAULT_MENU_DEPRECATED_SIZE;

    /**
     * The field width for the assignment portion of an option that is 
     * written to a file.
     */

00249     private static int fileCompleteOptionSize =
                                            DEFAULT_FILE_COMPLETE_OPTION_SIZE;

    /**
     * The field width for the comment portion of an option that is written
     * to a file.
     */

00257     private static int fileCommentSize = DEFAULT_FILE_COMMENT_SIZE;

    /**
     * A field indicating whether an option has been invoked.
     */

00263     protected boolean invoked;

    /**
     * Returns this option's value as an Object.
     *
     * @return An object representation of this option.
     */

    public abstract Object getObject();

    /**
     * Returns the option's value as a String. This String should conform
     * to the formatting requirements prescribed by a modify method.
     *
     * @return The option's value as a String conforming to formatting
     *         requirements.
     */

    public abstract String getStringValue();

    /**
     * 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.
     */

00289     public Option() {
      super();
      description = "";
    }

    /**
     * Constructs an option by copying the option passed.
     *
     * @param option  The option to copy for this object's construction.
     */

00300     public Option( Option option ) {
      longOption = option.getLongOption();
      shortOption = option.getShortOption();
      description = option.getDescription();
      deprecated = option.isDeprecated();
    }

    /**
     * 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.
     *
     * @param longOption The value of the long option
     */

00315     public Option( String longOption ) {
      this.longOption = longOption;
      this.shortOption = '\0';
      description = "";
    }

    /**
     * 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.
     *
     * @param shortOption The value of the short option.
     */

00329     public Option( char shortOption ) {
      this.shortOption = shortOption;
      this.longOption = null;
      description = "";
    }

    /**
     * Constructs an option by initializing its short and long options
     * with the values passed. The description is set to the empty string.
     *
     * @param longOption The value of the long option.
     * @param shortOption The value of the short option.
     */

00343     public Option( String longOption, char shortOption ) {
      this.longOption = longOption;
      this.shortOption = shortOption;
      description = "";
    }

    /**
     * Sets the long option.
     *
     * @param longOption The value to set the long option.
     */

00355     public void setKey( String longOption ) {
      this.longOption = longOption;
    }

    /**
     * Sets the short option.
     *
     * @param shortOption The value to set the short option.
     */

00365     public void setKey( char shortOption ) {
      this.shortOption = shortOption;
    }

    /**
     * Sets the short option.
     *
     * @param shortOption The value to set the short option.
     */

00375     public void setShortOption( char shortOption ) {
      setKey( shortOption );
    }

    /**
     * Sets the long option.
     *
     * @param longOption The value to set the long option.
     */

00385     public void setLongOption( String longOption ) {
      setKey( longOption );
    }

    /**
     * Sets the description of this option.
     *
     * @param description The description of this option.
     */

00395     public void setDescription( String description ) {
      this.description = description;
    }

    /**
     * Sets the deprecated flag to the value passed.
     *
     * @param deprecated A flag indicating whether the option is deprecated.
     */

00405     public void setDeprecated( boolean deprecated ) {
      this.deprecated = deprecated;
    }

    /**
     * Sets the field width for the option specification displayed
     * in the help report.
     *
     * @param newSize The size to set the field width.
     */

00416     public static void setHelpOptionSpecificationSize( int newSize ) {
      helpOptionSpecificationSize = newSize;
    }

    /**
     * Sets the field width for the type name displayed in the help report.
     *
     * @param newSize The size to set the field width.
     */

00426     public static void setHelpTypenameSize( int newSize ) {
      helpTypenameSize = newSize;
    }

    /**
     * Sets the field width for the description displayed in the help report.
     *
     * @param newSize The size to set the field width.
     */

00436     public static void setHelpDescriptionSize( int newSize ) {
      helpDescriptionSize = newSize;
    }

    /**
     * Sets the field width for the deprecated flag displayed in the
     * help report.
     *
     * @param newSize The size to set the field width.
     */

00447     public static void setHelpDeprecatedSize( int newSize ) {
      helpDeprecatedSize = newSize;
    }

    /**
     * Sets the field width for the option specification displayed
     * in the menu listing of options.
     *
     * @param newSize The size to set the field width.
     */

00458     public static void setMenuOptionSpecificationSize( int newSize ) {
      menuOptionSpecificationSize = newSize;
    }

    /**
     * Sets the field width for the type name displayed in the menu
     * listing of options.
     *
     * @param newSize The size to set the field width.
     */

00469     public static void setMenuTypenameSize( int newSize ) {
      menuTypenameSize = newSize;
    }

    /**
     * Sets the field width for the option description displayed
     * in the menu listing of options.
     *
     * @param newSize The size to set the field width.
     */

00480     public static void setMenuDescriptionSize( int newSize ) {
      menuDescriptionSize = newSize;
    }

    /**
     * Sets the field width for the deprecated flag displayed
     * in the menu listing of options.
     *
     * @param newSize The size to set the field width.
     */

00491     public static void setMenuDeprecatedSize( int newSize ) {
      menuDeprecatedSize = newSize;
    }

    /**
     * Sets the assignment field width used when options files are written.
     *
     * @param newSize The size to set the field width.
     */

00501     public static void setFileCompleteOptionSize( int newSize ) {
      fileCompleteOptionSize = newSize;
    }

    /**
     * Sets the assignment field width used when options files are written.
     *
     * @param newSize The size to set the field width.
     */

00511     public static void setFileCommentSize( int newSize ) {
      fileCommentSize = newSize;
    }

    /**
     * Sets whether this option has been invoked.
     *
     * @param A boolean indicating whether this option has been invoked.
     */

00521     public void setInvoked( boolean b ) {
      invoked = b;
    }

    /**
     * Deprecates this option.
     */

00529     public void deprecate() {
      setDeprecated( true );
    }

    /**
     * Return the name of this option. This method returns the same value as
     * the getLongOption accessor.
     *
     * @return The name of this otpion.
     */

00540     public String getName() {
      return longOption;
    }

    /**
     * Return the short option key. There is no short option when this
     * character is the null character.
     *
     * @return The short option key of this option.
     */

00551     public char getShortOption() {
      return shortOption;
    }

    /**
     * Return the long option key. There is no long option when this value
     * is null.
     *
     * @return The long option key of this option.
     */

00562     public String getLongOption() {
      return longOption;
    }


    /**
     * Return a line used for help reporting.
     *
     * @return A line used for help reporting.
     */

00573     public String getHelp() {
      return getHelpOptionSpecification() + " " + getHelpTypeName() + " "
          + getHelpDescription() + " " + getHelpDeprecated();
    }

    /**
     * Return the option specification field used during help reporting.
     *
     * @return The option specification field.
     */

00584     public String getHelpOptionSpecification() {
      return Utility.expandString(
          ( ( ( shortOption != '\0' ) ? ( "-" + getShortOption() ) : "  " )
          + ( ( longOption != null && shortOption != '\0' ) ? ", " : "  " )
          + ( ( longOption != null ) ? "--" + getLongOption(): "" ) ),
                       helpOptionSpecificationSize );
    }

    /**
     * Return the type name field used during help reporting.
     *
     * @return The type name field.
     */

00598     public String getHelpTypeName() {
      return Utility.expandString( "<" + getTypeName() + ">",
                             helpTypenameSize );
    }

    /**
     * Return the description field used during help reporting.
     *
     * @return The description field.
     */

00609     public String getHelpDescription() {
      return Utility.expandString( getDescription(),
                       helpDescriptionSize );
    }

    /**
     * Return the deprecated field used during help reporting.
     *
     * @return The deprecated field.
     */

00620     public String getHelpDeprecated() {
      return Utility.expandString( isDeprecated() ? "[d]" : "",
                       helpDeprecatedSize );
    }

    /**
     * Return the header displayed at the top of the help report.
     *
     * @return The header displayed at the top of the help report.
     */

00631     public static String getHelpHeader() {
      return Utility.expandString( "Option Name",
                             helpOptionSpecificationSize ) + " "
          + Utility.expandString( "Type", helpTypenameSize ) + " "
          + Utility.expandString( "Description", helpDescriptionSize );
    }

    /**
     * The description explaining the meaning of this option.
     *
     * @return This options description.
     */

00644     public String getDescription() {
      return description;
    }

    /**
     * The hash key of this option. This is used by classes that implement
     * the option registrar class. This method should <b>not</b> be overrided.
     *
     * @return The hash key of this option.
     */

00655     public String getHashKey() {
      return Option.getHashKey( longOption, shortOption );
    }

    /**
     * The hash key of an option if there is no short option. This method
     * should <b>not</b> be overrided.
     *
     * @param longOption The long option.
     *
     * @return The hash key of this option based on the long option.
     */

00668     public static String getHashKey( String longOption ) {
      return "," + ( ( longOption != null ) ? longOption : "" );
    }

    /**
     * The hash key of an option if there is no long option. This method
     * should <b>not</b> be overrided.
     *
     * @param shortOption The short option.
     *
     * @return The hash key of this option based on the short option.
     */

00681     public static String getHashKey( char shortOption ) {
      return "" + ( shortOption != '\0' ) + ",";
    }

    /**
     * The hash key of an option if there both short and long options are
     * defined.
     *
     * @param shortOption The short option.
     * @param longOption  The long option.
     *
     * @return The hash key of this option based on both the short and long
     *         options.
     */

00696     public static String getHashKey( String longOption, char shortOption ) {
      return ( ( shortOption == '\0' ) ? "" : "" + shortOption ) +
          ( ( longOption == null ) ? "," : "," + longOption );
    }

    /**
     * Returns whether this option is deprecated.
     *
     * @return A boolean indicating whether this option is deprecated.
     */

00707     public boolean isDeprecated() {
      return deprecated;
    }

    /**
     * Returns whether this option has been invoked.
     *
     * @return A boolean indicating whether this option has been invoked.
     */

00717     public boolean isInvoked() {
      return invoked;
    }

    /**
     * Returns (a) line(s) representing this option. This line is usually
     * later written to an options file.
     *
     * @return Line(s) representing this option.
     */

00728     public String getOptionFileLine() {
      boolean descriptionPrinted = false;
      String retval = "";
      String optionText = "";
      String strval = getStringValue();
      if ( longOption != null ) {
          optionText += "--" + longOption;
      }
      else if ( shortOption != '\0' ) {
          optionText += "-" + shortOption;
      }
      if ( optionText.length() > 0
           && Utility.trim( strval ).length() >= 0 ) {
          optionText += "=" + strval;
      }
      if ( optionText.length() <= fileCompleteOptionSize ) {
          retval += Utility.expandString( optionText,
                                  fileCompleteOptionSize );
      }
      else {
          retval += "; " + description + "\n";
          retval += optionText;
          descriptionPrinted = true;
      }
      if ( !descriptionPrinted ) { 
          StringBuffer descsplit = new StringBuffer( description );
          boolean tmp = false;
          while ( descsplit.length() > 0 ) {
            String st = "";
            int size = 0;
            if ( tmp ) {
                st += Utility.getSpaces( fileCompleteOptionSize );
            }
            size = ( descsplit.length() >= fileCommentSize )
                ? fileCommentSize : descsplit.length();
            st += "; " + descsplit.substring( 0, size );
            descsplit.delete( 0, size );
            retval += st + "\n";
            tmp = true;
          }
          descriptionPrinted = true;
      }
      return retval;
    }

    /**
     * Returns the field width for the option specification displayed in the
     * help report.
     *
     * @return The field width.
     */

00780     public static int getHelpOptionSpecificationSize() {
      return helpOptionSpecificationSize;
    }

    /**
     * Returns the field width for the type name displayed in the help report.
     *
     * @return The field width.
     */

00790     public static int getHelpTypenameSize() {
      return helpTypenameSize;
    }

    /**
     * Returns the field width for the description displayed in the help
     * report.
     *
     * @return The field width.
     */

00801     public static int getHelpDescriptionSize() {
      return helpDescriptionSize;
    }

    /**
     * Returns the field width for the deprecated flag displayed in the
     * help report.
     *
     * @return The field width.
     */

00812     public static int getHelpDeprecatedSize() {
      return helpDeprecatedSize;
    }

    /**
     * Returns the field width for the option specification displayed in the
     * menu listing of options.
     *
     * @return The field width.
     */

00823     public static int getMenuOptionSpecificationSize() {
      return menuOptionSpecificationSize;
    }

    /**
     * Returns the field width for the type name displayed in the
     * menu listing of options.
     *
     * @return The field width.
     */

00834     public static int getMenuTypenameSize() {
      return menuTypenameSize;
    }

    /**
     * Returns the field width for the description displayed in the
     * menu listing of options.
     *
     * @return The field width.
     */

00845     public static int getMenuDescriptionSize() {
      return menuDescriptionSize;
    }

    /**
     * Returns the field width for the deprecated flag displayed in the
     * menu listing of options.
     *
     * @return The field width.
     */

00856     public static int getMenuDeprecatedSize() {
      return menuDeprecatedSize;
    }

    /**
     * Returns the field width for assignment portion of a option file line.
     *
     * @return The field width.
     */

00866     public static int getFileCompleteOptionSize() {
      return fileCompleteOptionSize;
    }

    /**
     * Returns the field width for assignment portion of a option file line.
     *
     * @return The field width.
     */

00876     public static int getFileCommentSize() {
      return fileCommentSize;
    }

    /**
     * Returns the type name of this option.
     *
     * @return The type name of this option.
     */

    public abstract String getTypeName();

    /**
     * Prepares the option for modification.
     */

00892     public void action() {
      if ( deprecated ) {
          System.err.print( "Warning: " );
          if ( longOption != null ) {
            System.err.print( "--" + longOption );
          }
          if ( shortOption != '\0' && longOption != null ) {
            System.err.print( " or " );
          }
          if ( shortOption != '\0' ) {
            System.err.println( "-" + shortOption + " is deprecated." );
          }
      }
    }

} /** Option */






Generated by  Doxygen 1.6.0   Back to index