Scroll to navigation

info(3tcl) Tcl Built-In Commands info(3tcl) 





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:



  

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

  

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

  

  
Returns information about the class, class. The subcommands
      are described in CLASS INTROSPECTION below.

  

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

  

  
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.

  

  
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.

  

  
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).

  

  
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.

  

  
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.





  

  
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.

  

  
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:



  

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







  

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

  

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

  

  
means that the command is executed by eval or uplevel.

  

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







  

  
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.

  

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

  

  
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.

  

  
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.

  

  
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.

  

  
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)





  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
Returns information about the object, object. The
      subcommands are described in OBJECT INTROSPECTION
    below.

  

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

  

  
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.

  

  
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.

  

  
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.

  

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

  

  
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:



  

  
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.





  

  
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.

  

  
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.

  

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

  

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

  

  
This subcommand returns the argument list for the method forwarding called
      method that is set on the class called class.

  

  
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.

  

  
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:







  

  
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.

  

  
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).







  

  
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.

  

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

  

  
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.

  

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

  

  
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:



  

  
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.





  

  
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.

  

  
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.

  

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

  

  
This subcommand returns the argument list for the method forwarding called
      method that is set on the object called object.

  

  
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:







  

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

  

  
This returns whether object is a class that can manufacture classes
      (i.e. is oo::class or a subclass of it).

  

  
This returns whether class is directly mixed into
    object.

  

  
This returns whether object really is an object.

  

  
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).







  

  
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:







  

  
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.

  

  
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).







  

  
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.

  

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

  

  
This subcommand returns the name of the internal namespace of the object
      named 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).

  

  
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 object variables; 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







  

    8.4
    Tcl