The {@code AstNode} hierarchy sits atop the older {@link Node} class,which was designed for code generation. The {@code Node} class is aflexible, weakly-typed class suitable for creating and rewriting code trees, but using it requires you to remember the exact ordering of the child nodes, which are kept in a linked list. The {@code AstNode}hierarchy is a strongly-typed facade with named accessors for children and common properties, but under the hood it's still using a linked list of child nodes. It isn't a very good idea to use the child list directly unless you know exactly what you're doing.
Note that {@code AstNode} records additional information, includingthe node's position, length, and parent node. Also, some {@code AstNode}subclasses record some of their child nodes in instance members, since they are not needed for code generation. In a nutshell, only the code generator should be mixing and matching {@code AstNode} and {@code Node}objects.All offset fields in all subclasses of AstNode are relative to their parent. For things like paren, bracket and keyword positions, the position is relative to the current node. The node start position is relative to the parent node.
During the actual parsing, node positions are absolute; adding the node to its parent fixes up the offsets to be relative. By the time you see the AST (e.g. using the {@code Visitor} interface), the offsets are relative.
{@code AstNode} objects have property lists accessible via the{@link #getProp} and {@link #putProp} methods. The property lists areinteger-keyed with arbitrary {@code Object} values. For the most part theparser generating the AST avoids using properties, preferring fields for elements that are always set. Property lists are intended for user-defined annotations to the tree. The Rhino code generator acts as a client and uses node properties extensively. You are welcome to use the property-list API for anything your client needs.
This hierarchy does not have separate branches for expressions and statements, as the distinction in JavaScript is not as clear-cut as in Java or C++.
An AST node represents a Java source code construct, such as a name, type, expression, statement, or declaration.
Each AST node belongs to a unique AST instance, called the owning AST. The children of an AST node always have the same owner as their parent node. If a node from one AST is to be added to a different AST, the subtree must be cloned first to ensure that the added nodes have the correct owning AST.
When an AST node is part of an AST, it has a unique parent node. Clients can navigate upwards, from child to parent, as well as downwards, from parent to child. Newly created nodes are unparented. When an unparented node is set as a child of a node (using a setCHILD method), its parent link is set automatically and the parent link of the former child is set to null. For nodes with properties that include a list of children (for example, Block whose statements property is a list of statements), adding or removing an element to/for the list property automatically updates the parent links. These lists support the List.set method; however, the constraint that the same node cannot appear more than once means that this method cannot be used to swap elements without first removing the node.
ASTs must not contain cycles. All operations that could create a cycle detect this possibility and fail.
ASTs do not contain "holes" (missing subtrees). If a node is required to have a certain property, a syntactically plausible initial value is always supplied.
The hierarchy of AST node types has some convenient groupings marked by abstract superclasses:
ExpressionName (a sub-kind of expression)StatementTypeBodyDeclaration Abstract syntax trees may be hand constructed by clients, using the newTYPE factory methods (see AST) to create new nodes, and the various setCHILD methods to connect them together.
The class {@link ASTParser} parses a stringcontaining a Java source code and returns an abstract syntax tree for it. The resulting nodes carry source ranges relating the node back to the original source characters. The source range covers the construct as a whole.
Each AST node carries bit flags, which may convey additional information about the node. For instance, the parser uses a flag to indicate a syntax error. Newly created nodes have no flags set.
Each AST node is capable of carrying an open-ended collection of client-defined properties. Newly created nodes have none. getProperty and setProperty are used to access these properties.
AST nodes are thread-safe for readers provided there are no active writers. If one thread is modifying an AST, including creating new nodes or cloning existing ones, it is not safe for another thread to read, visit, write, create, or clone any of the nodes on the same AST. When synchronization is required, consider using the common AST object that owns the node; that is, use synchronize (node.getAST()) {...}.
ASTs also support the visitor pattern; see the class ASTVisitor for details.
Compilation units created by ASTParser from a source document can be serialized after arbitrary modifications with minimal loss of original formatting. See {@link CompilationUnit#recordModifications()} for details.See also {@link org.aspectj.org.eclipse.jdt.core.dom.rewrite.ASTRewrite} foran alternative way to describe and serialize changes to a read-only AST.
An AST node represents a Java source code construct, such as a name, type, expression, statement, or declaration.
Each AST node belongs to a unique AST instance, called the owning AST. The children of an AST node always have the same owner as their parent node. If a node from one AST is to be added to a different AST, the subtree must be cloned first to ensure that the added nodes have the correct owning AST.
When an AST node is part of an AST, it has a unique parent node. Clients can navigate upwards, from child to parent, as well as downwards, from parent to child. Newly created nodes are unparented. When an unparented node is set as a child of a node (using a setCHILD method), its parent link is set automatically and the parent link of the former child is set to null. For nodes with properties that include a list of children (for example, Block whose statements property is a list of statements), adding or removing an element to/for the list property automatically updates the parent links. These lists support the List.set method; however, the constraint that the same node cannot appear more than once means that this method cannot be used to swap elements without first removing the node.
ASTs must not contain cycles. All operations that could create a cycle detect this possibility and fail.
ASTs do not contain "holes" (missing subtrees). If a node is required to have a certain property, a syntactically plausible initial value is always supplied.
The hierarchy of AST node types has some convenient groupings marked by abstract superclasses:
ExpressionName (a sub-kind of expression)StatementTypeBodyDeclaration Abstract syntax trees may be hand constructed by clients, using the newTYPE factory methods (see AST) to create new nodes, and the various setCHILD methods to connect them together.
The class {@link ASTParser} parses a stringcontaining a Java source code and returns an abstract syntax tree for it. The resulting nodes carry source ranges relating the node back to the original source characters. The source range covers the construct as a whole.
Each AST node carries bit flags, which may convey additional information about the node. For instance, the parser uses a flag to indicate a syntax error. Newly created nodes have no flags set.
Each AST node is capable of carrying an open-ended collection of client-defined properties. Newly created nodes have none. getProperty and setProperty are used to access these properties.
AST nodes are thread-safe for readers provided there are no active writers. If one thread is modifying an AST, including creating new nodes or cloning existing ones, it is not safe for another thread to read, visit, write, create, or clone any of the nodes on the same AST. When synchronization is required, consider using the common AST object that owns the node; that is, use synchronize (node.getAST()) {...}.
ASTs also support the visitor pattern; see the class ASTVisitor for details. The NodeFinder class can be used to find a specific node inside a tree.
Compilation units created by ASTParser from a source document can be serialized after arbitrary modifications with minimal loss of original formatting. See {@link CompilationUnit#recordModifications()} for details.See also {@link org.eclipse.jdt.core.dom.rewrite.ASTRewrite} foran alternative way to describe and serialize changes to a read-only AST.
An AST node represents a PHP source code construct, such as a name, type, expression, statement, or declaration.
ASTs do not contain cycles.
@see Visitable @author Modhe S., Roy G. ,2007
The {@code AstNode} hierarchy sits atop the older {@link Node} class,which was designed for code generation. The {@code Node} class is aflexible, weakly-typed class suitable for creating and rewriting code trees, but using it requires you to remember the exact ordering of the child nodes, which are kept in a linked list. The {@code AstNode}hierarchy is a strongly-typed facade with named accessors for children and common properties, but under the hood it's still using a linked list of child nodes. It isn't a very good idea to use the child list directly unless you know exactly what you're doing.
Note that {@code AstNode} records additional information, includingthe node's position, length, and parent node. Also, some {@code AstNode}subclasses record some of their child nodes in instance members, since they are not needed for code generation. In a nutshell, only the code generator should be mixing and matching {@code AstNode} and {@code Node}objects.All offset fields in all subclasses of AstNode are relative to their parent. For things like paren, bracket and keyword positions, the position is relative to the current node. The node start position is relative to the parent node.
During the actual parsing, node positions are absolute; adding the node to its parent fixes up the offsets to be relative. By the time you see the AST (e.g. using the {@code Visitor} interface), the offsets are relative.
{@code AstNode} objects have property lists accessible via the{@link #getProp} and {@link #putProp} methods. The property lists areinteger-keyed with arbitrary {@code Object} values. For the most part theparser generating the AST avoids using properties, preferring fields for elements that are always set. Property lists are intended for user-defined annotations to the tree. The Rhino code generator acts as a client and uses node properties extensively. You are welcome to use the property-list API for anything your client needs.
This hierarchy does not have separate branches for expressions and statements, as the distinction in JavaScript is not as clear-cut as in Java or C++.
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |