Description: namespace - create and manipulate contexts for commands and variables
Syntax: namespace ?option? ?arg ...?
Argument: options, variable names, command arguments
Returns: text string with a list of values, with spaces between elements
See Also: global, variable, source, SCREXEC
Examples:
namespace eval
::ezsmtp {
global env tcl_platform
variable mail
# Global
variables that may be altered through ezsmtp::config.
set mail(vars)
[list verbose mailhost port from strictaddr]
set mail(verbose)
0
;# No logging output
set
mail(mailhost) localhost
;# Host with smtp daemon
set mail(port)
25
;# port for smtp daemon
}
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 options are listed below.
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 :: (double colons). If the optional pattern is given, then this command returns only the names that match the glob-style pattern. A pattern that starts with :: (double colons) is used directly, otherwise the namespace namespace is added to the beginning of the pattern (added as a prefix).
namespace code script
Captures the current namespace context for later execution of the script. It returns a newscript 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 {unitone}] 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 {unit one x y}.
namespace current
Returns the 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 ...?
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 ends; 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.
namespace eval namespace arg ?arg ...?
Activates a namespace and evaluates code in arg. 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 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 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 that 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. The namespace inscope command is much like the namespace 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 origin command
Returns the fully qualified name of the original command to which the imported 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. 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. 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 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
{
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 cannot interfere with other namespaces.