pathExpression.h

//
// Copyright 2023 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_USD_SDF_PATH_EXPRESSION_H
#define PXR_USD_SDF_PATH_EXPRESSION_H
 
#include "pxr/pxr.h"
#include "pxr/usd/sdf/api.h"
#include "pxr/usd/sdf/path.h"
#include "pxr/usd/sdf/pathPattern.h"
#include "pxr/base/tf/hash.h"
#include "pxr/base/vt/value.h"
#include "pxr/base/vt/traits.h"
 
#include <iosfwd>
#include <string>
#include <tuple>
#include <utility>
#include <vector>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class SdfPathExpression
{
public:
    using PathPattern = SdfPathPattern;
    
    class ExpressionReference {
    public:
        SDF_API
        static ExpressionReference const &Weaker();
        
        // Optional path reference, can be empty for "weaker" references (name
        // is "_") or for references to local or otherwise "named" collections.
        SdfPath path;
        
        // Name is either a property name, or "_" (meaning the weaker
        // collection).  If the name is "_", the path must be empty.
        std::string name;
 
        template <class HashState>
        friend void TfHashAppend(HashState &h, ExpressionReference const &er) {
            h.Append(er.path, er.name);
        }
 
        friend bool
        operator==(ExpressionReference const &l, ExpressionReference const &r) {
            return std::tie(l.path, l.name) == std::tie(r.path, r.name);
        }
        
        friend bool
        operator!=(ExpressionReference const &l, ExpressionReference const &r) {
            return !(l == r);
        }
 
        friend void swap(ExpressionReference &l, ExpressionReference &r) {
            auto lt = std::tie(l.path, l.name);
            auto rt = std::tie(r.path, r.name);
            swap(lt, rt);
        }
    };
 
    enum Op {
        // Operations on atoms.
        Complement,
        ImpliedUnion,
        Union,
        Intersection,
        Difference,
 
        // Atoms.
        ExpressionRef,
        Pattern
    };
 
    SdfPathExpression() = default;
 
    SDF_API
    explicit SdfPathExpression(std::string const &expr,
                               std::string const &parseContext = {});
 
    SDF_API
    static SdfPathExpression const &Everything();
 
    SDF_API
    static SdfPathExpression const &EveryDescendant();
 
    SDF_API
    static SdfPathExpression const &Nothing();
 
    SDF_API
    static SdfPathExpression const &WeakerRef();
    
    SDF_API
    static SdfPathExpression
    MakeComplement(SdfPathExpression &&right);
 
    static SdfPathExpression
    MakeComplement(SdfPathExpression const &right) {
        return MakeComplement(SdfPathExpression(right));
    }
 
    SDF_API
    static SdfPathExpression
    MakeOp(Op op, SdfPathExpression &&left, SdfPathExpression &&right);
 
    static SdfPathExpression
    MakeOp(Op op,
           SdfPathExpression const &left,
           SdfPathExpression const &right) {
        return MakeOp(op, SdfPathExpression(left), SdfPathExpression(right));
    }
 
    SDF_API
    static SdfPathExpression
    MakeAtom(ExpressionReference &&ref);
 
    static SdfPathExpression
    MakeAtom(ExpressionReference const &ref) {
        return MakeAtom(ExpressionReference(ref));
    }
 
    SDF_API
    static SdfPathExpression
    MakeAtom(PathPattern &&pattern);
 
    static SdfPathExpression
    MakeAtom(PathPattern const &pattern) {
        return MakeAtom(PathPattern(pattern));
    }
 
    static SdfPathExpression
    MakeAtom(SdfPath const &path) {
        return MakeAtom(PathPattern(path));
    }
 
    static SdfPathExpression
    MakeAtom(SdfPath &&path) {
        return MakeAtom(PathPattern(path));
    }
 
    SDF_API
    void Walk(TfFunctionRef<void (Op, int)> logic,
              TfFunctionRef<void (ExpressionReference const &)> ref,
              TfFunctionRef<void (PathPattern const &)> pattern) const;
 
    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;
 
    SdfPathExpression
    ReplacePrefix(SdfPath const &oldPrefix,
                  SdfPath const &newPrefix) const & {
        return SdfPathExpression(*this).ReplacePrefix(oldPrefix, newPrefix);
    }
 
    SDF_API
    SdfPathExpression
    ReplacePrefix(SdfPath const &oldPrefix,
                  SdfPath const &newPrefix) &&;
 
    SDF_API
    bool IsAbsolute() const;
 
    SdfPathExpression
    MakeAbsolute(SdfPath const &anchor) const & {
        return SdfPathExpression(*this).MakeAbsolute(anchor);
    }
 
    SDF_API
    SdfPathExpression
    MakeAbsolute(SdfPath const &anchor) &&;
 
    bool ContainsExpressionReferences() const {
        return !_refs.empty();
    }
 
    SDF_API
    bool ContainsWeakerExpressionReference() const;
 
    SdfPathExpression
    ResolveReferences(
        TfFunctionRef<SdfPathExpression (
                          ExpressionReference const &)> resolve) const & {
        return SdfPathExpression(*this).ResolveReferences(resolve);
    }
 
    SDF_API
    SdfPathExpression
    ResolveReferences(
        TfFunctionRef<SdfPathExpression (
                          ExpressionReference const &)> resolve) &&;
    
    SdfPathExpression
    ComposeOver(SdfPathExpression const &weaker) const & {
        return SdfPathExpression(*this).ComposeOver(weaker);
    }
 
    SDF_API
    SdfPathExpression
    ComposeOver(SdfPathExpression const &weaker) &&;
 
    bool IsComplete() const {
        return !ContainsExpressionReferences() && IsAbsolute();
    }
 
    SDF_API
    std::string GetText() const;
 
    bool IsEmpty() const {
        return _ops.empty();
    }
    
    explicit operator bool() const {
        return !IsEmpty();
    }
 
    std::string const &GetParseError() const & {
        return _parseError;
    }
 
private:
    template <class HashState>
    friend void TfHashAppend(HashState &h, SdfPathExpression const &expr) {
        h.Append(expr._ops, expr._refs, expr._patterns, expr._parseError);
    }
 
    SDF_API
    friend std::ostream &
    operator<<(std::ostream &, SdfPathExpression const &);
 
    friend bool
    operator==(SdfPathExpression const &l, SdfPathExpression const &r) {
        return std::tie(l._ops, l._refs, l._patterns, l._parseError) ==
               std::tie(r._ops, r._refs, r._patterns, r._parseError);
    }
 
    friend bool
    operator!=(SdfPathExpression const &l, SdfPathExpression const &r) {
        return !(l == r);
    }
 
    friend void swap(SdfPathExpression &l, SdfPathExpression &r) {
        auto lt = std::tie(l._ops, l._refs, l._patterns, l._parseError);
        auto rt = std::tie(r._ops, r._refs, r._patterns, r._parseError);
        swap(lt, rt);
    }
 
    std::vector<Op> _ops;
    std::vector<ExpressionReference> _refs;
    std::vector<PathPattern> _patterns;
 
    // This member holds a parsing error string if this expression was
    // constructed by the parser and errors were encountered during the parsing.
    std::string _parseError;
};
 
// Path expressions support composing-over and value transforms.
VT_VALUE_TYPE_CAN_COMPOSE(SdfPathExpression);
VT_VALUE_TYPE_CAN_TRANSFORM(SdfPathExpression);
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_USD_SDF_PATH_EXPRESSION_H