Manual Pages for UNIX Operating System command usage for man namespace

Tcl Built-In Commands                               namespace(1T)



_________________________________________________________________

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 sec-
     tion WHAT IS A NAMESPACE? 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  namespace  namespace.   If namespace is not speci-
          fied, then the children 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,  other-
          wise  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 execu-
          tion  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 [namespace code {foo  bar}]  is  invoked  in
          namespace  ::a::b.  Then eval "$script x y" can be exe-
          cuted 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



Tcl                     Last change: 8.0                        1






Tcl Built-In Commands                               namespace(1T)



          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 pro-
          grammers.

     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 com-
          mand  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 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 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 spe-
          cial characters, but it may not include  any  namespace
          qualifiers.  That is, the pattern can only specify com-
          mands in the current (exporting) namespace.  Each  pat-
          tern  is  appended  onto the namespace's list of export



Tcl                     Last change: 8.0                        2






Tcl Built-In Commands                               namespace(1T)



          patterns.  If the -clear flag is given, the namespace's
          export  pattern  list is reset to empty before any pat-
          tern 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 simple or qualified name such as x,
          foo::x or a::b::p*.   Qualified  names  contain  double
          colons  (::) 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 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 com-
          mand 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



Tcl                     Last change: 8.0                        3






Tcl Built-In Commands                               namespace(1T)



          namespace.   This  command  is  not expected to be used
          directly by programmers;  calls  to  it  are  generated
          implicitly  when  applications  use namespace code com-
          mands 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  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  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  com-
          mand  to  which  the  imported  command command refers.
          When a command is imported into a namespace, a new com-
          mand  is  created  in that namespace that points to the
          actual command in the exporting namespace.  If  a  com-
          mand  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  com-
          mand  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  com-
          mand 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
          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



Tcl                     Last change: 8.0                        4






Tcl Built-In Commands                               namespace(1T)



          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 sec-
          tion  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  com-
     mands.   For  example,  the following series of commands has
     the same effect as the namespace definition shown above:



Tcl                     Last change: 8.0                        5






Tcl Built-In Commands                               namespace(1T)



          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  com-
     mand  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 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




Tcl                     Last change: 8.0                        6






Tcl Built-In Commands                               namespace(1T)



     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 separa-
     tor.  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  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



Tcl                     Last change: 8.0                        7






Tcl Built-In Commands                               namespace(1T)



     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  dif-
     ferently   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 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 nui-
     sance 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 com-
     mands 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



Tcl                     Last change: 8.0                        8






Tcl Built-In Commands                               namespace(1T)



          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 com-
     mands,  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.  Oth-
     erwise, 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



Tcl                     Last change: 8.0                        9






Tcl Built-In Commands                               namespace(1T)



                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 packaged 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 evalua-
     tion 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"



Tcl                     Last change: 8.0                       10






Tcl Built-In Commands                               namespace(1T)



             }
             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(1T)


KEYWORDS
     exported, internal, variable

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tcl-8  |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tcl is available on http://opensolaris.org.
















Tcl                     Last change: 8.0                       11