namespace(n) Tcl (8.0) namespace(n)
_________________________________________________________________
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 namespace
code 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 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
callback scripts in the global namespace. A scoped
command captures a command together with its namespace
context in a way that allows it to be executed properly
Page 1 (printed 2/19/99)
namespace(n) Tcl (8.0) namespace(n)
later. See the section SCOPED VALUES 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
programmers.
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
command 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 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
special characters, but it may not include any
namespace qualifiers. That is, the pattern can only
specify commands in the current (exporting) namespace.
Each pattern is appended onto the namespace's list of
export patterns. If the -clear flag is given, the
namespace'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 command returns the namespace's current export
Page 2 (printed 2/19/99)
namespace(n) Tcl (8.0) namespace(n)
list.
namespace forget ?pattern pattern ...?
Removes previously imported commands from a namespace.
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 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
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
applications then register with, e.g., Tk widgets. The
namespace inscope command is much like the namespace
Page 3 (printed 2/19/99)
namespace(n) Tcl (8.0) namespace(n)
eval command except that it has lappend semantics 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
prefixes.
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 namespace, 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 successive 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 current
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
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
Page 4 (printed 2/19/99)
namespace(n) Tcl (8.0) namespace(n)
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 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 contents of a
namespace over time using a series of namespace eval
commands. For example, the following series of commands has
the same effect as the namespace definition shown above:
namespace eval Counter {
variable num 0
proc Bump {} {
variable num
return [incr num]
}
}
namespace eval Counter {
Page 5 (printed 2/19/99)
namespace(n) Tcl (8.0) namespace(n)
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:
proc Foo::Test {args} {return $args}
And you could move the same procedure to another namespace
like this:
rename Foo::Test Bar::Test
Page 6 (printed 2/19/99)
namespace(n) Tcl (8.0) namespace(n)
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
separator. Extra :s in a qualified name are ignored; that
is, two or more :s 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
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,
Page 7 (printed 2/19/99)
namespace(n) Tcl (8.0) namespace(n)namespace eval Foo {namespace which -variable traceLevel}
returns ::Foo::traceLevel.
As mentioned above, namespace names are looked up
differently 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 a ::.
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 COMMANDS
Namespaces are often used to represent libraries. Some
library commands are used so frequently that it is a
nuisance 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 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 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
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
Page 8 (printed 2/19/99)
namespace(n) Tcl (8.0) namespace(n)
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 num
variable max
if {$num > $max} {
Page 9 (printed 2/19/99)
namespace(n) Tcl (8.0) namespace(n)
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.
SEE ALSO
variable(n)
KEYWORDS
exported, internal, variable
Page 10 (printed 2/19/99)
