Package ptolemy.data.expr

Class 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)

    • 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.

    • 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.

      • 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.

      • 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.

      • 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.