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