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
              namespace code command.  The  new  script  has  two
              important  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
              callback scripts in the global namespace.  A scoped
              command  captures  a  command  together  with   its
              namespace  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 callback 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
              convenience to programmers.

       namespace delete ?namespace namespace ...?
              Each  namespace  namespace  is  deleted   and   all
              variables,   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 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.

       namespace eval namespace arg ?arg ...?
              Activates   a   namespace   called   namespace  and
              evaluates  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
              automatically created.

       namespace export ?-clear? ?pattern pattern ...?
              Specifies   which  commands  are  exported  from  a
              namespace.  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
              previously 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 current (exporting) namespace.  Each pattern is
              appended   onto  the  namespace's  list  of  export
              patterns.   If  the  -clear  flag  is  given,   the
              namespace'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
              namespace.  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
              characters 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
              applications then register with, e.g., Tk  widgets.
              The  namespace  inscope  command  is  much like the
              namespace eval command except that it  has  lappend
              semantics 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
              prefixes.

       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
              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  namespaces  a,  b,...,n  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, 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
              current 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
              namespace.  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 variable command or through a trace on
              the variable, this command will return  the  fully-
              qualified  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
       contents  of  a  namespace  over  time  using  a series of
       namespace  eval  commands.   For  example,  the  following
       series  of  commands  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
       simple  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
       namespace  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
       command 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-
       qualified name that starts with a ::, there is no question
       about what  command,  variable,  or  namespace  you  mean.
       However,  if  the  name does not start with a :: (i.e., is
       relative), 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
       printTrace 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
       resolution 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
       namespace.  This means, for example, that a namespace eval
       command  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,
       commands, 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
       variables 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
       nuisance to type  their  qualified  names.   For  example,
       suppose that all of the commands in a package like BLT are
       contained 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
       namespace, 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
       namespace export command specifies what  commands  may  be
       imported  by  other  namespaces.   If  a  namespace import
       command specifies a command  that  is  not  exported,  the
       command is not imported.


SEE ALSO
       variable(n)


KEYWORDS
