summaryrefslogtreecommitdiffstats
path: root/doc/namespace.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/namespace.n')
-rw-r--r--doc/namespace.n176
1 files changed, 88 insertions, 88 deletions
diff --git a/doc/namespace.n b/doc/namespace.n
index c9d974d..07dfc3d 100644
--- a/doc/namespace.n
+++ b/doc/namespace.n
@@ -6,7 +6,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: namespace.n,v 1.15 2004/08/31 15:19:36 dkf Exp $
+'\" RCS: @(#) $Id: namespace.n,v 1.16 2004/10/27 14:24:37 dkf Exp $
'\"
.so man.macros
.TH namespace n 8.5 Tcl "Tcl Built-In Commands"
@@ -262,15 +262,15 @@ The global namespace holds all global variables and commands.
The \fBnamespace eval\fR command lets you create new namespaces.
For example,
.CS
-\fBnamespace eval Counter {
- namespace export bump
- variable num 0
+\fBnamespace eval\fR Counter {
+ \fBnamespace export\fR bump
+ variable num 0
- proc bump {} {
- variable num
- incr num
- }
-}\fR
+ proc bump {} {
+ variable num
+ incr num
+ }
+}
.CE
creates a new namespace containing the variable \fBnum\fR and
the procedure \fBbump\fR.
@@ -292,21 +292,21 @@ namespace over time using a series of \fBnamespace eval\fR commands.
For example, the following series of commands has the same effect
as the namespace definition shown above:
.CS
-\fBnamespace eval Counter {
- variable num 0
- proc bump {} {
- variable num
- return [incr num]
- }
+\fBnamespace eval\fR Counter {
+ variable num 0
+ proc bump {} {
+ variable num
+ return [incr num]
+ }
}
-namespace eval Counter {
- proc test {args} {
- return $args
- }
+\fBnamespace eval\fR Counter {
+ proc test {args} {
+ return $args
+ }
}
-namespace eval Counter {
+\fBnamespace eval\fR Counter {
rename test ""
-}\fR
+}
.CE
Note that the \fBtest\fR procedure is added to the \fBCounter\fR namespace,
and later removed via the \fBrename\fR command.
@@ -339,12 +339,12 @@ Names must be qualified by the namespace that contains them.
From the global namespace,
we might access the \fBCounter\fR procedures like this:
.CS
-\fBCounter::bump 5
-Counter::Reset\fR
+Counter::bump 5
+Counter::Reset
.CE
We could access the current count like this:
.CS
-\fBputs "count = $Counter::num"\fR
+puts "count = $Counter::num"
.CE
When one namespace contains another, you may need more than one
qualifier to reach its elements.
@@ -352,18 +352,18 @@ If we had a namespace \fBFoo\fR that contained the namespace \fBCounter\fR,
you could invoke its \fBbump\fR procedure
from the global namespace like this:
.CS
-\fBFoo::Counter::bump 3\fR
+Foo::Counter::bump 3
.CE
.PP
You can also use qualified names when you create and rename commands.
For example, you could add a procedure to the \fBFoo\fR
namespace like this:
.CS
-\fBproc Foo::Test {args} {return $args}\fR
+proc Foo::Test {args} {return $args}
.CE
And you could move the same procedure to another namespace like this:
.CS
-\fBrename Foo::Test Bar::Test\fR
+rename Foo::Test Bar::Test
.CE
.PP
There are a few remaining points about qualified names
@@ -396,10 +396,10 @@ by looking in only the current namespace.
.PP
In the following example,
.CS
-\fBset traceLevel 0
-namespace eval Debug {
- printTrace $traceLevel
-}\fR
+set traceLevel 0
+\fBnamespace eval\fR Debug {
+ printTrace $traceLevel
+}
.CE
Tcl looks for \fBtraceLevel\fR in the namespace \fBDebug\fR
and then in the global namespace.
@@ -408,14 +408,14 @@ 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:
.CS
-\fBset traceLevel 0
-namespace eval Foo {
- variable traceLevel 3
+set traceLevel 0
+\fBnamespace eval\fR Foo {
+ variable traceLevel 3
- namespace eval Debug {
- printTrace $traceLevel
- }
-}\fR
+ \fBnamespace eval\fR Debug {
+ printTrace $traceLevel
+ }
+}
.CE
Here Tcl looks for \fBtraceLevel\fR first in the namespace \fBFoo::Debug\fR.
Since it is not found there, Tcl then looks for it
@@ -427,12 +427,12 @@ You can use the \fBnamespace which\fR command to clear up any question
about name resolution.
For example, the command:
.CS
-\fBnamespace eval Foo::Debug {namespace which \-variable traceLevel}\fR
+\fBnamespace eval\fR Foo::Debug {\fBnamespace which\fR \-variable traceLevel}
.CE
returns \fB::traceLevel\fR.
On the other hand, the command,
.CS
-\fBnamespace eval Foo {namespace which \-variable traceLevel}\fR
+\fBnamespace eval\fR Foo {\fBnamespace which\fR \-variable traceLevel}
.CE
returns \fB::Foo::traceLevel\fR.
.PP
@@ -472,21 +472,21 @@ For example, suppose that all of the commands in a package
like BLT are contained in a namespace called \fBBlt\fR.
Then you might access these commands like this:
.CS
-\fBBlt::graph .g \-background red
-Blt::table . .g 0,0\fR
+Blt::graph .g \-background red
+Blt::table . .g 0,0
.CE
If you use the \fBgraph\fR and \fBtable\fR commands frequently,
you may want to access them without the \fBBlt::\fR prefix.
You can do this by importing the commands into the current namespace,
like this:
.CS
-\fBnamespace import Blt::*\fR
+\fBnamespace import\fR Blt::*
.CE
This adds all exported commands from the \fBBlt\fR namespace
into the current namespace context, so you can write code like this:
.CS
-\fBgraph .g \-background red
-table . .g 0,0\fR
+graph .g \-background red
+table . .g 0,0
.CE
The \fBnamespace import\fR command only imports commands
from a namespace that that namespace exported
@@ -497,7 +497,7 @@ 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
.CS
-\fBnamespace import Blt::graph Blt::table\fR
+\fBnamespace import\fR Blt::graph Blt::table
.CE
imports only the \fBgraph\fR and \fBtable\fR commands into the
current context.
@@ -510,12 +510,12 @@ reissue the \fBnamespace import\fR command to pick up new commands
that have appeared in a namespace. In that case, you can use the
\fB\-force\fR option, and existing commands will be silently overwritten:
.CS
-\fBnamespace import \-force Blt::graph Blt::table\fR
+\fBnamespace import\fR \-force Blt::graph Blt::table
.CE
If for some reason, you want to stop using the imported commands,
you can remove them with a \fBnamespace forget\fR command, like this:
.CS
-\fBnamespace forget Blt::*\fR
+\fBnamespace forget\fR Blt::*
.CE
This searches the current namespace for any commands imported from \fBBlt\fR.
If it finds any, it removes them. Otherwise, it does nothing.
@@ -524,41 +524,41 @@ prefix.
.PP
When you delete a command from the exporting namespace like this:
.CS
-\fBrename Blt::graph ""\fR
+rename Blt::graph ""
.CE
the command is automatically removed from all namespaces that import it.
.SH "EXPORTING COMMANDS"
You can export commands from a namespace like this:
.CS
-\fBnamespace eval Counter {
- namespace export bump reset
- variable Num 0
- variable Max 100
+\fBnamespace eval\fR Counter {
+ \fBnamespace export\fR 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} {
- error "too high!"
- }
- }
-}\fR
+ 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} {
+ error "too high!"
+ }
+ }
+}
.CE
The procedures \fBbump\fR and \fBreset\fR are exported,
so they are included when you import from the \fBCounter\fR namespace,
like this:
.CS
-\fBnamespace import Counter::*\fR
+\fBnamespace import\fR Counter::*
.CE
However, the \fBCheck\fR procedure is not exported,
so it is ignored by the import operation.
@@ -577,14 +577,14 @@ and traces for evaluation in the global context. For instance, the following
code indicates how to direct a variable trace callback into the current
namespace:
.CS
-namespace eval a {
- variable b
- proc theTraceCallback { n1 n2 op } {
- upvar 1 $n1 var
- puts "the value of $n1 has changed to $var"
- return
- }
- trace variable b w [namespace code theTraceCallback]
+\fBnamespace eval\fR a {
+ variable b
+ proc theTraceCallback { n1 n2 op } {
+ upvar 1 $n1 var
+ puts "the value of $n1 has changed to $var"
+ return
+ }
+ trace variable b w [\fBnamespace code\fR theTraceCallback]
}
set a::b c
.CE
@@ -751,16 +751,16 @@ delete its namespace.
.SH EXAMPLES
Create a namespace containing a variable and an exported command:
.CS
-namespace eval foo {
+\fBnamespace eval\fR foo {
variable bar 0
proc grill {} {
variable bar
puts "called [incr bar] times"
}
- namespace export grill
+ \fBnamespace export\fR grill
}
.CE
-
+.PP
Call the command defined in the previous example in various ways.
.CS
# Direct call
@@ -772,17 +772,17 @@ grill
# Create two ensembles, one with the default name and one with a
# specified name. Then call through the ensembles.
-namespace eval foo {
- namespace ensemble create
- namespace ensemble create -command ::foobar
+\fBnamespace eval\fR foo {
+ \fBnamespace ensemble\fR create
+ \fBnamespace ensemble\fR create -command ::foobar
}
foo grill
foobar grill
.CE
-
+.PP
Look up where the command imported in the previous example came from:
.CS
-puts "grill came from [namespace which grill]"
+puts "grill came from [\fBnamespace which\fR grill]"
.CE
.SH "SEE ALSO"