include/Geant4/GUPI.hpp

0001 /*
0002 # <<BEGIN-copyright>>
0003 # Copyright 2019, Lawrence Livermore National Security, LLC.
0004 # This file is part of the gidiplus package (https://github.com/LLNL/gidiplus).
0005 # gidiplus is licensed under the MIT license (see https://opensource.org/licenses/MIT).
0006 # SPDX-License-Identifier: MIT
0007 # <<END-copyright>>
0008 */
0009
0010 #ifndef GUPI_hpp_included
0011 #define GUPI_hpp_included 1
0012
0013 #include <list>
0014 #include <map>
0015
0016 #include <LUPI_dataBuffer.hpp>
0017 #include <LUPI.hpp>
0018 #include <HAPI.hpp>
0019
0020 namespace GUPI {
0021
0022 class Entry;
0023 class Suite;
0024
0025 typedef Entry *(*GUPI_parseSuite)( Suite *a_parent, HAPI::Node const &a_node );
0026
0027 #define GUPI_documentationChars "documentation"
0028 #define GUPI_titleChars "title"
0029 #define GUPI_abstractChars "abstract"
0030 #define GUPI_bodyChars "body"
0031 #define GUPI_endfCompatibleChars "endfCompatible"
0032 #define GUPI_doiChars "doi"
0033 #define GUPI_publicationDateChars "publicationDate"
0034 #define GUPI_versionChars "version"
0035
0036 /*
0037 ============================================================
0038 ======================== WriteInfo =========================
0039 ============================================================
0040 */
0041
0042 class WriteInfo {
0043
0044     public:
0045         std::list<std::string> m_lines;
0046         std::string m_incrementalIndent;
0047         int m_valuesPerLine;
0048         std::string m_sep;
0049
0050         WriteInfo( std::string const &a_incrementalIndent = "  ", int a_valuesPerLine = 100, std::string const &a_sep = " " );
0051
0052         std::string incrementalIndent( std::string const &indent ) { return( indent + m_incrementalIndent ); }
0053         void push_back( std::string const &a_line ) { m_lines.push_back( a_line ); }
0054
0055         void addNodeStarter( std::string const &indent, std::string const &a_moniker, std::string const &a_attributes = "" ) {
0056                 m_lines.push_back( indent + "<" + a_moniker + a_attributes + ">" ); }
0057         void addNodeStarterEnder( std::string const &indent, std::string const &a_moniker, std::string const &a_attributes = "" ) {
0058                 m_lines.push_back( indent + "<" + a_moniker + a_attributes + "/>" ); }
0059         void addNodeEnder( std::string const &a_moniker ) { m_lines.back( ) += "</" + a_moniker + ">"; }
0060         std::string addAttribute( std::string const &a_name, std::string const &a_value ) const { return( " " + a_name + "=\"" + a_value + "\"" ); }
0061
0062         std::string nodeStarter( std::string const &indent, std::string const &a_moniker, std::string const &a_attributes = "" )
0063                 { return( indent + "<" + a_moniker + a_attributes + ">" ); }
0064         std::string nodeEnder( std::string const &a_moniker ) { return( "</" + a_moniker + ">" ); }
0065
0066         void print( );
0067         void clear( ) { m_lines.clear( ); }      /**< Clears the contents of *m_lines*. */
0068 };
0069
0070 /*
0071 ============================================================
0072 ========================= Ancestry =========================
0073 ============================================================
0074 */
0075 class Ancestry {
0076
0077     public:
0078             /* *********************************************************************************************************//**
0079              * Constructs and returns the key name/value for the *this* node.
0080              *
0081              * @return          The constructed key name/value.
0082              ***********************************************************************************************************/
0083         static std::string buildXLinkItemKey( std::string const &a_name, std::string const &a_key ) {
0084
0085             if( a_key.size( ) == 0 ) return( "" );
0086             return( "[@" + a_name + "='" + a_key + "']" );
0087         }
0088
0089     private:
0090         std::string m_moniker;                                  /**< The node's name (i.e., moniker). */
0091         Ancestry *m_ancestor;                                   /**< The parent node of *this*. */
0092         std::string m_attribute;                                /**< The name of the attribute in the node that uniquely identifies the node when the parent node containing other child nodes with the same moniker. */
0093
0094         Ancestry *findInAncestry2( std::size_t a_index, std::vector<std::string> const &a_segments );
0095         Ancestry const *findInAncestry2( std::size_t a_index, std::vector<std::string> const &a_segments ) const ;
0096
0097     public:
0098         Ancestry( std::string const &a_moniker, std::string const &a_attribute = "" );
0099         virtual ~Ancestry( );
0100         Ancestry &operator=( Ancestry const &a_ancestry );
0101
0102         std::string const &moniker( ) const { return( m_moniker ); }                               /**< Returns the value of the *m_moniker* member. */
0103         void setMoniker( std::string const &a_moniker ) { m_moniker = a_moniker; }          /**< Set the value of the *m_moniker* member to *a_moniker*. */
0104         Ancestry *ancestor( ) { return( m_ancestor ); }                                     /**< Returns the value of the *m_ancestor* member. */
0105         Ancestry const *ancestor( ) const { return( m_ancestor ); }                                     /**< Returns the value of the *m_ancestor* member. */
0106         void setAncestor( Ancestry *a_ancestor ) { m_ancestor = a_ancestor; }               /**< Sets the *m_ancestor* member to *a_ancestor*. */
0107         std::string attribute( ) const { return( m_attribute ); }                           /**< Returns the value of the *m_attribute* member. */
0108
0109         Ancestry *root( );
0110         Ancestry const *root( ) const ;
0111         bool isChild( Ancestry *a_instance ) { return( this == a_instance->m_ancestor ); }  /**< Returns true if *a_instance* is a child of *this*. */
0112         bool isParent( Ancestry *a_parent ) { return( this->m_ancestor == a_parent ); }     /**< Returns true if *a_instance* is the parent of *this*. */
0113         bool isRoot( ) const { return( this->m_ancestor == nullptr ); }                     /**< Returns true if *this* is the root ancestor. */
0114
0115         Ancestry *findInAncestry( std::string const &a_href );
0116         Ancestry const *findInAncestry( std::string const &a_href ) const ;
0117
0118             /* *********************************************************************************************************//**
0119              * Used to tranverse **GNDS** nodes. This method returns a pointer to a derived class' *a_item* member or nullptr if none exists.
0120              *
0121              * @param a_item    [in]    The name of the class member whose pointer is to be return.
0122              * @return                  The pointer to the class member or nullptr if class does not have a member named a_item.
0123              ***********************************************************************************************************/
0124         virtual Ancestry *findInAncestry3( std::string const &a_item ) = 0;
0125         virtual Ancestry const *findInAncestry3( std::string const &a_item ) const = 0;
0126
0127         virtual LUPI_HOST void serialize( LUPI::DataBuffer &a_buffer, LUPI::DataBuffer::Mode a_mode );
0128         virtual std::string xlinkItemKey( ) const { return( "" ); }                         /**< Returns the value of *this*'s key. */
0129         std::string toXLink( ) const ;
0130
0131         virtual void toXMLList( WriteInfo &a_writeInfo, std::string const &a_indent = "" ) const ;
0132         void printXML( ) const ;
0133 };
0134
0135 /*
0136 ============================================================
0137 ========================== Entry ===========================
0138 ============================================================
0139 */
0140 class Entry : public Ancestry {
0141
0142     private:
0143         std::string m_keyName;                                              /**< The name of the key used by the parent suite to reference *this* entry. */
0144         std::string m_keyValue;                                             /**< The key used by the parent suite to reference *this* entry. */
0145
0146     public:
0147         Entry( std::string const &a_moniker, std::string const &a_keyName, std::string const &a_keyValue );
0148         Entry( HAPI::Node const &a_node, std::string const &a_keyName );
0149         ~Entry( );
0150
0151         std::string const &keyName( ) const { return( m_keyName ); }        /**< Returns a const reference to the *m_keyName* member. */
0152         std::string const &keyValue( ) const { return( m_keyValue ); }      /**< Returns a const reference to the *m_keyValue* member. */
0153
0154         Ancestry *findInAncestry3( LUPI_maybeUnused std::string const &a_item ) { return( nullptr ); }
0155         Ancestry const *findInAncestry3( LUPI_maybeUnused std::string const &a_item ) const { return( nullptr ); }
0156         LUPI_HOST void serialize( LUPI::DataBuffer &a_buffer, LUPI::DataBuffer::Mode a_mode );
0157         std::string xlinkItemKey( ) const {
0158
0159             if( m_keyValue == "" ) return( "" );
0160             return( buildXLinkItemKey( m_keyName, m_keyValue ) );
0161         }
0162 };
0163
0164 /*
0165 ============================================================
0166 ========================== Text ============================
0167 ============================================================
0168 */
0169
0170 class Text : public Ancestry {
0171
0172     public:
0173         enum class Encoding {
0174             utf8,
0175             ascii
0176         };
0177
0178         enum class Markup {
0179             none,
0180             xml,
0181             html,
0182             latex
0183         };
0184
0185     private:
0186         std::string m_body;
0187         Encoding m_encoding;
0188         Markup m_markup;
0189         std::string m_label;
0190
0191     public:
0192         Text( HAPI::Node const &a_node );
0193         ~Text( );
0194
0195         std::string const &body( ) const { return m_body; }
0196         Encoding encoding( ) const { return m_encoding; }
0197         Markup markup( ) const { return m_markup; }
0198         std::string const &label( ) const { return m_label; }
0199
0200         Ancestry *findInAncestry3( LUPI_maybeUnused std::string const &a_item ) { return( nullptr ); }
0201         Ancestry const *findInAncestry3( LUPI_maybeUnused std::string const &a_item ) const { return( nullptr ); }
0202
0203 };
0204
0205 /*
0206 ============================================================
0207 ===================== Documentation ========================
0208 ============================================================
0209 */
0210 class Documentation : public Ancestry {
0211
0212     private:
0213         std::string m_doi;                                              /**< The name of the key used by the parent suite to reference *this* entry. */
0214         std::string m_publicationDate;                                             /**< The key used by the parent suite to reference *this* entry. */
0215         std::string m_version;
0216
0217         Text m_title;
0218         Text m_abstract;
0219         Text m_body;
0220
0221     public:
0222         // Documentation(std::string const &a_moniker, Text const &a_doi, std::string const &a_publicationDate, Text const &a_version);
0223         Documentation(HAPI::Node const &a_node);
0224         ~Documentation( );
0225
0226         std::string const &doi( ) const { return m_doi; }
0227         std::string const &publicationDate( ) const { return m_publicationDate; }
0228         std::string const &version( ) const { return m_version; }
0229
0230         Text const &title( ) const { return m_title; }
0231         Text const &abstract( ) const { return m_abstract; }
0232         Text const &body( ) const { return m_body; }
0233
0234         Ancestry *findInAncestry3( LUPI_maybeUnused std::string const &a_item ) { return( nullptr ); }
0235         Ancestry const *findInAncestry3( LUPI_maybeUnused std::string const &a_item ) const { return( nullptr ); }
0236
0237 };
0238
0239 /*
0240 ============================================================
0241 =========================== Suite ==========================
0242 ============================================================
0243 */
0244 class Suite : public Ancestry {
0245
0246     public:
0247         typedef std::vector<Entry *> Entries;                           /**< The typedef the the *m_entries* member. */
0248
0249     private:
0250         std::string m_keyName;                                          /**< The name of the key used to look up items in the suite. */
0251         mutable Entries m_entries;                                      /**< The list of nodes stored within *this*. */
0252         std::map<std::string,std::size_t> m_map;                        /**< A map of *this* node labels to their index in *m_entries*. */
0253
0254         Suite( Suite const *a_suite );                  // FIXME, should we make public or private copy constructor? Making private for now.
0255
0256     public:
0257         Suite( std::string const &a_keyName );
0258         Suite( std::string const &a_moniker, std::string const &a_keyName );
0259         Suite( HAPI::Node const &a_node, std::string const &a_keyName, GUPI_parseSuite a_parseSuite );
0260         ~Suite( );
0261
0262         std::string const &keyName( ) const { return( m_keyName ); }                        /**< Returns a const reference to the *m_keyName* member. */
0263         std::size_t size( ) const { return( m_entries.size( ) ); }                            /**< Returns the number of node contained by *this*. */
0264
0265         std::size_t operator[]( std::string const &a_label ) const ;
0266         typedef Entries::iterator iterator;
0267         typedef Entries::const_iterator const_iterator;
0268         iterator begin( ) { return m_entries.begin( ); }                                      /**< The C++ begin iterator for *this*. */
0269         const_iterator begin( ) const { return m_entries.begin( ); }                          /**< The C++ const begin iterator for *this*. */
0270         iterator end( ) { return m_entries.end( ); }                                          /**< The C++ end iterator for *this*. */
0271         const_iterator end( ) const { return m_entries.end( ); }                              /**< The C++ const end iterator for *this*. */
0272
0273         template<typename T> T       *get( std::size_t a_Index );
0274         template<typename T> T const *get( std::size_t a_Index ) const ;
0275         template<typename T> T       *get( std::string const &a_label );
0276         template<typename T> T const *get( std::string const &a_label ) const ;
0277
0278         void parse( HAPI::Node const &a_node, GUPI_parseSuite a_parseSuite );
0279         void add( Entry *a_entry );
0280         iterator find( std::string const &a_label );
0281         const_iterator find( std::string const &a_label ) const ;
0282         bool has( std::string const &a_label ) const { return( find( a_label ) != m_entries.end( ) ); }
0283
0284         Ancestry *findInAncestry3( std::string const &a_item );
0285         Ancestry const *findInAncestry3( std::string const &a_item ) const ;
0286         std::vector<iterator> findAllOfMoniker( std::string const &a_moniker ) ;
0287         std::vector<const_iterator> findAllOfMoniker( std::string const &a_moniker ) const ;
0288
0289         void toXMLList( WriteInfo &a_writeInfo, std::string const &a_indent = "" ) const ;
0290         void printEntryLabels( std::string const &a_header ) const ;
0291 };
0292
0293 /* *********************************************************************************************************//**
0294  * Returns the node at index *a_index*.
0295  *
0296  * @param a_index               [in]    The index of the node to return.
0297  *
0298  * @return                              The node at index *a_index*.
0299  ***********************************************************************************************************/
0300
0301 template<typename T> T *Suite::get( std::size_t a_index ) {
0302
0303     Entry *entry = m_entries[a_index];
0304     T *object = dynamic_cast<T *>( entry );
0305
0306     if( object == nullptr ) throw LUPI::Exception( "GIDI::Suite::get( std::size_t ): invalid cast" );
0307
0308     return( object );
0309 }
0310
0311 /* *********************************************************************************************************//**
0312  * Returns the node at index *a_index*.
0313  *
0314  * @param a_index               [in]    The index of the node to return.
0315  *
0316  * @return                              The node at index *a_index*.
0317  ***********************************************************************************************************/
0318
0319 template<typename T> T const *Suite::get( std::size_t a_index ) const {
0320
0321     Entry *entry = m_entries[a_index];
0322     T *object = dynamic_cast<T *>( entry );
0323
0324     if( object == nullptr ) throw LUPI::Exception( "GIDI::Suite::get( std::size_t ): invalid cast" );
0325
0326     return( object );
0327 }
0328
0329 /* *********************************************************************************************************//**
0330  * Returns the node with label *a_label*.
0331  *
0332  * @param a_label               [in]    The label of the node to return.
0333  *
0334  * @return                              The node with label *a_label*.
0335  ***********************************************************************************************************/
0336
0337 template<typename T> T *Suite::get( std::string const &a_label ) {
0338
0339     auto index = (*this)[a_label];
0340     Entry *entry = m_entries[index];
0341     T *object = dynamic_cast<T *>( entry );
0342
0343     if( object == nullptr ) throw LUPI::Exception( "GIDI::Suite::get( std::string const & ): invalid cast" );
0344
0345     return( object );
0346 }
0347
0348 /* *********************************************************************************************************//**
0349  * Returns the node with label *a_label*.
0350  *
0351  * @param a_label               [in]    The label of the node to return.
0352  *
0353  * @return                              The node with label *a_label*.
0354  ***********************************************************************************************************/
0355
0356 template<typename T> T const *Suite::get( std::string const &a_label ) const {
0357
0358     auto index = (*this)[a_label];
0359     Entry *entry = m_entries[index];
0360     T *object = dynamic_cast<T *>( entry );
0361
0362     if( object == nullptr ) throw LUPI::Exception( "GIDI::Suite::get( std::string const & ): invalid cast" );
0363
0364     return( object );
0365 }
0366
0367 }               // End of namespace GUPI.
0368
0369 #endif          // GUPI_hpp_included