tcl.lang
Class Namespace

java.lang.Object
  tcl.lang.Namespace

public class Namespace
extends Object

This structure contains a cached pointer to a namespace that is the result of resolving the namespace's name in some other namespace. It is the internal representation for a nsName object. It contains the pointer along with some information that is used to check the cached pointer's validity. (ported Tcl_Namespace to Namespace)

Nested Class Summary

static interface	Namespace.DeleteProc This interface is used to provide a callback when a namespace is deleted
static class	Namespace.GetNamespaceForQualNameResult
static class	Namespace.ResolvedNsName

Field Summary

int	activationCount Number of "activations" or active call frames for this namespace that are on the Tcl call stack.
HashMap<String,Namespace>	childTable Contains any child namespaces.
HashMap<String,WrappedCommand>	cmdTable Contains all the commands currently registered in the namespace.
static int	CREATE_NS_IF_UNKNOWN Flag passed to getNamespaceForQualName to have it create all namespace components of a namespace-qualified name that cannot be found.
Namespace.DeleteProc	deleteProc method to invoke when namespace is deleted
String[]	exportArray Reference to an array of string patterns specifying which commands are exported.
static int	FIND_ONLY_NS
int	flags OR-ed combination of the namespace status flags NS_DYING and NS_DEAD (listed below)
String	fullName The namespace's fully qualified name.
Interp	interp The interpreter containing this namespace.
int	maxExportPatterns Mumber of export patterns for which space is currently allocated.
String	name /The namespace's simple (unqualified) name.
static int	NS_DEAD NS_DEAD - 1 means deleteNamespace has been called to delete the namespace and no call frames still refer to it.
long	nsId unique id for the namespace
int	numExportPatterns Number of export patterns currently registered using "namespace export".
Namespace	parent reference to the namespace that contains this one.
int	refCount Count of references by nsName objects.
Resolver	resolver If non-null, this object overrides the usual command and variable resolution mechanism in Tcl.
HashMap<String,Var>	varTable Contains all the (global) variables currently in this namespace.

Constructor Summary

Namespace()

Method Summary

static void	appendExportList(Interp interp, Namespace namespace, TclObject obj) Appends onto the argument object the list of export patterns for the specified namespace.
static Namespace	createNamespace(Interp interp, String name, Namespace.DeleteProc deleteProc) Creates a new namespace with the given name.
static void	deleteNamespace(Namespace namespace) Deletes a namespace and all of the commands, variables, and other namespaces within it.
static void	exportList(Interp interp, Namespace namespace, String pattern, boolean resetListFirst) Makes all the commands matching a pattern available to later be imported from the namespace specified by namespace (or the current namespace if namespace is null).
static WrappedCommand	findCommand(Interp interp, String name, Namespace contextNs, int flags) Tcl_FindCommand -> findCommand Searches for a command.
static Namespace	findNamespace(Interp interp, String name, Namespace contextNs, int flags) Searches for a namespace.
static Var	findNamespaceVar(Interp interp, String name, Namespace contextNs, int flags)
static Object	FirstHashEntry(HashMap table) Return the first Object value contained in the given table.
static void	forgetImport(Interp interp, Namespace namespace, String pattern) Deletes previously imported commands.
static void	free(Namespace ns)
static Namespace	getCurrentNamespace(Interp interp) Returns a reference to an interpreter's currently active namespace.
static Namespace	getGlobalNamespace(Interp interp) Returns a reference to an interpreter's global :: namespace.
static void	getNamespaceForQualName(Interp interp, String qualName, Namespace cxtNs, int flags, Namespace.GetNamespaceForQualNameResult gnfqnr)
static WrappedCommand	getOriginalCommand(WrappedCommand command) An imported command is created in a namespace when a "real" command is imported from another namespace.
static void	importList(Interp interp, Namespace namespace, String pattern, boolean allowOverwrite) Imports all of the commands matching a pattern into the namespace specified by namespace (or the current namespace if namespace is null).
static void	popCallFrame(Interp interp)
static void	pushCallFrame(Interp interp, CallFrame frame, Namespace namespace, boolean isProcCallFrame)
static void	setNamespaceResolver(Namespace namespace, Resolver resolver) ---------------------------------------------------------------------- Tcl_SetNamespaceResolvers -> setNamespaceResolver Sets the command/variable resolution object for a namespace, thereby changing the way that command/variable names are interpreted.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

name

public String name

/The namespace's simple (unqualified) name. This contains no ::'s. The name of the global namespace is "" although "::" is an synonym.

fullName

public String fullName

The namespace's fully qualified name. This starts with ::.

deleteProc

public Namespace.DeleteProc deleteProc

method to invoke when namespace is deleted

parent

public Namespace parent

reference to the namespace that contains this one. null is this is the global namespace.

childTable

public HashMap<String,Namespace> childTable

Contains any child namespaces.

nsId

public long nsId

unique id for the namespace

interp

public Interp interp

The interpreter containing this namespace.

flags

public int flags

OR-ed combination of the namespace status flags NS_DYING and NS_DEAD (listed below)

activationCount

public 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.

refCount

public int refCount

Count of references by nsName objects. The namespace can't be freed until refCount becomes zero.

cmdTable

public HashMap<String,WrappedCommand> cmdTable

Contains all the commands currently registered in the namespace. Indexed by strings; values have type (WrappedCommand). 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.

varTable

public HashMap<String,Var> varTable

Contains all the (global) variables currently in this namespace. Indexed by strings; values have type (Var).

exportArray

public String[] exportArray

Reference 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.

numExportPatterns

public int numExportPatterns

Number of export patterns currently registered using "namespace export".

maxExportPatterns

public int maxExportPatterns

Mumber of export patterns for which space is currently allocated.

resolver

public Resolver resolver

If non-null, this object overrides the usual command and variable resolution mechanism in Tcl. This procedure is invoked within findCommand and findNamespaceVar to esolve all command and variable references within the namespace.

FIND_ONLY_NS

public static final int FIND_ONLY_NS

See Also:

Constant Field Values

NS_DEAD

public static final int NS_DEAD

NS_DEAD - 1 means 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.

See Also:

Constant Field Values

CREATE_NS_IF_UNKNOWN

public static final int CREATE_NS_IF_UNKNOWN

Flag passed to getNamespaceForQualName 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

See Also:

Constant Field Values

Constructor Detail

Namespace

public Namespace()

Method Detail

toString

public String toString()

Overrides:

toString in class Object

Returns:

the full namespace name string

See Also:

Object.toString()

getCurrentNamespace

public static Namespace getCurrentNamespace(Interp interp)

Returns a reference to an interpreter's currently active namespace.

Parameters:

interp - the current interpreter

Returns:

a reference to the interpreter's current namespace

getGlobalNamespace

public static Namespace getGlobalNamespace(Interp interp)

Returns a reference to an interpreter's global :: namespace.

Parameters:

interp - the current interpreter

Returns:

a reference to the interpreter's current namespace

pushCallFrame

public static void pushCallFrame(Interp interp,
                                 CallFrame frame,
                                 Namespace namespace,
                                 boolean isProcCallFrame)

popCallFrame

public static void popCallFrame(Interp interp)

createNamespace

public static Namespace createNamespace(Interp interp,
                                        String name,
                                        Namespace.DeleteProc deleteProc)

Creates a new namespace with the given name. If there is no active namespace (i.e., the interpreter is being initialized), the global :: namespace is created and returned.

Parameters:

interp - interpreter in which to create new namespace

name - name for the new namespace; may be a qualified name with the ancestors separated with ::'s

deleteProc - procedure called when namespace is deleted, or null if none should be called

Returns:

a reference to the new namespace if successful. If the namespace already exists or if another error occurs, this routine returns null, along with an error message in the interpreter's result object. Side effects: If the name contains "::" qualifiers and a parent namespace does not already exist, it is automatically created.

deleteNamespace

public static void deleteNamespace(Namespace namespace)

Deletes a namespace and all of the commands, variables, and other namespaces within it. Results: None. Side effects: When a namespace is deleted, it is automatically removed as a child of its parent namespace. Also, all its commands, variables and child namespaces are deleted.

Parameters:

namespace - namespace to delete

free

public static void free(Namespace ns)

exportList

public static void exportList(Interp interp,
                              Namespace namespace,
                              String pattern,
                              boolean resetListFirst)
                       throws TclException

Makes all the commands matching a pattern available to later be imported from the namespace specified by namespace (or the current namespace if namespace is null). The specified pattern is appended onto the namespace's export pattern list, which is optionally cleared beforehand. Results: Returns if successful, raises TclException if something goes wrong. Side effects: Appends the export pattern onto the namespace's export list. Optionally reset the namespace's export pattern list.

Parameters:

interp - current interpreter

namespace - export commands from this namespace, or null for the current namespace

pattern - String pattern indicating which commands to export. This pattern may not include any namespace qualifiers; only commands // in the specified namespace may be exported.

resetListFirst - If true, resets the namespace's export list before appending. If false, return an error if an imported cmd conflicts

Throws:

TclException

appendExportList

public static void appendExportList(Interp interp,
                                    Namespace namespace,
                                    TclObject obj)
                             throws TclException

Appends onto the argument object the list of export patterns for the specified namespace. Results: The method will return when successful; in this case the object referenced by obj has each export pattern appended to it. If an error occurs, an exception and the interpreter's result holds an error message. Side effects: If necessary, the object referenced by obj is converted into a list object.

Parameters:

interp - the interpreter used for error reporting

namespace - points to the namespace whose export pattern list is appended onto obj; null for current namespace

obj - Tcl object onto which current export pattern list is appended

Throws:

TclException

importList

public static void importList(Interp interp,
                              Namespace namespace,
                              String pattern,
                              boolean allowOverwrite)
                       throws TclException

Imports all of the commands matching a pattern into the namespace specified by namespace (or the current namespace if namespace is null). This is done by creating a new command (the "imported command") that points to the real command in its original namespace. If matching commands are on the autoload path but haven't been loaded yet, this command forces them to be loaded, then creates the links to them. Side effects: Creates new commands in the importing namespace. These indirect calls back to the real command and are deleted if the real commands are deleted.

Parameters:

interp - current interpreter

namespace - reference to the namespace into which the commands are to be imported. null for the current namespace.

pattern - String pattern indicating which commands to import. This pattern should be qualified by the name of the namespace from which to import the command(s).

allowOverwrite - If true, allow existing commands to be overwritten by imported commands. If 0, return an error if an imported cmd conflicts with an existing one.

Throws:

TclException

forgetImport

public static void forgetImport(Interp interp,
                                Namespace namespace,
                                String pattern)
                         throws TclException

Deletes previously imported commands.

Parameters:

interp - current interpreter

namespace - Points to the namespace from which previously imported commands should be removed. null for current namespace.

pattern - String pattern indicating which importedcommands to remove. This pattern may be qualified by the name of the namespace from which the command(s) were imported.

Throws:

TclException

getOriginalCommand

public static WrappedCommand getOriginalCommand(WrappedCommand command)

An imported command is created in a namespace when a "real" command is imported from another namespace. If the specified command is an imported command, this procedure returns the original command it refers to.

Parameters:

command - the imported command for which the original command should be returned

Returns:

If the command was imported into a sequence of namespaces a, b,...,n where each successive namespace just imports the command from the previous namespace, this procedure returns the Tcl_Command token in the first namespace, a. Otherwise, if the specified command is not an imported command, the procedure returns null.

getNamespaceForQualName

public static void getNamespaceForQualName(Interp interp,
                                           String qualName,
                                           Namespace cxtNs,
                                           int flags,
                                           Namespace.GetNamespaceForQualNameResult gnfqnr)

findNamespace

public static Namespace findNamespace(Interp interp,
                                      String name,
                                      Namespace contextNs,
                                      int flags)

Searches for a namespace.

Parameters:

interp - the interpreter in which to find the namespace

name - Namespace name. If it starts with "::", will be looked up in global namespace. Else, looked up first in contextNs (current namespace if contextNs is null), then in global namespace.

contextNs - Ignored if TCL.GLOBAL_ONLY flag is set or if the name starts with "::". Otherwise, points to namespace in which to resolve name; if null, look up name in the current namespace.

flags - Flags controlling namespace lookup: an OR'd combination of TCL.GLOBAL_ONLY and TCL.LEAVE_ERR_MSG flags.

Returns:

Returns a reference to the namespace if it is found. Otherwise, returns null and leaves an error message in the interpreter's result object if "flags" contains TCL.LEAVE_ERR_MSG.

findCommand

public static WrappedCommand findCommand(Interp interp,
                                         String name,
                                         Namespace contextNs,
                                         int flags)
                                  throws TclException

Tcl_FindCommand -> findCommand Searches for a command.

Parameters:

interp - the interpreter in which to find the command

name - the commands name; if it starts with "::" it will be looked up in the global namespace, otherwise in contextNs, or the current namespace if contextNs is null, and then the global namespace

contextNs - Ignored if TCL.GLOBAL_ONLY flag set. Otherwise, points to namespace in which to resolve name. If null, look up name in the current namespace.

flags - An OR'd combination of flags: TCL.GLOBAL_ONLY (look up name only in global namespace), TCL.NAMESPACE_ONLY (look up only in contextNs, or the current namespace if contextNs is null), and TCL.LEAVE_ERR_MSG. If both TCL.GLOBAL_ONLY and TCL.NAMESPACE_ONLY are given, TCL.GLOBAL_ONLY is ignored.

Returns:

a token for the command if it is found. Otherwise, if it can't be found or there is an error, returns null and leaves an error message in the interpreter's result object if "flags" contains TCL.LEAVE_ERR_MSG.

Throws:

TclException

findNamespaceVar

public static Var findNamespaceVar(Interp interp,
                                   String name,
                                   Namespace contextNs,
                                   int flags)
                            throws TclException

Throws:

TclException

setNamespaceResolver

public static void setNamespaceResolver(Namespace namespace,
                                        Resolver resolver)

---------------------------------------------------------------------- Tcl_SetNamespaceResolvers -> setNamespaceResolver Sets the command/variable resolution object for a namespace, thereby changing the way that command/variable names are interpreted. This allows extension writers to support different name resolution schemes, such as those for object-oriented packages. Command resolution is handled by the following method: resolveCmd (Interp interp, String name, Namespace context, int flags) throws TclException; Whenever a command is executed or Namespace.findCommand is invoked within the namespace, this method is called to resolve the command name. If this method is able to resolve the name, it should return the corresponding WrappedCommand. Otherwise, the procedure can return null, and the command will be treated under the usual name resolution rules. Or, it can throw a TclException, and the command will be considered invalid. Variable resolution is handled by the following method: resolveVar (Interp interp, String name, Namespace context, int flags) throws TclException; If this method is able to resolve the name, it should return the variable as Var object. The method may also return null, and the variable will be treated under the usual name resolution rules. Or, it can throw a TclException, and the variable will be considered invalid. Results: See above. Side effects: None. ----------------------------------------------------------------------

FirstHashEntry

public static Object FirstHashEntry(HashMap table)

Return the first Object value contained in the given table. This method is used only when taking apart a table where entries in the table could be removed elsewhere. An Iterator is no longer valid once entries have been removed so it is not possible to take a table apart safely with a single iterator. This method returns null when there are no more elements in the table, so it should not be used with a table that contains null values. This method is not efficient, but it is required when dealing with a Java Iterator when the table being iterated could have elements added or deleted.

Parameters:

table - a hash table

Returns:

first element in the hash table