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