gnu.dtools.ritopt
Class Options

java.lang.Object
  |
  +--gnu.dtools.ritopt.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
 

Author:

Damian Eads

Field Summary

static boolean	DEFAULT_DEPRECATED This boolean defines whether options are deprecated by default.
static boolean	DEFAULT_DISPLAY_USAGE This boolean defines whether usage should be displayed.
static java.lang.String	DEFAULT_GENERAL_MODULE_NAME The default general module name.
static java.lang.String	DEFAULT_OPTION_FILENAME The default option file.
static java.lang.String	DEFAULT_PROGRAM_NAME The default program name that is display in the usage.
static java.lang.String	DEFAULT_REASON The default reason for deprecation.
static boolean	DEFAULT_USE_MENU This boolean defines whether the menu should be used.
static int	DEFAULT_VERBOSITY The default verbosity.

Constructor Summary

Options()
Create an option repository.

Options(java.lang.String programName)
Create an option repository and associated it with a program name.

Method Summary

void	displayHelp() Sets the debugging flag.
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	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.

DEFAULT_DEPRECATED

public static final boolean DEFAULT_DEPRECATED

This boolean defines whether options are deprecated by default.

DEFAULT_REASON

public static final java.lang.String DEFAULT_REASON

The default reason for deprecation.

DEFAULT_GENERAL_MODULE_NAME

public static final java.lang.String DEFAULT_GENERAL_MODULE_NAME

The default general module name.

DEFAULT_DISPLAY_USAGE

public static final boolean DEFAULT_DISPLAY_USAGE

This boolean defines whether usage should be displayed.

DEFAULT_USE_MENU

public static final boolean DEFAULT_USE_MENU

This boolean defines whether the menu should be used.

DEFAULT_PROGRAM_NAME

public static final java.lang.String DEFAULT_PROGRAM_NAME

The default program name that is display in the usage.

DEFAULT_OPTION_FILENAME

public static final java.lang.String DEFAULT_OPTION_FILENAME

The default option file.

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.

Parameters:

The - program name.

getVersion

public java.lang.String getVersion()

Returns the version of the program.

Parameters:

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.

displayHelp

public void displayHelp()

Sets the debugging flag.

Parameters:

flag - The value to set the debugging flag. public void setDebugFlag( boolean flag ) { debugFlag = flag; } /** 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:

split - 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.