simgear/nasal/nasal.h

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