simgear/nasal/nasal.h

   1 #ifndef _NASAL_H
   2 #define _NASAL_H
   3 #ifdef __cplusplus
   4 extern "C" {
   5 #endif
   6
   7 #ifndef BYTE_ORDER
   8
   9 # if (BSD >= 199103)
  10 #  include <machine/endian.h>
  11 # elif defined(__CYGWIN__) || defined(__MINGW32__)
  12 #  include <sys/param.h>
  13 # elif defined(linux)
  14 #  include <endian.h>
  15 # else
  16 #  ifndef LITTLE_ENDIAN
  17 #   define LITTLE_ENDIAN   1234    /* LSB first: i386, vax */
  18 #  endif
  19 #  ifndef BIG_ENDIAN
  20 #   define BIG_ENDIAN      4321    /* MSB first: 68000, ibm, net */
  21 #  endif
  22
  23 #  if defined(ultrix) || defined(__alpha__) || defined(__alpha) ||  \
  24       defined(__i386__) || defined(__i486__) || defined(_X86_) ||   \
  25       defined(sun386)
  26 #   define BYTE_ORDER LITTLE_ENDIAN
  27 #  else
  28 #   define BYTE_ORDER BIG_ENDIAN
  29 #  endif
  30 # endif /* BSD */
  31 #endif /* BYTE_ORDER */
  32
  33 #if BYTE_ORDER == BIG_ENDIAN
  34 # include <limits.h>
  35 # if (LONG_MAX == 2147483647)
  36 #  define NASAL_BIG_ENDIAN_32_BIT 1
  37 # endif
  38 #endif
  39
  40 // This is a nasal "reference".  They are always copied by value, and
  41 // contain either a pointer to a garbage-collectable nasal object
  42 // (string, vector, hash) or a floating point number.  Keeping the
  43 // number here is an optimization to prevent the generation of
  44 // zillions of tiny "number" object that have to be collected.  Note
  45 // sneaky hack: on little endian systems, placing reftag after ptr and
  46 // putting 1's in the top 13 (except the sign bit) bits makes the
  47 // double value a NaN, and thus unmistakable (no actual number can
  48 // appear as a reference, and vice versa).  Swap the structure order
  49 // on 32 bit big-endian systems.  On 64 bit sytems of either
  50 // endianness, reftag and the double won't be coincident anyway.
  51 #define NASAL_REFTAG 0x7ff56789 // == 2,146,789,257 decimal
  52 typedef union {
  53     double num;
  54     struct {
  55 #ifdef NASAL_BIG_ENDIAN_32_BIT
  56         int reftag; // Big-endian systems need this here!
  57 #endif
  58         union {
  59             struct naObj* obj;
  60             struct naStr* str;
  61             struct naVec* vec;
  62             struct naHash* hash;
  63             struct naCode* code;
  64             struct naFunc* func;
  65             struct naClosure* closure;
  66             struct naCCode* ccode;
  67             struct naGhost* ghost;
  68         } ptr;
  69 #ifndef NASAL_BIG_ENDIAN_32_BIT
  70         int reftag; // Little-endian and 64 bit systems need this here!
  71 #endif
  72     } ref;
  73 } naRef;
  74
  75 typedef struct Context* naContext;
  76
  77 // The function signature for an extension function:
  78 typedef naRef (*naCFunction)(naContext ctx, naRef args);
  79
  80 // All Nasal code runs under the watch of a naContext:
  81 naContext naNewContext();
  82
  83 // Save this object in the context, preventing it (and objects
  84 // referenced by it) from being garbage collected.
  85 void naSave(naContext ctx, naRef obj);
  86
  87 // Parse a buffer in memory into a code object.
  88 naRef naParseCode(naContext c, naRef srcFile, int firstLine,
  89                   char* buf, int len, int* errLine);
  90
  91 // Binds a bare code object (as returned from naParseCode) with a
  92 // closure object (a hash) to act as the outer scope / namespace.
  93 // FIXME: this API is weak.  It should expose the recursive nature of
  94 // closures, and allow for extracting the closure and namespace
  95 // information from function objects.
  96 naRef naBindFunction(naContext ctx, naRef code, naRef closure);
  97
  98 // Call a code or function object with the specifed arguments "on" the
  99 // specified object and using the specified hash for the local
 100 // variables.  Any of args, obj or locals may be nil.
 101 naRef naCall(naContext ctx, naRef func, naRef args, naRef obj, naRef locals);
 102
 103 // Throw an error from the current call stack.  This function makes a
 104 // longjmp call to a handler in naCall() and DOES NOT RETURN.  It is
 105 // intended for use in library code that cannot otherwise report an
 106 // error via the return value, and MUST be used carefully.  If in
 107 // doubt, return naNil() as your error condition.
 108 void naRuntimeError(naContext ctx, char* msg);
 109
 110 // Call a method on an object (NOTE: func is a function binding, *not*
 111 // a code object as returned from naParseCode).
 112 naRef naMethod(naContext ctx, naRef func, naRef object);
 113
 114 // Returns a hash containing functions from the Nasal standard library
 115 // Useful for passing as a namespace to an initial function call
 116 naRef naStdLib(naContext c);
 117
 118 // Ditto, with math functions
 119 naRef naMathLib(naContext c);
 120
 121 // Current line number & error message
 122 int naStackDepth(naContext ctx);
 123 int naGetLine(naContext ctx, int frame);
 124 naRef naGetSourceFile(naContext ctx, int frame);
 125 char* naGetError(naContext ctx);
 126
 127 // Type predicates
 128 int naIsNil(naRef r);
 129 int naIsNum(naRef r);
 130 int naIsString(naRef r);
 131 int naIsScalar(naRef r);
 132 int naIsVector(naRef r);
 133 int naIsHash(naRef r);
 134 int naIsCode(naRef r);
 135 int naIsFunc(naRef r);
 136 int naIsCCode(naRef r);
 137
 138 // Allocators/generators:
 139 naRef naNil();
 140 naRef naNum(double num);
 141 naRef naNewString(naContext c);
 142 naRef naNewVector(naContext c);
 143 naRef naNewHash(naContext c);
 144 naRef naNewFunc(naContext c, naRef code);
 145 naRef naNewCCode(naContext c, naCFunction fptr);
 146
 147 // Some useful conversion/comparison routines
 148 int naEqual(naRef a, naRef b);
 149 int naTrue(naRef b);
 150 naRef naNumValue(naRef n);
 151 naRef naStringValue(naContext c, naRef n);
 152
 153 // String utilities:
 154 int naStr_len(naRef s);
 155 char* naStr_data(naRef s);
 156 naRef naStr_fromdata(naRef dst, char* data, int len);
 157 naRef naStr_concat(naRef dest, naRef s1, naRef s2);
 158 naRef naStr_substr(naRef dest, naRef str, int start, int len);
 159
 160 // Vector utilities:
 161 int naVec_size(naRef v);
 162 naRef naVec_get(naRef v, int i);
 163 void naVec_set(naRef vec, int i, naRef o);
 164 int naVec_append(naRef vec, naRef o);
 165 naRef naVec_removelast(naRef vec);
 166 void naVec_setsize(naRef vec, int sz);
 167
 168 // Hash utilities:
 169 int naHash_size(naRef h);
 170 int naHash_get(naRef hash, naRef key, naRef* out);
 171 naRef naHash_cget(naRef hash, char* key);
 172 void naHash_set(naRef hash, naRef key, naRef val);
 173 void naHash_cset(naRef hash, char* key, naRef val);
 174 void naHash_delete(naRef hash, naRef key);
 175 void naHash_keys(naRef dst, naRef hash);
 176
 177 // Ghost utilities:
 178 typedef struct naGhostType {
 179     void (*destroy)(void* ghost);
 180 } naGhostType;
 181 naRef        naNewGhost(naContext c, naGhostType* t, void* ghost);
 182 naGhostType* naGhost_type(naRef ghost);
 183 void*        naGhost_ptr(naRef ghost);
 184 int          naIsGhost(naRef r);
 185
 186 #ifdef __cplusplus
 187 } // extern "C"
 188 #endif
 189 #endif // _NASAL_H