diff options
Diffstat (limited to 'doc/namespace.n')
| -rw-r--r-- | doc/namespace.n | 229 |
1 files changed, 137 insertions, 92 deletions
diff --git a/doc/namespace.n b/doc/namespace.n index c79ce08..e93a704 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.9 2003/01/21 20:06:11 jenglish Exp $ +'\" RCS: @(#) $Id: namespace.n,v 1.9.2.1 2004/10/27 14:23:57 dkf Exp $ '\" .so man.macros .TH namespace n 8.0 Tcl "Tcl Built-In Commands" @@ -24,8 +24,8 @@ The \fBnamespace\fR command lets you create, access, and destroy separate contexts for commands and variables. See the section \fBWHAT IS A NAMESPACE?\fR below for a brief overview of namespaces. -The legal \fIoption\fR's are listed below. -Note that you can abbreviate the \fIoption\fR's. +The legal values of \fIoption\fR are listed below. +Note that you can abbreviate the \fIoption\fRs. .TP \fBnamespace children \fR?\fInamespace\fR? ?\fIpattern\fR? Returns a list of all child namespaces that belong to the @@ -33,14 +33,14 @@ namespace \fInamespace\fR. If \fInamespace\fR is not specified, then the children are returned for the current namespace. This command returns fully-qualified names, -which start with \fB::\fR. +which start with a double colon (\fB::\fR). If the optional \fIpattern\fR 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 \fB::\fR is used directly, +a pattern that starts with double colon (\fB::\fR) is used directly, otherwise the namespace \fInamespace\fR (or the fully-qualified name of the current namespace) -is prepended onto the the pattern. +is prepended onto the pattern. .TP \fBnamespace code \fIscript\fR Captures the current namespace context for later execution @@ -66,7 +66,7 @@ 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 later. -See the section \fBSCOPED VALUES\fR for some examples +See the section \fBSCOPED SCRIPTS\fR for some examples of how this is used to create callback scripts. .TP \fBnamespace current\fR @@ -129,7 +129,7 @@ this command returns the namespace's current export list. Removes previously imported commands from a namespace. Each \fIpattern\fR is a simple or qualified name such as \fBx\fR, \fBfoo::x\fR or \fBa::b::p*\fR. -Qualified names contain \fB::\fRs and qualify a name +Qualified names contain double colons (\fB::\fR) and qualify a name with the name of one or more namespaces. Each \fIqualified pattern\fR is qualified with the name of an exporting namespace @@ -211,7 +211,7 @@ the fully-qualified name of the current namespace's parent is returned. .TP \fBnamespace qualifiers\fR \fIstring\fR Returns any leading namespace qualifiers for \fIstring\fR. -Qualifiers are namespace names separated by \fB::\fRs. +Qualifiers are namespace names separated by double colons (\fB::\fR). For the \fIstring\fR \fB::foo::bar::x\fR, this command returns \fB::foo::bar\fR, and for \fB::\fR it returns an empty string. @@ -222,7 +222,7 @@ the names of currently defined namespaces. .TP \fBnamespace tail\fR \fIstring\fR 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 double colons (\fB::\fR). For the \fIstring\fR \fB::foo::bar::x\fR, this command returns \fBx\fR, and for \fB::\fR it returns an empty string. @@ -244,7 +244,6 @@ fully-qualified name of the variable. If no flag is given, \fIname\fR is treated as a command name. See the section \fBNAME RESOLUTION\fR below for an explanation of the rules regarding name resolution. - .SH "WHAT IS A NAMESPACE?" .PP A namespace is a collection of commands and variables. @@ -256,15 +255,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. @@ -286,21 +285,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. @@ -309,7 +308,6 @@ 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. - .SH "QUALIFIED NAMES" .PP Each namespace has a textual name such as @@ -325,8 +323,8 @@ The topmost or global namespace has the name ``'' (i.e., an empty string), although \fB::\fR is a synonym. As an example, the name \fB::safe::interp::create\fR refers to the command \fBcreate\fR in the namespace \fBinterp\fR -that is a child of of namespace \fB::safe\fR, -which in turn is a child of the global namespace \fB::\fR. +that is a child of namespace \fB::safe\fR, +which in turn is a child of the global namespace, \fB::\fR. .PP If you want to access commands and variables from another namespace, you must use some extra syntax. @@ -334,12 +332,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. @@ -347,18 +345,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 @@ -366,12 +364,11 @@ that we should cover. Namespaces have nonempty names except for the global namespace. \fB::\fR is disallowed in simple command, variable, and namespace names except as a namespace separator. -Extra \fB:\fRs in a qualified name are ignored; -that is, two or more \fB:\fRs are treated as a namespace separator. +Extra colons in any separator part of a qualified name are ignored; +i.e. two or more colons are treated as a namespace separator. A trailing \fB::\fR in a qualified variable or command name refers to the variable or command named {}. However, a trailing \fB::\fR in a qualified namespace name is ignored. - .SH "NAME RESOLUTION" .PP In general, all Tcl commands that take variable and command names @@ -392,10 +389,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. @@ -404,14 +401,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 @@ -423,12 +420,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 @@ -439,7 +436,7 @@ Namespace names are always resolved in the current namespace. This means, for example, that a \fBnamespace eval\fR command that creates a new 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 \fB::\fR. .PP Tcl has no access control to limit what variables, commands, or namespaces you can reference. @@ -459,7 +456,6 @@ to variables in the global namespace. It is not necessary to use a \fBvariable\fR command if you always refer to the namespace variable using an appropriate qualified name. - .SH "IMPORTING COMMANDS" .PP Namespaces are often used to represent libraries. @@ -469,21 +465,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 @@ -494,7 +490,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. @@ -507,12 +503,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 an \fBnamespace forget\fR command, like this: +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. @@ -521,42 +517,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. @@ -567,6 +562,56 @@ The \fBnamespace export\fR command specifies what commands may be imported by other namespaces. If a \fBnamespace import\fR command specifies a command that is not exported, the command is not imported. +.SH "SCOPED SCRIPTS" +The \fBnamespace code\fR command is the means by which a script may be +packaged for evaluation in a namespace other than the one in which it +was created. It is used most often to create event handlers, Tk bindings, +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 +\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 +When executed, it prints the message: +.CS +the value of a::b has changed to c +.CE +.SH EXAMPLES +Create a namespace containing a variable and an exported command: +.CS +\fBnamespace eval\fR foo { + variable bar 0 + proc grill {} { + variable bar + puts "called [incr bar] times" + } + \fBnamespace export\fR grill +} +.CE +.PP +Call the command defined in the previous example in various ways. +.CS +# Direct call +foo::grill + +# Import into current namespace, then call local alias +namespace import foo::grill +grill +.CE +.PP +Look up where the command imported in the previous example came from: +.CS +puts "grill came from [\fBnamespace which\fR grill]" +.CE .SH "SEE ALSO" variable(n) |