source: cpp/frams/param/param.h

Last change on this file was 1184, checked in by Maciej Komosinski, 18 months ago

Introduced a class to quickly copy field values between two compatible Param's, and added a constructor that checks if the paramtab structure is correct

  • Property svn:eol-style set to native
File size: 16.4 KB
Line 
1// This file is a part of Framsticks SDK.  http://www.framsticks.com/
2// Copyright (C) 1999-2022  Maciej Komosinski and Szymon Ulatowski.
3// See LICENSE.txt for details.
4
5#ifndef _PARAM_H_
6#define _PARAM_H_
7
8#include <stdio.h>
9#include <stdint.h>
10#include <vector>
11#include <frams/util/sstring.h>
12#include <frams/util/sstringutils.h>
13#include <frams/util/list.h>
14#include <frams/util/statrick.h>
15#include <common/virtfile/virtfile.h>
16#include <common/log.h>
17
18class ExtValue;
19class ExtObject;
20
21// ParamInterface flags:
22#define PARAM_READONLY       1  //< Param is not able to change this member
23#define PARAM_DONTSAVE       2  //< Param will not save this member
24#define PARAM_SETLEVEL(x) (((x)&3)<<2)  //< internal use
25#define PARAM_LEVEL(x)    (((x)>>2)&3)  //< internal use
26#define PARAM_USERREADONLY  16  //< GUI should not change this member (even if Param can)
27#define PARAM_USERHIDDEN    32  //< GUI should not display this member
28#define MUTPARAM_ALLOCENTRY 64  //< for mutableparam (private!)
29#define MUTPARAM_ALLOCDATA 128  //< for mutableparam (private!)
30#define PARAM_NOSTATIC  256     //< (FramScript) don't access this member in a static object (ClassName.field)
31#define PARAM_CONST     512     //< (FramScript) constant value
32#define PARAM_CANOMITNAME 1024  //< affects Param::saveSingleLine()/loadSingleLine() - for example one-liners in f0 genetic encoding
33#define PARAM_DONTLOAD    2048  //< Param::load() skips this field
34#define PARAM_NOISOLATION 4096  //< don't use proxy object in master/slave interactions
35#define PARAM_DEPRECATED  8192  //< this member is deprecated
36#define PARAM_LINECOMMENT 16384 //< Param::load() adds "@line ..." comment when loading multiline (internal use)
37#define PARAM_OBJECTSET 32768   //< setting this field is handled by the object's assign(...) function and cannot change the object reference
38
39typedef int32_t paInt;
40#define PA_INT_SCANF "%d"
41#define PA_INT_SCANF_X "%x"
42
43// the result of param::set() is a combination of bits:
44
45// read-only: cannot modify
46#define PSET_RONLY      1
47
48// value has been modified
49#define PSET_CHANGED    2
50
51//value has been adjusted because it tried to exceed min or max
52#define PSET_HITMIN     4
53#define PSET_HITMAX     8
54
55#define PSET_NOPROPERTY 16
56
57#define PSET_PARSEFAILED        32
58
59// useful combination: need to get and display the value so that a user knows that the value they tried to set has been rejected or changed
60#define PSET_WARN (PSET_RONLY | PSET_HITMIN | PSET_HITMAX | PSET_PARSEFAILED)
61
62
63struct ParamEntry;
64
65/** Property get/set interface - runtime access to named properties */
66class ParamInterface
67{
68public:
69        virtual ~ParamInterface() {}
70
71        virtual int getGroupCount() = 0; ///< @return the number of property groups
72        virtual int getPropCount() = 0; ///< @return the number of properties
73
74        virtual const char* getName() = 0;
75        virtual const char* getLongName() { return getName(); }
76        virtual const char* getDescription() { return 0; }
77        virtual ParamEntry *getParamTab() const { return NULL; }
78
79        int findId(const char *n);      ///< find id number for internal name
80        int findIdn(const char *naz, int n);
81        int findGroupId(const char* name);
82
83        virtual const char *id(int i) = 0;      ///< get internal name
84        virtual const char *name(int i) = 0;    ///< get the human-readable name
85
86        /** get type description.
87                first character defines basic datatype:
88                - d = integer
89                - f = floating point
90                - s = string
91                - o = ExtObject
92                - x = ExtValue (universal datatype)
93                */
94        virtual const char *type(int i) = 0;
95
96        virtual const char *help(int i) = 0;    ///< get long description (tooltip)
97
98        virtual int flags(int i) = 0;           ///< get flags
99
100        virtual int group(int i) = 0;           ///< get group id for a property
101        virtual const char *grname(int gi) = 0; ///< get group name
102        virtual int grmember(int gi, int n) = 0;        ///< get property id for n'th member of group "gi"
103
104        virtual void call(int i, ExtValue* args, ExtValue *ret) = 0;
105
106        void get(int, ExtValue &retval);        ///< most universal get, can be used for every datatype
107
108        virtual SString getString(int) = 0;     ///< get string value, you can only use this for "s" type property
109        virtual paInt getInt(int) = 0;  ///< get long value, you can only use this for "d" type property
110        virtual double getDouble(int) = 0;      ///< get double value, you can only use this for "f" type property
111        virtual ExtObject getObject(int) = 0;   ///< get object reference, you can only use this for "o" type property
112        virtual ExtValue getExtValue(int) = 0;  ///< get extvalue object, you can only use this for "x" type property
113
114        SString get(int);               ///< old style get, can convert long or double to string
115        SString getText(int);           ///< like getString, returns enumeration label for subtype "d 0 n ~enum1~enum2...
116
117        SString getStringById(const char*prop);  ///< get string value, you can only use this for "s" type property
118        paInt getIntById(const char* prop);    ///< get long value, you can only use this for "d" type property
119        double getDoubleById(const char* prop);///< get double value, you can only use this for "f" type property
120        ExtObject getObjectById(const char* prop);///< get object reference, you can only use this for "o" type property
121        ExtValue getExtValueById(const char* prop);///< get extvalue object, you can only use this for "x" type property
122        ExtValue getById(const char* prop);
123
124        int setIntFromString(int i, const char* str, bool strict = false);
125        int setDoubleFromString(int i, const char* str);
126        virtual int setInt(int, paInt) = 0;             ///< set long value, you can only use this for "d" type prop
127        virtual int setDouble(int, double) = 0; ///< set double value, you can only use this for "f" type prop
128        virtual int setString(int, const SString &) = 0;        ///< set string value, you can only use this for "s" type prop
129        virtual int setObject(int, const ExtObject &) = 0;      ///< set object reference, you can only use this for "o" type prop
130        virtual int setExtValue(int, const ExtValue &) = 0;     ///< 4 in 1
131
132        int set(int, const ExtValue &);///< most universal set, can be used for every datatype
133
134        int setFromString(int, const char*, bool strict = false);               ///< oldstyle set, can convert string to long or double
135
136        int setIntById(const char* prop, paInt);///< set long value, you can only use this for "d" type prop
137        int setDoubleById(const char* prop, double);///< set double value, you can only use this for "f" type prop
138        int setStringById(const char* prop, const SString &);///< set string value, you can only use this for "s" type prop
139        int setObjectById(const char* prop, const ExtObject &);///< set object reference, you can only use this for "o" type prop
140        int setExtValueById(const char* prop, const ExtValue &); ///< for ExtValue types only
141        int setById(const char* prop, const ExtValue &);///< can be used for all property types
142
143        /** get valid minimum, maximum and default value for property 'prop'
144                @return 0 if min/max/def information is not available */
145        int getMinMaxInt(int prop, paInt& minumum, paInt& maximum, paInt& def);
146        /** get valid minimum, maximum and default value for property 'prop'
147                @return 0 if min/max/def information is not available */
148        int getMinMaxDouble(int prop, double& minumum, double& maximum, double& def);
149        int getMinMaxString(int prop, int& minumum, int& maximum, SString& def);
150        static int getMinMaxIntFromTypeDef(const char* type, paInt& minumum, paInt& maximum, paInt& def);
151        static int getMinMaxDoubleFromTypeDef(const char* type, double& minumum, double& maximum, double& def);
152        static int getMinMaxStringFromTypeDef(const char* type, int& minumum, int& maximum, SString& def);
153
154        virtual void setDefault();
155        virtual void setDefault(int i);
156        void setMin();
157        void setMax();
158        void setMin(int i);
159        void setMax(int i);
160
161        /** return the human readable description of the given type */
162        static SString friendlyTypeDescrFromTypeDef(const char* type);
163        SString friendlyTypeDescr(int i) { return friendlyTypeDescrFromTypeDef(type(i)); }
164
165        /** copy all property values from other ParamInterface object */
166        void copyFrom(ParamInterface *src);
167
168        /** Copy all property values from compatible ParamInterface object.
169                This method is more efficient than copyFrom,
170                but can be used only if the other object has the same properties sequence, e.g.:
171                - any two Param objects having common paramtab
172                - any ParamInterface object and the Param with paramtab constructed by ParamObject::makeParamTab
173                */
174        void quickCopyFrom(ParamInterface *src);
175
176        enum FileFormat { FormatMultiLine, FormatSingleLine }; // FormatJSON in the future?
177        struct LoadOptions {
178                bool warn_unknown_fields; bool *abortable; int *linenum; int offset; bool parse_failed;
179                LoadOptions() : warn_unknown_fields(false), abortable(NULL), linenum(NULL), offset(0), parse_failed(false) {}
180        };
181
182        int saveMultiLine(VirtFILE*, const char* altname = NULL, bool force = 0);
183        int saveprop(VirtFILE*, int i, const char* p, bool force = 0);
184
185        int load(FileFormat format, VirtFILE*, LoadOptions *load_options = NULL);///< @return the number of fields loaded
186        int load(FileFormat format, const SString &, LoadOptions *load_options = NULL);///< @return the number of fields loaded
187protected:
188        int loadMultiLine(VirtFILE*, LoadOptions &options);///< @return the number of fields loaded
189        int loadSingleLine(const SString &, LoadOptions &options);///< @return the number of fields loaded
190public:
191
192        static const char* SERIALIZATION_PREFIX;
193
194        static bool isValidTypeDescription(const char* t);
195#ifdef _DEBUG
196        virtual void sanityCheck(int i) {}
197#endif
198        SString nameDotProperty(int prop);
199        SString nameDotPropertyForMessages(int prop);
200};
201
202
203
204/** Copy fields between two compatible params. A Param2ParamCopy object can be static so the field names are only looked up once. */
205class Param2ParamCopy
206{
207        std::vector<int> fields;
208public:
209        Param2ParamCopy(ParamInterface& schema, const std::initializer_list<const char*> names);
210        void operator()(const ParamInterface& from, ParamInterface& to);
211};
212
213
214
215
216// implementations:
217
218extern char MakeCodeGuardHappy;
219
220#define PROCOFFSET(_proc_) ( (void (*)(void*,ExtValue*,ExtValue*)) &(FIELDSTRUCT :: _proc_ ## _statrick))
221#define STATICPROCOFFSET(_proc_) ( (void (*)(void*,ExtValue*,ExtValue*)) &(FIELDSTRUCT :: _proc_))
222#define GETOFFSET(_proc_) ( (void (*)(void*,ExtValue*)) &(FIELDSTRUCT :: _proc_ ## _statrick))
223#define SETOFFSET(_proc_) ( (int (*)(void*,const ExtValue*)) &(FIELDSTRUCT :: _proc_ ## _statrick))
224
225#define FIELDOFFSET(_fld_) ((intptr_t)((char*)(&((FIELDSTRUCT*)&MakeCodeGuardHappy)->_fld_)-((char*)((FIELDSTRUCT*)&MakeCodeGuardHappy))))
226
227#ifdef _DEBUG
228#define PARAM_ILLEGAL_OFFSET ((intptr_t)0xdeadbeef)
229#else
230#define PARAM_ILLEGAL_OFFSET 0
231#endif
232
233#define FIELD(_fld_) FIELDOFFSET(_fld_),0,0
234#define LONGOFFSET(_o_) (_o_),0,0
235#define PROCEDURE(_proc_) PARAM_ILLEGAL_OFFSET,(void*)PROCOFFSET(_proc_),0
236#define STATICPROCEDURE(_proc_) PARAM_ILLEGAL_OFFSET,(void*)STATICPROCOFFSET(_proc_),0
237#define GETSET(_proc_) PARAM_ILLEGAL_OFFSET,(void*)GETOFFSET(get_ ## _proc_),(void*)SETOFFSET(set_ ## _proc_)
238#define GETFIELD(_proc_) FIELDOFFSET(_proc_),(void*)GETOFFSET(get_ ## _proc_),0
239#define SETFIELD(_proc_) FIELDOFFSET(_proc_),0,(void*)SETOFFSET(set_ ## _proc_)
240#define GETONLY(_proc_) PARAM_ILLEGAL_OFFSET,(void*)GETOFFSET(get_ ## _proc_),0
241#define SETONLY(_proc_) PARAM_ILLEGAL_OFFSET,0,(void*)SETOFFSET(set_ ## _proc_)
242
243#define PARAMPROCARGS ExtValue* args,ExtValue* ret
244#define PARAMSETARGS const ExtValue* arg
245#define PARAMGETARGS ExtValue* ret
246
247#define PARAMPROCDEF(name) STATRICKDEF2(name,ExtValue*,ExtValue*)
248#define PARAMGETDEF(name) STATRICKDEF1(get_ ## name,ExtValue*)
249#define PARAMSETDEF(name) STATRICKRDEF1(int,set_ ## name,const ExtValue*)
250
251///////////////////////////////
252
253struct ParamEntry
254{
255        const char *id;
256        paInt group, flags;
257        const char *name, *type;
258        intptr_t offset;
259        void *fun1; ///< procedure or get
260        void *fun2; ///< set
261        const char *help;
262};
263
264struct ParamEntryConstructor : public ParamEntry
265{
266public:
267        ParamEntryConstructor(const char *_id, paInt _group = 0, paInt _flags = 0, const char *_name = 0, const char *_type = 0, intptr_t _offset = 0, void *_fun1 = 0, void *_fun2 = 0, const char *_help = 0)
268        {
269                id = _id; group = _group; flags = _flags; name = _name; type = _type; offset = _offset; fun1 = _fun1; fun2 = _fun2; help = _help;
270        }
271};
272
273class SimpleAbstractParam : public virtual ParamInterface
274{
275protected:
276        virtual void *getTarget(int i);
277        const char* myname;
278        const char* mylongname;
279        bool dontcheckchanges;
280
281public:
282        void *object;
283
284        const char* getName() { return myname; }
285        const char* getLongName() { return mylongname ? mylongname : myname; }
286
287        void setName(const char* n) { myname = n; }
288        void setLongName(const char* n) { mylongname = n; }
289
290        /**
291                @param t ParamEntry table
292                @param o controlled object
293                @param n Param's name
294                */
295        SimpleAbstractParam(void* o = 0, const char*n = 0) :myname(n), mylongname(NULL), dontcheckchanges(0), object(o) {}
296        void setDontCheckChanges(bool x) { dontcheckchanges = x; }
297
298        void select(void *o) { object = o; }
299        void* getSelected() { return object; }
300
301        virtual ParamEntry *entry(int i) = 0;
302        const char *id(int i) { return (i >= getPropCount()) ? 0 : entry(i)->id; }
303        const char *name(int i) { return entry(i)->name; }
304        const char *type(int i) { return entry(i)->type; }
305        const char *help(int i) { return entry(i)->help; }
306        int flags(int i) { return entry(i)->flags; }
307        int group(int i) { return entry(i)->group; }
308        void call(int i, ExtValue* args, ExtValue *ret);
309
310        SString getString(int);
311        paInt getInt(int);
312        double getDouble(int);
313        ExtObject getObject(int);
314        ExtValue getExtValue(int);
315
316        void messageOnExceedRange(int i, int setflags, ExtValue& valuetoset);
317        int setInt(int, paInt);
318        int setDouble(int, double);
319        int setString(int, const SString &);
320        int setObject(int, const ExtObject &);
321        int setExtValue(int, const ExtValue &);
322
323        int isequal(int i, void* defdata);
324        void saveSingleLine(SString&, void *defdata, bool addcr = true, bool all_names = true);
325
326        virtual void setDefault();
327        virtual void setDefault(int i);
328
329#ifdef _DEBUG
330        void sanityCheck(int i);
331#endif
332};
333
334#ifdef _DEBUG
335#define CHECK_PARAMENTRY_COUNT // This could be the only version, because it is not significantly more costly than the other one. Now we have a _DEBUG (checking, slightly slower) version and a non-_DEBUG (i.e. release, non-checking, slightly faster) version. Since both versions are completely different, the non-_DEBUG (release) version is not verified at all during thorough _DEBUG testing.
336#endif
337
338class Param : public SimpleAbstractParam
339{
340protected:
341        ParamEntry *entry(int i) { return tab + tab[0].group + i; }
342public:
343        ParamEntry *tab;
344        /**
345                @param t ParamEntry table
346                @param o controlled object
347                @param n Param's name
348                */
349
350#ifdef CHECK_PARAMENTRY_COUNT
351       
352        template <int COUNT>
353        Param(ParamEntry (&t)[COUNT],void* o = 0, const char*n = 0) :SimpleAbstractParam(o, n), tab(t)
354        {
355                if (!n&&tab) myname = tab[0].name;
356                //printf("Param(ParamEntry t[%d]) %s\n",COUNT,myname?myname:"unknown name");
357                if (tab)
358                        {
359                        int in_array = COUNT-1-tab[0].group;
360                        if (tab[0].flags != in_array)
361                                printf("\nCHECK_PARAMENTRY_COUNT: %d items in ParamEntry[] array, declared %d (%s)\n\n",in_array, tab[0].flags, myname?myname:"unknown name");
362                        if (in_array>0 && tab[COUNT-1].id != NULL) //in_array>0 -> completely empty paramtab can't end with the usual zero row because that's also its first row
363                                printf("\nCHECK_PARAMENTRY_COUNT: last entry is not null (%s)\n\n",myname?myname:"unknown name");
364                        }
365        }
366
367        template<typename T, typename std::enable_if_t<std::is_same<ParamEntry*,T>::value>* = nullptr > //SFINAE-fu because the normal ParamEntry* overload would be also called for ParamEntry[COUNT] argument
368        Param(T t, void* o = 0, const char*n = 0) :SimpleAbstractParam(o, n), tab(t)
369        {
370                //printf("Param(ParamEntry* t) %s\n",tab?tab[0].name:"");
371                if (!n&&tab) myname = tab[0].name;
372        }
373
374        Param() :SimpleAbstractParam(NULL, NULL), tab(NULL)
375        {
376                //printf("Param(NULL)\n");
377        }
378
379#else // CHECK_PARAMENTRY_COUNT
380       
381        Param(ParamEntry *t = 0, void* o = 0, const char*n = 0) :SimpleAbstractParam(o, n), tab(t)
382        {
383                if (!n&&tab) myname = tab[0].name;
384        }
385       
386#endif // CHECK_PARAMENTRY_COUNT
387       
388        Param(const Param& p) :SimpleAbstractParam(p.object, p.myname), tab(p.tab) {}
389        void operator=(const Param&p) { object = p.object; myname = p.myname; tab = p.tab; }
390
391        const char* getDescription() { return tab[0].type; }
392        const char* getLongName() { return tab[0].help ? tab[0].help : SimpleAbstractParam::getLongName(); }
393
394        int getGroupCount() { return tab[0].group; }
395        int getPropCount() { return tab[0].flags; }
396        const char *grname(int i) { return (i < getGroupCount()) ? tab[i].id : 0; }
397        int grmember(int, int);
398        void setParamTab(ParamEntry *t, int dontupdatename = 0) { tab = t; if ((!dontupdatename) && tab) myname = tab[0].name; }
399        ParamEntry *getParamTab() const { return tab; }
400};
401
402extern ParamEntry empty_paramtab[];
403
404#endif
Note: See TracBrowser for help on using the repository browser.