| 1 | '\" |
| 2 | '\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies |
| 3 | '\" Copyright (c) 1997 Sun Microsystems, Inc. |
| 4 | '\" Copyright (c) 2000 Scriptics Corporation. |
| 5 | '\" |
| 6 | '\" See the file "license.terms" for information on usage and redistribution |
| 7 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
| 8 | '\" |
| 9 | '\" RCS: @(#) $Id: namespace.n,v 1.9.2.2 2005/05/12 16:23:11 dgp Exp $ |
| 10 | '\" |
| 11 | '\" The definitions below are for supplemental macros used in Tcl/Tk |
| 12 | '\" manual entries. |
| 13 | '\" |
| 14 | '\" .AP type name in/out ?indent? |
| 15 | '\" Start paragraph describing an argument to a library procedure. |
| 16 | '\" type is type of argument (int, etc.), in/out is either "in", "out", |
| 17 | '\" or "in/out" to describe whether procedure reads or modifies arg, |
| 18 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be |
| 19 | '\" needed; use .AS below instead) |
| 20 | '\" |
| 21 | '\" .AS ?type? ?name? |
| 22 | '\" Give maximum sizes of arguments for setting tab stops. Type and |
| 23 | '\" name are examples of largest possible arguments that will be passed |
| 24 | '\" to .AP later. If args are omitted, default tab stops are used. |
| 25 | '\" |
| 26 | '\" .BS |
| 27 | '\" Start box enclosure. From here until next .BE, everything will be |
| 28 | '\" enclosed in one large box. |
| 29 | '\" |
| 30 | '\" .BE |
| 31 | '\" End of box enclosure. |
| 32 | '\" |
| 33 | '\" .CS |
| 34 | '\" Begin code excerpt. |
| 35 | '\" |
| 36 | '\" .CE |
| 37 | '\" End code excerpt. |
| 38 | '\" |
| 39 | '\" .VS ?version? ?br? |
| 40 | '\" Begin vertical sidebar, for use in marking newly-changed parts |
| 41 | '\" of man pages. The first argument is ignored and used for recording |
| 42 | '\" the version when the .VS was added, so that the sidebars can be |
| 43 | '\" found and removed when they reach a certain age. If another argument |
| 44 | '\" is present, then a line break is forced before starting the sidebar. |
| 45 | '\" |
| 46 | '\" .VE |
| 47 | '\" End of vertical sidebar. |
| 48 | '\" |
| 49 | '\" .DS |
| 50 | '\" Begin an indented unfilled display. |
| 51 | '\" |
| 52 | '\" .DE |
| 53 | '\" End of indented unfilled display. |
| 54 | '\" |
| 55 | '\" .SO |
| 56 | '\" Start of list of standard options for a Tk widget. The |
| 57 | '\" options follow on successive lines, in four columns separated |
| 58 | '\" by tabs. |
| 59 | '\" |
| 60 | '\" .SE |
| 61 | '\" End of list of standard options for a Tk widget. |
| 62 | '\" |
| 63 | '\" .OP cmdName dbName dbClass |
| 64 | '\" Start of description of a specific option. cmdName gives the |
| 65 | '\" option's name as specified in the class command, dbName gives |
| 66 | '\" the option's name in the option database, and dbClass gives |
| 67 | '\" the option's class in the option database. |
| 68 | '\" |
| 69 | '\" .UL arg1 arg2 |
| 70 | '\" Print arg1 underlined, then print arg2 normally. |
| 71 | '\" |
| 72 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| 73 | '\" |
| 74 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| 75 | .if t .wh -1.3i ^B |
| 76 | .nr ^l \n(.l |
| 77 | .ad b |
| 78 | '\" # Start an argument description |
| 79 | .de AP |
| 80 | .ie !"\\$4"" .TP \\$4 |
| 81 | .el \{\ |
| 82 | . ie !"\\$2"" .TP \\n()Cu |
| 83 | . el .TP 15 |
| 84 | .\} |
| 85 | .ta \\n()Au \\n()Bu |
| 86 | .ie !"\\$3"" \{\ |
| 87 | \&\\$1 \\fI\\$2\\fP (\\$3) |
| 88 | .\".b |
| 89 | .\} |
| 90 | .el \{\ |
| 91 | .br |
| 92 | .ie !"\\$2"" \{\ |
| 93 | \&\\$1 \\fI\\$2\\fP |
| 94 | .\} |
| 95 | .el \{\ |
| 96 | \&\\fI\\$1\\fP |
| 97 | .\} |
| 98 | .\} |
| 99 | .. |
| 100 | '\" # define tabbing values for .AP |
| 101 | .de AS |
| 102 | .nr )A 10n |
| 103 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| 104 | .nr )B \\n()Au+15n |
| 105 | .\" |
| 106 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| 107 | .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| 108 | .. |
| 109 | .AS Tcl_Interp Tcl_CreateInterp in/out |
| 110 | '\" # BS - start boxed text |
| 111 | '\" # ^y = starting y location |
| 112 | '\" # ^b = 1 |
| 113 | .de BS |
| 114 | .br |
| 115 | .mk ^y |
| 116 | .nr ^b 1u |
| 117 | .if n .nf |
| 118 | .if n .ti 0 |
| 119 | .if n \l'\\n(.lu\(ul' |
| 120 | .if n .fi |
| 121 | .. |
| 122 | '\" # BE - end boxed text (draw box now) |
| 123 | .de BE |
| 124 | .nf |
| 125 | .ti 0 |
| 126 | .mk ^t |
| 127 | .ie n \l'\\n(^lu\(ul' |
| 128 | .el \{\ |
| 129 | .\" Draw four-sided box normally, but don't draw top of |
| 130 | .\" box if the box started on an earlier page. |
| 131 | .ie !\\n(^b-1 \{\ |
| 132 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| 133 | .\} |
| 134 | .el \}\ |
| 135 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| 136 | .\} |
| 137 | .\} |
| 138 | .fi |
| 139 | .br |
| 140 | .nr ^b 0 |
| 141 | .. |
| 142 | '\" # VS - start vertical sidebar |
| 143 | '\" # ^Y = starting y location |
| 144 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| 145 | .de VS |
| 146 | .if !"\\$2"" .br |
| 147 | .mk ^Y |
| 148 | .ie n 'mc \s12\(br\s0 |
| 149 | .el .nr ^v 1u |
| 150 | .. |
| 151 | '\" # VE - end of vertical sidebar |
| 152 | .de VE |
| 153 | .ie n 'mc |
| 154 | .el \{\ |
| 155 | .ev 2 |
| 156 | .nf |
| 157 | .ti 0 |
| 158 | .mk ^t |
| 159 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| 160 | .sp -1 |
| 161 | .fi |
| 162 | .ev |
| 163 | .\} |
| 164 | .nr ^v 0 |
| 165 | .. |
| 166 | '\" # Special macro to handle page bottom: finish off current |
| 167 | '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| 168 | '\" # page bottom macro. |
| 169 | .de ^B |
| 170 | .ev 2 |
| 171 | 'ti 0 |
| 172 | 'nf |
| 173 | .mk ^t |
| 174 | .if \\n(^b \{\ |
| 175 | .\" Draw three-sided box if this is the box's first page, |
| 176 | .\" draw two sides but no top otherwise. |
| 177 | .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| 178 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| 179 | .\} |
| 180 | .if \\n(^v \{\ |
| 181 | .nr ^x \\n(^tu+1v-\\n(^Yu |
| 182 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| 183 | .\} |
| 184 | .bp |
| 185 | 'fi |
| 186 | .ev |
| 187 | .if \\n(^b \{\ |
| 188 | .mk ^y |
| 189 | .nr ^b 2 |
| 190 | .\} |
| 191 | .if \\n(^v \{\ |
| 192 | .mk ^Y |
| 193 | .\} |
| 194 | .. |
| 195 | '\" # DS - begin display |
| 196 | .de DS |
| 197 | .RS |
| 198 | .nf |
| 199 | .sp |
| 200 | .. |
| 201 | '\" # DE - end display |
| 202 | .de DE |
| 203 | .fi |
| 204 | .RE |
| 205 | .sp |
| 206 | .. |
| 207 | '\" # SO - start of list of standard options |
| 208 | .de SO |
| 209 | .SH "STANDARD OPTIONS" |
| 210 | .LP |
| 211 | .nf |
| 212 | .ta 5.5c 11c |
| 213 | .ft B |
| 214 | .. |
| 215 | '\" # SE - end of list of standard options |
| 216 | .de SE |
| 217 | .fi |
| 218 | .ft R |
| 219 | .LP |
| 220 | See the \\fBoptions\\fR manual entry for details on the standard options. |
| 221 | .. |
| 222 | '\" # OP - start of full description for a single option |
| 223 | .de OP |
| 224 | .LP |
| 225 | .nf |
| 226 | .ta 4c |
| 227 | Command-Line Name: \\fB\\$1\\fR |
| 228 | Database Name: \\fB\\$2\\fR |
| 229 | Database Class: \\fB\\$3\\fR |
| 230 | .fi |
| 231 | .IP |
| 232 | .. |
| 233 | '\" # CS - begin code excerpt |
| 234 | .de CS |
| 235 | .RS |
| 236 | .nf |
| 237 | .ta .25i .5i .75i 1i |
| 238 | .. |
| 239 | '\" # CE - end code excerpt |
| 240 | .de CE |
| 241 | .fi |
| 242 | .RE |
| 243 | .. |
| 244 | .de UL |
| 245 | \\$1\l'|0\(ul'\\$2 |
| 246 | .. |
| 247 | .TH namespace n 8.0 Tcl "Tcl Built-In Commands" |
| 248 | .BS |
| 249 | '\" Note: do not modify the .SH NAME line immediately below! |
| 250 | .SH NAME |
| 251 | namespace \- create and manipulate contexts for commands and variables |
| 252 | .SH SYNOPSIS |
| 253 | \fBnamespace \fR?\fIoption\fR? ?\fIarg ...\fR? |
| 254 | .BE |
| 255 | |
| 256 | .SH DESCRIPTION |
| 257 | .PP |
| 258 | The \fBnamespace\fR command lets you create, access, and destroy |
| 259 | separate contexts for commands and variables. |
| 260 | See the section \fBWHAT IS A NAMESPACE?\fR below |
| 261 | for a brief overview of namespaces. |
| 262 | The legal values of \fIoption\fR are listed below. |
| 263 | Note that you can abbreviate the \fIoption\fRs. |
| 264 | .TP |
| 265 | \fBnamespace children \fR?\fInamespace\fR? ?\fIpattern\fR? |
| 266 | Returns a list of all child namespaces that belong to the |
| 267 | namespace \fInamespace\fR. |
| 268 | If \fInamespace\fR is not specified, |
| 269 | then the children are returned for the current namespace. |
| 270 | This command returns fully-qualified names, |
| 271 | which start with a double colon (\fB::\fR). |
| 272 | If the optional \fIpattern\fR is given, |
| 273 | then this command returns only the names that match the glob-style pattern. |
| 274 | The actual pattern used is determined as follows: |
| 275 | a pattern that starts with double colon (\fB::\fR) is used directly, |
| 276 | otherwise the namespace \fInamespace\fR |
| 277 | (or the fully-qualified name of the current namespace) |
| 278 | is prepended onto the pattern. |
| 279 | .TP |
| 280 | \fBnamespace code \fIscript\fR |
| 281 | Captures the current namespace context for later execution |
| 282 | of the script \fIscript\fR. |
| 283 | It returns a new script in which \fIscript\fR has been wrapped |
| 284 | in a \fBnamespace inscope\fR command. |
| 285 | The new script has two important properties. |
| 286 | First, it can be evaluated in any namespace and will cause |
| 287 | \fIscript\fR to be evaluated in the current namespace |
| 288 | (the one where the \fBnamespace code\fR command was invoked). |
| 289 | Second, additional arguments can be appended to the resulting script |
| 290 | and they will be passed to \fIscript\fR as additional arguments. |
| 291 | For example, suppose the command |
| 292 | \fBset script [namespace code {foo bar}]\fR |
| 293 | is invoked in namespace \fB::a::b\fR. |
| 294 | Then \fBeval "$script x y"\fR |
| 295 | can be executed in any namespace (assuming the value of |
| 296 | \fBscript\fR has been passed in properly) |
| 297 | and will have the same effect as the command |
| 298 | \fB::namespace eval ::a::b {foo bar x y}\fR. |
| 299 | This command is needed because |
| 300 | extensions like Tk normally execute callback scripts |
| 301 | in the global namespace. |
| 302 | A scoped command captures a command together with its namespace context |
| 303 | in a way that allows it to be executed properly later. |
| 304 | See the section \fBSCOPED SCRIPTS\fR for some examples |
| 305 | of how this is used to create callback scripts. |
| 306 | .TP |
| 307 | \fBnamespace current\fR |
| 308 | Returns the fully-qualified name for the current namespace. |
| 309 | The actual name of the global namespace is ``'' |
| 310 | (i.e., an empty string), |
| 311 | but this command returns \fB::\fR for the global namespace |
| 312 | as a convenience to programmers. |
| 313 | .TP |
| 314 | \fBnamespace delete \fR?\fInamespace namespace ...\fR? |
| 315 | Each namespace \fInamespace\fR is deleted |
| 316 | and all variables, procedures, and child namespaces |
| 317 | contained in the namespace are deleted. |
| 318 | If a procedure is currently executing inside the namespace, |
| 319 | the namespace will be kept alive until the procedure returns; |
| 320 | however, the namespace is marked to prevent other code from |
| 321 | looking it up by name. |
| 322 | If a namespace doesn't exist, this command returns an error. |
| 323 | If no namespace names are given, this command does nothing. |
| 324 | .TP |
| 325 | \fBnamespace eval\fR \fInamespace arg\fR ?\fIarg ...\fR? |
| 326 | Activates a namespace called \fInamespace\fR and evaluates some code |
| 327 | in that context. |
| 328 | If the namespace does not already exist, it is created. |
| 329 | If more than one \fIarg\fR argument is specified, |
| 330 | the arguments are concatenated together with a space between each one |
| 331 | in the same fashion as the \fBeval\fR command, |
| 332 | and the result is evaluated. |
| 333 | .br |
| 334 | .sp |
| 335 | If \fInamespace\fR has leading namespace qualifiers |
| 336 | and any leading namespaces do not exist, |
| 337 | they are automatically created. |
| 338 | .TP |
| 339 | \fBnamespace exists\fR \fInamespace\fR |
| 340 | Returns \fB1\fR if \fInamespace\fR is a valid namespace in the current |
| 341 | context, returns \fB0\fR otherwise. |
| 342 | .TP |
| 343 | \fBnamespace export \fR?\-\fBclear\fR? ?\fIpattern pattern ...\fR? |
| 344 | Specifies which commands are exported from a namespace. |
| 345 | The exported commands are those that can be later imported |
| 346 | into another namespace using a \fBnamespace import\fR command. |
| 347 | Both commands defined in a namespace and |
| 348 | commands the namespace has previously imported |
| 349 | can be exported by a namespace. |
| 350 | The commands do not have to be defined |
| 351 | at the time the \fBnamespace export\fR command is executed. |
| 352 | Each \fIpattern\fR may contain glob-style special characters, |
| 353 | but it may not include any namespace qualifiers. |
| 354 | That is, the pattern can only specify commands |
| 355 | in the current (exporting) namespace. |
| 356 | Each \fIpattern\fR is appended onto the namespace's list of export patterns. |
| 357 | If the \-\fBclear\fR flag is given, |
| 358 | the namespace's export pattern list is reset to empty before any |
| 359 | \fIpattern\fR arguments are appended. |
| 360 | If no \fIpattern\fRs are given and the \-\fBclear\fR flag isn't given, |
| 361 | this command returns the namespace's current export list. |
| 362 | .TP |
| 363 | \fBnamespace forget \fR?\fIpattern pattern ...\fR? |
| 364 | Removes previously imported commands from a namespace. |
| 365 | Each \fIpattern\fR is a simple or qualified name such as |
| 366 | \fBx\fR, \fBfoo::x\fR or \fBa::b::p*\fR. |
| 367 | Qualified names contain double colons (\fB::\fR) and qualify a name |
| 368 | with the name of one or more namespaces. |
| 369 | Each \fIqualified pattern\fR is qualified with the name of an |
| 370 | exporting namespace |
| 371 | and may have glob-style special characters in the command name |
| 372 | at the end of the qualified name. |
| 373 | Glob characters may not appear in a namespace name. |
| 374 | For each \fIsimple pattern\fR this command deletes the matching |
| 375 | commands of the |
| 376 | current namespace that were imported from a different namespace. |
| 377 | For \fIqualified patterns\fR, this command first finds the matching |
| 378 | exported commands. |
| 379 | It then checks whether any of those commands |
| 380 | were previously imported by the current namespace. |
| 381 | If so, this command deletes the corresponding imported commands. |
| 382 | In effect, this un-does the action of a \fBnamespace import\fR command. |
| 383 | .TP |
| 384 | \fBnamespace import \fR?\fB\-force\fR? ?\fIpattern\fR \fIpattern ...\fR? |
| 385 | Imports commands into a namespace. |
| 386 | Each \fIpattern\fR is a qualified name like |
| 387 | \fBfoo::x\fR or \fBa::p*\fR. |
| 388 | That is, it includes the name of an exporting namespace |
| 389 | and may have glob-style special characters in the command name |
| 390 | at the end of the qualified name. |
| 391 | Glob characters may not appear in a namespace name. |
| 392 | All the commands that match a \fIpattern\fR string |
| 393 | and which are currently exported from their namespace |
| 394 | are added to the current namespace. |
| 395 | This is done by creating a new command in the current namespace |
| 396 | that points to the exported command in its original namespace; |
| 397 | when the new imported command is called, it invokes the exported command. |
| 398 | This command normally returns an error |
| 399 | if an imported command conflicts with an existing command. |
| 400 | However, if the \-\fBforce\fR option is given, |
| 401 | imported commands will silently replace existing commands. |
| 402 | The \fBnamespace import\fR command has snapshot semantics: |
| 403 | that is, only requested commands that are currently defined |
| 404 | in the exporting namespace are imported. |
| 405 | In other words, you can import only the commands that are in a namespace |
| 406 | at the time when the \fBnamespace import\fR command is executed. |
| 407 | If another command is defined and exported in this namespace later on, |
| 408 | it will not be imported. |
| 409 | .TP |
| 410 | \fBnamespace inscope\fR \fInamespace\fR \fIscript\fR ?\fIarg ...\fR? |
| 411 | Executes a script in the context of the specified \fInamespace\fR. |
| 412 | This command is not expected to be used directly by programmers; |
| 413 | calls to it are generated implicitly when applications |
| 414 | use \fBnamespace code\fR commands to create callback scripts |
| 415 | that the applications then register with, e.g., Tk widgets. |
| 416 | The \fBnamespace inscope\fR command is much like the \fBnamespace eval\fR |
| 417 | command except that the \fInamespace\fR must already exist, |
| 418 | and \fBnamespace inscope\fR appends additional \fIarg\fRs |
| 419 | as proper list elements. |
| 420 | .br |
| 421 | \fBnamespace inscope ::foo $script $x $y $z\fR |
| 422 | is equivalent to |
| 423 | \fBnamespace eval ::foo [concat $script [list $x $y $z]]\fR |
| 424 | thus additional arguments will not undergo a second round of substitution, |
| 425 | as is the case with \fBnamespace eval\fR. |
| 426 | .TP |
| 427 | \fBnamespace origin \fIcommand\fR |
| 428 | Returns the fully-qualified name of the original command |
| 429 | to which the imported command \fIcommand\fR refers. |
| 430 | When a command is imported into a namespace, |
| 431 | a new command is created in that namespace |
| 432 | that points to the actual command in the exporting namespace. |
| 433 | If a command is imported into a sequence of namespaces |
| 434 | \fIa, b,...,n\fR where each successive namespace |
| 435 | just imports the command from the previous namespace, |
| 436 | this command returns the fully-qualified name of the original command |
| 437 | in the first namespace, \fIa\fR. |
| 438 | If \fIcommand\fR does not refer to an imported command, |
| 439 | the command's own fully-qualified name is returned. |
| 440 | .TP |
| 441 | \fBnamespace parent\fR ?\fInamespace\fR? |
| 442 | Returns the fully-qualified name of the parent namespace |
| 443 | for namespace \fInamespace\fR. |
| 444 | If \fInamespace\fR is not specified, |
| 445 | the fully-qualified name of the current namespace's parent is returned. |
| 446 | .TP |
| 447 | \fBnamespace qualifiers\fR \fIstring\fR |
| 448 | Returns any leading namespace qualifiers for \fIstring\fR. |
| 449 | Qualifiers are namespace names separated by double colons (\fB::\fR). |
| 450 | For the \fIstring\fR \fB::foo::bar::x\fR, |
| 451 | this command returns \fB::foo::bar\fR, |
| 452 | and for \fB::\fR it returns an empty string. |
| 453 | This command is the complement of the \fBnamespace tail\fR command. |
| 454 | Note that it does not check whether the |
| 455 | namespace names are, in fact, |
| 456 | the names of currently defined namespaces. |
| 457 | .TP |
| 458 | \fBnamespace tail\fR \fIstring\fR |
| 459 | Returns the simple name at the end of a qualified string. |
| 460 | Qualifiers are namespace names separated by double colons (\fB::\fR). |
| 461 | For the \fIstring\fR \fB::foo::bar::x\fR, |
| 462 | this command returns \fBx\fR, |
| 463 | and for \fB::\fR it returns an empty string. |
| 464 | This command is the complement of the \fBnamespace qualifiers\fR command. |
| 465 | It does not check whether the namespace names are, in fact, |
| 466 | the names of currently defined namespaces. |
| 467 | .TP |
| 468 | \fBnamespace which\fR ?\-\fBcommand\fR? ?\-\fBvariable\fR? \fIname\fR |
| 469 | Looks up \fIname\fR as either a command or variable |
| 470 | and returns its fully-qualified name. |
| 471 | For example, if \fIname\fR does not exist in the current namespace |
| 472 | but does exist in the global namespace, |
| 473 | this command returns a fully-qualified name in the global namespace. |
| 474 | If the command or variable does not exist, |
| 475 | this command returns an empty string. If the variable has been |
| 476 | created but not defined, such as with the \fBvariable\fR command |
| 477 | or through a \fBtrace\fR on the variable, this command will return the |
| 478 | fully-qualified name of the variable. |
| 479 | If no flag is given, \fIname\fR is treated as a command name. |
| 480 | See the section \fBNAME RESOLUTION\fR below for an explanation of |
| 481 | the rules regarding name resolution. |
| 482 | .SH "WHAT IS A NAMESPACE?" |
| 483 | .PP |
| 484 | A namespace is a collection of commands and variables. |
| 485 | It encapsulates the commands and variables to ensure that they |
| 486 | won't interfere with the commands and variables of other namespaces. |
| 487 | Tcl has always had one such collection, |
| 488 | which we refer to as the \fIglobal namespace\fR. |
| 489 | The global namespace holds all global variables and commands. |
| 490 | The \fBnamespace eval\fR command lets you create new namespaces. |
| 491 | For example, |
| 492 | .CS |
| 493 | \fBnamespace eval\fR Counter { |
| 494 | \fBnamespace export\fR bump |
| 495 | variable num 0 |
| 496 | |
| 497 | proc bump {} { |
| 498 | variable num |
| 499 | incr num |
| 500 | } |
| 501 | } |
| 502 | .CE |
| 503 | creates a new namespace containing the variable \fBnum\fR and |
| 504 | the procedure \fBbump\fR. |
| 505 | The commands and variables in this namespace are separate from |
| 506 | other commands and variables in the same program. |
| 507 | If there is a command named \fBbump\fR in the global namespace, |
| 508 | for example, it will be different from the command \fBbump\fR |
| 509 | in the \fBCounter\fR namespace. |
| 510 | .PP |
| 511 | Namespace variables resemble global variables in Tcl. |
| 512 | They exist outside of the procedures in a namespace |
| 513 | but can be accessed in a procedure via the \fBvariable\fR command, |
| 514 | as shown in the example above. |
| 515 | .PP |
| 516 | Namespaces are dynamic. |
| 517 | You can add and delete commands and variables at any time, |
| 518 | so you can build up the contents of a |
| 519 | namespace over time using a series of \fBnamespace eval\fR commands. |
| 520 | For example, the following series of commands has the same effect |
| 521 | as the namespace definition shown above: |
| 522 | .CS |
| 523 | \fBnamespace eval\fR Counter { |
| 524 | variable num 0 |
| 525 | proc bump {} { |
| 526 | variable num |
| 527 | return [incr num] |
| 528 | } |
| 529 | } |
| 530 | \fBnamespace eval\fR Counter { |
| 531 | proc test {args} { |
| 532 | return $args |
| 533 | } |
| 534 | } |
| 535 | \fBnamespace eval\fR Counter { |
| 536 | rename test "" |
| 537 | } |
| 538 | .CE |
| 539 | Note that the \fBtest\fR procedure is added to the \fBCounter\fR namespace, |
| 540 | and later removed via the \fBrename\fR command. |
| 541 | .PP |
| 542 | Namespaces can have other namespaces within them, |
| 543 | so they nest hierarchically. |
| 544 | A nested namespace is encapsulated inside its parent namespace |
| 545 | and can not interfere with other namespaces. |
| 546 | .SH "QUALIFIED NAMES" |
| 547 | .PP |
| 548 | Each namespace has a textual name such as |
| 549 | \fBhistory\fR or \fB::safe::interp\fR. |
| 550 | Since namespaces may nest, |
| 551 | qualified names are used to refer to |
| 552 | commands, variables, and child namespaces contained inside namespaces. |
| 553 | Qualified names are similar to the hierarchical path names for |
| 554 | Unix files or Tk widgets, |
| 555 | except that \fB::\fR is used as the separator |
| 556 | instead of \fB/\fR or \fB.\fR. |
| 557 | The topmost or global namespace has the name ``'' (i.e., an empty string), |
| 558 | although \fB::\fR is a synonym. |
| 559 | As an example, the name \fB::safe::interp::create\fR |
| 560 | refers to the command \fBcreate\fR in the namespace \fBinterp\fR |
| 561 | that is a child of namespace \fB::safe\fR, |
| 562 | which in turn is a child of the global namespace, \fB::\fR. |
| 563 | .PP |
| 564 | If you want to access commands and variables from another namespace, |
| 565 | you must use some extra syntax. |
| 566 | Names must be qualified by the namespace that contains them. |
| 567 | From the global namespace, |
| 568 | we might access the \fBCounter\fR procedures like this: |
| 569 | .CS |
| 570 | Counter::bump 5 |
| 571 | Counter::Reset |
| 572 | .CE |
| 573 | We could access the current count like this: |
| 574 | .CS |
| 575 | puts "count = $Counter::num" |
| 576 | .CE |
| 577 | When one namespace contains another, you may need more than one |
| 578 | qualifier to reach its elements. |
| 579 | If we had a namespace \fBFoo\fR that contained the namespace \fBCounter\fR, |
| 580 | you could invoke its \fBbump\fR procedure |
| 581 | from the global namespace like this: |
| 582 | .CS |
| 583 | Foo::Counter::bump 3 |
| 584 | .CE |
| 585 | .PP |
| 586 | You can also use qualified names when you create and rename commands. |
| 587 | For example, you could add a procedure to the \fBFoo\fR |
| 588 | namespace like this: |
| 589 | .CS |
| 590 | proc Foo::Test {args} {return $args} |
| 591 | .CE |
| 592 | And you could move the same procedure to another namespace like this: |
| 593 | .CS |
| 594 | rename Foo::Test Bar::Test |
| 595 | .CE |
| 596 | .PP |
| 597 | There are a few remaining points about qualified names |
| 598 | that we should cover. |
| 599 | Namespaces have nonempty names except for the global namespace. |
| 600 | \fB::\fR is disallowed in simple command, variable, and namespace names |
| 601 | except as a namespace separator. |
| 602 | Extra colons in any separator part of a qualified name are ignored; |
| 603 | i.e. two or more colons are treated as a namespace separator. |
| 604 | A trailing \fB::\fR in a qualified variable or command name |
| 605 | refers to the variable or command named {}. |
| 606 | However, a trailing \fB::\fR in a qualified namespace name is ignored. |
| 607 | .SH "NAME RESOLUTION" |
| 608 | .PP |
| 609 | In general, all Tcl commands that take variable and command names |
| 610 | support qualified names. |
| 611 | This means you can give qualified names to such commands as |
| 612 | \fBset\fR, \fBproc\fR, \fBrename\fR, and \fBinterp alias\fR. |
| 613 | If you provide a fully-qualified name that starts with a \fB::\fR, |
| 614 | there is no question about what command, variable, or namespace |
| 615 | you mean. |
| 616 | However, if the name does not start with a \fB::\fR |
| 617 | (i.e., is \fIrelative\fR), |
| 618 | Tcl follows a fixed rule for looking it up: |
| 619 | Command and variable names are always resolved |
| 620 | by looking first in the current namespace, |
| 621 | and then in the global namespace. |
| 622 | Namespace names, on the other hand, are always resolved |
| 623 | by looking in only the current namespace. |
| 624 | .PP |
| 625 | In the following example, |
| 626 | .CS |
| 627 | set traceLevel 0 |
| 628 | \fBnamespace eval\fR Debug { |
| 629 | printTrace $traceLevel |
| 630 | } |
| 631 | .CE |
| 632 | Tcl looks for \fBtraceLevel\fR in the namespace \fBDebug\fR |
| 633 | and then in the global namespace. |
| 634 | It looks up the command \fBprintTrace\fR in the same way. |
| 635 | If a variable or command name is not found in either context, |
| 636 | the name is undefined. |
| 637 | To make this point absolutely clear, consider the following example: |
| 638 | .CS |
| 639 | set traceLevel 0 |
| 640 | \fBnamespace eval\fR Foo { |
| 641 | variable traceLevel 3 |
| 642 | |
| 643 | \fBnamespace eval\fR Debug { |
| 644 | printTrace $traceLevel |
| 645 | } |
| 646 | } |
| 647 | .CE |
| 648 | Here Tcl looks for \fBtraceLevel\fR first in the namespace \fBFoo::Debug\fR. |
| 649 | Since it is not found there, Tcl then looks for it |
| 650 | in the global namespace. |
| 651 | The variable \fBFoo::traceLevel\fR is completely ignored |
| 652 | during the name resolution process. |
| 653 | .PP |
| 654 | You can use the \fBnamespace which\fR command to clear up any question |
| 655 | about name resolution. |
| 656 | For example, the command: |
| 657 | .CS |
| 658 | \fBnamespace eval\fR Foo::Debug {\fBnamespace which\fR \-variable traceLevel} |
| 659 | .CE |
| 660 | returns \fB::traceLevel\fR. |
| 661 | On the other hand, the command, |
| 662 | .CS |
| 663 | \fBnamespace eval\fR Foo {\fBnamespace which\fR \-variable traceLevel} |
| 664 | .CE |
| 665 | returns \fB::Foo::traceLevel\fR. |
| 666 | .PP |
| 667 | As mentioned above, |
| 668 | namespace names are looked up differently |
| 669 | than the names of variables and commands. |
| 670 | Namespace names are always resolved in the current namespace. |
| 671 | This means, for example, |
| 672 | that a \fBnamespace eval\fR command that creates a new namespace |
| 673 | always creates a child of the current namespace |
| 674 | unless the new namespace name begins with \fB::\fR. |
| 675 | .PP |
| 676 | Tcl has no access control to limit what variables, commands, |
| 677 | or namespaces you can reference. |
| 678 | If you provide a qualified name that resolves to an element |
| 679 | by the name resolution rule above, |
| 680 | you can access the element. |
| 681 | .PP |
| 682 | You can access a namespace variable |
| 683 | from a procedure in the same namespace |
| 684 | by using the \fBvariable\fR command. |
| 685 | Much like the \fBglobal\fR command, |
| 686 | this creates a local link to the namespace variable. |
| 687 | If necessary, it also creates the variable in the current namespace |
| 688 | and initializes it. |
| 689 | Note that the \fBglobal\fR command only creates links |
| 690 | to variables in the global namespace. |
| 691 | It is not necessary to use a \fBvariable\fR command |
| 692 | if you always refer to the namespace variable using an |
| 693 | appropriate qualified name. |
| 694 | .SH "IMPORTING COMMANDS" |
| 695 | .PP |
| 696 | Namespaces are often used to represent libraries. |
| 697 | Some library commands are used so frequently |
| 698 | that it is a nuisance to type their qualified names. |
| 699 | For example, suppose that all of the commands in a package |
| 700 | like BLT are contained in a namespace called \fBBlt\fR. |
| 701 | Then you might access these commands like this: |
| 702 | .CS |
| 703 | Blt::graph .g \-background red |
| 704 | Blt::table . .g 0,0 |
| 705 | .CE |
| 706 | If you use the \fBgraph\fR and \fBtable\fR commands frequently, |
| 707 | you may want to access them without the \fBBlt::\fR prefix. |
| 708 | You can do this by importing the commands into the current namespace, |
| 709 | like this: |
| 710 | .CS |
| 711 | \fBnamespace import\fR Blt::* |
| 712 | .CE |
| 713 | This adds all exported commands from the \fBBlt\fR namespace |
| 714 | into the current namespace context, so you can write code like this: |
| 715 | .CS |
| 716 | graph .g \-background red |
| 717 | table . .g 0,0 |
| 718 | .CE |
| 719 | The \fBnamespace import\fR command only imports commands |
| 720 | from a namespace that that namespace exported |
| 721 | with a \fBnamespace export\fR command. |
| 722 | .PP |
| 723 | Importing \fIevery\fR command from a namespace is generally |
| 724 | a bad idea since you don't know what you will get. |
| 725 | It is better to import just the specific commands you need. |
| 726 | For example, the command |
| 727 | .CS |
| 728 | \fBnamespace import\fR Blt::graph Blt::table |
| 729 | .CE |
| 730 | imports only the \fBgraph\fR and \fBtable\fR commands into the |
| 731 | current context. |
| 732 | .PP |
| 733 | If you try to import a command that already exists, you will get an |
| 734 | error. This prevents you from importing the same command from two |
| 735 | different packages. But from time to time (perhaps when debugging), |
| 736 | you may want to get around this restriction. You may want to |
| 737 | reissue the \fBnamespace import\fR command to pick up new commands |
| 738 | that have appeared in a namespace. In that case, you can use the |
| 739 | \fB\-force\fR option, and existing commands will be silently overwritten: |
| 740 | .CS |
| 741 | \fBnamespace import\fR \-force Blt::graph Blt::table |
| 742 | .CE |
| 743 | If for some reason, you want to stop using the imported commands, |
| 744 | you can remove them with a \fBnamespace forget\fR command, like this: |
| 745 | .CS |
| 746 | \fBnamespace forget\fR Blt::* |
| 747 | .CE |
| 748 | This searches the current namespace for any commands imported from \fBBlt\fR. |
| 749 | If it finds any, it removes them. Otherwise, it does nothing. |
| 750 | After this, the \fBBlt\fR commands must be accessed with the \fBBlt::\fR |
| 751 | prefix. |
| 752 | .PP |
| 753 | When you delete a command from the exporting namespace like this: |
| 754 | .CS |
| 755 | rename Blt::graph "" |
| 756 | .CE |
| 757 | the command is automatically removed from all namespaces that import it. |
| 758 | .SH "EXPORTING COMMANDS" |
| 759 | You can export commands from a namespace like this: |
| 760 | .CS |
| 761 | \fBnamespace eval\fR Counter { |
| 762 | \fBnamespace export\fR bump reset |
| 763 | variable Num 0 |
| 764 | variable Max 100 |
| 765 | |
| 766 | proc bump {{by 1}} { |
| 767 | variable Num |
| 768 | incr Num $by |
| 769 | Check |
| 770 | return $Num |
| 771 | } |
| 772 | proc reset {} { |
| 773 | variable Num |
| 774 | set Num 0 |
| 775 | } |
| 776 | proc Check {} { |
| 777 | variable Num |
| 778 | variable Max |
| 779 | if {$Num > $Max} { |
| 780 | error "too high!" |
| 781 | } |
| 782 | } |
| 783 | } |
| 784 | .CE |
| 785 | The procedures \fBbump\fR and \fBreset\fR are exported, |
| 786 | so they are included when you import from the \fBCounter\fR namespace, |
| 787 | like this: |
| 788 | .CS |
| 789 | \fBnamespace import\fR Counter::* |
| 790 | .CE |
| 791 | However, the \fBCheck\fR procedure is not exported, |
| 792 | so it is ignored by the import operation. |
| 793 | .PP |
| 794 | The \fBnamespace import\fR command only imports commands |
| 795 | that were declared as exported by their namespace. |
| 796 | The \fBnamespace export\fR command specifies what commands |
| 797 | may be imported by other namespaces. |
| 798 | If a \fBnamespace import\fR command specifies a command |
| 799 | that is not exported, the command is not imported. |
| 800 | .SH "SCOPED SCRIPTS" |
| 801 | The \fBnamespace code\fR command is the means by which a script may be |
| 802 | packaged for evaluation in a namespace other than the one in which it |
| 803 | was created. It is used most often to create event handlers, Tk bindings, |
| 804 | and traces for evaluation in the global context. For instance, the following |
| 805 | code indicates how to direct a variable trace callback into the current |
| 806 | namespace: |
| 807 | .CS |
| 808 | \fBnamespace eval\fR a { |
| 809 | variable b |
| 810 | proc theTraceCallback { n1 n2 op } { |
| 811 | upvar 1 $n1 var |
| 812 | puts "the value of $n1 has changed to $var" |
| 813 | return |
| 814 | } |
| 815 | trace variable b w [\fBnamespace code\fR theTraceCallback] |
| 816 | } |
| 817 | set a::b c |
| 818 | .CE |
| 819 | When executed, it prints the message: |
| 820 | .CS |
| 821 | the value of a::b has changed to c |
| 822 | .CE |
| 823 | .SH EXAMPLES |
| 824 | Create a namespace containing a variable and an exported command: |
| 825 | .CS |
| 826 | \fBnamespace eval\fR foo { |
| 827 | variable bar 0 |
| 828 | proc grill {} { |
| 829 | variable bar |
| 830 | puts "called [incr bar] times" |
| 831 | } |
| 832 | \fBnamespace export\fR grill |
| 833 | } |
| 834 | .CE |
| 835 | .PP |
| 836 | Call the command defined in the previous example in various ways. |
| 837 | .CS |
| 838 | # Direct call |
| 839 | foo::grill |
| 840 | |
| 841 | # Import into current namespace, then call local alias |
| 842 | namespace import foo::grill |
| 843 | grill |
| 844 | .CE |
| 845 | .PP |
| 846 | Look up where the command imported in the previous example came from: |
| 847 | .CS |
| 848 | puts "grill came from [\fBnamespace origin\fR grill]" |
| 849 | .CE |
| 850 | |
| 851 | .SH "SEE ALSO" |
| 852 | variable(n) |
| 853 | |
| 854 | .SH KEYWORDS |
| 855 | exported, internal, variable |