OpenVDB  12.0.0
Namespaces | Classes | Functions
openvdb::v12_0::ax::ast Namespace Reference

Namespaces

 tokens
 

Classes

struct  ArrayPack
 ArrayPacks represent temporary container creations of arbitrary sizes, typically generated through the use of curly braces {}. More...
 
struct  ArrayUnpack
 ArrayUnpack represent indexing operations into AX container types, primarily vectors and matrices indexed by the square brackets [] syntax. Multiple levels of indirection (multiple components) can be specified but current construction is limited to either a single or double component lookup. Providing two components infers a matrix indexing operation. More...
 
struct  AssignExpression
 AssignExpressions represents a similar object construction to a BinaryOperator. AssignExpressions can be chained together and are thus derived as Expressions rather than Statements. More...
 
struct  Attribute
 Attributes represent any access to a primitive value, typically associated with the '@' symbol syntax. Note that the AST does not store any additional information on the given attribute other than its name and type, which together form a unique Attribute identifier known as the Attribute 'token'. A 'primitive value' in this instance refers to a value on an OpenVDB Volume or OpenVDB Points tree. More...
 
struct  BinaryOperator
 A BinaryOperator represents a single binary operation between a left hand side (LHS) and right hand side (RHS) expression. The operation type is stored as a tokens::OperatorToken enumerated type on the node. AX grammar guarantees that this token will only ever be a valid binary operator token type when initialized by the parser. More...
 
struct  Block
 A Block node represents a scoped list of statements. It may comprise of 0 or more statements, and specifically indicates that a new scope is activated, typically represented by curly braces. Note that a block does not alway have to be encapsulated by curly braces, but always represents a new scope. More...
 
struct  Cast
 Cast nodes represent the conversion of an underlying expression to a target type. Cast nodes are typically constructed from functional notation and do not represent construction of the target type, rather a type-casted conversion. More...
 
struct  CommaOperator
 
struct  ConditionalStatement
 ConditionalStatements represents all combinations of 'if', 'else' and 'else if' syntax and semantics. A single ConditionalStatement only ever represents up to two branches; an 'if' (true) and an optional 'else' (false). ConditionalStatements are nested within the second 'else' branch to support 'else if' logic. As well as both 'if' and 'else' branches, a ConditionalStatement also holds an Expression related to its primary condition. More...
 
struct  Crement
 A Crement node represents a single increment '++' and decrement '–' operation. As well as it's crement type, it also stores whether the semantics constructed a post or pre-crement i.e. ++a or a++. More...
 
struct  DeclareLocal
 DeclareLocal AST nodes symbolize a single type declaration of a local variable. These store the local variables that They also however store its specified type. These have the important distinction of representing the initial creation and allocation of a variable, in comparison to a Local node which only represents access. More...
 
struct  Expression
 Expressions are comprised of full or potentially partial parts of a full statement that may not necessary make up an entire valid statement on their own. For example, while a Binary Operator such as "3 + 5;"" is a valid statement on its own, the full statement "3 + 5 + 6;" must be broken down into two expressions which together form the statement as well as determining precedence. More...
 
struct  ExternalVariable
 ExternalVariable represent any access to external (custom) data, typically associated with the '$' symbol syntax. Note that the AST does not store any additional information on the given external other than its name and type, which together form a unique external identifier known as the ExternalVariable 'token'. This token is used by the compiler to map user provided values to these external values. More...
 
struct  FunctionCall
 FunctionCalls represent a single call to a function and any provided arguments. The argument list can be empty. The function name is expected to exist in the AX function registry. More...
 
struct  Keyword
 Keywords represent keyword statements defining changes in execution. These include those that define changes in loop execution such as break and continue, as well as return statements. More...
 
struct  Local
 Local AST nodes represent a single accesses to a local variable. The only store the name of the variable being accessed. More...
 
struct  Loop
 Loops represent for, while and do-while loop constructs. These all consist of a condition - evaluated to determine if loop iteration should continue, and a body which is the logic to be repeated. For loops also have initial statements which are evaluated prior to loop execution (at loop scope) and commonly used to set up iterators, and iteration expressions which are evaluated between iterations after the body and before the condition. Both conditions and initial statements can be declarations or expressions, so are Statements, and iteration expressions can consist of multiple expressions. The loop body is a Block defining its own scope (encapsulated by initial statement scope for for-loops). More...
 
struct  Node
 The base abstract node which determines the interface and required methods for all derived concrete nodes which comprise a valid AST. More...
 
struct  Statement
 Abstract (pure-virtual) AST nodes. More...
 
struct  StatementList
 Concrete AST nodes. More...
 
struct  TernaryOperator
 A TernaryOperator represents a ternary (conditional) expression 'a ? b : c' which evaluates to 'b' if 'a' is true and 'c' if 'a' is false. Requires 'b' and 'c' to be convertibly typed expressions, or both void. The 'true' expression ('b') is optional with the conditional expression 'a' returned if it evaluates to true, otherwise returning 'c'. Note that 'a' will only be evaluated once in this case. More...
 
struct  Tree
 A Tree is the highest concrete (non-abstract) node in the entire AX AST hierarchy. It represents an entire conversion of a valid AX string. More...
 
struct  UnaryOperator
 A UnaryOperator represents a single unary operation on an expression. The operation type is stored as a tokens::OperatorToken enumerated type on the node. AX grammar guarantees that this token will only every be a valid unary operator token type when initialized by the parser. More...
 
struct  Value
 A Value (literal) AST node holds either literal text or absolute value information on all numerical, string and boolean constants. A single instance of a Value is templated on the requested scalar, boolean or string type. If scalar or boolean value is constructed from a string (as typically is the case in the parser), the value is automatically converted to its numerical representation. If this fails, the original text is stored instead. More...
 
struct  Value< std::string >
 Specialization of Values for strings. More...
 
struct  ValueBase
 ValueBases are a base class for anything that holds a value (literal). Derived classes store the actual typed values. More...
 
struct  Variable
 Variables are a base type for Locals, Attributes and ExternalVariables. Unlike other abstract types, they also consolidate data for the derived types. More...
 
struct  VisitNodeType
 
struct  Visitor
 The Visitor class uses the Curiously Recursive Template Pattern (CRTP) to provide a customizable interface intended to be used by clients wishing to perform custom operations over an AX Abstract Syntax Tree (AST). By default the Visitor implements simple traversal of all nodes, ensuring that each node on a well formed AST is visited at least once. By deriving from the Visitor, users are able to customize this default behavior and further manually override specific node behavior to their needs. The function options at the top of visitor can be overridden using CRTP to control the prior default behavior, with the ability to override the traverse() and visit() methods for the latter more granular control. More...
 

Functions

OPENVDB_AX_API openvdb::ax::ast::Tree::ConstPtr parse (const char *code, ax::Logger &logger)
 Construct an abstract syntax tree from a code snippet. More...
 
OPENVDB_AX_API openvdb::ax::ast::Tree::Ptr parse (const char *code)
 Construct an abstract syntax tree from a code snippet. More...
 
OPENVDB_AX_API void print (const ast::Node &node, const bool numberStatements=true, std::ostream &os=std::cout, const char *indent=" ")
 Writes a descriptive printout of a Node hierarchy into a target stream. More...
 
OPENVDB_AX_API void reprint (const ast::Node &node, std::ostream &os=std::cout, const char *indent=" ")
 Using the provided AST, print corresponding AX code which may have been used to create it. More...
 
OPENVDB_AX_API bool usesAttribute (const ast::Node &node, const std::string &name, const tokens::CoreType type=tokens::UNKNOWN)
 Returns whether or not a given branch of an AST reads from or writes to a given attribute. More...
 
OPENVDB_AX_API bool writesToAttribute (const ast::Node &node, const std::string &name, const tokens::CoreType type=tokens::UNKNOWN)
 Returns whether or not a given branch of an AST writes to a given attribute. More...
 
OPENVDB_AX_API bool callsFunction (const ast::Node &node, const std::string &name)
 Returns whether or not a given branch of an AST calls a function. More...
 
OPENVDB_AX_API void catalogueVariables (const ast::Node &node, std::vector< const ast::Variable * > *readOnly, std::vector< const ast::Variable * > *writeOnly, std::vector< const ast::Variable * > *readWrite, const bool locals=true, const bool attributes=true)
 todo More...
 
OPENVDB_AX_API void catalogueAttributeTokens (const ast::Node &node, std::vector< std::string > *readOnly, std::vector< std::string > *writeOnly, std::vector< std::string > *readWrite)
 Parse all attributes into three unique vectors which represent how they are accessed within the syntax tree. Read only attributes are stored within the 'readOnly' container (for example. More...
 
OPENVDB_AX_API void attributeDependencyTokens (const ast::Tree &tree, const std::string &name, const tokens::CoreType type, std::vector< std::string > &dependencies)
 Populate a list of attribute names which the given attribute depends on. More...
 
template<typename NodeT , typename OpT >
void visitNodeType (const ast::Node &node, const OpT &op)
 For an AST node of a given type, search for and call a custom const operator() which takes a const reference to every occurrence of the specified node type. More...
 
template<typename NodeT , typename ContainerType = std::vector<const NodeT*>>
void collectNodeType (const ast::Node &node, ContainerType &array)
 Visit all nodes of a given type and store pointers to them in a provided compatible container. More...
 
template<typename NodeTypeList , typename ContainerType = std::vector<const Node*>>
void collectNodeTypes (const ast::Node &node, ContainerType &array)
 Visit all nodes of the given types and store pointers to them in a container of base ast::Node pointers. More...
 
OPENVDB_AX_API void linearize (const ast::Node &node, std::vector< const ast::Node * > &list)
 Flatten the provided AST branch into a linear list using post order traversal. More...
 
OPENVDB_AX_API const ast::VariablefirstUse (const ast::Node &node, const std::string &token)
 
OPENVDB_AX_API const ast::VariablelastUse (const ast::Node &node, const std::string &token)
 

Function Documentation

OPENVDB_AX_API void openvdb::v12_0::ax::ast::attributeDependencyTokens ( const ast::Tree tree,
const std::string &  name,
const tokens::CoreType  type,
std::vector< std::string > &  dependencies 
)

Populate a list of attribute names which the given attribute depends on.

OPENVDB_AX_API bool openvdb::v12_0::ax::ast::callsFunction ( const ast::Node node,
const std::string &  name 
)

Returns whether or not a given branch of an AST calls a function.

Parameters
nodeThe AST to analyze
namethe name of the function to search for
OPENVDB_AX_API void openvdb::v12_0::ax::ast::catalogueAttributeTokens ( const ast::Node node,
std::vector< std::string > *  readOnly,
std::vector< std::string > *  writeOnly,
std::vector< std::string > *  readWrite 
)

Parse all attributes into three unique vectors which represent how they are accessed within the syntax tree. Read only attributes are stored within the 'readOnly' container (for example.

int a=@a;

), write only attributes in the 'writeOnly' container

@a=1;

and readWrite attributes in the 'readWrite' container

@a+=1;
Note
Note that the code generator is able to do this far more efficiently, however this provides simple front-end support for detecting these types of operations
Parameters
nodeThe AST to analyze
readOnlyThe unique list of attributes which are only read from
writeOnlyThe unique list of attributes which are only written too
readWriteThe unique list of attributes which both read from and written too
OPENVDB_AX_API void openvdb::v12_0::ax::ast::catalogueVariables ( const ast::Node node,
std::vector< const ast::Variable * > *  readOnly,
std::vector< const ast::Variable * > *  writeOnly,
std::vector< const ast::Variable * > *  readWrite,
const bool  locals = true,
const bool  attributes = true 
)

todo

void collectNodeType ( const ast::Node node,
ContainerType &  array 
)
inline

Visit all nodes of a given type and store pointers to them in a provided compatible container.

void collectNodeTypes ( const ast::Node node,
ContainerType &  array 
)
inline

Visit all nodes of the given types and store pointers to them in a container of base ast::Node pointers.

Note
NodeTypeList is expected to be a an openvdb::TypeList object with a list of node types. For example, to collect all Attribute and External Variable ast Nodes:

using ListT = openvdb::TypeList<ast::Attribute, ast::ExternalVariable>; std::vector<const ast::Node*> nodes; ast::collectNodeTypes<ListT>(tree, nodes);

OPENVDB_AX_API const ast::Variable* openvdb::v12_0::ax::ast::firstUse ( const ast::Node node,
const std::string &  token 
)
OPENVDB_AX_API const ast::Variable* openvdb::v12_0::ax::ast::lastUse ( const ast::Node node,
const std::string &  token 
)
OPENVDB_AX_API void openvdb::v12_0::ax::ast::linearize ( const ast::Node node,
std::vector< const ast::Node * > &  list 
)

Flatten the provided AST branch into a linear list using post order traversal.

OPENVDB_AX_API openvdb::ax::ast::Tree::ConstPtr openvdb::v12_0::ax::ast::parse ( const char *  code,
ax::Logger logger 
)

Construct an abstract syntax tree from a code snippet.

This method parses the provided null terminated code snippet and attempts to construct a complete abstract syntax tree (AST) which can be passed to the AX Compiler. If the code is not well formed (as defined by the AX grammar) a nullptr is returned and instances of any errors encoutered are stored to the provided logger.

Note
The returned AST is const as the logger uses this to determine line and column numbers of errors/warnings in later stages. If you need to modify the tree, take a copy.
Returns
A shared pointer to a valid const AST. Can be a nullptr on error.
Parameters
codeThe code to parse
loggerThe logger to collect syntax errors
OPENVDB_AX_API openvdb::ax::ast::Tree::Ptr openvdb::v12_0::ax::ast::parse ( const char *  code)

Construct an abstract syntax tree from a code snippet.

A runtime exception will be thrown with the first syntax error.

Returns
A shared pointer to a valid AST.
Parameters
codeThe code to parse
OPENVDB_AX_API void openvdb::v12_0::ax::ast::print ( const ast::Node node,
const bool  numberStatements = true,
std::ostream &  os = std::cout,
const char *  indent = "    " 
)

Writes a descriptive printout of a Node hierarchy into a target stream.

Parameters
nodeNode to print
numberStatementsWhether to number the line statements
osStream to write into
indentThe indent to print on each child traversal
OPENVDB_AX_API void openvdb::v12_0::ax::ast::reprint ( const ast::Node node,
std::ostream &  os = std::cout,
const char *  indent = "    " 
)

Using the provided AST, print corresponding AX code which may have been used to create it.

Note
The result is not guaranteed to be exactly equal to the code that was original parsed. A few potential key differences worth mentioning include whitespace matching, component indexing and inferred attribute types.
Parameters
nodeNode to print
osStream to write into
indentThe indent to print on each child traversal
OPENVDB_AX_API bool openvdb::v12_0::ax::ast::usesAttribute ( const ast::Node node,
const std::string &  name,
const tokens::CoreType  type = tokens::UNKNOWN 
)

Returns whether or not a given branch of an AST reads from or writes to a given attribute.

Parameters
nodeThe AST to analyze
namethe name of the attribute to search for
typethe type of the attribute to search for. If UNKNOWN, any attribute with the given name is checked.
void visitNodeType ( const ast::Node node,
const OpT &  op 
)
inline

For an AST node of a given type, search for and call a custom const operator() which takes a const reference to every occurrence of the specified node type.

Parameters
nodeThe AST to run over
opThe operator to call on every found AST node of type NodeT
OPENVDB_AX_API bool openvdb::v12_0::ax::ast::writesToAttribute ( const ast::Node node,
const std::string &  name,
const tokens::CoreType  type = tokens::UNKNOWN 
)

Returns whether or not a given branch of an AST writes to a given attribute.

Parameters
nodeThe AST to analyze
namethe name of the attribute to search for
typethe type of the attribute to search for. If UNKNOWN, the first attribute encountered with the given name is checked.