GraphTreeObject.h

/******************************************************************************
* Copyright (c) ATTX LLC 2024. All Rights Reserved.
*
* This software and associated documentation (the "Software") are the 
* proprietary and confidential information of ATTX, LLC. The Software is 
* furnished under a license agreement between ATTX and the user organization 
* and may be used or copied only in accordance with the terms of the agreement.
* Refer to 'license/attx_license.adoc' for standard license terms.
*
* EXPORT CONTROL NOTICE: THIS SOFTWARE MAY INCLUDE CONTENT CONTROLLED UNDER THE
* INTERNATIONAL TRAFFIC IN ARMS REGULATIONS (ITAR) OR THE EXPORT ADMINISTRATION 
* REGULATIONS (EAR99). No part of the Software may be used, reproduced, or 
* transmitted in any form or by any means, for any purpose, without the express 
* written permission of ATTX, LLC.
******************************************************************************/
/*
Graph tree header file
 
Author: Alex Reynolds
*/
#ifndef GRAPH_TREE_H
#define GRAPH_TREE_H
 
#include <vector>
#include <string>
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
 
#include "core/clockwerkerrors.h"
 
namespace clockwerk {
 
    /// This enumeration defines the possible derivations of the graph tree object
    /// which may be used to store helpful information on it. It's messy but it works
    /// well. Derivations may be added here as they are developed. If not, they will
    /// default to not defined.
    enum graph_tree_types_e : unsigned char {
        BASE_GRAPH_TREE,
        DATAIO,
        TASK,
        EXECUTIVE,
        FRAME,
        BODY,
        NODE
    };
 
    const std::string DELIMETER = ".";
    const std::string DEFAULT_NAME = "_";
 
    /// @brief   Base class for object organization
    /// 
    /// This file defines a base class for data organization into a format
    /// we're calling here a "graph tree". The graph tree is set up to connect
    /// a single parent to any number of children, which may be done upon construction
    /// or at runtime. Graph trees allow connections between any number of inherited
    /// objects and their parents/children, allowing for recursive math and search
    /// functionality. In essence, the class is a doubly linked list with multiple
    /// children and search functionality. 
    /// 
    ///                         Parent
    ///                            |
    ///         ---------------------------------------
    ///         |           |             |           |
    ///      Child 1      Child 2       Child 3     Child 4
    /// 
    /// Also, note that trees objects are entirely independent of their position in
    /// that tree, so a child can be treated as if it were root in the case where
    /// a local search should be performed.
    /// 
    /// String Address Functionality
    /// String addressing is one of the most critical functions of the graph tree.
    /// It allows for easy access to data, in addition to search and write functions. 
    /// String addresses are constructed from the names of individual objects on the 
    /// tree, separated by a delimiter defined in this file (a period by default). So
    /// a standard string address could look like:
    /// 
    /// .firstObj.secondObj.thirdObj.otherThing
    /// 
    /// which would indicate four levels of heirarchy on the tree, with otherThing
    /// being the furthest down on the tree. The object at the location otherThing
    /// can be accessed by requesting the string address.
    /// 
    /// Graph tree has the following restrictions driven by data size:
    /// Number of children -- restricted by variable size and uint8 size
    /// Number of descendants -- restricted by uint16 size
    class GraphTreeObject {
    public:
        /// @brief   Constructor with name for graph tree object
        GraphTreeObject(const std::string &name = "");
 
        /// Destructor
        virtual ~GraphTreeObject() {}
 
        /// Functions to get object's parent/children
        GraphTreeObject* parent() {return _parent;}
        std::vector<GraphTreeObject*>& children() {return _children;}
 
        /// @brief   Function to assign the node's parent via pointer
        /// @param   new_parent  The new parent to assign the node to
        /// @return  Error code corresponding to success/failure
        /// @note    This function is the only method to ADD or REMOVE a node
        ///          from a tree. To add, pass the address to a GraphTreeObject
        ///          to this function. To remove, pass a nullptr. Note that
        ///          parents for objects on an existing tree can be reassigned
        int parent(GraphTreeObject* new_parent);
 
        /// @brief   Function to assign the node's parent via reference
        /// @param   new_parent  The new parent to assign the node to
        /// @return  Error code corresponding to success/failure
        /// @note    This function is the only method to ADD or REMOVE a node
        ///          from a tree. To add, pass the address to a GraphTreeObject
        ///          to this function. To remove, pass a nullptr. Note that
        ///          parents for objects on an existing tree can be reassigned
        int parent(GraphTreeObject& new_parent);
 
        /// Getters for number of children and descendants
        unsigned int nChildren() {return _num_children;}
        unsigned int nDescendants() {return _num_descendants;}
 
        /// @brief   Getter and setter for object name
        std::string name() const {return _name;}
        int name(const std::string &new_name);
 
        /// @brief   Getter for the object rank
        int rank() {return _rank;}
 
        /// @brief Function to indicate type -- -1 by default unless implemented downstream
        /// @return Int indicating frame type -- unimplemented always -1
        virtual int type() {return _graph_tree_type;}
 
        /// @brief   Getter for object logability flag -- note no setter because should
        ///          only be set by this or a derived class in its definition
        bool loggable() {return _loggable;}
 
        /// @brief   Getter for object's string address
        /// @return  Returns the string address for the object
        std::string address();
 
        /// @brief   Function to search through the graph tree by string address
        /// @param   address     `The address or address chunk to search for
        /// @return  A vector of string addresses meeting the criteria specified by address
        std::vector<std::string> search(const std::string &address);
 
        /// @brief   Function to get an object from the graph tree by string address
        /// @param   address     The exact string address to access the variable with
        /// @return  Pointer to the graph tree object at the address, or nullptr if 
        ///          address is not valid or returns 
        GraphTreeObject* getByAddress(const std::string &address);
 
        /// @brief   Function to dump the graph node, optionally including descendents
        /// @param   recursive   Parameter indicating whether to dump only one node (default/false)
        ///                      or the entire tree (true)
        /// @note    Recursive dumps the whole tree... be careful what you wish for
        void dump(bool recursive=false);
 
        /// @brief   Function to return all info associated with a given graph node
        void graphNodeInfo();
 
        /// @brief   Function to recurse through graph tree and print all node info
        /// @return  String containing all recursive graph node information in tab cascade format
        void recurseGraphNodeInfo(unsigned int counter);
 
        /// @brief   Function to pass headers for this object to the logger
        /// @param   logger  Pointer to logger
        /// @return  Error code corresponding to success/failure
        virtual int header(void* logger) {return WARN_NOT_LOGGABLE;}
 
        virtual std::vector<std::string> header_info() const {return std::vector<std::string>();}
 
        /// @brief   Function to find all loggable parameters in this node and its children
        /// @param   matches     Expandable vector to hold all matches in the tree
        void findLoggable(std::vector<GraphTreeObject*> &matches);
 
        /// @brief   Function to log data to a logger
        /// @param   logger  Pointer to logger
        /// @return  Error code corresponding to success/failure
        virtual int log(void* logger) {return WARN_NOT_LOGGABLE;}
 
        /// @brief   Function to lock the graph tree object and its children to changes
        /// @param   recursive   Flag to indicate whether lock should be recursive
        void lock(bool recursive = true);
 
        /// @brief   Function to unlock the graph tree and its children for changes
        /// @param   recursive   Flag to indicate whether unlock should be recursive
        void unlock(bool recursive = true);
 
        /// @brief   Function to return whether graph tree object is locked
        bool locked() {return _locked;}
 
    protected:
        /// @brief   Function to recursively re-calculate the number of descendants
        ///          of a given node on the tree
        void recalculateDescendants();
 
        /// @brief   Function to recursively re-calculate the rank of a given node on the tree
        void recalculateRank();
 
        /// @brief   Function to decompose a string into a series of substrings via indexing
        /// @param   address     The address to be decomposed
        /// @return  A vector of strings containing each delimeter-separated substring
        std::vector<std::string> decomposeAddress(std::string address);
 
        /// @brief   Function to find all addresses mathcing the set of substrings
        /// @parem   subaddresses    A vector of subaddresses to match
        /// @param   num_subaddresses    The number of subaddresses to match
        /// @param   index   The index of subaddresses to search in
        /// @param   match_found     Variable indicating whether a match was found higher in the tree
        /// @param   matches     Implicit return of all matches to the specified address
        void findMatches(const std::vector<std::string> &subaddresses, const unsigned int &num_subaddresses,
                        unsigned int index, bool match_found, std::vector<GraphTreeObject*> &matches);
 
        /// @brief   Function to search through the graph tree by string address
        /// @param   address     `The address or address chunk to search for
        /// @return  A vector of objects addresses meeting the criteria specified by address
        std::vector<GraphTreeObject*> searchNodes(const std::string &address);
 
        /// @brief   Function to add a child to the graph tree object
        /// @param   child   A pointer to the graph tree object to add to the tree
        /// @return  An error code corresponding to success/failure 
        int addChild(GraphTreeObject* child);
 
        /// @brief   Function to remove a child from the graph node's children
        /// @param   child   The child to remove
        /// @return  Success/fail error code based on whether the child is present
        int removeChild(GraphTreeObject* child);
 
        /// Pointer to the object's parent -- should be null if the object is the root.
        /// Is set to null by default
        GraphTreeObject* _parent = nullptr;
 
        /// Pointers to the object's children -- automatically set to an empty vector,
        /// and can be increased to any size
        std::vector<GraphTreeObject*> _children;
 
        /// String name for object
        std::string _name = DEFAULT_NAME;
 
        /// Total number of descendants (includes children of children) of the tree,
        /// again not including the tree itself
        uint16_t _num_descendants = 0;
 
        /// Number of direct children of the tree (not including the tree itself)
        uint8_t _num_children = 0;
 
        /// Rank for how far down on the graph tree the object is -- starts at zero
        /// and maxes out at 256 via variable size
        uint8_t _rank = 0;
 
        /// Variable to store graph tree object type
        uint8_t _graph_tree_type = BASE_GRAPH_TREE;
 
        /// Variable to lock the graph tree object and prevent structural updates
        bool _locked = false;
 
        /// Variable to indicate whether the selected object is loggable. Set to false by default
        bool _loggable = false;
    };
 
}
 
#endif