xtc.util
Class Tool

java.lang.Object
  xtc.util.Tool

Direct Known Subclasses:

Rats

public abstract class Tool
extends java.lang.Object

The superclass of all tools.

Version:

$Revision: 1.26 $

Author:

Robert Grimm

Field Summary

protected Runtime

runtime The runtime.

Constructor Summary

Tool()
Create a new tool.

Method Summary

void	diagnose() Print tool diagnostics.
java.lang.String	getCopy() Get this tool's copyright.
java.lang.String	getExplanation() Get this tool's explanation.
abstract java.lang.String	getName() Get this tool's name.
java.lang.String	getVersion() Get this tool's version.
void	init() Initialize this tool.
java.io.File	locate(java.lang.String name) Locate the file with the specified name.
abstract Node	parse(java.io.Reader in, java.io.File file) Parse the specified file.
void	prepare() Prepare for processing.
void	printHeader(Printer printer) Print a tool header to the specified printer.
void	process(Node node) Process the specified AST node.
void	process(java.lang.String name) Recursively process the file with the specified name.
void	run(java.lang.String[] args) Run this tool with the specified command line arguments.
void	wrapUp() Wrap up this tool.

Methods inherited from class java.lang.Object

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

Field Detail

runtime

protected final Runtime runtime

The runtime.

Constructor Detail

Tool

public Tool()

Create a new tool.

Method Detail

getName

public abstract java.lang.String getName()

Get this tool's name.

Returns:

The name.

getVersion

public java.lang.String getVersion()

Get this tool's version. The default implementation returns Constants.VERSION.

Returns:

The version.

getCopy

public java.lang.String getCopy()

Get this tool's copyright. The default implementation returns Constants.FULL_COPY.

Returns:

The copyright.

getExplanation

public java.lang.String getExplanation()

Get this tool's explanation. This method should return any text to print after this tool's description of options. The text is automatically line-wrapped. The default implementation returns null to indicate that there is no explanation.

Returns:

The explanation.

init

public void init()

Initialize this tool. This method declares this tool's command line options. The default implementation declares

• a boolean option optionSilent for silent operation,
• a boolean option optionVerbose for verbose operation,
• a boolean option optionNoExit for not exiting the Java virtual machine,
• a multiple directory option Runtime.INPUT_DIRECTORY for the file search path,
• a directory option Runtime.OUTPUT_DIRECTORY for the output directory,
• a word option Runtime.INPUT_ENCODING for the character encoding when reading files,
• a word option Runtime.OUTPUT_ENCODING for the character encoding when writing files,
• a boolean option optionDiagnostics for printing tool diagnostics,
• a boolean option optionPerformance for collecting performance statistics,
• a boolean option optionMeasureParser for measuring parser performance only.
• a boolean option optionMeasureProcessing for measuring processing performance only.
• a boolean option optionGC for performing GC,
• an integer option runsWarmUp with a default of 2 for the number of warm-up runs,
• and an integer option runsTotal with a default of 12 for the total number of runs.

prepare

public void prepare()

Prepare for processing. This method prepares for actually processing files, for example, by performing consistency checks between command line arguments and by initializing all default values not specified on the command line. The default implementation invokes Runtime.initDefaultValues(). It also checks that the optionSilent and optionVerbose flags are not both set at the same time.

See Also:

wrapUp()

diagnose

public void diagnose()

Print tool diagnostics. The default implementation of this method does nothing.

locate

public java.io.File locate(java.lang.String name)
                    throws java.io.IOException

Locate the file with the specified name. The default implementation simply looks in the current directory, ignoring any directories in the tool's search path.

Parameters:

name - The file name.

Returns:

The corresponding file.

Throws:

java.lang.IllegalArgumentException - Signals an inappropriate file (e.g., one that is too large).

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

See Also:

Runtime.locate(String)

parse

public abstract Node parse(java.io.Reader in,
                           java.io.File file)
                    throws java.io.IOException,
                           ParseException

Parse the specified file.

Parameters:

in - The input stream for the file.

file - The corresponding file.

Returns:

The AST corresponding to the file's contents, or null if no tree has been generated.

Throws:

java.lang.IllegalArgumentException - Signals an inappropriate file (e.g., one that is too large).

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

ParseException - Signals a parse error.

process

public void process(Node node)

Process the specified AST node. This method is only invoked if parse(Reader,File) has completed successfuly, has returned a node (and not null), and no errors have been reported through Runtime.error(), Runtime.error(String), or Runtime.error(String,Node) while parsing. The default implementation of this method does nothing.

Parameters:

node - The node.

process

public void process(java.lang.String name)
             throws java.io.IOException,
                    ParseException

Recursively process the file with the specified name. This method locates the specified file, opens it, parses it, closes it, and then processes the resulting AST node.

Parameters:

name - The file name.

Throws:

java.lang.IllegalArgumentException - Signals an inappropriate file (e.g., one that is too large).

java.io.FileNotFoundException - Signals that the file was not found.

java.io.IOException - Signals an I/O error while accessing the file.

ParseException - Signals a parse error.

VisitingException - Signals an error while visiting a node.

printHeader

public void printHeader(Printer printer)

Print a tool header to the specified printer. This method prints a header documenting the tool name, version, copyright, and current time. It also prints a warning not to edit the result.

Parameters:

printer - The printer.

wrapUp

public void wrapUp()

Wrap up this tool. This method is invoked after all files have been processed. The default implementation does nothing.

run

public void run(java.lang.String[] args)

Run this tool with the specified command line arguments. This method works as following:

1. It calls init() to initialize this tool.
2. It prints the name, version, and copyright to the console.
3. If this tool has been invoked without arguments, it prints a description of all command line options and, optionally, an explanation. It then exits.
4. It processes the specified command line arguments and prepares for processing the files. If any errors have been reported during the two method calls, it exits.
5. For each file name specified on the command line, it locates the file, parses the contents, and processes the resulting AST. If the -performance command line option has been specified, it repeatedly parses and processes each file, measuring both latency and heap utilization. It then exits.

Parameters:

args - The command line arguments.