net.sourceforge.nrl.parser
Interface INRLParser

All Known Implementing Classes:

NRLParser

public interface INRLParser

An INRLParser is a parser that can return a fully-resolved NRL abstract syntax tree.

The way this is normally used is as follows:

1. Call parse(InputStream) to read in an AST
2. If an exception is thrown, process it - the result will be null
3. Call getErrors(), which may return a mixture of syntax and semantic errors if any occurred. If so, the AST is unsafe and the errors need to be displayed to a user (or some other processing).
4. Call resolveModelReferences(IRuleFile, IModelCollection) to resolve model references in the AST. Without this, no model information can be accessed through the AST.
5. Call getErrors() again to check if any errors occurred during model processing. If so, the AST is unsafe and needs to be discarded.

The reason why parsing and resolving, and on the other hand resolving against a model are kept separate is that the basic AST can be validated even before a model is available, for example in an editor. For any sort of processing, a full resolution against the model should be performed.

Method Summary

List<NRLError>	getErrors() Returns a collection of SyntaxError and SemanticError objects.
IRuleFile	parse(InputStream stream) Parse an input stream and construct an AST.
IRuleFile	parse(Reader reader) Alternative method for readers instead of streams
void	resolveModelReferences(IRuleFile ruleFile, IModelCollection models) Resolve model reference in the AST by looking up model elements.
void	resolveOperatorReferences(IRuleFile ruleFile, IOperators[] operators) Resolve operator references in the AST by looking up operator definitions in a collection of operators.

Method Detail

parse

IRuleFile parse(InputStream stream)
                throws Exception

Parse an input stream and construct an AST. After a call to this method, clients must:

• Handle any exception and about processing
• If no exception occurred, call getErrors() to get a list of parsing errors

If no check on errors is made after parsing, the AST is unstable and will cause null pointer and other exceptions.

Parameters:

stream - the stream to read from

Returns:

the rule file, which may contain errors

Throws:

Exception - if a severe error occurred. The result is that even getErrors() will not return a meaningful result.

parse

IRuleFile parse(Reader reader)
                throws Exception

Alternative method for readers instead of streams

Parameters:

reader - the reader to use for parsing

Returns:

the AST

Throws:

Exception

resolveModelReferences

void resolveModelReferences(IRuleFile ruleFile,
                            IModelCollection models)

Resolve model reference in the AST by looking up model elements. This can be called after parse(InputStream), if no errors occurred.

After a call to this method, getErrors() may contain a number of semantic errors where model references could not be looked up.

Parameters:

ruleFile - the rule file to resolve

models - the models to look at

resolveOperatorReferences

void resolveOperatorReferences(IRuleFile ruleFile,
                               IOperators[] operators)

Resolve operator references in the AST by looking up operator definitions in a collection of operators. This can only be called after parse(InputStream), and after resolveModelReferences(IRuleFile, IModelCollection), if no errors occurred.

This call is kept separate to enable callers to check operator references separately - because missing definitions may or may not be treated as errors depending on the state of the rule file.

After a call to this, getErrors() will contain semantic error objects if any operators could not be resolved properly.

Parameters:

ruleFile - the file to resolve

operators - the collection of operator files

getErrors

List<NRLError> getErrors()

Returns a collection of SyntaxError and SemanticError objects. This is intended for use after parse(InputStream), and returns a different result after every call to parse.

Returns:

the collection of errors, empty if no errors occurred