namespace man page on Minix

Man page or keyword search:  
man Server   6208 pages
apropos Keyword Search (all sections)
Output format
Minix logo
[printable version]

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, 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 procedure
       bump.  The commands and variables in this namespace are	separate  from
       other  commands	and variables in the same program.  If there is a com‐
       mand named bump in the global namespace, for example, it will  be  dif‐
       ferent 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 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 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 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 res‐
       olution process.

       You  can use the namespace which command to clear up any question about
       name resolution.	 For example, the command:
	      namespace eval Foo::Debug {namespace which -variable traceLevel}
       returns ::traceLevel.  On the other hand, the command,
	      namespace eval Foo {namespace which -variable traceLevel}
       returns ::Foo::traceLevel.

       As mentioned above, namespace names are looked up differently than  the
       names  of  variables and commands.  Namespace names are always resolved
       in the current 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::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 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
       exported, internal, variable

Tcl				      8.0			  namespace(n)
[top]

List of man pages available for Minix

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net