source4/web_server/ejs/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        "web_server/ejs/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
  96 /*
  97  *      Create a type for the default number type
  98  *      Config.h will define the default number type. For example:
  99  *
 100  *              BLD_FEATURE_NUM_TYPE=int
 101  *              BLD_FEATURE_NUM_TYPE_ID=MPR_TYPE_INT
 102  */
 103
 104 /**
 105  *      Set to the type used for MPR numeric variables. Will equate to int, int64
 106  *      or double.
 107  */
 108 typedef BLD_FEATURE_NUM_TYPE MprNum;
 109
 110 /**
 111  *      Set to the MPR_TYPE used for MPR numeric variables. Will equate to
 112  *      MPR_TYPE_INT, MPR_TYPE_INT64 or MPR_TYPE_FLOAT.
 113  */
 114 #define MPR_NUM_VAR BLD_FEATURE_NUM_TYPE_ID
 115 #define MPR_TYPE_NUM BLD_FEATURE_NUM_TYPE_ID
 116
 117 /*
 118  *      Return TRUE if a variable is a function type
 119  */
 120 #define mprVarIsFunction(type) \
 121         (type == MPR_TYPE_FUNCTION || type == MPR_TYPE_STRING_CFUNCTION || \
 122          type == MPR_TYPE_CFUNCTION)
 123
 124 /*
 125  *      Return TRUE if a variable is a numeric type
 126  */
 127 #define mprVarIsNumber(type) \
 128         (type == MPR_TYPE_INT || type == MPR_TYPE_INT64 || type == MPR_TYPE_FLOAT)
 129
 130 /*
 131  *      Return TRUE if a variable is a boolean
 132  */
 133 #define mprVarIsBoolean(type) \
 134         (type == MPR_TYPE_BOOL)
 135 #define mprVarIsString(type) \
 136         (type == MPR_TYPE_STRING)
 137 #define mprVarIsObject(type) \
 138         (type == MPR_TYPE_OBJECT)
 139 #define mprVarIsFloating(type) \
 140         (type == MPR_TYPE_FLOAT)
 141 #define mprVarIsUndefined(var) \
 142         ((var)->type == MPR_TYPE_UNDEFINED)
 143 #define mprVarIsNull(var) \
 144         ((var)->type == MPR_TYPE_NULL)
 145 #define mprVarIsValid(var) \
 146         (((var)->type != MPR_TYPE_NULL) && ((var)->type != MPR_TYPE_UNDEFINED))
 147
 148 #define MPR_VAR_MAX_RECURSE             5                               /* Max object loops */
 149
 150 #if BLD_FEATURE_SQUEEZE
 151 #define MPR_MAX_VAR                             64                              /* Max var full name */
 152 #else
 153 #define MPR_MAX_VAR                             512
 154 #endif
 155
 156 #ifndef __NO_PACK
 157 #pragma pack(2)
 158 #endif /* _NO_PACK */
 159
 160 /*
 161  *      Function signatures
 162  */
 163 typedef int     MprVarHandle;
 164 typedef int (*MprCFunction)(MprVarHandle userHandle, int argc,
 165         struct MprVar **argv);
 166 typedef int (*MprStringCFunction)(MprVarHandle userHandle, int argc,
 167         char **argv);
 168
 169 /*
 170  *      Triggers
 171  */
 172 typedef enum {
 173         MPR_VAR_WRITE,                                          /* This property is being updated */
 174         MPR_VAR_READ,                                           /* This property is being read */
 175         MPR_VAR_CREATE_PROPERTY,                        /* A property is being created */
 176         MPR_VAR_DELETE_PROPERTY,                        /* A property is being deleted */
 177         MPR_VAR_DELETE                                          /* This object is being deleted */
 178 } MprVarTriggerOp;
 179
 180 /*
 181  *      Trigger function return codes.
 182  */
 183 typedef enum {
 184         MPR_TRIGGER_ABORT,                                      /* Abort the current operation */
 185         MPR_TRIGGER_USE_NEW_VALUE,                      /* Proceed and use the newValue */
 186         MPR_TRIGGER_PROCEED                                     /* Proceed with the operation */
 187 } MprVarTriggerStatus;
 188
 189 /*
 190  *      The MprVarTrigger arguments have the following meaning:
 191  *
 192  *              op                                      The operation being performed. See MprVarTriggerOp.
 193  *              parentProperties        Pointer to the MprProperties structure.
 194  *              vp                                      Pointer to the property that registered the trigger.
 195  *              newValue                        New value (see below for more details).
 196  *              copyDepth                       Specify what data items to copy.
 197  *
 198  *      For VAR_READ, newVar is set to a temporary variable that the trigger
 199  *              function may assign a value to be returned instead of the actual
 200  *              property value.
 201  *      For VAR_WRITE, newValue holds the new value. The old existing value may be
 202  *              accessed via vp.
 203  *      For DELETE_PROPERTY, vp is the property being deleted. newValue is null.
 204  *      For ADD_PROPERTY, vp is set to the property being added and newValue holds
 205  *              the new value.
 206  */
 207 typedef MprVarTriggerStatus (*MprVarTrigger)(MprVarTriggerOp op,
 208         struct MprProperties *parentProperties, struct MprVar *vp,
 209         struct MprVar *newValue, int copyDepth);
 210
 211 /*
 212  *      mprCreateFunctionVar flags
 213  */
 214 /** Use the alternate handle on function callbacks */
 215 #define MPR_VAR_ALT_HANDLE              0x1
 216
 217 /** Use the script handle on function callbacks */
 218 #define MPR_VAR_SCRIPT_HANDLE   0x2
 219
 220 /*
 221  *      Useful define for the copyDepth argument
 222  */
 223 /** Don't copy any data. Copy only the variable name */
 224 #define MPR_NO_COPY                     0
 225
 226 /** Copy strings. Increment object reference counts. */
 227 #define MPR_SHALLOW_COPY        1
 228
 229 /** Copy strings and do complete object copies. */
 230 #define MPR_DEEP_COPY           2
 231
 232 /*
 233  *      GetFirst / GetNext flags
 234  */
 235 /** Step into data properties. */
 236 #define MPR_ENUM_DATA           0x1
 237
 238 /** Step into functions properties. */
 239 #define MPR_ENUM_FUNCTIONS      0x2
 240
 241 /*
 242  *      Collection type to hold properties in an object
 243  */
 244 typedef struct MprProperties {                                  /* Collection of properties */
 245 #if VAR_DEBUG
 246         struct MprProperties *next;                                     /* Linked list */
 247         struct MprProperties *prev;                                     /* Linked list */
 248         char                            name[32];                               /* Debug name */
 249 #endif
 250         struct MprVar           **buckets;                              /* Hash chains */
 251         int                                     numItems;                               /* Total count of items */
 252         int                                     numDataItems;                   /* Enumerable data items */
 253         uint                            hashSize                : 8;    /* Size of the hash table */
 254         uint                            refCount                : 8;    /* References to this property*/
 255         uint                            deleteProtect   : 8;    /* Don't recursively delete */
 256         uint                            visited                 : 8;    /* Node has been processed */
 257 } MprProperties;
 258
 259 /*
 260  *      Universal Variable Type
 261  */
 262 typedef struct MprVar {
 263         MprStr                          name;                                   /* Property name */
 264         MprStr                          fullName;                               /* Full object name */
 265         MprProperties           *properties;                    /* Pointer to properties */
 266
 267         /*
 268          *      Packed bit field
 269          */
 270         MprType                         type                    : 8;    /* Selector into union */
 271         uint                            bucketIndex             : 8;    /* Copy of bucket index */
 272
 273         uint                            flags                   : 5;    /* Type specific flags */
 274         uint                            allocatedData   : 1;    /* Data needs freeing */
 275         uint                            readonly                : 1;    /* Unmodifiable */
 276         uint                            deleteProtect   : 1;    /* Don't recursively delete */
 277
 278         uint                            visited                 : 1;    /* Node has been processed */
 279         uint                            allocatedVar    : 1;    /* Var needs freeing */
 280         uint                            spare                   : 6;    /* Unused */
 281
 282         struct MprVar           *forw;                                  /* Hash table linkage */
 283         MprVarTrigger           trigger;                                /* Trigger function */
 284
 285 #if UNUSED && KEEP
 286         struct MprVar           *baseClass;                             /* Pointer to class object */
 287 #endif
 288         MprProperties           *parentProperties;              /* Pointer to parent object */
 289
 290         /*
 291          *      Union of primitive types. When debugging on Linux, don't use unions
 292          *      as the gdb debugger can't display them.
 293          */
 294 #if !BLD_DEBUG && !LINUX && !VXWORKS
 295         union {
 296 #endif
 297                 int                             boolean;                                /* Use int for speed */
 298 #if BLD_FEATURE_FLOATING_POINT
 299                 double                  floating;
 300 #endif
 301                 int                             integer;
 302 #if BLD_FEATURE_INT64
 303                 int64                   integer64;
 304 #endif
 305                 struct {                                                                /* Javascript functions */
 306                         MprArray        *args;                                  /* Null terminated */
 307                         char            *body;
 308                 } function;
 309                 struct {                                                                /* Function with MprVar args */
 310                         MprCFunction fn;
 311                         void            *thisPtr;
 312                 } cFunction;
 313                 struct {                                                                /* Function with string args */
 314                         MprStringCFunction fn;
 315                         void            *thisPtr;
 316                 } cFunctionWithStrings;
 317                 MprStr                  string;                                 /* Allocated string */
 318 #if !BLD_DEBUG && !LINUX && !VXWORKS
 319         };
 320 #endif
 321 } MprVar;
 322
 323 /*
 324  *      Define a field macro so code an use numbers in a "generic" fashion.
 325  */
 326 #if MPR_NUM_VAR == MPR_TYPE_INT || DOXYGEN
 327 //*     Default numeric type */
 328 #define mprNumber integer
 329 #endif
 330 #if MPR_NUM_VAR == MPR_TYPE_INT64
 331 //*     Default numeric type */
 332 #define mprNumber integer64
 333 #endif
 334 #if MPR_NUM_VAR == MPR_TYPE_FLOAT
 335 //*     Default numeric type */
 336 #define mprNumber floating
 337 #endif
 338
 339 typedef BLD_FEATURE_NUM_TYPE MprNumber;
 340
 341
 342 #ifndef __NO_PACK
 343 #pragma pack()
 344 #endif /* __NO_PACK */
 345
 346 /********************************* Prototypes *********************************/
 347 /*
 348  *      Variable constructors and destructors
 349  */
 350 extern MprVar   mprCreateObjVar(const char *name, int hashSize);
 351 extern MprVar   mprCreateBoolVar(bool value);
 352 extern MprVar   mprCreateCFunctionVar(MprCFunction fn, void *thisPtr,
 353                                         int flags);
 354 #if BLD_FEATURE_FLOATING_POINT
 355 extern MprVar   mprCreateFloatVar(double value);
 356 #endif
 357 extern MprVar   mprCreateIntegerVar(int value);
 358 #if BLD_FEATURE_INT64
 359 extern MprVar   mprCreateInteger64Var(int64 value);
 360 #endif
 361 extern MprVar   mprCreateFunctionVar(char *args, char *body, int flags);
 362 extern MprVar   mprCreateNullVar(void);
 363 extern MprVar   mprCreateNumberVar(MprNumber value);
 364 extern MprVar   mprCreateStringCFunctionVar(MprStringCFunction fn,
 365                                         void *thisPtr, int flags);
 366 extern MprVar   mprCreateStringVar(const char *value, bool allocate);
 367 extern MprVar   mprCreateUndefinedVar(void);
 368 extern bool     mprDestroyVar(MprVar *vp);
 369 extern bool     mprDestroyAllVars(MprVar* vp);
 370 extern MprType  mprGetVarType(MprVar *vp);
 371
 372 /*
 373  *      Copy
 374  */
 375 extern void             mprCopyVar(MprVar *dest, MprVar *src, int copyDepth);
 376 extern void             mprCopyVarValue(MprVar *dest, MprVar src, int copyDepth);
 377 extern MprVar   *mprDupVar(MprVar *src, int copyDepth);
 378
 379 /*
 380  *      Manage vars
 381  */
 382 extern MprVarTrigger
 383                                 mprAddVarTrigger(MprVar *vp, MprVarTrigger fn);
 384 extern int              mprGetVarRefCount(MprVar *vp);
 385 extern void     mprSetVarDeleteProtect(MprVar *vp, int deleteProtect);
 386 extern void     mprSetVarFullName(MprVar *vp, char *name);
 387 extern void     mprSetVarReadonly(MprVar *vp, int readonly);
 388 extern void     mprSetVarName(MprVar *vp, char *name);
 389
 390 /*
 391  *      Create properties and return a reference to the property.
 392  */
 393 extern MprVar   *mprCreateProperty(MprVar *obj, const char *property,
 394                                         MprVar *newValue);
 395 extern MprVar   *mprCreatePropertyValue(MprVar *obj, const char *property,
 396                                         MprVar newValue);
 397 extern int              mprDeleteProperty(MprVar *obj, const char *property);
 398
 399 /*
 400  *      Get/Set properties. Set will update/create.
 401  */
 402 extern MprVar   *mprGetProperty(MprVar *obj, const char *property, MprVar *value);
 403 extern MprVar   *mprSetProperty(MprVar *obj, const char *property, MprVar *value);
 404 extern MprVar   *mprSetPropertyValue(MprVar *obj, const char *property, MprVar value);
 405
 406 /*
 407  *      Directly read/write property values (the property must already exist)
 408  *      For mprCopyProperty, mprDestroyVar must always called on the var.
 409  */
 410 extern int              mprReadProperty(MprVar *prop, MprVar *value);
 411 extern int              mprWriteProperty(MprVar *prop, MprVar *newValue);
 412 extern int              mprWritePropertyValue(MprVar *prop, MprVar newValue);
 413
 414 /*
 415  *      Copy a property. NOTE: reverse of most other args: (dest, src)
 416  */
 417 extern int              mprCopyProperty(MprVar *dest, MprVar *prop, int copyDepth);
 418
 419 /*
 420  *      Enumerate properties
 421  */
 422 extern MprVar   *mprGetFirstProperty(MprVar *obj, int includeFlags);
 423 extern MprVar   *mprGetNextProperty(MprVar *obj, MprVar *currentProperty,
 424                                         int includeFlags);
 425
 426 /*
 427  *      Query properties characteristics
 428  */
 429 extern int              mprGetPropertyCount(MprVar *obj, int includeFlags);
 430
 431 /*
 432  *      Conversion routines
 433  */
 434 extern MprVar   mprParseVar(char *str, MprType prefType);
 435 extern MprNum   mprVarToNumber(MprVar *vp);
 436 extern int              mprVarToInteger(MprVar *vp);
 437 #if BLD_FEATURE_INT64
 438 extern int64    mprVarToInteger64(MprVar *vp);
 439 #endif
 440 extern bool     mprVarToBool(MprVar *vp);
 441 #if BLD_FEATURE_FLOATING_POINT
 442 extern double   mprVarToFloat(MprVar *vp);
 443 #endif
 444 extern void     mprVarToString(char** buf, int size, char *fmt, MprVar *vp);
 445
 446 /*
 447  *      Parsing and utility routines
 448  */
 449 extern MprNum   mprParseNumber(char *str);
 450 extern int              mprParseInteger(char *str);
 451
 452 #if BLD_FEATURE_INT64
 453 extern int64    mprParseInteger64(char *str);
 454 #endif
 455
 456 #if BLD_FEATURE_FLOATING_POINT
 457 extern double   mprParseFloat(char *str);
 458 extern bool     mprIsInfinite(double f);
 459 extern bool     mprIsNan(double f);
 460 #endif
 461
 462 #if VAR_DEBUG
 463 extern void     mprPrintObjects(char *msg);
 464 extern void     mprPrintObjRefCount(MprVar *vp);
 465 #endif
 466
 467 #ifdef __cplusplus
 468 }
 469 #endif
 470
 471 /*****************************************************************************/
 472 #endif /* _h_MPR_VAR */
 473
 474 /*
 475  * Local variables:
 476  * tab-width: 4
 477  * c-basic-offset: 4
 478  * End:
 479  * vim:tw=78
 480  * vim600: sw=4 ts=4 fdm=marker
 481  * vim<600: sw=4 ts=4
 482  */