NAME

PAST - Parrot abstract syntax tree

DESCRIPTION

This file implements the various abstract syntax tree nodes for compiling programs in Parrot.

PAST Node types

PAST::Node

PAST::Node is the base class for all PAST (and POST) nodes. It's derived from class Capture, so that it has both array and hash components. The array component is used to maintain a node's children, while the hash component contains the attributes of the node. In general we provide and use accessor methods for a node's attributes, instead of accessing the hash component directly.

Every PAST node predefines name, source, and pos attributes. The name attribute is the node's name, if any, while source and pos are used to identify the location in the original source code for the node. The source and pos values are generally set by the node method below.

Other node attributes are generally defined by subclasses of PAST::Node.

init([child1, child2, ..., ] [attr1=>val1, attr2=>val2, ... ]): Initialize a PAST node with the given children and attributes. Adds each child to the node (using the push method, below) and calls the appropriate accessor method for each attribute. And returns the node.
new([child1, child2, ..., ] [attr1=>val1, attr2=>val2, ...]): Create a new PAST node of initialized with the given children and attributes. Returns the newly created node.
unshift(child): Add child to the beginning of the invocant's list of children.
push(child): Add child to the end of the invocant's list of children.
push_new(class, [child1, child2, ..., ] [attr1=>val1, attr2=>val2, ...]): Creates a new PAST node of type class, initializes it with the given children and attributes, and adds it to the end of the invocant's array of children. Returns the newly created PAST node.
iterator( ): Returns a newly initialized iterator for the invocant's list of children.
node([val]): Sets the invocant's source and pos attributes to those of val. If val is another PAST node, then source and pos are simply copied from that node, otherwise val is assumed to be a Match object and obtains source/position information from that.
name([value]): Accessor method -- sets/returns the name attribute of the invocant.
returns([value]): Accessor method -- sets/returns the return type for the invocant.
named([value]): Accessor method -- for named arguments, sets/returns the name to be associated with the argument.
flat([value]: Accessor method -- sets/returns the "flatten" flag on arguments.
attr(STR attrname, PMC value, INT has_value): Helper method for accessors. If has_value is true then set the invocant's value of attrname to value. Returns the (resulting) value of attrname in the invocant.
unique([STR fmt]): Generate a unique number that can be used as an identifier. If fmt is provided, then it will be used as a prefix to the unique number.
escape(STR name): Returns name in a format that can be compiled by PIR.
compile(code [, adverbs :slurpy :named]): (Deprecated.) Compile the given PAST tree according to adverbs.

PAST::Val

PAST::Val nodes represent constant values in the abstract syntax tree. The name attribute represents the value of the node.

value([value]): Get/set the constant value for this node.

PAST::Var

PAST::Var nodes represent variables within the abstract syntax tree. The variable name (if any) is given as the node's name attribute.

scope([value]): Get/set the PAST::Var node's "scope" (i.e., how the variable is accessed or set). Allowable values include "package", "lexical", "parameter", and "keyed", representing HLL global, lexical, block parameter, and array/hash variables respectively.
isdecl([flag]): Get/set the node's isdecl attribute (for lexical variables) to flag. A true value of isdecl indicates that the variable given by this node is to be created within the current lexical scope. Otherwise, the node refers to a lexical variable from an outer scope.
isslurpy([flag]): Get/set the node's isslurpy attribute (for parameter variables) to flag. A true value of isslurpy indicates that the parameter variable given by this node is to be created as a slurpy parameter (consuming all remaining arguments passed in).
viviself([type]): If the variable needs to be instantiated, then type indicates either the type of the value to create for the node or (future implementation) a PAST tree to create the value.
islvalue([flag]): Get/set the islvalue attribute, which indicates whether this variable is being used in an lvalue context.
bindvalue([value]): Private PAST attribute that indicates the value to be bound to this variable at runtime (e.g., for binding or assignment).

PAST::Op

PAST::Op nodes represent the operations in an abstract syntax tree. The primary function of the node is given by its pasttype, secondary functions may be given by the node's name, pirop, or other attributes.

pasttype([type]): A PAST::Op node's pasttype determines the type of operation to be performed. Predefined values of pasttype are:; assign - Copy the value of the node's second child into the variable expression given by its first child.; bind - Bind the variable given by the node's first child to the value given by its second child.; if - Evaluate the first child; if the first child is true then evaluate the second child (if any) otherwise evaluate the third child (if any). If either the second or third child are missing, then they evaluate as the result of the first child.; unless - Same as 'if' above, but reverse the evaluation of the second and third children nodes.; while - Evaluate the first child, if the result is true then evaluate the second child and repeat.; until - Evaluate the first child, if the result is false then evaluate the second child and repeat.; for - Iterate over the first child. For each element, invoke the sub in the second child, passing the element as the only parameter.; call - Call a subroutine, passing the results of any child nodes as arguments. The subroutine to be called is given by the node's name attribute, if the node has no name attribute then the first child is assumed to evaluate to a callable sub.; pirop - Execute the named PIR opcode, passing the results of any children nodes as arguments.; inline - Execute the sequence of PIR statements given by the node's inline attribute (a string). See the inline method below for details.; callmethod - Invokes a method on an object, using children nodes as arguments. If the node has a name attribute, then the first child is the invocant and any remaining children are arguments. If the node doesn't have a name attribute, then the first child evaluates to the method to be called, the second child is the invocant, and the remaining children are arguments to the method call.; try - (preliminary) Execute the code given by the first child, and if any exceptions occur then handle them using the code given by the second child.; If a node doesn't have a value set for pasttype, then it assumes "pirop" if its pirop attribute is set, otherwise it assumes "call".
pirop([opcode]): Get/set the PIR opcode to be executed for this node. The PAST implementation knows about the argument types for many of the PIR opcodes, and will try to automatically convert the results of any children nodes into the correct types if needed. (In general, the implementation tries to convert things to PMCs whenever it isn't certain what else to do.) The table of PIR opcodes that PAST "knows" about is in POST.pir.
islvalue([flag]): Get/set whether this node is an lvalue, or treats its first child as an lvalue (e.g., for assignment).
inline([STRING code]): Get/set the code to be used for inline PIR when pasttype is "inline". The code argument is PIR text to be inserted in the final generated code sequence. Sequences of "%0", "%1", "%2", ... "%9" in code are replaced with the evaluated results of the first, second, third, ..., tenth children nodes. (If you need more than ten arguments to your inline PIR, consider making it a subroutine call instead.); The register to hold the result of the inline PIR operation is given by "%r", "%t", or "%u" in the code string:

PAST::Stmts

PAST::Stmts is a container of PAST::Node without any specific methods.

PAST::Block

PAST::Block nodes represent lexical scopes within an abstract syntax tree, and roughly translate to individual Parrot subroutines. A PAST::Block node nested within another PAST::Block node acts like a nested lexical scope.

If the block has a name attribute, that becomes the name of the resulting Parrot sub, otherwise a unique name is automatically generated for the block.

blocktype([STRING type]): Get/set the type of the block. The currently understood values are 'declaration' and 'immediate'. 'Declaration' indicates that a block is simply being defined at this point, while 'immediate' indicates a block that is to be immediately executed when it is evaluated in the AST (e.g., the immediate blocks in Perl6 if, while, and other similar statements).
symbol(name, [attr1 => val, attr2 => val2, ...]): If called with named arguments, sets the symbol hash corresponding to name in the current block. The HLL is free to select any symbol attributes desired, although the 'scope' attribute is typically used to assist with lexical scoping of PAST::Var nodes.; If no named arguments are given, returns the current attribute hash for symbol name.
symtable([value]): Get/set the symbol table for the block. May be deprecated in favor of the symbol method above.
compiler([name]): Indicate that the children nodes of this block are to be compiled using compiler name instead of the standard PAST compiler.
pragma([pragma]): Get/set any pragmas (PIR) for this block.

AUTHOR

Patrick Michaud <pmichaud@pobox.com> is the author and maintainer. Please send patches and suggestions to the Parrot porters or Perl 6 compilers mailing lists.

HISTORY

2006-11-20 Patrick Michaud added first draft of POD documentation.