xtc.util
Class Runtime

java.lang.Object
  xtc.util.Runtime

public class Runtime
extends java.lang.Object

A tool's runtime. This helper class processes command line options, prints errors and warnings, and manages console output.

Version:

$Revision: 1.27 $

Author:

Robert Grimm

Field Summary

protected Printer	console The console printer.
protected Printer	errConsole The error console printer.
protected int	errors The error count.
protected java.util.Map<java.lang.String,xtc.util.Option>	externalMap The map from external names to options.
static java.lang.String	INPUT_DIRECTORY The internal name for the input directory option.
static java.lang.String	INPUT_ENCODING The internal name for the intput encoding option.
protected java.util.Map<java.lang.String,xtc.util.Option>	internalMap The map from internal names to options.
protected java.util.List<xtc.util.Option>	optionList The list of command line options.
protected java.util.Map<java.lang.String,java.lang.Object>	options The actual options.
static java.lang.String	OUTPUT_DIRECTORY The internal name for the output directory option.
static java.lang.String	OUTPUT_ENCODING The internal name for the output encoding option.
protected int	warnings The warning count.

Constructor Summary

Runtime()
Create a new runtime.

Method Summary

protected void	add(xtc.util.Option option) Add the specified option.
Runtime	att(java.lang.String external, java.lang.String internal, boolean multiple, java.lang.String description) Declare an attribute-valued command line option.
Runtime	bool(java.lang.String external, java.lang.String internal, boolean value, java.lang.String description) Declare a boolean command line option.
protected void	check(xtc.util.Option option, java.lang.Object value) Check that the specified value is valid for the specified option.
protected void	check(java.lang.String external, java.lang.String internal) Check that no option with the specified names exits.
Printer	console() Get a printer to the console.
Runtime	dir(java.lang.String external, java.lang.String internal, boolean multiple, java.lang.String description) Declare a directory-valued command line option.
Printer	errConsole() Get a printer to the error console.
void	error() Record an error reported through another means.
void	error(java.lang.String msg) Print the specified error message.
void	error(java.lang.String msg, Node n) Print the specified error message.
int	errorCount() Get the current error count.
void	exit() Exit the tool.
Runtime	file(java.lang.String external, java.lang.String internal, boolean multiple, java.lang.String description) Declare a file-valued command line option.
long	freeMemory() Get an estimate of free memory.
java.util.List<Attribute>	getAttributeList(java.lang.String name) Get the attribute list value of the specified option.
java.io.File	getFile(java.lang.String name) Get the file value of the specified option.
java.util.List<java.io.File>	getFileList(java.lang.String name) Get the file list value of the specified option.
int	getInt(java.lang.String name) Get the integer value of the specified option.
java.util.List<?>	getList(java.lang.String name) Get the list value of the specified option.
java.io.File	getOutputDirectory() Get this runtime's output directory.
java.io.Reader	getReader(java.io.File file) Get a reader for the specified file.
java.io.Reader	getReader(java.io.InputStream in) Get a reader for the specified input stream.
java.lang.String	getString(java.lang.String name) Get the string value of the specified option.
java.lang.Object	getValue(java.lang.String name) Get the value of the specified option.
java.io.Writer	getWriter(java.io.File file) Get a writer for the specified file.
java.io.Writer	getWriter(java.io.OutputStream in) Get a writer for the specified output stream.
boolean	hasPrefixValue(java.lang.String prefix) Determine whether any option with the specified prefix has a value.
boolean	hasValue(java.lang.String name) Determine whether the specified option has a value.
void	initDefaultValues() Initialize all options without values to their defaults.
void	initFlags(boolean value) Initialize all boolean options without values to the specified value.
void	initFlags(java.lang.String prefix, boolean value) Initialize all boolean options with the specified prefix and without values to the specified value.
java.io.File	locate(java.lang.String path) Locate the specified file.
Runtime	number(java.lang.String external, java.lang.String internal, int value, java.lang.String description) Declare an integer-valued command line option.
void	printOptions() Print a description of all command line options to the console.
int	process(java.lang.String[] args) Process the specified command line arguments.
boolean	seenError() Determine whether errors have been reported.
void	setConsole(Printer console) Update the printer to the console.
void	setErrConsole(Printer console) Update the printer to the error console.
void	setValue(java.lang.String name, boolean value) Set the value of the specified boolean-valued option.
void	setValue(java.lang.String name, java.lang.Object value) Set the value of the specified option.
boolean	test(java.lang.String name) Test the value of the specified boolean option.
void	warning() Record a warning reported through another means.
void	warning(java.lang.String msg) Print the specified warning message.
void	warning(java.lang.String msg, Node n) Print the specified warning message.
Runtime	word(java.lang.String external, java.lang.String internal, boolean multiple, java.lang.String description) Declare a word-valued command line option.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INPUT_DIRECTORY

public static final java.lang.String INPUT_DIRECTORY

The internal name for the input directory option. The option is expected to have multiple directory values.

See Also:

Constant Field Values

OUTPUT_DIRECTORY

public static final java.lang.String OUTPUT_DIRECTORY

The internal name for the output directory option. The option is expected to have a directory value.

See Also:

Constant Field Values

INPUT_ENCODING

public static final java.lang.String INPUT_ENCODING

The internal name for the intput encoding option. The option is expected to have a word value.

See Also:

Constant Field Values

OUTPUT_ENCODING

public static final java.lang.String OUTPUT_ENCODING

The internal name for the output encoding option. The option is expected to have a word value.

See Also:

Constant Field Values

console

protected Printer console

The console printer.

errConsole

protected Printer errConsole

The error console printer.

optionList

protected final java.util.List<xtc.util.Option> optionList

The list of command line options.

externalMap

protected final java.util.Map<java.lang.String,xtc.util.Option> externalMap

The map from external names to options.

internalMap

protected final java.util.Map<java.lang.String,xtc.util.Option> internalMap

The map from internal names to options.

options

protected final java.util.Map<java.lang.String,java.lang.Object> options

The actual options.

errors

protected int errors

The error count.

warnings

protected int warnings

The warning count.

Constructor Detail

Runtime

public Runtime()

Create a new runtime. Note that the list of input directories is empty, while the output directory is initialized to the current directory.

Method Detail

console

public Printer console()

Get a printer to the console.

Returns:

A printer to the console.

setConsole

public void setConsole(Printer console)

Update the printer to the console. Since the console is used throughout xtc, use this method with caution.

Parameters:

console - The new console.

errConsole

public Printer errConsole()

Get a printer to the error console.

Returns:

A printer to the error console.

setErrConsole

public void setErrConsole(Printer console)

Update the printer to the error console. Since the error console is used throughout xtc, use this method with caution.

Parameters:

console - The new error console.

freeMemory

public long freeMemory()

Get an estimate of free memory.

Returns:

An estimate of free memory.

check

protected void check(java.lang.String external,
                     java.lang.String internal)

Check that no option with the specified names exits.

Parameters:

external - The external name.

internal - The internal name.

Throws:

java.lang.IllegalArgumentException - Signals that an option with the external or interal name already exists.

add

protected void add(xtc.util.Option option)

Add the specified option. This method adds the specified option to the optionList, externalMap, and internalMap fields.

Parameters:

option - The option.

bool

public Runtime bool(java.lang.String external,
                    java.lang.String internal,
                    boolean value,
                    java.lang.String description)

Declare a boolean command line option.

Parameters:

external - The external name.

internal - The internal name.

value - The default value.

description - The description.

Returns:

This runtime.

Throws:

java.lang.IllegalArgumentException - Signals that an option with the external or interal name already exists.

word

public Runtime word(java.lang.String external,
                    java.lang.String internal,
                    boolean multiple,
                    java.lang.String description)

Declare a word-valued command line option.

Parameters:

external - The external name.

internal - The internal name.

multiple - The flag for multiple occurrences.

description - The description.

Returns:

This runtime.

Throws:

java.lang.IllegalArgumentException - Signals that an option with the external or interal name already exists.

number

public Runtime number(java.lang.String external,
                      java.lang.String internal,
                      int value,
                      java.lang.String description)

Declare an integer-valued command line option.

Parameters:

external - The external name.

internal - The internal name.

value - The default value.

description - The description.

Returns:

This runtime.

Throws:

java.lang.IllegalArgumentException - Signals that an option with the external or interal name already exists.

file

public Runtime file(java.lang.String external,
                    java.lang.String internal,
                    boolean multiple,
                    java.lang.String description)

Declare a file-valued command line option.

Parameters:

external - The external name.

internal - The internal name.

multiple - The flag for multiple occurrences.

description - The description.

Returns:

This runtime.

Throws:

java.lang.IllegalArgumentException - Signals that an option with the external or interal name already exists.

dir

public Runtime dir(java.lang.String external,
                   java.lang.String internal,
                   boolean multiple,
                   java.lang.String description)

Declare a directory-valued command line option. The default value is the current directory.

Parameters:

external - The external name.

internal - The internal name.

multiple - The flag for multiple occurrences.

description - The description.

Returns:

This runtime.

Throws:

java.lang.IllegalArgumentException - Signals that an option with the external or interal name already exists.

att

public Runtime att(java.lang.String external,
                   java.lang.String internal,
                   boolean multiple,
                   java.lang.String description)

Declare an attribute-valued command line option.

Parameters:

external - The external name.

internal - The internal name.

multiple - The flag for multiple occurrences.

description - The description.

Throws:

java.lang.IllegalArgumentException - Signals that an option with the external or interal name already exists.

printOptions

public void printOptions()

Print a description of all command line options to the console.

process

public int process(java.lang.String[] args)

Process the specified command line arguments. This method sets all options to their specified values.

Parameters:

args - The arguments.

Returns:

The index right after the processed command line options.

initDefaultValues

public void initDefaultValues()

Initialize all options without values to their defaults. The default value for word, file, and attribute options is null if no multiple occurrences are allowed and the empty list otherwise.

initFlags

public void initFlags(boolean value)

Initialize all boolean options without values to the specified value.

Parameters:

value - The value.

initFlags

public void initFlags(java.lang.String prefix,
                      boolean value)

Initialize all boolean options with the specified prefix and without values to the specified value.

Parameters:

prefix - The prefix.

value - The value.

hasValue

public boolean hasValue(java.lang.String name)

Determine whether the specified option has a value.

Parameters:

name - The internal name.

Returns:

true if the option has a value.

hasPrefixValue

public boolean hasPrefixValue(java.lang.String prefix)

Determine whether any option with the specified prefix has a value.

Parameters:

prefix - The prefix.

Returns:

true if any option with the prefix has a value.

getValue

public java.lang.Object getValue(java.lang.String name)

Get the value of the specified option.

Parameters:

name - The internal name.

Returns:

The option's value.

Throws:

java.lang.IllegalArgumentException - Signals that the option has no value.

test

public boolean test(java.lang.String name)

Test the value of the specified boolean option.

Parameters:

name - The internal name.

Returns:

The option's boolean value.

Throws:

java.lang.IllegalArgumentException - Signals that the corresponding option has no value.

java.lang.ClassCastException - Signals that the corresponding option does not have a boolean value.

getInt

public int getInt(java.lang.String name)

Get the integer value of the specified option.

Parameters:

name - The internal name.

Returns:

The option's integer value.

Throws:

java.lang.IllegalArgumentException - Signals that the corresponding option has no value.

java.lang.ClassCastException - Signals that the corresponding option does not have an integer value.

getString

public java.lang.String getString(java.lang.String name)

Get the string value of the specified option.

Parameters:

name - The internal name.

Returns:

The option's string value.

Throws:

java.lang.IllegalArgumentException - Signals that the corresponding option has no value.

java.lang.ClassCastException - Signals that the corresponding option does not have an integer value.

getFile

public java.io.File getFile(java.lang.String name)

Get the file value of the specified option.

Parameters:

name - The internal name.

Returns:

The option's file value.

Throws:

java.lang.IllegalArgumentException - Signals that the corresponding option has no value.

java.lang.ClassCastException - Signals that the corresponding option does not have a file value.

getList

public java.util.List<?> getList(java.lang.String name)

Get the list value of the specified option.

Parameters:

name - The internal name.

Returns:

The option's list value.

Throws:

java.lang.IllegalArgumentException - Signals that the corresponding option has no value.

java.lang.ClassCastException - Signals that the corresponding option does not have a list value.

getAttributeList

public java.util.List<Attribute> getAttributeList(java.lang.String name)

Get the attribute list value of the specified option.

Parameters:

name - The internal name.

Returns:

The option's attribute list value.

Throws:

java.lang.IllegalArgumentException - Signals that the corresponding option has no value.

java.lang.ClassCastException - Signals that the corresponding option does not have an attribute list value.

getFileList

public java.util.List<java.io.File> getFileList(java.lang.String name)

Get the file list value of the specified option.

Parameters:

name - The internal name.

Returns:

The option's file list value.

Throws:

java.lang.IllegalArgumentException - Signals that the corresponding option has no value.

java.lang.ClassCastException - Signals that the corresponding option does not have a file list value.

check

protected void check(xtc.util.Option option,
                     java.lang.Object value)

Check that the specified value is valid for the specified option.

Parameters:

option - The option.

value - The value.

Throws:

java.lang.IllegalArgumentException - Signals that the value is invalid.

setValue

public void setValue(java.lang.String name,
                     java.lang.Object value)

Set the value of the specified option.

Parameters:

name - The internal name.

value - The value.

Throws:

java.lang.IllegalArgumentException - Signals an unrecognized option or an invalid value.

setValue

public void setValue(java.lang.String name,
                     boolean value)

Set the value of the specified boolean-valued option.

Parameters:

name - The internal name.

value - The value.

Throws:

java.lang.IllegalArgumentException - Signals an unrecognized option or not a boolean-valued option.

locate

public java.io.File locate(java.lang.String path)
                    throws java.io.FileNotFoundException

Locate the specified file. This method searches this runtime's list of input directories.

Parameters:

path - The (relative) file path.

Returns:

The corresponding file.

Throws:

java.io.FileNotFoundException - Signals that the specified file could not be found.

See Also:

INPUT_DIRECTORY

getReader

public java.io.Reader getReader(java.io.File file)
                         throws java.io.IOException

Get a reader for the specified file. The reader uses this runtime's input encoding and is buffered.

Parameters:

file - The file.

Returns:

The corresponding reader.

Throws:

java.io.IOException - Signals an I/O error.

See Also:

INPUT_ENCODING

getReader

public java.io.Reader getReader(java.io.InputStream in)
                         throws java.io.UnsupportedEncodingException

Get a reader for the specified input stream. The reader uses this runtime's input encoding and is buffered.

Parameters:

in - The input stream.

Returns:

The corresponding reader.

Throws:

java.io.UnsupportedEncodingException - Signals that this runtime's encoding is not valid.

See Also:

INPUT_ENCODING

getOutputDirectory

public java.io.File getOutputDirectory()

Get this runtime's output directory.

Returns:

The output directory.

See Also:

OUTPUT_DIRECTORY

getWriter

public java.io.Writer getWriter(java.io.File file)
                         throws java.io.IOException

Get a writer for the specified file. The writer uses this runtime's output encoding and is buffered.

Parameters:

file - The file.

Returns:

The corresponding writer.

Throws:

java.io.IOException - Signals an I/O error.

See Also:

OUTPUT_ENCODING

getWriter

public java.io.Writer getWriter(java.io.OutputStream in)
                         throws java.io.UnsupportedEncodingException

Get a writer for the specified output stream. The writer uses this runtime's output encoding and is buffered.

Parameters:

in - The output stream.

Returns:

The corresponding writer.

Throws:

java.io.UnsupportedEncodingException - Signals that this runtime's encoding is not valid.

See Also:

OUTPUT_ENCODING

seenError

public boolean seenError()

Determine whether errors have been reported.

Returns:

true if errors have been reported.

errorCount

public int errorCount()

Get the current error count.

Returns:

The current error count.

error

public void error()

Record an error reported through another means.

error

public void error(java.lang.String msg)

Print the specified error message.

Parameters:

msg - The error message.

error

public void error(java.lang.String msg,
                  Node n)

Print the specified error message.

Parameters:

msg - The error message.

n - The offending node.

warning

public void warning()

Record a warning reported through another means.

warning

public void warning(java.lang.String msg)

Print the specified warning message.

Parameters:

msg - The warning message.

warning

public void warning(java.lang.String msg,
                    Node n)

Print the specified warning message.

Parameters:

msg - The warning message.

n - The offending node.

exit

public void exit()

Exit the tool. This method terminates the Java virtual machine with the appropriate exit code and a summary of error and warning numbers if any have been reported.