/*

 * tclInt.h --

 *

 *	Declarations of things used internally by the Tcl interpreter.

 *

 * Copyright (c) 1987-1993 The Regents of the University of California.

 * Copyright (c) 1993-1997 Lucent Technologies.

 * Copyright (c) 1994-1998 Sun Microsystems, Inc.

 * Copyright (c) 1998-1999 by Scriptics Corporation.

 * Copyright (c) 2001, 2002 by Kevin B. Kenny.  All rights reserved.

 * Portions Copyright (c) 2007 Nokia Corporation and/or its subsidiaries. All rights reserved.  

 *

 * See the file "license.terms" for information on usage and redistribution

 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.

 *

 * RCS: @(#) $Id: tclInt.h,v 1.118.2.28 2007/05/10 21:32:17 dgp Exp $

 */

#ifndef _TCLINT

#define _TCLINT

/*

 * Common include files needed by most of the Tcl source files are

 * included here, so that system-dependent personalizations for the

 * include files only have to be made in once place.  This results

 * in a few extra includes, but greater modularity.  The order of

 * the three groups of #includes is important.	For example, stdio.h

 * is needed by tcl.h, and the _ANSI_ARGS_ declaration in tcl.h is

 * needed by stdlib.h in some configurations.

 */

#ifndef _TCL

#include "tcl.h"

#endif

#include <stdio.h>

#include <ctype.h>

#ifdef NO_LIMITS_H

#   include "../compat/limits.h"

#else

#   include <limits.h>

#endif

#ifdef NO_STDLIB_H

#   include "../compat/stdlib.h"

#else

#   include <stdlib.h>

#endif

#ifdef NO_STRING_H

#include "../compat/string.h"

#else

#include <string.h>

#endif

/*

 * Ensure WORDS_BIGENDIAN is defined correcly:

 * Needs to happen here in addition to configure to work with fat compiles on

 * Darwin (where configure runs only once for multiple architectures).

 */

#ifdef HAVE_SYS_TYPES_H

#    include <sys/types.h>

#endif

#ifdef HAVE_SYS_PARAM_H

#    include <sys/param.h>

#endif

#ifdef BYTE_ORDER

#    ifdef BIG_ENDIAN

#        if BYTE_ORDER == BIG_ENDIAN

#            undef WORDS_BIGENDIAN

#            define WORDS_BIGENDIAN

#        endif

#    endif

#    ifdef LITTLE_ENDIAN

#        if BYTE_ORDER == LITTLE_ENDIAN

#            undef WORDS_BIGENDIAN

#        endif

#    endif

#endif

/*

 * Used to tag functions that are only to be visible within the module being

 * built and not outside it (where this is supported by the linker).

 */

#ifndef MODULE_SCOPE

#   ifdef __cplusplus

#	define MODULE_SCOPE extern "C"

#   else

#	define MODULE_SCOPE extern

#   endif

#endif

#undef TCL_STORAGE_CLASS

#ifdef BUILD_tcl

# define TCL_STORAGE_CLASS DLLEXPORT

#else

# ifdef USE_TCL_STUBS

#  define TCL_STORAGE_CLASS

# else

#  define TCL_STORAGE_CLASS DLLIMPORT

# endif

#endif

/*

 * The following procedures allow namespaces to be customized to

 * support special name resolution rules for commands/variables.

 * 

 */

struct Tcl_ResolvedVarInfo;

typedef Tcl_Var (Tcl_ResolveRuntimeVarProc) _ANSI_ARGS_((

    Tcl_Interp* interp, struct Tcl_ResolvedVarInfo *vinfoPtr));

typedef void (Tcl_ResolveVarDeleteProc) _ANSI_ARGS_((

    struct Tcl_ResolvedVarInfo *vinfoPtr));

/*

 * The following structure encapsulates the routines needed to resolve a

 * variable reference at runtime.  Any variable specific state will typically

 * be appended to this structure.

 */

typedef struct Tcl_ResolvedVarInfo {

    Tcl_ResolveRuntimeVarProc *fetchProc;

    Tcl_ResolveVarDeleteProc *deleteProc;

} Tcl_ResolvedVarInfo;

typedef int (Tcl_ResolveCompiledVarProc) _ANSI_ARGS_((

    Tcl_Interp* interp, CONST84 char* name, int length,

    Tcl_Namespace *context, Tcl_ResolvedVarInfo **rPtr));

typedef int (Tcl_ResolveVarProc) _ANSI_ARGS_((

    Tcl_Interp* interp, CONST84 char* name, Tcl_Namespace *context,

    int flags, Tcl_Var *rPtr));

typedef int (Tcl_ResolveCmdProc) _ANSI_ARGS_((Tcl_Interp* interp,

    CONST84 char* name, Tcl_Namespace *context, int flags,

    Tcl_Command *rPtr));

typedef struct Tcl_ResolverInfo {

    Tcl_ResolveCmdProc *cmdResProc;	/* Procedure handling command name

					 * resolution. */

    Tcl_ResolveVarProc *varResProc;	/* Procedure handling variable name

					 * resolution for variables that

					 * can only be handled at runtime. */

    Tcl_ResolveCompiledVarProc *compiledVarResProc;

					/* Procedure handling variable name

					 * resolution at compile time. */

} Tcl_ResolverInfo;

/*

 *----------------------------------------------------------------

 * Data structures related to namespaces.

 *----------------------------------------------------------------

 */

/*

 * The structure below defines a namespace.

 * Note: the first five fields must match exactly the fields in a

 * Tcl_Namespace structure (see tcl.h). If you change one, be sure to

 * change the other.

 */

typedef struct Namespace {

    char *name;			 /* The namespace's simple (unqualified)

				  * name. This contains no ::'s. The name of

				  * the global namespace is "" although "::"

				  * is an synonym. */

    char *fullName;		 /* The namespace's fully qualified name.

				  * This starts with ::. */

    ClientData clientData;	 /* An arbitrary value associated with this

				  * namespace. */

    Tcl_NamespaceDeleteProc *deleteProc;

				 /* Procedure invoked when deleting the

				  * namespace to, e.g., free clientData. */

    struct Namespace *parentPtr; /* Points to the namespace that contains

				  * this one. NULL if this is the global

				  * namespace. */

    Tcl_HashTable childTable;	 /* Contains any child namespaces. Indexed

				  * by strings; values have type

				  * (Namespace *). */

    long nsId;			 /* Unique id for the namespace. */

    Tcl_Interp *interp;		 /* The interpreter containing this

				  * namespace. */

    int flags;			 /* OR-ed combination of the namespace

				  * status flags NS_DYING and NS_DEAD

				  * listed below. */

    int activationCount;	 /* Number of "activations" or active call

				  * frames for this namespace that are on

				  * the Tcl call stack. The namespace won't

				  * be freed until activationCount becomes

				  * zero. */

    int refCount;		 /* Count of references by namespaceName *

				  * objects. The namespace can't be freed

				  * until refCount becomes zero. */

    Tcl_HashTable cmdTable;	 /* Contains all the commands currently

				  * registered in the namespace. Indexed by

				  * strings; values have type (Command *).

				  * Commands imported by Tcl_Import have

				  * Command structures that point (via an

				  * ImportedCmdRef structure) to the

				  * Command structure in the source

				  * namespace's command table. */

    Tcl_HashTable varTable;	 /* Contains all the (global) variables

				  * currently in this namespace. Indexed

				  * by strings; values have type (Var *). */

    char **exportArrayPtr;	 /* Points to an array of string patterns

				  * specifying which commands are exported.

				  * A pattern may include "string match"

				  * style wildcard characters to specify

				  * multiple commands; however, no namespace

				  * qualifiers are allowed. NULL if no

				  * export patterns are registered. */

    int numExportPatterns;	 /* Number of export patterns currently

				  * registered using "namespace export". */

    int maxExportPatterns;	 /* Mumber of export patterns for which

				  * space is currently allocated. */

    int cmdRefEpoch;		 /* Incremented if a newly added command

				  * shadows a command for which this

				  * namespace has already cached a Command *

				  * pointer; this causes all its cached

				  * Command* pointers to be invalidated. */

    int resolverEpoch;		 /* Incremented whenever (a) the name resolution

				  * rules change for this namespace or (b) a 

				  * newly added command shadows a command that

				  * is compiled to bytecodes.

				  * This invalidates all byte codes compiled

				  * in the namespace, causing the code to be

				  * recompiled under the new rules.*/

    Tcl_ResolveCmdProc *cmdResProc;

				 /* If non-null, this procedure overrides

				  * the usual command resolution mechanism

				  * in Tcl.  This procedure is invoked

				  * within Tcl_FindCommand to resolve all

				  * command references within the namespace. */

    Tcl_ResolveVarProc *varResProc;

				 /* If non-null, this procedure overrides

				  * the usual variable resolution mechanism

				  * in Tcl.  This procedure is invoked

				  * within Tcl_FindNamespaceVar to resolve all

				  * variable references within the namespace

				  * at runtime. */

    Tcl_ResolveCompiledVarProc *compiledVarResProc;

				 /* If non-null, this procedure overrides

				  * the usual variable resolution mechanism

				  * in Tcl.  This procedure is invoked

				  * within LookupCompiledLocal to resolve

				  * variable references within the namespace

				  * at compile time. */

} Namespace;

/*

 * Flags used to represent the status of a namespace:

 *

 * NS_DYING -	1 means Tcl_DeleteNamespace has been called to delete the

 *		namespace but there are still active call frames on the Tcl

 *		stack that refer to the namespace. When the last call frame

 *		referring to it has been popped, it's variables and command

 *		will be destroyed and it will be marked "dead" (NS_DEAD).

 *		The namespace can no longer be looked up by name.

 * NS_DEAD -	1 means Tcl_DeleteNamespace has been called to delete the

 *		namespace and no call frames still refer to it. Its

 *		variables and command have already been destroyed. This bit

 *		allows the namespace resolution code to recognize that the

 *		namespace is "deleted". When the last namespaceName object

 *		in any byte code code unit that refers to the namespace has

 *		been freed (i.e., when the namespace's refCount is 0), the

 *		namespace's storage will be freed.

 * NS_KILLED    1 means that TclTeardownNamespace has already been called on

 *              this namespace and it should not be called again [Bug 1355942]

 */

#define NS_DYING	0x01

#define NS_DEAD		0x02

#define NS_KILLED       0x04

/*

 * Flag passed to TclGetNamespaceForQualName to have it create all namespace

 * components of a namespace-qualified name that cannot be found. The new

 * namespaces are created within their specified parent. Note that this

 * flag's value must not conflict with the values of the flags

 * TCL_GLOBAL_ONLY, TCL_NAMESPACE_ONLY, and FIND_ONLY_NS (defined in

 * tclNamesp.c).

 */

#define CREATE_NS_IF_UNKNOWN 0x800

/*

 *----------------------------------------------------------------

 * Data structures related to variables.   These are used primarily

 * in tclVar.c

 *----------------------------------------------------------------

 */

/*

 * The following structure defines a variable trace, which is used to

 * invoke a specific C procedure whenever certain operations are performed

 * on a variable.

 */

typedef struct VarTrace {

    Tcl_VarTraceProc *traceProc;/* Procedure to call when operations given

				 * by flags are performed on variable. */

    ClientData clientData;	/* Argument to pass to proc. */

    int flags;			/* What events the trace procedure is

				 * interested in:  OR-ed combination of

				 * TCL_TRACE_READS, TCL_TRACE_WRITES,

				 * TCL_TRACE_UNSETS and TCL_TRACE_ARRAY. */

    struct VarTrace *nextPtr;	/* Next in list of traces associated with

				 * a particular variable. */

} VarTrace;

/*

 * The following structure defines a command trace, which is used to

 * invoke a specific C procedure whenever certain operations are performed

 * on a command.

 */

typedef struct CommandTrace {

    Tcl_CommandTraceProc *traceProc;/* Procedure to call when operations given

				     * by flags are performed on command. */

    ClientData clientData;	    /* Argument to pass to proc. */

    int flags;			    /* What events the trace procedure is

				     * interested in:  OR-ed combination of

				     * TCL_TRACE_RENAME, TCL_TRACE_DELETE. */

    struct CommandTrace *nextPtr;   /* Next in list of traces associated with

				     * a particular command. */

    int refCount;                   /* Used to ensure this structure is

                                     * not deleted too early.  Keeps track

                                     * of how many pieces of code have

                                     * a pointer to this structure. */

} CommandTrace;

/*

 * When a command trace is active (i.e. its associated procedure is

 * executing), one of the following structures is linked into a list

 * associated with the command's interpreter.  The information in

 * the structure is needed in order for Tcl to behave reasonably

 * if traces are deleted while traces are active.

 */

typedef struct ActiveCommandTrace {

    struct Command *cmdPtr;	/* Command that's being traced. */

    struct ActiveCommandTrace *nextPtr;

				/* Next in list of all active command

				 * traces for the interpreter, or NULL

				 * if no more. */

    CommandTrace *nextTracePtr;	/* Next trace to check after current

				 * trace procedure returns;  if this

				 * trace gets deleted, must update pointer

				 * to avoid using free'd memory. */

    int reverseScan;		/* Boolean set true when the traces

				 * are scanning in reverse order. */

} ActiveCommandTrace;

/*

 * When a variable trace is active (i.e. its associated procedure is

 * executing), one of the following structures is linked into a list

 * associated with the variable's interpreter.	The information in

 * the structure is needed in order for Tcl to behave reasonably

 * if traces are deleted while traces are active.

 */

typedef struct ActiveVarTrace {

    struct Var *varPtr;		/* Variable that's being traced. */

    struct ActiveVarTrace *nextPtr;

				/* Next in list of all active variable

				 * traces for the interpreter, or NULL

				 * if no more. */

    VarTrace *nextTracePtr;	/* Next trace to check after current

				 * trace procedure returns;  if this

				 * trace gets deleted, must update pointer

				 * to avoid using free'd memory. */

} ActiveVarTrace;

/*

 * The following structure describes an enumerative search in progress on

 * an array variable;  this are invoked with options to the "array"

 * command.

 */

typedef struct ArraySearch {

    int id;			/* Integer id used to distinguish among

				 * multiple concurrent searches for the

				 * same array. */

    struct Var *varPtr;		/* Pointer to array variable that's being

				 * searched. */

    Tcl_HashSearch search;	/* Info kept by the hash module about

				 * progress through the array. */

    Tcl_HashEntry *nextEntry;	/* Non-null means this is the next element

				 * to be enumerated (it's leftover from

				 * the Tcl_FirstHashEntry call or from

				 * an "array anymore" command).	 NULL

				 * means must call Tcl_NextHashEntry

				 * to get value to return. */

    struct ArraySearch *nextPtr;/* Next in list of all active searches

				 * for this variable, or NULL if this is

				 * the last one. */

} ArraySearch;

/*

 * The structure below defines a variable, which associates a string name

 * with a Tcl_Obj value. These structures are kept in procedure call frames

 * (for local variables recognized by the compiler) or in the heap (for

 * global variables and any variable not known to the compiler). For each

 * Var structure in the heap, a hash table entry holds the variable name and

 * a pointer to the Var structure.

 */

typedef struct Var {

    union {

	Tcl_Obj *objPtr;	/* The variable's object value. Used for 

				 * scalar variables and array elements. */

	Tcl_HashTable *tablePtr;/* For array variables, this points to

				 * information about the hash table used

				 * to implement the associative array. 

				 * Points to malloc-ed data. */

	struct Var *linkPtr;	/* If this is a global variable being

				 * referred to in a procedure, or a variable

				 * created by "upvar", this field points to

				 * the referenced variable's Var struct. */

    } value;

    char *name;			/* NULL if the variable is in a hashtable,

				 * otherwise points to the variable's

				 * name. It is used, e.g., by TclLookupVar

				 * and "info locals". The storage for the

				 * characters of the name is not owned by

				 * the Var and must not be freed when

				 * freeing the Var. */

    Namespace *nsPtr;		/* Points to the namespace that contains

				 * this variable or NULL if the variable is

				 * a local variable in a Tcl procedure. */

    Tcl_HashEntry *hPtr;	/* If variable is in a hashtable, either the

				 * hash table entry that refers to this

				 * variable or NULL if the variable has been

				 * detached from its hash table (e.g. an

				 * array is deleted, but some of its

				 * elements are still referred to in

				 * upvars). NULL if the variable is not in a

				 * hashtable. This is used to delete an

				 * variable from its hashtable if it is no

				 * longer needed. */

    int refCount;		/* Counts number of active uses of this

				 * variable, not including its entry in the

				 * call frame or the hash table: 1 for each

				 * additional variable whose linkPtr points

				 * here, 1 for each nested trace active on

				 * variable, and 1 if the variable is a 

				 * namespace variable. This record can't be

				 * deleted until refCount becomes 0. */

    VarTrace *tracePtr;		/* First in list of all traces set for this

				 * variable. */

    ArraySearch *searchPtr;	/* First in list of all searches active

				 * for this variable, or NULL if none. */

    int flags;			/* Miscellaneous bits of information about

				 * variable. See below for definitions. */

} Var;

/*

 * Flag bits for variables. The first three (VAR_SCALAR, VAR_ARRAY, and

 * VAR_LINK) are mutually exclusive and give the "type" of the variable.

 * VAR_UNDEFINED is independent of the variable's type. 

 *

 * VAR_SCALAR -			1 means this is a scalar variable and not

 *				an array or link. The "objPtr" field points

 *				to the variable's value, a Tcl object.

 * VAR_ARRAY -			1 means this is an array variable rather

 *				than a scalar variable or link. The

 *				"tablePtr" field points to the array's

 *				hashtable for its elements.

 * VAR_LINK -			1 means this Var structure contains a

 *				pointer to another Var structure that

 *				either has the real value or is itself

 *				another VAR_LINK pointer. Variables like

 *				this come about through "upvar" and "global"

 *				commands, or through references to variables

 *				in enclosing namespaces.

 * VAR_UNDEFINED -		1 means that the variable is in the process

 *				of being deleted. An undefined variable

 *				logically does not exist and survives only

 *				while it has a trace, or if it is a global

 *				variable currently being used by some

 *				procedure.

 * VAR_IN_HASHTABLE -		1 means this variable is in a hashtable and

 *				the Var structure is malloced. 0 if it is

 *				a local variable that was assigned a slot

 *				in a procedure frame by	the compiler so the

 *				Var storage is part of the call frame.

 * VAR_TRACE_ACTIVE -		1 means that trace processing is currently

 *				underway for a read or write access, so

 *				new read or write accesses should not cause

 *				trace procedures to be called and the

 *				variable can't be deleted.

 * VAR_ARRAY_ELEMENT -		1 means that this variable is an array

 *				element, so it is not legal for it to be

 *				an array itself (the VAR_ARRAY flag had

 *				better not be set).

 * VAR_NAMESPACE_VAR -		1 means that this variable was declared

 *				as a namespace variable. This flag ensures

 *				it persists until its namespace is

 *				destroyed or until the variable is unset;

 *				it will persist even if it has not been

 *				initialized and is marked undefined.

 *				The variable's refCount is incremented to

 *				reflect the "reference" from its namespace.

 *

 * The following additional flags are used with the CompiledLocal type

 * defined below:

 *

 * VAR_ARGUMENT -		1 means that this variable holds a procedure

 *				argument. 

 * VAR_TEMPORARY -		1 if the local variable is an anonymous

 *				temporary variable. Temporaries have a NULL

 *				name.

 * VAR_RESOLVED -		1 if name resolution has been done for this

 *				variable.

 */

#define VAR_SCALAR		0x1

#define VAR_ARRAY		0x2

#define VAR_LINK		0x4

#define VAR_UNDEFINED		0x8

#define VAR_IN_HASHTABLE	0x10

#define VAR_TRACE_ACTIVE	0x20

#define VAR_ARRAY_ELEMENT	0x40

#define VAR_NAMESPACE_VAR	0x80

#define VAR_ARGUMENT		0x100

#define VAR_TEMPORARY		0x200

#define VAR_RESOLVED		0x400	

/*

 * Macros to ensure that various flag bits are set properly for variables.

 * The ANSI C "prototypes" for these macros are:

 *

 * EXTERN void	TclSetVarScalar _ANSI_ARGS_((Var *varPtr));

 * EXTERN void	TclSetVarArray _ANSI_ARGS_((Var *varPtr));

 * EXTERN void	TclSetVarLink _ANSI_ARGS_((Var *varPtr));

 * EXTERN void	TclSetVarArrayElement _ANSI_ARGS_((Var *varPtr));

 * EXTERN void	TclSetVarUndefined _ANSI_ARGS_((Var *varPtr));

 * EXTERN void	TclClearVarUndefined _ANSI_ARGS_((Var *varPtr));

 */

#define TclSetVarScalar(varPtr) \

    (varPtr)->flags = ((varPtr)->flags & ~(VAR_ARRAY|VAR_LINK)) | VAR_SCALAR

#define TclSetVarArray(varPtr) \

    (varPtr)->flags = ((varPtr)->flags & ~(VAR_SCALAR|VAR_LINK)) | VAR_ARRAY

#define TclSetVarLink(varPtr) \

    (varPtr)->flags = ((varPtr)->flags & ~(VAR_SCALAR|VAR_ARRAY)) | VAR_LINK

#define TclSetVarArrayElement(varPtr) \

    (varPtr)->flags = ((varPtr)->flags & ~VAR_ARRAY) | VAR_ARRAY_ELEMENT

#define TclSetVarUndefined(varPtr) \

    (varPtr)->flags |= VAR_UNDEFINED

#define TclClearVarUndefined(varPtr) \

    (varPtr)->flags &= ~VAR_UNDEFINED

/*

 * Macros to read various flag bits of variables.

 * The ANSI C "prototypes" for these macros are:

 *

 * EXTERN int	TclIsVarScalar _ANSI_ARGS_((Var *varPtr));

 * EXTERN int	TclIsVarLink _ANSI_ARGS_((Var *varPtr));

 * EXTERN int	TclIsVarArray _ANSI_ARGS_((Var *varPtr));

 * EXTERN int	TclIsVarUndefined _ANSI_ARGS_((Var *varPtr));

 * EXTERN int	TclIsVarArrayElement _ANSI_ARGS_((Var *varPtr));

 * EXTERN int	TclIsVarTemporary _ANSI_ARGS_((Var *varPtr));

 * EXTERN int	TclIsVarArgument _ANSI_ARGS_((Var *varPtr));

 * EXTERN int	TclIsVarResolved _ANSI_ARGS_((Var *varPtr));

 */

#define TclIsVarScalar(varPtr) \

    ((varPtr)->flags & VAR_SCALAR)

#define TclIsVarLink(varPtr) \

    ((varPtr)->flags & VAR_LINK)

#define TclIsVarArray(varPtr) \

    ((varPtr)->flags & VAR_ARRAY)

#define TclIsVarUndefined(varPtr) \

    ((varPtr)->flags & VAR_UNDEFINED)

#define TclIsVarArrayElement(varPtr) \

    ((varPtr)->flags & VAR_ARRAY_ELEMENT)

#define TclIsVarTemporary(varPtr) \

    ((varPtr)->flags & VAR_TEMPORARY)

#define TclIsVarArgument(varPtr) \

    ((varPtr)->flags & VAR_ARGUMENT)

#define TclIsVarResolved(varPtr) \

    ((varPtr)->flags & VAR_RESOLVED)

/*

 *----------------------------------------------------------------

 * Data structures related to procedures.  These are used primarily

 * in tclProc.c, tclCompile.c, and tclExecute.c.

 *----------------------------------------------------------------

 */

/*

 * Forward declaration to prevent an error when the forward reference to

 * Command is encountered in the Proc and ImportRef types declared below.

 */

struct Command;

/*

 * The variable-length structure below describes a local variable of a

 * procedure that was recognized by the compiler. These variables have a

 * name, an element in the array of compiler-assigned local variables in the

 * procedure's call frame, and various other items of information. If the

 * local variable is a formal argument, it may also have a default value.

 * The compiler can't recognize local variables whose names are

 * expressions (these names are only known at runtime when the expressions

 * are evaluated) or local variables that are created as a result of an

 * "upvar" or "uplevel" command. These other local variables are kept

 * separately in a hash table in the call frame.

 */

typedef struct CompiledLocal {

    struct CompiledLocal *nextPtr;

				/* Next compiler-recognized local variable

				 * for this procedure, or NULL if this is

				 * the last local. */

    int nameLength;		/* The number of characters in local

				 * variable's name. Used to speed up

				 * variable lookups. */

    int frameIndex;		/* Index in the array of compiler-assigned

				 * variables in the procedure call frame. */

    int flags;			/* Flag bits for the local variable. Same as

				 * the flags for the Var structure above,

				 * although only VAR_SCALAR, VAR_ARRAY, 

				 * VAR_LINK, VAR_ARGUMENT, VAR_TEMPORARY, and

				 * VAR_RESOLVED make sense. */

    Tcl_Obj *defValuePtr;	/* Pointer to the default value of an

				 * argument, if any. NULL if not an argument

				 * or, if an argument, no default value. */

    Tcl_ResolvedVarInfo *resolveInfo;

				/* Customized variable resolution info

				 * supplied by the Tcl_ResolveCompiledVarProc

				 * associated with a namespace. Each variable

				 * is marked by a unique ClientData tag

				 * during compilation, and that same tag

				 * is used to find the variable at runtime. */

    char name[4];		/* Name of the local variable starts here.

				 * If the name is NULL, this will just be

				 * '\0'. The actual size of this field will

				 * be large enough to hold the name. MUST

				 * BE THE LAST FIELD IN THE STRUCTURE! */

} CompiledLocal;

/*

 * The structure below defines a command procedure, which consists of a

 * collection of Tcl commands plus information about arguments and other

 * local variables recognized at compile time.

 */

typedef struct Proc {

    struct Interp *iPtr;	  /* Interpreter for which this command

				   * is defined. */

    int refCount;		  /* Reference count: 1 if still present

				   * in command table plus 1 for each call

				   * to the procedure that is currently

				   * active. This structure can be freed

				   * when refCount becomes zero. */

    struct Command *cmdPtr;	  /* Points to the Command structure for

				   * this procedure. This is used to get

				   * the namespace in which to execute

				   * the procedure. */

    Tcl_Obj *bodyPtr;		  /* Points to the ByteCode object for

				   * procedure's body command. */

    int numArgs;		  /* Number of formal parameters. */

    int numCompiledLocals;	  /* Count of local variables recognized by

				   * the compiler including arguments and

				   * temporaries. */

    CompiledLocal *firstLocalPtr; /* Pointer to first of the procedure's

				   * compiler-allocated local variables, or

				   * NULL if none. The first numArgs entries

				   * in this list describe the procedure's

				   * formal arguments. */

    CompiledLocal *lastLocalPtr;  /* Pointer to the last allocated local

				   * variable or NULL if none. This has

				   * frame index (numCompiledLocals-1). */

} Proc;

/*

 * The structure below defines a command trace.	 This is used to allow Tcl

 * clients to find out whenever a command is about to be executed.

 */

typedef struct Trace {

    int level;			/* Only trace commands at nesting level

				 * less than or equal to this. */

    Tcl_CmdObjTraceProc *proc;	/* Procedure to call to trace command. */

    ClientData clientData;	/* Arbitrary value to pass to proc. */

    struct Trace *nextPtr;	/* Next in list of traces for this interp. */

    int flags;			/* Flags governing the trace - see

				 * Tcl_CreateObjTrace for details */

    Tcl_CmdObjTraceDeleteProc* delProc;

				/* Procedure to call when trace is deleted */

} Trace;

/*

 * When an interpreter trace is active (i.e. its associated procedure

 * is executing), one of the following structures is linked into a list

 * associated with the interpreter.  The information in the structure

 * is needed in order for Tcl to behave reasonably if traces are

 * deleted while traces are active.

 */

typedef struct ActiveInterpTrace {

    struct ActiveInterpTrace *nextPtr;

				/* Next in list of all active command

				 * traces for the interpreter, or NULL

				 * if no more. */

    Trace *nextTracePtr;	/* Next trace to check after current

				 * trace procedure returns;  if this

				 * trace gets deleted, must update pointer

				 * to avoid using free'd memory. */

    int reverseScan;		/* Boolean set true when the traces

				 * are scanning in reverse order. */

} ActiveInterpTrace;

/*

 * The structure below defines an entry in the assocData hash table which

 * is associated with an interpreter. The entry contains a pointer to a

 * function to call when the interpreter is deleted, and a pointer to

 * a user-defined piece of data.

 */

typedef struct AssocData {

    Tcl_InterpDeleteProc *proc;	/* Proc to call when deleting. */

    ClientData clientData;	/* Value to pass to proc. */

} AssocData;	

/*

 * The structure below defines a call frame. A call frame defines a naming

 * context for a procedure call: its local naming scope (for local

 * variables) and its global naming scope (a namespace, perhaps the global

 * :: namespace). A call frame can also define the naming context for a

 * namespace eval or namespace inscope command: the namespace in which the

 * command's code should execute. The Tcl_CallFrame structures exist only

 * while procedures or namespace eval/inscope's are being executed, and

 * provide a kind of Tcl call stack.

 * 

 * WARNING!! The structure definition must be kept consistent with the

 * Tcl_CallFrame structure in tcl.h. If you change one, change the other.

 */

typedef struct CallFrame {

    Namespace *nsPtr;		/* Points to the namespace used to resolve

				 * commands and global variables. */

    int isProcCallFrame;	/* If nonzero, the frame was pushed to

				 * execute a Tcl procedure and may have

				 * local vars. If 0, the frame was pushed

				 * to execute a namespace command and var

				 * references are treated as references to

				 * namespace vars; varTablePtr and

				 * compiledLocals are ignored. */

    int objc;			/* This and objv below describe the

				 * arguments for this procedure call. */

    Tcl_Obj *CONST *objv;	/* Array of argument objects. */

    struct CallFrame *callerPtr;

				/* Value of interp->framePtr when this

				 * procedure was invoked (i.e. next higher

				 * in stack of all active procedures). */

    struct CallFrame *callerVarPtr;

				/* Value of interp->varFramePtr when this

				 * procedure was invoked (i.e. determines

				 * variable scoping within caller). Same

				 * as callerPtr unless an "uplevel" command

				 * or something equivalent was active in

				 * the caller). */

    int level;			/* Level of this procedure, for "uplevel"

				 * purposes (i.e. corresponds to nesting of

				 * callerVarPtr's, not callerPtr's). 1 for

				 * outermost procedure, 0 for top-level. */

    Proc *procPtr;		/* Points to the structure defining the

				 * called procedure. Used to get information

				 * such as the number of compiled local

				 * variables (local variables assigned

				 * entries ["slots"] in the compiledLocals

				 * array below). */

    Tcl_HashTable *varTablePtr;	/* Hash table containing local variables not

				 * recognized by the compiler, or created at

				 * execution time through, e.g., upvar.

				 * Initially NULL and created if needed. */

    int numCompiledLocals;	/* Count of local variables recognized by

				 * the compiler including arguments. */

    Var* compiledLocals;	/* Points to the array of local variables

				 * recognized by the compiler. The compiler

				 * emits code that refers to these variables

				 * using an index into this array. */

} CallFrame;

#ifdef TCL_TIP280

/*

 * TIP #280

 * The structure below defines a command frame. A command frame

 * provides location information for all commands executing a tcl

 * script (source, eval, uplevel, procedure bodies, ...). The runtime

 * structure essentially contains the stack trace as it would be if

 * the currently executing command were to throw an error.

 *

 * For commands where it makes sense it refers to the associated

 * CallFrame as well.

 *

 * The structures are chained in a single list, with the top of the

 * stack anchored in the Interp structure.

 *

 * Instances can be allocated on the C stack, or the heap, the former

 * making cleanup a bit simpler.

 */

typedef struct CmdFrame {

  /* General data. Always available. */

  int              type;     /* Values see below */

  int              level;    /* #Frames in stack, prevent O(n) scan of list */

  int*             line;     /* Lines the words of the command start on */

  int              nline;

  CallFrame*       framePtr; /* Procedure activation record, may be NULL */

  struct CmdFrame* nextPtr;  /* Link to calling frame */

  /* Data needed for Eval vs TEBC

   *

   * EXECUTION CONTEXTS and usage of CmdFrame

   *

   * Field      TEBC            EvalEx          EvalObjEx

   * =======    ====            ======          =========

   * level      yes             yes             yes

   * type       BC/PREBC        SRC/EVAL        EVAL_LIST

   * line0      yes             yes             yes

   * framePtr   yes             yes             yes

   * =======    ====            ======          =========

   *

   * =======    ====            ======          ========= union data

   * line1      -               yes             -

   * line3      -               yes             -

   * path       -               yes             -

   * -------    ----            ------          ---------

   * codePtr    yes             -               -

   * pc         yes             -               -

   * =======    ====            ======          =========

   *

   * =======    ====            ======          ========= | union cmd

   * listPtr    -               -               yes       |

   * -------    ----            ------          --------- |

   * cmd        yes             yes             -         |

   * cmdlen     yes             yes             -         |

   * -------    ----            ------          --------- |

   */

  union {

    struct {

      Tcl_Obj*     path;     /* Path of the sourced file the command

			      * is in. */

    } eval;

    struct {

      CONST void*  codePtr;  /* Byte code currently executed */

      CONST char*  pc;       /* and instruction pointer.     */

    } tebc;

  } data;

  union {

    struct {

      CONST char*  cmd;      /* The executed command, if possible */

      int          len;      /* And its length */

    } str;

    Tcl_Obj*       listPtr;  /* Tcl_EvalObjEx, cmd list */

  } cmd;

} CmdFrame;

/* The following macros define the allowed values for the type field

 * of the CmdFrame structure above. Some of the values occur only in

 * the extended location data referenced via the 'baseLocPtr'.

 *

 * TCL_LOCATION_EVAL      : Frame is for a script evaluated by EvalEx.

 * TCL_LOCATION_EVAL_LIST : Frame is for a script evaluated by the list

 *                          optimization path of EvalObjEx.

 * TCL_LOCATION_BC        : Frame is for bytecode. 

 * TCL_LOCATION_PREBC     : Frame is for precompiled bytecode.

 * TCL_LOCATION_SOURCE    : Frame is for a script evaluated by EvalEx,

 *                          from a sourced file.

 * TCL_LOCATION_PROC      : Frame is for bytecode of a procedure.

 *

 * A TCL_LOCATION_BC type in a frame can be overridden by _SOURCE and

 * _PROC types, per the context of the byte code in execution.

 */

#define TCL_LOCATION_EVAL      (0) /* Location in a dynamic eval script */

#define TCL_LOCATION_EVAL_LIST (1) /* Location in a dynamic eval script, list-path */

#define TCL_LOCATION_BC        (2) /* Location in byte code */

#define TCL_LOCATION_PREBC     (3) /* Location in precompiled byte code, no location */

#define TCL_LOCATION_SOURCE    (4) /* Location in a file */

#define TCL_LOCATION_PROC      (5) /* Location in a dynamic proc */

#define TCL_LOCATION_LAST      (6) /* Number of values in the enum */

#endif

/*

 *----------------------------------------------------------------

 * Data structures and procedures related to TclHandles, which

 * are a very lightweight method of preserving enough information

 * to determine if an arbitrary malloc'd block has been deleted.

 *----------------------------------------------------------------

 */

typedef VOID **TclHandle;

/*

 *----------------------------------------------------------------

 * Data structures related to expressions.  These are used only in

 * tclExpr.c.

 *----------------------------------------------------------------

 */

/*

 * The data structure below defines a math function (e.g. sin or hypot)

 * for use in Tcl expressions.

 */

#define MAX_MATH_ARGS 5

typedef struct MathFunc {

    int builtinFuncIndex;	/* If this is a builtin math function, its

				 * index in the array of builtin functions.

				 * (tclCompilation.h lists these indices.)

				 * The value is -1 if this is a new function

				 * defined by Tcl_CreateMathFunc. The value

				 * is also -1 if a builtin function is

				 * replaced by a Tcl_CreateMathFunc call. */

    int numArgs;		/* Number of arguments for function. */

    Tcl_ValueType argTypes[MAX_MATH_ARGS];

				/* Acceptable types for each argument. */

    Tcl_MathProc *proc;		/* Procedure that implements this function.

				 * NULL if isBuiltinFunc is 1. */

    ClientData clientData;	/* Additional argument to pass to the

				 * function when invoking it. NULL if

				 * isBuiltinFunc is 1. */

} MathFunc;

/*

 * These are a thin layer over TclpThreadKeyDataGet and TclpThreadKeyDataSet

 * when threads are used, or an emulation if there are no threads.  These

 * are really internal and Tcl clients should use Tcl_GetThreadData.

 */

EXTERN VOID *TclThreadDataKeyGet _ANSI_ARGS_((Tcl_ThreadDataKey *keyPtr));

EXTERN void TclThreadDataKeySet _ANSI_ARGS_((Tcl_ThreadDataKey *keyPtr, VOID *data));

/*

 * This is a convenience macro used to initialize a thread local storage ptr.

 */

#define TCL_TSD_INIT(keyPtr)	(ThreadSpecificData *)Tcl_GetThreadData((keyPtr), sizeof(ThreadSpecificData))

/*

 *----------------------------------------------------------------

 * Data structures related to bytecode compilation and execution.

 * These are used primarily in tclCompile.c, tclExecute.c, and

 * tclBasic.c.

 *----------------------------------------------------------------

 */

/*

 * Forward declaration to prevent errors when the forward references to

 * Tcl_Parse and CompileEnv are encountered in the procedure type

 * CompileProc declared below.

 */

struct CompileEnv;

/*

 * The type of procedures called by the Tcl bytecode compiler to compile

 * commands. Pointers to these procedures are kept in the Command structure

 * describing each command. When a CompileProc returns, the interpreter's

 * result is set to error information, if any. In addition, the CompileProc

 * returns an integer value, which is one of the following:

 *

 * TCL_OK		Compilation completed normally.