Code Review / openocd.git / blob
? search:
summary | shortlog | log | commit | commitdiff | review | tree
history | raw | HEAD
sync up to latest jim tcl
[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 */
Open On-Chip Debugger

Linking to existing account procedure

If you already have an account and want to add another login method you MUST first sign in with your existing account and then change URL to read https://review.openocd.org/login/?link to get to this page again but this time it'll work for linking. Thank you.

SSH host keys fingerprints

1024 SHA256:YKx8b7u5ZWdcbp7/4AeXNaqElP49m6QrwfXaqQGJAOk gerrit-code-review@openocd.zylin.com (DSA)
384 SHA256:jHIbSQa4REvwCFG4cq5LBlBLxmxSqelQPem/EXIrxjk gerrit-code-review@openocd.org (ECDSA)
521 SHA256:UAOPYkU9Fjtcao0Ul/Rrlnj/OsQvt+pgdYSZ4jOYdgs gerrit-code-review@openocd.org (ECDSA)
256 SHA256:A13M5QlnozFOvTllybRZH6vm7iSt0XLxbA48yfc2yfY gerrit-code-review@openocd.org (ECDSA)
256 SHA256:spYMBqEYoAOtK7yZBrcwE8ZpYt6b68Cfh9yEVetvbXg gerrit-code-review@openocd.org (ED25519)
+--[ED25519 256]--+
|=..              |
|+o..   .         |
|*.o   . .        |
|+B . . .         |
|Bo. = o S        |
|Oo.+ + =         |
|oB=.* = . o      |
| =+=.+   + E     |
|. .=o   . o      |
+----[SHA256]-----+
2048 SHA256:0Onrb7/PHjpo6iVZ7xQX2riKN83FJ3KGU0TvI0TaFG4 gerrit-code-review@openocd.zylin.com (RSA)