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  NAMES-
       PACE?  below  for  a brief overview of namespaces.  The legal values of
       option are listed below.  Note that you can abbreviate the options.

       namespace children ?namespace? ?pattern?
              Returns a list of all child namespaces that belong to the names-
              pace  namespace.   If namespace 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
              (::).  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  double  colon (::) is used directly, otherwise the
              namespace namespace (or the fully-qualified name of the  current
              namespace) is prepended onto 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 inscope 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 [names-
              pace 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 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 SCOPED SCRIPTS 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,  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.

       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 argu-
              ments are concatenated together with a space between each one in
              the  same  fashion as the eval command, and the result is evalu-
              ated.

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

       namespace exists namespace
              Returns  1 if namespace is a valid namespace in the current con-
              text, returns 0 otherwise.

       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  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 namespace export com-
              mand 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 names-
              pace'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 names-
              pace's current export list.

       namespace forget ?pattern pattern ...?
              Removes previously imported commands  from  a  namespace.   Each
              pattern  is  a  simple  or  qualified  name such as x, foo::x or
              a::b::p*.  Qualified names contain double colons (::) and  qual-
              ify a name with the name of one or more namespaces.  Each quali-
              fied pattern 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 simple pattern this com-
              mand deletes the matching commands of the current namespace that
              were  imported  from  a different namespace.  For qualified pat-
              terns, 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 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 com-
              mand.  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
              applications  then  register with, e.g., Tk widgets.  The names-
              pace inscope command is much like  the  namespace  eval  command
              except  that  the  namespace  must  already exist, and namespace
              inscope appends additional args as proper list elements.
              namespace inscope ::foo $script $x $y $z is equivalent to names-
              pace 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  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 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 double colons (::).  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.  Qual-
              ifiers are namespace names separated by double colons (::).  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 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-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 pro-
       cedure 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  out-
       side  of  the procedures in a namespace but can be accessed in a proce-
       dure 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 hierar-
       chically.  A nested namespace is encapsulated inside its parent  names-
       pace 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  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 :: 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 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 names-
       pace 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 quali-
       fier 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 proce-
       dure 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 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 :: 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  sup-
       port  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 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 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 names-
       pace.  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 ::.

       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 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  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 Blt.  Then you might
       access these commands like this: Blt::graph .g -background red Blt::ta-
       ble  .  .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 spe-
       cific 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 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
       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 a 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.

SCOPED SCRIPTS
       The namespace code command 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: namespace eval a {
          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 [namespace code theTraceCallback] } set a::b c
       When executed, it prints the message: the value of a::b has changed  to
       c

EXAMPLES
       Create  a  namespace  containing  a  variable  and an exported command:
       namespace eval foo {
          variable bar 0
          proc grill {} {
             variable bar
             puts "called [incr bar] times"
          }
          namespace export grill }

       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 [namespace origin grill]"


SEE ALSO
       variable(n)


KEYWORDS
