variableExpression.h File Reference

Include dependency graph for variableExpression.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	EmptyList
	A result value representing an empty list. More...
class	Builder
	Helper class for storing intermediate results when building a variable expression. More...
class	FunctionBuilder
	Helper class for storing intermediate results when building a function variable expression. More...
class	ListBuilder
	Helper class for storing intermediate results when building a list variable expression. More...

Functions
SDF_API	operator bool () const
	Returns true if this object represents a valid expression, false if it represents an invalid expression.
SDF_API const std::string &	GetString () const
	Returns the expression string used to construct this object.
SDF_API const std::vector< std::string > &	GetErrors () const
	Returns a list of errors encountered when parsing this expression.
Evaluation
SDF_API Result	Evaluate (const VtDictionary &variables) const
	Evaluates this expression using the variables in variables and returns a Result object with the final value.
template<class ResultType >
Result	EvaluateTyped (const VtDictionary &variables) const
	Evaluates this expression using the variables in variables and returns a Result object with the final value.
Building Expressions
Utilities for programatically building a variable expression. These functions can be chained together to create complex expressions. For example: const SdfVariableExpression containsExpr = SdfVariableExpression::MakeFunction( "contains", SdfVariableExpression::MakeList( SdfVariableExpression::MakeLiteral("foo"), SdfVariableExpression::MakeLiteral("bar")), SdfVariableExpression::MakeVariable("VAR")); This yields the expression contains(["foo", "bar"], ${VAR}). Note that these functions may yield invalid expressions that cannot be evaluated. For example, calling MakeFunction with an unrecognized function name will produce an SdfVariableExpression whose bool operator returns false. However, calling GetString on the returned SdfVariableExpression will still return the expression string for inspection.

---

Class Documentation

EmptyList

class EmptyList

A result value representing an empty list.

Definition at line 129 of file variableExpression.h.

Function Documentation

Evaluate()

SDF_API Result Evaluate

(

const VtDictionary &

variables

)

const

Evaluates this expression using the variables in variables and returns a Result object with the final value.

If an error occurs during evaluation, the value field in the Result object will be an empty VtValue and error messages will be added to the errors field.

If the expression evaluates to an empty list, the value field in the Result object will contain an EmptyList object instead of an empty VtArray<T>, as the expression language does not provide syntax for specifying the expected element types in an empty list.

If this object represents an invalid expression, calling this function will return a Result object with an empty value and the errors from GetErrors().

If any values in variables used by this expression are themselves expressions, they will be parsed and evaluated. If an error occurs while evaluating any of these subexpressions, evaluation of this expression fails and the encountered errors will be added in the Result's list of errors.

EvaluateTyped()

template<class ResultType >

Result EvaluateTyped

(

const VtDictionary &

variables

)

const

Evaluates this expression using the variables in variables and returns a Result object with the final value.

This is a convenience function that calls Evaluate and ensures that the value in the Result object is either an empty VtValue or is holding the specified ResultType. If this is not the case, the Result value will be set to an empty VtValue an error message indicating the unexpected type will be added to the Result's error list. Otherwise, the Result will be returned as-is.

If the expression evaluates to an empty list and the ResultType is a VtArray<T>, the value in the Result object will be an empty VtArray<T>. This differs from Evaluate, which would return an untyped EmptyList object instead.

ResultType must be one of the supported types listed in the class documentation.

Definition at line 201 of file variableExpression.h.

GetErrors()

SDF_API const std::vector< std::string > & GetErrors

(

)

const

Returns a list of errors encountered when parsing this expression.

If the expression was parsed successfully, this list will be empty. However, additional errors may be encountered when evaluating the e expression.

GetString()

SDF_API const std::string & GetString

(

)

const

Returns the expression string used to construct this object.

operator bool()

SDF_API operator bool ( ) const

explicit

Returns true if this object represents a valid expression, false if it represents an invalid expression.

A return value of true does not mean that evaluation of this expression is guaranteed to succeed. For example, an expression may refer to a variable whose value is an invalid expression. Errors like this can only be discovered by calling Evaluate.