Ignore:
Timestamp:
01/14/18 11:25:02 (7 years ago)
Author:
Maciej Komosinski
Message:

Code formatting

File:
1 edited

Legend:

Unmodified
Added
Removed

  • cpp/frams/param/multiparamload.h

    r535 r721  
    11// This file is a part of Framsticks SDK.  http://www.framsticks.com/
    2 // Copyright (C) 1999-2015  Maciej Komosinski and Szymon Ulatowski.
     2// Copyright (C) 1999-2018  Maciej Komosinski and Szymon Ulatowski.
    33// See LICENSE.txt for details.
    44
    … …  
    1414        http://www.framsticks.com/common/formatspec.html
    1515        The loader can be configured to recognize multiple object types from object headers
    16     and automatically call ParamInterface::load for the matching class.
    17    
    18     Your code should repeatedly call MultiParamLoader::go() method and check the status after each call, until the end of file.
    19     The loader pauses before and/or after each object giving you a chance to perform your application-specific actions (see MultiParamLoader::breakOn()).
    20     If your application does not require any special actions, then the simple MultiParamLoader:run() can be used.
    21     The word "record" (and "record type") used in this description refer to the textual form of a serialized object - this is to avoid confusion with 'live' objects passed to the loader methods. "Record type" can be the same as the class name, but it does not have to be the same. For example, the most common record type for storing the Genotype object is called "org" (think: organism) instead of "Genotype".
     16        and automatically call ParamInterface::load for the matching class.
    2217
    23     Typical usage scenarios:
    24     1. Loading a file that contains at most one object of any given class:
    25     - declare the object class(es) - MultiParamLoader::addClass()
    26     - call MultiParamLoader::run()
    27     - and that's all, the records from the file will be loaded into the corresponding objects
     18        Your code should repeatedly call MultiParamLoader::go() method and check the status after each call, until the end of file.
     19        The loader pauses before and/or after each object giving you a chance to perform your application-specific actions (see MultiParamLoader::breakOn()).
     20        If your application does not require any special actions, then the simple MultiParamLoader:run() can be used.
     21        The word "record" (and "record type") used in this description refer to the textual form of a serialized object - this is to avoid confusion with 'live' objects passed to the loader methods. "Record type" can be the same as the class name, but it does not have to be the same. For example, the most common record type for storing the Genotype object is called "org" (think: organism) instead of "Genotype".
    2822
    29     2. Loading multiple objects and adding them to a list (see loadtest.cpp for a sample code that demonstrates this scenario)
    30     - declare the object class giving the empty "template" object - MultiParamLoader::addClass()
    31     - set breakOn(AfterObject)
    32     - call MultiParamLoader::go() in a loop
    33     - the returned status will be equal to AfterObject each time an object is loaded. One can detect this condition and create the real object from our template object
    34     (alternatively, one could breakOn(BeforeObject) and use MultiParamLoader::loadObjectNow(ParamInterface*) to load the incoming object into a newly created object).   
    35  */
     23        Typical usage scenarios:
     24        1. Loading a file that contains at most one object of any given class:
     25        - declare the object class(es) - MultiParamLoader::addClass()
     26        - call MultiParamLoader::run()
     27        - and that's all, the records from the file will be loaded into the corresponding objects
     28
     29        2. Loading multiple objects and adding them to a list (see loadtest.cpp for a sample code that demonstrates this scenario)
     30        - declare the object class giving the empty "template" object - MultiParamLoader::addClass()
     31        - set breakOn(AfterObject)
     32        - call MultiParamLoader::go() in a loop
     33        - the returned status will be equal to AfterObject each time an object is loaded. One can detect this condition and create the real object from our template object
     34        (alternatively, one could breakOn(BeforeObject) and use MultiParamLoader::loadObjectNow(ParamInterface*) to load the incoming object into a newly created object).
     35        */
    3636class MultiParamLoader
    3737{
    38 VirtFILE *file;
    39 SListTempl<VirtFILE*> filestack;
    40 char ownfile;
    41 PtrListTempl<ExtObject*> objects;
    42 int status;
    43 SString lasterror, lastcomment, lastunknown;
    44 ExtObject lastobject;
    45 int breakcond;
    46 Param emptyparam;
    47 bool aborting;
    48 int linenum;
     38        VirtFILE *file;
     39        SListTempl<VirtFILE*> filestack;
     40        char ownfile;
     41        PtrListTempl<ExtObject*> objects;
     42        int status;
     43        SString lasterror, lastcomment, lastunknown;
     44        ExtObject lastobject;
     45        int breakcond;
     46        Param emptyparam;
     47        bool aborting;
     48        int linenum;
    4949
    50 void init();
     50        void init();
    5151
    52 int maybeBreak(int cond)
    53 { status=cond; return breakcond & cond; }
     52        int maybeBreak(int cond)
     53        {
     54                status = cond;
     55                return breakcond & cond;
     56        }
    5457
    55 VirtFILE* popstack();
    56 void clearstack();
     58        VirtFILE* popstack();
     59        void clearstack();
    5760
    58   public:
    59 MultiParamLoader() {init();}
    60 MultiParamLoader(VirtFILE *f) {init(); load(f);}
    61 MultiParamLoader(const char* filename) {init(); load(filename);}
     61public:
     62        MultiParamLoader() { init(); }
     63        MultiParamLoader(VirtFILE *f) { init(); load(f); }
     64        MultiParamLoader(const char* filename) { init(); load(filename); }
    6265
    63 ~MultiParamLoader() {abort();clearObjects();}
     66        ~MultiParamLoader() { abort(); clearObjects(); }
    6467
    65 void reset();
     68        void reset();
    6669
    67 void load(); //< use previously opened file
    68 void load(VirtFILE *f);
    69 void load(const char* filename);
     70        void load(); //< use previously opened file
     71        void load(VirtFILE *f);
     72        void load(const char* filename);
    7073
    71 /** Register the object class. Class names will be matched with object headers ("xxx:" in the input file).
    72     Used with breakOn(BeforeObject) and/or breakOn(AfterObject).
    73     Note that registered classes will only work when the record name matches the class name, otherwise breakOn(BeforeUnknown) must be used and then getClassName() to check for the expected record.
    74  */
    75 void addObject(ParamInterface *pi) {objects+=new ExtObject(pi);}
    76 void removeObject(ParamInterface *pi) {removeObject(ExtObject(pi));}
    77 void addObject(const ExtObject &o) {objects+=new ExtObject(o);}
    78 void removeObject(const ExtObject &o);
    79 int findObject(const ExtObject &o);
    80 void clearObjects();
     74        /** Register the object class. Class names will be matched with object headers ("xxx:" in the input file).
     75                Used with breakOn(BeforeObject) and/or breakOn(AfterObject).
     76                Note that registered classes will only work when the record name matches the class name, otherwise breakOn(BeforeUnknown) must be used and then getClassName() to check for the expected record.
     77                */
     78        void addObject(ParamInterface *pi) { objects += new ExtObject(pi); }
     79        void removeObject(ParamInterface *pi) { removeObject(ExtObject(pi)); }
     80        void addObject(const ExtObject &o) { objects += new ExtObject(o); }
     81        void removeObject(const ExtObject &o);
     82        int findObject(const ExtObject &o);
     83        void clearObjects();
    8184
    82 /** To be used in the main loop: while(event=loader.go()) { ... }
    83     loader.go() will return on specified events (@see breakOn(), noBreakOn()),
    84     then you can handle the event and resume loading.
    85  */
    86 virtual int go();
    87 /** same value as 'go()' */
    88 int getStatus() {return status;}
    89 int finished() {return (status==Finished);}
     85        /** To be used in the main loop: while(event=loader.go()) { ... }
     86                loader.go() will return on specified events (@see breakOn(), noBreakOn()),
     87                then you can handle the event and resume loading.
     88                */
     89        virtual int go();
     90        /** same value as 'go()' */
     91        int getStatus() { return status; }
     92        int finished() { return (status == Finished); }
    9093
    91 VirtFILE *getFile() {return file;}
    92 SString currentFilePathForErrorMessage();
     94        VirtFILE *getFile() { return file; }
     95        SString currentFilePathForErrorMessage();
    9396
    94 /** Abort immediately and close the file if needed */
    95 void abort();
    96 /** @param conditions can be combined bitwise, eg. MultiParamLoader::BeforeObject |  MultiParamLoader::OnComment
    97     @see BreakConfitions
    98 */
    99 void breakOn(int conditions) {breakcond|=conditions;}
    100 void noBreakOn(int conditions) {breakcond&=~conditions;}
    101 /**
    102    These constants are used as arguments in breakOn(), and as status values from go() and getStatus().
    103    The user code can define some classes for automatic recognition (using addClass()); such records can be read without performing any additional actions.
    104    
    105    - BeforeObject: found an object with recognized classname (addClass()). Application code can choose to skip the incoming record (skipObject()), redirect the incoming data into a different object (loadObjectNow(ParamInterface*)), or do nothing for default behavior (loading into previously registered object).
     97        /** Abort immediately and close the file if needed */
     98        void abort();
     99        /** @param conditions can be combined bitwise, eg. MultiParamLoader::BeforeObject |  MultiParamLoader::OnComment
     100                @see BreakConfitions
     101                */
     102        void breakOn(int conditions) { breakcond |= conditions; }
     103        void noBreakOn(int conditions) { breakcond &= ~conditions; }
     104        /**
     105           These constants are used as arguments in breakOn(), and as status values from go() and getStatus().
     106           The user code can define some classes for automatic recognition (using addClass()); such records can be read without performing any additional actions.
    106107
    107    - AfterObject: the object was loaded into the registered class interface (addClass()). This is to allow for additional actions after loading the object (e.g. data validation).
     108           - BeforeObject: found an object with recognized classname (addClass()). Application code can choose to skip the incoming record (skipObject()), redirect the incoming data into a different object (loadObjectNow(ParamInterface*)), or do nothing for default behavior (loading into previously registered object).
    108109
    109    - BeforeUnknown: unknown (not registered) object header detected. Like in BeforeObject, the application can skipObject() or loadObjectNow().
     110           - AfterObject: the object was loaded into the registered class interface (addClass()). This is to allow for additional actions after loading the object (e.g. data validation).
    110111
    111 @see getClass(), GetClassName()
    112  */
    113 enum BreakConditions { Finished=0, BeforeObject=1, AfterObject=2,
    114                        BeforeUnknown=4, OnComment=8, OnError=16, Loading=32 };
     112           - BeforeUnknown: unknown (not registered) object header detected. Like in BeforeObject, the application can skipObject() or loadObjectNow().
    115113
    116 /** Can be used BeforeObject and AfterObject */
    117 ExtObject &getObject() {return lastobject;}
    118 /** Can be used BeforeUnknown, BeforeObject, AfterObject */
    119 const SString& getObjectName() {return lastunknown;}
    120 void setObjectName(SString n) {lastunknown=n;}
    121 /** Unknown object will be loaded if you set its class BeforeUnknown */
    122 void setObject(ParamInterface *pi) {lastobject=ExtObject(pi);}
    123 void setObject(const ExtObject& o) {lastobject=o;}
    124 /** Can be used OnComment */
    125 const SString& getComment() {return lastcomment;}
    126 /** Can be used OnError */
    127 const SString& getError() {return lasterror;}
    128 /** Can be used BeforeObject and BeforeUnknown */
    129 int loadObjectNow(ParamInterface *pi,bool warn_unknown_fields=true) {return loadObjectNow(ExtObject(pi),warn_unknown_fields);}
    130 int loadObjectNow(const ExtObject &o,bool warn_unknown_fields=true);
    131 /** Can be used BeforeObject */
    132 int loadObjectNow() {return loadObjectNow(getObject());}
    133 /** Can be used BeforeObject and BeforeUnknown.
    134     Object data will not be loaded. */
    135 int skipObject() {return loadObjectNow(&emptyparam,false);}
    136 /** @return 1 if no errors */
    137 int run();
     114           @see getClass(), GetClassName()
     115           */
     116        enum BreakConditions {
     117                Finished = 0, BeforeObject = 1, AfterObject = 2,
     118                BeforeUnknown = 4, OnComment = 8, OnError = 16, Loading = 32
     119        };
    138120
    139 void includeFile(SString& filename);
    140 bool returnFromIncluded();
    141 bool alreadyIncluded(const char* filename);
     121        /** Can be used BeforeObject and AfterObject */
     122        ExtObject &getObject() { return lastobject; }
     123        /** Can be used BeforeUnknown, BeforeObject, AfterObject */
     124        const SString& getObjectName() { return lastunknown; }
     125        void setObjectName(SString n) { lastunknown = n; }
     126        /** Unknown object will be loaded if you set its class BeforeUnknown */
     127        void setObject(ParamInterface *pi) { lastobject = ExtObject(pi); }
     128        void setObject(const ExtObject& o) { lastobject = o; }
     129        /** Can be used OnComment */
     130        const SString& getComment() { return lastcomment; }
     131        /** Can be used OnError */
     132        const SString& getError() { return lasterror; }
     133        /** Can be used BeforeObject and BeforeUnknown */
     134        int loadObjectNow(ParamInterface *pi, bool warn_unknown_fields = true) { return loadObjectNow(ExtObject(pi), warn_unknown_fields); }
     135        int loadObjectNow(const ExtObject &o, bool warn_unknown_fields = true);
     136        /** Can be used BeforeObject */
     137        int loadObjectNow() { return loadObjectNow(getObject()); }
     138        /** Can be used BeforeObject and BeforeUnknown.
     139                Object data will not be loaded. */
     140        int skipObject() { return loadObjectNow(&emptyparam, false); }
     141        /** @return 1 if no errors */
     142        int run();
     143
     144        void includeFile(SString& filename);
     145        bool returnFromIncluded();
     146        bool alreadyIncluded(const char* filename);
    142147
    143148};
    144149
    145150#endif
    146 
Note: See TracChangeset for help on using the changeset viewer.