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 inscope  command.   The  new  script  has  two
              important  properties.   First, it can be evaluated
              in any namespace and will cause script to be evalu-
              ated  in  the  current namespace (the one where the
              namespace code command was invoked).  Second, addi-
              tional  arguments  can be appended to the resulting
              script and they will be passed to script  as  addi-
              tional 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 exists namespace
              Returns  1 if namespace is a valid namespace in the
              current context, returns 0 otherwise.

       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 simple or qualified name
              such as x, foo::x  or  a::b::p*.   Qualified  names
              contain ::s and qualify a name with the name of one
              or more  namespaces.   Each  qualified  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.
              For  each  simple  pattern this command deletes the
              matching commands of  the  current  namespace  that
              were  imported  from  a  different  namespace.  For
              qualified patterns, 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 namespace import com-
              mand.

       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 script ?arg ...?
              Executes a script in the context of  the  specified
              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 the namespace must
              already exist, and namespace inscope appends  addi-
              tional args as proper list elements.
              namespace inscope ::foo $script $x $y $z is equiva-
              lent to namespace eval ::foo [concat $script  [list
              $x  $y  $z]]  thus  additional  arguments  will not
              undergo a second round of substitution, as  is  the
              case with namespace eval.

       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 cur-
              rently 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 the vari-
              able has been created but not defined, such as with
              the variable command or  through  a  trace  on  the
              variable, this command will return the fully-quali-
              fied name of the variable.  If no  flag  is  given,
              name is treated as a command name.  See the section
              NAME RESOLUTION below for  an  explanation  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
       differently  than  the  names  of  variables and commands.
       Namespace names are always resolved in the current  names-
       pace.  This means, for example, that a namespace eval com-
       mand that creates a new namespace always creates  a  child
       of  the  current  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
