1namespace(n)                 Tcl Built-In Commands                namespace(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       namespace - create and manipulate contexts for commands and variables
9

SYNOPSIS

11       namespace ?subcommand? ?arg ...?
12_________________________________________________________________
13

DESCRIPTION

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
21       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
33       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
54       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
60       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
70       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
75       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
83              If  namespace  has  leading namespace qualifiers and any leading
84              namespaces do not exist, they are automatically created.
85
86       namespace exists namespace
87              Returns 1 if namespace is  a  valid  namespace  in  the  current
88              context, returns 0 otherwise.
89
90       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
107       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
124       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
153       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
164                     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
170       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
182       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
187       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
195       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
204       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
213       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
222       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
234       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

WHAT IS A NAMESPACE?

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
258                 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
269       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
273       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
296       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

QUALIFIED NAMES

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
312       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
326       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
332       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

NAME RESOLUTION

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
358       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
372                 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
381       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
388       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
394       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
399       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

IMPORTING COMMANDS

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
427       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
433       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
448       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

EXPORTING COMMANDS

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
460                 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
484       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

SCOPED SCRIPTS

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

ENSEMBLES

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
521       Three subcommands of the namespace ensemble command are defined:        │
522
523       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
533       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
539       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
545       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
555   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
560       -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
572       -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
578       -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
588       -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
599       The following extra option is allowed by namespace ensemble create:     │
600
601       -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
608       The following extra option is allowed by namespace ensemble configure:  │
609
610       -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
615   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
622       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
633       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
643       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
655       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

EXAMPLES

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
673       Call the command defined in the previous example in various ways.
674              # Direct call
675              ::foo::grill
676
677              # Use the command resolution path to find the name
678              namespace eval boo {
679                 namespace path ::foo
680                 grill
681              }
682
683              # Import into current namespace, then call local alias
684              namespace import foo::grill
685              grill
686
687              # 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
696       Look up where the command imported in the previous example came from:
697              puts "grill came from [namespace origin grill]"
698
699       Remove all imported commands from the current namespace:
700              namespace forget {*}[namespace import]
701

SEE ALSO

703       interp(n), upvar(n), variable(n)
704

KEYWORDS

706       command, ensemble, exported, internal, variable
707
708
709
710Tcl                                   8.5                         namespace(n)
Impressum