Seth Woolley's Man Viewer

namespace(n) - namespace, namespace - create and manipulate contexts for commands and variables - man n namespace

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

namespace(n)                 Tcl Built-In Commands                namespace(n)



NAME
       namespace - create and manipulate contexts for commands and variables

SYNOPSIS
       namespace ?option? ?arg ...?


DESCRIPTION
       The  namespace  command  lets  you create, access(2,5), 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 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 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 ::.  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(1,8) which script  has
              been wrapped in(1,8) a namespace inscope command.  The new script has
              two important properties.  First, it can  be  evaluated  in(1,8)  any
              namespace  and  will cause script to be evaluated in(1,8) 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(7,n,1 builtins) script [names-
              pace code {foo bar}] is invoked in(1,8) namespace ::a::b.  Then  eval
              "$script  x  y"  can  be executed in(1,8) any namespace (assuming the
              value of script has been passed in(1,8) 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(1,8) the global namespace.  A scoped com-
              mand captures a command together with its namespace context in(1,8) a
              way  that allows it to be executed properly later.  See the sec-
              tion SCOPED VALUES for some examples of how this is used to cre-
              ate 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(3,n)), 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(1,8)  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(1,8) 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(1,8)
              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(3,n) namespace is a valid namespace in(1,8) the current con-
              text, returns 0 otherwise.

       namespace export ?-clear(1,3x,3x clrtobot)? ?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(1,8) 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(1,2,n) 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(1,8)  the  current
              (exporting) namespace.  Each pattern is appended onto the names-
              pace's list of export patterns.  If the -clear(1,3x,3x clrtobot)  flag  is  given,
              the namespace's export pattern list is reset(1,7,1 tput) to empty before any
              pattern arguments are appended.  If no patterns  are  given  and
              the  -clear(1,3x,3x clrtobot)  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 ::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(1,8) the command name at the end of
              the qualified name.  Glob characters may not appear in(1,8) a  names-
              pace  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 com-
              mand 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  correspond-
              ing  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(1,8)  the  command  name  at  the end of the qualified name.  Glob
              characters may not appear in(1,8) a namespace name.  All the commands
              that  match  a  pattern  string(3,n) and which are currently exported
              from their namespace are added to the current  namespace.   This
              is  done by creating a new command in(1,8) the current namespace that
              points to the exported command in(1,8) its original  namespace;  when
              the new imported command is called, it invokes the exported com-
              mand.  This command normally returns an  error(8,n)  if(3,n)  an  imported
              command  conflicts  with  an  existing command.  However, if(3,n) 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(1,8)  the  exporting  namespace  are  imported.  In other
              words, you can import only the commands that are in(1,8) a  namespace
              at  the  time(1,2,n) when the namespace import command is executed.  If
              another command is defined and exported in(1,8) this namespace  later
              on, it will not be imported.

       namespace inscope namespace script ?arg ...?
              Executes  a  script  in(1,8)  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(1,8) that
              namespace that points to the actual  command  in(1,8)  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(1,8)  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(3,n)
              Returns any leading namespace qualifiers for string(3,n).  Qualifiers
              are   namespace   names   separated  by  ::s.   For  the  string(3,n)
              ::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(1,8)  fact, the names of currently defined
              namespaces.

       namespace tail string(3,n)
              Returns the simple name at the end of a qualified string.  Qual-
              ifiers  are  namespace  names  separated by ::s.  For the string(3,n)
              ::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(1,8) 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(3,n) name does  not  exist  in(1,8)
              the  current  namespace  but does exist in(1,8) the global namespace,
              this command returns a fully-qualified name in(1,8) 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(3x,n,3x _nc_tracebits) 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(5,n) bump {} {
               variable num
               incr num
           }  }  creates  a  new namespace containing the variable num and the
       procedure bump.  The commands and variables in(1,8) this namespace are sepa-
       rate  from  other commands and variables in(1,8) the same program.  If there
       is a command named(5,8) bump in(1,8) the global namespace, for example,  it  will
       be different from the command bump in(1,8) the Counter namespace.

       Namespace  variables resemble global variables in(1,8) Tcl.  They exist out-
       side of the procedures in(1,8) a namespace but can be accessed in(1,8)  a  proce-
       dure via the variable command, as shown in(1,8) the example above.

       Namespaces  are dynamic.  You can add and delete commands and variables
       at any time(1,2,n), so you can build up the contents of a namespace over  time(1,2,n)
       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(5,n) bump {} {
               variable num
               return [incr num]
           } } namespace eval Counter {
           proc(5,n) test {args} {
               return $args
           } } namespace eval Counter {
           rename(1,2,n)  test  ""  }  Note  that  the test procedure is added to the
       Counter namespace, and later removed via the rename(1,2,n) 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(1,3,n,1 builtins)  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(3,n)), although :: is a  synonym.   As  an  example,  the  name
       ::safe::interp::create  refers  to  the command create in(1,8) the namespace
       interp that is a child of of namespace ::safe, which in(1,8) turn is a child
       of the global namespace ::.

       If  you  want  to access(2,5) 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(2,5)
       the Counter procedures like this:  Counter::bump  5  Counter::Reset  We
       could  access(2,5) the current count like this: puts(3,n) "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(1,2,n) commands.
       For example, you could add a procedure to the Foo namespace like  this:
       proc(5,n) Foo::Test {args} {return $args} And you could move(3x,7,3x curs_move) the same proce-
       dure to another namespace like this: rename(1,2,n) 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(1,8)  simple  command,  variable,  and  namespace  names
       except  as  a  namespace  separator.   Extra :s in(1,8) a qualified name are
       ignored; that is, two or more :s are treated as a namespace  separator.
       A  trailing  ::  in(1,8)  a qualified variable or command name refers to the
       variable or command named(5,8) {}.  However, a trailing ::  in(1,8)  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(7,n,1 builtins),  proc(5,n),  rename(1,2,n),  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(3,n) 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(1,8) the current namespace, and then in(1,8) the  global  names-
       pace.  Namespace names, on the other hand, are always resolved by look-
       ing in(1,8) only the current namespace.

       In the following example, set(7,n,1 builtins) traceLevel 0 namespace eval Debug {
           printTrace $traceLevel } Tcl looks for traceLevel in(1,8) the  namespace
       Debug and then in(1,8) the global namespace.  It looks up the command print-
       Trace in(1,8) the same way.  If a variable or command name is not  found  in(1,8)
       either  context,  the name is undefined.  To make this point absolutely
       clear(1,3x,3x clrtobot), consider the following example: set(7,n,1 builtins) traceLevel 0 namespace  eval
       Foo {
           variable traceLevel 3

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

       You can use the namespace which command to clear(1,3x,3x clrtobot) 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(1,8) 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(2,5) 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(2,5)  the
       element.

       You can access(2,5) a namespace variable from a procedure in(1,8) the same names-
       pace by using the variable command.  Much like the global command, this
       creates  a local link(1,2) to the namespace variable.  If necessary, it also
       creates the variable in(1,8) the current namespace and initializes it.  Note
       that  the  global command only creates links to variables in(1,8) the global
       namespace.  It is not necessary to use a variable command if(3,n) 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(1,8) a package
       like BLT are contained in(1,8) a  namespace  called  Blt.   Then  you  might
       access(2,5) 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(2,5) 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(1,2)  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(1,2,n) to time(1,2,n) (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(1,8)
       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 com-
       mand, 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  com-
       mands must be accessed with the Blt:: prefix.

       When  you  delete  a  command  from  the exporting namespace like this:
       rename(1,2,n) 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(1,7,1 tput)
           variable Num 0
           variable Max 100

           proc(5,n) bump {{by 1}} {
               variable Num
               incr Num $by
               Check
               return $Num
           }
           proc(5,n) reset(1,7,1 tput) {} {
               variable Num
               set(7,n,1 builtins) Num 0
           }
           proc(5,n) Check {} {
               variable Num
               variable Max
               if(3,n) {$Num > $Max} {
                   error(8,n) "too high!"
               }
           } } The procedures  bump  and  reset(1,7,1 tput)  are  exported,  so  they  are
       included  when you import from the Counter namespace, like this: names-
       pace 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
       exported, internal, variable



Tcl                                   8.0                         namespace(n)

References for this manual (incoming links)