NAME
       namespace  -  create  and manipulate contexts for commands
       and variables

SYNOPSIS
       namespace ?option? ?arg ...?


DESCRIPTION
       The namespace command lets you create, access, and destroy
       separate  contexts  for  commands  and variables.  See the
       section WHAT IS A NAMESPACE? below for a brief overview of
       namespaces.   The  legal  option's are listed below.  Note
       that you can abbreviate the option's.

       namespace children ?namespace? ?pattern?
              Returns a list of all child namespaces that  belong
              to  the  namespace  namespace.  If namespace is not
              specified, then the children are returned  for  the
              current  namespace.   This  command  returns fully-
              qualified names,  which  start  with  ::.   If  the
              optional   pattern  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  ::  is  used
              directly, otherwise the namespace namespace (or the
              fully-qualified name of the current  namespace)  is
              prepended onto the the pattern.

       namespace code script
              Captures  the  current  namespace context for later
              execution of the script script.  It returns  a  new
              script in which script has been wrapped in a names-
              pace code command.  The new script has  two  impor-
              tant properties.  First, it can be evaluated in any
              namespace and will cause script to be evaluated  in
              the  current namespace (the one where the namespace
              code  command  was  invoked).   Second,  additional
              arguments  can  be appended to the resulting script
              and they will be passed  to  script  as  additional
              arguments.   For  example,  suppose the command set
              script [namespace code {foo  bar}]  is  invoked  in
              namespace  ::a::b.   Then eval "$script x y" can be
              executed in any namespace (assuming  the  value  of
              script  has  been passed in properly) and will have
              the same  effect  as  the  command  namespace  eval
              ::a::b  {foo  bar  x  y}.   This  command is needed
              because extensions like Tk normally  execute  call-
              back  scripts  in  the  global namespace.  A scoped
              command captures a command together with its names-
              pace context in a way that allows it to be executed
              properly later.  See the section SCOPED VALUES  for
              some  examples  of how this is used to create call-
              back scripts.
       namespace current
              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  ::  for  the  global namespace as a conve-
              nience to programmers.

       namespace delete ?namespace namespace ...?
              Each namespace namespace is deleted and  all  vari-
              ables,  procedures,  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 pre-
              vent 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  com-
              mand does nothing.

       namespace eval namespace arg ?arg ...?
              Activates  a  namespace called namespace and evalu-
              ates some code in that context.  If  the  namespace
              does  not  already  exist,  it is created.  If more
              than one arg argument is specified,  the  arguments
              are concatenated together with a space between each
              one in the same fashion as the  eval  command,  and
              the result is evaluated.

              If  namespace  has leading namespace qualifiers and
              any leading namespaces do not exist, they are auto-
              matically created.

       namespace export ?-clear? ?pattern pattern ...?
              Specifies which commands are exported from a names-
              pace.  The exported commands are those that can  be
              later  imported  into  another  namespace  using  a
              namespace import command.  Both commands defined in
              a  namespace  and commands the namespace has previ-
              ously imported can be exported by a namespace.  The
              commands  do not have to be defined at the time the
              namespace export command is executed.  Each pattern
              may  contain  glob-style special characters, but it
              may not include any namespace qualifiers.  That is,
              the  pattern  can only specify commands in the cur-
              rent  (exporting)  namespace.   Each   pattern   is
              appended  onto  the namespace's list of export pat-
              terns.  If the -clear flag  is  given,  the  names-
              pace's export pattern list is reset to empty before
              any pattern arguments are appended.  If no patterns
              are  given  and  the  -clear flag isn't given, this
              command  returns  the  namespace's  current  export
              list.
       namespace forget ?pattern pattern ...?
              Removes  previously imported commands from a names-
              pace.  Each pattern is a  qualified  name  such  as
              foo::x  or  a::b::p*.   Qualified names contain ::s
              and qualify a name with the name  of  one  or  more
              namespaces.   Each  pattern  is  qualified with 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.  This command first
              finds the  matching  exported  commands.   It  then
              checks  whether  any  of  those 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
              namespace import command.

       namespace import ?-force? ?pattern pattern ...?
              Imports commands into a namespace.  Each pattern is
              a qualified name like foo::x or a::p*.  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 char-
              acters may not appear in a namespace name.  All the
              commands  that match a pattern 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   command.   This  command  normally
              returns an error if an imported  command  conflicts
              with  an  existing command.  However, if the -force
              option is given, imported  commands  will  silently
              replace  existing  commands.   The namespace import
              command  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  namespace  import
              command is executed.  If another command is defined
              and exported in this namespace later  on,  it  will
              not be imported.

       namespace inscope namespace arg ?arg ...?
              Executes  a  script  in the context of a particular
              namespace.  This command is not expected to be used
              directly  by programmers; calls to it are generated
              implicitly when  applications  use  namespace  code
              commands to create callback scripts that the appli-
              cations then register with, e.g., Tk widgets.   The
              namespace  inscope  command is much like the names-
              pace eval command except that it has lappend seman-
              tics  and  the  namespace  must  already exist.  It
              treats the first argument as a  list,  and  appends
              any  arguments  after  the  first  onto  the end as
              proper list elements.  namespace inscope ::foo a  x
              y z is equivalent to namespace eval ::foo [concat a
              [list x y z]] This lappend semantics  is  important
              because  many  callback  scripts  are actually pre-
              fixes.

       namespace origin command
              Returns the fully-qualified name  of  the  original
              command  to  which  the  imported  command  command
              refers.  When a command is imported into  a  names-
              pace,  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 namespaces a, b,...,n where  each  suc-
              cessive namespace just imports the command from the
              previous namespace, this command returns the fully-
              qualified name of the original command in the first
              namespace, a.  If command  does  not  refer  to  an
              imported command, the command's own fully-qualified
              name is returned.

       namespace parent ?namespace?
              Returns the  fully-qualified  name  of  the  parent
              namespace for namespace namespace.  If namespace is
              not specified, the fully-qualified name of the cur-
              rent namespace's parent is returned.

       namespace qualifiers string
              Returns   any   leading  namespace  qualifiers  for
              string.  Qualifiers are namespace  names  separated
              by ::s.  For the string ::foo::bar::x, this command
              returns ::foo::bar, and for :: it returns ``''  (an
              empty  string).   This command is the complement of
              the namespace tail command.  Note that it does  not
              check whether the namespace names are, in fact, the
              names of currently defined namespaces.

       namespace tail string
              Returns the simple name at the end of  a  qualified
              string.   Qualifiers  are namespace names separated
              by ::s.  For the string ::foo::bar::x, this command
              returns  x,  and  for  :: it returns ``'' (an empty
              string).  This command is  the  complement  of  the
              namespace  qualifiers  command.   It does not check
              whether the namespace names are, in fact, the names
              of currently defined namespaces.

       namespace which ?-command? ?-variable? name
              Looks  up  name as either a command or variable and
              returns its fully-qualified name.  For example,  if
              name  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 no flag
              is given, name is treated as a command  name.   See
              the  section  NAME RESOLUTION below for an explana-
              tion of the rules regarding name resolution.


WHAT IS A NAMESPACE?
       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  global  namespace.   The  global
       namespace  holds  all  global variables and commands.  The
       namespace eval command lets  you  create  new  namespaces.
       For example,
              namespace eval Counter {
                  namespace export Bump
                  variable num 0

                  proc Bump {} {
                      variable num
                      incr num
                  }
              }
       creates  a  new  namespace containing the variable num and
       the procedure Bump.  The commands and  variables  in  this
       namespace  are  separate from other commands and variables
       in the same program.  If there is a command named Bump  in
       the  global  namespace,  for example, it will be different
       from the command Bump in the Counter namespace.

       Namespace variables  resemble  global  variables  in  Tcl.
       They  exist  outside  of the procedures in a namespace but
       can be accessed in a procedure via the  variable  command,
       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  con-
       tents of a namespace over time using a series of namespace
       eval commands.  For example, the following series of  com-
       mands  has  the  same  effect  as the namespace definition
       shown above:
              namespace eval Counter {
                  variable num 0
                  proc Bump {} {
                      variable num
                      return [incr num]
                  }
              }
              namespace eval Counter {
                  proc test {args} {
                      return $args
                  }
              }
              namespace eval Counter {
                  rename test ""
              }
       Note that the test  procedure  is  added  to  the  Counter
       namespace, and later removed via the rename command.

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


QUALIFIED NAMES
       Each namespace has a  textual  name  such  as  history  or
       ::safe::interp.   Since  namespaces  may  nest,  qualified
       names are used to refer to commands, variables, and  child
       namespaces  contained  inside namespaces.  Qualified names
       are similar to the hierarchical path names for Unix  files
       or  Tk  widgets,  except  that :: is used as the separator
       instead of / or ..  The topmost or  global  namespace  has
       the  name  ``''  (i.e., an empty string), although :: is a
       synonym.  As an example, the  name  ::safe::interp::create
       refers  to the command create in the namespace interp that
       is a child of of namespace ::safe,  which  in  turn  is  a
       child of the global namespace ::.

       If  you want to access commands and variables from another
       namespace, you must use some extra syntax.  Names must  be
       qualified  by  the namespace that contains them.  From the
       global namespace, we might access the  Counter  procedures
       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 qualifier to reach its elements.   If  we  had  a
       namespace  Foo  that  contained the namespace Counter, you
       could invoke its Bump procedure 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 Foo namespace 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.  :: is disallowed in sim-
       ple  command,  variable,  and  namespace names except as a
       namespace separator.  Extra :s in  a  qualified  name  are
       ignored;  that  is, two or more :s are treated as a names-
       pace separator.  A trailing :: in a qualified variable  or
       command  name  refers to the variable or command named {}.
       However, a trailing :: in a qualified  namespace  name  is
       ignored.


NAME RESOLUTION
       In  general,  all Tcl commands that take variable and com-
       mand names support qualified names.  This  means  you  can
       give  qualified  names  to  such  commands  as  set, proc,
       rename, and interp alias.  If you provide  a  fully-quali-
       fied  name  that  starts  with  a ::, there is no question
       about what command, variable, or namespace you mean.  How-
       ever, if the name does not start with a :: (i.e., is rela-
       tive), 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  namespace.
       Namespace names, on the other hand, are always resolved by
       looking in only the current namespace.

       In the following example,
              set traceLevel 0
              namespace eval Debug {
                  printTrace $traceLevel
              }
       Tcl looks for traceLevel in the namespace Debug  and  then
       in  the  global namespace.  It looks up the command print-
       Trace in 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
              namespace eval Foo {
                  variable traceLevel 3

                  namespace eval Debug {
                      printTrace $traceLevel
                  }
              }
       Here  Tcl  looks  for  traceLevel  first  in the namespace
       Foo::Debug.  Since it is not found there, Tcl  then  looks
       for   it   in   the   global   namespace.    The  variable
       Foo::traceLevel is completely ignored during the name res-
       olution process.

       You  can  use  the namespace which command to clear up any
       question about name resolution.  For example, the command:
              namespace eval Foo::Debug {namespace which -variable traceLevel}
       returns ::traceLevel.  On the other hand, the command,
              namespace eval Foo {namespace which -variable traceLevel}
       returns ::Foo::traceLevel.

       As  mentioned above, namespace names are looked up differ-
       ently than the names of variables and commands.  Namespace
       names  are always resolved in the current namespace.  This
       means, for example, that a  namespace  eval  command  that
       creates a new namespace always creates a child of the cur-
       rent namespace unless the new namespace name begins with a
       ::.

       Tcl  has  no  access control to limit what variables, com-
       mands, or namespaces 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  namespace  by using the variable command.  Much
       like the global command, 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 global command only creates links to vari-
       ables in the global namespace.  It is not necessary to use
       a  variable  command  if you always refer to the namespace
       variable using an appropriate qualified name.


IMPORTING COMMANDS
       Namespaces are often used to  represent  libraries.   Some
       library  commands are used so frequently that it is a nui-
       sance to type their qualified names.  For example, suppose
       that  all  of  the commands in a package like BLT are con-
       tained in a namespace called Blt.  Then you  might  access
       these commands like this:
              Blt::graph .g -background red
              Blt::table . .g 0,0
       If  you  use  the graph and table commands frequently, you
       may want to access them without the Blt:: prefix.  You can
       do  this by importing the commands into the current names-
       pace, like this:
              namespace import Blt::*
       This adds all exported commands  from  the  Blt  namespace
       into  the current namespace context, so you can write code
       like this:
              graph .g -background red
              table . .g 0,0
       The namespace import command only imports commands from  a
       namespace  that  that  namespace exported with a namespace
       export command.

       Importing every 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 specific commands you need.  For
       example, the command
              namespace import Blt::graph Blt::table
       imports only the graph and table commands 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 different packages.  But  from  time
       to  time  (perhaps  when  debugging),  you may want to get
       around this restriction.  You  may  want  to  reissue  the
       namespace import command to pick up new commands that have
       appeared in a namespace.  In that case, you  can  use  the
       -force  option,  and  existing  commands  will be silently
       overwritten:
              namespace import -force Blt::graph Blt::table
       If for some reason, you want to stop  using  the  imported
       commands,  you  can  remove  them with an namespace forget
       command, like this:
              namespace forget Blt::*
       This searches  the  current  namespace  for  any  commands
       imported  from  Blt.   If  it  finds any, it removes them.
       Otherwise, it does nothing.  After this, the Blt  commands
       must be accessed with the Blt:: prefix.

       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.


EXPORTING COMMANDS
       You can export commands from a namespace like this:
              namespace eval Counter {
                  namespace export Bump 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  Bump  and Reset are exported, so they are
       included when you import from the Counter namespace,  like
       this:
              namespace import Counter::*
       However,  the  check  procedure  is not exported, so it is
       ignored by the import operation.

       The namespace import command only  imports  commands  that
       were  declared as exported by their namespace.  The names-
       pace  export  command  specifies  what  commands  may   be
       imported  by other namespaces.  If a namespace import com-
       mand specifies a command that is not exported, the command
       is not imported.


SEE ALSO
       variable(n)


KEYWORDS
       exported, internal, variable
