ParameterTree.hpp

// <ParameterTree.hpp> -*- C++ -*-
 
#pragma once
 
#include <vector>
#include <sstream>
#include <regex>
#include <memory>
#include <string>
#include <map>
#include <any>
 
#include <boost/algorithm/string.hpp>
 
#include "sparta/utils/Utils.hpp"
#include "sparta/simulation/Parameter.hpp"
#include "sparta/simulation/TreeNode.hpp"
#include "sparta/utils/LexicalCast.hpp"
#include "sparta/utils/MetaStructs.hpp"
 
namespace sparta
{
    class ParameterTree
    {
    public:
 
        class Node
        {
        public:
 
            typedef std::vector<std::unique_ptr<Node>> ChildVector;
 
        private:
 
            Node* parent_ = nullptr; 
            ParameterTree * tree_ = nullptr;  
            std::string name_;     
            std::string value_;    
            std::string origin_;   
            bool has_value_;       
            ChildVector children_; 
            uint32_t write_count_; 
            mutable uint32_t read_count_ = 0; 
            std::map<std::string, std::any> user_data_; 
 
            class UserDataPrinterBase
            {
            public:
                virtual ~UserDataPrinterBase() = default;
                virtual void print(const std::string& name, std::any user_data, std::ostream& o, uint32_t indent) const = 0;
            };
 
            template <typename T>
            class UserDataPrinter : public UserDataPrinterBase
            {
            public:
                void print(const std::string& name, std::any user_data, std::ostream& o, uint32_t indent) const override
                {
                    const T& ud = std::any_cast<const T&>(user_data);
                    for (uint32_t i = 0; i < indent; ++i) {
                        o << " ";
                    }
                    o << name << ": ";
                    print_(o, ud, indent);
                    o << "\n";
                }
 
            private:
                template <typename Value>
                typename std::enable_if<MetaStruct::is_any_pointer<Value>::value, void>::type
                print_(std::ostream& o, const Value& val, uint32_t indent) const {
                    if (!val) {
                        o << "nullptr";
                    } else {
                        o << val << " -> ";
                        print_(o, *val, indent);
                    }
                }
 
                template <typename Value>
                typename std::enable_if<!MetaStruct::is_any_pointer<Value>::value, void>::type
                print_(std::ostream& o, const Value& val, uint32_t indent) const {
                    if constexpr (std::is_same_v<Value, TreeNode::ExtensionsBase>) {
                        if (auto ps = val.getParameters()) {
                            o << val.getClassName() << " extension with parameters:\n";
                            const std::string s = ps->dumpList();
                            std::vector<std::string> lines;
                            boost::split(lines, s, boost::is_any_of("\n"));
                            for (auto & line : lines) {
                                for (uint32_t i = 0; i < indent+2; ++i) {
                                    o << " ";
                                }
                                o << line << "\n";
                            }
                        } else {
                            o << "extension without parameters";
                        }
                    } else if constexpr (std::is_same_v<Value, bool>) {
                        o << std::boolalpha << val << std::dec;
                    } else {
                        o << val;
                    }
                }
            };
 
            std::unordered_map<std::string, std::unique_ptr<UserDataPrinterBase>> user_data_printers_;
 
            uint32_t required_ = 0;
 
        public:
 
            Node() = delete;
 
            Node(Node* parent, const std::string& name,
                 const std::string& value, const std::string& origin) :
                parent_(parent),
                name_(name),
                value_(value),
                origin_(origin),
                has_value_(true),
                write_count_(1)
            {;}
 
            Node(Node* parent, const std::string& name) :
                parent_(parent),
                name_(name),
                value_(),
                has_value_(false),
                write_count_(0)
            {;}
 
            Node(Node* parent, ParameterTree* tree) :
                parent_(parent),
                tree_(tree),
                name_(""),
                value_(),
                has_value_(false),
                write_count_(0)
            {;}
 
            Node(Node* parent, const Node& n) :
                parent_(parent),
                name_(n.name_),
                value_(n.value_),
                origin_(n.origin_),
                has_value_(n.has_value_),
                write_count_(n.write_count_),
                read_count_(n.read_count_)
            {
                for(auto& x : n.children_){
                    children_.emplace_back(new Node(this, *x.get()));
                }
            }
 
            Node& operator= (const Node& n) {
                // preserve parent_
                name_ = n.name_;
                value_ = n.value_;
                origin_ = n.origin_;
                has_value_ = n.has_value_;
                write_count_ = static_cast<decltype(write_count_)>(has_value_);
                read_count_ = 0;
                for(auto& x : n.children_){
                    children_.emplace_back(new Node(this, *x.get()));
                }
                return *this;
            }
 
            void dump(std::ostream& o) const {
                o << "<VPT Node: \"" << name_ << "\" children:" << children_.size()
                  << " writes:" << write_count_ << " reads:" << read_count_ << " required:" << required_ << ">";
            }
 
            const std::string& getName() const { return name_; }
 
            Node* getParent() { return parent_; }
 
            Node const * getParent() const { return parent_; }
 
            Node * getRoot() {
                Node* p = this;
                while(p->getParent() != nullptr){
                    p = p->getParent();
                }
                sparta_assert(p->getName().size() == 0);
                return p;
            }
 
            Node const * getRoot() const {
                Node const * p = this;
                while(p->getParent() != nullptr){
                    p = p->getParent();
                }
                sparta_assert(p->getName().size() == 0);
                return p;
            }
 
            ParameterTree* getOwner() {
                return getRoot()->tree_;
            }
 
            const ParameterTree* getOwner() const {
                return getRoot()->tree_;
            }
 
            std::string getPath() const {
                std::stack<const std::string*> names;
                Node const * n = this;
                while(n && n->getName().size() > 0){ // Stop at null parent, or root (which has no name)
                    names.push(&n->getName());
                    n = n->getParent();
                }
 
                std::stringstream ss;
                if(names.size() > 0){
                    ss << *names.top();
                    names.pop();
                    while(names.size() > 0){
                        ss << '.' << *names.top();
                        names.pop();
                    }
                }
                return ss.str();
            }
 
            bool isRoot() const {
                return name_.size() == 0;
            }
 
            void incrementReadCount() const {
                ++read_count_;
            }
 
            void resetReadCount() const {
                read_count_ = 0;
            }
 
            uint32_t getReadCount() const {
                return read_count_;
            }
 
            const std::string& getValue() const {
                sparta_assert(hasValue(), "Node \"" << name_ << "\" does not have a value associated with it");
                incrementReadCount();
                return value_;
            }
 
            const std::string& peekValue() const {
                sparta_assert(hasValue(), "Node \"" << name_ << "\" does not have a value associated with it");
                return value_;
            }
 
            const std::string& getOrigin() const {
                sparta_assert(hasValue(), "Node \"" << name_ << "\" does not have a value associated with it");
                return origin_;
            }
 
            template <typename T, typename=typename std::enable_if<!std::is_convertible<T, std::string>::value>::type>
            T getAs() const {
                return lexicalCast<T>(getValue());
            }
 
            template <typename T, typename=typename std::enable_if<std::is_convertible<T, std::string>::value>::type>
            const std::string& getAs() const {
                return getValue();
            }
 
            operator std::string () const {
                return value_;
            }
 
            template <typename T>
            operator T () const {
                return getAs<T>();
            }
 
            template <typename T>
            bool operator==(const T& rhp) const {
                return getAs<T>() == rhp;
            }
 
            static bool matches(const std::string& pattern, const std::string& other) {
                std::regex expr(TreeNode::createSearchRegexPattern(pattern));
                std::smatch what;
                return std::regex_match(other, what, expr);
            }
 
            Node* getChild(const std::string& name) const {
                if(TreeNode::hasWildcardCharacters(name)){
                    throw SpartaException("Cannot call ParameterTree::Node::getChild with a name that is a search pattern: \"")
                        << name << "\". addChild must be used instead";
                }
 
                // Always search in reverse-applied order to match on most recent changes first
                auto itr = children_.rbegin();
                for(; itr != children_.rend(); ++itr){
                    if(matches((*itr)->getName(), name)){
                        return itr->get();
                    }
                }
 
                return nullptr;
            }
 
            Node* create(const std::string& path, bool required) {
                if(path.size() == 0){
                    return this;
                }
 
                size_t name_pos = 0;
                std::string immediate_child_name;
                immediate_child_name = TreeNode::getNextName(path, name_pos);
                if(immediate_child_name.size() == 0){
                    // Cannot get parent like this
                    return nullptr; // TEMPORARY behavior. See docstring
                    //throw SpartaException("Virtual parameter path \"") << path
                    //      << "\" is invalid because it contains an empty name (between two '.' "
                    //         "characters). Parents cannot currently be referenced in the virtual parameter tree";
                }
 
                // Get a child of node if one exists with an exact match before any nodes
                // with wilcards are encountered. If this node name includes a wildcard, a
                // child will be returned IFF it the pattern string itself matches with the
                // highest priority child in this node.
                Node* child = getPriorityChildMatch(immediate_child_name);
                if(!child){
                    child = addChild(immediate_child_name, required);
                }
 
                if(name_pos == std::string::npos){
                    return child;
                }
 
                const std::string remainder = path.substr(name_pos);
                return child->create(remainder, required);
            }
 
            Node* getPriorityChildMatch(const std::string& name) const {
                if(children_.size() == 0){
                    return nullptr;
                }
 
                // Becase the name is a pattern, it is impossible to math against other existing
                // children which are patterns. Therefore, if a pattern child is encountered
                // which does not exactly match the given name string, nullptr must be returned so
                // that the caller appends a new node, whih will have the highest priority
                const bool name_has_wildcard = TreeNode::hasWildcardCharacters(name);
 
                // Always search in reverse-applied order to match on most recent changes first.
                //
                // This is an optimization to prevent nodes from being created needlessly. It tries
                // to find a matching node while considering wildcards to avoid creating new nodes
                // in most cases where it is possible.
                //
                // Read the rules below to understand what happens. In general, if we don't get an
                // exact string match with an existing node before hitting another node which is
                // an exclusive superset or incomplete subset of the 'name' argument's pattern (it
                // may have no wildcards) then a new node will need to be added at the end of the
                // children list to specify a value. An existing node cannot be overridden.
                auto itr = children_.rbegin();
                for(; itr != children_.rend(); ++itr){
                    if((*itr)->getName() == name){
                        // Found a node with an exact name match (no pattern matching) before
                        // hitting a pattern node. This node can be used to apply a new parameter
                        return itr->get();
                    }
 
                    if(name_has_wildcard){
                        if(TreeNode::hasWildcardCharacters((*itr)->getName())){
                            // Encountered a wildcard node whch was not an exact string match.
                            // No way to tell if the name pattern exactly matches this node's, so
                            // assume it doesn't
                            return nullptr;
                        }else if(matches(name, (*itr)->getName())){
                            // Node has not wildcards but matches the pattern in 'name'. Therfore,
                            // A new parameter with this name would affect this node and more. A new
                            // node will have to be added to override it.
                            return nullptr;
                        }else{
                            // Node has no wildcards and the name agument is a pattern which
                            // does not match it. Therefore, it can be ignored because this 'name'
                            // will not apply
                            continue;
                        }
                    }else if(matches((*itr)->getName(), name)){
                        // Encountered a wildcard node which matches on this name before hitting an
                        // exact match. Therefore, a new node must be created by the caller so that
                        // the parameter being set will affect a subset of this node's pattern
                        return nullptr;
                    }
                }
                // No matches or important mismatches
                return nullptr;
            }
 
            Node* addChild(const std::string& name, bool required) {
                sparta_assert(hasValue() == false,
                            "Cannot add a child to a virtual parameter tree node \"" << name_
                            << "\" since it already has a value: \"" << value_ << "\"");
 
                children_.emplace_back(new Node(this, name));
                if(required){
                    children_.back()->incRequired();
                }
                return (children_.back().get());
            }
 
            Node& operator[] (const std::string& name) const {
                Node* child = getChild(name);
                sparta_assert(child != nullptr,
                                  "Node \"" << name_ << "\" has no child named \"" << name << "\"");
                return *child;
            }
 
            Node& operator[] (const char* name) const {
                return this->operator[](std::string(name));
            }
 
            bool hasValue() const {
                return has_value_;
            }
 
            void setValue(const std::string& val, bool required=true, const std::string& origin="") {
                //sparta_assert(parent_,
                //                  "Cannot assign a value to the root node of a virtual parameter tree");
                //sparta_assert(read_count_ == 0,
                //                  "Cannot set(\"" << val << "\") on node \"" << name_ << "\" because it has been read already");
                value_ = val;
                origin_ = origin;
                has_value_ = true;
                write_count_++;
                if(required){
                    required_ += 1;
                }
            }
 
            void incRequired() {
                required_ += 1;
            }
 
            void unrequire() {
                required_ = 0;
                for(auto & n : children_){
                    n->unrequire();
                }
            }
 
            std::unique_ptr<Node> release() {
                return parent_->release_(this);
            }
 
            bool set(const std::string& path, const std::string& val, bool required, const std::string& origin="") {
                //sparta_assert(read_count_ == 0,
                //            "Cannot set(\"" << val << "\") on node \"" << name_
                //            << "\" because it has been read already");
 
                // Set through root of the tree.
                std::string full_path = getPath();
                if(full_path.size() > 0 && path.size() > 0){
                    full_path += ".";
                }
                full_path += path;
                return getOwner()->set(full_path, val, required, origin);
            }
 
            const std::string& operator= (const std::string& val) {
                set("", val, true);
                return val;
            }
 
            bool isRequired() const {
                // Start at beginning. Another, later-written node may override
                // this node if it has the same patch or a matching pattern.
                if (getOwner()->isRequired(getPath()))
                {
                    return true;
                }
                return false;
            }
 
            uint32_t getRequiredCount() const {
                return required_;
            }
 
            std::vector<Node*> getChildren() {
                std::vector<Node*> children;
                for(auto & n : children_){
                    children.push_back(n.get());
                }
                return children;
            }
 
            std::vector<const Node*> getChildren() const {
                std::vector<const Node*> children;
                for(auto & n : children_){
                    children.push_back(n.get());
                }
                return children;
            }
 
            void recursFindPTreeNodesNamed(
                const std::string & name,
                std::vector<Node*> & matching_nodes)
            {
                if (getName() == name) {
                    matching_nodes.emplace_back(this);
                    return;
                }
 
                const auto children = getChildren();
                for (ParameterTree::Node * child : children) {
                    child->recursFindPTreeNodesNamed(name, matching_nodes);
                }
            }
 
            void recursFindPTreeNodesNamed(
                const std::string & name,
                std::vector<const Node*> & matching_nodes) const
            {
                if (getName() == name) {
                    matching_nodes.emplace_back(this);
                    return;
                }
 
                const auto children = getChildren();
                for (const ParameterTree::Node * child : children) {
                    child->recursFindPTreeNodesNamed(name, matching_nodes);
                }
            }
 
            template <typename Callback>
            size_t recurseVisitNodes(Callback callback) {
                size_t count = 0;
                recurseVisitNodes_(callback, count);
                return count;
            }
 
            template <typename Callback>
            size_t recurseVisitNodes(Callback callback) const {
                size_t count = 0;
                recurseVisitNodes_(callback, count);
                return count;
            }
 
            template <typename Callback>
            size_t recurseVisitLeaves(Callback callback) {
                size_t count = 0;
                recurseVisitLeaves_(callback, count);
                return count;
            }
 
            template <typename Callback>
            size_t recurseVisitLeaves(Callback callback) const {
                size_t count = 0;
                recurseVisitLeaves_(callback, count);
                return count;
            }
 
            void recursePrint(std::ostream& o, uint32_t indent=0, bool print_user_data=true) const {
                for(uint32_t i=0; i<indent; ++i){
                    o << " ";
                }
                o << name_;
                if(has_value_){
                    o << " = \"" << value_ << "\" (read " << read_count_ << ", written " << write_count_
                      << ", required " << required_ << ", origin '" << getOrigin() << "')";
                }
                o << "\n";
                if(print_user_data){
                    printUserData(o, indent+2);
                }
                for(auto & n : children_){
                    n->recursePrint(o, indent+2, print_user_data);
                }
            }
 
            void printUserData(std::ostream& o, uint32_t indent=0) const {
                if (user_data_.empty()) {
                    return;
                }
 
                for(uint32_t i=0; i<indent; ++i){
                    o << " ";
                }
 
                o << "User data (" << getPath() << "):\n";
                for (const auto & [ud_name, ud_printer] : user_data_printers_) {
                    std::any ud = user_data_.at(ud_name);
                    ud_printer->print(ud_name, ud, o, indent+2);
                }
            }
 
            void appendTree(const Node* ot) {
                sparta_assert(ot, "Cannot append a null virtual parameter tree");
                if(ot->getName().size() > 0){
                    // Attach 'ot' node argument as child of this
                    const bool required = false; // The starting node is not required to exist.. only its node children
                    Node* child = create(ot->getName(), required);
                    child->recursAppendTree_(ot);
                }else{
                    // 'ot' is a root node (no name). Merge it with this.
                    recursAppendTree_(ot);
                }
            }
 
            template <typename T>
            void setUserData(const std::string & name, const T & user_data) {
                static_assert(std::is_copy_constructible<T>::value, "std::any only works with copyable types");
                user_data_[name] = user_data;
                user_data_printers_[name] = std::make_unique<UserDataPrinter<T>>();
            }
 
            template <typename T>
            void setUserData(const std::string & name, T && user_data) {
                static_assert(std::is_copy_constructible<T>::value, "std::any only works with copyable types");
                user_data_[name] = std::move(user_data);
                user_data_printers_[name] = std::make_unique<UserDataPrinter<T>>();
            }
 
            template <typename T>
            const T & getUserData(const std::string & name) const {
                constexpr bool must_exist = true;
                return *tryGetUserData<T>(name, must_exist);
            }
 
            template <typename T>
            T & getUserData(const std::string & name) {
                constexpr bool must_exist = true;
                return *tryGetUserData<T>(name, must_exist);
            }
 
            template <typename T>
            const T * tryGetUserData(const std::string & name, bool must_exist = false) const {
                auto it = user_data_.find(name);
                if (it == user_data_.end()) {
                    if (must_exist) {
                        throw SpartaException("User data '") << name << "' does not exist for node '"
                            << getPath() << "'";
                    }
                    return nullptr;
                }
                return &std::any_cast<const T&>(it->second);
            }
 
            template <typename T>
            T * tryGetUserData(const std::string & name, bool must_exist = false) {
                auto it = user_data_.find(name);
                if (it == user_data_.end()) {
                    if (must_exist) {
                        throw SpartaException("User data '") << name << "' does not exist for node '"
                            << getPath() << "'";
                    }
                    return nullptr;
                }
                return &std::any_cast<T&>(it->second);
            }
 
            void recurseGetAllNodeExtensions(
                std::map<const Node*, std::map<std::string, const TreeNode::ExtensionsBase*>> & map) const
            {
                for (const auto & key : getUserDataKeys()) {
                    if (auto ext = tryGetUserData<std::shared_ptr<TreeNode::ExtensionsBase>>(key)) {
                        map[this][key] = ext->get();
                    }
                }
 
                for (auto child : getChildren()) {
                    child->recurseGetAllNodeExtensions(map);
                }
            }
 
            std::set<std::string> getUserDataKeys() const {
                std::set<std::string> keys;
                for (const auto & [key, _] : user_data_) {
                    keys.insert(key);
                }
                return keys;
            }
 
            bool clearUserData(const std::string & name) {
                user_data_printers_.erase(name);
                if (user_data_.count(name)) {
                    user_data_.erase(name);
                    return true;
                }
                return false;
            }
 
            size_t clearUserData() {
                user_data_printers_.clear();
                auto sz = user_data_.size();
                user_data_.clear();
                return sz;
            }
 
            class MatchIterator {
                ChildVector::const_reverse_iterator itr_;
            public:
                MatchIterator(ChildVector::const_reverse_iterator itr) :
                    itr_(itr)
                {;}
 
                MatchIterator(const MatchIterator&) = default;
 
                MatchIterator& operator=(const MatchIterator&) = default;
 
                bool operator==(const MatchIterator& rhp) const {
                    return itr_ == rhp.itr_;
                }
 
                bool operator!=(const MatchIterator& rhp) const {
                    return itr_ != rhp.itr_;
                }
 
                void operator++(int) {++itr_;}
 
                void operator++() {++itr_;}
 
                bool matches(const std::string& other) const {
                    return ParameterTree::Node::matches((*itr_)->getName(), other);
                }
 
                const Node* get() const {
                    return itr_->get();
                }
 
                Node* get() {
                    return itr_->get();
                }
 
                const Node* operator->() const {
                    return itr_->get();
                }
            };
 
            friend class MatchIterator;
 
            MatchIterator getMatcherBegin() const { return MatchIterator(children_.rbegin()); }
 
            MatchIterator getMatcherEnd() const { return MatchIterator(children_.rend()); }
 
        private:
 
            void recursAppendTree_(const Node* ot) {
                // Inherit value. Never invalidate
                if(ot->hasValue()){
                    setValue(ot->peekValue(), ot->getRequiredCount() > 0, ot->getOrigin());
                }
 
                // Inherit user data.
                for(const auto & [ud_name, ud_value] : ot->user_data_){
                    user_data_[ud_name] = ud_value;
                }
 
                for(auto & child : ot->getChildren()){
                    // TODO: copy required count instead of just boolean
                    Node* c = create(child->getName(), child->getRequiredCount() > 0); // Create if needed
                    c->recursAppendTree_(child);
                }
            }
 
            template <typename Callback>
            bool recurseVisitNodes_(Callback callback, size_t & count) {
                ++count;
                auto keep_going = callback(this);
                if (!keep_going) {
                    return false;
                }
                for (auto & child : children_) {
                    if (!child->recurseVisitNodes_(callback, count)) {
                        return false;
                    }
                }
                return true;
            }
 
            template <typename Callback>
            bool recurseVisitNodes_(Callback callback, size_t & count) const {
                ++count;
                auto keep_going = callback(this);
                if (!keep_going) {
                    return false;
                }
                for (const auto & child : children_) {
                    if (!child->recurseVisitNodes_(callback, count)) {
                        return false;
                    }
                }
                return true;
            }
 
            template <typename Callback>
            bool recurseVisitLeaves_(Callback callback, size_t & count) {
                if (children_.empty()) {
                    ++count;
                    auto keep_going = callback(this);
                    if (!keep_going) {
                        return false;
                    }
                }
 
                for (auto & child : children_) {
                    if (!child->recurseVisitLeaves_(callback, count)) {
                        return false;
                    }
                }
                return true;
            }
 
            template <typename Callback>
            bool recurseVisitLeaves_(Callback callback, size_t & count) const {
                if (children_.empty()) {
                    ++count;
                    auto keep_going = callback(this);
                    if (!keep_going) {
                        return false;
                    }
                }
 
                for (const auto & child : children_) {
                    if (!child->recurseVisitLeaves_(callback, count)) {
                        return false;
                    }
                }
                return true;
            }
 
            std::unique_ptr<Node> release_(Node *node) {
                std::unique_ptr<Node> rtn;
                auto it = std::find_if(children_.begin(), children_.end(),
                                       [node] (const auto & child) -> bool {
                                           return (child.get() == node);
                                       });
                if (it != children_.end()) {
                    rtn = std::move(*it);
                    children_.erase(it);
                }
                return rtn;
            }
        };
 
        ParameterTree() :
            root_(new Node(nullptr, this))
        {;}
 
        ParameterTree(const ParameterTree& rhp) :
            root_(new Node(nullptr, this))
        {
            root_->appendTree(rhp.getRoot());
        }
 
        ParameterTree& operator=(const ParameterTree& rhp) {
            clear();
            merge(rhp);
            return *this;
        }
 
        //bool operator==(const ParameterTree& rhp) const {
        //}
 
        virtual ~ParameterTree() {}
 
        void clear() {
            root_.reset(new Node(nullptr, this)); // Clear all children
        }
 
        bool set(const std::string& path, const std::string& value, bool required, const std::string& origin="") {
            Node* n = create(path, false); // inc required after setting value
            if(!n){
                return false;
            }
            n->setValue(value, required, origin);
 
            return true;
        }
 
        Node* create(const std::string& path, bool required=false) {
            if(path.size() == 0){
                return getRoot();
            }
 
            return getRoot()->create(path, required);
        }
 
        const Node& get(const std::string& path) const {
            const Node* node = tryGet(path);
            if(!node){
                throw SpartaException("Unable to find parameter in tree: \"") << path << "\"";
            }
            return *node;
        }
 
        const Node& operator[] (const std::string& name) const {
            return get(name);
        }
 
        bool hasValue(const std::string& path, const bool must_be_leaf = true) const {
            const Node* n = tryGet_(path, must_be_leaf);
            return n != nullptr && n->hasValue();
        }
 
        bool exists(const std::string& path, const bool must_be_leaf = true) const {
            return tryGet_(path, must_be_leaf) != nullptr;
        }
 
        uint32_t getUnreadValueNodes(std::vector<const Node*>* nodes) const {
            return recursCountUnreadValueNodes_<const Node>(root_.get(), nodes);
        }
 
        uint32_t getUnreadValueNodes(std::vector<Node*>* nodes) {
            return recursCountUnreadValueNodes_<Node>(root_.get(), nodes);
        }
 
        const Node* tryGet(const std::string& path, const bool must_be_leaf = true) const {
            return tryGet_(path, must_be_leaf);
        }
 
        Node* tryGet(const std::string& path, const bool must_be_leaf = true) {
            return tryGet_(path, must_be_leaf);
        }
 
        bool isRequired(const std::string& path) const {
 
            if(path.size() == 0){
                return root_->getRequiredCount() > 0;
            }
 
            std::string immediate_child_name;
            size_t name_pos = 0;
            immediate_child_name = TreeNode::getNextName(path, name_pos);
 
            if(immediate_child_name.size() == 0){
                // Cannot get parent.
                throw SpartaException("Parameter ") << path
                                                  << " is invalid because it contains an empty name (between two '.' "
                    "characters). Parents cannot currently be refrenced in the parameter tree";
            }
 
            bool match_found = false;
            const bool required = recursGetIsRequired_(root_.get(), path, immediate_child_name, name_pos, match_found);
            sparta_assert(match_found,
                        "Asked ParameterTree if path \"" << path << "\" is required but no "
                        "matching node was found in the ParameterTree");
            return required;
        }
 
        bool unrequire(const std::string &path) {
            Node * node = tryGet_(path, false);
            if(nullptr != node) {
                node->unrequire();
                return true;
            }
            return false;
        }
 
        bool isRead(const std::string& path) const {
            if(path.size() == 0){
                return root_->hasValue() && root_->getReadCount() > 0;
            }
 
            std::string immediate_child_name;
            size_t name_pos = 0;
            immediate_child_name = TreeNode::getNextName(path, name_pos);
 
            if(immediate_child_name.size() == 0){
                // Cannot get parent.
                throw SpartaException("Parameter ") << path
                                                  << " is invalid because it contains an empty name (between two '.' "
                    "characters). Parents cannot currently be refrenced in the parameter tree";
            }
 
            return recursIsRead_(root_.get(), path, immediate_child_name, name_pos);
        }
 
        Node const * getRoot() const { return root_.get(); }
 
        Node * getRoot() { return root_.get(); }
 
        void merge(const ParameterTree& rhp) {
            root_->appendTree(rhp.getRoot());
        }
 
        template <typename Callback>
        size_t visitNodes(Callback callback) {
            return root_->recurseVisitNodes(callback);
        }
 
        template <typename Callback>
        size_t visitNodes(Callback callback) const {
            return root_->recurseVisitNodes(callback);
        }
 
        template <typename Callback>
        size_t visitLeaves(Callback callback) {
            return root_->recurseVisitLeaves(callback);
        }
 
        template <typename Callback>
        size_t visitLeaves(Callback callback) const {
            return root_->recurseVisitLeaves(callback);
        }
 
        void recursePrint(std::ostream& o, bool print_user_data=true) const {
            root_->recursePrint(o, 0, print_user_data); // Begin with 0 indent
        }
 
        std::map<const Node*, std::map<std::string, const TreeNode::ExtensionsBase*>>
        getAllNodeExtensions() const
        {
            std::map<const Node*, std::map<std::string, const TreeNode::ExtensionsBase*>> all_ext_map;
            root_->recurseGetAllNodeExtensions(all_ext_map);
            return all_ext_map;
        }
 
    private:
 
        const Node* tryGet_(const std::string& path, const bool must_be_leaf = true) const {
            if(path.size() == 0){
                return root_.get();
            }
 
            std::string immediate_child_name;
            size_t name_pos = 0;
            immediate_child_name = TreeNode::getNextName(path, name_pos);
 
            if(immediate_child_name.size() == 0){
                // Cannot get parent.
                throw SpartaException("Parameter ") << path
                                                  << " is invalid because it contains an empty name (between two '.' "
                    "characters). Parents cannot currently be refrenced in the parameter tree";
            }
 
            return recursTryGet_<const Node>(static_cast<const Node*>(root_.get()), path,
                                             immediate_child_name, name_pos, must_be_leaf);
        }
 
        Node* tryGet_(const std::string& path, const bool must_be_leaf = true) {
            if(path.size() == 0){
                return root_.get();
            }
 
            std::string immediate_child_name;
            size_t name_pos = 0;
            immediate_child_name = TreeNode::getNextName(path, name_pos);
 
            if(immediate_child_name.size() == 0){
                // Cannot get parent.
                throw SpartaException("Parameter ") << path
                                                  << " is invalid because it contains an empty name (between two '.' "
                    "characters). Parents cannot currently be refrenced in the parameter tree";
            }
 
            return recursTryGet_(root_.get(), path,
                                 immediate_child_name, name_pos, must_be_leaf);
        }
 
        template<typename NodeT>
        static NodeT* recursTryGet_(NodeT* node, const std::string& path,
                                    const std::string& match_name,
                                    size_t name_pos, const bool must_be_leaf)
        {
            sparta_assert(!TreeNode::hasWildcardCharacters(match_name),
                        "Cannot attempt to read a node with a path containing wildcard "
                        "characters. A specific node path must be used. Error in \""
                        << match_name << "\" from \"" << path << "\"");
 
            if(name_pos == std::string::npos){
                // End of the search.. No deeper
                NodeT* result = nullptr;
                NodeT* backup = nullptr; // First match (if is has no value)
                auto itr = node->getMatcherBegin();
                for(; itr != node->getMatcherEnd(); ++itr){
                    if(itr.matches(match_name)){
                        if(itr.get()->hasValue() || !must_be_leaf){
                            itr.get()->incrementReadCount();
                            if(!result){
                                result = itr.get(); // Found it
                            }
                        }else if(!backup){
                            backup = itr.get();
                        }
                    }
                }
                if(result){
                    return result;
                }
                return backup; // No match here
            }
 
            // Search deeper
            std::string immediate_child_name;
            immediate_child_name = TreeNode::getNextName(path, name_pos);
 
            if(immediate_child_name.size() == 0){
                // Cannot get parent.
                throw SpartaException("Parameter ") << path
                                                  << " is invalid because it contains an empty name (between two '.' "
                                                     "characters). Parents cannot currently be refrenced in the parameter tree";
            }
 
            NodeT* result = nullptr;
            auto itr = node->getMatcherBegin();
            for(; itr != node->getMatcherEnd(); ++itr){
                if(itr.matches(match_name)){
                    NodeT* match = recursTryGet_(itr.get(), path, immediate_child_name, name_pos, must_be_leaf);
                    if(match && (match->hasValue() || !must_be_leaf)) {
                        match->incrementReadCount();
                        if(result == nullptr){
                            result = match;
                        }
                    }
                    // Keep this match as result and continue iterating to mark all matching nodes as read
                }
            }
            return result;
        }
 
        bool recursGetIsRequired_(const Node* node,
                                  const std::string& path,
                                  const std::string& match_name,
                                  size_t name_pos,
                                  bool& found_match) const
        {
            found_match = false;
 
            if(name_pos == std::string::npos){
                // End of the search.. No deeper
                auto itr = node->getMatcherBegin();
                for(; itr != node->getMatcherEnd(); ++itr){
                    if(TreeNode::hasWildcardCharacters(match_name)
                        ? itr->getName() == match_name // Exact name match if match_name has wildcards
                        : itr.matches(match_name))     // Pattern match if match_name has no wildcards
                    {
                        found_match = true;
                        return itr.get()->getRequiredCount() > 0;
                    }
                }
 
                return false; // dummy
            }
 
            // Search deeper
            std::string immediate_child_name;
            immediate_child_name = TreeNode::getNextName(path, name_pos);
 
            if(immediate_child_name.size() == 0){
                // Cannot get parent.
                throw SpartaException("Parameter ") << path
                                                  << " is invalid because it contains an empty name (between two '.' "
                                                     "characters). Parents cannot currently be refrenced in the parameter tree";
            }
 
            auto itr = node->getMatcherBegin();
            for(; itr != node->getMatcherEnd(); ++itr){
                if(itr.matches(match_name)){
                    const bool required = recursGetIsRequired_(itr.get(), path, immediate_child_name, name_pos, found_match);
                    if(found_match){
                        return required;
                    }
                    // No match found. Keep going
                }
            }
 
            sparta_assert(found_match == false); // Should not have been set
            return false; // dummy
        }
 
        template<class NodeT>
        static uint32_t recursCountUnreadValueNodes_(NodeT* n, std::vector<NodeT*> * nodes) {
            uint32_t count = 0;
            if(n->hasValue() && (n->getReadCount() == 0)){
                count = 1;
                if(nodes){
                    nodes->push_back(n);
                }
            }
            auto itr = n->getMatcherBegin();
            for(; itr != n->getMatcherEnd(); ++itr){
                count += recursCountUnreadValueNodes_<NodeT>(itr.get(), nodes);
            }
            return count;
        }
 
        bool recursIsRead_(const Node* node,
                           const std::string& path,
                           const std::string& match_name,
                           size_t name_pos) const
        {
            sparta_assert(!TreeNode::hasWildcardCharacters(match_name),
                              "Cannot attempt to read a node with a path containing wildcard "
                              "characters. A specific node path must be used. Error in \""
                              << match_name << "\" from \"" << path << "\"");
 
            if(name_pos == std::string::npos){
                auto itr = node->getMatcherBegin();
                for(; itr != node->getMatcherEnd(); ++itr){
                    if(itr.matches(match_name)){
                        if(itr.get()->hasValue() && itr.get()->getReadCount() > 0){
                            return true;
                        }
                    }
                }
                return false;
            }
 
            // Search deeper
            std::string immediate_child_name;
            immediate_child_name = TreeNode::getNextName(path, name_pos);
            if(immediate_child_name.size() == 0){
                // Cannot get parent.
                throw SpartaException("Parameter ") << path
                                                  << " is invalid because it contains an empty name (between two '.' "
                                                     "characters). Parents cannot currently be refrenced in the parameter tree";
            }
 
            auto itr = node->getMatcherBegin();
            for(; itr != node->getMatcherEnd(); ++itr){
                if(itr.matches(match_name)){
                    bool read = recursIsRead_(itr.get(), path, immediate_child_name, name_pos);
                    if(read){
                        return true;
                    }
                }
            }
            return false;
        }
 
        std::unique_ptr<Node> root_;
 
    }; // class ParameterSet
 
    inline std::ostream& operator<<(std::ostream& o, const ParameterTree::Node& n) {
        n.dump(o);
        return o;
    }
 
    inline std::ostream& operator<<(std::ostream& o, const ParameterTree::Node* n) {
        if(!n){
            o << "<null ParameterTree::Node>";
        }else{
            o << *n;
        }
        return o;
    }
 
} // namespace sparta