ptolemy.data.expr

Class PtParser

java.lang.Object

ptolemy.data.expr.PtParser

All Implemented Interfaces:

PtParserConstants, PtParserTreeConstants

public class PtParser
extends java.lang.Object
implements PtParserTreeConstants, PtParserConstants

This file implements an expression parser for Ptolemy II using the JavaCC parser generator. It can handle all the basic arithmetic operators (*, /, +, -, %, ^), relational operators (<, ≤, >, ≥, == !=), logical operators(&&, ||, !), bitwise operators (&, |, #, ~) and, using reflection, all of the functionality available in the java.lang.Math package.

By editing the ASTFunctionNode file it is also relatively easy to allow references to other functions. This provides an easy mechanism to extend the range to the parser e.g. have a tcl(...) function that passes the string to a Tcl interpreter and returns the result.

?

Functional if is supported via the following syntax:

?

        (boolean) ? (value1) : (value2)

Extensibility is also supported by allowing method calls on the Tokens, the syntax is

?

        (value1).method(comma separated arguments)

JavaCC by itself simply generates a file (and support files) that allow an input to be parsed, it does not return a parse tree. For the purposes of type checking we require a parse tree, and this is obtained using JJTree, a preprocessor for JavaCC.

?

JJtree operates by annotating the grammar file to support the generation of the parse tree. Thus the process is

?

X.jjt --> JJTREE --> X.jj --> JAVACC --> X.java + support files

The parser can also be passed a symbol table of ptolemy.data.expr.Variables which the expression to be parsed can reference.

Anything between quotes(") or apostrophes(') is taken to be one string. Strings are allowed to contain newlines or carriage returns. In addition, these characters, as well as other special characters, can be escaped using the standard Java syntax (\n, \t, \077, etc.).

The expressions recognized follow as close as possible the syntax of Java. In particular the operator precedences implemented here follow exactly those in Java. Any type conversions that are performed are lossless. If the user wants lossy conversions, explicit casts will be necessary.

Complex number are specified by an i or j after the imaginary part of the number. Long numbers are specified by an l or L after an integer number.

Users can register constants with the parser and also register classes where functions that may be called are defined. For a more thorough description of what the Parser is designed to do, please consult the Ptolemy II design document.

Note that the parsers created by JavaCC generally have quite a bit of internal state. On the other hand, the parse trees generated by this parser are much smaller. It is also fairly cheap to traverse a parse tree in order to evaluate it. Thus it is usually preferable to cache parse trees and create a new parser when the cached parse tree becomes invalid.

Since:

Ptolemy II 1.0

Version:

$Id$

Author:

Neil Smyth, Steve Neuendorffer

See Also:

ASTPtBitwiseNode, ASTPtFunctionApplicationNode, ASTPtFunctionDefinitionNode, ASTPtFunctionalIfNode, ASTPtLeafNode, ASTPtLogicalNode, ASTPtMethodCallNode, ASTPtProductNode, ASTPtRelationalNode, ASTPtRootNode, ASTPtSumNode, ASTPtUnaryNode, Token

Pt.AcceptedRating:

Yellow (yuhong)

Pt.ProposedRating:

Yellow (nsmyth)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) static class	PtParser.JJCalls

Field Summary

Fields

Modifier and Type	Field and Description
(package private) boolean	debug
(package private) SimpleCharStream	jj_input_stream
Token	jj_nt Next token.
protected JJTPtParserState	jjtree
Token	token Current token.
PtParserTokenManager	token_source Generated Token Manager.

Fields inherited from interface ptolemy.data.expr.PtParserTreeConstants

jjtNodeName, JJTPTARRAYCONSTRUCTNODE, JJTPTASSIGNMENTNODE, JJTPTBITWISENODE, JJTPTFUNCTIONALIFNODE, JJTPTFUNCTIONAPPLICATIONNODE, JJTPTFUNCTIONDEFINITIONNODE, JJTPTLEAFNODE, JJTPTLOGICALNODE, JJTPTMATRIXCONSTRUCTNODE, JJTPTMETHODCALLNODE, JJTPTORDEREDRECORDCONSTRUCTNODE, JJTPTPOWERNODE, JJTPTPRODUCTNODE, JJTPTRECORDCONSTRUCTNODE, JJTPTRELATIONALNODE, JJTPTROOTNODE, JJTPTSHIFTNODE, JJTPTSUMNODE, JJTPTUNARYNODE, JJTPTUNIONCONSTRUCTNODE, JJTVOID

Fields inherited from interface ptolemy.data.expr.PtParserConstants

AND, BITWISE_NOT, BOOL_NOT, BOOLEAN, CLOSEBRACE, CLOSEBRACKET, CLOSEPAREN, CLOSEUNION, COLON, COMMA, COMPLEX, COND_AND, COND_OR, DECIMAL_LITERAL, DEFAULT, DIVIDE, DOUBLE, EOF, EQUALS, ERROR, EXPONENT, FUNCTION, GT, GTE, HEX_LITERAL, ID, INTEGER, INTEGER_FORMAT_SPEC, LETTER, LSHR, LT, LTE, MINUS, MODULO, MULTI_LINE_COMMENT, MultiLineCommentMode, MULTIPLY, NOTEQUALS, OCTAL_LITERAL, OPENBRACE, OPENBRACKET, OPENPAREN, OPENUNION, OR, PERIOD, PLUS, POWER, QUESTION, SEPARATOR, SETEQUALS, SHL, SHR, SINGLE_LINE_COMMENT, SingleLineCommentMode, SMBRACE, SMDOLLAR, SMDOLLARBRACE, SMDOLLARPAREN, SMID, SMIDBRACE, SMIDPAREN, SMLETTER, SMPAREN, SMSTRING, STRING, StringMode, StringModeIDBrace, StringModeIDNone, StringModeIDParen, tokenImage, XOR

Constructor Summary

Constructors

Constructor and Description
PtParser()
PtParser(java.io.InputStream stream) Constructor with InputStream.
PtParser(java.io.InputStream stream, java.lang.String encoding) Constructor with InputStream and supplied encoding
PtParser(PtParserTokenManager tm) Constructor with generated Token Manager.
PtParser(java.io.Reader stream) Constructor.

Method Summary

Modifier and Type	Method and Description
void	arrayConstruct()
void	assignment()
void	assignmentIdentifier()
void	bitwiseAnd()
void	bitwiseOr()
void	bitwiseXor()
java.lang.String	cleanupString(java.lang.String str)
void	disable_tracing() Disable tracing.
void	element()
void	enable_tracing() Enable tracing.
void	expression()
void	funcIf()
void	function()
void	functionDefinition()
java.util.Map	generateAssignmentMap(java.lang.String stringIn) Generates a parse tree from the given String.
ParseException	generateParseException() Generate ParseException.
ASTPtRootNode	generateParseTree(java.lang.String stringIn) Generates a parse tree from the given String.
ASTPtRootNode	generateSimpleAssignmentParseTree(java.lang.String stringIn) Generates a parse tree from the given String, which may optionally contain an assignment.
ASTPtRootNode	generateStringParseTree(java.lang.String stringIn) Generates a parse tree from the given String, which is interpreted in "String Mode" instead of as an operator expression.
Token	getNextToken() Get the next Token.
static java.util.List	getRegisteredClasses() Return the list of classes the parser searches when a function call is encountered.
Token	getToken(int index) Get the specific Token.
java.util.LinkedList	getUndefinedList(java.lang.String stringIn) Deprecated. Use a visitor with a ParseTreeFreeVariableCollector instead.
void	identifier()
void	integer()
void	logicalAnd()
void	logicalEquals()
void	logicalOr()
void	matrixConstruct()
void	nilArrayConstruct()
void	optTypeSpecifier()
void	orderedRecordConstruct()
void	power()
void	primaryElement()
void	recordConstruct()
static void	registerConstant(java.lang.String name, java.lang.Object value) Add a constant to the list of constants that the parser recognizes.
static void	registerFunctionClass(java.lang.String newClassName) Add a class to the list of classes that the parser searches when a function call is encountered.
void	ReInit(java.io.InputStream stream) Reinitialise.
void	ReInit(java.io.InputStream stream, java.lang.String encoding) Reinitialise.
void	ReInit(PtParserTokenManager tm) Reinitialise.
void	ReInit(java.io.Reader stream) Reinitialise.
void	relational()
void	shift()
ASTPtRootNode	start()
java.util.Map	startAssignmentList()
ASTPtRootNode	startSimpleAssignment()
ASTPtRootNode	startString()
void	stringModeElement()
void	stringModeString()
void	sum()
void	term()
void	unary()
void	unionConstruct()

Methods inherited from class java.lang.Object

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

Field Detail

jjtree

protected JJTPtParserState jjtree

debug

boolean debug

token_source

public PtParserTokenManager token_source

Generated Token Manager.

jj_input_stream

SimpleCharStream jj_input_stream

token

public Token token

Current token.

jj_nt

public Token jj_nt

Next token.

Constructor Detail

PtParser

public PtParser()

PtParser

public PtParser(java.io.InputStream stream)

Constructor with InputStream.

PtParser

public PtParser(java.io.InputStream stream,
                java.lang.String encoding)

Constructor with InputStream and supplied encoding

PtParser

public PtParser(java.io.Reader stream)

Constructor.

PtParser

public PtParser(PtParserTokenManager tm)

Constructor with generated Token Manager.

Method Detail

getUndefinedList

@Deprecated
public java.util.LinkedList getUndefinedList(java.lang.String stringIn)
                                                  throws IllegalActionException

Deprecated. Use a visitor with a ParseTreeFreeVariableCollector instead.

Returns the list of undefined variables after parsing the given String.

Parameters:

stringIn - The expression to be parsed

Returns:

The list of undefined variables.

Throws:

IllegalActionException - If the parse fails.

generateParseTree

public ASTPtRootNode generateParseTree(java.lang.String stringIn)
                                throws IllegalActionException

Generates a parse tree from the given String. The root node is returned. To evaluate the parse tree, use a ParseTreeEvaluator.

Parameters:

stringIn - The expression to be parsed.

Returns:

The root node of the parse tree.

Throws:

IllegalActionException - If the parse fails.

generateSimpleAssignmentParseTree

public ASTPtRootNode generateSimpleAssignmentParseTree(java.lang.String stringIn)
                                                throws IllegalActionException

Generates a parse tree from the given String, which may optionally contain an assignment. The root node is returned. If the string represents an assignment, then the toplevel node will be an ASTPtAssignmentNode.

Parameters:

stringIn - The expression to be parsed.

Returns:

The root node of the parse tree.

Throws:

IllegalActionException - If the parse fails.

generateStringParseTree

public ASTPtRootNode generateStringParseTree(java.lang.String stringIn)
                                      throws IllegalActionException

Generates a parse tree from the given String, which is interpreted in "String Mode" instead of as an operator expression. In string mode, the expression is a literal string, except for identifiers which are denoted by $param. The root node is returned. To evaluate the parse tree, use a ParseTreeEvaluator.

Parameters:

stringIn - The expression to be parsed.

Returns:

The root node of the parse tree.

Throws:

IllegalActionException - If the parse fails.

generateAssignmentMap

public java.util.Map generateAssignmentMap(java.lang.String stringIn)
                                    throws IllegalActionException

Generates a parse tree from the given String. The string will be parsed according to rules for assignment lists. The returned node is a RootNode containing one assignment node for each assignment in the expression.

Parameters:

stringIn - The expression to be parsed.

Returns:

The root node of the parse tree.

Throws:

IllegalActionException - If the parse fails.

cleanupString

public java.lang.String cleanupString(java.lang.String str)
                               throws ParseException

Throws:

ParseException

getRegisteredClasses

public static java.util.List getRegisteredClasses()

Return the list of classes the parser searches when a function call is encountered. The classes are searched in the same order that they were registered with the parser, so the classes that are most likely to be searched should be registered first. This method is synchronized so that it can be called safely from multiple parsers.

Returns:

An unmodifiable list that can be iterated over.

registerConstant

public static void registerConstant(java.lang.String name,
                                    java.lang.Object value)
                             throws java.lang.IllegalArgumentException

Add a constant to the list of constants that the parser recognizes. It is a static method. The constants are stored in a hash table by the Constants class. The entry for each name is a ptolemy.data.Token of the appropriate type. The value for the constant can be given in a ptolemy.data.Token or in one of the data wrapper classes in java.lang.

Parameters:

name - The string name that the parser will recognize.

value - An Object constraining the value associated with the constant.

Throws:

java.lang.IllegalArgumentException - If the constant cannot be registered with the parser.

registerFunctionClass

public static void registerFunctionClass(java.lang.String newClassName)
                                  throws java.lang.IllegalArgumentException

Add a class to the list of classes that the parser searches when a function call is encountered. It is a static method. It stores the classes in a LinkedList. The classes are searched in the same order that they were registered with the parser, so the classes that are most likely to be searched should be registered first. This method is synchronized so that it can be called safely from multiple parsers.

Parameters:

newClassName - The fully qualified name of the Class to be added to the search path for functions.

Throws:

java.lang.IllegalArgumentException - If the Class named by the argument cannot not be found.

startSimpleAssignment

public final ASTPtRootNode startSimpleAssignment()
                                          throws ParseException

Throws:

ParseException

startAssignmentList

public final java.util.Map startAssignmentList()
                                        throws ParseException

Throws:

ParseException

assignment

public final void assignment()
                      throws ParseException

Throws:

ParseException

startString

public final ASTPtRootNode startString()
                                throws ParseException

Throws:

ParseException

stringModeElement

public final void stringModeElement()
                             throws ParseException

Throws:

ParseException

stringModeString

public final void stringModeString()
                            throws ParseException

Throws:

ParseException

start

public final ASTPtRootNode start()
                          throws ParseException

Throws:

ParseException

expression

public final void expression()
                      throws ParseException

Throws:

ParseException

funcIf

public final void funcIf()
                  throws ParseException

Throws:

ParseException

logicalOr

public final void logicalOr()
                     throws ParseException

Throws:

ParseException

logicalAnd

public final void logicalAnd()
                      throws ParseException

Throws:

ParseException

bitwiseOr

public final void bitwiseOr()
                     throws ParseException

Throws:

ParseException

bitwiseXor

public final void bitwiseXor()
                      throws ParseException

Throws:

ParseException

bitwiseAnd

public final void bitwiseAnd()
                      throws ParseException

Throws:

ParseException

logicalEquals

public final void logicalEquals()
                         throws ParseException

Throws:

ParseException

power

public final void power()
                 throws ParseException

Throws:

ParseException

relational

public final void relational()
                      throws ParseException

Throws:

ParseException

shift

public final void shift()
                 throws ParseException

Throws:

ParseException

sum

public final void sum()
               throws ParseException

Throws:

ParseException

term

public final void term()
                throws ParseException

Throws:

ParseException

unary

public final void unary()
                 throws ParseException

Throws:

ParseException

element

public final void element()
                   throws ParseException

Throws:

ParseException

integer

public final void integer()
                   throws ParseException

Throws:

ParseException

primaryElement

public final void primaryElement()
                          throws ParseException

Throws:

ParseException

functionDefinition

public final void functionDefinition()
                              throws ParseException

Throws:

ParseException

optTypeSpecifier

public final void optTypeSpecifier()
                            throws ParseException

Throws:

ParseException

function

public final void function()
                    throws ParseException

Throws:

ParseException

assignmentIdentifier

public final void assignmentIdentifier()
                                throws ParseException

Throws:

ParseException

identifier

public final void identifier()
                      throws ParseException

Throws:

ParseException

matrixConstruct

public final void matrixConstruct()
                           throws ParseException

Throws:

ParseException

recordConstruct

public final void recordConstruct()
                           throws ParseException

Throws:

ParseException

orderedRecordConstruct

public final void orderedRecordConstruct()
                                  throws ParseException

Throws:

ParseException

unionConstruct

public final void unionConstruct()
                          throws ParseException

Throws:

ParseException

arrayConstruct

public final void arrayConstruct()
                          throws ParseException

Throws:

ParseException

nilArrayConstruct

public final void nilArrayConstruct()
                             throws ParseException

Throws:

ParseException

ReInit

public void ReInit(java.io.InputStream stream)

Reinitialise.

ReInit

public void ReInit(java.io.InputStream stream,
                   java.lang.String encoding)

Reinitialise.

ReInit

public void ReInit(java.io.Reader stream)

Reinitialise.

ReInit

public void ReInit(PtParserTokenManager tm)

Reinitialise.

getNextToken

public final Token getNextToken()

Get the next Token.

getToken

public final Token getToken(int index)

Get the specific Token.

generateParseException

public ParseException generateParseException()

Generate ParseException.

enable_tracing

public final void enable_tracing()

Enable tracing.

disable_tracing

public final void disable_tracing()

Disable tracing.