Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
info(n)			     Tcl Built-In Commands		       info(n)

______________________________________________________________________________

NAME
       info - Information about	the state of the Tcl interpreter

SYNOPSIS
       info option ?arg	arg ...?
______________________________________________________________________________

DESCRIPTION
       Available commands:

       info args procname
	      Returns the names	of the parameters to the procedure named proc-
	      name.

       info body procname
	      Returns the body of the procedure	named procname.

       info class subcommand class ?arg	...
	      Returns information about	the class named	class.	See CLASS  IN-
	      TROSPECTION below.

       info cmdcount
	      Returns  the  total  number of commands evaluated	in this	inter-
	      preter.

       info cmdtype commandName
	      Returns a	the type of the	command	named  commandName.   Built-in |
	      types are:						       |

	      alias							       |
		     commandName  was  created by interp alias.	 In a safe in- |
		     terpreter an alias	is only	visible	if both	the alias  and |
		     the target	are visible.				       |

	      coroutine							       |
		     commandName was created by	coroutine.		       |

	      ensemble							       |
		     commandName was created by	namespace ensemble.	       |

	      import							       |
		     commandName was created by	namespace import.	       |

	      native							       |
		     commandName  was  created by the Tcl_CreateObjProc	inter- |
		     face directly without further registration	of the type of |
		     command.						       |

	      object							       |
		     commandName  is the public	command	that represents	an in- |
		     stance of oo::object or one of its	subclasses.	       |

	      privateObject						       |
		     commandName is the	private	command, my by	default,  that |
		     represents	 an  instance of oo::object or one of its sub- |
		     classes.						       |

	      proc							       |
		     commandName was created by	proc.			       |

	      slave							       |
		     commandName was created by	interp create.		       |

	      zlibStream						       |
		     commandName was created by	zlib stream.		       |

	      Other types may be also registered as well.   See	 Tcl_Register- |
	      CommandTypeName.						       |

       info commands ?pattern?
	      Returns  the  names of all commands visible in the current name-
	      space.  If pattern is given, returns only	those names that match
	      according	 to  string match.  Only the last component of pattern
	      is a pattern.  Other components identify a namespace.  See NAME-
	      SPACE RESOLUTION in the namespace(n) documentation.

       info complete command
	      Returns  1  if  command  is a complete command, and 0 otherwise.
	      Typically	used in	 line-oriented	input  environments  to	 allow
	      users to type in commands	that span multiple lines.

       info coroutine
	      Returns  the  name of the	current	coroutine, or the empty	string
	      if there is no current coroutine or the  current	coroutine  has
	      been deleted.

       info default procname parameter varname
	      If  the parameter	parameter for the procedure named procname has
	      a	default	value, stores that value in  varname  and  returns  1.
	      Otherwise, returns 0.

       info errorstack ?interp?
	      Returns  a  description  of the active command at	each level for
	      the last error in	the current interpreter, or in the interpreter
	      named interp if given.

	      The description is a dictionary of tokens	and parameters.	Tokens
	      are currently either CALL, UP, or	INNER, but other values	may be
	      introduced in the	future.	CALL indicates a command call, and its
	      parameter	is the corresponding info  level  0.  UP  indicates  a
	      shift  in	 variable  frames generated by uplevel or similar, and
	      applies to the previous CALL item. Its parameter	is  the	 level
	      offset.  INNER  identifies the "inner context", which is the in-
	      nermost atomic command or	bytecode instruction that  raised  the
	      error,  along  with its arguments	when available.	While CALL and
	      UP provide a trail of the	call path, INNER provides  details  of
	      the offending operation in the innermost procedure call, even to
	      sub-expression granularity.

	      This information is also present in the -errorstack entry	of the
	      options dictionary returned by 3-argument	catch; info errorstack
	      is a convenient way of retrieving	it for uncaught	errors at top-
	      level in an interactive interpreter.

       info exists varName
	      Returns  1  if  a	variable named varName is visible and has been
	      defined, and 0 otherwise.

       info frame ?depth?
	      Returns the depth	of the call to info frame itself.   Otherwise,
	      returns a	dictionary describing the active command at the	depth,
	      which counts all commands	visible	to info	level,	plus  commands
	      that don't create	a new level, such as eval, source, or uplevel.
	      The frame	depth is always	greater	than the current level.

	      If depth is greater than 0 it is the frame at that depth.	  Oth-
	      erwise it	is the number of frames	up from	the current frame.

	      As  with	info  level and	error traces, for nested commands like
	      "foo [bar	[x]]", only "x"	is seen	by info	frame  invoked	within
	      "x".

	      The dictionary may contain the following keys:

	      type   Always  present.  Possible	values are source, proc, eval,
		     and precompiled.

		     source
			    A script loaded via	the source command.

		     proc
			    The	body of	a procedure that could not  be	traced
			    back to a line in a	particular script.

		     eval
			    The	body of	a script provided to eval or uplevel.

		     precompiled
			    A pre-compiled script (loadable by the package tb-
			    cload), and	no further information is available.

	      line   The line number of	of the command inside its script.  Not
		     available	for  precompiled  commands.   When the type is
		     source, the line number is	relative to the	 beginning  of
		     the  file,	 whereas for the last two types	it is relative
		     to	the start of the script.

	      file   For type source, provides the normalized path of the file
		     that contains the command.

	      cmd    The command before	substitutions were performed.

	      proc   For  type	prod, the name of the procedure	containing the
		     command.

	      lambda For a command in a	script evaluated as the	body of	an un-
		     named  routine  via  the apply command, the definition of
		     that routine.

	      level  For a frame that corresponds to a level,  (to  be	deter-
		     mined).

	      When  a  command can be traced to	its literal definition in some
	      script, e.g.  procedures nested  in  statically  defined	proce-
	      dures,  and  literal eval	scripts	in files or statically defined
	      procedures, its type is source and its location is the  absolute
	      line  number in the script.  Otherwise, its type is proc and its
	      location is its line number within the body of the procedure.

	      In contrast, procedure definitions and eval within a dynamically
	      evaluated	 environment  count line numbers relative to the start
	      of their script, even if they would be able to count relative to
	      the  start of the	outer dynamic script. That type	of number usu-
	      ally makes more sense.

	      A	different way of describing this behaviour is that  file-based
	      locations	 are  tracked as deeply	as possible, and where this is
	      not possible the lines are counted based on the smallest	possi-
	      ble  eval	 or procedure body, as that scope is usually easier to
	      find than	any dynamic outer scope.

	      The syntactic form {*} is	handled	like eval. I.e.	if it is given
	      a	literal	list argument the system tracks	the line number	within
	      the list words as	well,  and  otherwise  all  line  numbers  are
	      counted relative to the start of each word (smallest scope)

       info functions ?pattern?
	      If  pattern  is  not given, returns a list of all	the math func-
	      tions currently defined.	If  pattern  is	 given,	 returns  only
	      those names that match pattern according to string match.

       info globals ?pattern?
	      If pattern is not	given, returns a list of all the names of cur-
	      rently-defined global variables.	Global variables are variables
	      in  the global namespace.	 If pattern is given, only those names
	      matching pattern are returned.  Matching is determined using the
	      same rules as for	string match.

       info hostname
	      Returns the name of the current host.

	      This  name  is  not  guaranteed to be the	fully-qualified	domain
	      name of the host.	 Where machines	have several different	names,
	      as is common on systems with both	TCP/IP (DNS) and NetBIOS-based
	      networking installed, it is the name that	is suitable for	TCP/IP
	      networking that is returned.

       info level ?level?
	      If  number is not	given, the level this routine was called from.
	      Otherwise	returns	the  complete  command	active	at  the	 given
	      level.   If  number  is greater than 0, it is the	desired	level.
	      Otherwise, it is number levels up	from  the  current  level.   A
	      complete	command	is the words in	the command, with all subsitu-
	      tions performed, meaning that it is a  list.   See  uplevel  for
	      more information on levels.

       info library
	      Returns  the  value of tcl_library, which	is the name of the li-
	      brary directory  in  which  the  scripts	distributed  with  Tcl
	      scripts are stored.

       info loaded ?interp? ?package?
	      Returns  the  name of each file loaded in	interp va load as part
	      of package .  If package is not given, returns a list where each
	      item  is the name	of the loaded file and the name	of the package
	      for which	the file was loaded.  For a statically-loaded  package
	      the  name	of the file is the empty string.  For nterp, the empty
	      string is	the current interpreter.

       info locals ?pattern?
	      If pattern is given, returns the name  of	 each  local  variable
	      matching	pattern	according to string match.  Otherwise, returns
	      the name of each local variable.	A variables defined  with  the
	      global, upvar or variable	is not local.

       info nameofexecutable
	      Returns the absolute pathname of the program for the current in-
	      terpreter.  If such a file can not be identified an empty	string
	      is returned.

       info object subcommand object ?arg ...
	      Returns information about	the object named object. subcommand is
	      described	OBJECT INTROSPECTION below.

       info patchlevel
	      Returns the value	of  the	 global	 variable  tcl_patchLevel,  in
	      which the	exact version of the Tcl library initially stored.

       info procs ?pattern?
	      Returns  the  names  of  all  visible  procedures. If pattern is
	      given, returns only those	names that match according  to	string
	      match.   Only the	final component	in pattern is actually consid-
	      ered a pattern.  Any qualifying components simply	select a name-
	      space.   See NAMESPACE RESOLUTION	in the namespace(n) documenta-
	      tion.

       info script ?filename?
	      Returns the pathname of the  innermost  script  currently	 being
	      evaluated, or the	empty string if	no pathname can	be determined.
	      If filename is given, sets the return value of any future	 calls
	      to  info script for the duration of the innermost	active script.
	      This is useful in	virtual	file system applications.

       info sharedlibextension
	      Returns the extension used on this platform for names of	shared
	      libraries, e.g.  .so under Solaris.  Returns the empty string if
	      shared libraries are not supported on this platform.

       info tclversion
	      Returns the value	of the global variable tcl_version,  in	 which
	      the major	and minor version of the Tcl library are stored.

       info vars ?pattern?
	      If  pattern is not given,	returns	the names of all visible vari-
	      ables.  If pattern is given, returns only	those names that match
	      according	 to  string match.  Only the last component of pattern
	      is a pattern.  Other components identify a namespace.  See NAME-
	      SPACE  RESOLUTION	 in the	namespace(n) documentation.  When pat-
	      tern is a	qualified name,	results	are fully qualified.

	      A	variable that has declared but not yet defined is included  in
	      the results.

   CLASS INTROSPECTION
       The following subcommand	values are supported by	info class:

       info class call class method
	      Returns  a  description  of  the method implementations that are
	      used to provide a	stereotypical instance of class's  implementa-
	      tion  of method (stereotypical instances being objects instanti-
	      ated by a	class without having any  object-specific  definitions
	      added). This consists of a list of lists of four elements, where
	      each sublist consists of a word that describes the general  type
	      of  method  implementation  (being one of	method for an ordinary
	      method, filter for an applied  filter,  private  for  a  private |
	      method,  and unknown for a method	that is	invoked	as part	of un-
	      known method handling), a	word giving the	name of	the particular
	      method  invoked  (which  is  always  the	same as	method for the
	      method type, and "unknown" for the unknown type),	a word	giving
	      the  fully  qualified name of the	class that defined the method,
	      and a word describing the	type  of  method  implementation  (see
	      info class methodtype).

	      Note that	there is no inspection of whether the method implemen-
	      tations actually use next	to transfer  control  along  the  call
	      chain,  and the call chains that this command files do not actu- |
	      ally contain private methods.

       info class constructor class
	      This subcommand returns a	description of the definition  of  the
	      constructor of class class. The definition is described as a two
	      element list; the	first element is the list of arguments to  the
	      constructor  in  a  form suitable	for passing to another call to
	      proc or a	method definition, and the second element is the  body
	      of  the  constructor. If no constructor is present, this returns
	      the empty	list.

       info class definition class method
	      This subcommand returns a	description of the definition  of  the
	      method  named method of class class. The definition is described
	      as a two element list; the first element is the  list  of	 argu-
	      ments  to	 the  method in	a form suitable	for passing to another
	      call to proc or a	method definition, and the second  element  is
	      the body of the method.

       info class definitionnamespace class ?kind?
	      This  subcommand returns the definition namespace	for kind defi- |
	      nitions of the class class; the definition  namespace  only  af- |
	      fects  the instances of class, not class itself. The kind	can be |
	      either -class  to	 return	 the  definition  namespace  used  for |
	      oo::define, or -instance to return the definition	namespace used |
	      for oo::objdefine; the -class kind is default  (though  this  is |
	      only   actually	useful	on  classes  that  are	subclasses  of |
	      oo::class).						       |

	      If class does not	provide	a definition namespace	of  the	 given |
	      kind,  this  command  returns the	empty string. In those circum- |
	      stances, the oo::define and oo::objdefine	commands look up which |
	      definition  namespace to use using the class inheritance hierar- |
	      chy.							       |

       info class destructor class
	      This subcommand returns the body	of  the	 destructor  of	 class
	      class.  If  no  destructor  is  present,	this returns the empty
	      string.

       info class filters class
	      This subcommand returns the list of filter methods  set  on  the
	      class.

       info class forward class	method
	      This  subcommand	returns	 the argument list for the method for-
	      warding called method that is set	on the class called class.

       info class instances class ?pattern?
	      This subcommand returns a	list of	instances of class  class.  If
	      the optional pattern argument is present,	it constrains the list
	      of returned instances to those that match	it  according  to  the
	      rules of string match.

       info class methods class	?options...?
	      This  subcommand	returns	 a  list of all	public (i.e. exported)
	      methods of the class called class. Any of	the following  options
	      may  be  given,  controlling  exactly which method names are re-
	      turned:

	      -all   If	the -all flag is given,	and the	 -scope	 flag  is  not |
		     given, the	list of	methods	will include those methods de-
		     fined not just by the class, but also by the class's  su-
		     perclasses	and mixins.

	      -private
		     If	the -private flag is given, and	the -scope flag	is not |
		     given, the	list of	methods	will also include the  non-ex-
		     ported methods of the class (and superclasses and mixins,
		     if	-all is	also given).  Note that	this naming is an  un- |
		     fortunate	clash  with  true private methods; this	option |
		     name is retained for backward compatibility.

	      -scope scope
		     Returns a list of all methods  on	class  that  have  the |
		     given  visibility	scope.	 When this option is supplied, |
		     both the -all and -private	options	are ignored. The valid |
		     values for	scope are:				       |

		     public						       |
			Only  methods  with  public scope (i.e., callable from |
			anywhere by any	instance of this class)	are to be  re- |
			turned.						       |

		     unexported						       |
			Only   methods	 with  unexported  scope  (i.e.,  only |
			callable via my) are to	be returned.		       |

		     private						       |
			Only methods with private scope	(i.e.,	only  callable |
			from within this class's methods) are to be returned.  |

       info class methodtype class method
	      This subcommand returns a	description of the type	of implementa-
	      tion used	for the	method named method of class class.  When  the
	      result  is  method,  further  information	can be discovered with
	      info class definition, and when the result is  forward,  further
	      information can be discovered with info class forward.

       info class mixins class
	      This  subcommand	returns	 a  list of all	classes	that have been
	      mixed into the class named class.

       info class subclasses class ?pattern?
	      This subcommand returns a	list of	 direct	 subclasses  of	 class
	      class.  If  the  optional	 pattern  argument is present, it con-
	      strains the list of returned classes to those that match it  ac-
	      cording to the rules of string match.

       info class superclasses class
	      This  subcommand	returns	a list of direct superclasses of class
	      class in inheritance precedence order.

       info class variables class ?-private?
	      This subcommand returns a	list of	all variables that  have  been
	      declared	for the	class named class (i.e.	that are automatically
	      present in the class's methods, constructor and destructor).  If |
	      the  -private  option is given, this lists the private variables |
	      declared instead.

   OBJECT INTROSPECTION
       The following subcommand	values are supported by	info object:

       info object call	object method
	      Returns a	description of the  method  implementations  that  are
	      used  to	provide	 object's implementation of method.  This con-
	      sists of a list of lists of four elements,  where	 each  sublist
	      consists of a word that describes	the general type of method im-
	      plementation (being one of method	for an ordinary	method,	filter
	      for an applied filter, private for a private method, and unknown |
	      for a method that	is invoked as  part  of	 unknown  method  han-
	      dling),  a word giving the name of the particular	method invoked
	      (which is	always the same	as method for  the  method  type,  and
	      "unknown"	 for the unknown type),	a word giving what defined the
	      method (the fully	qualified name of the class,  or  the  literal
	      string  object  if the method implementation is on an instance),
	      and a word describing the	type  of  method  implementation  (see
	      info object methodtype).

	      Note that	there is no inspection of whether the method implemen-
	      tations actually use next	to transfer  control  along  the  call
	      chain,  and the call chains that this command files do not actu- |
	      ally contain private methods.

       info object class object	?className?
	      If className is not given, this subcommand returns class of  the
	      object  object. If className is present, this subcommand returns
	      a	boolean	value indicating whether the object is of that class.

       info object creationid object
	      Returns the unique creation identifier for  the  object  object. |
	      This  creation  identifier is unique to the object (within a Tcl |
	      interpreter) and cannot be controlled at object creation time or |
	      altered afterwards.					       |

	      Implementation note: the creation	identifier is used to generate |
	      unique identifiers associated with the  object,  especially  for |
	      private variables.					       |

       info object definition object method
	      This  subcommand	returns	a description of the definition	of the
	      method named method of object  object.  The  definition  is  de-
	      scribed  as a two	element	list; the first	element	is the list of
	      arguments	to the method in a form	suitable for  passing  to  an-
	      other  call  to proc or a	method definition, and the second ele-
	      ment is the body of the method.

       info object filters object
	      This subcommand returns the list of filter methods  set  on  the
	      object.

       info object forward object method
	      This  subcommand	returns	 the argument list for the method for-
	      warding called method that is set	on the object called object.

       info object isa category	object ?arg?
	      This subcommand tests whether an object belongs to a  particular
	      category,	 returning  a boolean value that indicates whether the
	      object argument meets the	criteria for the  category.  The  sup-
	      ported categories	are:

	      info object isa class object
		     This  returns whether object is a class (i.e. an instance
		     of	oo::class or one of its	subclasses).

	      info object isa metaclass	object
		     This returns whether object is a class that can  manufac-
		     ture classes (i.e.	is oo::class or	a subclass of it).

	      info object isa mixin object class
		     This returns whether class	is directly mixed into object.

	      info object isa object object
		     This returns whether object really	is an object.

	      info object isa typeof object class
		     This  returns  whether  class is the type of object (i.e.
		     whether object is an instance of class or one of its sub-
		     classes, whether direct or	indirect).

       info object methods object ?option...?
	      This  subcommand	returns	 a  list of all	public (i.e. exported)
	      methods of the object called object. Any of  the	following  op-
	      tions  may  be given, controlling	exactly	which method names are
	      returned:

	      -all   If	the -all flag is given,	and the	 -scope	 flag  is  not |
		     given, the	list of	methods	will include those methods de-
		     fined not just by the object, but also  by	 the  object's
		     class and mixins, plus the	superclasses of	those classes.

	      -private
		     If	the -private flag is given, and	the -scope flag	is not |
		     given, the	list of	methods	will also include the  non-ex-
		     ported  methods  of  the  object (and classes, if -all is
		     also given).  Note	that this  naming  is  an  unfortunate |
		     clash  with true private methods; this option name	is re- |
		     tained for	backward compatibility.

	      -scope scope
		     Returns a list of all methods on  object  that  have  the |
		     given  visibility	scope.	 When this option is supplied, |
		     both the -all and -private	options	are ignored. The valid |
		     values for	scope are:				       |

		     public						       |
			Only  methods  with  public scope (i.e., callable from |
			anywhere) are to be returned.			       |

		     unexported						       |
			Only  methods  with  unexported	 scope	 (i.e.,	  only |
			callable via my) are to	be returned.		       |

		     private						       |
			Only  methods  with private scope (i.e., only callable |
			from within this object's instance methods) are	to  be |
			returned.					       |

       info object methodtype object method
	      This subcommand returns a	description of the type	of implementa-
	      tion used	for the	method named method of object object. When the
	      result  is  method,  further  information	can be discovered with
	      info object definition, and when the result is forward,  further
	      information can be discovered with info object forward.

       info object mixins object
	      This  subcommand	returns	 a  list of all	classes	that have been
	      mixed into the object named object.

       info object namespace object
	      This subcommand returns the name of the  internal	 namespace  of
	      the object named object.

       info object variables objectR ?-private?
	      This  subcommand	returns	a list of all variables	that have been
	      declared for the object named object (i.e.  that	are  automati-
	      cally  present in	the object's methods).	If the -private	option |
	      is given,	this lists the private variables declared instead.

       info object vars	object ?pattern?
	      This subcommand returns a	list of	all variables in  the  private
	      namespace	 of  the  object named object. If the optional pattern
	      argument is given, it is a filter	(in the	 syntax	 of  a	string
	      match  glob  pattern)  that constrains the list of variables re-
	      turned. Note that	this is	different from the  list  returned  by
	      info  object variables; that can include variables that are cur-
	      rently unset, whereas this can include variables	that  are  not
	      automatically  included  by any of object's methods (or those of
	      its class, superclasses or mixins).

EXAMPLES
       This command prints out a  procedure  suitable  for  saving  in	a  Tcl
       script:

	      proc printProc {procName}	{
		  set result [list proc	$procName]
		  set formals {}
		  foreach var [info args $procName] {
		      if {[info	default	$procName $var def]} {
			  lappend formals [list	$var $def]
		      }	else {
			  # Still need the list-quoting	because	variable
			  # names may properly contain spaces.
			  lappend formals [list	$var]
		      }
		  }
		  puts [lappend	result $formals	[info body $procName]]
	      }

   EXAMPLES WITH OBJECTS
       Every  object  necessarily knows	what its class is; this	information is
       trivially extractable through introspection:

	      oo::class	create c
	      c	create o
	      puts [info object	class o]
				   -_ prints "::c"
	      puts [info object	class c]
				   -_ prints "::oo::class"

       The introspection capabilities can be used to discover what  class  im-
       plements	a method and get how it	is defined. This procedure illustrates
       how:

	      proc getDef {obj method} {
		  foreach inf [info object call	$obj $method] {
		      lassign $inf calltype name locus methodtype

		      #	Assume no forwards or filters, and hence no $calltype
		      #	or $methodtype checks...

		      if {$locus eq "object"} {
			  return [info object definition $obj $name]
		      }	else {
			  return [info class definition	$locus $name]
		      }
		  }
		  error	"no definition for $method"
	      }

       This is an alternate way	of looking up the  definition;	it  is	imple-
       mented  by  manually  scanning  the  list of methods up the inheritance
       tree. This code assumes that only single	inheritance  is	 in  use,  and
       that  there is no complex use of	mixed-in classes (in such cases, using
       info object call	as above is the	simplest way of	doing this by far):

	      proc getDef {obj method} {
		  if {$method in [info object methods $obj]} {
		      #	Assume no forwards
		      return [info object definition $obj $method]
		  }

		  set cls [info	object class $obj]

		  while	{$method ni [info class	methods	$cls]} {
		      #	Assume the simple case
		      set cls [lindex [info class superclass $cls] 0]
		      if {$cls eq ""} {
			  error	"no definition for $method"
		      }
		  }

		  # Assume no forwards
		  return [info class definition	$cls $method]
	      }

SEE ALSO
       global(n),   oo::class(n),   oo::define(n),   oo::object(n),   proc(n),
       self(n),	tcl_library(n),	tcl_patchLevel(n), tcl_version(n)

KEYWORDS
       command,	information, interpreter, introspection, level,	namespace, ob-
       ject, procedure,	variable

Tcl				      8.4			       info(n)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=info.tcl87&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help