jim.h

   1 /* Jim - A small embeddable Tcl interpreter
   2  *
   3  * Copyright 2005 Salvatore Sanfilippo <antirez@invece.org>
   4  * Copyright 2005 Clemens Hintze <c.hintze@gmx.net>
   5  * Copyright 2005 patthoyts - Pat Thoyts <patthoyts@users.sf.net>
   6  * Copyright 2008 oharboe - Øyvind Harboe - oyvind.harboe@zylin.com
   7  * Copyright 2008 Andrew Lunn <andrew@lunn.ch>
   8  * Copyright 2008 Duane Ellis <openocd@duaneellis.com>
   9  * Copyright 2008 Uwe Klein <uklein@klein-messgeraete.de>
  10  *
  11  * The FreeBSD license
  12  *
  13  * Redistribution and use in source and binary forms, with or without
  14  * modification, are permitted provided that the following conditions
  15  * are met:
  16  *
  17  * 1. Redistributions of source code must retain the above copyright
  18  *    notice, this list of conditions and the following disclaimer.
  19  * 2. Redistributions in binary form must reproduce the above
  20  *    copyright notice, this list of conditions and the following
  21  *    disclaimer in the documentation and/or other materials
  22  *    provided with the distribution.
  23  *
  24  * THIS SOFTWARE IS PROVIDED BY THE JIM TCL PROJECT ``AS IS'' AND ANY
  25  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  26  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  27  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  28  * JIM TCL PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  29  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  30  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  31  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  32  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  33  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  34  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  35  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  36  *
  37  * The views and conclusions contained in the software and documentation
  38  * are those of the authors and should not be interpreted as representing
  39  * official policies, either expressed or implied, of the Jim Tcl Project.
  40  *
  41  *--- Inline Header File Documentation ---
  42  *    [By Duane Ellis, openocd@duaneellis.com, 8/18/8]
  43  *
  44  * Belief is "Jim" would greatly benifit if Jim Internals where
  45  * documented in some way - form whatever, and perhaps - the package:
  46  * 'doxygen' is the correct approach to do that.
  47  *
  48  *   Details, see: http://www.stack.nl/~dimitri/doxygen/
  49  *
  50  * To that end please follow these guide lines:
  51  *
  52  *    (A) Document the PUBLIC api in the .H file.
  53  *
  54  *    (B) Document JIM Internals, in the .C file.
  55  *
  56  *    (C) Remember JIM is embedded in other packages, to that end do
  57  *    not assume that your way of documenting is the right way, Jim's
  58  *    public documentation should be agnostic, such that it is some
  59  *    what agreeable with the "package" that is embedding JIM inside
  60  *    of it's own doxygen documentation.
  61  *
  62  *    (D) Use minimal Doxygen tags.
  63  *
  64  * This will be an "ongoing work in progress" for some time.
  65  **/
  66
  67 #ifndef __JIM__H
  68 #define __JIM__H
  69
  70 #ifdef __cplusplus
  71 extern "C" {
  72 #endif
  73
  74 #include <time.h>
  75 #include <limits.h>
  76 #include <stdio.h>  /* for the FILE typedef definition */
  77 #include <stdlib.h> /* In order to export the Jim_Free() macro */
  78 #include <stdarg.h> /* In order to get type va_list */
  79
  80 /* -----------------------------------------------------------------------------
  81  * System configuration
  82  * autoconf (configure) will set these
  83  * ---------------------------------------------------------------------------*/
  84 #if (defined(_WIN32) || defined(WIN32)) && !defined(__MINGW32__)
  85 #include <jim-win32compat.h>
  86 #else
  87
  88 #if defined(__MINGW32__)
  89 #define JIM_ANSIC
  90 #endif
  91
  92 #if !defined(JIM_ANSIC) && !defined(NOMMU)
  93 #define JIM_DYNLIB      /* Dynamic library support */
  94 #endif
  95
  96 #ifndef HAVE_NO_AUTOCONF
  97 #include <autoconf.h>
  98 #endif
  99
 100 /* -----------------------------------------------------------------------------
 101  * Compiler specific fixes.
 102  * ---------------------------------------------------------------------------*/
 103
 104 /* Long Long type and related issues */
 105 #ifdef HAVE_LONG_LONG
 106 #  define jim_wide long long
 107 #  ifndef LLONG_MAX
 108 #    define LLONG_MAX    9223372036854775807LL
 109 #  endif
 110 #  ifndef LLONG_MIN
 111 #    define LLONG_MIN    (-LLONG_MAX - 1LL)
 112 #  endif
 113 #  define JIM_WIDE_MIN LLONG_MIN
 114 #  define JIM_WIDE_MAX LLONG_MAX
 115 #else
 116 #  define jim_wide long
 117 #  define JIM_WIDE_MIN LONG_MIN
 118 #  define JIM_WIDE_MAX LONG_MAX
 119 #  define strtoull strtoul
 120 #endif
 121
 122 /* -----------------------------------------------------------------------------
 123  * LIBC specific fixes
 124  * ---------------------------------------------------------------------------*/
 125
 126 #ifdef HAVE_LONG_LONG
 127 #  define JIM_WIDE_MODIFIER "lld"
 128 #else
 129 #  define JIM_WIDE_MODIFIER "ld"
 130 #endif
 131
 132 #endif
 133
 134 /* -----------------------------------------------------------------------------
 135  * Exported defines
 136  * ---------------------------------------------------------------------------*/
 137
 138 /* Jim version numbering: every version of jim is marked with a
 139  * successive integer number. This is version 0. The first
 140  * stable version will be 1, then 2, 3, and so on. */
 141 #define JIM_VERSION 63
 142
 143 #define JIM_OK 0
 144 #define JIM_ERR 1
 145 #define JIM_RETURN 2
 146 #define JIM_BREAK 3
 147 #define JIM_CONTINUE 4
 148 #define JIM_SIGNAL 5
 149 #define JIM_EXIT 6
 150 /* The following are internal codes and should never been seen/used */
 151 #define JIM_EVAL 7
 152
 153 #define JIM_MAX_NESTING_DEPTH 10000 /* default max nesting depth */
 154
 155 /* Some function get an integer argument with flags to change
 156  * the behaviour. */
 157 #define JIM_NONE 0    /* no flags set */
 158 #define JIM_ERRMSG 1    /* set an error message in the interpreter. */
 159
 160 /* Flags for Jim_SubstObj() */
 161 #define JIM_SUBST_NOVAR 1 /* don't perform variables substitutions */
 162 #define JIM_SUBST_NOCMD 2 /* don't perform command substitutions */
 163 #define JIM_SUBST_NOESC 4 /* don't perform escapes substitutions */
 164 #define JIM_SUBST_FLAG 128 /* flag to indicate that this is a real substition object */
 165
 166 /* Unused arguments generate annoying warnings... */
 167 #define JIM_NOTUSED(V) ((void) V)
 168
 169 /* Flags for Jim_GetEnum() */
 170 #define JIM_ENUM_ABBREV 2    /* Allow unambiguous abbreviation */
 171
 172 /* Flags used by API calls getting a 'nocase' argument. */
 173 #define JIM_CASESENS    0   /* case sensitive */
 174 #define JIM_NOCASE      1   /* no case */
 175
 176 /* Filesystem related */
 177 #define JIM_PATH_LEN 1024
 178
 179 /* Newline, some embedded system may need -DJIM_CRLF */
 180 #ifdef JIM_CRLF
 181 #define JIM_NL "\r\n"
 182 #else
 183 #define JIM_NL "\n"
 184 #endif
 185
 186 #ifdef JIM_TCL_COMPAT
 187 #define JIM_LIBPATH "auto_path"
 188 #define JIM_INTERACTIVE "tcl_interactive"
 189 #else
 190 #define JIM_LIBPATH "jim_libpath"
 191 #define JIM_INTERACTIVE "jim_interactive"
 192 #endif
 193
 194 /* -----------------------------------------------------------------------------
 195  * Stack
 196  * ---------------------------------------------------------------------------*/
 197
 198 typedef struct Jim_Stack {
 199     int len;
 200     int maxlen;
 201     void **vector;
 202 } Jim_Stack;
 203
 204 /* -----------------------------------------------------------------------------
 205  * Hash table
 206  * ---------------------------------------------------------------------------*/
 207
 208 typedef struct Jim_HashEntry {
 209     const void *key;
 210     void *val;
 211     struct Jim_HashEntry *next;
 212 } Jim_HashEntry;
 213
 214 typedef struct Jim_HashTableType {
 215     unsigned int (*hashFunction)(const void *key);
 216     const void *(*keyDup)(void *privdata, const void *key);
 217     void *(*valDup)(void *privdata, const void *obj);
 218     int (*keyCompare)(void *privdata, const void *key1, const void *key2);
 219     void (*keyDestructor)(void *privdata, const void *key);
 220     void (*valDestructor)(void *privdata, void *obj);
 221 } Jim_HashTableType;
 222
 223 typedef struct Jim_HashTable {
 224     Jim_HashEntry **table;
 225     const Jim_HashTableType *type;
 226     unsigned int size;
 227     unsigned int sizemask;
 228     unsigned int used;
 229     unsigned int collisions;
 230     void *privdata;
 231 } Jim_HashTable;
 232
 233 typedef struct Jim_HashTableIterator {
 234     Jim_HashTable *ht;
 235     int index;
 236     Jim_HashEntry *entry, *nextEntry;
 237 } Jim_HashTableIterator;
 238
 239 /* This is the initial size of every hash table */
 240 #define JIM_HT_INITIAL_SIZE     16
 241
 242 /* ------------------------------- Macros ------------------------------------*/
 243 #define Jim_FreeEntryVal(ht, entry) \
 244     if ((ht)->type->valDestructor) \
 245         (ht)->type->valDestructor((ht)->privdata, (entry)->val)
 246
 247 #define Jim_SetHashVal(ht, entry, _val_) do { \
 248     if ((ht)->type->valDup) \
 249         entry->val = (ht)->type->valDup((ht)->privdata, _val_); \
 250     else \
 251         entry->val = (_val_); \
 252 } while(0)
 253
 254 #define Jim_FreeEntryKey(ht, entry) \
 255     if ((ht)->type->keyDestructor) \
 256         (ht)->type->keyDestructor((ht)->privdata, (entry)->key)
 257
 258 #define Jim_SetHashKey(ht, entry, _key_) do { \
 259     if ((ht)->type->keyDup) \
 260         entry->key = (ht)->type->keyDup((ht)->privdata, _key_); \
 261     else \
 262         entry->key = (_key_); \
 263 } while(0)
 264
 265 #define Jim_CompareHashKeys(ht, key1, key2) \
 266     (((ht)->type->keyCompare) ? \
 267         (ht)->type->keyCompare((ht)->privdata, key1, key2) : \
 268         (key1) == (key2))
 269
 270 #define Jim_HashKey(ht, key) (ht)->type->hashFunction(key)
 271
 272 #define Jim_GetHashEntryKey(he) ((he)->key)
 273 #define Jim_GetHashEntryVal(he) ((he)->val)
 274 #define Jim_GetHashTableCollisions(ht) ((ht)->collisions)
 275 #define Jim_GetHashTableSize(ht) ((ht)->size)
 276 #define Jim_GetHashTableUsed(ht) ((ht)->used)
 277
 278 /* -----------------------------------------------------------------------------
 279  * Jim_Obj structure
 280  * ---------------------------------------------------------------------------*/
 281
 282 /* -----------------------------------------------------------------------------
 283  * Jim object. This is mostly the same as Tcl_Obj itself,
 284  * with the addition of the 'prev' and 'next' pointers.
 285  * In Jim all the objects are stored into a linked list for GC purposes,
 286  * so that it's possible to access every object living in a given interpreter
 287  * sequentially. When an object is freed, it's moved into a different
 288  * linked list, used as object pool.
 289  *
 290  * The refcount of a freed object is always -1.
 291  * ---------------------------------------------------------------------------*/
 292 typedef struct Jim_Obj {
 293     int refCount; /* reference count */
 294     char *bytes; /* string representation buffer. NULL = no string repr. */
 295     int length; /* number of bytes in 'bytes', not including the numterm. */
 296     const struct Jim_ObjType *typePtr; /* object type. */
 297     /* Internal representation union */
 298     union {
 299         /* integer number type */
 300         jim_wide wideValue;
 301         /* hashed object type value */
 302         int hashValue;
 303         /* index type */
 304         int indexValue;
 305         /* return code type */
 306         int returnCode;
 307         /* double number type */
 308         double doubleValue;
 309         /* Generic pointer */
 310         void *ptr;
 311         /* Generic two pointers value */
 312         struct {
 313             void *ptr1;
 314             void *ptr2;
 315         } twoPtrValue;
 316         /* Variable object */
 317         struct {
 318             unsigned jim_wide callFrameId;
 319             struct Jim_Var *varPtr;
 320         } varValue;
 321         /* Command object */
 322         struct {
 323             unsigned jim_wide procEpoch;
 324             struct Jim_Cmd *cmdPtr;
 325         } cmdValue;
 326         /* List object */
 327         struct {
 328             struct Jim_Obj **ele;    /* Elements vector */
 329             int len;        /* Length */
 330             int maxLen;        /* Allocated 'ele' length */
 331         } listValue;
 332         /* String type */
 333         struct {
 334             int maxLength;
 335         } strValue;
 336         /* Reference type */
 337         struct {
 338             jim_wide id;
 339             struct Jim_Reference *refPtr;
 340         } refValue;
 341         /* Source type */
 342         struct {
 343             const char *fileName;
 344             int lineNumber;
 345         } sourceValue;
 346         /* Dict substitution type */
 347         struct {
 348             struct Jim_Obj *varNameObjPtr;
 349             struct Jim_Obj *indexObjPtr;
 350         } dictSubstValue;
 351         /* tagged binary type */
 352         struct {
 353             unsigned char *data;
 354             size_t         len;
 355         } binaryValue;
 356         /* Regular expression pattern */
 357         struct {
 358             unsigned flags;
 359             void *compre;       /* really an allocated (regex_t *) */
 360         } regexpValue;
 361     } internalRep;
 362     /* This are 8 or 16 bytes more for every object
 363      * but this is required for efficient garbage collection
 364      * of Jim references. */
 365     struct Jim_Obj *prevObjPtr; /* pointer to the prev object. */
 366     struct Jim_Obj *nextObjPtr; /* pointer to the next object. */
 367 } Jim_Obj;
 368
 369 /* Jim_Obj related macros */
 370 #define Jim_IncrRefCount(objPtr) \
 371     ++(objPtr)->refCount
 372 #define Jim_DecrRefCount(interp, objPtr) \
 373     if (--(objPtr)->refCount <= 0) Jim_FreeObj(interp, objPtr)
 374 #define Jim_IsShared(objPtr) \
 375     ((objPtr)->refCount > 1)
 376
 377 /* This macro is used when we allocate a new object using
 378  * Jim_New...Obj(), but for some error we need to destroy it.
 379  * Instead to use Jim_IncrRefCount() + Jim_DecrRefCount() we
 380  * can just call Jim_FreeNewObj. To call Jim_Free directly
 381  * seems too raw, the object handling may change and we want
 382  * that Jim_FreeNewObj() can be called only against objects
 383  * that are belived to have refcount == 0. */
 384 #define Jim_FreeNewObj Jim_FreeObj
 385
 386 /* Free the internal representation of the object. */
 387 #define Jim_FreeIntRep(i,o) \
 388     if ((o)->typePtr && (o)->typePtr->freeIntRepProc) \
 389         (o)->typePtr->freeIntRepProc(i, o)
 390
 391 /* Get the internal representation pointer */
 392 #define Jim_GetIntRepPtr(o) (o)->internalRep.ptr
 393
 394 /* Set the internal representation pointer */
 395 #define Jim_SetIntRepPtr(o, p) \
 396     (o)->internalRep.ptr = (p)
 397
 398 /* The object type structure.
 399  * There are four methods.
 400  *
 401  * - FreeIntRep is used to free the internal representation of the object.
 402  *   Can be NULL if there is nothing to free.
 403  * - DupIntRep is used to duplicate the internal representation of the object.
 404  *   If NULL, when an object is duplicated, the internalRep union is
 405  *   directly copied from an object to another.
 406  *   Note that it's up to the caller to free the old internal repr of the
 407  *   object before to call the Dup method.
 408  * - UpdateString is used to create the string from the internal repr.
 409  * - setFromAny is used to convert the current object into one of this type.
 410  */
 411
 412 struct Jim_Interp;
 413
 414 typedef void (Jim_FreeInternalRepProc)(struct Jim_Interp *interp,
 415         struct Jim_Obj *objPtr);
 416 typedef void (Jim_DupInternalRepProc)(struct Jim_Interp *interp,
 417         struct Jim_Obj *srcPtr, Jim_Obj *dupPtr);
 418 typedef void (Jim_UpdateStringProc)(struct Jim_Obj *objPtr);
 419
 420 typedef struct Jim_ObjType {
 421     const char *name; /* The name of the type. */
 422     Jim_FreeInternalRepProc *freeIntRepProc;
 423     Jim_DupInternalRepProc *dupIntRepProc;
 424     Jim_UpdateStringProc *updateStringProc;
 425     int flags;
 426 } Jim_ObjType;
 427
 428 /* Jim_ObjType flags */
 429 #define JIM_TYPE_NONE 0        /* No flags */
 430 #define JIM_TYPE_REFERENCES 1    /* The object may contain referneces. */
 431
 432 /* Starting from 1 << 20 flags are reserved for private uses of
 433  * different calls. This way the same 'flags' argument may be used
 434  * to pass both global flags and private flags. */
 435 #define JIM_PRIV_FLAG_SHIFT 20
 436
 437 /* -----------------------------------------------------------------------------
 438  * Call frame, vars, commands structures
 439  * ---------------------------------------------------------------------------*/
 440
 441 /* Call frame */
 442 typedef struct Jim_CallFrame {
 443     unsigned jim_wide id; /* Call Frame ID. Used for caching. */
 444     struct Jim_HashTable vars; /* Where local vars are stored */
 445     struct Jim_HashTable *staticVars; /* pointer to procedure static vars */
 446     struct Jim_CallFrame *parentCallFrame;
 447     Jim_Obj *const *argv; /* object vector of the current procedure call. */
 448     int argc; /* number of args of the current procedure call. */
 449     Jim_Obj *procArgsObjPtr; /* arglist object of the running procedure */
 450     Jim_Obj *procBodyObjPtr; /* body object of the running procedure */
 451     struct Jim_CallFrame *nextFramePtr;
 452     const char *filename;       /* file and line of caller of this proc (if available) */
 453     int line;
 454 } Jim_CallFrame;
 455
 456 /* The var structure. It just holds the pointer of the referenced
 457  * object. If linkFramePtr is not NULL the variable is a link
 458  * to a variable of name store on objPtr living on the given callframe
 459  * (this happens when the [global] or [upvar] command is used).
 460  * The interp in order to always know how to free the Jim_Obj associated
 461  * with a given variable because In Jim objects memory managment is
 462  * bound to interpreters. */
 463 typedef struct Jim_Var {
 464     Jim_Obj *objPtr;
 465     struct Jim_CallFrame *linkFramePtr;
 466 } Jim_Var;
 467
 468 /* The cmd structure. */
 469 typedef int (*Jim_CmdProc)(struct Jim_Interp *interp, int argc,
 470     Jim_Obj *const *argv);
 471 typedef void (*Jim_DelCmdProc)(struct Jim_Interp *interp, void *privData);
 472
 473 /* A command is implemented in C if funcPtr is != NULL, otherwise
 474  * it's a Tcl procedure with the arglist and body represented by the
 475  * two objects referenced by arglistObjPtr and bodyoObjPtr. */
 476 typedef struct Jim_Cmd {
 477     int inUse;           /* Reference count */
 478     Jim_CmdProc cmdProc; /* Not-NULL for a C command. */
 479     void *privData; /* Only used for C commands. */
 480     Jim_DelCmdProc delProc; /* Called when the command is deleted if != NULL */
 481     Jim_Obj *argListObjPtr;
 482     Jim_Obj *bodyObjPtr;
 483     Jim_HashTable *staticVars; /* Static vars hash table. NULL if no statics. */
 484     int leftArity;    /* Required args assigned from the left */
 485     int optionalArgs; /* Number of optional args (default values) */
 486     int rightArity;   /* Required args assigned from the right */
 487     int args;         /* True if 'args' specified */
 488 } Jim_Cmd;
 489
 490 /* Pseudo Random Number Generator State structure */
 491 typedef struct Jim_PrngState {
 492     unsigned char sbox[256];
 493     unsigned int i, j;
 494 } Jim_PrngState;
 495
 496 /* -----------------------------------------------------------------------------
 497  * Jim interpreter structure.
 498  * Fields similar to the real Tcl interpreter structure have the same names.
 499  * ---------------------------------------------------------------------------*/
 500 typedef struct Jim_Interp {
 501     Jim_Obj *result; /* object returned by the last command called. */
 502     int errorLine; /* Error line where an error occurred. */
 503     char *errorFileName; /* Error file where an error occurred. */
 504     int addStackTrace; /* > 0 If a level should be added to the stack trace */
 505     int numLevels; /* Number of current nested calls. */
 506     int maxNestingDepth; /* Used for infinite loop detection. */
 507     int returnCode; /* Completion code to return on JIM_RETURN. */
 508     int returnLevel; /* Current level of 'return -level' */
 509     int exitCode; /* Code to return to the OS on JIM_EXIT. */
 510     long id; /* Hold unique id for various purposes */
 511     int signal_level; /* A nesting level of catch -signal */
 512     jim_wide sigmask;  /* Bit mask of caught signals, or 0 if none */
 513     int (*signal_set_result)(struct Jim_Interp *interp, jim_wide sigmask); /* Set a result for the sigmask */
 514     Jim_CallFrame *framePtr; /* Pointer to the current call frame */
 515     Jim_CallFrame *topFramePtr; /* toplevel/global frame pointer. */
 516     struct Jim_HashTable commands; /* Commands hash table */
 517     unsigned jim_wide procEpoch; /* Incremented every time the result
 518                 of procedures names lookup caching
 519                 may no longer be valid. */
 520     unsigned jim_wide callFrameEpoch; /* Incremented every time a new
 521                 callframe is created. This id is used for the
 522                 'ID' field contained in the Jim_CallFrame
 523                 structure. */
 524     Jim_Obj *liveList; /* Linked list of all the live objects. */
 525     Jim_Obj *freeList; /* Linked list of all the unused objects. */
 526     Jim_Obj *currentScriptObj; /* Script currently in execution. */
 527     Jim_Obj *emptyObj; /* Shared empty string object. */
 528     Jim_Obj *trueObj; /* Shared true int object. */
 529     Jim_Obj *falseObj; /* Shared false int object. */
 530     unsigned jim_wide referenceNextId; /* Next id for reference. */
 531     struct Jim_HashTable references; /* References hash table. */
 532     jim_wide lastCollectId; /* reference max Id of the last GC
 533                 execution. It's set to -1 while the collection
 534                 is running as sentinel to avoid to recursive
 535                 calls via the [collect] command inside
 536                 finalizers. */
 537     time_t lastCollectTime; /* unix time of the last GC execution */
 538     struct Jim_HashTable sharedStrings; /* Shared Strings hash table */
 539     Jim_Obj *stackTrace; /* Stack trace object. */
 540     Jim_Obj *errorProc; /* Name of last procedure which returned an error */
 541     Jim_Obj *unknown; /* Unknown command cache */
 542     int unknown_called; /* The unknown command has been invoked */
 543     int errorFlag; /* Set if an error occurred during execution. */
 544     void *cmdPrivData; /* Used to pass the private data pointer to
 545                   a command. It is set to what the user specified
 546                   via Jim_CreateCommand(). */
 547
 548     struct Jim_CallFrame *freeFramesList; /* list of CallFrame structures. */
 549     struct Jim_HashTable assocData; /* per-interp storage for use by packages */
 550     Jim_PrngState *prngState; /* per interpreter Random Number Gen. state. */
 551     struct Jim_HashTable packages; /* Provided packages hash table */
 552     Jim_Stack *localProcs; /* procs to be destroyed on end of evaluation */
 553 } Jim_Interp;
 554
 555 /* Currently provided as macro that performs the increment.
 556  * At some point may be a real function doing more work.
 557  * The proc epoch is used in order to know when a command lookup
 558  * cached can no longer considered valid. */
 559 #define Jim_InterpIncrProcEpoch(i) (i)->procEpoch++
 560 #define Jim_SetResultString(i,s,l) Jim_SetResult(i, Jim_NewStringObj(i,s,l))
 561 #define Jim_SetResultInt(i,intval) Jim_SetResult(i, Jim_NewIntObj(i,intval))
 562 /* Note: Using trueObj and falseObj here makes some things slower...*/
 563 #define Jim_SetResultBool(i,b) Jim_SetResultInt(i, b)
 564 #define Jim_SetEmptyResult(i) Jim_SetResult(i, (i)->emptyObj)
 565 #define Jim_GetResult(i) ((i)->result)
 566 #define Jim_CmdPrivData(i) ((i)->cmdPrivData)
 567
 568 /* Note that 'o' is expanded only one time inside this macro,
 569  * so it's safe to use side effects. */
 570 #define Jim_SetResult(i,o) do {     \
 571     Jim_Obj *_resultObjPtr_ = (o);    \
 572     Jim_IncrRefCount(_resultObjPtr_); \
 573     Jim_DecrRefCount(i,(i)->result);  \
 574     (i)->result = _resultObjPtr_;     \
 575 } while(0)
 576
 577 /* Use this for filehandles, etc. which need a unique id */
 578 #define Jim_GetId(i) (++(i)->id)
 579
 580 /* Reference structure. The interpreter pointer is held within privdata member in HashTable */
 581 #define JIM_REFERENCE_TAGLEN 7 /* The tag is fixed-length, because the reference
 582                                   string representation must be fixed length. */
 583 typedef struct Jim_Reference {
 584     Jim_Obj *objPtr;
 585     Jim_Obj *finalizerCmdNamePtr;
 586     char tag[JIM_REFERENCE_TAGLEN+1];
 587 } Jim_Reference;
 588
 589 /* -----------------------------------------------------------------------------
 590  * Exported API prototypes.
 591  * ---------------------------------------------------------------------------*/
 592
 593 /* Macros that are common for extensions and core. */
 594 #define Jim_NewEmptyStringObj(i) Jim_NewStringObj(i, "", 0)
 595
 596 /* The core includes real prototypes, extensions instead
 597  * include a global function pointer for every function exported.
 598  * Once the extension calls Jim_InitExtension(), the global
 599  * functon pointers are set to the value of the STUB table
 600  * contained in the Jim_Interp structure.
 601  *
 602  * This makes Jim able to load extensions even if it is statically
 603  * linked itself, and to load extensions compiled with different
 604  * versions of Jim (as long as the API is still compatible.) */
 605
 606 /* Macros are common for core and extensions */
 607 #define Jim_FreeHashTableIterator(iter) Jim_Free(iter)
 608
 609 #define JIM_EXPORT
 610
 611 /* Memory allocation */
 612 JIM_EXPORT void * Jim_Alloc (int size);
 613 JIM_EXPORT void Jim_Free (void *ptr);
 614 JIM_EXPORT char * Jim_StrDup (const char *s);
 615 JIM_EXPORT char *Jim_StrDupLen(const char *s, int l);
 616
 617 /* evaluation */
 618 JIM_EXPORT int Jim_Eval(Jim_Interp *interp, const char *script);
 619 /* in C code, you can do this and get better error messages */
 620 /*   Jim_Eval_Named( interp, "some tcl commands", __FILE__, __LINE__ ); */
 621 JIM_EXPORT int Jim_Eval_Named(Jim_Interp *interp, const char *script,const char *filename, int lineno);
 622 JIM_EXPORT int Jim_EvalGlobal(Jim_Interp *interp, const char *script);
 623 JIM_EXPORT int Jim_EvalFile(Jim_Interp *interp, const char *filename);
 624 JIM_EXPORT int Jim_EvalObj (Jim_Interp *interp, Jim_Obj *scriptObjPtr);
 625 JIM_EXPORT int Jim_EvalObjBackground (Jim_Interp *interp,
 626         Jim_Obj *scriptObjPtr);
 627 JIM_EXPORT int Jim_EvalObjVector (Jim_Interp *interp, int objc,
 628         Jim_Obj *const *objv);
 629 JIM_EXPORT int Jim_SubstObj (Jim_Interp *interp, Jim_Obj *substObjPtr,
 630         Jim_Obj **resObjPtrPtr, int flags);
 631
 632 /* stack */
 633 JIM_EXPORT void Jim_InitStack(Jim_Stack *stack);
 634 JIM_EXPORT void Jim_FreeStack(Jim_Stack *stack);
 635 JIM_EXPORT int Jim_StackLen(Jim_Stack *stack);
 636 JIM_EXPORT void Jim_StackPush(Jim_Stack *stack, void *element);
 637 JIM_EXPORT void * Jim_StackPop(Jim_Stack *stack);
 638 JIM_EXPORT void * Jim_StackPeek(Jim_Stack *stack);
 639 JIM_EXPORT void Jim_FreeStackElements(Jim_Stack *stack, void (*freeFunc)(void *ptr));
 640
 641 /* hash table */
 642 JIM_EXPORT int Jim_InitHashTable (Jim_HashTable *ht,
 643         const Jim_HashTableType *type, void *privdata);
 644 JIM_EXPORT int Jim_ExpandHashTable (Jim_HashTable *ht,
 645         unsigned int size);
 646 JIM_EXPORT int Jim_AddHashEntry (Jim_HashTable *ht, const void *key,
 647         void *val);
 648 JIM_EXPORT int Jim_ReplaceHashEntry (Jim_HashTable *ht,
 649         const void *key, void *val);
 650 JIM_EXPORT int Jim_DeleteHashEntry (Jim_HashTable *ht,
 651         const void *key);
 652 JIM_EXPORT int Jim_FreeHashTable (Jim_HashTable *ht);
 653 JIM_EXPORT Jim_HashEntry * Jim_FindHashEntry (Jim_HashTable *ht,
 654         const void *key);
 655 JIM_EXPORT int Jim_ResizeHashTable (Jim_HashTable *ht);
 656 JIM_EXPORT Jim_HashTableIterator *Jim_GetHashTableIterator
 657         (Jim_HashTable *ht);
 658 JIM_EXPORT Jim_HashEntry * Jim_NextHashEntry
 659         (Jim_HashTableIterator *iter);
 660
 661 /* objects */
 662 JIM_EXPORT Jim_Obj * Jim_NewObj (Jim_Interp *interp);
 663 JIM_EXPORT void Jim_FreeObj (Jim_Interp *interp, Jim_Obj *objPtr);
 664 JIM_EXPORT void Jim_InvalidateStringRep (Jim_Obj *objPtr);
 665 JIM_EXPORT void Jim_InitStringRep (Jim_Obj *objPtr, const char *bytes,
 666         int length);
 667 JIM_EXPORT Jim_Obj * Jim_DuplicateObj (Jim_Interp *interp,
 668         Jim_Obj *objPtr);
 669 JIM_EXPORT const char * Jim_GetString(Jim_Obj *objPtr,
 670         int *lenPtr);
 671 JIM_EXPORT int Jim_Length(Jim_Obj *objPtr);
 672
 673 /* string object */
 674 JIM_EXPORT Jim_Obj * Jim_NewStringObj (Jim_Interp *interp,
 675         const char *s, int len);
 676 JIM_EXPORT Jim_Obj * Jim_NewStringObjNoAlloc (Jim_Interp *interp,
 677         char *s, int len);
 678 JIM_EXPORT void Jim_AppendString (Jim_Interp *interp, Jim_Obj *objPtr,
 679         const char *str, int len);
 680 JIM_EXPORT void Jim_AppendObj (Jim_Interp *interp, Jim_Obj *objPtr,
 681         Jim_Obj *appendObjPtr);
 682 JIM_EXPORT void Jim_AppendStrings (Jim_Interp *interp,
 683         Jim_Obj *objPtr, ...);
 684 JIM_EXPORT int Jim_StringEqObj (Jim_Obj *aObjPtr,
 685         Jim_Obj *bObjPtr, int nocase);
 686 JIM_EXPORT int Jim_StringMatchObj (Jim_Obj *patternObjPtr,
 687         Jim_Obj *objPtr, int nocase);
 688 JIM_EXPORT Jim_Obj * Jim_StringRangeObj (Jim_Interp *interp,
 689         Jim_Obj *strObjPtr, Jim_Obj *firstObjPtr,
 690         Jim_Obj *lastObjPtr);
 691 JIM_EXPORT Jim_Obj * Jim_FormatString (Jim_Interp *interp,
 692         Jim_Obj *fmtObjPtr, int objc, Jim_Obj *const *objv);
 693 JIM_EXPORT Jim_Obj * Jim_ScanString (Jim_Interp *interp, Jim_Obj *strObjPtr,
 694         Jim_Obj *fmtObjPtr, int flags);
 695 JIM_EXPORT int Jim_CompareStringImmediate (Jim_Interp *interp,
 696         Jim_Obj *objPtr, const char *str);
 697
 698 /* reference object */
 699 JIM_EXPORT Jim_Obj * Jim_NewReference (Jim_Interp *interp,
 700         Jim_Obj *objPtr, Jim_Obj *tagPtr, Jim_Obj *cmdNamePtr);
 701 JIM_EXPORT Jim_Reference * Jim_GetReference (Jim_Interp *interp,
 702         Jim_Obj *objPtr);
 703 JIM_EXPORT int Jim_SetFinalizer (Jim_Interp *interp, Jim_Obj *objPtr, Jim_Obj *cmdNamePtr);
 704 JIM_EXPORT int Jim_GetFinalizer (Jim_Interp *interp, Jim_Obj *objPtr, Jim_Obj **cmdNamePtrPtr);
 705
 706 /* interpreter */
 707 JIM_EXPORT Jim_Interp * Jim_CreateInterp (void);
 708 JIM_EXPORT void Jim_FreeInterp (Jim_Interp *i);
 709 JIM_EXPORT int Jim_GetExitCode (Jim_Interp *interp);
 710 JIM_EXPORT const char *Jim_ReturnCode(int code);
 711 JIM_EXPORT void Jim_SetResultFormatted(Jim_Interp *interp, const char *format, ...);
 712
 713 /* commands */
 714 JIM_EXPORT void Jim_RegisterCoreCommands (Jim_Interp *interp);
 715 JIM_EXPORT int Jim_CreateCommand (Jim_Interp *interp,
 716         const char *cmdName, Jim_CmdProc cmdProc, void *privData,
 717          Jim_DelCmdProc delProc);
 718 JIM_EXPORT int Jim_CreateProcedure(Jim_Interp *interp, const char *cmdName,
 719         Jim_Obj *argListObjPtr, Jim_Obj *staticsListObjPtr, Jim_Obj *bodyObjPtr,
 720         int leftArity, int defaultArgs, int argsPos, int rightArity);
 721 JIM_EXPORT int Jim_DeleteCommand (Jim_Interp *interp,
 722         const char *cmdName);
 723 JIM_EXPORT int Jim_RenameCommand (Jim_Interp *interp,
 724         const char *oldName, const char *newName);
 725 JIM_EXPORT Jim_Cmd * Jim_GetCommand (Jim_Interp *interp,
 726         Jim_Obj *objPtr, int flags);
 727 JIM_EXPORT int Jim_SetVariable (Jim_Interp *interp,
 728         Jim_Obj *nameObjPtr, Jim_Obj *valObjPtr);
 729 JIM_EXPORT int Jim_SetVariableStr (Jim_Interp *interp,
 730         const char *name, Jim_Obj *objPtr);
 731 JIM_EXPORT int Jim_SetGlobalVariableStr (Jim_Interp *interp,
 732         const char *name, Jim_Obj *objPtr);
 733 JIM_EXPORT int Jim_SetVariableStrWithStr (Jim_Interp *interp,
 734         const char *name, const char *val);
 735 JIM_EXPORT int Jim_SetVariableLink (Jim_Interp *interp,
 736         Jim_Obj *nameObjPtr, Jim_Obj *targetNameObjPtr,
 737         Jim_CallFrame *targetCallFrame);
 738 JIM_EXPORT Jim_Obj * Jim_GetVariable (Jim_Interp *interp,
 739         Jim_Obj *nameObjPtr, int flags);
 740 JIM_EXPORT Jim_Obj * Jim_GetGlobalVariable (Jim_Interp *interp,
 741         Jim_Obj *nameObjPtr, int flags);
 742 JIM_EXPORT Jim_Obj * Jim_GetVariableStr (Jim_Interp *interp,
 743         const char *name, int flags);
 744 JIM_EXPORT Jim_Obj * Jim_GetGlobalVariableStr (Jim_Interp *interp,
 745         const char *name, int flags);
 746 JIM_EXPORT int Jim_UnsetVariable (Jim_Interp *interp,
 747         Jim_Obj *nameObjPtr, int flags);
 748
 749 /* call frame */
 750 JIM_EXPORT int Jim_GetCallFrameByLevel (Jim_Interp *interp,
 751         Jim_Obj *levelObjPtr, Jim_CallFrame **framePtrPtr,
 752         int *newLevelPtr);
 753
 754 /* garbage collection */
 755 JIM_EXPORT int Jim_Collect (Jim_Interp *interp);
 756 JIM_EXPORT void Jim_CollectIfNeeded (Jim_Interp *interp);
 757
 758 /* index object */
 759 JIM_EXPORT int Jim_GetIndex (Jim_Interp *interp, Jim_Obj *objPtr,
 760         int *indexPtr);
 761
 762 /* list object */
 763 JIM_EXPORT Jim_Obj * Jim_NewListObj (Jim_Interp *interp,
 764         Jim_Obj *const *elements, int len);
 765 JIM_EXPORT void Jim_ListInsertElements (Jim_Interp *interp,
 766         Jim_Obj *listPtr, int index, int objc, Jim_Obj *const *objVec);
 767 JIM_EXPORT void Jim_ListAppendElement (Jim_Interp *interp,
 768         Jim_Obj *listPtr, Jim_Obj *objPtr);
 769 JIM_EXPORT void Jim_ListAppendList (Jim_Interp *interp,
 770         Jim_Obj *listPtr, Jim_Obj *appendListPtr);
 771 JIM_EXPORT int Jim_ListLength (Jim_Interp *interp, Jim_Obj *objPtr);
 772 JIM_EXPORT int Jim_ListIndex (Jim_Interp *interp, Jim_Obj *listPrt,
 773         int index, Jim_Obj **objPtrPtr, int seterr);
 774 JIM_EXPORT int Jim_SetListIndex (Jim_Interp *interp,
 775         Jim_Obj *varNamePtr, Jim_Obj *const *indexv, int indexc,
 776         Jim_Obj *newObjPtr);
 777 JIM_EXPORT Jim_Obj * Jim_ConcatObj (Jim_Interp *interp, int objc,
 778         Jim_Obj *const *objv);
 779
 780 /* dict object */
 781 JIM_EXPORT Jim_Obj * Jim_NewDictObj (Jim_Interp *interp,
 782         Jim_Obj *const *elements, int len);
 783 JIM_EXPORT int Jim_DictKey (Jim_Interp *interp, Jim_Obj *dictPtr,
 784         Jim_Obj *keyPtr, Jim_Obj **objPtrPtr, int flags);
 785 JIM_EXPORT int Jim_DictKeysVector (Jim_Interp *interp,
 786         Jim_Obj *dictPtr, Jim_Obj *const *keyv, int keyc,
 787         Jim_Obj **objPtrPtr, int flags);
 788 JIM_EXPORT int Jim_SetDictKeysVector (Jim_Interp *interp,
 789         Jim_Obj *varNamePtr, Jim_Obj *const *keyv, int keyc,
 790         Jim_Obj *newObjPtr);
 791 JIM_EXPORT int Jim_DictPairs(Jim_Interp *interp,
 792         Jim_Obj *dictPtr, Jim_Obj ***objPtrPtr, int *len);
 793 JIM_EXPORT int Jim_DictAddElement(Jim_Interp *interp, Jim_Obj *objPtr,
 794         Jim_Obj *keyObjPtr, Jim_Obj *valueObjPtr);
 795
 796 /* return code object */
 797 JIM_EXPORT int Jim_GetReturnCode (Jim_Interp *interp, Jim_Obj *objPtr,
 798         int *intPtr);
 799
 800 /* expression object */
 801 JIM_EXPORT int Jim_EvalExpression (Jim_Interp *interp,
 802         Jim_Obj *exprObjPtr, Jim_Obj **exprResultPtrPtr);
 803 JIM_EXPORT int Jim_GetBoolFromExpr (Jim_Interp *interp,
 804         Jim_Obj *exprObjPtr, int *boolPtr);
 805
 806 /* integer object */
 807 JIM_EXPORT int Jim_GetWide (Jim_Interp *interp, Jim_Obj *objPtr,
 808         jim_wide *widePtr);
 809 JIM_EXPORT int Jim_GetLong (Jim_Interp *interp, Jim_Obj *objPtr,
 810         long *longPtr);
 811 JIM_EXPORT void Jim_SetWide (Jim_Interp *interp, Jim_Obj *objPtr,
 812         jim_wide wideValue);
 813 #define Jim_NewWideObj  Jim_NewIntObj
 814 JIM_EXPORT Jim_Obj * Jim_NewIntObj (Jim_Interp *interp,
 815         jim_wide wideValue);
 816
 817 /* double object */
 818 JIM_EXPORT int Jim_GetDouble(Jim_Interp *interp, Jim_Obj *objPtr,
 819         double *doublePtr);
 820 JIM_EXPORT void Jim_SetDouble(Jim_Interp *interp, Jim_Obj *objPtr,
 821         double doubleValue);
 822 JIM_EXPORT Jim_Obj * Jim_NewDoubleObj(Jim_Interp *interp, double doubleValue);
 823
 824 /* shared strings */
 825 JIM_EXPORT const char * Jim_GetSharedString (Jim_Interp *interp,
 826         const char *str);
 827 JIM_EXPORT void Jim_ReleaseSharedString (Jim_Interp *interp,
 828         const char *str);
 829
 830 /* commands utilities */
 831 JIM_EXPORT void Jim_WrongNumArgs (Jim_Interp *interp, int argc,
 832         Jim_Obj *const *argv, const char *msg);
 833 JIM_EXPORT int Jim_GetEnum (Jim_Interp *interp, Jim_Obj *objPtr,
 834         const char * const *tablePtr, int *indexPtr, const char *name, int flags);
 835 JIM_EXPORT int Jim_ScriptIsComplete (const char *s, int len,
 836         char *stateCharPtr);
 837 /**
 838  * Find a matching name in the array of the given length.
 839  *
 840  * NULL entries are ignored.
 841  *
 842  * Returns the matching index if found, or -1 if not.
 843  */
 844 JIM_EXPORT int Jim_FindByName(const char *name, const char *array[], size_t len);
 845
 846 /* package utilities */
 847 typedef void (Jim_InterpDeleteProc)(Jim_Interp *interp, void *data);
 848 JIM_EXPORT void * Jim_GetAssocData(Jim_Interp *interp, const char *key);
 849 JIM_EXPORT int Jim_SetAssocData(Jim_Interp *interp, const char *key,
 850         Jim_InterpDeleteProc *delProc, void *data);
 851 JIM_EXPORT int Jim_DeleteAssocData(Jim_Interp *interp, const char *key);
 852
 853 /* Packages C API */
 854 /* jim-package.c */
 855 JIM_EXPORT int Jim_PackageProvide (Jim_Interp *interp,
 856         const char *name, const char *ver, int flags);
 857 JIM_EXPORT int Jim_PackageRequire (Jim_Interp *interp,
 858         const char *name, int flags);
 859
 860 /* error messages */
 861 JIM_EXPORT void Jim_PrintErrorMessage (Jim_Interp *interp);
 862
 863 /* interactive mode */
 864 JIM_EXPORT int Jim_InteractivePrompt (Jim_Interp *interp);
 865
 866 /* Misc */
 867 JIM_EXPORT int Jim_InitStaticExtensions(Jim_Interp *interp);
 868 JIM_EXPORT void Jim_Panic (Jim_Interp *interp, const char *fmt, ...);
 869 JIM_EXPORT int Jim_StringToWide(const char *str, jim_wide *widePtr, int base);
 870
 871 /* jim-load.c */
 872 JIM_EXPORT int Jim_LoadLibrary(Jim_Interp *interp, const char *pathName);
 873
 874 /* jim-aio.c */
 875 JIM_EXPORT FILE *Jim_AioFilehandle(Jim_Interp *interp, Jim_Obj *command);
 876
 877
 878 int Jim_IsDict(Jim_Obj *objPtr);
 879 int Jim_IsList(Jim_Obj *objPtr);
 880
 881 #ifdef __cplusplus
 882 }
 883 #endif
 884
 885 #endif /* __JIM__H */
 886
 887 /*
 888  * Local Variables: ***
 889  * c-basic-offset: 4 ***
 890  * tab-width: 4 ***
 891  * End: ***
 892  */