simgear/nasal/nasal.h

   1 #ifndef _NASAL_H
   2 #define _NASAL_H
   3 #ifdef __cplusplus
   4 extern "C" {
   5 #endif
   6
   7 #include "naref.h"
   8
   9 typedef struct Context* naContext;
  10
  11 // The function signature for an extension function:
  12 typedef naRef (*naCFunction)(naContext ctx, naRef me, int argc, naRef* args);
  13
  14 // All Nasal code runs under the watch of a naContext:
  15 naContext naNewContext();
  16 void naFreeContext(naContext c);
  17
  18 // Use this when making a call to a new context "underneath" a
  19 // preexisting context on the same stack.  It allows stack walking to
  20 // see through the boundary, and eliminates the need to release the
  21 // mod lock (i.e. must be called with the mod lock held!)
  22 naContext naSubContext(naContext super);
  23
  24 // The naContext supports a user data pointer that can be used to
  25 // store data specific to an naCall invocation without exposing it to
  26 // Nasal as a ghost.  FIXME: this API is semi-dangerous, there is no
  27 // provision for sharing it, nor for validating the source or type of
  28 // the pointer returned.
  29 void naSetUserData(naContext c, void* p);
  30 void* naGetUserData(naContext c);
  31
  32 // "Save" this object in the context, preventing it (and objects
  33 // referenced by it) from being garbage collected.
  34 void naSave(naContext ctx, naRef obj);
  35
  36 // Similar, but the object is automatically released when the
  37 // context next runs native bytecode.  Useful for saving off C-space
  38 // temporaries to protect them before passing back into a naCall.
  39 void naTempSave(naContext c, naRef r);
  40
  41 // Parse a buffer in memory into a code object.  The srcFile parameter
  42 // is a Nasal string representing the "file" from which the code is
  43 // read.  The "first line" is typically 1, but is settable for
  44 // situations where the Nasal code is embedded in another context with
  45 // its own numbering convetions.  If an error occurs, returns nil and
  46 // sets the errLine pointer to point to the line at fault.  The string
  47 // representation of the error can be retrieved with naGetError() on
  48 // the context.
  49 naRef naParseCode(naContext c, naRef srcFile, int firstLine,
  50                   char* buf, int len, int* errLine);
  51
  52 // Binds a bare code object (as returned from naParseCode) with a
  53 // closure object (a hash) to act as the outer scope / namespace.
  54 naRef naBindFunction(naContext ctx, naRef code, naRef closure);
  55
  56 // Similar, but it binds to the current context's closure (i.e. the
  57 // namespace at the top of the current call stack).
  58 naRef naBindToContext(naContext ctx, naRef code);
  59
  60 // Call a code or function object with the specified arguments "on"
  61 // the specified object and using the specified hash for the local
  62 // variables.  Passing a null args array skips the parameter variables
  63 // (e.g. "arg") assignments; to get a zero-length arg instead, pass in
  64 // argc==0 and a non-null args vector.  The obj or locals parameters
  65 // may be nil.  Will attempt to acquire the mod lock, so call
  66 // naModUnlock() first if the lock is already held.
  67 naRef naCall(naContext ctx, naRef func, int argc, naRef* args,
  68              naRef obj, naRef locals);
  69
  70 // As naCall(), but continues execution at the operation after a
  71 // previous die() call or runtime error.  Useful to do "yield"
  72 // semantics, leaving the context in a condition where it can be
  73 // restarted from C code.  Cannot be used currently to restart a
  74 // failed operation.  Will attempt to acquire the mod lock, so call
  75 // naModUnlock() first if the lock is already held.
  76 naRef naContinue(naContext ctx);
  77
  78 // Throw an error from the current call stack.  This function makes a
  79 // longjmp call to a handler in naCall() and DOES NOT RETURN.  It is
  80 // intended for use in library code that cannot otherwise report an
  81 // error via the return value, and MUST be used carefully.  If in
  82 // doubt, return naNil() as your error condition.  Works like
  83 // printf().
  84 void naRuntimeError(naContext c, const char* fmt, ...);
  85
  86 // "Re-throws" a runtime error caught from the subcontext.  Acts as a
  87 // naRuntimeError() called on the parent context.  Does not return.
  88 void naRethrowError(naContext subc);
  89
  90 // Retrieve the specified member from the object, respecting the
  91 // "parents" array as for "object.field".  Returns zero for missing
  92 // fields.
  93 int naMember_get(naRef obj, naRef field, naRef* out);
  94 int naMember_cget(naRef obj, const char* field, naRef* out);
  95
  96 // Returns a hash containing functions from the Nasal standard library
  97 // Useful for passing as a namespace to an initial function call
  98 naRef naInit_std(naContext c);
  99
 100 // Ditto, for other core libraries
 101 naRef naInit_math(naContext c);
 102 naRef naInit_bits(naContext c);
 103 naRef naInit_io(naContext c);
 104 naRef naInit_regex(naContext c);
 105 naRef naInit_unix(naContext c);
 106 naRef naInit_thread(naContext c);
 107 naRef naInit_utf8(naContext c);
 108 naRef naInit_sqlite(naContext c);
 109 naRef naInit_readline(naContext c);
 110 naRef naInit_gtk(naContext ctx);
 111 naRef naInit_cairo(naContext ctx);
 112
 113 // Context stack inspection, frame zero is the "top"
 114 int naStackDepth(naContext ctx);
 115 int naGetLine(naContext ctx, int frame);
 116 naRef naGetSourceFile(naContext ctx, int frame);
 117 char* naGetError(naContext ctx);
 118
 119 // Type predicates
 120 int naIsNil(naRef r);
 121 int naIsNum(naRef r);
 122 int naIsString(naRef r);
 123 int naIsScalar(naRef r);
 124 int naIsVector(naRef r);
 125 int naIsHash(naRef r);
 126 int naIsCode(naRef r);
 127 int naIsFunc(naRef r);
 128 int naIsCCode(naRef r);
 129
 130 // Allocators/generators:
 131 naRef naNil();
 132 naRef naNum(double num);
 133 naRef naNewString(naContext c);
 134 naRef naNewVector(naContext c);
 135 naRef naNewHash(naContext c);
 136 naRef naNewFunc(naContext c, naRef code);
 137 naRef naNewCCode(naContext c, naCFunction fptr);
 138
 139 // Some useful conversion/comparison routines
 140 int naEqual(naRef a, naRef b);
 141 int naStrEqual(naRef a, naRef b);
 142 int naTrue(naRef b);
 143 naRef naNumValue(naRef n);
 144 naRef naStringValue(naContext c, naRef n);
 145
 146 // String utilities:
 147 int naStr_len(naRef s);
 148 char* naStr_data(naRef s);
 149 naRef naStr_fromdata(naRef dst, char* data, int len);
 150 naRef naStr_concat(naRef dest, naRef s1, naRef s2);
 151 naRef naStr_substr(naRef dest, naRef str, int start, int len);
 152 naRef naInternSymbol(naRef sym);
 153
 154 // Vector utilities:
 155 int naVec_size(naRef v);
 156 naRef naVec_get(naRef v, int i);
 157 void naVec_set(naRef vec, int i, naRef o);
 158 int naVec_append(naRef vec, naRef o);
 159 naRef naVec_removelast(naRef vec);
 160 void naVec_setsize(naRef vec, int sz);
 161
 162 // Hash utilities:
 163 int naHash_size(naRef h);
 164 int naHash_get(naRef hash, naRef key, naRef* out);
 165 naRef naHash_cget(naRef hash, char* key);
 166 void naHash_set(naRef hash, naRef key, naRef val);
 167 void naHash_cset(naRef hash, char* key, naRef val);
 168 void naHash_delete(naRef hash, naRef key);
 169 void naHash_keys(naRef dst, naRef hash);
 170
 171 // Ghost utilities:
 172 typedef struct naGhostType {
 173     void (*destroy)(void* ghost);
 174     const char* name;
 175 } naGhostType;
 176 naRef        naNewGhost(naContext c, naGhostType* t, void* ghost);
 177 naGhostType* naGhost_type(naRef ghost);
 178 void*        naGhost_ptr(naRef ghost);
 179 int          naIsGhost(naRef r);
 180
 181 // Acquires a "modification lock" on a context, allowing the C code to
 182 // modify Nasal data without fear that such data may be "lost" by the
 183 // garbage collector (nasal data the C stack is not examined in GC!).
 184 // This disallows garbage collection until the current thread can be
 185 // blocked.  The lock should be acquired whenever nasal objects are
 186 // being modified.  It need not be acquired when only read access is
 187 // needed, PRESUMING that the Nasal data being read is findable by the
 188 // collector (via naSave, for example) and that another Nasal thread
 189 // cannot or will not delete the reference to the data.  It MUST NOT
 190 // be acquired by naCFunction's, as those are called with the lock
 191 // already held; acquiring two locks for the same thread will cause a
 192 // deadlock when the GC is invoked.  It should be UNLOCKED by
 193 // naCFunction's when they are about to do any long term non-nasal
 194 // processing and/or blocking I/O.  Note that naModLock() may need to
 195 // block to allow garbage collection to occur, and that garbage
 196 // collection by other threads may be blocked until naModUnlock() is
 197 // called.  It must also be UNLOCKED by threads that hold a lock
 198 // already before making a naCall() or naContinue() call -- these
 199 // functions will attempt to acquire the lock again.
 200 void naModLock();
 201 void naModUnlock();
 202
 203 // Library utilities.  Generate namespaces and add symbols.
 204 typedef struct { char* name; naCFunction func; } naCFuncItem;
 205 naRef naGenLib(naContext c, naCFuncItem *funcs);
 206 void naAddSym(naContext c, naRef ns, char *sym, naRef val);
 207
 208 #ifdef __cplusplus
 209 } // extern "C"
 210 #endif
 211 #endif // _NASAL_H