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
section WHAT IS A NAMESPACE? below for a brief overview of
namespaces. The legal option's are listed below. Note
that you can abbreviate the option's.
namespace children ?namespace? ?pattern?
Returns a list of all child namespaces that belong
to the namespace namespace. If namespace is not
specified, then the children are returned for the
current namespace. This command returns fully-
qualified names, which start with ::. 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 :: is used
directly, otherwise the namespace namespace (or the
fully-qualified name of the current namespace) is
prepended onto the the pattern.
namespace code script
Captures the current namespace context for later
execution of the script script. It returns a new
script in which script has been wrapped in a names
pace code command. The new script has two impor
tant 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
executed 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 call
back scripts in the global namespace. A scoped
command captures a command together with its names
pace context in a way that allows it to be executed
some examples of how this is used to create call
back 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 conve
nience to programmers.
namespace delete ?namespace namespace ...?
Each namespace namespace is deleted and all vari
ables, 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 pre
vent other code from looking it up by name. If a
namespace doesn't exist, this command returns an
error. If no namespace names are given, this com
mand does nothing.
namespace eval namespace arg ?arg ...?
Activates a namespace called namespace and evalu
ates 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 auto
matically created.
namespace export ?-clear? ?pattern pattern ...?
Specifies which commands are exported from a names
pace. 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 previ
ously 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 special characters, but it
may not include any namespace qualifiers. That is,
the pattern can only specify commands in the cur
rent (exporting) namespace. Each pattern is
appended onto the namespace's list of export pat
terns. If the -clear flag is given, the names
pace's export pattern list is reset to empty before
any pattern arguments are appended. If no patterns
are given and the -clear flag isn't given, this
list.
namespace forget ?pattern pattern ...?
Removes previously imported commands from a names
pace. Each pattern is a qualified name such as
foo::x or a::b::p*. Qualified names contain ::s
and qualify a name with the name of one or more
namespaces. Each 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. This command first
finds the matching exported commands. It then
checks whether any of those 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 char
acters 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 command 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 arg ?arg ...?
Executes a script in the context of a particular
namespace. This command is not expected to be used
directly by programmers; calls to it are generated
implicitly when applications use namespace code
commands to create callback scripts that the appli
cations then register with, e.g., Tk widgets. The
pace eval command except that it has lappend seman
tics and the namespace must already exist. It
treats the first argument as a list, and appends
any arguments after the first onto the end as
proper list elements. namespace inscope ::foo a x
y z is equivalent to namespace eval ::foo [concat a
[list x y z]] This lappend semantics is important
because many callback scripts are actually pre
fixes.
namespace origin command
Returns the fully-qualified name of the original
command to which the imported command command
refers. When a command is imported into a names
pace, a new command is created in that namespace
that points to the actual command in the exporting
namespace. If a command is imported into a
sequence of namespaces a, b,...,n where each suc
cessive namespace just imports the command from the
previous namespace, this command returns the fully-
qualified name of the original command 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 cur
rent namespace's parent is returned.
namespace qualifiers string
Returns any leading namespace qualifiers for
string. Qualifiers are namespace names separated
by ::s. For the string ::foo::bar::x, this command
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 ::s. 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 whether the
namespace names are, in fact, the names of cur
rently defined namespaces.
namespace which ?-command? ?-variable? name
Looks up name as either a command or variable and
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 names
pace. If the command or variable does not exist,
this command returns an empty string. If the vari
able 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-quali
fied name of the variable. If no flag is given,
name is treated as a command name. See the section
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 con
tents of a namespace over time using a series of namespace
eval commands. For example, the following series of com
mands has the same effect as the namespace definition
shown above:
namespace eval Counter {
variable num 0
proc bump {} {
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 command create in the namespace interp that
is a child of 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
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:
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 sim
ple command, variable, and namespace names except as a
namespace separator. Extra :s in a qualified name are
ignored; that is, two or more :s are treated as a names
pace 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 com
mand 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-quali
fied name that starts with a ::, there is no question
about what command, variable, or namespace you mean. How
ever, if the name does not start with a :: (i.e., is rela
tive), 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 print
Trace 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
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
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 differ
ently 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 cur
rent namespace unless the new namespace name begins with a
::.
Tcl has no access control to limit what variables, com
mands, 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 vari
ables 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 COMMANDS
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 con
tained in a namespace called Blt. Then you might access
these commands 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 names
pace, 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
table . .g 0,0
The namespace import command only imports commands from a
namespace that that namespace exported with a namespace
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
commands, you can remove them with an 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.
Otherwise, 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 COMMANDS
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
set Num 0
}
proc Check {} {
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 names
pace export command specifies what commands may be
imported by other namespaces. If a namespace import com
mand specifies a command that is not exported, the command
is not imported.
SEE ALSO
variable(n)
KEYWORDS
exported, internal, variable
Man(1) output converted with
man2html