doc/pluto/FILEFORMAT

   1 $Id$
   2
   3 pluto_persist() produces a "hunk" of objects. Here's the file format adhered
   4 to by the function, and expected by pluto_unpersist().
   5
   6 As a developer, I feel that where file format information is given it is of
   7 utmost importance that that information precisely and accurately reflects the
   8 actual operation of the application. Therefore, if you find any discrepancy
   9 between this and actual operation, please lambast me thoroughly over email.
  10
  11 Pseudo-C is used to express the file format. Padding is assumed to be
  12 nonexistent. The keyword "one_of" is used to express a concept similar to
  13 "union", except that its size is the size of the actual datatype chosen. Thus,
  14 objects which contain, directly or indirectly, a one_of, may vary  in size.
  15
  16
  17 struct Object {
  18         int firstTime;          /* Whether this is the first time the object
  19                                 is being referenced */
  20         one_of {
  21                 RealObject o;   /* if firstTime == 1 */
  22                 Reference r;    /* if firstTime == 0 */
  23         };
  24 };
  25
  26 struct Reference {
  27         int ref;        /* The index the object was registered with */
  28 };
  29
  30 struct RealObject {
  31         int type;               /* The type of the object */
  32         one_of {
  33                 Boolean b;      /* If type == LUA_TBOOLEAN */
  34                 LightUserData l;        /* If type == LUA_TLIGHTUSERDATA */
  35                 Number n;       /* If type == LUA_TNUMBER */
  36                 String s;       /* If type == LUA_TSTRING */
  37                 Table t;        /* If type == LUA_TTABLE */
  38                 Function f;     /* If type == LUA_TFUNCTION */
  39                 Userdata u;     /* If type == LUA_TUSERDATA */
  40                 Thread th;      /* If type == LUA_TTHREAD */
  41                 Proto p;        /* If type == LUA_TPROTO (from lobject.h) */
  42                 Upval uv;       /* If type == LUA_TUPVAL (from lobject.h) */
  43         };                      /* The actual object */
  44 };
  45
  46 struct Boolean {
  47         int32 bvalue;           /* 0 for false, 1 for true */
  48 };
  49
  50 struct LightUserData {
  51         void* luvalue;          /* The actual, literal pointer */
  52 };
  53
  54 struct Number {
  55         lua_Number nvalue;      /* The actual number */
  56 };
  57
  58 struct String {
  59         int length;             /* The length of the string */
  60         char str[length];       /* The actual string (not null terminated) */
  61 };
  62
  63 struct Table {
  64         int isspecial;          /* 1 if SP is used; 0 otherwise */
  65         one_of {
  66                 Closure c;      /* if isspecial == 1; closure to refill the table */
  67                 LiteralTable t; /* if isspecial == 0; literal table info */
  68         };
  69 };
  70
  71 struct LiteralTable {
  72         Object metatable;       /* nil for default metatable */
  73         Pair p[];               /* key/value pairs */
  74         Object nil = nil;       /* Nil reference to terminate */
  75 };
  76
  77 struct Pair {
  78         Object key;
  79         Object value;
  80 };
  81
  82 struct Function {               /* Actually a closure */
  83         lu_byte nups;           /* Number of upvalues the function uses */
  84         Object proto;           /* The proto this function uses */
  85         Object upvals[nups];    /* All upvalues */
  86         Object fenv;            /* The FEnv (nil for the global table)
  87 };
  88
  89 struct Upval {
  90         Object obj;             /* The object this upval refers to */
  91 }
  92
  93 struct Userdata {
  94         int isSpecial;          /* 1 for special persistence, 0 for literal
  95         one_of {
  96                 LiteralUserdata lu;     /* if is_special is 0 */
  97                 SpecialUserdata su;     /* if is_special is 1 */
  98         };
  99 };
 100
 101 struct LiteralUserdata {
 102         Object metatable;               /* The metatable (nil for default) */
 103         int length;             /* Size of the data */
 104         char data[length];      /* The actual data */
 105 };
 106
 107 struct SpecialUserdata {
 108         int length;             /* The size of the data */
 109         Object func;            /* The closure used to fill the userdata */
 110 };
 111
 112 struct Thread {
 113         int stacksize;          /* The size of the stack filled with objects,
 114                                  * including the "nil" that is hidden below
 115                                  * the bottom of the stack visible to C */
 116         Object stack[stacksize];/* Indices of all stack values, bottom up */
 117         int callinfosize;       /* Number of elements in the CallInfo stack */
 118         CallInfo callinfostack[callinfosize];   /* The CallInfo stack */
 119         int base;               /* base = L->base - L->stack; */
 120         int top;                /* top = L->top - L->stack; */
 121         OpenUpval openupvals[]; /* Upvalues to open */
 122         Object nil = nil;       /* To terminate the open upvalues list */
 123 };
 124
 125 struct OpenUpval {
 126         Object upval;           /* The upvalue */
 127         int stackpos;           /* The stack position to "reopen" it to */
 128
 129 };
 130
 131 struct CallInfo {
 132         int base;               /* base = ci->base - L->stack; */
 133         int top;                /* top = ci->top - L->stack; */
 134         int pc;                 /* pc = ci->pc - proto->code; */
 135         int state;              /* flags used by the CallInfo */
 136 };
 137
 138 struct Proto {
 139         int sizek;              /* Number of constants referenced */
 140         Object k[sizek];        /* Constants referenced */
 141         int sizep;              /* Number of inner Protos referenced */
 142         Object p[sizep];        /* Inner Protos referenced */
 143         int sizecode;           /* Number of instructions in code */
 144         Instruction code[sizecode];     /* The proto's code */
 145         lu_byte nups;           /* Number of upvalues used */
 146         lu_byte numparams;      /* Number of parameters taken */
 147         lu_byte is_vararg;      /* 1 if function accepts varargs, 0 otherwise */
 148         lu_byte maxstacksize;   /* Size of stack reserved for the function */
 149 };
 150