git.gag.com Git - fw/openocd/blob - src/helper/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 * Some /very/ old compiler maybe do not know how to
  82 * handle 'const'. They even do not know, how to ignore
  83 * it. For those compiler it may be better to compile with
  84 * define JIM_NO_CONST activated
  85 * ---------------------------------------------------------------------------*/
  86
  87 #ifdef JIM_NO_CONST
  88 #  define const
  89 #endif
  90
  91 /* -----------------------------------------------------------------------------
  92  * System configuration
  93  * For most modern systems, you can leave the default.
  94  * For embedded systems some change may be required.
  95  * ---------------------------------------------------------------------------*/
  96
  97 #define HAVE_LONG_LONG
  98
  99 /* -----------------------------------------------------------------------------
 100  * Compiler specific fixes.
 101  * ---------------------------------------------------------------------------*/
 102
 103 /* MSC has _stricmp instead of strcasecmp */
 104 #ifdef _MSC_VER
 105 #  define strcasecmp _stricmp
 106 #endif /* _MSC_VER */
 107
 108 /* Long Long type and related issues */
 109 #ifdef HAVE_LONG_LONG
 110 #  ifdef _MSC_VER /* MSC compiler */
 111 #    define jim_wide _int64
 112 #    ifndef LLONG_MAX
 113 #      define LLONG_MAX    9223372036854775807I64
 114 #    endif
 115 #    ifndef LLONG_MIN
 116 #      define LLONG_MIN    (-LLONG_MAX - 1I64)
 117 #    endif
 118 #    define JIM_WIDE_MIN LLONG_MIN
 119 #    define JIM_WIDE_MAX LLONG_MAX
 120 #  else /* Other compilers (mainly GCC) */
 121 #    define jim_wide long long
 122 #    ifndef LLONG_MAX
 123 #      define LLONG_MAX    9223372036854775807LL
 124 #    endif
 125 #    ifndef LLONG_MIN
 126 #      define LLONG_MIN    (-LLONG_MAX - 1LL)
 127 #    endif
 128 #    define JIM_WIDE_MIN LLONG_MIN
 129 #    define JIM_WIDE_MAX LLONG_MAX
 130 #  endif
 131 #else
 132 #  define jim_wide long
 133 #  define JIM_WIDE_MIN LONG_MIN
 134 #  define JIM_WIDE_MAX LONG_MAX
 135 #endif
 136
 137 /* -----------------------------------------------------------------------------
 138  * LIBC specific fixes
 139  * ---------------------------------------------------------------------------*/
 140
 141 #ifdef HAVE_LONG_LONG
 142 # if defined(_MSC_VER) || defined(__MSVCRT__)
 143 #    define JIM_WIDE_MODIFIER "I64d"
 144 # else
 145 #    define JIM_WIDE_MODIFIER "lld"
 146 # endif
 147 #else
 148 #    define JIM_WIDE_MODIFIER "ld"
 149 #endif
 150
 151 /* -----------------------------------------------------------------------------
 152  * Exported defines
 153  * ---------------------------------------------------------------------------*/
 154
 155 /* Jim version numbering: every version of jim is marked with a
 156  * successive integer number. This is version 0. The first
 157  * stable version will be 1, then 2, 3, and so on. */
 158 #define JIM_VERSION 51
 159
 160 #define JIM_OK 0
 161 #define JIM_ERR 1
 162 #define JIM_RETURN 2
 163 #define JIM_BREAK 3
 164 #define JIM_CONTINUE 4
 165 #define JIM_EVAL 5
 166 #define JIM_EXIT 6
 167 #define JIM_MAX_NESTING_DEPTH 10000 /* default max nesting depth */
 168
 169 /* Some function get an integer argument with flags to change
 170  * the behaviour. */
 171 #define JIM_NONE 0    /* no flags set */
 172 #define JIM_ERRMSG 1    /* set an error message in the interpreter. */
 173
 174 /* Flags for Jim_SubstObj() */
 175 #define JIM_SUBST_NOVAR 1 /* don't perform variables substitutions */
 176 #define JIM_SUBST_NOCMD 2 /* don't perform command substitutions */
 177 #define JIM_SUBST_NOESC 4 /* don't perform escapes substitutions */
 178
 179 /* Unused arguments generate annoying warnings... */
 180 #define JIM_NOTUSED(V) ((void) V)
 181
 182 /* Flags used by API calls getting a 'nocase' argument. */
 183 #define JIM_CASESENS    0   /* case sensitive */
 184 #define JIM_NOCASE      1   /* no case */
 185
 186 /* Filesystem related */
 187 #define JIM_PATH_LEN 1024
 188
 189 /* Newline, some embedded system may need -DJIM_CRLF */
 190 #ifdef JIM_CRLF
 191 #define JIM_NL "\r\n"
 192 #else
 193 #define JIM_NL "\n"
 194 #endif
 195
 196 #if defined(__WIN32__) || defined(_WIN32)
 197 #define DLLEXPORT __declspec(dllexport)
 198 #define DLLIMPORT __declspec(dllimport)
 199 #else
 200 #define DLLEXPORT
 201 #define DLLIMPORT
 202 #endif
 203
 204 /* -----------------------------------------------------------------------------
 205  * Stack
 206  * ---------------------------------------------------------------------------*/
 207
 208 typedef struct Jim_Stack {
 209     int len;
 210     int maxlen;
 211     void **vector;
 212 } Jim_Stack;
 213
 214 /* -----------------------------------------------------------------------------
 215  * Hash table
 216  * ---------------------------------------------------------------------------*/
 217
 218 typedef struct Jim_HashEntry {
 219     const void *key;
 220     void *val;
 221     struct Jim_HashEntry *next;
 222 } Jim_HashEntry;
 223
 224 typedef struct Jim_HashTableType {
 225     unsigned int (*hashFunction)(const void *key);
 226     const void *(*keyDup)(void *privdata, const void *key);
 227     void *(*valDup)(void *privdata, const void *obj);
 228     int (*keyCompare)(void *privdata, const void *key1, const void *key2);
 229     void (*keyDestructor)(void *privdata, const void *key);
 230     void (*valDestructor)(void *privdata, void *obj);
 231 } Jim_HashTableType;
 232
 233 typedef struct Jim_HashTable {
 234     Jim_HashEntry **table;
 235     Jim_HashTableType *type;
 236     unsigned int size;
 237     unsigned int sizemask;
 238     unsigned int used;
 239     unsigned int collisions;
 240     void *privdata;
 241 } Jim_HashTable;
 242
 243 typedef struct Jim_HashTableIterator {
 244     Jim_HashTable *ht;
 245     int index;
 246     Jim_HashEntry *entry, *nextEntry;
 247 } Jim_HashTableIterator;
 248
 249 /* This is the initial size of every hash table */
 250 #define JIM_HT_INITIAL_SIZE     16
 251
 252 /* ------------------------------- Macros ------------------------------------*/
 253 #define Jim_FreeEntryVal(ht, entry) \
 254     if ((ht)->type->valDestructor) \
 255         (ht)->type->valDestructor((ht)->privdata, (entry)->val)
 256
 257 #define Jim_SetHashVal(ht, entry, _val_) do { \
 258     if ((ht)->type->valDup) \
 259         entry->val = (ht)->type->valDup((ht)->privdata, _val_); \
 260     else \
 261         entry->val = (_val_); \
 262 } while(0)
 263
 264 #define Jim_FreeEntryKey(ht, entry) \
 265     if ((ht)->type->keyDestructor) \
 266         (ht)->type->keyDestructor((ht)->privdata, (entry)->key)
 267
 268 #define Jim_SetHashKey(ht, entry, _key_) do { \
 269     if ((ht)->type->keyDup) \
 270         entry->key = (ht)->type->keyDup((ht)->privdata, _key_); \
 271     else \
 272         entry->key = (_key_); \
 273 } while(0)
 274
 275 #define Jim_CompareHashKeys(ht, key1, key2) \
 276     (((ht)->type->keyCompare) ? \
 277         (ht)->type->keyCompare((ht)->privdata, key1, key2) : \
 278         (key1) == (key2))
 279
 280 #define Jim_HashKey(ht, key) (ht)->type->hashFunction(key)
 281
 282 #define Jim_GetHashEntryKey(he) ((he)->key)
 283 #define Jim_GetHashEntryVal(he) ((he)->val)
 284 #define Jim_GetHashTableCollisions(ht) ((ht)->collisions)
 285 #define Jim_GetHashTableSize(ht) ((ht)->size)
 286 #define Jim_GetHashTableUsed(ht) ((ht)->used)
 287
 288 /* -----------------------------------------------------------------------------
 289  * Jim_Obj structure
 290  * ---------------------------------------------------------------------------*/
 291
 292 /* -----------------------------------------------------------------------------
 293  * Jim object. This is mostly the same as Tcl_Obj itself,
 294  * with the addition of the 'prev' and 'next' pointers.
 295  * In Jim all the objects are stored into a linked list for GC purposes,
 296  * so that it's possible to access every object living in a given interpreter
 297  * sequentially. When an object is freed, it's moved into a different
 298  * linked list, used as object pool.
 299  *
 300  * The refcount of a freed object is always -1.
 301  * ---------------------------------------------------------------------------*/
 302 typedef struct Jim_Obj {
 303     int refCount; /* reference count */
 304     char *bytes; /* string representation buffer. NULL = no string repr. */
 305     int length; /* number of bytes in 'bytes', not including the numterm. */
 306     struct Jim_ObjType *typePtr; /* object type. */
 307     /* Internal representation union */
 308     union {
 309         /* integer number type */
 310         jim_wide wideValue;
 311         /* hashed object type value */
 312         int hashValue;
 313         /* index type */
 314         int indexValue;
 315         /* return code type */
 316         int returnCode;
 317         /* double number type */
 318         double doubleValue;
 319         /* Generic pointer */
 320         void *ptr;
 321         /* Generic two pointers value */
 322         struct {
 323             void *ptr1;
 324             void *ptr2;
 325         } twoPtrValue;
 326         /* Variable object */
 327         struct {
 328             unsigned jim_wide callFrameId;
 329             struct Jim_Var *varPtr;
 330         } varValue;
 331         /* Command object */
 332         struct {
 333             unsigned jim_wide procEpoch;
 334             struct Jim_Cmd *cmdPtr;
 335         } cmdValue;
 336         /* List object */
 337         struct {
 338             struct Jim_Obj **ele;    /* Elements vector */
 339             int len;        /* Length */
 340             int maxLen;        /* Allocated 'ele' length */
 341         } listValue;
 342         /* String type */
 343         struct {
 344             int maxLength;
 345         } strValue;
 346         /* Reference type */
 347         struct {
 348             jim_wide id;
 349             struct Jim_Reference *refPtr;
 350         } refValue;
 351         /* Source type */
 352         struct {
 353             const char *fileName;
 354             int lineNumber;
 355         } sourceValue;
 356         /* Dict substitution type */
 357         struct {
 358             struct Jim_Obj *varNameObjPtr;
 359             struct Jim_Obj *indexObjPtr;
 360         } dictSubstValue;
 361         /* tagged binary type */
 362         struct {
 363             unsigned char *data;
 364             size_t         len;
 365         } binaryValue;
 366     } internalRep;
 367     /* This are 8 or 16 bytes more for every object
 368      * but this is required for efficient garbage collection
 369      * of Jim references. */
 370     struct Jim_Obj *prevObjPtr; /* pointer to the prev object. */
 371     struct Jim_Obj *nextObjPtr; /* pointer to the next object. */
 372 } Jim_Obj;
 373
 374 /* Jim_Obj related macros */
 375 #define Jim_IncrRefCount(objPtr) \
 376     ++(objPtr)->refCount
 377 #define Jim_DecrRefCount(interp, objPtr) \
 378     if (--(objPtr)->refCount <= 0) Jim_FreeObj(interp, objPtr)
 379 #define Jim_IsShared(objPtr) \
 380     ((objPtr)->refCount > 1)
 381
 382 /* This macro is used when we allocate a new object using
 383  * Jim_New...Obj(), but for some error we need to destroy it.
 384  * Instead to use Jim_IncrRefCount() + Jim_DecrRefCount() we
 385  * can just call Jim_FreeNewObj. To call Jim_Free directly
 386  * seems too raw, the object handling may change and we want
 387  * that Jim_FreeNewObj() can be called only against objects
 388  * that are belived to have refcount == 0. */
 389 #define Jim_FreeNewObj Jim_FreeObj
 390
 391 /* Free the internal representation of the object. */
 392 #define Jim_FreeIntRep(i,o) \
 393     if ((o)->typePtr && (o)->typePtr->freeIntRepProc) \
 394         (o)->typePtr->freeIntRepProc(i, o)
 395
 396 /* Get the internal representation pointer */
 397 #define Jim_GetIntRepPtr(o) (o)->internalRep.ptr
 398
 399 /* Set the internal representation pointer */
 400 #define Jim_SetIntRepPtr(o, p) \
 401     (o)->internalRep.ptr = (p)
 402
 403 /* The object type structure.
 404  * There are four methods.
 405  *
 406  * - FreeIntRep is used to free the internal representation of the object.
 407  *   Can be NULL if there is nothing to free.
 408  * - DupIntRep is used to duplicate the internal representation of the object.
 409  *   If NULL, when an object is duplicated, the internalRep union is
 410  *   directly copied from an object to another.
 411  *   Note that it's up to the caller to free the old internal repr of the
 412  *   object before to call the Dup method.
 413  * - UpdateString is used to create the string from the internal repr.
 414  * - setFromAny is used to convert the current object into one of this type.
 415  */
 416
 417 struct Jim_Interp;
 418
 419 typedef void (Jim_FreeInternalRepProc)(struct Jim_Interp *interp,
 420         struct Jim_Obj *objPtr);
 421 typedef void (Jim_DupInternalRepProc)(struct Jim_Interp *interp,
 422         struct Jim_Obj *srcPtr, Jim_Obj *dupPtr);
 423 typedef void (Jim_UpdateStringProc)(struct Jim_Obj *objPtr);
 424
 425 typedef struct Jim_ObjType {
 426     const char *name; /* The name of the type. */
 427     Jim_FreeInternalRepProc *freeIntRepProc;
 428     Jim_DupInternalRepProc *dupIntRepProc;
 429     Jim_UpdateStringProc *updateStringProc;
 430     int flags;
 431 } Jim_ObjType;
 432
 433 /* Jim_ObjType flags */
 434 #define JIM_TYPE_NONE 0        /* No flags */
 435 #define JIM_TYPE_REFERENCES 1    /* The object may contain referneces. */
 436
 437 /* Starting from 1 << 20 flags are reserved for private uses of
 438  * different calls. This way the same 'flags' argument may be used
 439  * to pass both global flags and private flags. */
 440 #define JIM_PRIV_FLAG_SHIFT 20
 441
 442 /* -----------------------------------------------------------------------------
 443  * Call frame, vars, commands structures
 444  * ---------------------------------------------------------------------------*/
 445
 446 /* Call frame */
 447 typedef struct Jim_CallFrame {
 448     unsigned jim_wide id; /* Call Frame ID. Used for caching. */
 449     struct Jim_HashTable vars; /* Where local vars are stored */
 450     struct Jim_HashTable *staticVars; /* pointer to procedure static vars */
 451     struct Jim_CallFrame *parentCallFrame;
 452     Jim_Obj *const *argv; /* object vector of the current procedure call. */
 453     int argc; /* number of args of the current procedure call. */
 454     Jim_Obj *procArgsObjPtr; /* arglist object of the running procedure */
 455     Jim_Obj *procBodyObjPtr; /* body object of the running procedure */
 456     struct Jim_CallFrame *nextFramePtr;
 457 } Jim_CallFrame;
 458
 459 /* The var structure. It just holds the pointer of the referenced
 460  * object. If linkFramePtr is not NULL the variable is a link
 461  * to a variable of name store on objPtr living on the given callframe
 462  * (this happens when the [global] or [upvar] command is used).
 463  * The interp in order to always know how to free the Jim_Obj associated
 464  * with a given variable because In Jim objects memory managment is
 465  * bound to interpreters. */
 466 typedef struct Jim_Var {
 467     Jim_Obj *objPtr;
 468     struct Jim_CallFrame *linkFramePtr;
 469 } Jim_Var;
 470
 471 /* The cmd structure. */
 472 typedef int (*Jim_CmdProc)(struct Jim_Interp *interp, int argc,
 473     Jim_Obj *const *argv);
 474 typedef void (*Jim_DelCmdProc)(struct Jim_Interp *interp, void *privData);
 475
 476 /* A command is implemented in C if funcPtr is != NULL, otherwise
 477  * it's a Tcl procedure with the arglist and body represented by the
 478  * two objects referenced by arglistObjPtr and bodyoObjPtr. */
 479 typedef struct Jim_Cmd {
 480     Jim_CmdProc cmdProc; /* Not-NULL for a C command. */
 481     void *privData; /* Only used for C commands. */
 482     Jim_DelCmdProc delProc; /* Called when the command is deleted if != NULL */
 483     Jim_Obj *argListObjPtr;
 484     Jim_Obj *bodyObjPtr;
 485     Jim_HashTable *staticVars; /* Static vars hash table. NULL if no statics. */
 486     int arityMin; /* Min number of arguments. */
 487     int arityMax; /* Max number of arguments. */
 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     const char *errorFileName; /* Error file where an error occurred. */
 504     int numLevels; /* Number of current nested calls. */
 505     int maxNestingDepth; /* Used for infinite loop detection. */
 506     int returnCode; /* Completion code to return on JIM_RETURN. */
 507     int exitCode; /* Code to return to the OS on JIM_EXIT. */
 508     Jim_CallFrame *framePtr; /* Pointer to the current call frame */
 509     Jim_CallFrame *topFramePtr; /* toplevel/global frame pointer. */
 510     struct Jim_HashTable commands; /* Commands hash table */
 511     unsigned jim_wide procEpoch; /* Incremented every time the result
 512                 of procedures names lookup caching
 513                 may no longer be valid. */
 514     unsigned jim_wide callFrameEpoch; /* Incremented every time a new
 515                 callframe is created. This id is used for the
 516                 'ID' field contained in the Jim_CallFrame
 517                 structure. */
 518     Jim_Obj *liveList; /* Linked list of all the live objects. */
 519     Jim_Obj *freeList; /* Linked list of all the unused objects. */
 520     const char *scriptFileName; /* File name of the script currently in execution. */
 521     Jim_Obj *emptyObj; /* Shared empty string object. */
 522     unsigned jim_wide referenceNextId; /* Next id for reference. */
 523     struct Jim_HashTable references; /* References hash table. */
 524     jim_wide lastCollectId; /* reference max Id of the last GC
 525                 execution. It's set to -1 while the collection
 526                 is running as sentinel to avoid to recursive
 527                 calls via the [collect] command inside
 528                 finalizers. */
 529     time_t lastCollectTime; /* unix time of the last GC execution */
 530     struct Jim_HashTable sharedStrings; /* Shared Strings hash table */
 531     Jim_Obj *stackTrace; /* Stack trace object. */
 532     Jim_Obj *unknown; /* Unknown command cache */
 533     int errorFlag; /* Set if an error occurred during execution. */
 534     int evalRetcodeLevel; /* Level where the last return with code JIM_EVAL
 535                              happened. */
 536     void *cmdPrivData; /* Used to pass the private data pointer to
 537                   a command. It is set to what the user specified
 538                   via Jim_CreateCommand(). */
 539
 540     struct Jim_HashTable stub; /* Stub hash table to export API */
 541     /* Jim_GetApi() function pointer, used to bootstrap the STUB table */
 542     int (*getApiFuncPtr)(struct Jim_Interp *, const char *, void *);
 543     struct Jim_CallFrame *freeFramesList; /* list of CallFrame structures. */
 544     struct Jim_HashTable assocData; /* per-interp storage for use by packages */
 545     Jim_PrngState *prngState; /* per interpreter Random Number Gen. state. */
 546     struct Jim_HashTable packages; /* Provided packages hash table */
 547     void *cookie_stdin; /* input file pointer, 'stdin' by default */
 548     void *cookie_stdout; /* output file pointer, 'stdout' by default */
 549     void *cookie_stderr; /* errors file pointer, 'stderr' by default */
 550     size_t (*cb_fwrite  )( const void *ptr, size_t size, size_t n, void *cookie );
 551         size_t (*cb_fread   )( void *ptr, size_t size, size_t n, void *cookie );
 552         int    (*cb_vfprintf)( void *cookie, const char *fmt, va_list ap );
 553         int    (*cb_fflush  )( void *cookie );
 554         char  *(*cb_fgets   )( char *s, int size, void *cookie );
 555 } Jim_Interp;
 556
 557 /* Currently provided as macro that performs the increment.
 558  * At some point may be a real function doing more work.
 559  * The proc epoch is used in order to know when a command lookup
 560  * cached can no longer considered valid. */
 561 #define Jim_InterpIncrProcEpoch(i) (i)->procEpoch++
 562 #define Jim_SetResultString(i,s,l) Jim_SetResult(i, Jim_NewStringObj(i,s,l))
 563 #define Jim_SetEmptyResult(i) Jim_SetResult(i, (i)->emptyObj)
 564 #define Jim_GetResult(i) ((i)->result)
 565 #define Jim_CmdPrivData(i) ((i)->cmdPrivData)
 566
 567 /* Note that 'o' is expanded only one time inside this macro,
 568  * so it's safe to use side effects. */
 569 #define Jim_SetResult(i,o) do {     \
 570     Jim_Obj *_resultObjPtr_ = (o);    \
 571     Jim_IncrRefCount(_resultObjPtr_); \
 572     Jim_DecrRefCount(i,(i)->result);  \
 573     (i)->result = _resultObjPtr_;     \
 574 } while(0)
 575
 576 /* Reference structure. The interpreter pointer is held within privdata member in HashTable */
 577 #define JIM_REFERENCE_TAGLEN 7 /* The tag is fixed-length, because the reference
 578                                   string representation must be fixed length. */
 579 typedef struct Jim_Reference {
 580     Jim_Obj *objPtr;
 581     Jim_Obj *finalizerCmdNamePtr;
 582     char tag[JIM_REFERENCE_TAGLEN+1];
 583 } Jim_Reference;
 584
 585 /** Name Value Pairs, aka: NVP
 586  *   -  Given a string - return the associated int.
 587  *   -  Given a number - return the associated string.
 588  *   .
 589  *
 590  * Very useful when the number is not a simple index into an array of
 591  * known string, or there may be multiple strings (aliases) that mean then same
 592  * thing.
 593  *
 594  * An NVP Table is terminated with ".name=NULL".
 595  *
 596  * During the 'name2value' operation, if no matching string is found
 597  * the pointer to the terminal element (with p->name==NULL) is returned.
 598  *
 599  * Example:
 600  * \code
 601  *      const Jim_Nvp yn[] = {
 602  *          { "yes", 1 },
 603  *          { "no" , 0 },
 604  *          { "yep", 1 },
 605  *          { "nope", 0 },
 606  *          { NULL, -1 },
 607  *      };
 608  *
 609  *  Jim_Nvp *result
 610  *  e = Jim_Nvp_name2value( interp, yn, "y", &result );
 611  *         returns &yn[0];
 612  *  e = Jim_Nvp_name2value( interp, yn, "n", &result );
 613  *         returns &yn[1];
 614  *  e = Jim_Nvp_name2value( interp, yn, "Blah", &result );
 615  *         returns &yn[4];
 616  * \endcode
 617  *
 618  * During the number2name operation, the first matching value is returned.
 619  */
 620 typedef struct {
 621         const char *name;
 622         int         value;
 623 } Jim_Nvp;
 624
 625
 626 /* -----------------------------------------------------------------------------
 627  * Exported API prototypes.
 628  * ---------------------------------------------------------------------------*/
 629
 630 /* Macros that are common for extensions and core. */
 631 #define Jim_NewEmptyStringObj(i) Jim_NewStringObj(i, "", 0)
 632
 633 /* The core includes real prototypes, extensions instead
 634  * include a global function pointer for every function exported.
 635  * Once the extension calls Jim_InitExtension(), the global
 636  * functon pointers are set to the value of the STUB table
 637  * contained in the Jim_Interp structure.
 638  *
 639  * This makes Jim able to load extensions even if it is statically
 640  * linked itself, and to load extensions compiled with different
 641  * versions of Jim (as long as the API is still compatible.) */
 642
 643 /* Macros are common for core and extensions */
 644 #define Jim_FreeHashTableIterator(iter) Jim_Free(iter)
 645
 646 #ifdef DOXYGEN
 647 #define JIM_STATIC
 648 #define JIM_API( X )  X
 649 #else
 650 #ifndef __JIM_CORE__
 651 # if defined JIM_EXTENSION || defined JIM_EMBEDDED
 652 #  define JIM_API(x) (*x)
 653 #  define JIM_STATIC
 654 # else
 655 #  define JIM_API(x) (*x)
 656 #  define JIM_STATIC extern
 657 # endif
 658 #else
 659 # define JIM_API(x) x
 660 # if defined(BUILD_Jim)
 661 #   define JIM_STATIC DLLEXPORT
 662 # else
 663 #   define JIM_STATIC static
 664 # endif
 665 #endif /* __JIM_CORE__ */
 666 #endif /* DOXYGEN */
 667
 668 /** Set the result - printf() style */
 669 JIM_STATIC int JIM_API( Jim_SetResult_sprintf )( Jim_Interp *p, const char *fmt, ... );
 670
 671 /* Memory allocation */
 672 JIM_STATIC void * JIM_API(Jim_Alloc) (int size);
 673 JIM_STATIC void JIM_API(Jim_Free) (void *ptr);
 674 JIM_STATIC char * JIM_API(Jim_StrDup) (const char *s);
 675
 676 /* evaluation */
 677 JIM_STATIC int JIM_API(Jim_Eval)(Jim_Interp *interp, const char *script);
 678 /* in C code, you can do this and get better error messages */
 679 /*   Jim_Eval_Named( interp, "some tcl commands", __FILE__, __LINE__ ); */
 680 JIM_STATIC int JIM_API(Jim_Eval_Named)(Jim_Interp *interp, const char *script,const char *filename, int lineno);
 681 JIM_STATIC int JIM_API(Jim_EvalGlobal)(Jim_Interp *interp, const char *script);
 682 JIM_STATIC int JIM_API(Jim_EvalFile)(Jim_Interp *interp, const char *filename);
 683 JIM_STATIC int JIM_API(Jim_EvalObj) (Jim_Interp *interp, Jim_Obj *scriptObjPtr);
 684 JIM_STATIC int JIM_API(Jim_EvalObjBackground) (Jim_Interp *interp,
 685         Jim_Obj *scriptObjPtr);
 686 JIM_STATIC int JIM_API(Jim_EvalObjVector) (Jim_Interp *interp, int objc,
 687         Jim_Obj *const *objv);
 688 JIM_STATIC int JIM_API(Jim_SubstObj) (Jim_Interp *interp, Jim_Obj *substObjPtr,
 689         Jim_Obj **resObjPtrPtr, int flags);
 690
 691 /* stack */
 692 JIM_STATIC void JIM_API(Jim_InitStack)(Jim_Stack *stack);
 693 JIM_STATIC void JIM_API(Jim_FreeStack)(Jim_Stack *stack);
 694 JIM_STATIC int JIM_API(Jim_StackLen)(Jim_Stack *stack);
 695 JIM_STATIC void JIM_API(Jim_StackPush)(Jim_Stack *stack, void *element);
 696 JIM_STATIC void * JIM_API(Jim_StackPop)(Jim_Stack *stack);
 697 JIM_STATIC void * JIM_API(Jim_StackPeek)(Jim_Stack *stack);
 698 JIM_STATIC void JIM_API(Jim_FreeStackElements)(Jim_Stack *stack, void (*freeFunc)(void *ptr));
 699
 700 /* hash table */
 701 JIM_STATIC int JIM_API(Jim_InitHashTable) (Jim_HashTable *ht,
 702         Jim_HashTableType *type, void *privdata);
 703 JIM_STATIC int JIM_API(Jim_ExpandHashTable) (Jim_HashTable *ht,
 704         unsigned int size);
 705 JIM_STATIC int JIM_API(Jim_AddHashEntry) (Jim_HashTable *ht, const void *key,
 706         void *val);
 707 JIM_STATIC int JIM_API(Jim_ReplaceHashEntry) (Jim_HashTable *ht,
 708         const void *key, void *val);
 709 JIM_STATIC int JIM_API(Jim_DeleteHashEntry) (Jim_HashTable *ht,
 710         const void *key);
 711 JIM_STATIC int JIM_API(Jim_FreeHashTable) (Jim_HashTable *ht);
 712 JIM_STATIC Jim_HashEntry * JIM_API(Jim_FindHashEntry) (Jim_HashTable *ht,
 713         const void *key);
 714 JIM_STATIC int JIM_API(Jim_ResizeHashTable) (Jim_HashTable *ht);
 715 JIM_STATIC Jim_HashTableIterator *JIM_API(Jim_GetHashTableIterator)
 716         (Jim_HashTable *ht);
 717 JIM_STATIC Jim_HashEntry * JIM_API(Jim_NextHashEntry)
 718         (Jim_HashTableIterator *iter);
 719
 720 /* objects */
 721 JIM_STATIC Jim_Obj * JIM_API(Jim_NewObj) (Jim_Interp *interp);
 722 JIM_STATIC void JIM_API(Jim_FreeObj) (Jim_Interp *interp, Jim_Obj *objPtr);
 723 JIM_STATIC void JIM_API(Jim_InvalidateStringRep) (Jim_Obj *objPtr);
 724 JIM_STATIC void JIM_API(Jim_InitStringRep) (Jim_Obj *objPtr, const char *bytes,
 725         int length);
 726 JIM_STATIC Jim_Obj * JIM_API(Jim_DuplicateObj) (Jim_Interp *interp,
 727         Jim_Obj *objPtr);
 728 JIM_STATIC const char * JIM_API(Jim_GetString)(Jim_Obj *objPtr,
 729         int *lenPtr);
 730 JIM_STATIC int JIM_API(Jim_Length)(Jim_Obj *objPtr);
 731
 732 /* string object */
 733 JIM_STATIC Jim_Obj * JIM_API(Jim_NewStringObj) (Jim_Interp *interp,
 734         const char *s, int len);
 735 JIM_STATIC Jim_Obj * JIM_API(Jim_NewStringObjNoAlloc) (Jim_Interp *interp,
 736         char *s, int len);
 737 JIM_STATIC void JIM_API(Jim_AppendString) (Jim_Interp *interp, Jim_Obj *objPtr,
 738         const char *str, int len);
 739 JIM_STATIC void JIM_API(Jim_AppendString_sprintf) (Jim_Interp *interp, Jim_Obj *objPtr,
 740                                                                                                    const char *fmt, ... );
 741 JIM_STATIC void JIM_API(Jim_AppendObj) (Jim_Interp *interp, Jim_Obj *objPtr,
 742         Jim_Obj *appendObjPtr);
 743 JIM_STATIC void JIM_API(Jim_AppendStrings) (Jim_Interp *interp,
 744         Jim_Obj *objPtr, ...);
 745 JIM_STATIC int JIM_API(Jim_StringEqObj) (Jim_Obj *aObjPtr,
 746         Jim_Obj *bObjPtr, int nocase);
 747 JIM_STATIC int JIM_API(Jim_StringMatchObj) (Jim_Obj *patternObjPtr,
 748         Jim_Obj *objPtr, int nocase);
 749 JIM_STATIC Jim_Obj * JIM_API(Jim_StringRangeObj) (Jim_Interp *interp,
 750         Jim_Obj *strObjPtr, Jim_Obj *firstObjPtr,
 751         Jim_Obj *lastObjPtr);
 752 JIM_STATIC Jim_Obj * JIM_API(Jim_FormatString) (Jim_Interp *interp,
 753         Jim_Obj *fmtObjPtr, int objc, Jim_Obj *const *objv);
 754 JIM_STATIC Jim_Obj * JIM_API(Jim_ScanString) (Jim_Interp *interp, Jim_Obj *strObjPtr,
 755         Jim_Obj *fmtObjPtr, int flags);
 756 JIM_STATIC int JIM_API(Jim_CompareStringImmediate) (Jim_Interp *interp,
 757         Jim_Obj *objPtr, const char *str);
 758
 759 /* reference object */
 760 JIM_STATIC Jim_Obj * JIM_API(Jim_NewReference) (Jim_Interp *interp,
 761         Jim_Obj *objPtr, Jim_Obj *tagPtr, Jim_Obj *cmdNamePtr);
 762 JIM_STATIC Jim_Reference * JIM_API(Jim_GetReference) (Jim_Interp *interp,
 763         Jim_Obj *objPtr);
 764 JIM_STATIC int JIM_API(Jim_SetFinalizer) (Jim_Interp *interp, Jim_Obj *objPtr, Jim_Obj *cmdNamePtr);
 765 JIM_STATIC int JIM_API(Jim_GetFinalizer) (Jim_Interp *interp, Jim_Obj *objPtr, Jim_Obj **cmdNamePtrPtr);
 766
 767 /* interpreter */
 768 JIM_STATIC Jim_Interp * JIM_API(Jim_CreateInterp) (void);
 769 JIM_STATIC void JIM_API(Jim_FreeInterp) (Jim_Interp *i);
 770 JIM_STATIC int JIM_API(Jim_GetExitCode) (Jim_Interp *interp);
 771 JIM_STATIC void * JIM_API(Jim_SetStdin) (Jim_Interp *interp, void *fp);
 772 JIM_STATIC void * JIM_API(Jim_SetStdout) (Jim_Interp *interp, void *fp);
 773 JIM_STATIC void * JIM_API(Jim_SetStderr) (Jim_Interp *interp, void *fp);
 774
 775 /* commands */
 776 JIM_STATIC void JIM_API(Jim_RegisterCoreCommands) (Jim_Interp *interp);
 777 JIM_STATIC int JIM_API(Jim_CreateCommand) (Jim_Interp *interp,
 778         const char *cmdName, Jim_CmdProc cmdProc, void *privData,
 779          Jim_DelCmdProc delProc);
 780 JIM_STATIC int JIM_API(Jim_CreateProcedure) (Jim_Interp *interp,
 781         const char *cmdName, Jim_Obj *argListObjPtr, Jim_Obj *staticsListObjPtr,
 782         Jim_Obj *bodyObjPtr, int arityMin, int arityMax);
 783 JIM_STATIC int JIM_API(Jim_DeleteCommand) (Jim_Interp *interp,
 784         const char *cmdName);
 785 JIM_STATIC int JIM_API(Jim_RenameCommand) (Jim_Interp *interp,
 786         const char *oldName, const char *newName);
 787 JIM_STATIC Jim_Cmd * JIM_API(Jim_GetCommand) (Jim_Interp *interp,
 788         Jim_Obj *objPtr, int flags);
 789 JIM_STATIC int JIM_API(Jim_SetVariable) (Jim_Interp *interp,
 790         Jim_Obj *nameObjPtr, Jim_Obj *valObjPtr);
 791 JIM_STATIC int JIM_API(Jim_SetVariableStr) (Jim_Interp *interp,
 792         const char *name, Jim_Obj *objPtr);
 793 JIM_STATIC int JIM_API(Jim_SetGlobalVariableStr) (Jim_Interp *interp,
 794         const char *name, Jim_Obj *objPtr);
 795 JIM_STATIC int JIM_API(Jim_SetVariableStrWithStr) (Jim_Interp *interp,
 796         const char *name, const char *val);
 797 JIM_STATIC int JIM_API(Jim_SetVariableLink) (Jim_Interp *interp,
 798         Jim_Obj *nameObjPtr, Jim_Obj *targetNameObjPtr,
 799         Jim_CallFrame *targetCallFrame);
 800 JIM_STATIC Jim_Obj * JIM_API(Jim_GetVariable) (Jim_Interp *interp,
 801         Jim_Obj *nameObjPtr, int flags);
 802 JIM_STATIC Jim_Obj * JIM_API(Jim_GetGlobalVariable) (Jim_Interp *interp,
 803         Jim_Obj *nameObjPtr, int flags);
 804 JIM_STATIC Jim_Obj * JIM_API(Jim_GetVariableStr) (Jim_Interp *interp,
 805         const char *name, int flags);
 806 JIM_STATIC Jim_Obj * JIM_API(Jim_GetGlobalVariableStr) (Jim_Interp *interp,
 807         const char *name, int flags);
 808 JIM_STATIC int JIM_API(Jim_UnsetVariable) (Jim_Interp *interp,
 809         Jim_Obj *nameObjPtr, int flags);
 810
 811 /* call frame */
 812 JIM_STATIC int JIM_API(Jim_GetCallFrameByLevel) (Jim_Interp *interp,
 813         Jim_Obj *levelObjPtr, Jim_CallFrame **framePtrPtr,
 814         int *newLevelPtr);
 815
 816 /* garbage collection */
 817 JIM_STATIC int JIM_API(Jim_Collect) (Jim_Interp *interp);
 818 JIM_STATIC void JIM_API(Jim_CollectIfNeeded) (Jim_Interp *interp);
 819
 820 /* index object */
 821 JIM_STATIC int JIM_API(Jim_GetIndex) (Jim_Interp *interp, Jim_Obj *objPtr,
 822         int *indexPtr);
 823
 824 /* list object */
 825 JIM_STATIC Jim_Obj * JIM_API(Jim_NewListObj) (Jim_Interp *interp,
 826         Jim_Obj *const *elements, int len);
 827 JIM_STATIC void JIM_API(Jim_ListInsertElements) (Jim_Interp *interp,
 828         Jim_Obj *listPtr, int index, int objc, Jim_Obj *const *objVec);
 829 JIM_STATIC void JIM_API(Jim_ListAppendElement) (Jim_Interp *interp,
 830         Jim_Obj *listPtr, Jim_Obj *objPtr);
 831 JIM_STATIC void JIM_API(Jim_ListAppendList) (Jim_Interp *interp,
 832         Jim_Obj *listPtr, Jim_Obj *appendListPtr);
 833 JIM_STATIC void JIM_API(Jim_ListLength) (Jim_Interp *interp, Jim_Obj *listPtr,
 834         int *intPtr);
 835 JIM_STATIC int JIM_API(Jim_ListIndex) (Jim_Interp *interp, Jim_Obj *listPrt,
 836         int index, Jim_Obj **objPtrPtr, int seterr);
 837 JIM_STATIC int JIM_API(Jim_SetListIndex) (Jim_Interp *interp,
 838         Jim_Obj *varNamePtr, Jim_Obj *const *indexv, int indexc,
 839         Jim_Obj *newObjPtr);
 840 JIM_STATIC Jim_Obj * JIM_API(Jim_ConcatObj) (Jim_Interp *interp, int objc,
 841         Jim_Obj *const *objv);
 842
 843 /* dict object */
 844 JIM_STATIC Jim_Obj * JIM_API(Jim_NewDictObj) (Jim_Interp *interp,
 845         Jim_Obj *const *elements, int len);
 846 JIM_STATIC int JIM_API(Jim_DictKey) (Jim_Interp *interp, Jim_Obj *dictPtr,
 847         Jim_Obj *keyPtr, Jim_Obj **objPtrPtr, int flags);
 848 JIM_STATIC int JIM_API(Jim_DictKeysVector) (Jim_Interp *interp,
 849         Jim_Obj *dictPtr, Jim_Obj *const *keyv, int keyc,
 850         Jim_Obj **objPtrPtr, int flags);
 851 JIM_STATIC int JIM_API(Jim_SetDictKeysVector) (Jim_Interp *interp,
 852         Jim_Obj *varNamePtr, Jim_Obj *const *keyv, int keyc,
 853         Jim_Obj *newObjPtr);
 854
 855 /* return code object */
 856 JIM_STATIC int JIM_API(Jim_GetReturnCode) (Jim_Interp *interp, Jim_Obj *objPtr,
 857         int *intPtr);
 858
 859 /* expression object */
 860 JIM_STATIC int JIM_API(Jim_EvalExpression) (Jim_Interp *interp,
 861         Jim_Obj *exprObjPtr, Jim_Obj **exprResultPtrPtr);
 862 JIM_STATIC int JIM_API(Jim_GetBoolFromExpr) (Jim_Interp *interp,
 863         Jim_Obj *exprObjPtr, int *boolPtr);
 864
 865 /* integer object */
 866 JIM_STATIC int JIM_API(Jim_GetWide) (Jim_Interp *interp, Jim_Obj *objPtr,
 867         jim_wide *widePtr);
 868 JIM_STATIC int JIM_API(Jim_GetLong) (Jim_Interp *interp, Jim_Obj *objPtr,
 869         long *longPtr);
 870 JIM_STATIC void JIM_API(Jim_SetWide) (Jim_Interp *interp, Jim_Obj *objPtr,
 871         jim_wide wideValue);
 872 #define Jim_NewWideObj  Jim_NewIntObj
 873 JIM_STATIC Jim_Obj * JIM_API(Jim_NewIntObj) (Jim_Interp *interp,
 874         jim_wide wideValue);
 875
 876 /* double object */
 877 JIM_STATIC int JIM_API(Jim_GetDouble)(Jim_Interp *interp, Jim_Obj *objPtr,
 878         double *doublePtr);
 879 JIM_STATIC void JIM_API(Jim_SetDouble)(Jim_Interp *interp, Jim_Obj *objPtr,
 880         double doubleValue);
 881 JIM_STATIC Jim_Obj * JIM_API(Jim_NewDoubleObj)(Jim_Interp *interp, double doubleValue);
 882
 883 /* shared strings */
 884 JIM_STATIC const char * JIM_API(Jim_GetSharedString) (Jim_Interp *interp,
 885         const char *str);
 886 JIM_STATIC void JIM_API(Jim_ReleaseSharedString) (Jim_Interp *interp,
 887         const char *str);
 888
 889 /* commands utilities */
 890 JIM_STATIC void JIM_API(Jim_WrongNumArgs) (Jim_Interp *interp, int argc,
 891         Jim_Obj *const *argv, const char *msg);
 892 JIM_STATIC int JIM_API(Jim_GetEnum) (Jim_Interp *interp, Jim_Obj *objPtr,
 893         const char * const *tablePtr, int *indexPtr, const char *name, int flags);
 894 JIM_STATIC int JIM_API(Jim_GetNvp) (Jim_Interp *interp,
 895                                                                         Jim_Obj *objPtr,
 896                                                                         const Jim_Nvp *nvp_table,
 897                                                                         const Jim_Nvp **result);
 898 JIM_STATIC int JIM_API(Jim_ScriptIsComplete) (const char *s, int len,
 899         char *stateCharPtr);
 900
 901 /* package utilities */
 902 typedef void (Jim_InterpDeleteProc)(Jim_Interp *interp, void *data);
 903 JIM_STATIC void * JIM_API(Jim_GetAssocData)(Jim_Interp *interp, const char *key);
 904 JIM_STATIC int JIM_API(Jim_SetAssocData)(Jim_Interp *interp, const char *key,
 905         Jim_InterpDeleteProc *delProc, void *data);
 906 JIM_STATIC int JIM_API(Jim_DeleteAssocData)(Jim_Interp *interp, const char *key);
 907
 908 /* API import/export functions */
 909 JIM_STATIC int JIM_API(Jim_GetApi) (Jim_Interp *interp, const char *funcname,
 910         void *targetPtrPtr);
 911 JIM_STATIC int JIM_API(Jim_RegisterApi) (Jim_Interp *interp,
 912         const char *funcname, void *funcptr);
 913
 914 /* Packages C API */
 915 JIM_STATIC int JIM_API(Jim_PackageProvide) (Jim_Interp *interp,
 916         const char *name, const char *ver, int flags);
 917 JIM_STATIC const char * JIM_API(Jim_PackageRequire) (Jim_Interp *interp,
 918         const char *name, const char *ver, int flags);
 919
 920 /* error messages */
 921 JIM_STATIC void JIM_API(Jim_PrintErrorMessage) (Jim_Interp *interp);
 922
 923 /* interactive mode */
 924 JIM_STATIC int JIM_API(Jim_InteractivePrompt) (Jim_Interp *interp);
 925
 926 /* Misc */
 927 JIM_STATIC void JIM_API(Jim_Panic) (Jim_Interp *interp, const char *fmt, ...);
 928
 929 /* Jim's STDIO */
 930 JIM_STATIC int     JIM_API( Jim_fprintf  )( Jim_Interp *interp, void *cookie, const char *fmt, ... );
 931 JIM_STATIC int     JIM_API( Jim_vfprintf )( Jim_Interp *interp, void *cookie, const char *fmt, va_list ap );
 932 JIM_STATIC size_t  JIM_API( Jim_fwrite   )( Jim_Interp *interp, const void *ptr, size_t size, size_t nmeb, void *cookie );
 933 JIM_STATIC size_t  JIM_API( Jim_fread    )( Jim_Interp *interp, void *ptr, size_t size, size_t nmeb, void *cookie );
 934 JIM_STATIC int     JIM_API( Jim_fflush   )( Jim_Interp *interp, void *cookie );
 935 JIM_STATIC char *  JIM_API( Jim_fgets    )( Jim_Interp *interp, char *s, int size, void *cookie );
 936
 937 /* Name Value Pairs Operations */
 938 JIM_STATIC Jim_Nvp *JIM_API(Jim_Nvp_name2value_simple)( const Jim_Nvp *nvp_table, const char *name );
 939 JIM_STATIC Jim_Nvp *JIM_API(Jim_Nvp_name2value_nocase_simple)( const Jim_Nvp *nvp_table, const char *name );
 940 JIM_STATIC Jim_Nvp *JIM_API(Jim_Nvp_value2name_simple)( const Jim_Nvp *nvp_table, int v );
 941
 942 JIM_STATIC int JIM_API(Jim_Nvp_name2value)( Jim_Interp *interp, const Jim_Nvp *nvp_table, const char *name, Jim_Nvp **result );
 943 JIM_STATIC int JIM_API(Jim_Nvp_name2value_nocase)( Jim_Interp *interp, const Jim_Nvp *nvp_table, const char *name, Jim_Nvp **result);
 944 JIM_STATIC int JIM_API(Jim_Nvp_value2name)( Jim_Interp *interp, const Jim_Nvp *nvp_table, int value, Jim_Nvp **result );
 945
 946 JIM_STATIC int JIM_API(Jim_Nvp_name2value_obj)( Jim_Interp *interp, const Jim_Nvp *nvp_table, Jim_Obj *name_obj, Jim_Nvp **result );
 947 JIM_STATIC int JIM_API(Jim_Nvp_name2value_obj_nocase)( Jim_Interp *interp, const Jim_Nvp *nvp_table, Jim_Obj *name_obj, Jim_Nvp **result );
 948 JIM_STATIC int JIM_API(Jim_Nvp_value2name_obj)( Jim_Interp *interp, const Jim_Nvp *nvp_table, Jim_Obj *value_obj, Jim_Nvp **result );
 949
 950 /** prints a nice 'unknown' parameter error message to the 'result' */
 951 JIM_STATIC void JIM_API(Jim_SetResult_NvpUnknown)( Jim_Interp *interp,
 952                                                                                                    Jim_Obj *param_name,
 953                                                                                                    Jim_Obj *param_value,
 954                                                                                                    const Jim_Nvp *nvp_table );
 955
 956
 957 /** Debug: convert argc/argv into a printable string for printf() debug
 958  *
 959  * \param interp - the interpeter
 960  * \param argc   - arg count
 961  * \param argv   - the objects
 962  *
 963  * \returns string pointer holding the text.
 964  *
 965  * Note, next call to this function will free the old (last) string.
 966  *
 967  * For example might want do this:
 968  * \code
 969  *     fp = fopen("some.file.log", "a" );
 970  *     fprintf( fp, "PARAMS are: %s\n", Jim_DebugArgvString( interp, argc, argv ) );
 971  *     fclose(fp);
 972  * \endcode
 973  */
 974 JIM_STATIC const char *JIM_API( Jim_Debug_ArgvString )( Jim_Interp *interp, int argc, Jim_Obj *const *argv );
 975
 976
 977 /** A TCL -ish GetOpt like code.
 978  *
 979  * Some TCL objects have various "configuration" values.
 980  * For example - in Tcl/Tk the "buttons" have many options.
 981  *
 982  * Usefull when dealing with command options.
 983  * that may come in any order...
 984  *
 985  * Does not support "-foo=123" type options.
 986  * Only supports tcl type options, like "-foo 123"
 987  */
 988
 989 typedef struct jim_getopt {
 990         Jim_Interp     *interp;
 991         int            argc;
 992         Jim_Obj        * const * argv;
 993         int            isconfigure; /* non-zero if configure */
 994 } Jim_GetOptInfo;
 995
 996 /** GetOpt - how to.
 997  *
 998  * Example (short and incomplete):
 999  * \code
1000  *   Jim_GetOptInfo goi;
1001  *
1002  *   Jim_GetOpt_Setup( &goi, interp, argc, argv );
1003  *
1004  *   while( goi.argc ){
1005  *         e = Jim_GetOpt_Nvp( &goi, nvp_options, &n );
1006  *         if( e != JIM_OK ){
1007  *               Jim_GetOpt_NvpUnknown( &goi, nvp_options, 0 );
1008  *               return e;
1009  *         }
1010  *
1011  *         switch( n->value ){
1012  *         case ALIVE:
1013  *             printf("Option ALIVE specified\n");
1014  *             break;
1015  *         case FIRST:
1016  *             if( goi.argc < 1 ){
1017  *                     .. not enough args error ..
1018  *             }
1019  *             Jim_GetOpt_String( &goi, &cp, NULL );
1020  *             printf("FIRSTNAME: %s\n", cp );
1021  *         case AGE:
1022  *             Jim_GetOpt_Wide( &goi, &w );
1023  *             printf("AGE: %d\n", (int)(w) );
1024  *             break;
1025  *         case POLITICS:
1026  *             e = Jim_GetOpt_Nvp( &goi, nvp_politics, &n );
1027  *             if( e != JIM_OK ){
1028  *                 Jim_GetOpt_NvpUnknown( &goi, nvp_politics, 1 );
1029  *                 return e;
1030  *             }
1031  *         }
1032  *  }
1033  *
1034  * \endcode
1035  *
1036  */
1037
1038 /** Setup GETOPT
1039  *
1040  * \param goi    - get opt info to be initialized
1041  * \param interp - jim interp
1042  * \param argc   - argc count.
1043  * \param argv   - argv (will be copied)
1044  *
1045  * \code
1046  *     Jim_GetOptInfo  goi;
1047  *
1048  *     Jim_GetOptSetup( &goi, interp, argc, argv );
1049  * \endcode
1050  */
1051
1052 JIM_STATIC int JIM_API( Jim_GetOpt_Setup )( Jim_GetOptInfo *goi,
1053                                                                                         Jim_Interp *interp,
1054                                                                                         int argc,
1055                                                                                         Jim_Obj * const *  argv );
1056
1057
1058 /** Debug - Dump parameters to stderr
1059  * \param goi - current parameters
1060  */
1061 JIM_STATIC void JIM_API( Jim_GetOpt_Debug )( Jim_GetOptInfo *goi);
1062
1063
1064
1065 /** Remove argv[0] from the list.
1066  *
1067  * \param goi - get opt info
1068  * \param puthere - where param is put
1069  *
1070  */
1071 JIM_STATIC int JIM_API( Jim_GetOpt_Obj)( Jim_GetOptInfo *goi, Jim_Obj **puthere );
1072
1073 /** Remove argv[0] as string.
1074  *
1075  * \param goi     - get opt info
1076  * \param puthere - where param is put
1077  */
1078 JIM_STATIC int JIM_API( Jim_GetOpt_String )( Jim_GetOptInfo *goi, char **puthere, int *len );
1079
1080 /** Remove argv[0] as double.
1081  *
1082  * \param goi     - get opt info
1083  * \param puthere - where param is put.
1084  *
1085  */
1086 JIM_STATIC int JIM_API( Jim_GetOpt_Double )( Jim_GetOptInfo *goi, double *puthere );
1087
1088 /** Remove argv[0] as wide.
1089  *
1090  * \param goi     - get opt info
1091  * \param puthere - where param is put.
1092  */
1093 JIM_STATIC int JIM_API( Jim_GetOpt_Wide )( Jim_GetOptInfo *goi, jim_wide *puthere );
1094
1095 /** Remove argv[0] as NVP.
1096  *
1097  * \param goi     - get opt info
1098  * \param lookup  - nvp lookup table
1099  * \param puthere - where param is put.
1100  *
1101  */
1102 JIM_STATIC int JIM_API( Jim_GetOpt_Nvp)( Jim_GetOptInfo *goi, const Jim_Nvp *lookup, Jim_Nvp **puthere );
1103
1104 /** Create an appropriate error message for an NVP.
1105  *
1106  * \param goi - options info
1107  * \param lookup - the NVP table that was used.
1108  * \param hadprefix - 0 or 1 if the option had a prefix.
1109  *
1110  * This function will set the "interp->result" to a human readable
1111  * error message listing the available options.
1112  *
1113  * This function assumes the previous option argv[-1] is the unknown string.
1114  *
1115  * If this option had some prefix, then pass "hadprefix=1" else pass "hadprefix=0"
1116  *
1117  * Example:
1118  * \code
1119  *
1120  *  while( goi.argc ){
1121  *     // Get the next option
1122  *     e = Jim_GetOpt_Nvp( &goi, cmd_options, &n );
1123  *     if( e != JIM_OK ){
1124  *          // option was not recognized
1125  *          // pass 'hadprefix=0' because there is no prefix
1126  *          Jim_GetOpt_NvpUnknown( &goi, cmd_options, 0 );
1127  *          return e;
1128  *     }
1129  *
1130  *     switch( n->value ){
1131  *     case OPT_SEX:
1132  *          // handle:  --sex male|female|lots|needmore
1133  *          e = Jim_GetOpt_Nvp( &goi, &nvp_sex, &n );
1134  *          if( e != JIM_OK ){
1135  *               Jim_GetOpt_NvpUnknown( &ogi, nvp_sex, 1 );
1136  *               return e;
1137  *          }
1138  *          printf("Code: (%d) is %s\n", n->value, n->name );
1139  *          break;
1140  *     case ...:
1141  *          [snip]
1142  *     }
1143  * }
1144  * \endcode
1145  *
1146  */
1147 JIM_STATIC void JIM_API( Jim_GetOpt_NvpUnknown)( Jim_GetOptInfo *goi, const Jim_Nvp *lookup, int hadprefix );
1148
1149
1150 /** Remove argv[0] as Enum
1151  *
1152  * \param goi     - get opt info
1153  * \param lookup  - lookup table.
1154  * \param puthere - where param is put.
1155  *
1156  */
1157 JIM_STATIC int JIM_API( Jim_GetOpt_Enum)( Jim_GetOptInfo *goi, const char * const *  lookup, int *puthere );
1158
1159
1160 #undef JIM_STATIC
1161 #undef JIM_API
1162
1163 #ifndef __JIM_CORE__
1164
1165 #define JIM_GET_API(name) \
1166     Jim_GetApi(interp, "Jim_" #name, ((void *)&Jim_ ## name))
1167
1168 #if defined JIM_EXTENSION || defined JIM_EMBEDDED
1169 /* This must be included "inline" inside the extension */
1170 static void Jim_InitExtension(Jim_Interp *interp)
1171 {
1172   Jim_GetApi = interp->getApiFuncPtr;
1173
1174   JIM_GET_API(Alloc);
1175   JIM_GET_API(Free);
1176   JIM_GET_API(Eval);
1177   JIM_GET_API(Eval_Named);
1178   JIM_GET_API(EvalGlobal);
1179   JIM_GET_API(EvalFile);
1180   JIM_GET_API(EvalObj);
1181   JIM_GET_API(EvalObjBackground);
1182   JIM_GET_API(EvalObjVector);
1183   JIM_GET_API(InitHashTable);
1184   JIM_GET_API(ExpandHashTable);
1185   JIM_GET_API(AddHashEntry);
1186   JIM_GET_API(ReplaceHashEntry);
1187   JIM_GET_API(DeleteHashEntry);
1188   JIM_GET_API(FreeHashTable);
1189   JIM_GET_API(FindHashEntry);
1190   JIM_GET_API(ResizeHashTable);
1191   JIM_GET_API(GetHashTableIterator);
1192   JIM_GET_API(NextHashEntry);
1193   JIM_GET_API(NewObj);
1194   JIM_GET_API(FreeObj);
1195   JIM_GET_API(InvalidateStringRep);
1196   JIM_GET_API(InitStringRep);
1197   JIM_GET_API(DuplicateObj);
1198   JIM_GET_API(GetString);
1199   JIM_GET_API(Length);
1200   JIM_GET_API(InvalidateStringRep);
1201   JIM_GET_API(NewStringObj);
1202   JIM_GET_API(NewStringObjNoAlloc);
1203   JIM_GET_API(AppendString);
1204   JIM_GET_API(AppendString_sprintf);
1205   JIM_GET_API(AppendObj);
1206   JIM_GET_API(AppendStrings);
1207   JIM_GET_API(StringEqObj);
1208   JIM_GET_API(StringMatchObj);
1209   JIM_GET_API(StringRangeObj);
1210   JIM_GET_API(FormatString);
1211   JIM_GET_API(ScanString);
1212   JIM_GET_API(CompareStringImmediate);
1213   JIM_GET_API(NewReference);
1214   JIM_GET_API(GetReference);
1215   JIM_GET_API(SetFinalizer);
1216   JIM_GET_API(GetFinalizer);
1217   JIM_GET_API(CreateInterp);
1218   JIM_GET_API(FreeInterp);
1219   JIM_GET_API(GetExitCode);
1220   JIM_GET_API(SetStdin);
1221   JIM_GET_API(SetStdout);
1222   JIM_GET_API(SetStderr);
1223   JIM_GET_API(CreateCommand);
1224   JIM_GET_API(CreateProcedure);
1225   JIM_GET_API(DeleteCommand);
1226   JIM_GET_API(RenameCommand);
1227   JIM_GET_API(GetCommand);
1228   JIM_GET_API(SetVariable);
1229   JIM_GET_API(SetVariableStr);
1230   JIM_GET_API(SetGlobalVariableStr);
1231   JIM_GET_API(SetVariableStrWithStr);
1232   JIM_GET_API(SetVariableLink);
1233   JIM_GET_API(GetVariable);
1234   JIM_GET_API(GetCallFrameByLevel);
1235   JIM_GET_API(Collect);
1236   JIM_GET_API(CollectIfNeeded);
1237   JIM_GET_API(GetIndex);
1238   JIM_GET_API(NewListObj);
1239   JIM_GET_API(ListInsertElements);
1240   JIM_GET_API(ListAppendElement);
1241   JIM_GET_API(ListAppendList);
1242   JIM_GET_API(ListLength);
1243   JIM_GET_API(ListIndex);
1244   JIM_GET_API(SetListIndex);
1245   JIM_GET_API(ConcatObj);
1246   JIM_GET_API(NewDictObj);
1247   JIM_GET_API(DictKey);
1248   JIM_GET_API(DictKeysVector);
1249   JIM_GET_API(GetIndex);
1250   JIM_GET_API(GetReturnCode);
1251   JIM_GET_API(EvalExpression);
1252   JIM_GET_API(GetBoolFromExpr);
1253   JIM_GET_API(GetWide);
1254   JIM_GET_API(GetLong);
1255   JIM_GET_API(SetWide);
1256   JIM_GET_API(NewIntObj);
1257   JIM_GET_API(GetDouble);
1258   JIM_GET_API(SetDouble);
1259   JIM_GET_API(NewDoubleObj);
1260   JIM_GET_API(WrongNumArgs);
1261   JIM_GET_API(SetDictKeysVector);
1262   JIM_GET_API(SubstObj);
1263   JIM_GET_API(RegisterApi);
1264   JIM_GET_API(PrintErrorMessage);
1265   JIM_GET_API(InteractivePrompt);
1266   JIM_GET_API(RegisterCoreCommands);
1267   JIM_GET_API(GetSharedString);
1268   JIM_GET_API(ReleaseSharedString);
1269   JIM_GET_API(Panic);
1270   JIM_GET_API(StrDup);
1271   JIM_GET_API(UnsetVariable);
1272   JIM_GET_API(GetVariableStr);
1273   JIM_GET_API(GetGlobalVariable);
1274   JIM_GET_API(GetGlobalVariableStr);
1275   JIM_GET_API(GetAssocData);
1276   JIM_GET_API(SetAssocData);
1277   JIM_GET_API(DeleteAssocData);
1278   JIM_GET_API(GetEnum);
1279   JIM_GET_API(GetNvp);
1280   JIM_GET_API(ScriptIsComplete);
1281   JIM_GET_API(PackageProvide);
1282   JIM_GET_API(PackageRequire);
1283   JIM_GET_API(InitStack);
1284   JIM_GET_API(FreeStack);
1285   JIM_GET_API(StackLen);
1286   JIM_GET_API(StackPush);
1287   JIM_GET_API(StackPop);
1288   JIM_GET_API(StackPeek);
1289   JIM_GET_API(FreeStackElements);
1290   JIM_GET_API(fprintf  );
1291   JIM_GET_API(vfprintf );
1292   JIM_GET_API(fwrite   );
1293   JIM_GET_API(fread    );
1294   JIM_GET_API(fflush   );
1295   JIM_GET_API(fgets    );
1296   JIM_GET_API(Nvp_name2value);
1297   JIM_GET_API(Nvp_name2value_nocase);
1298   JIM_GET_API(Nvp_name2value_simple);
1299
1300   JIM_GET_API(Nvp_value2name);
1301   JIM_GET_API(Nvp_value2name_simple);
1302
1303
1304   JIM_GET_API(Nvp_name2value_obj);
1305   JIM_GET_API(Nvp_value2name_obj);
1306   JIM_GET_API(Nvp_name2value_obj_nocase);
1307
1308   JIM_GET_API(GetOpt_Setup);
1309   JIM_GET_API(GetOpt_Obj);
1310   JIM_GET_API(GetOpt_String);
1311   JIM_GET_API(GetOpt_Double);
1312   JIM_GET_API(GetOpt_Wide);
1313   JIM_GET_API(GetOpt_Nvp);
1314   JIM_GET_API(GetOpt_NvpUnknown);
1315   JIM_GET_API(GetOpt_Enum);
1316   JIM_GET_API(GetOpt_Debug);
1317   JIM_GET_API(SetResult_sprintf);
1318   JIM_GET_API(SetResult_NvpUnknown);
1319   JIM_GET_API(Debug_ArgvString);
1320 }
1321 #endif /* defined JIM_EXTENSION || defined JIM_EMBEDDED */
1322
1323 #undef JIM_GET_API
1324
1325 #ifdef JIM_EMBEDDED
1326 Jim_Interp *ExportedJimCreateInterp(void);
1327 static __inline__ void Jim_InitEmbedded(void) {
1328     Jim_Interp *i = ExportedJimCreateInterp();
1329     Jim_InitExtension(i);
1330     Jim_FreeInterp(i);
1331 }
1332 #endif /* JIM_EMBEDDED */
1333 #endif /* __JIM_CORE__ */
1334
1335 #ifdef __cplusplus
1336 }
1337 #endif
1338
1339 #endif /* __JIM__H */