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