r8404: small upstream merges of appweb code
[bbaumbach/samba-autobuild/.git] / source4 / lib / appweb / mpr / var.h
1 /*
2  *      @file   var.h
3  *      @brief  MPR Universal Variable Type
4  *      @copy   default.m
5  *      
6  *      Copyright (c) Mbedthis Software LLC, 2003-2005. All Rights Reserved.
7  *      Copyright (c) Michael O'Brien, 1994-1995. All Rights Reserved.
8  *      
9  *      This software is distributed under commercial and open source licenses.
10  *      You may use the GPL open source license described below or you may acquire 
11  *      a commercial license from Mbedthis Software. You agree to be fully bound 
12  *      by the terms of either license. Consult the LICENSE.TXT distributed with 
13  *      this software for full details.
14  *      
15  *      This software is open source; you can redistribute it and/or modify it 
16  *      under the terms of the GNU General Public License as published by the 
17  *      Free Software Foundation; either version 2 of the License, or (at your 
18  *      option) any later version. See the GNU General Public License for more 
19  *      details at: http://www.mbedthis.com/downloads/gplLicense.html
20  *      
21  *      This program is distributed WITHOUT ANY WARRANTY; without even the 
22  *      implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
23  *      
24  *      This GPL license does NOT permit incorporating this software into 
25  *      proprietary programs. If you are unable to comply with the GPL, you must
26  *      acquire a commercial license to use this software. Commercial licenses 
27  *      for this software and support services are available from Mbedthis 
28  *      Software at http://www.mbedthis.com 
29  *      
30  *      @end
31  */
32
33 /******************************* Documentation ********************************/
34 /*
35  *      Variables can efficiently store primitive types and can hold references to
36  *      objects. Objects can store properties which are themselves variables.
37  *      Properties can be primitive data types, other objects or functions. 
38  *      Properties are indexed by a character name. A variable may store one of 
39  *      the following types: 
40  *
41  *              string, integer, integer-64bit, C function, C function with string args,
42  *               Javascript function, Floating point number, boolean value, Undefined 
43  *              value and the Null value. 
44  *
45  *      Variables have names while objects may be referenced by multiple variables.
46  *      Objects use reference counting for garbage collection.
47  *
48  *      This module is not thread safe for performance and compactness. It relies
49  *      on upper modules to provide thread synchronization as required. The API
50  *      provides primitives to get variable/object references or to get copies of 
51  *      variables which will help minimize required lock times.
52  */
53
54 #ifndef _h_MPR_VAR
55 #define _h_MPR_VAR 1
56
57 /********************************* Includes ***********************************/
58
59 #include        "miniMpr.h"
60
61 /********************************** Defines ***********************************/
62
63 /*
64  *      Define VAR_DEBUG if you want to track objects. However, this code is not
65  *      thread safe and you need to run the server single threaded.
66  *
67  *              #define VAR_DEBUG 1
68  */
69
70 #ifdef __cplusplus
71 extern "C" {
72 #endif
73 /*
74  *      Forward declare types
75  */
76 struct MprProperties;
77 struct MprVar;
78
79 /*
80  *      Possible variable types. Don't use enum because we need to be able to
81  *      do compile time conditional compilation on BLD_FEATURE_NUM_TYPE_ID.
82  */
83 typedef int MprType;
84 #define MPR_TYPE_UNDEFINED                      0       /* Undefined. No value has been set. */
85 #define MPR_TYPE_NULL                           1       /* Value defined to be null. */
86 #define MPR_TYPE_BOOL                           2       /* Boolean type. */
87 #define MPR_TYPE_CFUNCTION                      3       /* C function or C++ method */
88 #define MPR_TYPE_FLOAT                          4       /* Floating point number */
89 #define MPR_TYPE_INT                            5       /* Integer number */
90 #define MPR_TYPE_INT64                          6       /* 64-bit Integer number */
91 #define MPR_TYPE_OBJECT                         7       /* Object reference */
92 #define MPR_TYPE_FUNCTION                       8       /* JavaScript function */
93 #define MPR_TYPE_STRING                         9       /* String (immutable) */
94 #define MPR_TYPE_STRING_CFUNCTION       10      /* C/C++ function with string args */
95 #define MPR_TYPE_PTR                            11      /* Opaque pointer */
96
97 /*
98  *      Create a type for the default number type
99  *      Config.h will define the default number type. For example:
100  *
101  *              BLD_FEATURE_NUM_TYPE=int
102  *              BLD_FEATURE_NUM_TYPE_ID=MPR_TYPE_INT
103  */
104
105 /**
106  *      Set to the type used for MPR numeric variables. Will equate to int, int64 
107  *      or double. 
108  */
109 typedef BLD_FEATURE_NUM_TYPE MprNum;
110
111 /**
112  *      Set to the MPR_TYPE used for MPR numeric variables. Will equate to 
113  *      MPR_TYPE_INT, MPR_TYPE_INT64 or MPR_TYPE_FLOAT.
114  */
115 #define MPR_NUM_VAR BLD_FEATURE_NUM_TYPE_ID
116 #define MPR_TYPE_NUM BLD_FEATURE_NUM_TYPE_ID
117
118 /*
119  *      Return TRUE if a variable is a function type
120  */
121 #define mprVarIsFunction(type) \
122         (type == MPR_TYPE_FUNCTION || type == MPR_TYPE_STRING_CFUNCTION || \
123          type == MPR_TYPE_CFUNCTION)
124
125 /*
126  *      Return TRUE if a variable is a numeric type
127  */
128 #define mprVarIsNumber(type) \
129         (type == MPR_TYPE_INT || type == MPR_TYPE_INT64 || type == MPR_TYPE_FLOAT)
130
131 /*
132  *      Return TRUE if a variable is a boolean
133  */
134 #define mprVarIsBoolean(type) \
135         (type == MPR_TYPE_BOOL)
136 #define mprVarIsString(type) \
137         (type == MPR_TYPE_STRING)
138 #define mprVarIsObject(type) \
139         (type == MPR_TYPE_OBJECT)
140 #define mprVarIsFloating(type) \
141         (type == MPR_TYPE_FLOAT)
142 #define mprVarIsPtr(type) \
143         (type == MPR_TYPE_PTR)
144 #define mprVarIsUndefined(var) \
145         ((var)->type == MPR_TYPE_UNDEFINED)
146 #define mprVarIsNull(var) \
147         ((var)->type == MPR_TYPE_NULL)
148 #define mprVarIsValid(var) \
149         (((var)->type != MPR_TYPE_NULL) && ((var)->type != MPR_TYPE_UNDEFINED))
150
151 #define MPR_VAR_MAX_RECURSE             5                               /* Max object loops */
152
153 #if BLD_FEATURE_SQUEEZE
154 #define MPR_MAX_VAR                             64                              /* Max var full name */
155 #else
156 #define MPR_MAX_VAR                             512
157 #endif
158
159 /*
160  *      Function signatures
161  */
162 typedef int     MprVarHandle;
163 typedef int (*MprCFunction)(MprVarHandle userHandle, int argc, 
164         struct MprVar **argv);
165 typedef int (*MprStringCFunction)(MprVarHandle userHandle, int argc, 
166         char **argv);
167
168 /*
169  *      Triggers
170  */
171 typedef enum {
172         MPR_VAR_WRITE,                                          /* This property is being updated */
173         MPR_VAR_READ,                                           /* This property is being read */
174         MPR_VAR_CREATE_PROPERTY,                        /* A property is being created */
175         MPR_VAR_DELETE_PROPERTY,                        /* A property is being deleted */
176         MPR_VAR_DELETE                                          /* This object is being deleted */
177 } MprVarTriggerOp;
178
179 /*
180  *      Trigger function return codes.
181  */
182 typedef enum {
183         MPR_TRIGGER_ABORT,                                      /* Abort the current operation */
184         MPR_TRIGGER_USE_NEW_VALUE,                      /* Proceed and use the newValue */
185         MPR_TRIGGER_PROCEED                                     /* Proceed with the operation */
186 } MprVarTriggerStatus;
187
188 /*
189  *      The MprVarTrigger arguments have the following meaning:
190  *
191  *              op                                      The operation being performed. See MprVarTriggerOp.
192  *              parentProperties        Pointer to the MprProperties structure.
193  *              vp                                      Pointer to the property that registered the trigger.
194  *              newValue                        New value (see below for more details).
195  *              copyDepth                       Specify what data items to copy.
196  *
197  *      For VAR_READ, newVar is set to a temporary variable that the trigger 
198  *              function may assign a value to be returned instead of the actual 
199  *              property value. 
200  *      For VAR_WRITE, newValue holds the new value. The old existing value may be
201  *              accessed via vp.
202  *      For DELETE_PROPERTY, vp is the property being deleted. newValue is null.
203  *      For ADD_PROPERTY, vp is set to the property being added and newValue holds 
204  *              the new value.
205  */
206 typedef MprVarTriggerStatus (*MprVarTrigger)(MprVarTriggerOp op, 
207         struct MprProperties *parentProperties, struct MprVar *vp, 
208         struct MprVar *newValue, int copyDepth);
209
210 /*
211  *      mprCreateFunctionVar flags
212  */
213 /** Use the alternate handle on function callbacks */
214 #define MPR_VAR_ALT_HANDLE              0x1
215
216 /** Use the script handle on function callbacks */
217 #define MPR_VAR_SCRIPT_HANDLE   0x2
218
219 /*
220  *      Useful define for the copyDepth argument
221  */
222 /** Don't copy any data. Copy only the variable name */
223 #define MPR_NO_COPY                     0
224
225 /** Copy strings. Increment object reference counts. */
226 #define MPR_SHALLOW_COPY        1
227
228 /** Copy strings and do complete object copies. */
229 #define MPR_DEEP_COPY           2
230
231 /*
232  *      GetFirst / GetNext flags
233  */
234 /** Step into data properties. */
235 #define MPR_ENUM_DATA           0x1
236
237 /** Step into functions properties. */
238 #define MPR_ENUM_FUNCTIONS      0x2
239
240 /*
241  *      Collection type to hold properties in an object
242  */
243 typedef struct MprProperties {                                  /* Collection of properties */
244 #if VAR_DEBUG
245         struct MprProperties *next;                                     /* Linked list */
246         struct MprProperties *prev;                                     /* Linked list */
247         char                            name[32];                               /* Debug name */
248 #endif
249         struct MprVar           **buckets;                              /* Hash chains */
250         int                                     numItems;                               /* Total count of items */
251         /* FUTURE - Better way of doing this */
252         int                                     numDataItems;                   /* Enumerable data items */
253         uint                            hashSize                : 8;    /* Size of the hash table */
254         /* FUTURE -- increase size of refCount */
255         uint                            refCount                : 8;    /* References to this property*/
256         /* FUTURE - make these flags */
257         uint                            deleteProtect   : 8;    /* Don't recursively delete */
258         uint                            visited                 : 8;    /* Node has been processed */
259 } MprProperties;
260
261 /*
262  *      Universal Variable Type
263  */
264 typedef struct MprVar {
265         /* FUTURE - remove name to outside reference */
266         MprStr                          name;                                   /* Property name */
267         /* FUTURE - remove */
268         MprStr                          fullName;                               /* Full object name */
269         /* FUTURE - make part of the union */
270         MprProperties           *properties;                    /* Pointer to properties */
271
272         /*
273          *      Packed bit field
274          */
275         MprType                         type                    : 8;    /* Selector into union */
276         uint                            bucketIndex             : 8;    /* Copy of bucket index */
277
278         uint                            flags                   : 5;    /* Type specific flags */
279         uint                            allocatedData   : 1;    /* Data needs freeing */
280         uint                            readonly                : 1;    /* Unmodifiable */
281         uint                            deleteProtect   : 1;    /* Don't recursively delete */
282
283         uint                            visited                 : 1;    /* Node has been processed */
284         uint                            allocatedVar    : 1;    /* Var needs freeing */
285         uint                            spare                   : 6;    /* Unused */
286
287         struct MprVar           *forw;                                  /* Hash table linkage */
288         MprVarTrigger           trigger;                                /* Trigger function */
289
290 #if UNUSED && KEEP
291         struct MprVar           *baseClass;                             /* Pointer to class object */
292 #endif
293         MprProperties           *parentProperties;              /* Pointer to parent object */
294
295         /*
296          *      Union of primitive types. When debugging on Linux, don't use unions 
297          *      as the gdb debugger can't display them.
298          */
299 #if !BLD_DEBUG && !LINUX && !VXWORKS
300         union {
301 #endif
302                 int                             boolean;                                /* Use int for speed */
303 #if BLD_FEATURE_FLOATING_POINT
304                 double                  floating;
305 #endif
306                 int                             integer;
307 #if BLD_FEATURE_INT64
308                 int64                   integer64;
309 #endif
310                 struct {                                                                /* Javascript functions */
311                         MprArray        *args;                                  /* Null terminated */
312                         char            *body;
313                 } function;
314                 struct {                                                                /* Function with MprVar args */
315                         MprCFunction fn;
316                         void            *thisPtr;
317                 } cFunction;
318                 struct {                                                                /* Function with string args */
319                         MprStringCFunction fn;
320                         void            *thisPtr;
321                 } cFunctionWithStrings;
322                 MprStr                  string;                                 /* Allocated string */
323                 void                    *ptr;                                   /* Opaque pointer */
324 #if !BLD_DEBUG && !LINUX && !VXWORKS
325         };
326 #endif
327 } MprVar;
328
329 /*
330  *      Define a field macro so code an use numbers in a "generic" fashion.
331  */
332 #if MPR_NUM_VAR == MPR_TYPE_INT || DOXYGEN
333 /*      Default numeric type */
334 #define mprNumber integer
335 #endif
336 #if MPR_NUM_VAR == MPR_TYPE_INT64
337 /*      Default numeric type */
338 #define mprNumber integer64
339 #endif
340 #if MPR_NUM_VAR == MPR_TYPE_FLOAT
341 /*      Default numeric type */
342 #define mprNumber floating
343 #endif
344
345 typedef BLD_FEATURE_NUM_TYPE MprNumber;
346
347 /********************************* Prototypes *********************************/
348 /*
349  *      Variable constructors and destructors
350  */
351 extern MprVar   mprCreateObjVar(const char *name, int hashSize);
352 extern MprVar   mprCreateBoolVar(bool value);
353 extern MprVar   mprCreateCFunctionVar(MprCFunction fn, void *thisPtr, 
354                                         int flags);
355 #if BLD_FEATURE_FLOATING_POINT
356 extern MprVar   mprCreateFloatVar(double value);
357 #endif
358 extern MprVar   mprCreateIntegerVar(int value);
359 #if BLD_FEATURE_INT64
360 extern MprVar   mprCreateInteger64Var(int64 value);
361 #endif
362 extern MprVar   mprCreateFunctionVar(char *args, char *body, int flags);
363 extern MprVar   mprCreateNullVar(void);
364 extern MprVar   mprCreateNumberVar(MprNumber value);
365 extern MprVar   mprCreateStringCFunctionVar(MprStringCFunction fn, 
366                                         void *thisPtr, int flags);
367 extern MprVar   mprCreateStringVar(const char *value, bool allocate);
368 extern MprVar   mprCreateUndefinedVar(void);
369 extern MprVar   mprCreatePtrVar(void *ptr);
370 extern bool     mprDestroyVar(MprVar *vp);
371 extern bool     mprDestroyAllVars(MprVar* vp);
372 extern MprType  mprGetVarType(MprVar *vp);
373
374 /*
375  *      Copy
376  */
377 extern void             mprCopyVar(MprVar *dest, MprVar *src, int copyDepth);
378 extern void             mprCopyVarValue(MprVar *dest, MprVar src, int copyDepth);
379 extern MprVar   *mprDupVar(MprVar *src, int copyDepth);
380
381 /*
382  *      Manage vars
383  */
384 extern MprVarTrigger 
385                                 mprAddVarTrigger(MprVar *vp, MprVarTrigger fn);
386 extern int              mprGetVarRefCount(MprVar *vp);
387 extern void     mprSetVarDeleteProtect(MprVar *vp, int deleteProtect);
388 extern void     mprSetVarFullName(MprVar *vp, char *name);
389 extern void     mprSetVarReadonly(MprVar *vp, int readonly);
390 extern void     mprSetVarName(MprVar *vp, char *name);
391
392 /*
393  *      Create properties and return a reference to the property.
394  */
395 extern MprVar   *mprCreateProperty(MprVar *obj, const char *property, 
396                                         MprVar *newValue);
397 extern MprVar   *mprCreatePropertyValue(MprVar *obj, const char *property, 
398                                         MprVar newValue);
399 extern int              mprDeleteProperty(MprVar *obj, const char *property);
400
401 /*
402  *      Get/Set properties. Set will update/create.
403  */
404 extern MprVar   *mprGetProperty(MprVar *obj, const char *property, 
405                                         MprVar *value);
406 extern MprVar   *mprSetProperty(MprVar *obj, const char *property, 
407                                         MprVar *value);
408 extern MprVar   *mprSetPropertyValue(MprVar *obj, const char *property, 
409                                         MprVar value);
410
411 /*
412  *      Directly read/write property values (the property must already exist)
413  *      For mprCopyProperty, mprDestroyVar must always called on the var.
414  */
415 extern int              mprReadProperty(MprVar *prop, MprVar *value);
416 extern int              mprWriteProperty(MprVar *prop, MprVar *newValue);
417 extern int              mprWritePropertyValue(MprVar *prop, MprVar newValue);
418
419 /*
420  *      Copy a property. NOTE: reverse of most other args: (dest, src)
421  */
422 extern int              mprCopyProperty(MprVar *dest, MprVar *prop, int copyDepth);
423
424 /*
425  *      Enumerate properties
426  */
427 extern MprVar   *mprGetFirstProperty(MprVar *obj, int includeFlags);
428 extern MprVar   *mprGetNextProperty(MprVar *obj, MprVar *currentProperty, 
429                                         int includeFlags);
430
431 /*
432  *      Query properties characteristics
433  */
434 extern int              mprGetPropertyCount(MprVar *obj, int includeFlags);
435
436 /*
437  *      Conversion routines
438  */
439 extern MprVar   mprParseVar(char *str, MprType prefType);
440 extern MprNum   mprVarToNumber(const MprVar *vp);
441 extern int              mprVarToInteger(const MprVar *vp);
442 #if BLD_FEATURE_INT64
443 extern int64    mprVarToInteger64(const MprVar *vp);
444 #endif
445 extern bool     mprVarToBool(const MprVar *vp);
446 #if BLD_FEATURE_FLOATING_POINT
447 extern double   mprVarToFloat(const MprVar *vp);
448 #endif
449 extern void     mprVarToString(char** buf, int size, char *fmt, MprVar *vp);
450
451 /*
452  *      Parsing and utility routines
453  */
454 extern MprNum   mprParseNumber(char *str);
455 extern int              mprParseInteger(char *str);
456
457 #if BLD_FEATURE_INT64
458 extern int64    mprParseInteger64(char *str);
459 #endif
460
461 #if BLD_FEATURE_FLOATING_POINT
462 extern double   mprParseFloat(char *str);
463 extern bool     mprIsInfinite(double f);
464 extern bool     mprIsNan(double f);
465 #endif
466
467 #if VAR_DEBUG
468 extern void     mprPrintObjects(char *msg);
469 extern void     mprPrintObjRefCount(MprVar *vp);
470 #endif
471
472 #ifdef __cplusplus
473 }
474 #endif
475
476 /*****************************************************************************/
477 #endif /* _h_MPR_VAR */
478
479 /*
480  * Local variables:
481  * tab-width: 4
482  * c-basic-offset: 4
483  * End:
484  * vim:tw=78
485  * vim600: sw=4 ts=4 fdm=marker
486  * vim<600: sw=4 ts=4
487  */