 |
|
|
|
Class responsible for parsing and evaluating variable expressions. More...
#include <variableExpression.h>
Classes | |
| class | EmptyList |
| A result value representing an empty list. More... | |
Public Member Functions | |
| SDF_API | SdfVariableExpression (const std::string &expr) |
Construct using the expression expr. | |
| 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. | |
| 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. | |
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:
The "${NAME}" portion of the string with the value of expression variable "NAME".
Expression variables may be any of these supported types:
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 80 of file variableExpression.h.
| class SdfVariableExpression::EmptyList |
A result value representing an empty list.
Definition at line 139 of file variableExpression.h.
|
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.
| SDF_API SdfVariableExpression | ( | ) |
Construct an object representing an invalid expression.
| 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.
|
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 211 of file variableExpression.h.
| 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.
| SDF_API const std::string & GetString | ( | ) | const |
Returns the expression string used to construct this object.
|
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.
|
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.
|
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.
1.9.6