core: improvements to garbage collection
[jimtcl.git] / jim.h
blobad66b1682288ddf8de722e08a7b8351f6214a525
1 /* Jim - A small embeddable Tcl interpreter
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>
11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions
13 * are met:
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.
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.
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.
39 *--- Inline Header File Documentation ---
40 * [By Duane Ellis, openocd@duaneellis.com, 8/18/8]
42 * Belief is "Jim" would greatly benefit if Jim Internals where
43 * documented in some way - form whatever, and perhaps - the package:
44 * 'doxygen' is the correct approach to do that.
46 * Details, see: http://www.stack.nl/~dimitri/doxygen/
48 * To that end please follow these guide lines:
50 * (A) Document the PUBLIC api in the .H file.
52 * (B) Document JIM Internals, in the .C file.
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.
60 * (D) Use minimal Doxygen tags.
62 * This will be an "ongoing work in progress" for some time.
63 **/
65 #ifndef __JIM__H
66 #define __JIM__H
68 #ifdef __cplusplus
69 extern "C" {
70 #endif
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 */
78 /* -----------------------------------------------------------------------------
79 * System configuration
80 * autoconf (configure) will set these
81 * ---------------------------------------------------------------------------*/
82 #include <jim-win32compat.h>
84 #ifndef HAVE_NO_AUTOCONF
85 #include <jim-config.h>
86 #endif
88 /* -----------------------------------------------------------------------------
89 * Compiler specific fixes.
90 * ---------------------------------------------------------------------------*/
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
110 /* -----------------------------------------------------------------------------
111 * LIBC specific fixes
112 * ---------------------------------------------------------------------------*/
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
122 #define UCHAR(c) ((unsigned char)(c))
124 /* -----------------------------------------------------------------------------
125 * Exported defines
126 * ---------------------------------------------------------------------------*/
128 #define JIM_OK 0
129 #define JIM_ERR 1
130 #define JIM_RETURN 2
131 #define JIM_BREAK 3
132 #define JIM_CONTINUE 4
133 #define JIM_SIGNAL 5
134 #define JIM_EXIT 6
135 /* The following are internal codes and should never been seen/used */
136 #define JIM_EVAL 7
138 #define JIM_MAX_CALLFRAME_DEPTH 1000 /* default max nesting depth for procs */
139 #define JIM_MAX_EVAL_DEPTH 2000 /* default max nesting depth for eval */
141 /* Some function get an integer argument with flags to change
142 * the behaviour. */
144 /* Starting from 1 << 20 flags are reserved for private uses of
145 * different calls. This way the same 'flags' argument may be used
146 * to pass both global flags and private flags. */
147 #define JIM_PRIV_FLAG_SHIFT 20
149 #define JIM_NONE 0 /* no flags set */
150 #define JIM_ERRMSG 1 /* set an error message in the interpreter. */
151 #define JIM_ENUM_ABBREV 2 /* Jim_GetEnum() - Allow unambiguous abbreviation */
152 #define JIM_UNSHARED 4 /* Jim_GetVariable() - return unshared object */
153 #define JIM_MUSTEXIST 8 /* Jim_SetDictKeysVector() - fail if non-existent */
155 /* Flags for Jim_SubstObj() */
156 #define JIM_SUBST_NOVAR 1 /* don't perform variables substitutions */
157 #define JIM_SUBST_NOCMD 2 /* don't perform command substitutions */
158 #define JIM_SUBST_NOESC 4 /* don't perform escapes substitutions */
159 #define JIM_SUBST_FLAG 128 /* flag to indicate that this is a real substitution object */
161 /* Flags used by API calls getting a 'nocase' argument. */
162 #define JIM_CASESENS 0 /* case sensitive */
163 #define JIM_NOCASE 1 /* no case */
164 #define JIM_OPT_END 2 /* if implemented by a command (e.g. regexp), add -- to the argument list */
166 /* Filesystem related */
167 #define JIM_PATH_LEN 1024
169 /* Unused arguments generate annoying warnings... */
170 #define JIM_NOTUSED(V) ((void) V)
172 #define JIM_LIBPATH "auto_path"
173 #define JIM_INTERACTIVE "tcl_interactive"
175 /* -----------------------------------------------------------------------------
176 * Stack
177 * ---------------------------------------------------------------------------*/
179 typedef struct Jim_Stack {
180 int len;
181 int maxlen;
182 void **vector;
183 } Jim_Stack;
185 /* -----------------------------------------------------------------------------
186 * Hash table
187 * ---------------------------------------------------------------------------*/
189 typedef struct Jim_HashEntry {
190 void *key;
191 union {
192 void *val;
193 int intval;
194 } u;
195 struct Jim_HashEntry *next;
196 } Jim_HashEntry;
198 typedef struct Jim_HashTableType {
199 unsigned int (*hashFunction)(const void *key);
200 void *(*keyDup)(void *privdata, const void *key);
201 void *(*valDup)(void *privdata, const void *obj);
202 int (*keyCompare)(void *privdata, const void *key1, const void *key2);
203 void (*keyDestructor)(void *privdata, void *key);
204 void (*valDestructor)(void *privdata, void *obj);
205 } Jim_HashTableType;
207 typedef struct Jim_HashTable {
208 Jim_HashEntry **table;
209 const Jim_HashTableType *type;
210 void *privdata;
211 unsigned int size;
212 unsigned int sizemask;
213 unsigned int used;
214 unsigned int collisions;
215 unsigned int uniq;
216 } Jim_HashTable;
218 typedef struct Jim_HashTableIterator {
219 Jim_HashTable *ht;
220 Jim_HashEntry *entry, *nextEntry;
221 int index;
222 } Jim_HashTableIterator;
224 /* This is the initial size of every hash table */
225 #define JIM_HT_INITIAL_SIZE 16
227 /* ------------------------------- Macros ------------------------------------*/
228 #define Jim_FreeEntryVal(ht, entry) \
229 if ((ht)->type->valDestructor) \
230 (ht)->type->valDestructor((ht)->privdata, (entry)->u.val)
232 #define Jim_SetHashVal(ht, entry, _val_) do { \
233 if ((ht)->type->valDup) \
234 (entry)->u.val = (ht)->type->valDup((ht)->privdata, (_val_)); \
235 else \
236 (entry)->u.val = (_val_); \
237 } while(0)
239 #define Jim_FreeEntryKey(ht, entry) \
240 if ((ht)->type->keyDestructor) \
241 (ht)->type->keyDestructor((ht)->privdata, (entry)->key)
243 #define Jim_SetHashKey(ht, entry, _key_) do { \
244 if ((ht)->type->keyDup) \
245 (entry)->key = (ht)->type->keyDup((ht)->privdata, (_key_)); \
246 else \
247 (entry)->key = (void *)(_key_); \
248 } while(0)
250 #define Jim_CompareHashKeys(ht, key1, key2) \
251 (((ht)->type->keyCompare) ? \
252 (ht)->type->keyCompare((ht)->privdata, (key1), (key2)) : \
253 (key1) == (key2))
255 #define Jim_HashKey(ht, key) ((ht)->type->hashFunction(key) + (ht)->uniq)
257 #define Jim_GetHashEntryKey(he) ((he)->key)
258 #define Jim_GetHashEntryVal(he) ((he)->u.val)
259 #define Jim_GetHashTableCollisions(ht) ((ht)->collisions)
260 #define Jim_GetHashTableSize(ht) ((ht)->size)
261 #define Jim_GetHashTableUsed(ht) ((ht)->used)
263 /* -----------------------------------------------------------------------------
264 * Jim_Obj structure
265 * ---------------------------------------------------------------------------*/
267 /* -----------------------------------------------------------------------------
268 * Jim object. This is mostly the same as Tcl_Obj itself,
269 * with the addition of the 'prev' and 'next' pointers.
270 * In Jim all the objects are stored into a linked list for GC purposes,
271 * so that it's possible to access every object living in a given interpreter
272 * sequentially. When an object is freed, it's moved into a different
273 * linked list, used as object pool.
275 * The refcount of a freed object is always -1.
276 * ---------------------------------------------------------------------------*/
277 typedef struct Jim_Obj {
278 char *bytes; /* string representation buffer. NULL = no string repr. */
279 const struct Jim_ObjType *typePtr; /* object type. */
280 int refCount; /* reference count */
281 int length; /* number of bytes in 'bytes', not including the null term. */
282 /* Internal representation union */
283 union {
284 /* integer number type */
285 jim_wide wideValue;
286 /* generic integer value (e.g. index, return code) */
287 int intValue;
288 /* double number type */
289 double doubleValue;
290 /* Generic pointer */
291 void *ptr;
292 /* Generic two pointers value */
293 struct {
294 void *ptr1;
295 void *ptr2;
296 } twoPtrValue;
297 /* Generic pointer, int, int value */
298 struct {
299 void *ptr;
300 int int1;
301 int int2;
302 } ptrIntValue;
303 /* Variable object */
304 struct {
305 struct Jim_Var *varPtr;
306 unsigned long callFrameId; /* for caching */
307 int global; /* If the variable name is globally scoped with :: */
308 } varValue;
309 /* Command object */
310 struct {
311 struct Jim_Obj *nsObj;
312 struct Jim_Cmd *cmdPtr;
313 unsigned long procEpoch; /* for caching */
314 } cmdValue;
315 /* List object */
316 struct {
317 struct Jim_Obj **ele; /* Elements vector */
318 int len; /* Length */
319 int maxLen; /* Allocated 'ele' length */
320 } listValue;
321 /* String type */
322 struct {
323 int maxLength;
324 int charLength; /* utf-8 char length. -1 if unknown */
325 } strValue;
326 /* Reference type */
327 struct {
328 unsigned long id;
329 struct Jim_Reference *refPtr;
330 } refValue;
331 /* Source type */
332 struct {
333 struct Jim_Obj *fileNameObj;
334 int lineNumber;
335 } sourceValue;
336 /* Dict substitution type */
337 struct {
338 struct Jim_Obj *varNameObjPtr;
339 struct Jim_Obj *indexObjPtr;
340 } dictSubstValue;
341 struct {
342 int line;
343 int argc;
344 } scriptLineValue;
345 } internalRep;
346 /* These fields add 8 or 16 bytes more for every object
347 * but this is required for efficient garbage collection
348 * of Jim references. */
349 struct Jim_Obj *prevObjPtr; /* pointer to the prev object. */
350 struct Jim_Obj *nextObjPtr; /* pointer to the next object. */
351 } Jim_Obj;
353 /* Jim_Obj related macros */
354 #define Jim_IncrRefCount(objPtr) \
355 ++(objPtr)->refCount
356 #define Jim_DecrRefCount(interp, objPtr) \
357 if (--(objPtr)->refCount <= 0) Jim_FreeObj(interp, objPtr)
358 #define Jim_IsShared(objPtr) \
359 ((objPtr)->refCount > 1)
361 /* This macro is used when we allocate a new object using
362 * Jim_New...Obj(), but for some error we need to destroy it.
363 * Instead to use Jim_IncrRefCount() + Jim_DecrRefCount() we
364 * can just call Jim_FreeNewObj. To call Jim_Free directly
365 * seems too raw, the object handling may change and we want
366 * that Jim_FreeNewObj() can be called only against objects
367 * that are believed to have refcount == 0. */
368 #define Jim_FreeNewObj Jim_FreeObj
370 /* Free the internal representation of the object. */
371 #define Jim_FreeIntRep(i,o) \
372 if ((o)->typePtr && (o)->typePtr->freeIntRepProc) \
373 (o)->typePtr->freeIntRepProc(i, o)
375 /* Get the internal representation pointer */
376 #define Jim_GetIntRepPtr(o) (o)->internalRep.ptr
378 /* Set the internal representation pointer */
379 #define Jim_SetIntRepPtr(o, p) \
380 (o)->internalRep.ptr = (p)
382 /* The object type structure.
383 * There are three methods.
385 * - freeIntRepProc is used to free the internal representation of the object.
386 * Can be NULL if there is nothing to free.
388 * - dupIntRepProc is used to duplicate the internal representation of the object.
389 * If NULL, when an object is duplicated, the internalRep union is
390 * directly copied from an object to another.
391 * Note that it's up to the caller to free the old internal repr of the
392 * object before to call the Dup method.
394 * - updateStringProc is used to create the string from the internal repr.
397 struct Jim_Interp;
399 typedef void (Jim_FreeInternalRepProc)(struct Jim_Interp *interp,
400 struct Jim_Obj *objPtr);
401 typedef void (Jim_DupInternalRepProc)(struct Jim_Interp *interp,
402 struct Jim_Obj *srcPtr, Jim_Obj *dupPtr);
403 typedef void (Jim_UpdateStringProc)(struct Jim_Obj *objPtr);
405 typedef struct Jim_ObjType {
406 const char *name; /* The name of the type. */
407 Jim_FreeInternalRepProc *freeIntRepProc;
408 Jim_DupInternalRepProc *dupIntRepProc;
409 Jim_UpdateStringProc *updateStringProc;
410 int flags;
411 } Jim_ObjType;
413 /* Jim_ObjType flags */
414 #define JIM_TYPE_NONE 0 /* No flags */
415 #define JIM_TYPE_REFERENCES 1 /* The object may contain references. */
417 /* -----------------------------------------------------------------------------
418 * Call frame, vars, commands structures
419 * ---------------------------------------------------------------------------*/
421 /* Call frame */
422 typedef struct Jim_CallFrame {
423 unsigned long id; /* Call Frame ID. Used for caching. */
424 int level; /* Level of this call frame. 0 = global */
425 struct Jim_HashTable vars; /* Where local vars are stored */
426 struct Jim_HashTable *staticVars; /* pointer to procedure static vars */
427 struct Jim_CallFrame *parent; /* The parent callframe */
428 Jim_Obj *const *argv; /* object vector of the current procedure call. */
429 int argc; /* number of args of the current procedure call. */
430 Jim_Obj *procArgsObjPtr; /* arglist object of the running procedure */
431 Jim_Obj *procBodyObjPtr; /* body object of the running procedure */
432 struct Jim_CallFrame *next; /* Callframes are in a linked list */
433 Jim_Obj *nsObj; /* Namespace for this proc call frame */
434 Jim_Obj *fileNameObj; /* file and line of caller of this proc (if available) */
435 int line;
436 Jim_Stack *localCommands; /* commands to be destroyed when the call frame is destroyed */
437 struct Jim_Obj *tailcallObj; /* Pending tailcall invocation */
438 struct Jim_Cmd *tailcallCmd; /* Resolved command for pending tailcall invocation */
439 } Jim_CallFrame;
441 /* The var structure. It just holds the pointer of the referenced
442 * object. If linkFramePtr is not NULL the variable is a link
443 * to a variable of name stored in objPtr living in the given callframe
444 * (this happens when the [global] or [upvar] command is used).
445 * The interp in order to always know how to free the Jim_Obj associated
446 * with a given variable because in Jim objects memory management is
447 * bound to interpreters. */
448 typedef struct Jim_Var {
449 Jim_Obj *objPtr;
450 struct Jim_CallFrame *linkFramePtr;
451 } Jim_Var;
453 /* The cmd structure. */
454 typedef int Jim_CmdProc(struct Jim_Interp *interp, int argc,
455 Jim_Obj *const *argv);
456 typedef void Jim_DelCmdProc(struct Jim_Interp *interp, void *privData);
460 /* A command is implemented in C if isproc is 0, otherwise
461 * it is a Tcl procedure with the arglist and body represented by the
462 * two objects referenced by arglistObjPtr and bodyObjPtr. */
463 typedef struct Jim_Cmd {
464 int inUse; /* Reference count */
465 int isproc; /* Is this a procedure? */
466 struct Jim_Cmd *prevCmd; /* Previous command defn if cmd created 'local' */
467 union {
468 struct {
469 /* native (C) command */
470 Jim_CmdProc *cmdProc; /* The command implementation */
471 Jim_DelCmdProc *delProc; /* Called when the command is deleted if != NULL */
472 void *privData; /* command-private data available via Jim_CmdPrivData() */
473 } native;
474 struct {
475 /* Tcl procedure */
476 Jim_Obj *argListObjPtr;
477 Jim_Obj *bodyObjPtr;
478 Jim_HashTable *staticVars; /* Static vars hash table. NULL if no statics. */
479 int argListLen; /* Length of argListObjPtr */
480 int reqArity; /* Number of required parameters */
481 int optArity; /* Number of optional parameters */
482 int argsPos; /* Position of 'args', if specified, or -1 */
483 int upcall; /* True if proc is currently in upcall */
484 struct Jim_ProcArg {
485 Jim_Obj *nameObjPtr; /* Name of this arg */
486 Jim_Obj *defaultObjPtr; /* Default value, (or rename for $args) */
487 } *arglist;
488 Jim_Obj *nsObj; /* Namespace for this proc */
489 } proc;
490 } u;
491 } Jim_Cmd;
493 /* Pseudo Random Number Generator State structure */
494 typedef struct Jim_PrngState {
495 unsigned char sbox[256];
496 unsigned int i, j;
497 } Jim_PrngState;
499 /* -----------------------------------------------------------------------------
500 * Jim interpreter structure.
501 * Fields similar to the real Tcl interpreter structure have the same names.
502 * ---------------------------------------------------------------------------*/
503 typedef struct Jim_Interp {
504 Jim_Obj *result; /* object returned by the last command called. */
505 int errorLine; /* Error line where an error occurred. */
506 Jim_Obj *errorFileNameObj; /* Error file where an error occurred. */
507 int addStackTrace; /* > 0 if a level should be added to the stack trace */
508 int maxCallFrameDepth; /* Used for infinite loop detection. */
509 int maxEvalDepth; /* Used for infinite loop detection. */
510 int evalDepth; /* Current eval depth */
511 int returnCode; /* Completion code to return on JIM_RETURN. */
512 int returnLevel; /* Current level of 'return -level' */
513 int exitCode; /* Code to return to the OS on JIM_EXIT. */
514 long id; /* Hold unique id for various purposes */
515 int signal_level; /* A nesting level of catch -signal */
516 jim_wide sigmask; /* Bit mask of caught signals, or 0 if none */
517 int (*signal_set_result)(struct Jim_Interp *interp, jim_wide sigmask); /* Set a result for the sigmask */
518 Jim_CallFrame *framePtr; /* Pointer to the current call frame */
519 Jim_CallFrame *topFramePtr; /* toplevel/global frame pointer. */
520 struct Jim_HashTable commands; /* Commands hash table */
521 unsigned long procEpoch; /* Incremented every time the result
522 of procedures names lookup caching
523 may no longer be valid. */
524 unsigned long callFrameEpoch; /* Incremented every time a new
525 callframe is created. This id is used for the
526 'ID' field contained in the Jim_CallFrame
527 structure. */
528 int local; /* If 'local' is in effect, newly defined procs keep a reference to the old defn */
529 int quitting; /* Set to 1 during Jim_FreeInterp() */
530 Jim_Obj *liveList; /* Linked list of all the live objects. */
531 Jim_Obj *freeList; /* Linked list of all the unused objects. */
532 Jim_Obj *currentScriptObj; /* Script currently in execution. */
533 Jim_Obj *nullScriptObj; /* script representation of an empty string */
534 Jim_Obj *emptyObj; /* Shared empty string object. */
535 Jim_Obj *trueObj; /* Shared true int object. */
536 Jim_Obj *falseObj; /* Shared false int object. */
537 unsigned long referenceNextId; /* Next id for reference. */
538 struct Jim_HashTable references; /* References hash table. */
539 unsigned long lastCollectId; /* reference max Id of the last GC
540 execution. It's set to ~0 while the collection
541 is running as sentinel to avoid to recursive
542 calls via the [collect] command inside
543 finalizers. */
544 jim_wide lastCollectTime; /* unix time of the last GC execution */
545 Jim_Obj *stackTrace; /* Stack trace object. */
546 Jim_Obj *errorProc; /* Name of last procedure which returned an error */
547 Jim_Obj *unknown; /* Unknown command cache */
548 Jim_Obj *defer; /* "jim::defer" */
549 int unknown_called; /* The unknown command has been invoked */
550 int errorFlag; /* Set if an error occurred during execution. */
551 void *cmdPrivData; /* Used to pass the private data pointer to
552 a command. It is set to what the user specified
553 via Jim_CreateCommand(). */
555 Jim_Cmd *oldCmdCache; /* commands that have been deleted, but may still be cached */
556 int oldCmdCacheSize; /* Number of delete commands */
557 struct Jim_CallFrame *freeFramesList; /* list of CallFrame structures. */
558 struct Jim_HashTable assocData; /* per-interp storage for use by packages */
559 Jim_PrngState *prngState; /* per interpreter Random Number Gen. state. */
560 struct Jim_HashTable packages; /* Provided packages hash table */
561 Jim_Stack *loadHandles; /* handles of loaded modules [load] */
562 } Jim_Interp;
564 /* Currently provided as macro that performs the increment.
565 * At some point may be a real function doing more work.
566 * The proc epoch is used in order to know when a command lookup
567 * cached can no longer considered valid. */
568 #define Jim_SetResultString(i,s,l) Jim_SetResult(i, Jim_NewStringObj(i,s,l))
569 #define Jim_SetResultInt(i,intval) Jim_SetResult(i, Jim_NewIntObj(i,intval))
570 /* Note: Using trueObj and falseObj here makes some things slower...*/
571 #define Jim_SetResultBool(i,b) Jim_SetResultInt(i, b)
572 #define Jim_SetEmptyResult(i) Jim_SetResult(i, (i)->emptyObj)
573 #define Jim_GetResult(i) ((i)->result)
574 #define Jim_CmdPrivData(i) ((i)->cmdPrivData)
576 /* Note that 'o' is expanded only one time inside this macro,
577 * so it's safe to use side effects. */
578 #define Jim_SetResult(i,o) do { \
579 Jim_Obj *_resultObjPtr_ = (o); \
580 Jim_IncrRefCount(_resultObjPtr_); \
581 Jim_DecrRefCount(i,(i)->result); \
582 (i)->result = _resultObjPtr_; \
583 } while(0)
585 /* Use this for filehandles, etc. which need a unique id */
586 #define Jim_GetId(i) (++(i)->id)
588 /* Reference structure. The interpreter pointer is held within privdata member in HashTable */
589 #define JIM_REFERENCE_TAGLEN 7 /* The tag is fixed-length, because the reference
590 string representation must be fixed length. */
591 typedef struct Jim_Reference {
592 Jim_Obj *objPtr;
593 Jim_Obj *finalizerCmdNamePtr;
594 char tag[JIM_REFERENCE_TAGLEN+1];
595 } Jim_Reference;
597 /* -----------------------------------------------------------------------------
598 * Exported API prototypes.
599 * ---------------------------------------------------------------------------*/
601 #define Jim_NewEmptyStringObj(i) Jim_NewStringObj(i, "", 0)
602 #define Jim_FreeHashTableIterator(iter) Jim_Free(iter)
604 #define JIM_EXPORT
606 /* Memory allocation */
607 JIM_EXPORT void *Jim_Alloc (int size);
608 JIM_EXPORT void *Jim_Realloc(void *ptr, int size);
609 JIM_EXPORT void Jim_Free (void *ptr);
610 JIM_EXPORT char * Jim_StrDup (const char *s);
611 JIM_EXPORT char *Jim_StrDupLen(const char *s, int l);
613 /* environment */
614 JIM_EXPORT char **Jim_GetEnviron(void);
615 JIM_EXPORT void Jim_SetEnviron(char **env);
616 JIM_EXPORT int Jim_MakeTempFile(Jim_Interp *interp, const char *filename_template, int unlink_file);
618 /* evaluation */
619 JIM_EXPORT int Jim_Eval(Jim_Interp *interp, const char *script);
620 /* in C code, you can do this and get better error messages */
621 /* Jim_EvalSource( interp, __FILE__, __LINE__ , "some tcl commands"); */
622 JIM_EXPORT int Jim_EvalSource(Jim_Interp *interp, const char *filename, int lineno, const char *script);
623 /* Backwards compatibility */
624 #define Jim_Eval_Named(I, S, F, L) Jim_EvalSource((I), (F), (L), (S))
626 JIM_EXPORT int Jim_EvalGlobal(Jim_Interp *interp, const char *script);
627 JIM_EXPORT int Jim_EvalFile(Jim_Interp *interp, const char *filename);
628 JIM_EXPORT int Jim_EvalFileGlobal(Jim_Interp *interp, const char *filename);
629 JIM_EXPORT int Jim_EvalObj (Jim_Interp *interp, Jim_Obj *scriptObjPtr);
630 JIM_EXPORT int Jim_EvalObjVector (Jim_Interp *interp, int objc,
631 Jim_Obj *const *objv);
632 JIM_EXPORT int Jim_EvalObjList(Jim_Interp *interp, Jim_Obj *listObj);
633 JIM_EXPORT int Jim_EvalObjPrefix(Jim_Interp *interp, Jim_Obj *prefix,
634 int objc, Jim_Obj *const *objv);
635 #define Jim_EvalPrefix(i, p, oc, ov) Jim_EvalObjPrefix((i), Jim_NewStringObj((i), (p), -1), (oc), (ov))
636 JIM_EXPORT int Jim_EvalNamespace(Jim_Interp *interp, Jim_Obj *scriptObj, Jim_Obj *nsObj);
637 JIM_EXPORT int Jim_SubstObj (Jim_Interp *interp, Jim_Obj *substObjPtr,
638 Jim_Obj **resObjPtrPtr, int flags);
640 /* stack */
641 JIM_EXPORT void Jim_InitStack(Jim_Stack *stack);
642 JIM_EXPORT void Jim_FreeStack(Jim_Stack *stack);
643 JIM_EXPORT int Jim_StackLen(Jim_Stack *stack);
644 JIM_EXPORT void Jim_StackPush(Jim_Stack *stack, void *element);
645 JIM_EXPORT void * Jim_StackPop(Jim_Stack *stack);
646 JIM_EXPORT void * Jim_StackPeek(Jim_Stack *stack);
647 JIM_EXPORT void Jim_FreeStackElements(Jim_Stack *stack, void (*freeFunc)(void *ptr));
649 /* hash table */
650 JIM_EXPORT int Jim_InitHashTable (Jim_HashTable *ht,
651 const Jim_HashTableType *type, void *privdata);
652 JIM_EXPORT void Jim_ExpandHashTable (Jim_HashTable *ht,
653 unsigned int size);
654 JIM_EXPORT int Jim_AddHashEntry (Jim_HashTable *ht, const void *key,
655 void *val);
656 JIM_EXPORT int Jim_ReplaceHashEntry (Jim_HashTable *ht,
657 const void *key, void *val);
658 JIM_EXPORT int Jim_DeleteHashEntry (Jim_HashTable *ht,
659 const void *key);
660 JIM_EXPORT int Jim_FreeHashTable (Jim_HashTable *ht);
661 JIM_EXPORT Jim_HashEntry * Jim_FindHashEntry (Jim_HashTable *ht,
662 const void *key);
663 JIM_EXPORT Jim_HashTableIterator *Jim_GetHashTableIterator
664 (Jim_HashTable *ht);
665 JIM_EXPORT Jim_HashEntry * Jim_NextHashEntry
666 (Jim_HashTableIterator *iter);
668 /* objects */
669 JIM_EXPORT Jim_Obj * Jim_NewObj (Jim_Interp *interp);
670 JIM_EXPORT void Jim_FreeObj (Jim_Interp *interp, Jim_Obj *objPtr);
671 JIM_EXPORT void Jim_InvalidateStringRep (Jim_Obj *objPtr);
672 JIM_EXPORT Jim_Obj * Jim_DuplicateObj (Jim_Interp *interp,
673 Jim_Obj *objPtr);
674 JIM_EXPORT const char * Jim_GetString(Jim_Obj *objPtr,
675 int *lenPtr);
676 JIM_EXPORT const char *Jim_String(Jim_Obj *objPtr);
677 JIM_EXPORT int Jim_Length(Jim_Obj *objPtr);
679 /* string object */
680 JIM_EXPORT Jim_Obj * Jim_NewStringObj (Jim_Interp *interp,
681 const char *s, int len);
682 JIM_EXPORT Jim_Obj *Jim_NewStringObjUtf8(Jim_Interp *interp,
683 const char *s, int charlen);
684 JIM_EXPORT Jim_Obj * Jim_NewStringObjNoAlloc (Jim_Interp *interp,
685 char *s, int len);
686 JIM_EXPORT void Jim_AppendString (Jim_Interp *interp, Jim_Obj *objPtr,
687 const char *str, int len);
688 JIM_EXPORT void Jim_AppendObj (Jim_Interp *interp, Jim_Obj *objPtr,
689 Jim_Obj *appendObjPtr);
690 JIM_EXPORT void Jim_AppendStrings (Jim_Interp *interp,
691 Jim_Obj *objPtr, ...);
692 JIM_EXPORT int Jim_StringEqObj(Jim_Obj *aObjPtr, Jim_Obj *bObjPtr);
693 JIM_EXPORT int Jim_StringMatchObj (Jim_Interp *interp, Jim_Obj *patternObjPtr,
694 Jim_Obj *objPtr, int nocase);
695 JIM_EXPORT Jim_Obj * Jim_StringRangeObj (Jim_Interp *interp,
696 Jim_Obj *strObjPtr, Jim_Obj *firstObjPtr,
697 Jim_Obj *lastObjPtr);
698 JIM_EXPORT Jim_Obj * Jim_FormatString (Jim_Interp *interp,
699 Jim_Obj *fmtObjPtr, int objc, Jim_Obj *const *objv);
700 JIM_EXPORT Jim_Obj * Jim_ScanString (Jim_Interp *interp, Jim_Obj *strObjPtr,
701 Jim_Obj *fmtObjPtr, int flags);
702 JIM_EXPORT int Jim_CompareStringImmediate (Jim_Interp *interp,
703 Jim_Obj *objPtr, const char *str);
704 JIM_EXPORT int Jim_StringCompareObj(Jim_Interp *interp, Jim_Obj *firstObjPtr,
705 Jim_Obj *secondObjPtr, int nocase);
706 JIM_EXPORT int Jim_Utf8Length(Jim_Interp *interp, Jim_Obj *objPtr);
708 /* reference object */
709 JIM_EXPORT Jim_Obj * Jim_NewReference (Jim_Interp *interp,
710 Jim_Obj *objPtr, Jim_Obj *tagPtr, Jim_Obj *cmdNamePtr);
711 JIM_EXPORT Jim_Reference * Jim_GetReference (Jim_Interp *interp,
712 Jim_Obj *objPtr);
713 JIM_EXPORT int Jim_SetFinalizer (Jim_Interp *interp, Jim_Obj *objPtr, Jim_Obj *cmdNamePtr);
714 JIM_EXPORT int Jim_GetFinalizer (Jim_Interp *interp, Jim_Obj *objPtr, Jim_Obj **cmdNamePtrPtr);
716 /* interpreter */
717 JIM_EXPORT Jim_Interp * Jim_CreateInterp (void);
718 JIM_EXPORT void Jim_FreeInterp (Jim_Interp *i);
719 JIM_EXPORT int Jim_GetExitCode (Jim_Interp *interp);
720 JIM_EXPORT const char *Jim_ReturnCode(int code);
721 JIM_EXPORT void Jim_SetResultFormatted(Jim_Interp *interp, const char *format, ...);
723 /* commands */
724 JIM_EXPORT void Jim_RegisterCoreCommands (Jim_Interp *interp);
725 JIM_EXPORT int Jim_CreateCommand (Jim_Interp *interp,
726 const char *cmdName, Jim_CmdProc *cmdProc, void *privData,
727 Jim_DelCmdProc *delProc);
728 JIM_EXPORT int Jim_DeleteCommand (Jim_Interp *interp,
729 Jim_Obj *cmdNameObj);
730 JIM_EXPORT int Jim_RenameCommand (Jim_Interp *interp,
731 Jim_Obj *oldNameObj, Jim_Obj *newNameObj);
732 JIM_EXPORT Jim_Cmd * Jim_GetCommand (Jim_Interp *interp,
733 Jim_Obj *objPtr, int flags);
734 JIM_EXPORT int Jim_SetVariable (Jim_Interp *interp,
735 Jim_Obj *nameObjPtr, Jim_Obj *valObjPtr);
736 JIM_EXPORT int Jim_SetVariableStr (Jim_Interp *interp,
737 const char *name, Jim_Obj *objPtr);
738 JIM_EXPORT int Jim_SetGlobalVariableStr (Jim_Interp *interp,
739 const char *name, Jim_Obj *objPtr);
740 JIM_EXPORT int Jim_SetVariableStrWithStr (Jim_Interp *interp,
741 const char *name, const char *val);
742 JIM_EXPORT int Jim_SetVariableLink (Jim_Interp *interp,
743 Jim_Obj *nameObjPtr, Jim_Obj *targetNameObjPtr,
744 Jim_CallFrame *targetCallFrame);
745 JIM_EXPORT Jim_Obj * Jim_MakeGlobalNamespaceName(Jim_Interp *interp,
746 Jim_Obj *nameObjPtr);
747 JIM_EXPORT Jim_Obj * Jim_GetVariable (Jim_Interp *interp,
748 Jim_Obj *nameObjPtr, int flags);
749 JIM_EXPORT Jim_Obj * Jim_GetGlobalVariable (Jim_Interp *interp,
750 Jim_Obj *nameObjPtr, int flags);
751 JIM_EXPORT Jim_Obj * Jim_GetVariableStr (Jim_Interp *interp,
752 const char *name, int flags);
753 JIM_EXPORT Jim_Obj * Jim_GetGlobalVariableStr (Jim_Interp *interp,
754 const char *name, int flags);
755 JIM_EXPORT int Jim_UnsetVariable (Jim_Interp *interp,
756 Jim_Obj *nameObjPtr, int flags);
758 /* call frame */
759 JIM_EXPORT Jim_CallFrame *Jim_GetCallFrameByLevel(Jim_Interp *interp,
760 Jim_Obj *levelObjPtr);
762 /* garbage collection */
763 JIM_EXPORT int Jim_Collect (Jim_Interp *interp);
764 JIM_EXPORT void Jim_CollectIfNeeded (Jim_Interp *interp);
766 /* index object */
767 JIM_EXPORT int Jim_GetIndex (Jim_Interp *interp, Jim_Obj *objPtr,
768 int *indexPtr);
770 /* list object */
771 JIM_EXPORT Jim_Obj * Jim_NewListObj (Jim_Interp *interp,
772 Jim_Obj *const *elements, int len);
773 JIM_EXPORT void Jim_ListInsertElements (Jim_Interp *interp,
774 Jim_Obj *listPtr, int listindex, int objc, Jim_Obj *const *objVec);
775 JIM_EXPORT void Jim_ListAppendElement (Jim_Interp *interp,
776 Jim_Obj *listPtr, Jim_Obj *objPtr);
777 JIM_EXPORT void Jim_ListAppendList (Jim_Interp *interp,
778 Jim_Obj *listPtr, Jim_Obj *appendListPtr);
779 JIM_EXPORT int Jim_ListLength (Jim_Interp *interp, Jim_Obj *objPtr);
780 JIM_EXPORT int Jim_ListIndex (Jim_Interp *interp, Jim_Obj *listPrt,
781 int listindex, Jim_Obj **objPtrPtr, int seterr);
782 JIM_EXPORT Jim_Obj *Jim_ListGetIndex(Jim_Interp *interp, Jim_Obj *listPtr, int idx);
783 JIM_EXPORT int Jim_SetListIndex (Jim_Interp *interp,
784 Jim_Obj *varNamePtr, Jim_Obj *const *indexv, int indexc,
785 Jim_Obj *newObjPtr);
786 JIM_EXPORT Jim_Obj * Jim_ConcatObj (Jim_Interp *interp, int objc,
787 Jim_Obj *const *objv);
788 JIM_EXPORT Jim_Obj *Jim_ListJoin(Jim_Interp *interp,
789 Jim_Obj *listObjPtr, const char *joinStr, int joinStrLen);
791 /* dict object */
792 JIM_EXPORT Jim_Obj * Jim_NewDictObj (Jim_Interp *interp,
793 Jim_Obj *const *elements, int len);
794 JIM_EXPORT int Jim_DictKey (Jim_Interp *interp, Jim_Obj *dictPtr,
795 Jim_Obj *keyPtr, Jim_Obj **objPtrPtr, int flags);
796 JIM_EXPORT int Jim_DictKeysVector (Jim_Interp *interp,
797 Jim_Obj *dictPtr, Jim_Obj *const *keyv, int keyc,
798 Jim_Obj **objPtrPtr, int flags);
799 JIM_EXPORT int Jim_SetDictKeysVector (Jim_Interp *interp,
800 Jim_Obj *varNamePtr, Jim_Obj *const *keyv, int keyc,
801 Jim_Obj *newObjPtr, int flags);
802 JIM_EXPORT int Jim_DictPairs(Jim_Interp *interp,
803 Jim_Obj *dictPtr, Jim_Obj ***objPtrPtr, int *len);
804 JIM_EXPORT int Jim_DictAddElement(Jim_Interp *interp, Jim_Obj *objPtr,
805 Jim_Obj *keyObjPtr, Jim_Obj *valueObjPtr);
807 #define JIM_DICTMATCH_KEYS 0x0001
808 #define JIM_DICTMATCH_VALUES 0x002
810 JIM_EXPORT int Jim_DictMatchTypes(Jim_Interp *interp, Jim_Obj *objPtr, Jim_Obj *patternObj, int match_type, int return_types);
811 JIM_EXPORT int Jim_DictSize(Jim_Interp *interp, Jim_Obj *objPtr);
812 JIM_EXPORT int Jim_DictInfo(Jim_Interp *interp, Jim_Obj *objPtr);
813 JIM_EXPORT Jim_Obj *Jim_DictMerge(Jim_Interp *interp, int objc, Jim_Obj *const *objv);
815 /* return code object */
816 JIM_EXPORT int Jim_GetReturnCode (Jim_Interp *interp, Jim_Obj *objPtr,
817 int *intPtr);
819 /* expression object */
820 JIM_EXPORT int Jim_EvalExpression (Jim_Interp *interp,
821 Jim_Obj *exprObjPtr);
822 JIM_EXPORT int Jim_GetBoolFromExpr (Jim_Interp *interp,
823 Jim_Obj *exprObjPtr, int *boolPtr);
825 /* boolean object */
826 JIM_EXPORT int Jim_GetBoolean(Jim_Interp *interp, Jim_Obj *objPtr,
827 int *booleanPtr);
829 /* integer object */
830 JIM_EXPORT int Jim_GetWide (Jim_Interp *interp, Jim_Obj *objPtr,
831 jim_wide *widePtr);
832 JIM_EXPORT int Jim_GetLong (Jim_Interp *interp, Jim_Obj *objPtr,
833 long *longPtr);
834 #define Jim_NewWideObj Jim_NewIntObj
835 JIM_EXPORT Jim_Obj * Jim_NewIntObj (Jim_Interp *interp,
836 jim_wide wideValue);
838 /* double object */
839 JIM_EXPORT int Jim_GetDouble(Jim_Interp *interp, Jim_Obj *objPtr,
840 double *doublePtr);
841 JIM_EXPORT void Jim_SetDouble(Jim_Interp *interp, Jim_Obj *objPtr,
842 double doubleValue);
843 JIM_EXPORT Jim_Obj * Jim_NewDoubleObj(Jim_Interp *interp, double doubleValue);
845 /* commands utilities */
846 JIM_EXPORT void Jim_WrongNumArgs (Jim_Interp *interp, int argc,
847 Jim_Obj *const *argv, const char *msg);
848 JIM_EXPORT int Jim_GetEnum (Jim_Interp *interp, Jim_Obj *objPtr,
849 const char * const *tablePtr, int *indexPtr, const char *name, int flags);
850 JIM_EXPORT int Jim_CheckShowCommands(Jim_Interp *interp, Jim_Obj *objPtr,
851 const char *const *tablePtr);
852 JIM_EXPORT int Jim_ScriptIsComplete(Jim_Interp *interp,
853 Jim_Obj *scriptObj, char *stateCharPtr);
856 * Find a matching name in the array of the given length.
858 * NULL entries are ignored.
860 * Returns the matching index if found, or -1 if not.
862 JIM_EXPORT int Jim_FindByName(const char *name, const char * const array[], size_t len);
864 /* package utilities */
865 typedef void (Jim_InterpDeleteProc)(Jim_Interp *interp, void *data);
866 JIM_EXPORT void * Jim_GetAssocData(Jim_Interp *interp, const char *key);
867 JIM_EXPORT int Jim_SetAssocData(Jim_Interp *interp, const char *key,
868 Jim_InterpDeleteProc *delProc, void *data);
869 JIM_EXPORT int Jim_DeleteAssocData(Jim_Interp *interp, const char *key);
871 /* Packages C API */
872 /* jim-package.c */
873 JIM_EXPORT int Jim_PackageProvide (Jim_Interp *interp,
874 const char *name, const char *ver, int flags);
875 JIM_EXPORT int Jim_PackageRequire (Jim_Interp *interp,
876 const char *name, int flags);
878 /* error messages */
879 JIM_EXPORT void Jim_MakeErrorMessage (Jim_Interp *interp);
881 /* interactive mode */
882 JIM_EXPORT int Jim_InteractivePrompt (Jim_Interp *interp);
883 JIM_EXPORT void Jim_HistoryLoad(const char *filename);
884 JIM_EXPORT void Jim_HistorySave(const char *filename);
885 JIM_EXPORT char *Jim_HistoryGetline(Jim_Interp *interp, const char *prompt);
886 JIM_EXPORT void Jim_HistorySetCompletion(Jim_Interp *interp, Jim_Obj *commandObj);
887 JIM_EXPORT void Jim_HistoryAdd(const char *line);
888 JIM_EXPORT void Jim_HistoryShow(void);
890 /* Misc */
891 JIM_EXPORT int Jim_InitStaticExtensions(Jim_Interp *interp);
892 JIM_EXPORT int Jim_StringToWide(const char *str, jim_wide *widePtr, int base);
893 JIM_EXPORT int Jim_IsBigEndian(void);
896 * Returns 1 if a signal has been received while
897 * in a catch -signal {} clause.
899 #define Jim_CheckSignal(i) ((i)->signal_level && (i)->sigmask)
901 /* jim-load.c */
902 JIM_EXPORT int Jim_LoadLibrary(Jim_Interp *interp, const char *pathName);
903 JIM_EXPORT void Jim_FreeLoadHandles(Jim_Interp *interp);
905 /* jim-aio.c */
906 JIM_EXPORT FILE *Jim_AioFilehandle(Jim_Interp *interp, Jim_Obj *command);
908 /* type inspection - avoid where possible */
909 JIM_EXPORT int Jim_IsDict(Jim_Obj *objPtr);
910 JIM_EXPORT int Jim_IsList(Jim_Obj *objPtr);
912 #ifdef __cplusplus
914 #endif
916 #endif /* __JIM__H */
919 * Local Variables: ***
920 * c-basic-offset: 4 ***
921 * tab-width: 4 ***
922 * End: ***