Tcl Built-In Commands namespace(1T)
NAME
namespace - create and manipulate contexts for commands and
variables
SYNOPSIS
namespace ?option? ?arg ...?
DESCRIPTION
The namespace command lets you create, access, and destroy
separate contexts for commands and variables. See the sec-
tion WHAT IS A NAMESPACE? below for a brief overview of
namespaces. The legal values of option are listed below.
Note that you can abbreviate the options.
namespace children ?namespace? ?pattern?
Returns a list of all child namespaces that belong to
the namespace namespace. If namespace is not speci-
fied, then the children are returned for the current
namespace. This command returns fully-qualified names,
which start with a double colon (::). If the optional
pattern is given, then this command returns only the
names that match the glob-style pattern. The actual
pattern used is determined as follows: a pattern that
starts with double colon (::) is used directly, other-
wise the namespace namespace (or the fully-qualified
name of the current namespace) is prepended onto the
pattern.
namespace code script
Captures the current namespace context for later execu-
tion of the script script. It returns a new script in
which script has been wrapped in a namespace inscope
command. The new script has two important properties.
First, it can be evaluated in any namespace and will
cause script to be evaluated in the current namespace
(the one where the namespace code command was invoked).
Second, additional arguments can be appended to the
resulting script and they will be passed to script as
additional arguments. For example, suppose the command
set script [namespace code {foo bar}] is invoked in
namespace ::a::b. Then eval "$script x y" can be exe-
cuted in any namespace (assuming the value of script
has been passed in properly) and will have the same
effect as the command ::namespace eval ::a::b {foo bar
x y}. This command is needed because extensions like
Tk normally execute callback scripts in the global
namespace. A scoped command captures a command
together with its namespace context in a way that
Tcl Last change: 8.0 1
Tcl Built-In Commands namespace(1T)
allows it to be executed properly later. See the sec-
tion SCOPED SCRIPTS for some examples of how this is
used to create callback scripts.
namespace current
Returns the fully-qualified name for the current
namespace. The actual name of the global namespace is
``'' (i.e., an empty string), but this command returns
:: for the global namespace as a convenience to pro-
grammers.
namespace delete ?namespace namespace ...?
Each namespace namespace is deleted and all variables,
procedures, and child namespaces contained in the
namespace are deleted. If a procedure is currently
executing inside the namespace, the namespace will be
kept alive until the procedure returns; however, the
namespace is marked to prevent other code from looking
it up by name. If a namespace doesn't exist, this com-
mand returns an error. If no namespace names are
given, this command does nothing.
namespace eval namespace arg ?arg ...?
Activates a namespace called namespace and evaluates
some code in that context. If the namespace does not
already exist, it is created. If more than one arg
argument is specified, the arguments are concatenated
together with a space between each one in the same
fashion as the eval command, and the result is
evaluated.
If namespace has leading namespace qualifiers and any
leading namespaces do not exist, they are automatically
created.
namespace exists namespace
Returns 1 if namespace is a valid namespace in the
current context, returns 0 otherwise.
namespace export ?-clear? ?pattern pattern ...?
Specifies which commands are exported from a namespace.
The exported commands are those that can be later
imported into another namespace using a namespace
import command. Both commands defined in a namespace
and commands the namespace has previously imported can
be exported by a namespace. The commands do not have
to be defined at the time the namespace export command
is executed. Each pattern may contain glob-style spe-
cial characters, but it may not include any namespace
qualifiers. That is, the pattern can only specify com-
mands in the current (exporting) namespace. Each pat-
tern is appended onto the namespace's list of export
Tcl Last change: 8.0 2
Tcl Built-In Commands namespace(1T)
patterns. If the -clear flag is given, the namespace's
export pattern list is reset to empty before any pat-
tern arguments are appended. If no patterns are given
and the -clear flag isn't given, this command returns
the namespace's current export list.
namespace forget ?pattern pattern ...?
Removes previously imported commands from a namespace.
Each pattern is a simple or qualified name such as x,
foo::x or a::b::p*. Qualified names contain double
colons (::) and qualify a name with the name of one or
more namespaces. Each qualified pattern is qualified
with the name of an exporting namespace and may have
glob-style special characters in the command name at
the end of the qualified name. Glob characters may not
appear in a namespace name. For each simple pattern
this command deletes the matching commands of the
current namespace that were imported from a different
namespace. For qualified patterns, this command first
finds the matching exported commands. It then checks
whether any of those commands were previously imported
by the current namespace. If so, this command deletes
the corresponding imported commands. In effect, this
un-does the action of a namespace import command.
namespace import ?-force? ?pattern pattern ...?
Imports commands into a namespace. Each pattern is a
qualified name like foo::x or a::p*. That is, it
includes the name of an exporting namespace and may
have glob-style special characters in the command name
at the end of the qualified name. Glob characters may
not appear in a namespace name. All the commands that
match a pattern string and which are currently exported
from their namespace are added to the current
namespace. This is done by creating a new command in
the current namespace that points to the exported com-
mand in its original namespace; when the new imported
command is called, it invokes the exported command.
This command normally returns an error if an imported
command conflicts with an existing command. However,
if the -force option is given, imported commands will
silently replace existing commands. The namespace
import command has snapshot semantics: that is, only
requested commands that are currently defined in the
exporting namespace are imported. In other words, you
can import only the commands that are in a namespace at
the time when the namespace import command is executed.
If another command is defined and exported in this
namespace later on, it will not be imported.
namespace inscope namespace script ?arg ...?
Executes a script in the context of the specified
Tcl Last change: 8.0 3
Tcl Built-In Commands namespace(1T)
namespace. This command is not expected to be used
directly by programmers; calls to it are generated
implicitly when applications use namespace code com-
mands to create callback scripts that the applications
then register with, e.g., Tk widgets. The namespace
inscope command is much like the namespace eval command
except that the namespace must already exist, and
namespace inscope appends additional args as proper
list elements.
namespace inscope ::foo $script $x $y $z is equivalent
to namespace eval ::foo [concat $script [list $x $y
$z] thus additional arguments will not undergo a
second round of substitution, as is the case with
namespace eval.
namespace origin command
Returns the fully-qualified name of the original com-
mand to which the imported command command refers.
When a command is imported into a namespace, a new com-
mand is created in that namespace that points to the
actual command in the exporting namespace. If a com-
mand is imported into a sequence of namespaces a,
b,...,n where each successive namespace just imports
the command from the previous namespace, this command
returns the fully-qualified name of the original com-
mand in the first namespace, a. If command does not
refer to an imported command, the command's own fully-
qualified name is returned.
namespace parent ?namespace?
Returns the fully-qualified name of the parent
namespace for namespace namespace. If namespace is not
specified, the fully-qualified name of the current
namespace's parent is returned.
namespace qualifiers string
Returns any leading namespace qualifiers for string.
Qualifiers are namespace names separated by double
colons (::). For the string ::foo::bar::x, this com-
mand returns ::foo::bar, and for :: it returns an empty
string. This command is the complement of the
namespace tail command. Note that it does not check
whether the namespace names are, in fact, the names of
currently defined namespaces.
namespace tail string
Returns the simple name at the end of a qualified
string. Qualifiers are namespace names separated by
double colons (::). For the string ::foo::bar::x, this
command returns x, and for :: it returns an empty
string. This command is the complement of the
namespace qualifiers command. It does not check
Tcl Last change: 8.0 4
Tcl Built-In Commands namespace(1T)
whether the namespace names are, in fact, the names of
currently defined namespaces.
namespace which ?-command? ?-variable? name
Looks up name as either a command or variable and
returns its fully-qualified name. For example, if name
does not exist in the current namespace but does exist
in the global namespace, this command returns a fully-
qualified name in the global namespace. If the command
or variable does not exist, this command returns an
empty string. If the variable has been created but not
defined, such as with the variable command or through a
trace on the variable, this command will return the
fully-qualified name of the variable. If no flag is
given, name is treated as a command name. See the sec-
tion NAME RESOLUTION below for an explanation of the
rules regarding name resolution.
WHAT IS A NAMESPACE?
A namespace is a collection of commands and variables. It
encapsulates the commands and variables to ensure that they
won't interfere with the commands and variables of other
namespaces. Tcl has always had one such collection, which
we refer to as the global namespace. The global namespace
holds all global variables and commands. The namespace eval
command lets you create new namespaces. For example,
namespace eval Counter {
namespace export bump
variable num 0
proc bump {} {
variable num
incr num
}
}
creates a new namespace containing the variable num and the
procedure bump. The commands and variables in this
namespace are separate from other commands and variables in
the same program. If there is a command named bump in the
global namespace, for example, it will be different from the
command bump in the Counter namespace.
Namespace variables resemble global variables in Tcl. They
exist outside of the procedures in a namespace but can be
accessed in a procedure via the variable command, as shown
in the example above.
Namespaces are dynamic. You can add and delete commands and
variables at any time, so you can build up the contents of a
namespace over time using a series of namespace eval com-
mands. For example, the following series of commands has
the same effect as the namespace definition shown above:
Tcl Last change: 8.0 5
Tcl Built-In Commands namespace(1T)
namespace eval Counter {
variable num 0
proc bump {} {
variable num
return [incr num]
}
}
namespace eval Counter {
proc test {args} {
return $args
}
}
namespace eval Counter {
rename test ""
}
Note that the test procedure is added to the Counter
namespace, and later removed via the rename command.
Namespaces can have other namespaces within them, so they
nest hierarchically. A nested namespace is encapsulated
inside its parent namespace and can not interfere with other
namespaces.
QUALIFIED NAMES
Each namespace has a textual name such as history or
::safe::interp. Since namespaces may nest, qualified names
are used to refer to commands, variables, and child
namespaces contained inside namespaces. Qualified names are
similar to the hierarchical path names for Unix files or Tk
widgets, except that :: is used as the separator instead of
/ or .. The topmost or global namespace has the name ``''
(i.e., an empty string), although :: is a synonym. As an
example, the name ::safe::interp::create refers to the com-
mand create in the namespace interp that is a child of
namespace ::safe, which in turn is a child of the global
namespace, ::.
If you want to access commands and variables from another
namespace, you must use some extra syntax. Names must be
qualified by the namespace that contains them. From the
global namespace, we might access the Counter procedures
like this:
Counter::bump 5
Counter::Reset
We could access the current count like this:
puts "count = $Counter::num"
When one namespace contains another, you may need more than
one qualifier to reach its elements. If we had a namespace
Foo that contained the namespace Counter, you could invoke
its bump procedure from the global namespace like this:
Foo::Counter::bump 3
Tcl Last change: 8.0 6
Tcl Built-In Commands namespace(1T)
You can also use qualified names when you create and rename
commands. For example, you could add a procedure to the Foo
namespace like this:
proc Foo::Test {args} {return $args}
And you could move the same procedure to another namespace
like this:
rename Foo::Test Bar::Test
There are a few remaining points about qualified names that
we should cover. Namespaces have nonempty names except for
the global namespace. :: is disallowed in simple command,
variable, and namespace names except as a namespace separa-
tor. Extra colons in any separator part of a qualified name
are ignored; i.e. two or more colons are treated as a
namespace separator. A trailing :: in a qualified variable
or command name refers to the variable or command named {}.
However, a trailing :: in a qualified namespace name is
ignored.
NAME RESOLUTION
In general, all Tcl commands that take variable and command
names support qualified names. This means you can give
qualified names to such commands as set, proc, rename, and
interp alias. If you provide a fully-qualified name that
starts with a ::, there is no question about what command,
variable, or namespace you mean. However, if the name does
not start with a :: (i.e., is relative), Tcl follows a
fixed rule for looking it up: Command and variable names
are always resolved by looking first in the current
namespace, and then in the global namespace. Namespace
names, on the other hand, are always resolved by looking in
only the current namespace.
In the following example,
set traceLevel 0
namespace eval Debug {
printTrace $traceLevel
}
Tcl looks for traceLevel in the namespace Debug and then in
the global namespace. It looks up the command printTrace in
the same way. If a variable or command name is not found in
either context, the name is undefined. To make this point
absolutely clear, consider the following example:
set traceLevel 0
namespace eval Foo {
variable traceLevel 3
namespace eval Debug {
printTrace $traceLevel
}
}
Here Tcl looks for traceLevel first in the namespace
Tcl Last change: 8.0 7
Tcl Built-In Commands namespace(1T)
Foo::Debug. Since it is not found there, Tcl then looks for
it in the global namespace. The variable Foo::traceLevel is
completely ignored during the name resolution process.
You can use the namespace which command to clear up any
question about name resolution. For example, the command:
namespace eval Foo::Debug {namespace which -variable traceLevel}
returns ::traceLevel. On the other hand, the command,
namespace eval Foo {namespace which -variable traceLevel}
returns ::Foo::traceLevel.
As mentioned above, namespace names are looked up dif-
ferently than the names of variables and commands.
Namespace names are always resolved in the current
namespace. This means, for example, that a namespace eval
command that creates a new namespace always creates a child
of the current namespace unless the new namespace name
begins with ::.
Tcl has no access control to limit what variables, commands,
or namespaces you can reference. If you provide a qualified
name that resolves to an element by the name resolution rule
above, you can access the element.
You can access a namespace variable from a procedure in the
same namespace by using the variable command. Much like the
global command, this creates a local link to the namespace
variable. If necessary, it also creates the variable in the
current namespace and initializes it. Note that the global
command only creates links to variables in the global
namespace. It is not necessary to use a variable command if
you always refer to the namespace variable using an
appropriate qualified name.
IMPORTING COMANDS
Namespaces are often used to represent libraries. Some
library commands are used so frequently that it is a nui-
sance to type their qualified names. For example, suppose
that all of the commands in a package like BLT are contained
in a namespace called Blt. Then you might access these com-
mands like this:
Blt::graph .g -background red
Blt::table . .g 0,0
If you use the graph and table commands frequently, you may
want to access them without the Blt:: prefix. You can do
this by importing the commands into the current namespace,
like this:
namespace import Blt::*
This adds all exported commands from the Blt namespace into
the current namespace context, so you can write code like
this:
graph .g -background red
Tcl Last change: 8.0 8
Tcl Built-In Commands namespace(1T)
table . .g 0,0
The namespace import command only imports commands from a
namespace that that namespace exported with a namespace
export command.
Importing every command from a namespace is generally a bad
idea since you don't know what you will get. It is better
to import just the specific commands you need. For example,
the command
namespace import Blt::graph Blt::table
imports only the graph and table commands into the current
context.
If you try to import a command that already exists, you will
get an error. This prevents you from importing the same
command from two different packages. But from time to time
(perhaps when debugging), you may want to get around this
restriction. You may want to reissue the namespace import
command to pick up new commands that have appeared in a
namespace. In that case, you can use the -force option, and
existing commands will be silently overwritten:
namespace import -force Blt::graph Blt::table
If for some reason, you want to stop using the imported com-
mands, you can remove them with a namespace forget command,
like this:
namespace forget Blt::*
This searches the current namespace for any commands
imported from Blt. If it finds any, it removes them. Oth-
erwise, it does nothing. After this, the Blt commands must
be accessed with the Blt:: prefix.
When you delete a command from the exporting namespace like
this:
rename Blt::graph ""
the command is automatically removed from all namespaces
that import it.
EXPORTING COMANDS
You can export commands from a namespace like this:
namespace eval Counter {
namespace export bump reset
variable Num 0
variable Max 100
proc bump {{by 1}} {
variable Num
incr Num $by
Check
return $Num
}
proc reset {} {
variable Num
Tcl Last change: 8.0 9
Tcl Built-In Commands namespace(1T)
set Num 0
}
proc Check {} {
variable Num
variable Max
if {$Num > $Max} {
error "too high!"
}
}
}
The procedures bump and reset are exported, so they are
included when you import from the Counter namespace, like
this:
namespace import Counter::*
However, the Check procedure is not exported, so it is
ignored by the import operation.
The namespace import command only imports commands that were
declared as exported by their namespace. The namespace
export command specifies what commands may be imported by
other namespaces. If a namespace import command specifies a
command that is not exported, the command is not imported.
SCOPED SCRIPTS
The namespace code command is the means by which a script
may be packaged for evaluation in a namespace other than the
one in which it was created. It is used most often to
create event handlers, Tk bindings, and traces for evalua-
tion in the global context. For instance, the following
code indicates how to direct a variable trace callback into
the current namespace:
namespace eval a {
variable b
proc theTraceCallback { n1 n2 op } {
upvar 1 $n1 var
puts "the value of $n1 has changed to $var"
return
}
trace variable b w [namespace code theTraceCallback]
}
set a::b c
When executed, it prints the message:
the value of a::b has changed to c
EXAMPLES
Create a namespace containing a variable and an exported
command:
namespace eval foo {
variable bar 0
proc grill {} {
variable bar
puts "called [incr bar] times"
Tcl Last change: 8.0 10
Tcl Built-In Commands namespace(1T)
}
namespace export grill
}
Call the command defined in the previous example in various
ways.
# Direct call
foo::grill
# Import into current namespace, then call local alias
namespace import foo::grill
grill
Look up where the command imported in the previous example
came from:
puts "grill came from [namespace origin grill]"
SEE ALSO
variable(1T)
KEYWORDS
exported, internal, variable
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWTcl
Interface Stability Uncommitted
NOTES
Source for Tcl is available on http:/opensolaris.org.
Tcl Last change: 8.0 11
|
