Show
Ignore:
Timestamp:
06/22/09 13:10:28 (15 years ago)
Author:
mido
Message:

1) UI_File renamed to UIFile
2) part UI's documentation
3) stat/mixtures.h renamed to stat/emix.h and related changes applied

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • library/bdm/base/user_info.h

    r392 r394  
    1717using namespace libconfig; 
    1818 
     19namespace bdm 
     20{ 
     21         
     22/*! 
     23  \def UIREGISTER(class_name) 
     24  Macro for registration of class into map of UserInfos -- registered class is scriptable  
     25 
     26  TODO napsat i to, ze UIREG musi byt v hacku.. 
     27*/ 
    1928#ifndef BDMLIB  
    20 //!Macro for registration of classes into map of UserInfos -- registered class is scriptable  
    21 #define UIREGISTER(class_name) template<> const Particular_UI<class_name>& Particular_UI<class_name>::ui = Particular_UI<class_name>(#class_name)  
     29#define UIREGISTER(class_name) template<> const ParticularUI<class_name>& ParticularUI<class_name>::ui = ParticularUI<class_name>(#class_name)  
    2230#else 
    2331#define UIREGISTER(class_name) 
    2432#endif 
    2533 
    26 #define ASSERT_UITYPE(S,Type) it_assert_debug(S.getType()==Setting::Type, string("Wrong setting type, see input path \"")+string(S.getPath())+string("\"")) 
    27  
    28 namespace bdm 
    29 { 
    30          
    31         //! exception used in UI::build if it fails it can be caught and handled - see merger_mex.h 
     34//!  macro assertting that the setting SET is of the SettingType TYPE 
     35#define ASSERT_UITYPE(SET,TYPE) it_assert_debug(SET.getType()==Setting::TYPE, string("Wrong setting type, see input path \"")+string(SET.getPath())+string("\"")) 
     36 
     37//! exception used in UI::build if it fails it can be caught and handled - see merger_mex.h 
    3238class UIbuildException : public std::invalid_argument { 
    3339        public: 
    3440                UIbuildException() : std::invalid_argument("class name") { } 
    3541}; 
    36          
    37 class UI_File : public Config 
    38 { 
    39 private: 
    40         const string file_name; 
    41  
    42 public: 
    43         //! create empty object prepared to store Settings 
    44         UI_File(); 
    45  
    46         //! creates object and fills it from a file 
    47         UI_File( const string &file_name ); 
    48  
    49         //! save UserInfo to the file  
    50         void save(const string &file_name); 
    51  
    52         operator Setting&(); 
    53 }; 
    5442 
    5543/*! 
    56 @brief This class serves to load and/or save DOMElements into/from files 
    57 stored on a hard-disk. 
    58  
    59 Firstly, you associate new RootElement instance with some filename during a time of its  
    60 construtcion. Then, you save some object into the new RootElement instance, 
    61 and save it into the file this way: 
     44@brief This class serves to load and/or save user-infos into/from  
     45configuration files stored on a hard-disk. 
     46 
     47Firstly, save some user-infos into the new UIFile instance. Then,  
     48call the save method with a filename as its only argument: 
     49 
    6250\code 
    6351        CAudi audi; 
    64         RootElement root("cars.xml"); 
    65         UserInfo::save( audi, root, "TT"); 
    66         root.save(); 
     52        UIFile file; 
     53        UI::save( audi, file, "TT"); 
     54        file.save("cars.cfg"); 
    6755\endcode 
    6856 
    69 In the other way round, when loading object from a XML file, the appropriate code looks like this: 
     57In the other way round, when loading object from a configuration file,  
     58the appropriate code looks like this: 
     59 
    7060\code 
    71         RootElement root("cars.xml"); 
    72         root.load(); 
    73         UserInfo::build<T>(root,"TT"); 
     61        UIFile file("cars.cfg"); 
     62        CAudi *audi = UI::build<CAudi>(file,"TT"); 
    7463\endcode 
    7564*/ 
     65class UIFile : public Config 
     66{ 
     67public: 
     68        //! create empty file instance prepared to store Settings 
     69        UIFile(); 
     70 
     71        //! creates instance and fills it from the configuration file file_name 
     72        UIFile( const string &file_name ); 
     73 
     74        //! save all the stored Settings into the configuration file file_name 
     75        void save(const string &file_name); 
     76 
     77        //! this operator allows the ability of substituting Setting parameter by UIFile instance 
     78        operator Setting&(); 
     79}; 
     80 
    7681 
    7782 
    7883/*! 
    79 @brief UserInfo is an abstract is for internal purposes only. Use CompoundUserInfo<T> or Particular_UI<T> instead. 
    80 The raison d'etre of this class is to allow pointers to its templated descendants.  
    81  
    82 Also, the main functions of the whole UserInfo library are included within this class, see 
    83 static methods 'build' and 'save'. 
    84  
     84@brief UI is an abstract class and it is intended for internal purposes only 
     85 
     86This class exists mainly to allow pointers to its templated descendant ParticularUI<T>. Next,  
     87it collects all the auxiliary functions useful to prepare some concret user-infos, see static  
     88methods 'build', 'get' and 'save'.  
    8589*/ 
    8690class UI  
    8791{ 
    8892private: 
    89         //! static class encalupsating map of names to related UserInfos 
     93        //! Atatic class encalupsating two maps, one mapping names to UI instances and the other mapping type_infos to class names 
    9094        //!  
    91         //! The key property of this class is that it initilaized the internal map immediately 
    92         //! when it is used for a first time. 
    93         class Mapped_UI 
     95        //! The key property of this class is that it initilaize the internal map immediately 
     96        //! when it is used for a first time. Therefore, we do not have to care about the  
     97        //! order of calls to UIREGISTER macro, which operates with both these mappings. 
     98        class MappedUI 
    9499        { 
    95100        private: 
    96                 //! Type definition of mapping which transforms type names to the related user infors 
    97                 typedef map< const string, const UI* const > String_To_UI_Map; 
    98  
    99                 //! Type definition of mapping which transforms type names to the related user infors 
    100                 typedef map< const type_info * const, const string > Type_Info_To_String_Map; 
    101  
    102                 //! immediately initialized instance of type String_To_UI_Map 
    103                 static String_To_UI_Map& mapped_strings(); 
    104  
    105                 //! immediately initialized instance of type String_To_UI_Map 
    106                 static Type_Info_To_String_Map& mapped_type_infos(); 
     101                //! Type definition of mapping which transforms class names to the related UI instances 
     102                typedef map< const string, const UI* const > StringToUIMap; 
     103 
     104                //! Type definition of mapping which transforms RTTI type_infos to the related class names 
     105                typedef map< const type_info * const, const string > TypeInfoToStringMap; 
     106 
     107                //! immediately initialized instance of type StringToUIMap 
     108                static StringToUIMap& mapped_strings(); 
     109 
     110                //! immediately initialized instance of type TypeInfoToStringMap 
     111                static TypeInfoToStringMap& mapped_type_infos(); 
     112 
     113                //! method for reporting a error when an attempt to operate with an unregistered class occures 
     114                static void unregistered_class_error( const string &unregistered_class_name ); 
    107115 
    108116        public: 
    … …  
    110118                static void add_class( const string &class_name, const type_info * const class_type_info, const UI* const ui ); 
    111119 
    112                 //! search for an userinfo related to the passed key within the internal map 
     120                //! search for an userinfo related to the passed class name within the internal map 
    113121                static const UI& retrieve_ui( const string &class_name ); 
    114122 
    115                 //! search for an userinfo related to the passed key within the internal map 
     123                //! search for an class name related to the passed type_info within the internal map 
    116124                static const string& retrieve_class_name( const type_info* const class_type_info ); 
    117125        }; 
    118126 
    119  
    120  
    121  
    122         //! internal method assembling a typeless instance from components obtained by the 'AssemblyComponentsFromSetting()' method 
     127        //! Method assembling a typeless instance, it is implemented in descendant class ParticularUI<T> 
    123128        virtual root* new_instance() const = 0; 
    124129         
    125         //! This methods tries to save an instance of type T (or some of its descendant types) 
    126         //! and build DOM tree accordingly. Then, it creates a new DOMNode named according class_name 
    127         //! and connecti it to the passed Setting as a new child node. 
     130        //! Method switching from the \a element to its child Setting according the passed \a index, it also does all the necessary error-checking  
    128131        static const Setting& to_child_setting( const Setting &element, const int index ); 
    129132 
     133        //! Method switching from the \a element to its child Setting according the passed \a name, it also does all the necessary error-checking  
    130134        static const Setting& to_child_setting( const Setting &element, const string &name ); 
    131135 
    132  
    133         //! \name Matematical Operations TODO 
    134         //!@{ 
    135  
    136         //! This methods tries to build a new double matrix  
     136        //! This methods converts a Setting into a matrix  
    137137        static void from_setting( mat& matrix, const Setting &element );         
    138         //! This methods tries to build a new integer vector 
     138        //! This methods converts a Setting into an integer vector 
    139139        static void from_setting( ivec &vector, const Setting &element ); 
    140         // jednak kvuli pretypovani, apak taky proto, ze na string nefunguje link_expander.. 
     140        //! This methods converts a Setting into a string 
    141141        static void from_setting( string &str, const Setting &element ); 
    142         //! This methods tries to build a new templated array  
    143  
     142        //! This methods converts a Setting into a real vector 
    144143        static void from_setting( vec &vector, const Setting &element ); 
    145  
     144        //! This methods converts a Setting into a integer scalar  
     145        static void from_setting( int &integer, const Setting &element ); 
     146        //! This methods converts a Setting into a real scalar  
     147        static void from_setting( double &real, const Setting &element ); 
     148        //! This methods converts a Setting into a class T descendant 
    146149        template<class T> static void from_setting( T* &instance, const Setting &element ) 
    147150        {                        
    … …  
    155158                        ui_error( "the obligatory ""class"" identifier is missing", link.result ); 
    156159         
    157                 // and finally we find a UserInfo related to this type 
    158                 const UI& related_UI = Mapped_UI::retrieve_ui( class_name ); 
     160                // then we find a user-info related to this type 
     161                const UI& related_UI = MappedUI::retrieve_ui( class_name ); 
    159162                 
    160163                root* typeless_instance = related_UI.new_instance(); 
    … …  
    168171//              catch(...) 
    169172//              { 
     173                        // TODO pouzit ui_error?  
    170174//                      it_error ( "UI error: class " + class_name + " is not a descendant of the desired output class. Try to call the UI::build function with a different type parameter." ); 
    171175//              } 
    … …  
    177181                catch(SettingException xcptn) 
    178182                { 
     183                        // TODO pouzit ui_error?  
    179184                        it_error ( "UI error: the method " + class_name + ".from_setting(Setting&) has thrown an exception when parsing the setting " + xcptn.getPath() + ". Try to correct this method." ); 
    180185                } 
    181186        }        
    182187 
    183  
    184         //! This methods tries to build a new templated array ,  
    185         // efektivne jen pro vect, mat a string, pro dalsi je nutne pridat from_setting metodu.. ale to asi necceme 
     188        //! This methods converts a Setting into a new templated array ,  
     189        // TODO efektivne jen pro vect, mat a string, pro dalsi je nutne pridat from_setting metodu.. ale to asi necceme 
    186190        template<class T> static void from_setting( Array<T> &array_to_load, const Setting &element ) 
    187191        { 
    … …  
    198202        } 
    199203 
    200           //!@} 
    201  
    202  
     204        //! Method for reporting user-info errors related to some concrete Setting 
    203205        static void ui_error( string message, const Setting &element ); 
    204206 
    205207protected: 
    206         //! default constructor  
     208        //! Default constructor for internal use only, see \sa ParticularUI<T> 
    207209        UI( const string& class_name, const type_info * const class_type_info )  
    208210        {        
    209                 Mapped_UI::add_class( class_name, class_type_info, this ); 
    210         } 
    211  
    212         //! Virtual destructor for future use; 
    213         virtual ~UI(){}; 
     211                MappedUI::add_class( class_name, class_type_info, this ); 
     212        } 
    214213 
    215214public:  
    216         //! This methods tries to build a new instance of type T (or some of its descendant types) 
    217         //! according to a data stored in a DOMNode named class_name within a child nodes of the passed element. 
    218         //! If an error occurs, it returns a NULL pointer. 
    219  
    220         // vraci true, kdyz to byl platny link, jinak false.. v pripade chyby konci it_errorem.. 
    221         // do elementu vrati setting prislusny po rozbaleni linku, jinak ponecha beze zmeny 
     215 
     216        /*! 
     217        @brief This class serves to expand links used in configuration file.  
     218 
     219        TODO - napsat co dela, a hlavne proc je to takhle implementovany.. otevreny soubor! 
     220 
     221        ABSOLUTE PATH..  
     222 
     223        Firstly, save some user-infos into the new UIFile instance. Then,  
     224        call the save method with a filename as its only argument: 
     225 
     226        \code 
     227                CAudi audi; 
     228                UIFile file; 
     229                UI::save( audi, file, "TT"); 
     230                file.save("cars.cfg"); 
     231        \endcode 
     232 
     233        */ 
    222234        class SettingResolver    
    223235        { 
    224236        private: 
    225                 UI_File *file; 
    226  
    227                 const Setting &initialize_reference( UI_File* &file, const Setting &potential_link); 
     237                //! If necessary, this pointer stores an addres of an opened UIFile, else it equals NULL 
     238                UIFile *file; 
     239 
     240                //! This method initialize result reference, i.e., it executes the main code of SettingResolver class 
     241                //! 
     242                //! This code could be also located directly in constructor. The only reason why we made this  
     243                //! method is the keyword 'const' within the declaration of result reference (TODO funguje odkaz?). Such a reference 
     244                //! have to be intialized before any other constructor command, exactly in the way it is implemented now. 
     245                const Setting &initialize_reference( UIFile* &file, const Setting &potential_link); 
    228246 
    229247        public: 
     248                //! Reference to a resolved link or to the original Setting in the case it does not contain a link 
    230249                const Setting &result; 
    231250 
     251                //! If potential_link contains a link to some other setting, it is resolved here. Anyway, the Setting reference result is prepared for use. 
    232252                SettingResolver( const Setting &potential_link ); 
    233253                 
     254                //! An opened UIFile file is closed here if necessary. 
    234255                ~SettingResolver();              
    235256        }; 
    236257 
    237  
    238  
    239         //! Prototype of a UI builder. Return value is by the second argument since it type checking via \c dynamic_cast. 
     258        //TODO 
     259        //! \name Initialization of bdm::root descendant classes according the values stored in a Setting variable 
     260        //!@{ 
     261        //! Return value is by the second argument since it type checking via \c dynamic_cast. 
    240262        template<class T> static T* build( const Setting &element, const int index ) 
    241263        { 
    … …  
    258280                return instance; 
    259281        } 
    260  
     282        //!@} 
     283 
     284        //! \name Initialization of structures according the values stored in a Setting variable - TODO VYCET?! 
     285        //!@{ 
    261286        //! This methods tries to build a new double matrix  
    262287        template<class T> static void get( T &instance, const Setting &element, const string &name ) 
    … …  
    272297 
    273298        //! This methods tries to build a new double matrix  
     299        template<class T> static void get( T &instance, const Setting &element  ) 
     300        { 
     301                from_setting( instance, element ); 
     302        } 
     303 
     304        //! This methods tries to build a new double matrix  
    274305        template<class T> static void get( Array<T> &array_to_load, const Setting &element, const string &name ) 
    275306        { 
    … …  
    282313                from_setting( array_to_load, to_child_setting( element, index ) ); 
    283314        } 
     315 
     316        //! This methods tries to build a new double matrix  
     317        template<class T> static void get( Array<T> &array_to_load, const Setting &element  ) 
     318        { 
     319                from_setting( array_to_load, element ); 
     320        } 
     321        //!@} 
    284322 
    285323        template< class T> static void save( const T * const instance, Setting &element, const string &name = "") 
    … …  
    288326                                                                         : element.add( name, Setting::TypeGroup );              
    289327 
    290                 const string &class_name = Mapped_UI::retrieve_class_name( &typeid(*instance) ); 
     328                const string &class_name = MappedUI::retrieve_class_name( &typeid(*instance) ); 
    291329                         
    292330                // add attribute "class"  
    … …  
    321359        static void save( const ivec &vec, Setting &element, const string &name = "" ); 
    322360         
    323         static void save( const vec &vector, Setting &element, const string &name); 
    324  
    325         private:  
     361        static void save( const vec &vector, Setting &element, const string &name = "" ); 
    326362        //! This methods tries to save a double vec  
    327         static void save( const string &str, Setting &element);  
     363        static void save( const string &str, Setting &element, const string &name = "" ); 
     364 
     365        static void save( const int &integer, Setting &element, const string &name = "" ); 
     366 
     367        static void save( const double &real, Setting &element, const string &name = "" );       
    328368 
    329369}; 
    … …  
    335375own userinfo class prepared). 
    336376*/ 
    337 template<typename T> class Particular_UI : private UI 
     377template<typename T> class ParticularUI : private UI 
    338378{ 
    339379        public: 
    340380 
    341381        //! default constructor, which is intentionally declared as private 
    342         Particular_UI<T>( const string &class_name) : UI( class_name, &typeid(T) )  
     382        ParticularUI<T>( const string &class_name) : UI( class_name, &typeid(T) )  
    343383        {       cout << class_name << endl; 
    344384        }; 
    … …  
    346386        //! the only instance of this class (each type T has its own instance) 
    347387        //! which is used as a factory for processing related UI 
    348         static const Particular_UI<T>& ui;       
     388        static const ParticularUI<T>& ui;        
    349389 
    350390        root* new_instance() const