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