1info(n) Tcl Built-In Commands info(n)
2______________________________________________________________________________
6
8 info - Return information about the state of the Tcl interpreter
9
11 info option ?arg arg ...?
12______________________________________________________________________________
13
15 This command provides information about various internals of the Tcl
16 interpreter. The legal options (which may be abbreviated) are:
17 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 info body procname
24 Returns the body of procedure procname. Procname must be the
25 name of a Tcl command procedure.
26 info class subcommand class ?arg ...
28 Returns information about the class, class. The subcommands are │
29 described in CLASS INTROSPECTION below.
30 info cmdcount
32 Returns a count of the total number of commands that have been
33 invoked in this interpreter.
34 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 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 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 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 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 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 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 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 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 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 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 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 The result dictionary may contain the keys listed below, with
128 the specified meanings for their values:
129 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 source
135 means that the command is found in a script loaded
136 by the source command.
137 proc
139 means that the command is found in dynamically
140 created procedure body.
141 eval
143 means that the command is executed by eval or
144 uplevel.
145 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 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 file This entry is present only for type source. It provides
159 the normalized path of the file the command is in.
160 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 info object subcommand object ?arg ...
271 Returns information about the object, object. The subcommands │
272 are described in OBJECT INTROSPECTION below.
273 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 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 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 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 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 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 CLASS INTROSPECTION
326 The following subcommand values are supported by info class: │
327 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 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 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 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 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 info class filters class
371 This subcommand returns the list of filter methods set on the │
372 class.
373 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 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 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 -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 -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 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 info class mixins class
408 This subcommand returns a list of all classes that have been │
409 mixed into the class named class.
410 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 info class superclasses class
418 This subcommand returns a list of direct superclasses of class │
419 class in inheritance precedence order.
420 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 OBJECT INTROSPECTION │
427 The following subcommand values are supported by info object:
428 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 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 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 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 info object filters object
463 This subcommand returns the list of filter methods set on the │
464 object.
465 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 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 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 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 info object isa mixin object class
485 This returns whether class is directly mixed into object. │
486 info object isa object object
488 This returns whether object really is an object. │
489 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 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 -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 -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 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 info object mixins object
519 This subcommand returns a list of all classes that have been │
520 mixed into the object named object.
521 info object namespace object
523 This subcommand returns the name of the internal namespace of │
524 the object named object.
525 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 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
543 This command prints out a procedure suitable for saving in a Tcl
544 script:
545 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 EXAMPLES WITH OBJECTS
562 Every object necessarily knows what its class is; this information is │
563 trivially extractable through introspection: │
564 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 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 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 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 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
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
618 command, information, interpreter, introspection, level, namespace, │
619 object, procedure, variable
620Tcl 8.4 info(n)