1mNAME0m
       namespace - create and manipulate contexts for commands and variables

1mSYNOPSIS0m
       1mnamespace 22m?4moption24m? ?4marg24m 4m...24m?


1mDESCRIPTION0m
       The  1mnamespace  22mcommand  lets  you create, access, and destroy separate
       contexts for commands and variables.  See the section 1mWHAT IS A  NAMES-0m
       1mPACE?  22mbelow  for  a brief overview of namespaces.  The legal values of
       4moption24m are listed below.  Note that you can abbreviate the 4moption24ms.

       1mnamespace children 22m?4mnamespace24m? ?4mpattern24m?
              Returns a list of all child namespaces that belong to the names-
              pace  4mnamespace24m.   If 4mnamespace24m is not specified, then the chil-
              dren are returned  for  the  current  namespace.   This  command
              returns  fully-qualified  names, which start with a double colon
              (1m::22m).  If the optional  4mpattern24m  is  given,  then  this  command
              returns  only  the names that match the glob-style pattern.  The
              actual pattern used is determined as  follows:  a  pattern  that
              starts  with  double  colon (1m::22m) is used directly, otherwise the
              namespace 4mnamespace24m (or the fully-qualified name of the  current
              namespace) is prepended onto the pattern.

       1mnamespace code 4m22mscript0m
              Captures  the  current  namespace context for later execution of
              the script 4mscript24m.  It returns a new script in which 4mscript24m  has
              been wrapped in a 1mnamespace inscope 22mcommand.  The new script has
              two important properties.  First, it can  be  evaluated  in  any
              namespace  and  will cause 4mscript24m to be evaluated in the current
              namespace  (the  one  where  the  1mnamespace  code  22mcommand   was
              invoked).   Second,  additional arguments can be appended to the
              resulting script and they will be passed to 4mscript24m as additional
              arguments.   For example, suppose the command 1mset script [names-0m
              1mpace code {foo bar}] 22mis invoked in namespace 1m::a::b22m.  Then  1meval0m
              1m"$script  x  y"  22mcan  be executed in any namespace (assuming the
              value of 1mscript 22mhas been passed in properly) and will  have  the
              same  effect  as  the command 1m::namespace eval ::a::b {foo bar x0m
              1my}22m.  This command is needed because extensions like Tk  normally
              execute callback scripts in the global namespace.  A scoped com-
              mand captures a command together with its namespace context in a
              way  that allows it to be executed properly later.  See the sec-
              tion 1mSCOPED SCRIPTS 22mfor some examples of how  this  is  used  to
              create callback scripts.

       1mnamespace current0m
              Returns the fully-qualified name for the current namespace.  The
              actual name of the global namespace  is  ``''  (i.e.,  an  empty
              string), but this command returns 1m:: 22mfor the global namespace as
              a convenience to programmers.

       1mnamespace delete 22m?4mnamespace24m 4mnamespace24m 4m...24m?
              Each namespace 4mnamespace24m is deleted and  all  variables,  proce-
              dures,  and  child  namespaces  contained  in  the namespace are
              deleted.  If a  procedure  is  currently  executing  inside  the
              namespace,  the namespace will be kept alive until the procedure
              returns; however, the namespace is marked to prevent other  code
              from  looking it up by name.  If a namespace doesn't exist, this
              command returns an error.  If no namespace names are given, this
              command does nothing.

       1mnamespace eval 4m22mnamespace24m 4marg24m ?4marg24m 4m...24m?
              Activates  a  namespace called 4mnamespace24m and evaluates some code
              in that context.  If the namespace does not already exist, it is
              created.   If more than one 4marg24m argument is specified, the argu-
              ments are concatenated together with a space between each one in
              the  same  fashion as the 1meval 22mcommand, and the result is evalu-
              ated.

              If 4mnamespace24m has leading namespace qualifiers  and  any  leading
              namespaces do not exist, they are automatically created.

       1mnamespace exists 4m22mnamespace0m
              Returns  1m1 22mif 4mnamespace24m is a valid namespace in the current con-
              text, returns 1m0 22motherwise.

       1mnamespace export 22m?-1mclear22m? ?4mpattern24m 4mpattern24m 4m...24m?
              Specifies which commands are exported  from  a  namespace.   The
              exported  commands  are  those  that  can be later imported into
              another namespace using a 1mnamespace import 22mcommand.   Both  com-
              mands defined in a namespace and commands the namespace has pre-
              viously imported can be exported by a namespace.   The  commands
              do  not have to be defined at the time the 1mnamespace export 22mcom-
              mand is executed.  Each 4mpattern24m may contain  glob-style  special
              characters,  but  it  may  not include any namespace qualifiers.
              That is, the pattern can only specify commands  in  the  current
              (exporting) namespace.  Each 4mpattern24m is appended onto the names-
              pace's list of export patterns.  If the -1mclear  22mflag  is  given,
              the namespace's export pattern list is reset to empty before any
              4mpattern24m arguments are appended.  If no 4mpattern24ms  are  given  and
              the  -1mclear  22mflag  isn't  given, this command returns the names-
              pace's current export list.

       1mnamespace forget 22m?4mpattern24m 4mpattern24m 4m...24m?
              Removes previously imported commands  from  a  namespace.   Each
              4mpattern24m  is  a  simple  or  qualified  name such as 1mx22m, 1mfoo::x 22mor
              1ma::b::p*22m.  Qualified names contain double colons (1m::22m) and  qual-
              ify a name with the name of one or more namespaces.  Each 4mquali-0m
              4mfied24m 4mpattern24m is qualified with the name of an  exporting  names-
              pace  and  may have glob-style special characters in the command
              name at the end of the qualified name.  Glob characters may  not
              appear  in  a namespace name.  For each 4msimple24m 4mpattern24m this com-
              mand deletes the matching commands of the current namespace that
              were  imported  from  a different namespace.  For 4mqualified24m 4mpat-0m
              4mterns24m, this command first finds the matching exported  commands.
              It  then  checks  whether  any of those commands were previously
              imported by the current namespace.  If so, this command  deletes
              the  corresponding  imported  commands.  In effect, this un-does
              the action of a 1mnamespace import 22mcommand.

       1mnamespace import 22m?1m-force22m? ?4mpattern24m 4mpattern24m 4m...24m?
              Imports commands into a namespace.  Each 4mpattern24m is a  qualified
              name  like 1mfoo::x 22mor 1ma::p*22m.  That is, it includes the name of an
              exporting namespace and may have glob-style  special  characters
              in  the  command  name  at  the end of the qualified name.  Glob
              characters may not appear in a namespace name.  All the commands
              that  match  a  4mpattern24m  string and which are currently exported
              from their namespace are added to the current  namespace.   This
              is  done by creating a new command in the current namespace that
              points to the exported command in its original  namespace;  when
              the new imported command is called, it invokes the exported com-
              mand.  This command normally returns an  error  if  an  imported
              command  conflicts  with  an  existing command.  However, if the
              -1mforce 22moption is given, imported commands will silently  replace
              existing  commands.   The  1mnamespace import 22mcommand has snapshot
              semantics: that is, only requested commands that  are  currently
              defined  in  the  exporting  namespace  are  imported.  In other
              words, you can import only the commands that are in a  namespace
              at  the  time when the 1mnamespace import 22mcommand is executed.  If
              another command is defined and exported in this namespace  later
              on, it will not be imported.

       1mnamespace inscope 4m22mnamespace24m 4mscript24m ?4marg24m 4m...24m?
              Executes  a  script  in  the context of the specified 4mnamespace24m.
              This command is not expected to be used directly by programmers;
              calls  to  it  are  generated  implicitly  when applications use
              1mnamespace code 22mcommands to  create  callback  scripts  that  the
              applications  then  register with, e.g., Tk widgets.  The 1mnames-0m
              1mpace inscope 22mcommand is much like  the  1mnamespace  eval  22mcommand
              except  that  the  4mnamespace24m  must  already exist, and 1mnamespace0m
              1minscope 22mappends additional 4marg24ms as proper list elements.
              1mnamespace inscope ::foo $script $x $y $z 22mis equivalent to 1mnames-0m
              1mpace eval ::foo [concat $script [list $x $y $z]] 22mthus additional
              arguments will not undergo a second round of substitution, as is
              the case with 1mnamespace eval22m.

       1mnamespace origin 4m22mcommand0m
              Returns  the  fully-qualified  name  of  the original command to
              which the imported command 4mcommand24m refers.  When  a  command  is
              imported  into  a  namespace,  a  new command is created in that
              namespace that points to the actual  command  in  the  exporting
              namespace.   If  a command is imported into a sequence of names-
              paces 4ma,24m 4mb,...,n24m where each successive  namespace  just  imports
              the  command  from  the previous namespace, this command returns
              the fully-qualified name of the original command  in  the  first
              namespace, 4ma24m.  If 4mcommand24m does not refer to an imported command,
              the command's own fully-qualified name is returned.

       1mnamespace parent 22m?4mnamespace24m?
              Returns the fully-qualified name of  the  parent  namespace  for
              namespace  4mnamespace24m.  If 4mnamespace24m is not specified, the fully-
              qualified name of the current namespace's parent is returned.

       1mnamespace qualifiers 4m22mstring0m
              Returns any leading namespace qualifiers for 4mstring24m.  Qualifiers
              are  namespace  names  separated by double colons (1m::22m).  For the
              4mstring24m 1m::foo::bar::x22m, this command returns 1m::foo::bar22m,  and  for
              1m::  22mit  returns an empty string.  This command is the complement
              of the 1mnamespace tail 22mcommand.  Note  that  it  does  not  check
              whether the namespace names are, in fact, the names of currently
              defined namespaces.

       1mnamespace tail 4m22mstring0m
              Returns the simple name at the end of a qualified string.  Qual-
              ifiers are namespace names separated by double colons (1m::22m).  For
              the 4mstring24m 1m::foo::bar::x22m, this command returns 1mx22m, and for 1m::  22mit
              returns  an empty string.  This command is the complement of the
              1mnamespace qualifiers 22mcommand.  It does  not  check  whether  the
              namespace  names  are,  in  fact, the names of currently defined
              namespaces.

       1mnamespace which 22m?-1mcommand22m? ?-1mvariable22m? 4mname0m
              Looks up 4mname24m as either a command or variable  and  returns  its
              fully-qualified  name.   For  example, if 4mname24m does not exist in
              the current namespace but does exist in  the  global  namespace,
              this command returns a fully-qualified name in the global names-
              pace.  If the command or variable does not exist,  this  command
              returns  an  empty string.  If the variable has been created but
              not defined, such as with the  1mvariable  22mcommand  or  through  a
              1mtrace 22mon the variable, this command will return the fully-quali-
              fied name of the variable.  If no flag is given, 4mname24m is treated
              as a command name.  See the section 1mNAME RESOLUTION 22mbelow for an
              explanation of the rules regarding name resolution.

1mWHAT IS A NAMESPACE?0m
       A namespace is a collection of commands and variables.  It encapsulates
       the commands and variables to ensure that they won't interfere with the
       commands and variables of other namespaces.  Tcl  has  always  had  one
       such collection, which we refer to as the 4mglobal24m 4mnamespace24m.  The global
       namespace holds all global variables and commands.  The 1mnamespace  eval0m
       command lets you create new namespaces.  For example,
              1mnamespace eval 22mCounter {
                 1mnamespace export 22mbump
                 variable num 0

                 proc bump {} {
                    variable num
                    incr num
                 }
              }
       creates  a  new namespace containing the variable 1mnum 22mand the procedure
       1mbump22m.  The commands and variables in this namespace are  separate  from
       other  commands  and variables in the same program.  If there is a com-
       mand named 1mbump 22min the global namespace, for example, it will  be  dif-
       ferent from the command 1mbump 22min the 1mCounter 22mnamespace.

       Namespace  variables resemble global variables in Tcl.  They exist out-
       side of the procedures in a namespace but can be accessed in  a  proce-
       dure via the 1mvariable 22mcommand, as shown in the example above.

       Namespaces  are dynamic.  You can add and delete commands and variables
       at any time, so you can build up the contents of a namespace over  time
       using  a series of 1mnamespace eval 22mcommands.  For example, the following
       series of commands has the same  effect  as  the  namespace  definition
       shown above:
              1mnamespace eval 22mCounter {
                 variable num 0
                 proc bump {} {
                    variable num
                    return [incr num]
                 }
              }
              1mnamespace eval 22mCounter {
                 proc test {args} {
                    return $args
                 }
              }
              1mnamespace eval 22mCounter {
                  rename test ""
              }
       Note  that  the  1mtest  22mprocedure is added to the 1mCounter 22mnamespace, and
       later removed via the 1mrename 22mcommand.

       Namespaces can have other namespaces within them, so they nest  hierar-
       chically.   A nested namespace is encapsulated inside its parent names-
       pace and can not interfere with other namespaces.

1mQUALIFIED NAMES0m
       Each namespace has a textual name such as  1mhistory  22mor  1m::safe::interp22m.
       Since  namespaces  may  nest, qualified names are used to refer to com-
       mands, variables, and child  namespaces  contained  inside  namespaces.
       Qualified  names  are  similar  to the hierarchical path names for Unix
       files or Tk widgets, except that 1m:: 22mis used as the separator instead of
       1m/  22mor  1m.22m.   The topmost or global namespace has the name ``'' (i.e., an
       empty string), although 1m:: 22mis a  synonym.   As  an  example,  the  name
       1m::safe::interp::create  22mrefers  to  the command 1mcreate 22min the namespace
       1minterp 22mthat is a child of namespace 1m::safe22m, which in turn is a child of
       the global namespace, 1m::22m.

       If  you  want  to access commands and variables from another namespace,
       you must use some extra syntax.  Names must be qualified by the  names-
       pace  that  contains  them.  From the global namespace, we might access
       the 1mCounter 22mprocedures like this:
              Counter::bump 5
              Counter::Reset
       We could access the current count like this:
              puts "count = $Counter::num"
       When one namespace contains another, you may need more than one  quali-
       fier  to  reach its elements.  If we had a namespace 1mFoo 22mthat contained
       the namespace 1mCounter22m, you could invoke its  1mbump  22mprocedure  from  the
       global namespace like this:
              Foo::Counter::bump 3

       You  can  also use qualified names when you create and rename commands.
       For example, you could add a procedure to the 1mFoo 22mnamespace like this:
              proc Foo::Test {args} {return $args}
       And you could move the same procedure to another namespace like this:
              rename Foo::Test Bar::Test

       There are a few remaining points about qualified names that  we  should
       cover.  Namespaces have nonempty names except for the global namespace.
       1m:: 22mis disallowed in  simple  command,  variable,  and  namespace  names
       except as a namespace separator.  Extra colons in any separator part of
       a qualified name are ignored; i.e. two or more colons are treated as  a
       namespace  separator.  A trailing 1m:: 22min a qualified variable or command
       name refers to the variable or command named {}.  However,  a  trailing
       1m:: 22min a qualified namespace name is ignored.

1mNAME RESOLUTION0m
       In  general, all Tcl commands that take variable and command names sup-
       port qualified names.  This means you can give qualified names to  such
       commands  as  1mset22m,  1mproc22m,  1mrename22m,  and 1minterp alias22m.  If you provide a
       fully-qualified name that starts with a 1m::22m, there is no question  about
       what  command,  variable,  or namespace you mean.  However, if the name
       does not start with a 1m:: 22m(i.e., is 4mrelative24m), Tcl follows a fixed  rule
       for  looking  it  up: Command and variable names are always resolved by
       looking first in the current namespace, and then in the  global  names-
       pace.  Namespace names, on the other hand, are always resolved by look-
       ing in only the current namespace.

       In the following example,
              set traceLevel 0
              1mnamespace eval 22mDebug {
                 printTrace $traceLevel
              }
       Tcl looks for 1mtraceLevel 22min the namespace 1mDebug 22mand then in the  global
       namespace.   It  looks up the command 1mprintTrace 22min the same way.  If a
       variable or command name is not found in either context,  the  name  is
       undefined.  To make this point absolutely clear, consider the following
       example:
              set traceLevel 0
              1mnamespace eval 22mFoo {
                 variable traceLevel 3

                 1mnamespace eval 22mDebug {
                    printTrace $traceLevel
                 }
              }
       Here Tcl looks for 1mtraceLevel 22mfirst in the namespace 1mFoo::Debug22m.  Since
       it  is  not found there, Tcl then looks for it in the global namespace.
       The variable 1mFoo::traceLevel 22mis completely ignored during the name res-
       olution process.

       You  can use the 1mnamespace which 22mcommand to clear up any question about
       name resolution.  For example, the command:
              1mnamespace eval 22mFoo::Debug {1mnamespace which 22m-variable traceLevel}
       returns 1m::traceLevel22m.  On the other hand, the command,
              1mnamespace eval 22mFoo {1mnamespace which 22m-variable traceLevel}
       returns 1m::Foo::traceLevel22m.

       As mentioned above, namespace names are looked up differently than  the
       names  of  variables and commands.  Namespace names are always resolved
       in the current namespace.  This means, for example,  that  a  1mnamespace0m
       1meval 22mcommand that creates a new namespace always creates a child of the
       current namespace unless the new namespace name begins with 1m::22m.

       Tcl has no access control to limit what variables, commands, or  names-
       paces you can reference.  If you provide a qualified name that resolves
       to an element by the name resolution rule above,  you  can  access  the
       element.

       You can access a namespace variable from a procedure in the same names-
       pace by using the 1mvariable 22mcommand.  Much like the 1mglobal 22mcommand, this
       creates  a local link to the namespace variable.  If necessary, it also
       creates the variable in the current namespace and initializes it.  Note
       that  the  1mglobal 22mcommand only creates links to variables in the global
       namespace.  It is not necessary to use a 1mvariable 22mcommand if you always
       refer to the namespace variable using an appropriate qualified name.

1mIMPORTING COMMANDS0m
       Namespaces  are  often  used to represent libraries.  Some library com-
       mands are used so frequently that it is a nuisance to type their quali-
       fied names.  For example, suppose that all of the commands in a package
       like BLT are contained in a  namespace  called  1mBlt22m.   Then  you  might
       access these commands like this:
              Blt::graph .g -background red
              Blt::table . .g 0,0
       If  you  use  the  1mgraph 22mand 1mtable 22mcommands frequently, you may want to
       access them without the 1mBlt:: 22mprefix.  You can do this by importing the
       commands into the current namespace, like this:
              1mnamespace import 22mBlt::*
       This adds all exported commands from the 1mBlt 22mnamespace into the current
       namespace context, so you can write code like this:
              graph .g -background red
              table . .g 0,0
       The 1mnamespace import 22mcommand only imports  commands  from  a  namespace
       that that namespace exported with a 1mnamespace export 22mcommand.

       Importing  4mevery24m command from a namespace is generally a bad idea since
       you don't know what you will get.  It is better to import just the spe-
       cific commands you need.  For example, the command
              1mnamespace import 22mBlt::graph Blt::table
       imports only the 1mgraph 22mand 1mtable 22mcommands into the current context.

       If  you  try  to  import a command that already exists, you will get an
       error.  This prevents you from importing the same command from two dif-
       ferent  packages.   But from time to time (perhaps when debugging), you
       may want to get around this restriction.  You may want to  reissue  the
       1mnamespace  import 22mcommand to pick up new commands that have appeared in
       a namespace.  In that case, you can use the 1m-force 22moption, and existing
       commands will be silently overwritten:
              1mnamespace import 22m-force Blt::graph Blt::table
       If  for  some reason, you want to stop using the imported commands, you
       can remove them with a 1mnamespace forget 22mcommand, like this:
              1mnamespace forget 22mBlt::*
       This searches the current namespace for any commands imported from 1mBlt22m.
       If  it  finds any, it removes them.  Otherwise, it does nothing.  After
       this, the 1mBlt 22mcommands must be accessed with the 1mBlt:: 22mprefix.

       When you delete a command from the exporting namespace like this:
              rename Blt::graph ""
       the command is automatically removed from all  namespaces  that  import
       it.

1mEXPORTING COMMANDS0m
       You can export commands from a namespace like this:
              1mnamespace eval 22mCounter {
                 1mnamespace export 22mbump reset
                 variable Num 0
                 variable Max 100

                 proc bump {{by 1}} {
                    variable Num
                    incr Num $by
                    Check
                    return $Num
                 }
                 proc reset {} {
                    variable Num
                    set Num 0
                 }
                 proc Check {} {
                    variable Num
                    variable Max
                    if {$Num > $Max} {
                       error "too high!"
                    }
                 }
              }
       The  procedures  1mbump 22mand 1mreset 22mare exported, so they are included when
       you import from the 1mCounter 22mnamespace, like this:
              1mnamespace import 22mCounter::*
       However, the 1mCheck 22mprocedure is not exported, so it is ignored  by  the
       import operation.

       The  1mnamespace  import 22mcommand only imports commands that were declared
       as exported by their namespace.  The 1mnamespace export 22mcommand specifies
       what  commands  may  be  imported  by other namespaces.  If a 1mnamespace0m
       1mimport 22mcommand specifies a command that is not exported, the command is
       not imported.

1mSCOPED SCRIPTS0m
       The  1mnamespace code 22mcommand is the means by which a script may be pack-
       aged for evaluation in a namespace other than the one in which  it  was
       created.   It is used most often to create event handlers, Tk bindings,
       and traces for evaluation in the global  context.   For  instance,  the
       following  code  indicates how to direct a variable trace callback into
       the current namespace:
              1mnamespace eval 22ma {
                 variable b
                 proc theTraceCallback { n1 n2 op } {
                    upvar 1 $n1 var
                    puts "the value of $n1 has changed to $var"
                    return
                 }
                 trace variable b w [1mnamespace code 22mtheTraceCallback]
              }
              set a::b c
       When executed, it prints the message:
              the value of a::b has changed to c

1mEXAMPLES0m
       Create a namespace containing a variable and an exported command:
              1mnamespace eval 22mfoo {
                 variable bar 0
                 proc grill {} {
                    variable bar
                    puts "called [incr bar] times"
                 }
                 1mnamespace export 22mgrill
              }

       Call the command defined in the previous example in various ways.
              # Direct call
              foo::grill

              # Import into current namespace, then call local alias
              namespace import foo::grill
              grill

       Look up where the command imported in the previous example came from:
              puts "grill came from [1mnamespace which 22mgrill]"


1mSEE ALSO0m
       variable(n)


1mKEYWORDS0m
