ptolemy.data.expr
Class PtParser

java.lang.Object
  extended byptolemy.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 retuns 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 (or contact nsmyth@eecs)

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: PtParser.java,v 1.109 2004/04/13 15:50:05 cxh Exp $
Author:
Neil Smyth, Steve Neuendorffer
See Also:
ASTPtBitwiseNode, ASTPtFunctionApplicationNode, ASTPtFunctionDefinitionNode, ASTPtFunctionalIfNode, ASTPtLeafNode, ASTPtLogicalNode, ASTPtMethodCallNode, ASTPtProductNode, ASTPtRelationalNode, ASTPtRootNode, ASTPtSumNode, ASTPtUnaryNode, Token
Accepted Rating:
Yellow (yuhong)
Proposed Rating:
Yellow (nsmyth)

Field Summary
 Token jj_nt
           
protected  ptolemy.data.expr.JJTPtParserState jjtree
           
 boolean lookingAhead
           
 Token token
           
 PtParserTokenManager token_source
           
 
Fields inherited from interface ptolemy.data.expr.PtParserTreeConstants
jjtNodeName, JJTPTARRAYCONSTRUCTNODE, JJTPTASSIGNMENTNODE, JJTPTBITWISENODE, JJTPTFUNCTIONALIFNODE, JJTPTFUNCTIONAPPLICATIONNODE, JJTPTFUNCTIONDEFINITIONNODE, JJTPTLEAFNODE, JJTPTLOGICALNODE, JJTPTMATRIXCONSTRUCTNODE, JJTPTMETHODCALLNODE, JJTPTPOWERNODE, JJTPTPRODUCTNODE, JJTPTRECORDCONSTRUCTNODE, JJTPTRELATIONALNODE, JJTPTROOTNODE, JJTPTSHIFTNODE, JJTPTSUMNODE, JJTPTUNARYNODE, JJTVOID
 
Fields inherited from interface ptolemy.data.expr.PtParserConstants
AND, BITWISE_NOT, BOOL_NOT, BOOLEAN, CLOSEBRACE, CLOSEBRACKET, CLOSEPAREN, 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, 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
PtParser()
           
PtParser(java.io.InputStream stream)
           
PtParser(PtParserTokenManager tm)
           
PtParser(java.io.Reader stream)
           
 
Method Summary
 void arrayConstruct()
           
 void assignment()
           
 void assignmentIdentifier()
           
 void bitwiseAnd()
           
 void bitwiseOr()
           
 void bitwiseXor()
           
 void disable_tracing()
           
 void element()
           
 void 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()
           
 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()
           
static java.util.List getRegisteredClasses()
          Return the list of classes the parser searches when a function call is encountered.
 Token getToken(int index)
           
 java.util.LinkedList getUndefinedList(java.lang.String stringIn)
          Deprecated. Use a visitor with a ParseTreeFreeVariableCollector instead.
 void identifier()
           
 void logicalAnd()
           
 void logicalEquals()
           
 void logicalOr()
           
 void matrixConstruct()
           
 void optTypeSpecifier()
           
 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)
           
 void ReInit(PtParserTokenManager tm)
           
 void ReInit(java.io.Reader stream)
           
 void relational()
           
 void shift()
           
 ASTPtRootNode start()
           
 java.util.Map startAssignmentList()
           
 ASTPtRootNode startSimpleAssignment()
           
 ASTPtRootNode startString()
           
 void stringModeElement()
           
 void stringModeString()
           
 void sum()
           
 void term()
           
 void unary()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

jjtree

protected ptolemy.data.expr.JJTPtParserState jjtree

token_source

public PtParserTokenManager token_source

token

public Token token

jj_nt

public Token jj_nt

lookingAhead

public boolean lookingAhead
Constructor Detail

PtParser

public PtParser()

PtParser

public PtParser(java.io.InputStream stream)

PtParser

public PtParser(java.io.Reader stream)

PtParser

public PtParser(PtParserTokenManager tm)
Method Detail

getUndefinedList

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.

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

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

arrayConstruct

public final void arrayConstruct()
                          throws ParseException
Throws:
ParseException

ReInit

public void ReInit(java.io.InputStream stream)

ReInit

public void ReInit(java.io.Reader stream)

ReInit

public void ReInit(PtParserTokenManager tm)

getNextToken

public final Token getNextToken()

getToken

public final Token getToken(int index)

generateParseException

public ParseException generateParseException()

enable_tracing

public final void enable_tracing()

disable_tracing

public final void disable_tracing()