Subversion Repositories or1k

'\"

'\" Copyright (c) 1998 Lucent Technologies, Inc.

'\"

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

'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.

'\"

'\" SCCS: %W%

'\"

.so man.macros

.TH Tcl_AddInterpResolvers 3 8.0 Tcl "Tcl Library Procedures"

.BS

.SH NAME

Tcl_AddInterpResolvers, Tcl_GetInterpResolvers, Tcl_RemoveInterpResolvers, Tcl_SetNamespaceResolvers, Tcl_GetNamespaceResolvers \- change the name resolution rules for commands/variables

.SH SYNOPSIS

.nf

\fB#include \fR

.sp

void

\fBTcl_AddInterpResolvers\fR(\fIinterp, name, cmdProc, varProc, compiledVarProc\fR)

.sp

int

\fBTcl_GetInterpResolvers\fR(\fIinterp, name, resInfoPtr\fR)

.sp

int

\fBTcl_RemoveInterpResolvers\fR(\fIinterp, name\fR)

.sp

void

\fBTcl_SetNamespaceResolvers\fR(\fInamespacePtr, cmdProc, varProc, compiledVarProc\fR)

.sp

int

\fBTcl_GetNamespaceResolvers\fR(\fInamespacePtr, resInfoPtr\fR)

.SH ARGUMENTS

.AS Tcl_ResolveCompiledVarProc *compiledVarProc

.AP Tcl_Interp *interp  in

Interpreter whose name resolution rules are being queried or modified.

.AP char *name in

Name for a group of name resolution procedures.

.AP Tcl_ResolveCmdProc *cmdProc in

Procedure which will be used to resolve command names.

.AP Tcl_ResolveVarProc *varProc in

Procedure which will be used to resolve variable names at run time.

.AP Tcl_ResolveCompiledVarProc *compiledVarProc in

Procedure which will be used to resolve variable names at compile time.

.AP Tcl_ResolverInfo *resInfoPtr out

Returns the resolution procedures that are currently in effect for

a particular namespace or for a particular name resolution scheme

in the interpreter.

.AP Tcl_Namespace *namespacePtr in

Namespace whose name resolution rules are being queried or modified.

.BE

.SH DESCRIPTION

.PP

These procedures make it possible to change the way that Tcl

resolves command/variable names.  The name resolution rules are

changed by supplying three procedures:  \fIcmdProc\fR, \fIvarProc\fR, and

\fIcompiledVarProc\fR.  See the section \fBHOW NAME RESOLUTION PROCEDURES

WORK\fR for details about these procedures.

.PP

The name resolution rules can be changed for a particular namespace,

for an entire interpreter, or both.  When a name needs to be resolved,

Tcl handles it as follows.  The name resolution scheme for the

current namespace is consulted first.  Each of the name resolution

schemes for the interpreter are consulted next.  Finally, Tcl uses

the default rules for name resolution as described for the

\fBnamespace\fR command.

.PP

\fBTcl_AddInterpResolver\fR adds a set of name resolution procedures

to an interpreter.  The procedures are identified by a string \fIname\fR,

so they can be queried or deleted later on.  All of the name resolution

schemes for the interpreter are kept on a list, and they are consulted

in order from most- to least-recently added.  For example, suppose one

extension adds a name resolution scheme called "fred", and another

extension adds another scheme called "barney".  When a name is resolved,

the "barney" scheme will be consulted first, followed by the "fred"

scheme, if necessary.

.PP

\fBTcl_GetInterpResolver\fR looks for a particular name resolution

scheme in an interpreter.  If the \fIname\fR is recognized, this

procedure returns a non-zero value along with pointers to the

name resolution procedures in the \fIresInfoPtr\fR structure.  Otherwise,

the procedure returns 0.

.PP

\fBTcl_RemoveInterpResolver\fR looks for a particular name resolution

scheme in an interpreter.  If the \fIname\fR is recognized, this

procedure deletes the scheme and returns a non-zero value.  Otherwise,

it returns 0.

.PP

\fBTcl_SetNamespaceResolver\fR sets the name resolution procedures

for a particular namespace.  Unlike an interpreter, a namespace can

have only one name resolution scheme in effect at any given time.

.PP

\fBTcl_GetNamespaceResolver\fR returns the name resolution procedures

for a particular namespace.  If the namespace has a special name

resolution scheme, this procedure returns a non-zero value along

with pointers to the name resolution procedures in the \fIresInfoPtr\fR

structure.  Otherwise, the procedure returns 0.

.SH "HOW NAME RESOLUTION PROCEDURES WORK"

A name resolution scheme is enforced by three name resolution procedures.

The \fIcmdProc\fR procedure is used to resolve command names.  It must

conform to the following type:

.CS

typedef int Tcl_ResolveCmdProc(Tcl_Interp* \fIinterp\fR,

        char* \fIname\fR, Tcl_Namespace* \fIcontext\fR, int \fIflags\fR,

        Tcl_Command* \fIrPtr\fR);

.CE

The \fIinterp\fR argument is the interpreter performing the resolution;

\fIname\fR is the command name being resolved; \fIcontext\fR is the

namespace context containing the command reference; and \fIflags\fR

may contain TCL_LEAVE_ERR_MSG.

.PP

If this procedure recognizes the command \fIname\fR, it should

store the Tcl_Command token for that command in the \fIrPtr\fR

argument and return TCL_OK.  If this procedure doesn't recognize

the command \fIname\fR, it should return TCL_CONTINUE, and the

name resolution will continue with another procedure or with the

default Tcl resolution scheme.  If this procedure recognizes

the command \fIname\fR, but for some reason the command is

invalid, the procedure should return TCL_ERROR.  If the \fIflags\fR

argument contains TCL_LEAVE_ERR_MSG, the procedure should leave

an error message in the interpreter, explaining why the command

is invalid.

.PP

The \fIvarProc\fR procedure is similar to \fIcmdProc\fR, but it is

used to resolve variable names encountered at run time.  It must

conform to the following type:

.CS

typedef int Tcl_ResolveVarProc(Tcl_Interp* \fIinterp\fR,

        char* \fIname\fR, Tcl_Namespace* \fIcontext\fR, int \fIflags\fR,

        Tcl_Var* \fIrPtr\fR);

.CE

The \fIinterp\fR argument is the interpreter performing the resolution;

\fIname\fR is the variable name being resolved; \fIcontext\fR is the

namespace context containing the variable reference; and \fIflags\fR

may contain TCL_GLOBAL_ONLY, TCL_NAMESPACE_ONLY, or TCL_LEAVE_ERR_MSG.

.PP

If this procedure recognizes the variable \fIname\fR, it should

store the Tcl_Var token for that variable in the \fIrPtr\fR

argument and return TCL_OK.  If this procedure doesn't recognize

the variable \fIname\fR, it should return TCL_CONTINUE, and the

name resolution will continue with another procedure or with the

default Tcl resolution scheme.  If this procedure recognizes

the variable \fIname\fR, but for some reason the variable is

not accessible, the procedure should return TCL_ERROR.  If the

\fIflags\fR argument contains TCL_LEAVE_ERR_MSG, the procedure

should leave an error message in the interpreter, explaining why

the variable reference is invalid.

.PP

Note that this procedure should look for the TCL_GLOBAL_ONLY and

TCL_NAMESPACE_ONLY flags.  It should handle them appropriately, or

return TCL_CONTINUE and let Tcl handle the reference.  But it should

not ignore the flags.

.PP

Tcl also resolves variables when a body of code is compiled; the

\fIcompiledVarProc\fR procedure handles that case.  It must

conform to the following type:

.CS

typedef int Tcl_ResolveCompiledVarProc(Tcl_Interp* \fIinterp\fR,

        char* \fIname\fR, int \fIlength\fR, Tcl_Namespace* \fIcontext\fR,

        Tcl_ResolvedVarInfo* \fIrPtr\fR);

.CE

The \fIinterp\fR argument is the interpreter performing the resolution;

\fIname\fR is the variable name being resolved; \fIlength\fR is the

number of bytes in \fIname\fR, which is not a null-terminated

string; and \fIcontext\fR is the namespace context containing the

variable reference.

.PP

If this procedure recognizes the variable \fIname\fR, it should

return some information characterizing the variable in the

\fIrPtr\fR structure.  This structure is defined as follows:

.CS

typedef struct Tcl_ResolvedVarInfo {

    ClientData \fIidentity\fR;

    Tcl_ResolveRuntimeVarProc *\fIfetchProc\fR;

    Tcl_ResolveVarDeleteProc *\fIdeleteProc\fR;

} Tcl_ResolvedVarInfo;

.CE

The \fIidentity\fR field is an arbitrary value that characterizes

the variable.  Each variable should have a unique identity.  Each

time the compiled code is executed, Tcl will call the \fIfetchProc\fR

procedure to get the actual variable for a particular \fIidentity\fR

value.  This callback procedure must conform to the following type:

.CS

typedef Tcl_Var Tcl_ResolveRuntimeVarProc(Tcl_Interp* \fIinterp\fR,

    ClientData \fIidentity\fR);

.CE

The \fIfetchProc\fR procedure takes the \fIinterp\fR interpreter

and the \fIidentity\fR from compile time and returns a Tcl_Var

token representing the variable.  If for some reason the variable

can't be found, this procedure should return NULL, and Tcl will

create a local variable within the call frame of the procedure

being executed.

.PP

When the compiled code is discarded, Tcl calls the \fIdeleteProc\fR

procedure to release the \fIidentity\fR data.  The delete procedure

must conform to the following type:

.CS

typedef void Tcl_ResolveVarDeleteProc(ClientData \fIidentity\fR);

.CE

.PP

In general, the \fIvarProc\fR and \fIcompiledVarProc\fR procedures

should \fIboth\fR be defined.  If the \fIcompiledVarProc\fR is not

defined, then Tcl will create local variables for any variable

names that are not recognized within a procedure.  If the \fIvarProc\fR

is not defined, then Tcl will not recognize variables that are

encountered at runtime.  For example, consider the following procedure:

.CS

proc foo {args} {

    set anotherRef "1"

    set name "another"

    set ${name}Ref "2"

}

.CE

Suppose that the \fIcompiledVarProc\fR resolves the name

\fBanotherRef\fR at compile time.  The name \fB${name}Ref\fR

can't be resolved at compile time, so the resolution of that

name is deferred to run time.  If the \fIvarProc\fR procedure

must intercept the name \fBanotherRef\fR at run time and

supply the appropriate variable.

.SH KEYWORDS

interpreter, namespace, resolution