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 {
498 variable b
499 proc theTraceCallback { n1 n2 op } {
500 upvar 1 $n1 var
501 puts "the value of $n1 has changed to $var"
502 return
503 }
504 trace variable b w [namespace code theTraceCallback]
505 }
506 set a::b c
507 When executed, it prints the message:
508 the value of a::b has changed to c
509
511 The namespace ensemble is used to create and manipulate ensemble │
512 commands, which are commands formed by grouping subcommands together. │
513 The commands typically come from the current namespace when the │
514 ensemble was created, though this is configurable. Note that there may │
515 be any number of ensembles associated with any namespace (including │
516 none, which is true of all namespaces by default), though all the │
517 ensembles associated with a namespace are deleted when that namespace │
518 is deleted. The link between an ensemble command and its namespace is │
519 maintained however the ensemble is renamed. │
520 Three subcommands of the namespace ensemble command are defined: │
522 namespace ensemble create ?option value ...? │
524 Creates a new ensemble command linked to the current namespace, │
525 returning the fully qualified name of the command created. The │
526 arguments to namespace ensemble create allow the configuration │
527 of the command as if with the namespace ensemble configure │
528 command. If not overridden with the -command option, this │
529 command creates an ensemble with exactly the same name as the │
530 linked namespace. See the section ENSEMBLE OPTIONS below for a │
531 full list of options supported and their effects. │
532 namespace ensemble configure command ?option? ?value ...? │
534 Retrieves the value of an option associated with the ensemble │
535 command named command, or updates some options associated with │
536 that ensemble command. See the section ENSEMBLE OPTIONS below │
537 for a full list of options supported and their effects. │
538 namespace ensemble exists command │
540 Returns a boolean value that describes whether the command │
541 command exists and is an ensemble command. This command only │
542 ever returns an error if the number of arguments to the command │
543 is wrong. │
544 When called, an ensemble command takes its first argument and looks it │
546 up (according to the rules described below) to discover a list of words │
547 to replace the ensemble command and subcommand with. The resulting │
548 list of words is then evaluated (with no further substitutions) as if │
549 that was what was typed originally (i.e. by passing the list of words │
550 through Tcl_EvalObjv) and returning the result of the command. Note │
551 that it is legal to make the target of an ensemble rewrite be another │
552 (or even the same) ensemble command. The ensemble command will not be │
553 visible through the use of the uplevel or info level commands. │
554 ENSEMBLE OPTIONS │
556 The following options, supported by the namespace ensemble create and │
557 namespace ensemble configure commands, control how an ensemble command │
558 behaves: │
559 -map │
561 When non-empty, this option supplies a dictionary that provides │
562 a mapping from subcommand names to a list of prefix words to │
563 substitute in place of the ensemble command and subcommand words │
564 (in a manner similar to an alias created with interp alias; the │
565 words are not reparsed after substitution). When this option is │
566 empty, the mapping will be from the local name of the subcommand │
567 to its fully-qualified name. Note that when this option is non- │
568 empty and the -subcommands option is empty, the ensemble │
569 subcommand names will be exactly those words that have mappings │
570 in the dictionary. │
571 -prefixes │
573 This option (which is enabled by default) controls whether the │
574 ensemble command recognizes unambiguous prefixes of its │
575 subcommands. When turned off, the ensemble command requires │
576 exact matching of subcommand names. │
577 -subcommands │
579 When non-empty, this option lists exactly what subcommands are │
580 in the ensemble. The mapping for each of those commands will be │
581 either whatever is defined in the -map option, or to the command │
582 with the same name in the namespace linked to the ensemble. If │
583 this option is empty, the subcommands of the namespace will │
584 either be the keys of the dictionary listed in the -map option │
585 or the exported commands of the linked namespace at the time of │
586 the invocation of the ensemble command. │
587 -unknown │
589 When non-empty, this option provides a partial command (to which │
590 all the words that are arguments to the ensemble command, │
591 including the fully-qualified name of the ensemble, are │
592 appended) to handle the case where an ensemble subcommand is not │
593 recognized and would otherwise generate an error. When empty │
594 (the default) an error (in the style of Tcl_GetIndexFromObj) is │
595 generated whenever the ensemble is unable to determine how to │
596 implement a particular subcommand. See UNKNOWN HANDLER │
597 BEHAVIOUR for more details. │
598 The following extra option is allowed by namespace ensemble create: │
600 -command │
602 This write-only option allows the name of the ensemble created │
603 by namespace ensemble create to be anything in any existing │
604 namespace. The default value for this option is the fully- │
605 qualified name of the namespace in which the namespace ensemble │
606 create command is invoked. │
607 The following extra option is allowed by namespace ensemble configure: │
609 -namespace │
611 This read-only option allows the retrieval of the fully- │
612 qualified name of the namespace which the ensemble was created │
613 within. │
614 UNKNOWN HANDLER BEHAVIOUR │
616 If an unknown handler is specified for an ensemble, that handler is │
617 called when the ensemble command would otherwise return an error due to │
618 it being unable to decide which subcommand to invoke. The exact │
619 conditions under which that occurs are controlled by the -subcommands, │
620 -map and -prefixes options as described above. │
621 To execute the unknown handler, the ensemble mechanism takes the │
623 specified -unknown option and appends each argument of the attempted │
624 ensemble command invocation (including the ensemble command itself, │
625 expressed as a fully qualified name). It invokes the resulting command │
626 in the scope of the attempted call. If the execution of the unknown │
627 handler terminates normally, the ensemble engine reparses the │
628 subcommand (as described below) and tries to dispatch it again, which │
629 is ideal for when the ensemble's configuration has been updated by the │
630 unknown subcommand handler. Any other kind of termination of the │
631 unknown handler is treated as an error. │
632 The result of the unknown handler is expected to be a list (it is an │
634 error if it is not). If the list is an empty list, the ensemble command │
635 attempts to look up the original subcommand again and, if it is not │
636 found this time, an error will be generated just as if the -unknown │
637 handler was not there (i.e. for any particular invocation of an │
638 ensemble, its unknown handler will be called at most once.) This makes │
639 it easy for the unknown handler to update the ensemble or its backing │
640 namespace so as to provide an implementation of the desired subcommand │
641 and reparse. │
642 When the result is a non-empty list, the words of that list are used to │
644 replace the ensemble command and subcommand, just as if they had been │
645 looked up in the -map. It is up to the unknown handler to supply all │
646 namespace qualifiers if the implementing subcommand is not in the │
647 namespace of the caller of the ensemble command. Also note that when │
648 ensemble commands are chained (e.g. if you make one of the commands │
649 that implement an ensemble subcommand into an ensemble, in a manner │
650 similar to the text widget's tag and mark subcommands) then the rewrite │
651 happens in the context of the caller of the outermost ensemble. That is │
652 to say that ensembles do not in themselves place any namespace contexts │
653 on the Tcl call stack. │
654 Where an empty -unknown handler is given (the default), the ensemble │
656 command will generate an error message based on the list of commands │
657 that the ensemble has defined (formatted similarly to the error message │
658 from Tcl_GetIndexFromObj). This is the error that will be thrown when │
659 the subcommand is still not recognized during reparsing. It is also an │
660 error for an -unknown handler to delete its namespace.
661
663 Create a namespace containing a variable and an exported command:
664 namespace eval foo {
665 variable bar 0
666 proc grill {} {
667 variable bar
668 puts "called [incr bar] times"
669 }
670 namespace export grill
671 }
672 Call the command defined in the previous example in various ways.
674 # Direct call
675 ::foo::grill
676 # Use the command resolution path to find the name
678 namespace eval boo {
679 namespace path ::foo
680 grill
681 }
682 # Import into current namespace, then call local alias
684 namespace import foo::grill
685 grill
686 # Create two ensembles, one with the default name and one with a
688 # specified name. Then call through the ensembles.
689 namespace eval foo {
690 namespace ensemble create
691 namespace ensemble create -command ::foobar
692 }
693 foo grill
694 foobar grill
695 Look up where the command imported in the previous example came from:
697 puts "grill came from [namespace origin grill]"
698 Remove all imported commands from the current namespace:
700 namespace forget {*}[namespace import]
701
703 interp(n), upvar(n), variable(n)
704
706 command, ensemble, exported, internal, variable
707Tcl 8.5 namespace(n)