SdfVariableExpression Class Reference

Class responsible for parsing and evaluating variable expressions. More...

#include <variableExpression.h>

Classes
class	Builder
	Helper class for storing intermediate results when building a variable expression. More...
class	EmptyList
	A result value representing an empty list. 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...

Public Member Functions
SDF_API	SdfVariableExpression (const std::string &expr)
	Construct using the expression expr.
SDF_API	SdfVariableExpression (std::string &&expr)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
SDF_API	SdfVariableExpression ()
	Construct an object representing an invalid expression.
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.

Static Public Member Functions
static SDF_API bool	IsExpression (const std::string &s)
	Returns true if s is a variable expression, false otherwise.
static SDF_API bool	IsValidVariableType (const VtValue &value)
	Returns true if value holds a type that is supported by variable expressions, false otherwise.
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.
template<class... Arguments>
static FunctionBuilder	MakeFunction (const std::string &fnName, Arguments &&... fnArgs)
	Create a function expression that calls the function named fnName with fnArgs as arguments, i.e.
template<class... Elements>
static ListBuilder	MakeList (Elements &&... elems)
	Create a list expression with listElems as elements, i.e.
template<class T >
static ListBuilder	MakeListOfLiterals (const std::vector< T > &values)
	Create a list expression with the values in values as literal elements.
static SDF_API Builder	MakeLiteral (int64_t value)
	Create a literal expression for value.
static SDF_API Builder	MakeLiteral (bool value)
static SDF_API Builder	MakeLiteral (const std::string &value)
static SDF_API Builder	MakeLiteral (const char *value)
static SDF_API Builder	MakeNone ()
	Create a "None" literal expression.
static SDF_API Builder	MakeVariable (const std::string &name)
	Create a variable reference expression for the variable named name, i.e.

Detailed Description

Class responsible for parsing and evaluating variable expressions.

Variable expressions are written in a custom language and represented in scene description as a string surrounded by backticks (`). These expressions may refer to "expression variables", which are key-value pairs provided by clients. For example, when evaluating an expression like:

`"a_${NAME}_string"`

The "${NAME}" portion of the string with the value of expression variable "NAME".

Expression variables may be any of these supported types:

• std::string
• int64_t (int is accepted but coerced to int64_t)
• bool
• VtArrays containing any of the above types.
• None (represented by an empty VtValue)

Expression variables are typically authored in scene description as layer metadata under the 'expressionVariables' field. Higher levels of the system (e.g., composition) are responsible for examining fields that support variable expressions, evaluating them with the appropriate variables (via this class) and consuming the results.

See Variable Expressions or more information on the expression language and areas of the system where expressions may be used.

Definition at line 63 of file variableExpression.h.

---

Class Documentation

SdfVariableExpression::EmptyList

class SdfVariableExpression::EmptyList

A result value representing an empty list.

Definition at line 129 of file variableExpression.h.

Constructor & Destructor Documentation

SdfVariableExpression() [1/3]

SDF_API SdfVariableExpression ( const std::string &  expr )

explicit

Construct using the expression expr.

If the expression cannot be parsed, this object represents an invalid expression. Parsing errors will be accessible via GetErrors.

SdfVariableExpression() [2/3]

SDF_API SdfVariableExpression ( std::string &&  expr )

explicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

SdfVariableExpression() [3/3]

SDF_API SdfVariableExpression

(

)

Construct an object representing an invalid expression.

Member 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()

Result EvaluateTyped ( const VtDictionary &  variables ) const

inline

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.

IsExpression()

static SDF_API bool IsExpression ( const std::string &  s )

static

Returns true if s is a variable expression, false otherwise.

A variable expression is a string surrounded by backticks (`).

A return value of true does not guarantee that s is a valid expression. This function is meant to be used as an initial check to determine if a string should be considered as an expression.

IsValidVariableType()

static SDF_API bool IsValidVariableType ( const VtValue &  value )

static

Returns true if value holds a type that is supported by variable expressions, false otherwise.

If this function returns true, value may be used for an expression variable supplied to the Evaluate function. value may also be authored into the 'expressionVariables' dictionary, unless it is an empty VtValue representing the None value. See class documentation for list of supported types.

MakeFunction()

static FunctionBuilder MakeFunction ( const std::string &  fnName, Arguments &&...  fnArgs  )

inlinestatic

Create a function expression that calls the function named fnName with fnArgs as arguments, i.e.

fnName(fnArgs1, fnArgs2, ...).

fnArgs must be other SdfVariableExpression objects or the result of other expression builder functions.

Definition at line 313 of file variableExpression.h.

MakeList()

static ListBuilder MakeList ( Elements &&...  elems )

inlinestatic

Create a list expression with listElems as elements, i.e.

[listElems1, listElems2, ...].

elems must be other SdfVariableExpression objects or the result of other expression builder functions.

Definition at line 327 of file variableExpression.h.

MakeListOfLiterals()

static ListBuilder MakeListOfLiterals ( const std::vector< T > &  values )

inlinestatic

Create a list expression with the values in values as literal elements.

values must hold types that can be represented by literal expressions, i.e. a type for which MakeLiteral is defined.

Definition at line 341 of file variableExpression.h.

MakeLiteral()

static SDF_API Builder MakeLiteral ( int64_t  value )

static

Create a literal expression for value.

MakeNone()

static SDF_API Builder MakeNone ( )

static

Create a "None" literal expression.

MakeVariable()

static SDF_API Builder MakeVariable ( const std::string &  name )

static

Create a variable reference expression for the variable named name, i.e.

${name}.

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.

---

The documentation for this class was generated from the following file:

• pxr/usd/sdf/variableExpression.h