Commit | Line | Data |
---|---|---|
920dae64 AT |
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 |