1info(n)                      Tcl Built-In Commands                     info(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       info - Return information about the state of the Tcl interpreter
9

SYNOPSIS

11       info option ?arg arg ...?
12______________________________________________________________________________
13

DESCRIPTION

15       This  command  provides  information about various internals of the Tcl
16       interpreter.  The legal options (which may be abbreviated) are:
17
18       info args procname
19              Returns a list containing the names of the arguments  to  proce‐
20              dure  procname,  in  order.   Procname must be the name of a Tcl
21              command procedure.
22
23       info body procname
24              Returns the body of procedure procname.  Procname  must  be  the
25              name of a Tcl command procedure.
26
27       info class subcommand class ?arg ...
28              Returns  information about the class, class. The subcommands are │
29              described in CLASS INTROSPECTION below.
30
31       info cmdcount
32              Returns a count of the total number of commands that  have  been
33              invoked in this interpreter.
34
35       info commands ?pattern?
36              If  pattern is not specified, returns a list of names of all the
37              Tcl commands visible (i.e. executable without using a  qualified
38              name) to the current namespace, including both the built-in com‐
39              mands written in C and the command procedures defined using  the
40              proc  command.  If pattern is specified, only those names match‐
41              ing pattern are returned.  Matching is determined using the same
42              rules as for string match.  pattern can be a qualified name like
43              Foo::print*.  That is, it may  specify  a  particular  namespace
44              using  a  sequence of namespace names separated by double colons
45              (::), and may have pattern matching special  characters  at  the
46              end  to specify a set of commands in that namespace.  If pattern
47              is a qualified name, the resulting list  of  command  names  has
48              each one qualified with the name of the specified namespace, and
49              only the commands defined in the named namespace are returned.
50
51       info complete command
52              Returns 1 if command is a complete Tcl command in the  sense  of
53              having  no  unclosed  quotes,  braces, brackets or array element
54              names.  If the command does not appear to be complete then 0  is
55              returned.  This command is typically used in line-oriented input
56              environments to allow users to type in commands that span multi‐
57              ple lines;  if the command is not complete, the script can delay
58              evaluating it until additional lines have been typed to complete
59              the command.
60
61       info coroutine
62              Returns  the  name  of the currently executing coroutine, or the │
63              empty string if either no coroutine is currently  executing,  or │
64              the current coroutine has been deleted (but has not yet returned │
65              or yielded since deletion).
66
67       info default procname arg varname
68              Procname must be the name of a Tcl  command  procedure  and  arg
69              must  be the name of an argument to that procedure.  If arg does
70              not have a default value then the command returns 0.   Otherwise
71              it  returns  1 and places the default value of arg into variable
72              varname.
73
74       info errorstack ?interp?
75              Returns, in a form that is programmatically easy to  parse,  the │
76              function  names  and arguments at each level from the call stack │
77              of the last error in the given interp, or in the current one  if │
78              not specified.                                                   │
79
80              This  form  is an even-sized list alternating tokens and parame‐ │
81              ters. Tokens are currently either CALL, UP, or INNER, but  other │
82              values  may be introduced in the future. CALL indicates a proce‐ │
83              dure call, and its parameter is the corresponding info level  0. │
84              UP  indicates a shift in variable frames generated by uplevel or │
85              similar, and applies to the previous CALL item. Its parameter is │
86              the level offset. INNER identifies the “inner context”, which is │
87              the innermost atomic command or bytecode instruction that raised │
88              the  error,  along with its arguments when available. While CALL 
89              and UP allow to follow complex call paths, INNER homes in on the │
90              offending  operation in the innermost procedure call, even going │
91              to sub-expression granularity.                                   │
92
93              This information is also present in the -errorstack entry of the │
94              options dictionary returned by 3-argument catch; info errorstack 
95              is a convenient way of retrieving it for uncaught errors at top- │
96              level in an interactive tclsh.                                   │
97
98       info exists varName
99              Returns  1  if  the variable named varName exists in the current
100              context (either as a global or  local  variable)  and  has  been
101              defined by being given a value, returns 0 otherwise.
102
103       info frame ?number?
104              This  command  provides  access to all frames on the stack, even
105              those hidden from info level. If number is not  specified,  this
106              command  returns a number giving the frame level of the command.
107              This is 1 if the command is invoked at top-level. If  number  is
108              specified,  then the result is a dictionary containing the loca‐
109              tion information for the command at the numbered  level  on  the
110              stack.
111
112              If  number  is positive (> 0) then it selects a particular stack
113              level (1 refers to the outer-most active command, 2 to the  com‐
114              mand  it  called, and so on, up to the current frame level which
115              refers to info frame itself); otherwise it gives a  level  rela‐
116              tive  to  the  current command (0 refers to the current command,
117              i.e., info frame itself, -1 to its caller, and so on).
118
119              This is similar to how info level works, except that  this  sub‐
120              command   reports  all  frames,  like  sourced  scripts,  evals,
121              uplevels, etc.
122
123              Note that for nested commands, like “foo [bar  [x]]”,  only  “x”
124              will  be  seen by an info frame invoked within “x”.  This is the
125              same as for info level and error stack traces.
126
127              The result dictionary may contain the keys  listed  below,  with
128              the specified meanings for their values:
129
130              type   This  entry is always present and describes the nature of
131                     the location for the command. The recognized  values  are
132                     source, proc, eval, and precompiled.
133
134                     source
135                            means that the command is found in a script loaded
136                            by the source command.
137
138                     proc
139                            means that the command  is  found  in  dynamically
140                            created procedure body.
141
142                     eval
143                            means  that  the  command  is  executed by eval or
144                            uplevel.
145
146                     precompiled
147                            means that the command is found in a  pre-compiled
148                            script  (loadable  by the package tbcload), and no
149                            further information will be available.
150
151              line   This entry provides the number of the line the command is
152                     at inside of the script it is a part of. This information
153                     is not present for type precompiled. For type source this
154                     information  is  counted relative to the beginning of the
155                     file, whereas for the last two types the line is  counted
156                     relative to the start of the script.
157
158              file   This  entry  is present only for type source. It provides
159                     the normalized path of the file the command is in.
160
161              cmd    This entry provides the string representation of the com‐
162                     mand. This is usually the unsubstituted form, however for
163                     commands which are a canonically-constructed list  (e.g.,
164                     as  produced  by the list command) executed by eval it is
165                     the substituted form as they have no other string  repre‐
166                     sentation.  Care  is taken that the canonicality property
167                     of the latter is not spoiled.
168
169              proc   This entry is present only if the command is found in the
170                     body  of  a  regular  Tcl procedure. It then provides the
171                     name of that procedure.
172
173              lambda This entry is present only if the command is found in the
174                     body  of  an  anonymous  Tcl procedure, i.e. a lambda. It
175                     then provides the entire  definition  of  the  lambda  in
176                     question.
177
178              level  This  entry  is  present  only if the queried frame has a
179                     corresponding frame returned by info level.  It  provides
180                     the index of this frame, relative to the current level (0
181                     and negative numbers).
182
183              A thing of note is that for  procedures  statically  defined  in
184              files the locations of commands in their bodies will be reported
185              with type source and absolute line  numbers,  and  not  as  type
186              proc.  The  same  is  true  for  procedures nested in statically
187              defined procedures, and literal eval scripts in files or  stati‐
188              cally defined procedures.
189
190              In contrast, procedure definitions and eval within a dynamically
191              evaluated environment count line numbers relative to  the  start
192              of their script, even if they would be able to count relative to
193              the start of the outer dynamic script. That type of number  usu‐
194              ally makes more sense.
195
196              A  different way of describing this behaviour is that file based
197              locations are tracked as deeply as possible, and where  this  is
198              not  possible the lines are counted based on the smallest possi‐
199              ble eval or procedure body, as that scope is usually  easier  to
200              find than any dynamic outer scope.
201
202              The syntactic form {*} is handled like eval. I.e. if it is given
203              a literal list argument the system tracks the line number within
204              the  list  words  as  well,  and  otherwise all line numbers are
205              counted relative to the start of each word (smallest scope)
206
207       info functions ?pattern?
208              If pattern is not specified, returns a  list  of  all  the  math
209              functions  currently  defined.   If  pattern  is specified, only
210              those functions whose name matches pattern are returned.  Match‐
211              ing is determined using the same rules as for string match.
212
213       info globals ?pattern?
214              If  pattern is not specified, returns a list of all the names of
215              currently-defined global variables.  Global variables are  vari‐
216              ables  in  the  global namespace.  If pattern is specified, only
217              those names matching pattern are returned.  Matching  is  deter‐
218              mined using the same rules as for string match.
219
220       info hostname
221              Returns  the  name  of  the computer on which this invocation is
222              being executed.  Note that this name is not guaranteed to be the
223              fully  qualified  domain  name of the host.  Where machines have
224              several different names (as  is  common  on  systems  with  both
225              TCP/IP  (DNS) and NetBIOS-based networking installed,) it is the
226              name that is suitable for TCP/IP networking that is returned.
227
228       info level ?number?
229              If number is not specified, this command returns a number giving
230              the  stack  level of the invoking procedure, or 0 if the command
231              is invoked at top-level.   If  number  is  specified,  then  the
232              result  is  a  list consisting of the name and arguments for the
233              procedure call at level number on the stack.  If number is posi‐
234              tive  then  it selects a particular stack level (1 refers to the
235              top-most active procedure, 2 to the procedure it called, and  so
236              on); otherwise it gives a level relative to the current level (0
237              refers to the current procedure, -1 to its caller, and  so  on).
238              See  the uplevel command for more information on what stack lev‐
239              els mean.
240
241       info library
242              Returns the name of the library directory in which standard  Tcl
243              scripts   are  stored.   This  is  actually  the  value  of  the
244              tcl_library variable and may be changed by setting tcl_library.
245
246       info loaded ?interp?
247              Returns a list describing all of the  packages  that  have  been
248              loaded  into interp with the load command.  Each list element is
249              a sub-list with two elements consisting of the name of the  file
250              from  which  the package was loaded and the name of the package.
251              For statically-loaded packages the file name will  be  an  empty
252              string.   If  interp is omitted then information is returned for
253              all packages loaded in any interpreter in the process.  To get a
254              list of just the packages in the current interpreter, specify an
255              empty string for the interp argument.
256
257       info locals ?pattern?
258              If pattern is not specified, returns a list of all the names  of
259              currently-defined  local  variables,  including arguments to the
260              current procedure, if any.  Variables defined with  the  global,
261              upvar   and  variable commands will not be returned.  If pattern
262              is specified, only those names matching  pattern  are  returned.
263              Matching is determined using the same rules as for string match.
264
265       info nameofexecutable
266              Returns  the  full  path  name of the binary file from which the
267              application was invoked.  If Tcl  was  unable  to  identify  the
268              file, then an empty string is returned.
269
270       info object subcommand object ?arg ...
271              Returns  information  about  the object, object. The subcommands │
272              are described in OBJECT INTROSPECTION below.
273
274       info patchlevel
275              Returns the value of the global variable  tcl_patchLevel,  which
276              holds the exact version of the Tcl library by default.
277
278       info procs ?pattern?
279              If  pattern is not specified, returns a list of all the names of
280              Tcl command procedures in the current namespace.  If pattern  is
281              specified,  only  those procedure names in the current namespace
282              matching pattern are returned.  Matching is determined using the
283              same  rules as for string match.  If pattern contains any names‐
284              pace separators, they are used to select a namespace relative to
285              the  current  namespace  (or relative to the global namespace if
286              pattern starts with ::) to match within; the matching pattern is
287              taken to be the part after the last namespace separator.
288
289       info script ?filename?
290              If a Tcl script file is currently being evaluated (i.e. there is
291              a call to Tcl_EvalFile active or there is an  active  invocation
292              of  the  source  command), then this command returns the name of
293              the innermost file being processed.  If filename  is  specified,
294              then  the  return value of this command will be modified for the
295              duration of the active invocation to return that name.  This  is
296              useful  in virtual file system applications.  Otherwise the com‐
297              mand returns an empty string.
298
299       info sharedlibextension
300              Returns the extension used on this platform  for  the  names  of
301              files  containing  shared  libraries  (for  example,  .so  under
302              Solaris).  If shared libraries are not supported on  this  plat‐
303              form then an empty string is returned.
304
305       info tclversion
306              Returns  the  value  of  the  global variable tcl_version, which
307              holds the major and minor version of the Tcl library by default.
308
309       info vars ?pattern?
310              If pattern is not specified, returns a list of all the names  of
311              currently-visible  variables.   This  includes  locals  and cur‐
312              rently-visible globals.  If pattern  is  specified,  only  those
313              names  matching  pattern  are  returned.  Matching is determined
314              using the same rules as for string  match.   pattern  can  be  a
315              qualified  name  like  Foo::option*.   That is, it may specify a
316              particular namespace using a sequence of namespace  names  sepa‐
317              rated  by double colons (::), and may have pattern matching spe‐
318              cial characters at the end to specify a set of variables in that
319              namespace.   If  pattern is a qualified name, the resulting list
320              of variable names has each matching namespace variable qualified
321              with  the  name of its namespace.  Note that a currently-visible
322              variable may not yet “exist” if it has  not  been  set  (e.g.  a
323              variable declared but not set by variable).
324
325   CLASS INTROSPECTION
326       The following subcommand values are supported by info class:            │
327
328       info class call class method
329              Returns  a  description  of  the method implementations that are │
330              used to provide a stereotypical instance of class's  implementa‐ │
331              tion  of method (stereotypical instances being objects instanti‐ │
332              ated by a class without having any  object-specific  definitions │
333              added). This consists of a list of lists of four elements, where │
334              each sublist consists of a word that describes the general  type │
335              of  method  implementation  (being one of method for an ordinary │
336              method, filter for an applied filter, and unknown for  a  method │
337              that is invoked as part of unknown method handling), a word giv‐ │
338              ing the name of the particular method invoked (which  is  always │
339              the  same  as  method for the method type, and “unknown” for the │
340              unknown type), a word giving the fully  qualified  name  of  the │
341              class that defined the method, and a word describing the type of │
342              method implementation (see info class methodtype).               │
343
344              Note that there is no inspection of whether the method implemen‐ │
345              tations  actually  use  next  to transfer control along the call │
346              chain.                                                           │
347
348       info class constructor class
349              This subcommand returns a description of the definition  of  the │
350              constructor of class class. The definition is described as a two │
351              element list; the first element is the list of arguments to  the │
352              constructor  in  a  form suitable for passing to another call to │
353              proc or a method definition, and the second element is the  body │
354              of  the  constructor. If no constructor is present, this returns │
355              the empty list.
356
357       info class definition class method
358              This subcommand returns a description of the definition  of  the │
359              method  named method of class class. The definition is described │
360              as a two element list; the first element is the  list  of  argu‐ │
361              ments  to  the  method in a form suitable for passing to another │
362              call to proc or a method definition, and the second  element  is │
363              the body of the method.
364
365       info class destructor class
366              This  subcommand  returns  the  body  of the destructor of class │
367              class. If no destructor  is  present,  this  returns  the  empty │
368              string.
369
370       info class filters class
371              This  subcommand  returns  the list of filter methods set on the │
372              class.
373
374       info class forward class method
375              This subcommand returns the argument list for  the  method  for‐ │
376              warding called method that is set on the class called class.
377
378       info class instances class ?pattern?
379              This  subcommand  returns a list of instances of class class. If │
380              the optional pattern argument is present, it constrains the list │
381              of  returned  instances  to those that match it according to the │
382              rules of string match.
383
384       info class methods class ?options...?
385              This subcommand returns a list of  all  public  (i.e.  exported) │
386              methods  of the class called class. Any of the following options │
387              may be specified, controlling exactly  which  method  names  are │
388              returned:                                                        │
389
390              -all   If  the  -all  flag  is  given,  the list of methods will │
391                     include those methods defined not just by the class,  but │
392                     also by the class's superclasses and mixins.
393
394              -private
395                     If  the  -private flag is given, the list of methods will │
396                     also include the private (i.e. non-exported)  methods  of │
397                     the  class  (and superclasses and mixins, if -all is also │
398                     given).                                                   │
399
400       info class methodtype class method
401              This subcommand returns a description of the type of implementa‐ │
402              tion  used  for the method named method of class class. When the │
403              result is method, further information  can  be  discovered  with │
404              info  class  definition, and when the result is forward, further │
405              information can be discovered with info class forward.
406
407       info class mixins class
408              This subcommand returns a list of all  classes  that  have  been │
409              mixed into the class named class.
410
411       info class subclasses class ?pattern?
412              This  subcommand  returns  a  list of direct subclasses of class │
413              class. If the optional pattern  argument  is  present,  it  con‐ │
414              strains  the  list  of  returned  classes to those that match it │
415              according to the rules of string match.
416
417       info class superclasses class
418              This subcommand returns a list of direct superclasses  of  class │
419              class in inheritance precedence order.
420
421       info class variables class
422              This  subcommand  returns a list of all variables that have been │
423              declared for the class named class (i.e. that are  automatically │
424              present in the class's methods, constructor and destructor).     │
425
426   OBJECT INTROSPECTION                                                        
427       The following subcommand values are supported by info object:
428
429       info object call object method
430              Returns  a  description  of  the method implementations that are │
431              used to provide object's implementation of  method.   This  con‐ │
432              sists  of  a  list of lists of four elements, where each sublist │
433              consists of a word that describes the  general  type  of  method │
434              implementation (being one of method for an ordinary method, fil‐ 
435              ter for an applied filter, and unknown  for  a  method  that  is │
436              invoked  as  part of unknown method handling), a word giving the │
437              name of the particular method invoked (which is always the  same │
438              as  method  for  the  method type, and “unknown” for the unknown 
439              type), a word giving what defined the method (the  fully  quali‐ │
440              fied  name  of  the  class,  or the literal string object if the │
441              method implementation is on an instance), and a word  describing │
442              the type of method implementation (see info object methodtype).  │
443
444              Note that there is no inspection of whether the method implemen‐ │
445              tations actually use next to transfer  control  along  the  call │
446              chain.                                                           │
447
448       info object class object ?className?
449              If  className  is  unspecified, this subcommand returns class of │
450              the object object. If  className  is  present,  this  subcommand │
451              returns a boolean value indicating whether the object is of that │
452              class.
453
454       info object definition object method
455              This subcommand returns a description of the definition  of  the │
456              method   named  method  of  object  object.  The  definition  is │
457              described as a two element list; the first element is  the  list │
458              of  arguments  to  the  method in a form suitable for passing to │
459              another call to proc or a method definition, and the second ele‐ │
460              ment is the body of the method.
461
462       info object filters object
463              This  subcommand  returns  the list of filter methods set on the │
464              object.
465
466       info object forward object method
467              This subcommand returns the argument list for  the  method  for‐ │
468              warding called method that is set on the object called object.
469
470       info object isa category object ?arg?
471              This  subcommand tests whether an object belongs to a particular │
472              category, returning a boolean value that indicates  whether  the │
473              object  argument  meets  the criteria for the category. The sup‐ │
474              ported categories are:
475
476              info object isa class object
477                     This returns whether object is a class (i.e. an  instance │
478                     of oo::class or one of its subclasses).
479
480              info object isa metaclass object
481                     This  returns whether object is a class that can manufac‐ │
482                     ture classes (i.e. is oo::class or a subclass of it).
483
484              info object isa mixin object class
485                     This returns whether class is directly mixed into object. │
486
487              info object isa object object
488                     This returns whether object really is an object.          │
489
490              info object isa typeof object class
491                     This returns whether class is the type  of  object  (i.e. │
492                     whether object is an instance of class or one of its sub‐ │
493                     classes, whether direct or indirect).                     │
494
495       info object methods object ?option...?
496              This subcommand returns a list of  all  public  (i.e.  exported) │
497              methods  of  the  object  called  object.  Any  of the following │
498              options may be specified, controlling exactly which method names │
499              are returned:                                                    │
500
501              -all   If  the  -all  flag  is  given,  the list of methods will │
502                     include those methods defined not just by the object, but │
503                     also  by  the  object's class and mixins, plus the super‐ │
504                     classes of those classes.
505
506              -private
507                     If the -private flag is given, the list of  methods  will │
508                     also  include  the private (i.e. non-exported) methods of │
509                     the object (and classes, if -all is also given).          │
510
511       info object methodtype object method
512              This subcommand returns a description of the type of implementa‐ │
513              tion used for the method named method of object object. When the │
514              result is method, further information  can  be  discovered  with │
515              info  object definition, and when the result is forward, further │
516              information can be discovered with info object forward.
517
518       info object mixins object
519              This subcommand returns a list of all  classes  that  have  been │
520              mixed into the object named object.
521
522       info object namespace object
523              This  subcommand  returns  the name of the internal namespace of │
524              the object named object.
525
526       info object variables object
527              This subcommand returns a list of all variables that  have  been │
528              declared  for  the  object named object (i.e. that are automati‐ │
529              cally present in the object's methods).
530
531       info object vars object ?pattern?
532              This subcommand returns a list of all variables in  the  private │
533              namespace  of  the  object named object. If the optional pattern
534              argument is given, it is a filter (in the  syntax  of  a  string 
535              match  glob  pattern)  that  constrains  the  list  of variables │
536              returned. Note that this is different from the list returned  by │
537              info  object variables; that can include variables that are cur‐ │
538              rently unset, whereas this can include variables  that  are  not │
539              automatically  included  by any of object's methods (or those of │
540              its class, superclasses or mixins).
541

EXAMPLES

543       This command prints out a  procedure  suitable  for  saving  in  a  Tcl
544       script:
545
546              proc printProc {procName} {
547                  set result [list proc $procName]
548                  set formals {}
549                  foreach var [info args $procName] {
550                      if {[info default $procName $var def]} {
551                          lappend formals [list $var $def]
552                      } else {
553                          # Still need the list-quoting because variable
554                          # names may properly contain spaces.
555                          lappend formals [list $var]
556                      }
557                  }
558                  puts [lappend result $formals [info body $procName]]
559              }
560
561   EXAMPLES WITH OBJECTS
562       Every  object  necessarily knows what its class is; this information is │
563       trivially extractable through introspection:                            │
564
565              oo::class create c                                               │
566              c create o                                                       │
567              puts [info object class o]                                       │
568                                    prints "::c"
569              puts [info object class c]                                       │
570                                    prints "::oo::class"
571
572       The introspection capabilities can  be  used  to  discover  what  class │
573       implements  a  method  and get how it is defined. This procedure illus‐ │
574       trates how:                                                             │
575
576              proc getDef {obj method} {                                       │
577                  foreach inf [info object call $obj $method] {                │
578                      lassign $inf calltype name locus methodtype              │
579                      # Assume no forwards or filters, and hence no $calltype  │
580                      # or $methodtype checks...                               │
581                      if {$locus eq "object"} {                                │
582                          return [info object definition $obj $name]           │
583                      } else {                                                 │
584                          return [info class definition $locus $name]          │
585                      }                                                        │
586                  }                                                            │
587                  error "no definition for $method"                            │
588              }                                                                │
589
590       This is an alternate way of looking up the  definition;  it  is  imple‐ │
591       mented  by  manually  scanning  the  list of methods up the inheritance │
592       tree. This code assumes that only single inheritance  is  in  use,  and │
593       that  there is no complex use of mixed-in classes (in such cases, using │
594       info object call as above is the simplest way of doing this by far):    │
595
596              proc getDef {obj method} {                                       │
597                  if {$method in [info object methods $obj]} {                 │
598                      # Assume no forwards                                     │
599                      return [info object definition $obj $method]             │
600                  }                                                            │
601                  set cls [info object class $obj]                             │
602                  while {$method ni [info class methods $cls]} {               │
603                      # Assume the simple case                                 │
604                      set cls [lindex [info class superclass $cls] 0]          │
605                      if {$cls eq ""} {                                        │
606                          error "no definition for $method"                    │
607                      }                                                        │
608                  }                                                            │
609                  # Assume no forwards                                         │
610                  return [info class definition $cls $method]                  │
611              }                                                                │
612

SEE ALSO

614       global(n),   oo::class(n),   oo::define(n),   oo::object(n),   proc(n), │
615       self(n), tcl_library(n), tcl_patchLevel(n), tcl_version(n)
616

KEYWORDS

618       command,  information,  interpreter,  introspection,  level, namespace, │
619       object, procedure, variable
620
621
622
623Tcl                                   8.4                              info(n)
Impressum