source: cpp/frams/param/multiparamload.h @ 998

Last change on this file since 998 was 998, checked in by Maciej Komosinski, 2 months ago

Report the error status just once so that while(go()) does not have to always check the error condition to stop (prevents endless loop on permanent errors)

  • Property svn:eol-style set to native
File size: 6.8 KB
Line 
1// This file is a part of Framsticks SDK.  http://www.framsticks.com/
2// Copyright (C) 1999-2018  Maciej Komosinski and Szymon Ulatowski.
3// See LICENSE.txt for details.
4
5#ifndef _MULTIPARAMLOAD_H_
6#define _MULTIPARAMLOAD_H_
7
8#include <stdio.h>
9#include "param.h"
10#include <common/virtfile/virtfile.h>
11#include <frams/util/extvalue.h>
12
13/** This is the general "framsticks-format" file parser for loading multiple objects.
14        http://www.framsticks.com/common/formatspec.html
15        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".
22
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        */
36class MultiParamLoader
37{
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;
49
50        void init();
51
52        int maybeBreak(int cond)
53        {
54                status = cond;
55                return breakcond & cond;
56        }
57
58        VirtFILE* popstack();
59        void clearstack();
60
61public:
62        MultiParamLoader() { init(); }
63        MultiParamLoader(VirtFILE *f) { init(); load(f); }
64        MultiParamLoader(const char* filename) { init(); load(filename); }
65
66        virtual ~MultiParamLoader() { abort(); clearObjects(); }
67
68        void reset();
69
70        void load(); //< use previously opened file
71        void load(VirtFILE *f);
72        void load(const char* filename);
73
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();
84
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 getStatusClearError() { int s = status; if (status & OnError) status &= ~ OnError; return s; }
93        int finished() { return (status == Finished); }
94
95        VirtFILE *getFile() { return file; }
96        SString currentFilePathForErrorMessage();
97
98        /** Abort immediately and close the file if needed */
99        void abort();
100        /** @param conditions can be combined bitwise, eg. MultiParamLoader::BeforeObject |  MultiParamLoader::OnComment
101                @see BreakConfitions
102                */
103        void breakOn(int conditions) { breakcond |= conditions; }
104        void noBreakOn(int conditions) { breakcond &= ~conditions; }
105        /**
106           These constants are used as arguments in breakOn(), and as status values from go() and getStatus().
107           The user code can define some classes for automatic recognition (using addClass()); such records can be read without performing any additional actions.
108
109           - 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).
110
111           - 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).
112
113           - BeforeUnknown: unknown (not registered) object header detected. Like in BeforeObject, the application can skipObject() or loadObjectNow().
114
115           @see getClass(), GetClassName()
116           */
117        enum BreakConditions {
118                Finished = 0, BeforeObject = 1, AfterObject = 2,
119                BeforeUnknown = 4, OnComment = 8, OnError = 16, Loading = 32
120        };
121
122        /** Can be used BeforeObject and AfterObject */
123        ExtObject &getObject() { return lastobject; }
124        /** Can be used BeforeUnknown, BeforeObject, AfterObject */
125        const SString& getObjectName() { return lastunknown; }
126        void setObjectName(SString n) { lastunknown = n; }
127        /** Unknown object will be loaded if you set its class BeforeUnknown */
128        void setObject(ParamInterface *pi) { lastobject = ExtObject(pi); }
129        void setObject(const ExtObject& o) { lastobject = o; }
130        /** Can be used OnComment */
131        const SString& getComment() { return lastcomment; }
132        /** Can be used OnError */
133        const SString& getError() { return lasterror; }
134        /** Can be used BeforeObject and BeforeUnknown */
135        int loadObjectNow(ParamInterface *pi, bool warn_unknown_fields = true) { return loadObjectNow(ExtObject(pi), warn_unknown_fields); }
136        int loadObjectNow(const ExtObject &o, bool warn_unknown_fields = true);
137        /** Can be used BeforeObject */
138        int loadObjectNow() { return loadObjectNow(getObject()); }
139        /** Can be used BeforeObject and BeforeUnknown.
140                Object data will not be loaded. */
141        int skipObject() { return loadObjectNow(&emptyparam, false); }
142        /** @return 1 if no errors */
143        int run();
144
145        void includeFile(SString& filename);
146        bool returnFromIncluded();
147        bool alreadyIncluded(const char* filename);
148
149};
150
151#endif
Note: See TracBrowser for help on using the repository browser.