Provided by: tcl8.6-doc_8.6.14+dfsg-1build1_all bug

NAME

       info - Return information about the state of the Tcl interpreter

SYNOPSIS

       info option ?arg arg ...?
_________________________________________________________________________________________________

DESCRIPTION

       This  command  provides  information  about various internals of the Tcl interpreter.  The
       legal options (which may be abbreviated) are:

       info args procname
              Returns a list containing the names of the  arguments  to  procedure  procname,  in
              order.  Procname must be the name of a Tcl command procedure.

       info body procname
              Returns the body of procedure procname.  Procname must be the name of a Tcl command
              procedure.

       info class subcommand class ?arg ...
              Returns information about the class, class. The subcommands are described in  CLASSINTROSPECTION below.

       info cmdcount
              Returns  a  count  of  the  total number of commands that have been invoked in this
              interpreter.

       info commands ?pattern?
              If pattern is not specified, returns a list  of  names  of  all  the  Tcl  commands
              visible  (i.e. executable without using a qualified name) to the current namespace,
              including both the built-in commands  written  in  C  and  the  command  procedures
              defined using the proc command.  If pattern is specified, only those names matching
              pattern are returned.  Matching is determined using the same rules  as  for  string
              match.   pattern can be a qualified name like Foo::print*.  That is, it may specify
              a particular namespace using a sequence of  namespace  names  separated  by  double
              colons (::), and may have pattern matching special characters at the end to specify
              a set of commands in that namespace.  If pattern is a qualified name, the resulting
              list  of  command  names  has  each  one  qualified  with the name of the specified
              namespace, and only the commands defined in the named namespace are returned.

       info complete command
              Returns 1 if command is a complete Tcl command in the sense of having  no  unclosed
              quotes, braces, brackets or array element names.  If the command does not appear to
              be complete then 0 is returned.  This command is typically  used  in  line-oriented
              input environments to allow users to type in commands that span multiple lines;  if
              the command is not complete, the script can delay evaluating  it  until  additional
              lines have been typed to complete the command.

       info coroutine
              Returns  the  name  of  the  currently  executing coroutine, or the empty string if │
              either no coroutine is currently executing,  or  the  current  coroutine  has  been │
              deleted (but has not yet returned or yielded since deletion).

       info default procname arg varname
              Procname must be the name of a Tcl command procedure and arg must be the name of an
              argument to that procedure.  If arg does not have a default value then the  command
              returns  0.   Otherwise  it  returns  1  and  places  the default value of arg into
              variable varname.

       info errorstack ?interp?
              Returns, in a form that is programmatically easy to parse, the function  names  and │
              arguments  at each level from the call stack of the last error in the given interp, │
              or in the current one if not specified.                                             │

              This form is an even-sized list  alternating  tokens  and  parameters.  Tokens  are │
              currently  either  CALL,  UP,  or  INNER, but other values may be introduced in the │
              future. CALL indicates a procedure 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 innermost atomic command or │
              bytecode  instruction  that  raised  the  error,  along  with  its  arguments  when │
              available.  While CALL and UP allow to follow complex call paths, INNER homes in on │
              the offending operation in  the  innermost  procedure  call,  even  going  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 tclsh.                           │

       info exists varName
              Returns  1 if the variable named varName exists in the current context (either as a
              global or local variable) and has been defined by being given a  value,  returns  0
              otherwise.

       info frame ?number?
              This  command  provides  access  to all frames on the stack, even those hidden from
              info level. If number is not specified, this command returns a  number  giving  the
              frame  level  of  the command. This is 1 if the command is invoked at top-level. If
              number is specified, then the  result  is  a  dictionary  containing  the  location
              information for the command at the numbered level on the stack.

              If  number  is positive (> 0) then it selects a particular stack level (1 refers to
              the outer-most active command, 2 to the command it called, and so  on,  up  to  the
              current  frame level which refers to info frame itself); otherwise it gives a level
              relative to the current command (0 refers to the current command, i.e., info  frame
              itself, -1 to its caller, and so on).

              This  is  similar  to how info level works, except that this subcommand reports all
              frames, like sourced scripts, evals, uplevels, etc.

              Note that for nested commands, like “foo [bar [x]]”, only “x” will be  seen  by  an
              info  frame invoked within “x”.  This is the same as for info level and error stack
              traces.

              The result dictionary may  contain  the  keys  listed  below,  with  the  specified
              meanings for their values:

              type   This  entry  is  always present and describes the nature of the location for
                     the command. The recognized values are source, proc, eval, and precompiled.

                     source
                            means that the command is found in a  script  loaded  by  the  source
                            command.

                     proc
                            means  that  the  command  is  found in dynamically created procedure
                            body.

                     eval
                            means that the command is executed by eval or uplevel.

                     precompiled
                            means that the command is found in a precompiled script (loadable  by
                            the package tbcload), and no further information will be available.

              line   This  entry  provides the number of the line the command is at inside of the
                     script  it  is  a  part  of.  This  information  is  not  present  for  type
                     precompiled.  For  type  source  this information is counted relative to the
                     beginning of the file, whereas for the last two types the  line  is  counted
                     relative to the start of the script.

              file   This  entry is present only for type source. It provides the normalized path
                     of the file the command is in.

              cmd    This entry provides the  string  representation  of  the  command.  This  is
                     usually   the   unsubstituted   form,  however  for  commands  which  are  a
                     canonically-constructed  list  (e.g.,  as  produced  by  the  list  command)
                     executed  by  eval  it  is the substituted form as they have no other string
                     representation. Care is taken that the canonicality property of  the  latter
                     is not spoiled.

              proc   This  entry is present only if the command is found in the body of a regular
                     Tcl procedure. It then provides the name of that procedure.

              lambda This entry is present only if the  command  is  found  in  the  body  of  an
                     anonymous  Tcl  procedure,  i.e.  a  lambda.  It  then  provides  the entire
                     definition of the lambda in question.

              level  This entry is present only if the queried frame has  a  corresponding  frame
                     returned by info level. It provides the index of this frame, relative to the
                     current level (0 and negative numbers).

              A thing of note is that for procedures statically defined in files the locations of
              commands  in  their  bodies  will  be  reported  with type source and absolute line
              numbers, and not as type proc. The same is true for procedures nested in statically
              defined  procedures,  and  literal  eval  scripts  in  files  or statically defined
              procedures.

              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 usually 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  possible 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  specified, returns a list of all the math functions currently
              defined.  If pattern is specified, only those functions whose name matches  pattern
              are returned.  Matching is determined using the same rules as for string match.

       info globals ?pattern?
              If  pattern  is not specified, returns a list of all the names of currently-defined
              global variables.  Global variables are variables  in  the  global  namespace.   If
              pattern  is specified, 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 computer on which this invocation is being executed.   Note
              that 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 ?number?
              If number is not specified, this command returns a number giving the stack level of
              the  invoking procedure, or 0 if the command is invoked at top-level.  If number is
              specified, then the result is a list consisting of the name and arguments  for  the
              procedure call at level number on the stack.  If number is positive then it selects
              a particular stack level (1 refers to the  top-most  active  procedure,  2  to  the
              procedure it called, and so on); otherwise it gives a level relative to the current
              level (0 refers to the current procedure, -1 to its caller, and so  on).   See  the
              uplevel command for more information on what stack levels mean.

       info library
              Returns the name of the library directory in which standard Tcl scripts are stored.
              This is actually the value of the  tcl_library  variable  and  may  be  changed  by
              setting tcl_library.

       info loaded ?interp?
              Returns  a  list  describing  all of the packages that have been loaded into interp
              with the load  command.   Each  list  element  is  a  sub-list  with  two  elements
              consisting  of  the name of the file from which the package was loaded and the name
              of the package.  For statically-loaded packages the file  name  will  be  an  empty
              string.   If interp is omitted then information is returned for all packages loaded
              in any interpreter in the process.  To get a list  of  just  the  packages  in  the
              current interpreter, specify an empty string for the interp argument.

       info locals ?pattern?
              If  pattern  is not specified, returns a list of all the names of currently-defined
              local variables, including arguments to the current procedure, if  any.   Variables
              defined  with  the  global,  upvar  and variable commands will not be returned.  If
              pattern is specified, only those names matching pattern are returned.  Matching  is
              determined using the same rules as for string match.

       info nameofexecutable
              Returns  the  full  path  name  of  the  binary file from which the application was
              invoked.  If Tcl was unable to identify the file, then an empty string is returned.

       info object subcommand object ?arg ...
              Returns information about the object, object.  The  subcommands  are  described  in │
              OBJECT INTROSPECTION below.

       info patchlevel
              Returns  the  value  of  the  global variable tcl_patchLevel, which holds the exact
              version of the Tcl library by default.

       info procs ?pattern?
              If pattern is not specified, returns a  list  of  all  the  names  of  Tcl  command
              procedures in the current namespace.  If pattern is specified, only those procedure
              names in  the  current  namespace  matching  pattern  are  returned.   Matching  is
              determined  using  the  same  rules  as  for string match.  If pattern contains any
              namespace separators, they are used to select a namespace relative to  the  current
              namespace  (or relative to the global namespace if pattern starts with ::) to match
              within; the matching pattern is taken to be  the  part  after  the  last  namespace
              separator.

       info script ?filename?
              If  a  Tcl  script  file  is  currently  being  evaluated  (i.e. there is a call to
              Tcl_EvalFile active or there is an active invocation of the source  command),  then
              this  command  returns the name of the innermost file being processed.  If filename
              is specified, then the return value of  this  command  will  be  modified  for  the
              duration  of  the active invocation to return that name.  This is useful in virtual
              file system applications.  Otherwise the command returns an empty string.

       info sharedlibextension
              Returns the extension used on this platform  for  the  names  of  files  containing
              shared  libraries  (for  example,  .so under Solaris).  If shared libraries are not
              supported on this platform then an empty string is returned.

       info tclversion
              Returns the value of the global variable tcl_version, which  holds  the  major  and
              minor version of the Tcl library by default.

       info vars ?pattern?
              If  pattern  is not specified, returns a list of all the names of currently-visible
              variables.  This includes locals and  currently-visible  globals.   If  pattern  is
              specified,  only those names matching pattern are returned.  Matching is determined
              using the same rules as for string match.  pattern can be  a  qualified  name  like
              Foo::option*.   That  is, it may specify a particular namespace using a sequence of
              namespace names separated by double colons (::),  and  may  have  pattern  matching
              special  characters at the end to specify a set of variables in that namespace.  If
              pattern is a qualified name, the resulting list of variable names has each matching
              namespace  variable  qualified  with  the  name  of  its  namespace.   Note  that a
              currently-visible variable may not yet “exist” if it  has  not  been  set  (e.g.  a
              variable declared but not set by variable).

   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 implementation of method (stereotypical instances │
              being   objects   instantiated  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,  and │
              unknown  for  a  method that is invoked as part of unknown 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 implementations actually use │
              next to transfer control along the call chain.                                      │

       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 arguments 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 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 forwarding 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 specified, controlling exactly │
              which method names are returned:                                                    │

              -all   If the -all flag is given, the list of methods will  include  those  methods │
                     defined  not  just  by  the  class, but also by the class's superclasses and │
                     mixins.

              -private
                     If the -private flag is given, the list of methods  will  also  include  the │
                     private  (i.e.  non-exported)  methods  of  the  class (and superclasses and │
                     mixins, if -all is also given).                                              │

       info class methodtype class method
              This subcommand returns a description of the type of implementation  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 constrains the list of returned classes to those │
              that match it according 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
              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).                                                        │

   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 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, and unknown for a method that is invoked as part of unknown 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 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 implementations actually use │
              next to transfer control along the call chain.                                      │

       info object class object ?className?
              If className is unspecified, 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 definition object method
              This  subcommand returns a description of the definition of the method named method │
              of object object. The definition is described as a  two  element  list;  the  first │
              element  is  the  list of arguments 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 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 forwarding 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 supported 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 manufacture 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 subclasses, 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 options may be specified,  controlling  exactly │
              which method names are returned:                                                    │

              -all   If  the  -all  flag is given, the list of methods will include those methods │
                     defined 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, the list of methods will also include the │
                     private (i.e. non-exported) methods of the object (and classes, if  -all  is │
                     also given).                                                                 │

       info object methodtype object method
              This  subcommand  returns  a description of the type of implementation 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 object
              This subcommand returns a list of all variables that have  been  declared  for  the │
              object named object (i.e. that are automatically present in the object's methods).

       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 │
              returned. Note that this is  different  from  the  list  returned  by  info  objectvariables;  that  can  include variables that are currently 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 implements 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 implemented 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(3tcl), oo::class(3tcl), oo::define(3tcl), oo::object(3tcl), proc(3tcl), self(3tcl), │
       tcl_library(3tcl), tcl_patchLevel(3tcl), tcl_version(3tcl)

KEYWORDS

       command,  information,  interpreter,  introspection,  level, namespace, object, procedure, │
       variable