1namespace(n) Tcl Built-In Commands namespace(n)
2______________________________________________________________________________
6
8 namespace - create and manipulate contexts for commands and variables
9
11 namespace ?subcommand? ?arg ...?
12_________________________________________________________________
13
15 The namespace command lets you create, access, and destroy separate
16 contexts for commands and variables. See the section WHAT IS A NAMES‐
17 PACE? below for a brief overview of namespaces. The legal values of
18 subcommand are listed below. Note that you can abbreviate the subcom‐
19 mands.
20 namespace children ?namespace? ?pattern?
22 Returns a list of all child namespaces that belong to the names‐
23 pace namespace. If namespace is not specified, then the chil‐
24 dren are returned for the current namespace. This command
25 returns fully-qualified names, which start with a double colon
26 (::). If the optional pattern is given, then this command
27 returns only the names that match the glob-style pattern. The
28 actual pattern used is determined as follows: a pattern that
29 starts with double colon (::) is used directly, otherwise the
30 namespace namespace (or the fully-qualified name of the current
31 namespace) is prepended onto the pattern.
32 namespace code script
34 Captures the current namespace context for later execution of
35 the script script. It returns a new script in which script has
36 been wrapped in a namespace inscope command. The new script has
37 two important properties. First, it can be evaluated in any
38 namespace and will cause script to be evaluated in the current
39 namespace (the one where the namespace code command was
40 invoked). Second, additional arguments can be appended to the
41 resulting script and they will be passed to script as additional
42 arguments. For example, suppose the command set script [names‐
43 pace code {foo bar}] is invoked in namespace ::a::b. Then eval
44 $script [list x y] can be executed in any namespace (assuming
45 the value of script has been passed in properly) and will have
46 the same effect as the command ::namespace eval ::a::b {foo bar
47 x y}. This command is needed because extensions like Tk nor‐
48 mally execute callback scripts in the global namespace. A
49 scoped command captures a command together with its namespace
50 context in a way that allows it to be executed properly later.
51 See the section SCOPED SCRIPTS for some examples of how this is
52 used to create callback scripts.
53 namespace current
55 Returns the fully-qualified name for the current namespace. The
56 actual name of the global namespace is (i.e., an empty string),
57 but this command returns :: for the global namespace as a
58 convenience to programmers.
59 namespace delete ?namespace namespace ...?
61 Each namespace namespace is deleted and all variables,
62 procedures, and child namespaces contained in the namespace are
63 deleted. If a procedure is currently executing inside the
64 namespace, the namespace will be kept alive until the procedure
65 returns; however, the namespace is marked to prevent other code
66 from looking it up by name. If a namespace does not exist, this
67 command returns an error. If no namespace names are given, this
68 command does nothing.
69 namespace ensemble subcommand ?arg ...?
71 Creates and manipulates a command that is formed out of an │
72 ensemble of subcommands. See the section ENSEMBLES below for │
73 further details.
74 namespace eval namespace arg ?arg ...?
76 Activates a namespace called namespace and evaluates some code
77 in that context. If the namespace does not already exist, it is
78 created. If more than one arg argument is specified, the
79 arguments are concatenated together with a space between each
80 one in the same fashion as the eval command, and the result is
81 evaluated.
82 If namespace has leading namespace qualifiers and any leading
84 namespaces do not exist, they are automatically created.
85 namespace exists namespace
87 Returns 1 if namespace is a valid namespace in the current
88 context, returns 0 otherwise.
89 namespace export ?-clear? ?pattern pattern ...?
91 Specifies which commands are exported from a namespace. The
92 exported commands are those that can be later imported into
93 another namespace using a namespace import command. Both
94 commands defined in a namespace and commands the namespace has
95 previously imported can be exported by a namespace. The
96 commands do not have to be defined at the time the namespace
97 export command is executed. Each pattern may contain glob-style
98 special characters, but it may not include any namespace
99 qualifiers. That is, the pattern can only specify commands in
100 the current (exporting) namespace. Each pattern is appended
101 onto the namespace's list of export patterns. If the -clear
102 flag is given, the namespace's export pattern list is reset to
103 empty before any pattern arguments are appended. If no patterns
104 are given and the -clear flag is not given, this command returns
105 the namespace's current export list.
106 namespace forget ?pattern pattern ...?
108 Removes previously imported commands from a namespace. Each
109 pattern is a simple or qualified name such as x, foo::x or
110 a::b::p*. Qualified names contain double colons (::) and
111 qualify a name with the name of one or more namespaces. Each
112 “qualified pattern” is qualified with the name of an exporting
113 namespace and may have glob-style special characters in the
114 command name at the end of the qualified name. Glob characters
115 may not appear in a namespace name. For each “simple pattern”
116 this command deletes the matching commands of the current
117 namespace that were imported from a different namespace. For
118 “qualified patterns”, this command first finds the matching
119 exported commands. It then checks whether any of those commands
120 were previously imported by the current namespace. If so, this
121 command deletes the corresponding imported commands. In effect,
122 this un-does the action of a namespace import command.
123 namespace import ?-force? ?pattern pattern ...?
125 Imports commands into a namespace, or queries the set of │
126 imported commands in a namespace. When no arguments are │
127 present, namespace import returns the list of commands in the │
128 current namespace that have been imported from other namespaces. │
129 The commands in the returned list are in the format of simple │
130 names, with no namespace qualifiers at all. This format is │
131 suitable for composition with namespace forget (see EXAMPLES │
132 below). When pattern arguments are present, each pattern is a
133 qualified name like foo::x or a::p*. That is, it includes the
134 name of an exporting namespace and may have glob-style special
135 characters in the command name at the end of the qualified name.
136 Glob characters may not appear in a namespace name. All the
137 commands that match a pattern string and which are currently
138 exported from their namespace are added to the current
139 namespace. This is done by creating a new command in the
140 current namespace that points to the exported command in its
141 original namespace; when the new imported command is called, it
142 invokes the exported command. This command normally returns an
143 error if an imported command conflicts with an existing command.
144 However, if the -force option is given, imported commands will
145 silently replace existing commands. The namespace import
146 command has snapshot semantics: that is, only requested commands
147 that are currently defined in the exporting namespace are
148 imported. In other words, you can import only the commands that
149 are in a namespace at the time when the namespace import command
150 is executed. If another command is defined and exported in this
151 namespace later on, it will not be imported.
152 namespace inscope namespace script ?arg ...?
154 Executes a script in the context of the specified namespace.
155 This command is not expected to be used directly by programmers;
156 calls to it are generated implicitly when applications use
157 namespace code commands to create callback scripts that the
158 applications then register with, e.g., Tk widgets. The
159 namespace inscope command is much like the namespace eval
160 command except that the namespace must already exist, and
161 namespace inscope appends additional args as proper list
162 elements.
163 namespace inscope ::foo $script $x $y $z
165 is equivalent to
166 namespace eval ::foo [concat $script [list $x $y $z]]
167 thus additional arguments will not undergo a second round of
168 substitution, as is the case with namespace eval.
169 namespace origin command
171 Returns the fully-qualified name of the original command to
172 which the imported command command refers. When a command is
173 imported into a namespace, a new command is created in that
174 namespace that points to the actual command in the exporting
175 namespace. If a command is imported into a sequence of
176 namespaces a, b,...,n where each successive namespace just
177 imports the command from the previous namespace, this command
178 returns the fully-qualified name of the original command in the
179 first namespace, a. If command does not refer to an imported
180 command, the command's own fully-qualified name is returned.
181 namespace parent ?namespace?
183 Returns the fully-qualified name of the parent namespace for
184 namespace namespace. If namespace is not specified, the fully-
185 qualified name of the current namespace's parent is returned.
186 namespace path ?namespaceList?
188 Returns the command resolution path of the current namespace. If │
189 namespaceList is specified as a list of named namespaces, the │
190 current namespace's command resolution path is set to those │
191 namespaces and returns the empty list. The default command │
192 resolution path is always empty. See the section NAME RESOLUTION │
193 below for an explanation of the rules regarding name resolution.
194 namespace qualifiers string
196 Returns any leading namespace qualifiers for string. Qualifiers
197 are namespace names separated by double colons (::). For the
198 string ::foo::bar::x, this command returns ::foo::bar, and for
199 :: it returns an empty string. This command is the complement
200 of the namespace tail command. Note that it does not check
201 whether the namespace names are, in fact, the names of currently
202 defined namespaces.
203 namespace tail string
205 Returns the simple name at the end of a qualified string.
206 Qualifiers are namespace names separated by double colons (::).
207 For the string ::foo::bar::x, this command returns x, and for ::
208 it returns an empty string. This command is the complement of
209 the namespace qualifiers command. It does not check whether the
210 namespace names are, in fact, the names of currently defined
211 namespaces.
212 namespace upvar namespace otherVar myVar ?otherVar myVar ...
214 This command arranges for one or more local variables in the
215 current procedure to refer to variables in namespace. The
216 namespace name is resolved as described in section NAME
217 RESOLUTION. The command namespace upvar $ns a b has the same
218 behaviour as upvar 0 ${ns}::a b, with the sole exception of the
219 resolution rules used for qualified namespace or variable names.
220 namespace upvar returns an empty string.
221 namespace unknown ?script?
223 Sets or returns the unknown command handler for the current
224 namespace. The handler is invoked when a command called from
225 within the namespace cannot be found (in either the current
226 namespace or the global namespace). The script argument, if
227 given, should be a well formed list representing a command name
228 and optional arguments. When the handler is invoked, the full
229 invocation line will be appended to the script and the result
230 evaluated in the context of the namespace. The default handler
231 for all namespaces is ::unknown. If no argument is given, it
232 returns the handler for the current namespace.
233 namespace which ?-command? ?-variable? name
235 Looks up name as either a command or variable and returns its
236 fully-qualified name. For example, if name does not exist in
237 the current namespace but does exist in the global namespace,
238 this command returns a fully-qualified name in the global
239 namespace. If the command or variable does not exist, this
240 command returns an empty string. If the variable has been
241 created but not defined, such as with the variable command or
242 through a trace on the variable, this command will return the
243 fully-qualified name of the variable. If no flag is given, name
244 is treated as a command name. See the section NAME RESOLUTION
245 below for an explanation of the rules regarding name resolution.
246
248 A namespace is a collection of commands and variables. It encapsulates
249 the commands and variables to ensure that they will not interfere with
250 the commands and variables of other namespaces. Tcl has always had one
251 such collection, which we refer to as the global namespace. The global
252 namespace holds all global variables and commands. The namespace eval
253 command lets you create new namespaces. For example,
254 namespace eval Counter {
255 namespace export bump
256 variable num 0
257 proc bump {} {
259 variable num
260 incr num
261 }
262 }
263 creates a new namespace containing the variable num and the procedure
264 bump. The commands and variables in this namespace are separate from
265 other commands and variables in the same program. If there is a
266 command named bump in the global namespace, for example, it will be
267 different from the command bump in the Counter namespace.
268 Namespace variables resemble global variables in Tcl. They exist
270 outside of the procedures in a namespace but can be accessed in a
271 procedure via the variable command, as shown in the example above.
272 Namespaces are dynamic. You can add and delete commands and variables
274 at any time, so you can build up the contents of a namespace over time
275 using a series of namespace eval commands. For example, the following
276 series of commands has the same effect as the namespace definition
277 shown above:
278 namespace eval Counter {
279 variable num 0
280 proc bump {} {
281 variable num
282 return [incr num]
283 }
284 }
285 namespace eval Counter {
286 proc test {args} {
287 return $args
288 }
289 }
290 namespace eval Counter {
291 rename test ""
292 }
293 Note that the test procedure is added to the Counter namespace, and
294 later removed via the rename command.
295 Namespaces can have other namespaces within them, so they nest
297 hierarchically. A nested namespace is encapsulated inside its parent
298 namespace and can not interfere with other namespaces.
299
301 Each namespace has a textual name such as history or ::safe::interp.
302 Since namespaces may nest, qualified names are used to refer to
303 commands, variables, and child namespaces contained inside namespaces.
304 Qualified names are similar to the hierarchical path names for Unix
305 files or Tk widgets, except that :: is used as the separator instead of
306 / or .. The topmost or global namespace has the name (i.e., an empty
307 string), although :: is a synonym. As an example, the name
308 ::safe::interp::create refers to the command create in the namespace
309 interp that is a child of namespace ::safe, which in turn is a child of
310 the global namespace, ::.
311 If you want to access commands and variables from another namespace,
313 you must use some extra syntax. Names must be qualified by the
314 namespace that contains them. From the global namespace, we might
315 access the Counter procedures like this:
316 Counter::bump 5
317 Counter::Reset
318 We could access the current count like this:
319 puts "count = $Counter::num"
320 When one namespace contains another, you may need more than one
321 qualifier to reach its elements. If we had a namespace Foo that
322 contained the namespace Counter, you could invoke its bump procedure
323 from the global namespace like this:
324 Foo::Counter::bump 3
325 You can also use qualified names when you create and rename commands.
327 For example, you could add a procedure to the Foo namespace like this:
328 proc Foo::Test {args} {return $args}
329 And you could move the same procedure to another namespace like this:
330 rename Foo::Test Bar::Test
331 There are a few remaining points about qualified names that we should
333 cover. Namespaces have nonempty names except for the global namespace.
334 :: is disallowed in simple command, variable, and namespace names
335 except as a namespace separator. Extra colons in any separator part of
336 a qualified name are ignored; i.e. two or more colons are treated as a
337 namespace separator. A trailing :: in a qualified variable or command
338 name refers to the variable or command named {}. However, a trailing
339 :: in a qualified namespace name is ignored.
340
342 In general, all Tcl commands that take variable and command names
343 support qualified names. This means you can give qualified names to
344 such commands as set, proc, rename, and interp alias. If you provide a
345 fully-qualified name that starts with a ::, there is no question about
346 what command, variable, or namespace you mean. However, if the name
347 does not start with a :: (i.e., is relative), Tcl follows basic rules
348 for looking it up: Variable names are always resolved by looking first
349 in the current namespace, and then in the global namespace. Command │
350 names are also always resolved by looking in the current namespace │
351 first. If not found there, they are searched for in every namespace on │
352 the current namespace's command path (which is empty by default). If │
353 not found there, command names are looked up in the global namespace │
354 (or, failing that, are processed by the unknown command.) Namespace
355 names, on the other hand, are always resolved by looking in only the
356 current namespace.
357 In the following example,
359 set traceLevel 0
360 namespace eval Debug {
361 printTrace $traceLevel
362 }
363 Tcl looks for traceLevel in the namespace Debug and then in the global
364 namespace. It looks up the command printTrace in the same way. If a
365 variable or command name is not found in either context, the name is
366 undefined. To make this point absolutely clear, consider the following
367 example:
368 set traceLevel 0
369 namespace eval Foo {
370 variable traceLevel 3
371 namespace eval Debug {
373 printTrace $traceLevel
374 }
375 }
376 Here Tcl looks for traceLevel first in the namespace Foo::Debug. Since
377 it is not found there, Tcl then looks for it in the global namespace.
378 The variable Foo::traceLevel is completely ignored during the name
379 resolution process.
380 You can use the namespace which command to clear up any question about
382 name resolution. For example, the command:
383 namespace eval Foo::Debug {namespace which -variable traceLevel}
384 returns ::traceLevel. On the other hand, the command,
385 namespace eval Foo {namespace which -variable traceLevel}
386 returns ::Foo::traceLevel.
387 As mentioned above, namespace names are looked up differently than the
389 names of variables and commands. Namespace names are always resolved
390 in the current namespace. This means, for example, that a namespace
391 eval command that creates a new namespace always creates a child of the
392 current namespace unless the new namespace name begins with ::.
393 Tcl has no access control to limit what variables, commands, or
395 namespaces you can reference. If you provide a qualified name that
396 resolves to an element by the name resolution rule above, you can
397 access the element.
398 You can access a namespace variable from a procedure in the same
400 namespace by using the variable command. Much like the global command,
401 this creates a local link to the namespace variable. If necessary, it
402 also creates the variable in the current namespace and initializes it.
403 Note that the global command only creates links to variables in the
404 global namespace. It is not necessary to use a variable command if you
405 always refer to the namespace variable using an appropriate qualified
406 name.
407
409 Namespaces are often used to represent libraries. Some library
410 commands are used so frequently that it is a nuisance to type their
411 qualified names. For example, suppose that all of the commands in a
412 package like BLT are contained in a namespace called Blt. Then you
413 might access these commands like this:
414 Blt::graph .g -background red
415 Blt::table . .g 0,0
416 If you use the graph and table commands frequently, you may want to
417 access them without the Blt:: prefix. You can do this by importing the
418 commands into the current namespace, like this:
419 namespace import Blt::*
420 This adds all exported commands from the Blt namespace into the current
421 namespace context, so you can write code like this:
422 graph .g -background red
423 table . .g 0,0
424 The namespace import command only imports commands from a namespace
425 that that namespace exported with a namespace export command.
426 Importing every command from a namespace is generally a bad idea since
428 you do not know what you will get. It is better to import just the
429 specific commands you need. For example, the command
430 namespace import Blt::graph Blt::table
431 imports only the graph and table commands into the current context.
432 If you try to import a command that already exists, you will get an
434 error. This prevents you from importing the same command from two
435 different packages. But from time to time (perhaps when debugging),
436 you may want to get around this restriction. You may want to reissue
437 the namespace import command to pick up new commands that have appeared
438 in a namespace. In that case, you can use the -force option, and
439 existing commands will be silently overwritten:
440 namespace import -force Blt::graph Blt::table
441 If for some reason, you want to stop using the imported commands, you
442 can remove them with a namespace forget command, like this:
443 namespace forget Blt::*
444 This searches the current namespace for any commands imported from Blt.
445 If it finds any, it removes them. Otherwise, it does nothing. After
446 this, the Blt commands must be accessed with the Blt:: prefix.
447 When you delete a command from the exporting namespace like this:
449 rename Blt::graph ""
450 the command is automatically removed from all namespaces that import
451 it.
452
454 You can export commands from a namespace like this:
455 namespace eval Counter {
456 namespace export bump reset
457 variable Num 0
458 variable Max 100
459 proc bump {{by 1}} {
461 variable Num
462 incr Num $by
463 Check
464 return $Num
465 }
466 proc reset {} {
467 variable Num
468 set Num 0
469 }
470 proc Check {} {
471 variable Num
472 variable Max
473 if {$Num > $Max} {
474 error "too high!"
475 }
476 }
477 }
478 The procedures bump and reset are exported, so they are included when
479 you import from the Counter namespace, like this:
480 namespace import Counter::*
481 However, the Check procedure is not exported, so it is ignored by the
482 import operation.
483 The namespace import command only imports commands that were declared
485 as exported by their namespace. The namespace export command specifies
486 what commands may be imported by other namespaces. If a namespace
487 import command specifies a command that is not exported, the command is
488 not imported.
489
491 The namespace code command is the means by which a script may be
492 packaged for evaluation in a namespace other than the one in which it
493 was created. It is used most often to create event handlers, Tk
494 bindings, and traces for evaluation in the global context. For
495 instance, the following code indicates how to direct a variable trace
496 callback into the current namespace:
497 namespace eval a {
499 variable b
500 proc theTraceCallback { n1 n2 op } {
501 upvar 1 $n1 var
502 puts "the value of $n1 has changed to $var"
503 return
504 }
505 trace add variable b write [namespace code theTraceCallback]
506 }
507 set a::b c
508 When executed, it prints the message:
510 the value of a::b has changed to c
512
514 The namespace ensemble is used to create and manipulate ensemble │
515 commands, which are commands formed by grouping subcommands together. │
516 The commands typically come from the current namespace when the │
517 ensemble was created, though this is configurable. Note that there may │
518 be any number of ensembles associated with any namespace (including │
519 none, which is true of all namespaces by default), though all the │
520 ensembles associated with a namespace are deleted when that namespace │
521 is deleted. The link between an ensemble command and its namespace is │
522 maintained however the ensemble is renamed. │
523 Three subcommands of the namespace ensemble command are defined: │
525 namespace ensemble create ?option value ...? │
527 Creates a new ensemble command linked to the current namespace, │
528 returning the fully qualified name of the command created. The │
529 arguments to namespace ensemble create allow the configuration │
530 of the command as if with the namespace ensemble configure │
531 command. If not overridden with the -command option, this │
532 command creates an ensemble with exactly the same name as the │
533 linked namespace. See the section ENSEMBLE OPTIONS below for a │
534 full list of options supported and their effects. │
535 namespace ensemble configure command ?option? ?value ...? │
537 Retrieves the value of an option associated with the ensemble │
538 command named command, or updates some options associated with │
539 that ensemble command. See the section ENSEMBLE OPTIONS below │
540 for a full list of options supported and their effects. │
541 namespace ensemble exists command │
543 Returns a boolean value that describes whether the command │
544 command exists and is an ensemble command. This command only │
545 ever returns an error if the number of arguments to the command │
546 is wrong. │
547 When called, an ensemble command takes its first argument and looks it │
549 up (according to the rules described below) to discover a list of words │
550 to replace the ensemble command and subcommand with. The resulting │
551 list of words is then evaluated (with no further substitutions) as if │
552 that was what was typed originally (i.e. by passing the list of words │
553 through Tcl_EvalObjv) and returning the result of the command. Note │
554 that it is legal to make the target of an ensemble rewrite be another │
555 (or even the same) ensemble command. The ensemble command will not be │
556 visible through the use of the uplevel or info level commands. │
557 ENSEMBLE OPTIONS │
559 The following options, supported by the namespace ensemble create and │
560 namespace ensemble configure commands, control how an ensemble command │
561 behaves: │
562 -map │
564 When non-empty, this option supplies a dictionary that provides │
565 a mapping from subcommand names to a list of prefix words to │
566 substitute in place of the ensemble command and subcommand words │
567 (in a manner similar to an alias created with interp alias; the │
568 words are not reparsed after substitution); if the first word of │
569 any target is not fully qualified when set, it is assumed to be │
570 relative to the current namespace and changed to be exactly that │
571 (that is, it is always fully qualified when read). When this │
572 option is empty, the mapping will be from the local name of the │
573 subcommand to its fully-qualified name. Note that when this │
574 option is non-empty and the -subcommands option is empty, the │
575 ensemble subcommand names will be exactly those words that have │
576 mappings in the dictionary. │
577 -prefixes │
579 This option (which is enabled by default) controls whether the │
580 ensemble command recognizes unambiguous prefixes of its │
581 subcommands. When turned off, the ensemble command requires │
582 exact matching of subcommand names. │
583 -subcommands │
585 When non-empty, this option lists exactly what subcommands are │
586 in the ensemble. The mapping for each of those commands will be │
587 either whatever is defined in the -map option, or to the command │
588 with the same name in the namespace linked to the ensemble. If │
589 this option is empty, the subcommands of the namespace will │
590 either be the keys of the dictionary listed in the -map option │
591 or the exported commands of the linked namespace at the time of │
592 the invocation of the ensemble command. │
593 -unknown │
595 When non-empty, this option provides a partial command (to which │
596 all the words that are arguments to the ensemble command, │
597 including the fully-qualified name of the ensemble, are │
598 appended) to handle the case where an ensemble subcommand is not │
599 recognized and would otherwise generate an error. When empty │
600 (the default) an error (in the style of Tcl_GetIndexFromObj) is │
601 generated whenever the ensemble is unable to determine how to │
602 implement a particular subcommand. See UNKNOWN HANDLER │
603 BEHAVIOUR for more details. │
604 The following extra option is allowed by namespace ensemble create: │
606 -command │
608 This write-only option allows the name of the ensemble created │
609 by namespace ensemble create to be anything in any existing │
610 namespace. The default value for this option is the fully- │
611 qualified name of the namespace in which the namespace ensemble │
612 create command is invoked. │
613 The following extra option is allowed by namespace ensemble configure: │
615 -namespace │
617 This read-only option allows the retrieval of the fully- │
618 qualified name of the namespace which the ensemble was created │
619 within. │
620 UNKNOWN HANDLER BEHAVIOUR │
622 If an unknown handler is specified for an ensemble, that handler is │
623 called when the ensemble command would otherwise return an error due to │
624 it being unable to decide which subcommand to invoke. The exact │
625 conditions under which that occurs are controlled by the -subcommands, │
626 -map and -prefixes options as described above. │
627 To execute the unknown handler, the ensemble mechanism takes the │
629 specified -unknown option and appends each argument of the attempted │
630 ensemble command invocation (including the ensemble command itself, │
631 expressed as a fully qualified name). It invokes the resulting command │
632 in the scope of the attempted call. If the execution of the unknown │
633 handler terminates normally, the ensemble engine reparses the │
634 subcommand (as described below) and tries to dispatch it again, which │
635 is ideal for when the ensemble's configuration has been updated by the │
636 unknown subcommand handler. Any other kind of termination of the │
637 unknown handler is treated as an error. │
638 The result of the unknown handler is expected to be a list (it is an │
640 error if it is not). If the list is an empty list, the ensemble command │
641 attempts to look up the original subcommand again and, if it is not │
642 found this time, an error will be generated just as if the -unknown │
643 handler was not there (i.e. for any particular invocation of an │
644 ensemble, its unknown handler will be called at most once.) This makes │
645 it easy for the unknown handler to update the ensemble or its backing │
646 namespace so as to provide an implementation of the desired subcommand │
647 and reparse. │
648 When the result is a non-empty list, the words of that list are used to │
650 replace the ensemble command and subcommand, just as if they had been │
651 looked up in the -map. It is up to the unknown handler to supply all │
652 namespace qualifiers if the implementing subcommand is not in the │
653 namespace of the caller of the ensemble command. Also note that when │
654 ensemble commands are chained (e.g. if you make one of the commands │
655 that implement an ensemble subcommand into an ensemble, in a manner │
656 similar to the text widget's tag and mark subcommands) then the rewrite │
657 happens in the context of the caller of the outermost ensemble. That is │
658 to say that ensembles do not in themselves place any namespace contexts │
659 on the Tcl call stack. │
660 Where an empty -unknown handler is given (the default), the ensemble │
662 command will generate an error message based on the list of commands │
663 that the ensemble has defined (formatted similarly to the error message │
664 from Tcl_GetIndexFromObj). This is the error that will be thrown when │
665 the subcommand is still not recognized during reparsing. It is also an │
666 error for an -unknown handler to delete its namespace.
667
669 Create a namespace containing a variable and an exported command:
670 namespace eval foo {
671 variable bar 0
672 proc grill {} {
673 variable bar
674 puts "called [incr bar] times"
675 }
676 namespace export grill
677 }
678 Call the command defined in the previous example in various ways.
680 # Direct call
681 ::foo::grill
682 # Use the command resolution path to find the name
684 namespace eval boo {
685 namespace path ::foo
686 grill
687 }
688 # Import into current namespace, then call local alias
690 namespace import foo::grill
691 grill
692 # Create two ensembles, one with the default name and one with a
694 # specified name. Then call through the ensembles.
695 namespace eval foo {
696 namespace ensemble create
697 namespace ensemble create -command ::foobar
698 }
699 foo grill
700 foobar grill
701 Look up where the command imported in the previous example came from:
703 puts "grill came from [namespace origin grill]"
704 Remove all imported commands from the current namespace:
706 namespace forget {*}[namespace import]
707
709 interp(n), upvar(n), variable(n)
710
712 command, ensemble, exported, internal, variable
713Tcl 8.5 namespace(n)