'\"
|
'\"
|
'\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies
|
'\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies
|
'\" Copyright (c) 1997 Sun Microsystems, Inc.
|
'\" Copyright (c) 1997 Sun Microsystems, Inc.
|
'\"
|
'\"
|
'\" See the file "license.terms" for information on usage and redistribution
|
'\" See the file "license.terms" for information on usage and redistribution
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
'\"
|
'\"
|
'\" RCS: @(#) $Id: namespace.n,v 1.1.1.1 2002-01-16 10:25:24 markom Exp $
|
'\" RCS: @(#) $Id: namespace.n,v 1.1.1.1 2002-01-16 10:25:24 markom Exp $
|
'\"
|
'\"
|
.so man.macros
|
.so man.macros
|
.TH namespace n 8.0 Tcl "Tcl Built-In Commands"
|
.TH namespace n 8.0 Tcl "Tcl Built-In Commands"
|
.BS
|
.BS
|
'\" Note: do not modify the .SH NAME line immediately below!
|
'\" Note: do not modify the .SH NAME line immediately below!
|
.SH NAME
|
.SH NAME
|
namespace \- create and manipulate contexts for commands and variables
|
namespace \- create and manipulate contexts for commands and variables
|
.SH SYNOPSIS
|
.SH SYNOPSIS
|
\fBnamespace \fR?\fIoption\fR? ?\fIarg ...\fR?
|
\fBnamespace \fR?\fIoption\fR? ?\fIarg ...\fR?
|
.BE
|
.BE
|
|
|
.SH DESCRIPTION
|
.SH DESCRIPTION
|
.PP
|
.PP
|
The \fBnamespace\fR command lets you create, access, and destroy
|
The \fBnamespace\fR command lets you create, access, and destroy
|
separate contexts for commands and variables.
|
separate contexts for commands and variables.
|
See the section \fBWHAT IS A NAMESPACE?\fR below
|
See the section \fBWHAT IS A NAMESPACE?\fR below
|
for a brief overview of namespaces.
|
for a brief overview of namespaces.
|
The legal \fIoption\fR's are listed below.
|
The legal \fIoption\fR's are listed below.
|
Note that you can abbreviate the \fIoption\fR's.
|
Note that you can abbreviate the \fIoption\fR's.
|
.TP
|
.TP
|
\fBnamespace children \fR?\fInamespace\fR? ?\fIpattern\fR?
|
\fBnamespace children \fR?\fInamespace\fR? ?\fIpattern\fR?
|
Returns a list of all child namespaces that belong to the
|
Returns a list of all child namespaces that belong to the
|
namespace \fInamespace\fR.
|
namespace \fInamespace\fR.
|
If \fInamespace\fR is not specified,
|
If \fInamespace\fR is not specified,
|
then the children are returned for the current namespace.
|
then the children are returned for the current namespace.
|
This command returns fully-qualified names,
|
This command returns fully-qualified names,
|
which start with \fB::\fR.
|
which start with \fB::\fR.
|
If the optional \fIpattern\fR is given,
|
If the optional \fIpattern\fR is given,
|
then this command returns only the names that match the glob-style pattern.
|
then this command returns only the names that match the glob-style pattern.
|
The actual pattern used is determined as follows:
|
The actual pattern used is determined as follows:
|
a pattern that starts with \fB::\fR is used directly,
|
a pattern that starts with \fB::\fR is used directly,
|
otherwise the namespace \fInamespace\fR
|
otherwise the namespace \fInamespace\fR
|
(or the fully-qualified name of the current namespace)
|
(or the fully-qualified name of the current namespace)
|
is prepended onto the the pattern.
|
is prepended onto the the pattern.
|
.TP
|
.TP
|
\fBnamespace code \fIscript\fR
|
\fBnamespace code \fIscript\fR
|
Captures the current namespace context for later execution
|
Captures the current namespace context for later execution
|
of the script \fIscript\fR.
|
of the script \fIscript\fR.
|
It returns a new script in which \fIscript\fR has been wrapped
|
It returns a new script in which \fIscript\fR has been wrapped
|
in a \fBnamespace code\fR command.
|
in a \fBnamespace code\fR command.
|
The new script has two important properties.
|
The new script has two important properties.
|
First, it can be evaluated in any namespace and will cause
|
First, it can be evaluated in any namespace and will cause
|
\fIscript\fR to be evaluated in the current namespace
|
\fIscript\fR to be evaluated in the current namespace
|
(the one where the \fBnamespace code\fR command was invoked).
|
(the one where the \fBnamespace code\fR command was invoked).
|
Second, additional arguments can be appended to the resulting script
|
Second, additional arguments can be appended to the resulting script
|
and they will be passed to \fIscript\fR as additional arguments.
|
and they will be passed to \fIscript\fR as additional arguments.
|
For example, suppose the command
|
For example, suppose the command
|
\fBset script [namespace code {foo bar}]\fR
|
\fBset script [namespace code {foo bar}]\fR
|
is invoked in namespace \fB::a::b\fR.
|
is invoked in namespace \fB::a::b\fR.
|
Then \fBeval "$script x y"\fR
|
Then \fBeval "$script x y"\fR
|
can be executed in any namespace (assuming the value of
|
can be executed in any namespace (assuming the value of
|
\fBscript\fR has been passed in properly)
|
\fBscript\fR has been passed in properly)
|
and will have the same effect as the command
|
and will have the same effect as the command
|
\fBnamespace eval ::a::b {foo bar x y}\fR.
|
\fBnamespace eval ::a::b {foo bar x y}\fR.
|
This command is needed because
|
This command is needed because
|
extensions like Tk normally execute callback scripts
|
extensions like Tk normally execute callback scripts
|
in the global namespace.
|
in the global namespace.
|
A scoped command captures a command together with its namespace context
|
A scoped command captures a command together with its namespace context
|
in a way that allows it to be executed properly later.
|
in a way that allows it to be executed properly later.
|
See the section \fBSCOPED VALUES\fR for some examples
|
See the section \fBSCOPED VALUES\fR for some examples
|
of how this is used to create callback scripts.
|
of how this is used to create callback scripts.
|
.TP
|
.TP
|
\fBnamespace current\fR
|
\fBnamespace current\fR
|
Returns the fully-qualified name for the current namespace.
|
Returns the fully-qualified name for the current namespace.
|
The actual name of the global namespace is ``''
|
The actual name of the global namespace is ``''
|
(i.e., an empty string),
|
(i.e., an empty string),
|
but this command returns \fB::\fR for the global namespace
|
but this command returns \fB::\fR for the global namespace
|
as a convenience to programmers.
|
as a convenience to programmers.
|
.TP
|
.TP
|
\fBnamespace delete \fR?\fInamespace namespace ...\fR?
|
\fBnamespace delete \fR?\fInamespace namespace ...\fR?
|
Each namespace \fInamespace\fR is deleted
|
Each namespace \fInamespace\fR is deleted
|
and all variables, procedures, and child namespaces
|
and all variables, procedures, and child namespaces
|
contained in the namespace are deleted.
|
contained in the namespace are deleted.
|
If a procedure is currently executing inside the namespace,
|
If a procedure is currently executing inside the namespace,
|
the namespace will be kept alive until the procedure returns;
|
the namespace will be kept alive until the procedure returns;
|
however, the namespace is marked to prevent other code from
|
however, the namespace is marked to prevent other code from
|
looking it up by name.
|
looking it up by name.
|
If a namespace doesn't exist, this command returns an error.
|
If a namespace doesn't exist, this command returns an error.
|
If no namespace names are given, this command does nothing.
|
If no namespace names are given, this command does nothing.
|
.TP
|
.TP
|
\fBnamespace eval\fR \fInamespace arg\fR ?\fIarg ...\fR?
|
\fBnamespace eval\fR \fInamespace arg\fR ?\fIarg ...\fR?
|
Activates a namespace called \fInamespace\fR and evaluates some code
|
Activates a namespace called \fInamespace\fR and evaluates some code
|
in that context.
|
in that context.
|
If the namespace does not already exist, it is created.
|
If the namespace does not already exist, it is created.
|
If more than one \fIarg\fR argument is specified,
|
If more than one \fIarg\fR argument is specified,
|
the arguments are concatenated together with a space between each one
|
the arguments are concatenated together with a space between each one
|
in the same fashion as the \fBeval\fR command,
|
in the same fashion as the \fBeval\fR command,
|
and the result is evaluated.
|
and the result is evaluated.
|
.br
|
.br
|
.sp
|
.sp
|
If \fInamespace\fR has leading namespace qualifiers
|
If \fInamespace\fR has leading namespace qualifiers
|
and any leading namespaces do not exist,
|
and any leading namespaces do not exist,
|
they are automatically created.
|
they are automatically created.
|
.TP
|
.TP
|
\fBnamespace export \fR?\-\fBclear\fR? ?\fIpattern pattern ...\fR?
|
\fBnamespace export \fR?\-\fBclear\fR? ?\fIpattern pattern ...\fR?
|
Specifies which commands are exported from a namespace.
|
Specifies which commands are exported from a namespace.
|
The exported commands are those that can be later imported
|
The exported commands are those that can be later imported
|
into another namespace using a \fBnamespace import\fR command.
|
into another namespace using a \fBnamespace import\fR command.
|
Both commands defined in a namespace and
|
Both commands defined in a namespace and
|
commands the namespace has previously imported
|
commands the namespace has previously imported
|
can be exported by a namespace.
|
can be exported by a namespace.
|
The commands do not have to be defined
|
The commands do not have to be defined
|
at the time the \fBnamespace export\fR command is executed.
|
at the time the \fBnamespace export\fR command is executed.
|
Each \fIpattern\fR may contain glob-style special characters,
|
Each \fIpattern\fR may contain glob-style special characters,
|
but it may not include any namespace qualifiers.
|
but it may not include any namespace qualifiers.
|
That is, the pattern can only specify commands
|
That is, the pattern can only specify commands
|
in the current (exporting) namespace.
|
in the current (exporting) namespace.
|
Each \fIpattern\fR is appended onto the namespace's list of export patterns.
|
Each \fIpattern\fR is appended onto the namespace's list of export patterns.
|
If the \-\fBclear\fR flag is given,
|
If the \-\fBclear\fR flag is given,
|
the namespace's export pattern list is reset to empty before any
|
the namespace's export pattern list is reset to empty before any
|
\fIpattern\fR arguments are appended.
|
\fIpattern\fR arguments are appended.
|
If no \fIpattern\fRs are given and the \-\fBclear\fR flag isn't given,
|
If no \fIpattern\fRs are given and the \-\fBclear\fR flag isn't given,
|
this command returns the namespace's current export list.
|
this command returns the namespace's current export list.
|
.TP
|
.TP
|
\fBnamespace forget \fR?\fIpattern pattern ...\fR?
|
\fBnamespace forget \fR?\fIpattern pattern ...\fR?
|
Removes previously imported commands from a namespace.
|
Removes previously imported commands from a namespace.
|
Each \fIpattern\fR is a qualified name such as
|
Each \fIpattern\fR is a qualified name such as
|
\fBfoo::x\fR or \fBa::b::p*\fR.
|
\fBfoo::x\fR or \fBa::b::p*\fR.
|
Qualified names contain \fB::\fRs and qualify a name
|
Qualified names contain \fB::\fRs and qualify a name
|
with the name of one or more namespaces.
|
with the name of one or more namespaces.
|
Each \fIpattern\fR is qualified with the name of an exporting namespace
|
Each \fIpattern\fR is qualified with the name of an exporting namespace
|
and may have glob-style special characters in the command name
|
and may have glob-style special characters in the command name
|
at the end of the qualified name.
|
at the end of the qualified name.
|
Glob characters may not appear in a namespace name.
|
Glob characters may not appear in a namespace name.
|
This command first finds the matching exported commands.
|
This command first finds the matching exported commands.
|
It then checks whether any of those those commands
|
It then checks whether any of those those commands
|
were previously imported by the current namespace.
|
were previously imported by the current namespace.
|
If so, this command deletes the corresponding imported commands.
|
If so, this command deletes the corresponding imported commands.
|
In effect, this un-does the action of a \fBnamespace import\fR command.
|
In effect, this un-does the action of a \fBnamespace import\fR command.
|
.TP
|
.TP
|
\fBnamespace import \fR?\fB\-force\fR? ?\fIpattern\fR \fIpattern ...\fR?
|
\fBnamespace import \fR?\fB\-force\fR? ?\fIpattern\fR \fIpattern ...\fR?
|
Imports commands into a namespace.
|
Imports commands into a namespace.
|
Each \fIpattern\fR is a qualified name like
|
Each \fIpattern\fR is a qualified name like
|
\fBfoo::x\fR or \fBa::p*\fR.
|
\fBfoo::x\fR or \fBa::p*\fR.
|
That is, it includes the name of an exporting namespace
|
That is, it includes the name of an exporting namespace
|
and may have glob-style special characters in the command name
|
and may have glob-style special characters in the command name
|
at the end of the qualified name.
|
at the end of the qualified name.
|
Glob characters may not appear in a namespace name.
|
Glob characters may not appear in a namespace name.
|
All the commands that match a \fIpattern\fR string
|
All the commands that match a \fIpattern\fR string
|
and which are currently exported from their namespace
|
and which are currently exported from their namespace
|
are added to the current namespace.
|
are added to the current namespace.
|
This is done by creating a new command in 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;
|
that points to the exported command in its original namespace;
|
when the new imported command is called, it invokes the exported command.
|
when the new imported command is called, it invokes the exported command.
|
This command normally returns an error
|
This command normally returns an error
|
if an imported command conflicts with an existing command.
|
if an imported command conflicts with an existing command.
|
However, if the \-\fBforce\fR option is given,
|
However, if the \-\fBforce\fR option is given,
|
imported commands will silently replace existing commands.
|
imported commands will silently replace existing commands.
|
The \fBnamespace import\fR command has snapshot semantics:
|
The \fBnamespace import\fR command has snapshot semantics:
|
that is, only requested commands that are currently defined
|
that is, only requested commands that are currently defined
|
in the exporting namespace are imported.
|
in the exporting namespace are imported.
|
In other words, you can import only the commands that are in a namespace
|
In other words, you can import only the commands that are in a namespace
|
at the time when the \fBnamespace import\fR command is executed.
|
at the time when the \fBnamespace import\fR command is executed.
|
If another command is defined and exported in this namespace later on,
|
If another command is defined and exported in this namespace later on,
|
it will not be imported.
|
it will not be imported.
|
.TP
|
.TP
|
\fBnamespace inscope\fR \fInamespace arg\fR ?\fIarg ...\fR?
|
\fBnamespace inscope\fR \fInamespace arg\fR ?\fIarg ...\fR?
|
Executes a script in the context of a particular namespace.
|
Executes a script in the context of a particular namespace.
|
This command is not expected to be used directly by programmers;
|
This command is not expected to be used directly by programmers;
|
calls to it are generated implicitly when applications
|
calls to it are generated implicitly when applications
|
use \fBnamespace code\fR commands to create callback scripts
|
use \fBnamespace code\fR commands to create callback scripts
|
that the applications then register with, e.g., Tk widgets.
|
that the applications then register with, e.g., Tk widgets.
|
The \fBnamespace inscope\fR command is much like the \fBnamespace eval\fR
|
The \fBnamespace inscope\fR command is much like the \fBnamespace eval\fR
|
command except that it has \fBlappend\fR semantics
|
command except that it has \fBlappend\fR semantics
|
and the namespace must already exist.
|
and the namespace must already exist.
|
It treats the first argument as a list,
|
It treats the first argument as a list,
|
and appends any arguments after the first
|
and appends any arguments after the first
|
onto the end as proper list elements.
|
onto the end as proper list elements.
|
\fBnamespace inscope ::foo a x y z\fR
|
\fBnamespace inscope ::foo a x y z\fR
|
is equivalent to
|
is equivalent to
|
\fBnamespace eval ::foo [concat a [list x y z]]\fR
|
\fBnamespace eval ::foo [concat a [list x y z]]\fR
|
This \fBlappend\fR semantics is important because many callback scripts
|
This \fBlappend\fR semantics is important because many callback scripts
|
are actually prefixes.
|
are actually prefixes.
|
.TP
|
.TP
|
\fBnamespace origin \fIcommand\fR
|
\fBnamespace origin \fIcommand\fR
|
Returns the fully-qualified name of the original command
|
Returns the fully-qualified name of the original command
|
to which the imported command \fIcommand\fR refers.
|
to which the imported command \fIcommand\fR refers.
|
When a command is imported into a namespace,
|
When a command is imported into a namespace,
|
a new command is created in that namespace
|
a new command is created in that namespace
|
that points to the actual command in the exporting namespace.
|
that points to the actual command in the exporting namespace.
|
If a command is imported into a sequence of namespaces
|
If a command is imported into a sequence of namespaces
|
\fIa, b,...,n\fR where each successive namespace
|
\fIa, b,...,n\fR where each successive namespace
|
just imports the command from the previous namespace,
|
just imports the command from the previous namespace,
|
this command returns the fully-qualified name of the original command
|
this command returns the fully-qualified name of the original command
|
in the first namespace, \fIa\fR.
|
in the first namespace, \fIa\fR.
|
If \fIcommand\fR does not refer to an imported command,
|
If \fIcommand\fR does not refer to an imported command,
|
the command's own fully-qualified name is returned.
|
the command's own fully-qualified name is returned.
|
.TP
|
.TP
|
\fBnamespace parent\fR ?\fInamespace\fR?
|
\fBnamespace parent\fR ?\fInamespace\fR?
|
Returns the fully-qualified name of the parent namespace
|
Returns the fully-qualified name of the parent namespace
|
for namespace \fInamespace\fR.
|
for namespace \fInamespace\fR.
|
If \fInamespace\fR is not specified,
|
If \fInamespace\fR is not specified,
|
the fully-qualified name of the current namespace's parent is returned.
|
the fully-qualified name of the current namespace's parent is returned.
|
.TP
|
.TP
|
\fBnamespace qualifiers\fR \fIstring\fR
|
\fBnamespace qualifiers\fR \fIstring\fR
|
Returns any leading namespace qualifiers for \fIstring\fR.
|
Returns any leading namespace qualifiers for \fIstring\fR.
|
Qualifiers are namespace names separated by \fB::\fRs.
|
Qualifiers are namespace names separated by \fB::\fRs.
|
For the \fIstring\fR \fB::foo::bar::x\fR,
|
For the \fIstring\fR \fB::foo::bar::x\fR,
|
this command returns \fB::foo::bar\fR,
|
this command returns \fB::foo::bar\fR,
|
and for \fB::\fR it returns \fB``''\fR (an empty string).
|
and for \fB::\fR it returns \fB``''\fR (an empty string).
|
This command is the complement of the \fBnamespace tail\fR command.
|
This command is the complement of the \fBnamespace tail\fR command.
|
Note that it does not check whether the
|
Note that it does not check whether the
|
namespace names are, in fact,
|
namespace names are, in fact,
|
the names of currently defined namespaces.
|
the names of currently defined namespaces.
|
.TP
|
.TP
|
\fBnamespace tail\fR \fIstring\fR
|
\fBnamespace tail\fR \fIstring\fR
|
Returns the simple name at the end of a qualified string.
|
Returns the simple name at the end of a qualified string.
|
Qualifiers are namespace names separated by \fB::\fRs.
|
Qualifiers are namespace names separated by \fB::\fRs.
|
For the \fIstring\fR \fB::foo::bar::x\fR,
|
For the \fIstring\fR \fB::foo::bar::x\fR,
|
this command returns \fBx\fR,
|
this command returns \fBx\fR,
|
and for \fB::\fR it returns \fB``''\fR (an empty string).
|
and for \fB::\fR it returns \fB``''\fR (an empty string).
|
This command is the complement of the \fBnamespace qualifiers\fR command.
|
This command is the complement of the \fBnamespace qualifiers\fR command.
|
It does not check whether the namespace names are, in fact,
|
It does not check whether the namespace names are, in fact,
|
the names of currently defined namespaces.
|
the names of currently defined namespaces.
|
.TP
|
.TP
|
\fBnamespace which\fR ?\-\fBcommand\fR? ?\-\fBvariable\fR? \fIname\fR
|
\fBnamespace which\fR ?\-\fBcommand\fR? ?\-\fBvariable\fR? \fIname\fR
|
Looks up \fIname\fR as either a command or variable
|
Looks up \fIname\fR as either a command or variable
|
and returns its fully-qualified name.
|
and returns its fully-qualified name.
|
For example, if \fIname\fR does not exist in the current namespace
|
For example, if \fIname\fR does not exist in the current namespace
|
but does exist in the global namespace,
|
but does exist in the global namespace,
|
this command returns a fully-qualified name in the global namespace.
|
this command returns a fully-qualified name in the global namespace.
|
If the command or variable does not exist,
|
If the command or variable does not exist,
|
this command returns an empty string.
|
this command returns an empty string.
|
If no flag is given, \fIname\fR is treated as a command name.
|
If no flag is given, \fIname\fR is treated as a command name.
|
See the section \fBNAME RESOLUTION\fR below for an explanation of
|
See the section \fBNAME RESOLUTION\fR below for an explanation of
|
the rules regarding name resolution.
|
the rules regarding name resolution.
|
|
|
.SH "WHAT IS A NAMESPACE?"
|
.SH "WHAT IS A NAMESPACE?"
|
.PP
|
.PP
|
A namespace is a collection of commands and variables.
|
A namespace is a collection of commands and variables.
|
It encapsulates the commands and variables to ensure that they
|
It encapsulates the commands and variables to ensure that they
|
won't interfere with the commands and variables of other namespaces.
|
won't interfere with the commands and variables of other namespaces.
|
Tcl has always had one such collection,
|
Tcl has always had one such collection,
|
which we refer to as the \fIglobal namespace\fR.
|
which we refer to as the \fIglobal namespace\fR.
|
The global namespace holds all global variables and commands.
|
The global namespace holds all global variables and commands.
|
The \fBnamespace eval\fR command lets you create new namespaces.
|
The \fBnamespace eval\fR command lets you create new namespaces.
|
For example,
|
For example,
|
.CS
|
.CS
|
\fBnamespace eval Counter {
|
\fBnamespace eval Counter {
|
namespace export Bump
|
namespace export Bump
|
variable num 0
|
variable num 0
|
|
|
proc Bump {} {
|
proc Bump {} {
|
variable num
|
variable num
|
incr num
|
incr num
|
}
|
}
|
}\fR
|
}\fR
|
.CE
|
.CE
|
creates a new namespace containing the variable \fBnum\fR and
|
creates a new namespace containing the variable \fBnum\fR and
|
the procedure \fBBump\fR.
|
the procedure \fBBump\fR.
|
The commands and variables in this namespace are separate from
|
The commands and variables in this namespace are separate from
|
other commands and variables in the same program.
|
other commands and variables in the same program.
|
If there is a command named \fBBump\fR in the global namespace,
|
If there is a command named \fBBump\fR in the global namespace,
|
for example, it will be different from the command \fBBump\fR
|
for example, it will be different from the command \fBBump\fR
|
in the \fBCounter\fR namespace.
|
in the \fBCounter\fR namespace.
|
.PP
|
.PP
|
Namespace variables resemble global variables in Tcl.
|
Namespace variables resemble global variables in Tcl.
|
They exist outside of the procedures in a namespace
|
They exist outside of the procedures in a namespace
|
but can be accessed in a procedure via the \fBvariable\fR command,
|
but can be accessed in a procedure via the \fBvariable\fR command,
|
as shown in the example above.
|
as shown in the example above.
|
.PP
|
.PP
|
Namespaces are dynamic.
|
Namespaces are dynamic.
|
You can add and delete commands and variables at any time,
|
You can add and delete commands and variables at any time,
|
so you can build up the contents of a
|
so you can build up the contents of a
|
namespace over time using a series of \fBnamespace eval\fR commands.
|
namespace over time using a series of \fBnamespace eval\fR commands.
|
For example, the following series of commands has the same effect
|
For example, the following series of commands has the same effect
|
as the namespace definition shown above:
|
as the namespace definition shown above:
|
.CS
|
.CS
|
\fBnamespace eval Counter {
|
\fBnamespace eval Counter {
|
variable num 0
|
variable num 0
|
proc Bump {} {
|
proc Bump {} {
|
variable num
|
variable num
|
return [incr num]
|
return [incr num]
|
}
|
}
|
}
|
}
|
namespace eval Counter {
|
namespace eval Counter {
|
proc test {args} {
|
proc test {args} {
|
return $args
|
return $args
|
}
|
}
|
}
|
}
|
namespace eval Counter {
|
namespace eval Counter {
|
rename test ""
|
rename test ""
|
}\fR
|
}\fR
|
.CE
|
.CE
|
Note that the \fBtest\fR procedure is added to the \fBCounter\fR namespace,
|
Note that the \fBtest\fR procedure is added to the \fBCounter\fR namespace,
|
and later removed via the \fBrename\fR command.
|
and later removed via the \fBrename\fR command.
|
.PP
|
.PP
|
Namespaces can have other namespaces within them,
|
Namespaces can have other namespaces within them,
|
so they nest hierarchically.
|
so they nest hierarchically.
|
A nested namespace is encapsulated inside its parent namespace
|
A nested namespace is encapsulated inside its parent namespace
|
and can not interfere with other namespaces.
|
and can not interfere with other namespaces.
|
|
|
.SH "QUALIFIED NAMES"
|
.SH "QUALIFIED NAMES"
|
.PP
|
.PP
|
Each namespace has a textual name such as
|
Each namespace has a textual name such as
|
\fBhistory\fR or \fB::safe::interp\fR.
|
\fBhistory\fR or \fB::safe::interp\fR.
|
Since namespaces may nest,
|
Since namespaces may nest,
|
qualified names are used to refer to
|
qualified names are used to refer to
|
commands, variables, and child namespaces contained inside namespaces.
|
commands, variables, and child namespaces contained inside namespaces.
|
Qualified names are similar to the hierarchical path names for
|
Qualified names are similar to the hierarchical path names for
|
Unix files or Tk widgets,
|
Unix files or Tk widgets,
|
except that \fB::\fR is used as the separator
|
except that \fB::\fR is used as the separator
|
instead of \fB/\fR or \fB.\fR.
|
instead of \fB/\fR or \fB.\fR.
|
The topmost or global namespace has the name ``'' (i.e., an empty string),
|
The topmost or global namespace has the name ``'' (i.e., an empty string),
|
although \fB::\fR is a synonym.
|
although \fB::\fR is a synonym.
|
As an example, the name \fB::safe::interp::create\fR
|
As an example, the name \fB::safe::interp::create\fR
|
refers to the command \fBcreate\fR in the namespace \fBinterp\fR
|
refers to the command \fBcreate\fR in the namespace \fBinterp\fR
|
that is a child of of namespace \fB::safe\fR,
|
that is a child of of namespace \fB::safe\fR,
|
which in turn is a child of the global namespace \fB::\fR.
|
which in turn is a child of the global namespace \fB::\fR.
|
.PP
|
.PP
|
If you want to access commands and variables from another namespace,
|
If you want to access commands and variables from another namespace,
|
you must use some extra syntax.
|
you must use some extra syntax.
|
Names must be qualified by the namespace that contains them.
|
Names must be qualified by the namespace that contains them.
|
From the global namespace,
|
From the global namespace,
|
we might access the \fBCounter\fR procedures like this:
|
we might access the \fBCounter\fR procedures like this:
|
.CS
|
.CS
|
\fBCounter::Bump 5
|
\fBCounter::Bump 5
|
Counter::Reset\fR
|
Counter::Reset\fR
|
.CE
|
.CE
|
We could access the current count like this:
|
We could access the current count like this:
|
.CS
|
.CS
|
\fBputs "count = $Counter::num"\fR
|
\fBputs "count = $Counter::num"\fR
|
.CE
|
.CE
|
When one namespace contains another, you may need more than one
|
When one namespace contains another, you may need more than one
|
qualifier to reach its elements.
|
qualifier to reach its elements.
|
If we had a namespace \fBFoo\fR that contained the namespace \fBCounter\fR,
|
If we had a namespace \fBFoo\fR that contained the namespace \fBCounter\fR,
|
you could invoke its \fBBump\fR procedure
|
you could invoke its \fBBump\fR procedure
|
from the global namespace like this:
|
from the global namespace like this:
|
.CS
|
.CS
|
\fBFoo::Counter::Bump 3\fR
|
\fBFoo::Counter::Bump 3\fR
|
.CE
|
.CE
|
.PP
|
.PP
|
You can also use qualified names when you create and rename commands.
|
You can also use qualified names when you create and rename commands.
|
For example, you could add a procedure to the \fBFoo\fR
|
For example, you could add a procedure to the \fBFoo\fR
|
namespace like this:
|
namespace like this:
|
.CS
|
.CS
|
\fBproc Foo::Test {args} {return $args}\fR
|
\fBproc Foo::Test {args} {return $args}\fR
|
.CE
|
.CE
|
And you could move the same procedure to another namespace like this:
|
And you could move the same procedure to another namespace like this:
|
.CS
|
.CS
|
\fBrename Foo::Test Bar::Test\fR
|
\fBrename Foo::Test Bar::Test\fR
|
.CE
|
.CE
|
.PP
|
.PP
|
There are a few remaining points about qualified names
|
There are a few remaining points about qualified names
|
that we should cover.
|
that we should cover.
|
Namespaces have nonempty names except for the global namespace.
|
Namespaces have nonempty names except for the global namespace.
|
\fB::\fR is disallowed in simple command, variable, and namespace names
|
\fB::\fR is disallowed in simple command, variable, and namespace names
|
except as a namespace separator.
|
except as a namespace separator.
|
Extra \fB:\fRs in a qualified name are ignored;
|
Extra \fB:\fRs in a qualified name are ignored;
|
that is, two or more \fB:\fRs are treated as a namespace separator.
|
that is, two or more \fB:\fRs are treated as a namespace separator.
|
A trailing \fB::\fR in a qualified variable or command name
|
A trailing \fB::\fR in a qualified variable or command name
|
refers to the variable or command named {}.
|
refers to the variable or command named {}.
|
However, a trailing \fB::\fR in a qualified namespace name is ignored.
|
However, a trailing \fB::\fR in a qualified namespace name is ignored.
|
|
|
.SH "NAME RESOLUTION"
|
.SH "NAME RESOLUTION"
|
.PP
|
.PP
|
In general, all Tcl commands that take variable and command names
|
In general, all Tcl commands that take variable and command names
|
support qualified names.
|
support qualified names.
|
This means you can give qualified names to such commands as
|
This means you can give qualified names to such commands as
|
\fBset\fR, \fBproc\fR, \fBrename\fR, and \fBinterp alias\fR.
|
\fBset\fR, \fBproc\fR, \fBrename\fR, and \fBinterp alias\fR.
|
If you provide a fully-qualified name that starts with a \fB::\fR,
|
If you provide a fully-qualified name that starts with a \fB::\fR,
|
there is no question about what command, variable, or namespace
|
there is no question about what command, variable, or namespace
|
you mean.
|
you mean.
|
However, if the name does not start with a \fB::\fR
|
However, if the name does not start with a \fB::\fR
|
(i.e., is \fIrelative\fR),
|
(i.e., is \fIrelative\fR),
|
Tcl follows a fixed rule for looking it up:
|
Tcl follows a fixed rule for looking it up:
|
Command and variable names are always resolved
|
Command and variable names are always resolved
|
by looking first in the current namespace,
|
by looking first in the current namespace,
|
and then in the global namespace.
|
and then in the global namespace.
|
Namespace names, on the other hand, are always resolved
|
Namespace names, on the other hand, are always resolved
|
by looking in only the current namespace.
|
by looking in only the current namespace.
|
.PP
|
.PP
|
In the following example,
|
In the following example,
|
.CS
|
.CS
|
\fBset traceLevel 0
|
\fBset traceLevel 0
|
namespace eval Debug {
|
namespace eval Debug {
|
printTrace $traceLevel
|
printTrace $traceLevel
|
}\fR
|
}\fR
|
.CE
|
.CE
|
Tcl looks for \fBtraceLevel\fR in the namespace \fBDebug\fR
|
Tcl looks for \fBtraceLevel\fR in the namespace \fBDebug\fR
|
and then in the global namespace.
|
and then in the global namespace.
|
It looks up the command \fBprintTrace\fR in the same way.
|
It looks up the command \fBprintTrace\fR in the same way.
|
If a variable or command name is not found in either context,
|
If a variable or command name is not found in either context,
|
the name is undefined.
|
the name is undefined.
|
To make this point absolutely clear, consider the following example:
|
To make this point absolutely clear, consider the following example:
|
.CS
|
.CS
|
\fBset traceLevel 0
|
\fBset traceLevel 0
|
namespace eval Foo {
|
namespace eval Foo {
|
variable traceLevel 3
|
variable traceLevel 3
|
|
|
namespace eval Debug {
|
namespace eval Debug {
|
printTrace $traceLevel
|
printTrace $traceLevel
|
}
|
}
|
}\fR
|
}\fR
|
.CE
|
.CE
|
Here Tcl looks for \fBtraceLevel\fR first in the namespace \fBFoo::Debug\fR.
|
Here Tcl looks for \fBtraceLevel\fR first in the namespace \fBFoo::Debug\fR.
|
Since it is not found there, Tcl then looks for it
|
Since it is not found there, Tcl then looks for it
|
in the global namespace.
|
in the global namespace.
|
The variable \fBFoo::traceLevel\fR is completely ignored
|
The variable \fBFoo::traceLevel\fR is completely ignored
|
during the name resolution process.
|
during the name resolution process.
|
.PP
|
.PP
|
You can use the \fBnamespace which\fR command to clear up any question
|
You can use the \fBnamespace which\fR command to clear up any question
|
about name resolution.
|
about name resolution.
|
For example, the command:
|
For example, the command:
|
.CS
|
.CS
|
\fBnamespace eval Foo::Debug {namespace which \-variable traceLevel}\fR
|
\fBnamespace eval Foo::Debug {namespace which \-variable traceLevel}\fR
|
.CE
|
.CE
|
returns \fB::traceLevel\fR.
|
returns \fB::traceLevel\fR.
|
On the other hand, the command,
|
On the other hand, the command,
|
.CS
|
.CS
|
\fBnamespace eval Foo {namespace which \-variable traceLevel}\fR
|
\fBnamespace eval Foo {namespace which \-variable traceLevel}\fR
|
.CE
|
.CE
|
returns \fB::Foo::traceLevel\fR.
|
returns \fB::Foo::traceLevel\fR.
|
.PP
|
.PP
|
As mentioned above,
|
As mentioned above,
|
namespace names are looked up differently
|
namespace names are looked up differently
|
than the names of variables and commands.
|
than the names of variables and commands.
|
Namespace names are always resolved in the current namespace.
|
Namespace names are always resolved in the current namespace.
|
This means, for example,
|
This means, for example,
|
that a \fBnamespace eval\fR command that creates a new namespace
|
that a \fBnamespace eval\fR command that creates a new namespace
|
always creates a child of the current namespace
|
always creates a child of the current namespace
|
unless the new namespace name begins with a \fB::\fR.
|
unless the new namespace name begins with a \fB::\fR.
|
.PP
|
.PP
|
Tcl has no access control to limit what variables, commands,
|
Tcl has no access control to limit what variables, commands,
|
or namespaces you can reference.
|
or namespaces you can reference.
|
If you provide a qualified name that resolves to an element
|
If you provide a qualified name that resolves to an element
|
by the name resolution rule above,
|
by the name resolution rule above,
|
you can access the element.
|
you can access the element.
|
.PP
|
.PP
|
You can access a namespace variable
|
You can access a namespace variable
|
from a procedure in the same namespace
|
from a procedure in the same namespace
|
by using the \fBvariable\fR command.
|
by using the \fBvariable\fR command.
|
Much like the \fBglobal\fR command,
|
Much like the \fBglobal\fR command,
|
this creates a local link to the namespace variable.
|
this creates a local link to the namespace variable.
|
If necessary, it also creates the variable in the current namespace
|
If necessary, it also creates the variable in the current namespace
|
and initializes it.
|
and initializes it.
|
Note that the \fBglobal\fR command only creates links
|
Note that the \fBglobal\fR command only creates links
|
to variables in the global namespace.
|
to variables in the global namespace.
|
It is not necessary to use a \fBvariable\fR command
|
It is not necessary to use a \fBvariable\fR command
|
if you always refer to the namespace variable using an
|
if you always refer to the namespace variable using an
|
appropriate qualified name.
|
appropriate qualified name.
|
|
|
.SH "IMPORTING COMMANDS"
|
.SH "IMPORTING COMMANDS"
|
.PP
|
.PP
|
Namespaces are often used to represent libraries.
|
Namespaces are often used to represent libraries.
|
Some library commands are used so frequently
|
Some library commands are used so frequently
|
that it is a nuisance to type their qualified names.
|
that it is a nuisance to type their qualified names.
|
For example, suppose that all of the commands in a package
|
For example, suppose that all of the commands in a package
|
like BLT are contained in a namespace called \fBBlt\fR.
|
like BLT are contained in a namespace called \fBBlt\fR.
|
Then you might access these commands like this:
|
Then you might access these commands like this:
|
.CS
|
.CS
|
\fBBlt::graph .g \-background red
|
\fBBlt::graph .g \-background red
|
Blt::table . .g 0,0\fR
|
Blt::table . .g 0,0\fR
|
.CE
|
.CE
|
If you use the \fBgraph\fR and \fBtable\fR commands frequently,
|
If you use the \fBgraph\fR and \fBtable\fR commands frequently,
|
you may want to access them without the \fBBlt::\fR prefix.
|
you may want to access them without the \fBBlt::\fR prefix.
|
You can do this by importing the commands into the current namespace,
|
You can do this by importing the commands into the current namespace,
|
like this:
|
like this:
|
.CS
|
.CS
|
\fBnamespace import Blt::*\fR
|
\fBnamespace import Blt::*\fR
|
.CE
|
.CE
|
This adds all exported commands from the \fBBlt\fR namespace
|
This adds all exported commands from the \fBBlt\fR namespace
|
into the current namespace context, so you can write code like this:
|
into the current namespace context, so you can write code like this:
|
.CS
|
.CS
|
\fBgraph .g \-background red
|
\fBgraph .g \-background red
|
table . .g 0,0\fR
|
table . .g 0,0\fR
|
.CE
|
.CE
|
The \fBnamespace import\fR command only imports commands
|
The \fBnamespace import\fR command only imports commands
|
from a namespace that that namespace exported
|
from a namespace that that namespace exported
|
with a \fBnamespace export\fR command.
|
with a \fBnamespace export\fR command.
|
.PP
|
.PP
|
Importing \fIevery\fR command from a namespace is generally
|
Importing \fIevery\fR command from a namespace is generally
|
a bad idea since you don't know what you will get.
|
a bad idea since you don't know what you will get.
|
It is better to import just the specific commands you need.
|
It is better to import just the specific commands you need.
|
For example, the command
|
For example, the command
|
.CS
|
.CS
|
\fBnamespace import Blt::graph Blt::table\fR
|
\fBnamespace import Blt::graph Blt::table\fR
|
.CE
|
.CE
|
imports only the \fBgraph\fR and \fBtable\fR commands into the
|
imports only the \fBgraph\fR and \fBtable\fR commands into the
|
current context.
|
current context.
|
.PP
|
.PP
|
If you try to import a command that already exists, you will get an
|
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
|
error. This prevents you from importing the same command from two
|
different packages. But from time to time (perhaps when debugging),
|
different packages. But from time to time (perhaps when debugging),
|
you may want to get around this restriction. You may want to
|
you may want to get around this restriction. You may want to
|
reissue the \fBnamespace import\fR command to pick up new commands
|
reissue the \fBnamespace import\fR command to pick up new commands
|
that have appeared in a namespace. In that case, you can use the
|
that have appeared in a namespace. In that case, you can use the
|
\fB\-force\fR option, and existing commands will be silently overwritten:
|
\fB\-force\fR option, and existing commands will be silently overwritten:
|
.CS
|
.CS
|
\fBnamespace import \-force Blt::graph Blt::table\fR
|
\fBnamespace import \-force Blt::graph Blt::table\fR
|
.CE
|
.CE
|
If for some reason, you want to stop using the imported commands,
|
If for some reason, you want to stop using the imported commands,
|
you can remove them with an \fBnamespace forget\fR command, like this:
|
you can remove them with an \fBnamespace forget\fR command, like this:
|
.CS
|
.CS
|
\fBnamespace forget Blt::*\fR
|
\fBnamespace forget Blt::*\fR
|
.CE
|
.CE
|
This searches the current namespace for any commands imported from \fBBlt\fR.
|
This searches the current namespace for any commands imported from \fBBlt\fR.
|
If it finds any, it removes them. Otherwise, it does nothing.
|
If it finds any, it removes them. Otherwise, it does nothing.
|
After this, the \fBBlt\fR commands must be accessed with the \fBBlt::\fR
|
After this, the \fBBlt\fR commands must be accessed with the \fBBlt::\fR
|
prefix.
|
prefix.
|
.PP
|
.PP
|
When you delete a command from the exporting namespace like this:
|
When you delete a command from the exporting namespace like this:
|
.CS
|
.CS
|
\fBrename Blt::graph ""\fR
|
\fBrename Blt::graph ""\fR
|
.CE
|
.CE
|
the command is automatically removed from all namespaces that import it.
|
the command is automatically removed from all namespaces that import it.
|
|
|
.SH "EXPORTING COMMANDS"
|
.SH "EXPORTING COMMANDS"
|
You can export commands from a namespace like this:
|
You can export commands from a namespace like this:
|
.CS
|
.CS
|
\fBnamespace eval Counter {
|
\fBnamespace eval Counter {
|
namespace export Bump Reset
|
namespace export Bump Reset
|
variable num 0
|
variable num 0
|
variable max 100
|
variable max 100
|
|
|
proc Bump {{by 1}} {
|
proc Bump {{by 1}} {
|
variable num
|
variable num
|
incr num $by
|
incr num $by
|
check
|
check
|
return $num
|
return $num
|
}
|
}
|
proc Reset {} {
|
proc Reset {} {
|
variable num
|
variable num
|
set num 0
|
set num 0
|
}
|
}
|
proc check {} {
|
proc check {} {
|
variable num
|
variable num
|
variable max
|
variable max
|
if {$num > $max} {
|
if {$num > $max} {
|
error "too high!"
|
error "too high!"
|
}
|
}
|
}
|
}
|
}\fR
|
}\fR
|
.CE
|
.CE
|
The procedures \fBBump\fR and \fBReset\fR are exported,
|
The procedures \fBBump\fR and \fBReset\fR are exported,
|
so they are included when you import from the \fBCounter\fR namespace,
|
so they are included when you import from the \fBCounter\fR namespace,
|
like this:
|
like this:
|
.CS
|
.CS
|
\fBnamespace import Counter::*\fR
|
\fBnamespace import Counter::*\fR
|
.CE
|
.CE
|
However, the \fBcheck\fR procedure is not exported,
|
However, the \fBcheck\fR procedure is not exported,
|
so it is ignored by the import operation.
|
so it is ignored by the import operation.
|
.PP
|
.PP
|
The \fBnamespace import\fR command only imports commands
|
The \fBnamespace import\fR command only imports commands
|
that were declared as exported by their namespace.
|
that were declared as exported by their namespace.
|
The \fBnamespace export\fR command specifies what commands
|
The \fBnamespace export\fR command specifies what commands
|
may be imported by other namespaces.
|
may be imported by other namespaces.
|
If a \fBnamespace import\fR command specifies a command
|
If a \fBnamespace import\fR command specifies a command
|
that is not exported, the command is not imported.
|
that is not exported, the command is not imported.
|
|
|
.SH "SEE ALSO"
|
.SH "SEE ALSO"
|
variable(n)
|
variable(n)
|
|
|
.SH KEYWORDS
|
.SH KEYWORDS
|
exported, internal, variable
|
exported, internal, variable
|
|
|
