Objects of this class represent a logical expression syntax tree consisting of SdfPath matching patterns (with optionally embedded predicate expressions) joined by the set-algebraic operators + (union), & (intersection), - (difference), ~ (complement) and an implied-union operator represented by two subexpressions joined by whitespace. More...

#include <pathExpression.h>

Classes
class	ExpressionReference
	Objects of this class represent references to other path expressions, which will be resolved later by a call to ResolveReferences() or ComposeOver(). More...

class	PathPattern
	Objects of this class represent SdfPath matching patterns, consisting of an SdfPath prefix followed by a sequence of components, which may contain wildcards and optional embedded predicate expressions (see SdfPredicateExpression). More...

Public Types
enum	Op { Complement , ImpliedUnion , Union , Intersection , Difference , ExpressionRef , Pattern }
	Enumerant describing a subexpression operation. More...

Public Member Functions
	SdfPathExpression ()=default
	Default construction produces the "empty" expression.

SDF_API	SdfPathExpression (std::string const &expr, std::string const &parseContext={})
	Construct an expression by parsing `expr`.

SDF_API void	Walk (TfFunctionRef< void(Op, int)> logic, TfFunctionRef< void(ExpressionReference const &)> ref, TfFunctionRef< void(PathPattern const &)> pattern) const
	Walk this expression's syntax tree in depth-first order, calling `pattern` with the current PathPattern when one is encountered, `ref` with the current ExpressionReference when one is encountered, and `logic` multiple times for each logical operation encountered.

SDF_API void	WalkWithOpStack (TfFunctionRef< void(std::vector< std::pair< Op, int > > const &)> logic, TfFunctionRef< void(ExpressionReference const &)> ref, TfFunctionRef< void(PathPattern const &)> pattern) const
	Equivalent to Walk(), except that the `logic` function is called with a const reference to the current Op stack instead of just the top of it.

SdfPathExpression	ReplacePrefix (SdfPath const &oldPrefix, SdfPath const &newPrefix) const &
	Return a new expression created by replacing literal path prefixes that start with `oldPrefix` with `newPrefix`.

SDF_API SdfPathExpression	ReplacePrefix (SdfPath const &oldPrefix, SdfPath const &newPrefix) &&
	Return a new expression created by replacing literal path prefixes that start with `oldPrefix` with `newPrefix`.

SDF_API bool	IsAbsolute () const
	Return true if all contained pattern prefixes are absolute, false otherwise.

SdfPathExpression	MakeAbsolute (SdfPath const &anchor) const &
	Return a new expression created by making any relative path prefixes in this expression absolute by SdfPath::MakeAbsolutePath().

SDF_API SdfPathExpression	MakeAbsolute (SdfPath const &anchor) &&
	Return a new expression created by making any relative path prefixes in this expression absolute by SdfPath::MakeAbsolutePath().

bool	ContainsExpressionReferences () const
	Return true if this expression contains any references to other collections.

SDF_API bool	ContainsWeakerExpressionReference () const
	Return true if this expression contains one or more "weaker" expression references, expressed as '_' in the expression language.

SdfPathExpression	ResolveReferences (TfFunctionRef< SdfPathExpression(ExpressionReference const &)> resolve) const &
	Return a new expression created by resolving collection references in this expression.

SDF_API SdfPathExpression	ResolveReferences (TfFunctionRef< SdfPathExpression(ExpressionReference const &)> resolve) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

SdfPathExpression	ComposeOver (SdfPathExpression const &weaker) const &
	Return a new expression created by replacing references to the "weaker expression" (i.e. "%_") in this expression with `weaker`.

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

bool	IsComplete () const
	Return true if this expression is considered "complete".

SDF_API std::string	GetText () const
	Return a text representation of this expression that parses to the same expression.

bool	IsEmpty () const
	Return true if this is the empty expression; i.e.

	operator bool () const
	Return true if this expression contains any operations, false otherwise.

std::string const &	GetParseError () const &
	Return parsing errors as a string if this function was constructed from a string and parse errors were encountered.

Static Public Member Functions
static SDF_API SdfPathExpression const &	Everything ()
	Return the expression "//" which matches all paths.

static SDF_API SdfPathExpression const &	EveryDescendant ()
	Return the relative expression ".//" which matches all paths descendant to an anchor path.

static SDF_API SdfPathExpression const &	Nothing ()
	Return the empty expression which matches no paths.

static SDF_API SdfPathExpression const &	WeakerRef ()
	Return the expression "%_", consisting solely of a reference to the "weaker" path expression, to be resolved by ComposeOver() or ResolveReferences()

static SDF_API SdfPathExpression	MakeComplement (SdfPathExpression &&right)
	Produce a new expression representing the set-complement of `right`.

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

static SDF_API SdfPathExpression	MakeOp (Op op, SdfPathExpression &&left, SdfPathExpression &&right)
	Produce a new expression representing the set-algebraic operation `op` with operands `left` and `right`.

static SdfPathExpression	MakeOp (Op op, SdfPathExpression const &left, SdfPathExpression const &right)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static SDF_API SdfPathExpression	MakeAtom (ExpressionReference &&ref)
	Produce a new expression containing only the reference `ref`.

static SdfPathExpression	MakeAtom (ExpressionReference const &ref)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static SDF_API SdfPathExpression	MakeAtom (PathPattern &&pattern)
	Produce a new expression containing only the pattern `pattern`.

static SdfPathExpression	MakeAtom (PathPattern const &pattern)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Friends
template<class HashState >
void	TfHashAppend (HashState &h, SdfPathExpression const &expr)

SDF_API friend std::ostream &	operator<< (std::ostream &, SdfPathExpression const &)

bool	operator== (SdfPathExpression const &l, SdfPathExpression const &r)

bool	operator!= (SdfPathExpression const &l, SdfPathExpression const &r)

void	swap (SdfPathExpression &l, SdfPathExpression &r)

Detailed Description

Objects of this class represent a logical expression syntax tree consisting of SdfPath matching patterns (with optionally embedded predicate expressions) joined by the set-algebraic operators + (union), & (intersection), - (difference), ~ (complement) and an implied-union operator represented by two subexpressions joined by whitespace.

An SdfPathExpression can be constructed from a string, which will parse the string into an expression object. The syntax for an expression is as follows:

The fundamental building blocks are path patterns and expression references. A path pattern is similar to an SdfPath, but it may contain glob-style wild-card characters, embedded brace-enclosed predicate expressions (see SdfPredicateExpression) and // elements indicating arbitrary levels of prim hierarchy. For example, consider /foo//bar*‍/baz{active:false}. This pattern matches absolute paths whose first component is foo, that also have some descendant prim whose name begins with bar, which in turn has a child named baz where the predicate active:false evaluates to true.

An expression reference starts with % followed by a prim path, a :, and a name. There is also one "special" expression reference, _ which means "the weaker" expression when composing expressions together. See ComposeOver() and ResolveReferences() for more information.

These building blocks may be joined as mentioned above, with +, -, &, or whitespace, and may be complemented with ~, and grouped with ( and ).

Definition at line 71 of file pathExpression.h.

Member Enumeration Documentation

◆ Op

enum Op

Enumerant describing a subexpression operation.

Definition at line 290 of file pathExpression.h.

Constructor & Destructor Documentation

◆ SdfPathExpression() [1/2]

SdfPathExpression ( )

default

Default construction produces the "empty" expression.

Conversion to bool returns 'false'. The empty expression matches nothing.

◆ SdfPathExpression() [2/2]

SDF_API SdfPathExpression	(	std::string const &	expr,
		std::string const &	parseContext = `{}`
	)

explicit

Construct an expression by parsing expr.

If provided, parseContext appears in a parse error, if one is generated. See GetParseError(). See the class documentation for details on expression syntax.

Member Function Documentation

◆ ComposeOver() [1/2]

SDF_API SdfPathExpression ComposeOver ( SdfPathExpression const & weaker ) &&

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

◆ ComposeOver() [2/2]

SdfPathExpression ComposeOver ( SdfPathExpression const & weaker ) const &

inline

Return a new expression created by replacing references to the "weaker expression" (i.e. "%_") in this expression with weaker.

This is a restricted form of ResolveReferences() that only resolves "weaker" references, replacing them by weaker, leaving other references unmodified. As a special case, if this expression IsEmpty(), return weaker.

Definition at line 504 of file pathExpression.h.

◆ ContainsExpressionReferences()

bool ContainsExpressionReferences ( ) const

inline

Return true if this expression contains any references to other collections.

Definition at line 468 of file pathExpression.h.

◆ ContainsWeakerExpressionReference()

SDF_API bool ContainsWeakerExpressionReference ( ) const

Return true if this expression contains one or more "weaker" expression references, expressed as '_' in the expression language.

Return false otherwise.

◆ EveryDescendant()

static SDF_API SdfPathExpression const & EveryDescendant ( )

static

Return the relative expression ".//" which matches all paths descendant to an anchor path.

◆ Everything()

static SDF_API SdfPathExpression const & Everything ( )

static

Return the expression "//" which matches all paths.

◆ GetParseError()

std::string const & GetParseError ( ) const &

inline

Return parsing errors as a string if this function was constructed from a string and parse errors were encountered.

Definition at line 545 of file pathExpression.h.

◆ GetText()

SDF_API std::string GetText ( ) const

Return a text representation of this expression that parses to the same expression.

◆ IsAbsolute()

SDF_API bool IsAbsolute ( ) const

Return true if all contained pattern prefixes are absolute, false otherwise.

Call MakeAbsolute() to anchor any relative paths and make them absolute.

◆ IsComplete()

bool IsComplete ( ) const

inline

Return true if this expression is considered "complete".

Here, complete means that the expression has all absolute paths, and contains no expression references. This is equivalent to:

!expr.ContainsExpressionReferences() && expr.IsAbsolute()

To complete an expression, call MakeAbsolute(), ResolveReferences() and/or ComposeOver().

Definition at line 523 of file pathExpression.h.

◆ IsEmpty()

bool IsEmpty ( ) const

inline

Return true if this is the empty expression; i.e.

default-constructed or constructed from a string with invalid syntax.

Definition at line 534 of file pathExpression.h.

◆ MakeAbsolute() [1/2]

SDF_API SdfPathExpression MakeAbsolute ( SdfPath const & anchor ) &&

Return a new expression created by making any relative path prefixes in this expression absolute by SdfPath::MakeAbsolutePath().

◆ MakeAbsolute() [2/2]

SdfPathExpression MakeAbsolute ( SdfPath const & anchor ) const &

inline

Return a new expression created by making any relative path prefixes in this expression absolute by SdfPath::MakeAbsolutePath().

Definition at line 456 of file pathExpression.h.

◆ MakeAtom() [1/4]

static SDF_API SdfPathExpression MakeAtom ( ExpressionReference && ref )

static

Produce a new expression containing only the reference ref.

◆ MakeAtom() [2/4]

static SdfPathExpression MakeAtom ( ExpressionReference const & ref )

inlinestatic

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

Definition at line 368 of file pathExpression.h.

◆ MakeAtom() [3/4]

static SDF_API SdfPathExpression MakeAtom ( PathPattern && pattern )

static

Produce a new expression containing only the pattern pattern.

◆ MakeAtom() [4/4]

static SdfPathExpression MakeAtom ( PathPattern const & pattern )

inlinestatic

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

Definition at line 379 of file pathExpression.h.

◆ MakeComplement() [1/2]

static SDF_API SdfPathExpression MakeComplement ( SdfPathExpression && right )

static

Produce a new expression representing the set-complement of right.

◆ MakeComplement() [2/2]

static SdfPathExpression MakeComplement ( SdfPathExpression const & right )

inlinestatic

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

Definition at line 342 of file pathExpression.h.

◆ MakeOp() [1/2]

static SDF_API SdfPathExpression MakeOp	(	Op	op,
		SdfPathExpression &&	left,
		SdfPathExpression &&	right
	)

static

Produce a new expression representing the set-algebraic operation op with operands left and right.

The op must be one of ImpliedUnion, Union, Intersection, or Difference.

◆ MakeOp() [2/2]

static SdfPathExpression MakeOp	(	Op	op,
		SdfPathExpression const &	left,
		SdfPathExpression const &	right
	)

inlinestatic

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

Definition at line 355 of file pathExpression.h.

◆ Nothing()

static SDF_API SdfPathExpression const & Nothing ( )

static

Return the empty expression which matches no paths.

This is the same as a default-constructed SdfPathExpression.

◆ operator bool()

operator bool ( ) const

inlineexplicit

Return true if this expression contains any operations, false otherwise.

Definition at line 539 of file pathExpression.h.

◆ ReplacePrefix() [1/2]

SDF_API SdfPathExpression ReplacePrefix	(	SdfPath const &	oldPrefix,
		SdfPath const &	newPrefix
	)		&&

Return a new expression created by replacing literal path prefixes that start with oldPrefix with newPrefix.

◆ ReplacePrefix() [2/2]

SdfPathExpression ReplacePrefix	(	SdfPath const &	oldPrefix,
		SdfPath const &	newPrefix
	)		const &

inline

Return a new expression created by replacing literal path prefixes that start with oldPrefix with newPrefix.

Definition at line 435 of file pathExpression.h.

◆ ResolveReferences() [1/2]

SDF_API SdfPathExpression ResolveReferences ( TfFunctionRef< SdfPathExpression(ExpressionReference const &)> resolve ) &&

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

◆ ResolveReferences() [2/2]

SdfPathExpression ResolveReferences ( TfFunctionRef< SdfPathExpression(ExpressionReference const &)> resolve ) const &

inline

Return a new expression created by resolving collection references in this expression.

This function calls resolve to produce a subexpression from a "%" ExpressionReference. To leave an expression reference unchanged, return an expression containing the passed argument by calling MakeAtom().

Definition at line 484 of file pathExpression.h.

◆ Walk()

SDF_API void Walk	(	TfFunctionRef< void(Op, int)>	logic,
		TfFunctionRef< void(ExpressionReference const &)>	ref,
		TfFunctionRef< void(PathPattern const &)>	pattern
	)		const

Walk this expression's syntax tree in depth-first order, calling pattern with the current PathPattern when one is encountered, ref with the current ExpressionReference when one is encountered, and logic multiple times for each logical operation encountered.

When calling logic, the logical operation is passed as the Op parameter, and an integer indicating "where" we are in the set of operands is passed as the int parameter. For a Complement, call logic(Op=Complement, int=0) to start, then after the subexpression that the Complement applies to is walked, call logic(Op=Complement, int=1). For the other operators like Union and Intersection, call logic(Op, 0) before the first argument, then logic(Op, 1) after the first subexpression, then logic(Op, 2) after the second subexpression. For a concrete example, consider the following expression:

/foo/bar// /foo/baz// & ~/foo/bar/qux// _

logic(Intersection, 0) logic(ImpliedUnion, 0) pattern(/foo/bar//) logic(ImpliedUnion, 1) pattern(/foo/baz//) logic(ImpliedUnion, 2) logic(Intersection, 1) logic(ImpliedUnion, 0) logic(Complement, 0) pattern(/foo/bar/qux//) logic(Complement, 1) logic(ImpliedUnion, 1) ref(_) logic(ImpliedUnion, 2) logic(Intersection, 2)

◆ WalkWithOpStack()

SDF_API void WalkWithOpStack	(	TfFunctionRef< void(std::vector< std::pair< Op, int > > const &)>	logic,
		TfFunctionRef< void(ExpressionReference const &)>	ref,
		TfFunctionRef< void(PathPattern const &)>	pattern
	)		const

Equivalent to Walk(), except that the logic function is called with a const reference to the current Op stack instead of just the top of it.

The top of the Op stack is the vector's back. This is useful in case the processing code needs to understand the context in which an Op appears.

◆ WeakerRef()

static SDF_API SdfPathExpression const & WeakerRef ( )

static

Return the expression "%_", consisting solely of a reference to the "weaker" path expression, to be resolved by ComposeOver() or ResolveReferences()

Friends And Related Function Documentation

◆ operator!=

bool operator!=	(	SdfPathExpression const &	l,
		SdfPathExpression const &	r
	)

friend

Definition at line 566 of file pathExpression.h.

◆ operator==

bool operator==	(	SdfPathExpression const &	l,
		SdfPathExpression const &	r
	)

friend

Definition at line 560 of file pathExpression.h.

◆ swap

void swap	(	SdfPathExpression &	l,
		SdfPathExpression &	r
	)

friend

Definition at line 570 of file pathExpression.h.

◆ TfHashAppend

void TfHashAppend	(	HashState &	h,
		SdfPathExpression const &	expr
	)

friend

Definition at line 551 of file pathExpression.h.

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

pxr/usd/sdf/pathExpression.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ Op

Constructor & Destructor Documentation

◆ SdfPathExpression() [1/2]

◆ SdfPathExpression() [2/2]

Member Function Documentation

◆ ComposeOver() [1/2]

◆ ComposeOver() [2/2]

◆ ContainsExpressionReferences()

◆ ContainsWeakerExpressionReference()

◆ EveryDescendant()

◆ Everything()

◆ GetParseError()

◆ GetText()

◆ IsAbsolute()

◆ IsComplete()

◆ IsEmpty()

◆ MakeAbsolute() [1/2]

◆ MakeAbsolute() [2/2]

◆ MakeAtom() [1/4]

◆ MakeAtom() [2/4]

◆ MakeAtom() [3/4]

◆ MakeAtom() [4/4]

◆ MakeComplement() [1/2]

◆ MakeComplement() [2/2]

◆ MakeOp() [1/2]

◆ MakeOp() [2/2]

◆ Nothing()

◆ operator bool()

◆ ReplacePrefix() [1/2]

◆ ReplacePrefix() [2/2]

◆ ResolveReferences() [1/2]

◆ ResolveReferences() [2/2]

◆ Walk()

◆ WalkWithOpStack()

◆ WeakerRef()

Friends And Related Function Documentation

◆ operator!=

◆ operator==

◆ swap

◆ TfHashAppend