2 '\" Copyright (c) 1993 The Regents of the University of California.
3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
4 '\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies
5 '\" Copyright (c) 1998-2000 Ajuba Solutions
6 '\" Copyright (c) 2007-2012 Donal K. Fellows
8 '\" See the file "license.terms" for information on usage and redistribution
9 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
11 .TH info n 8.4 Tcl "Tcl Built-In Commands"
12 .\" The -*- nroff -*- definitions below are for supplemental macros used
13 .\" in Tcl/Tk manual entries.
15 .\" .AP type name in/out ?indent?
16 .\" Start paragraph describing an argument to a library procedure.
17 .\" type is type of argument (int, etc.), in/out is either "in", "out",
18 .\" or "in/out" to describe whether procedure reads or modifies arg,
19 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
20 .\" needed; use .AS below instead)
23 .\" Give maximum sizes of arguments for setting tab stops. Type and
24 .\" name are examples of largest possible arguments that will be passed
25 .\" to .AP later. If args are omitted, default tab stops are used.
28 .\" Start box enclosure. From here until next .BE, everything will be
29 .\" enclosed in one large box.
32 .\" End of box enclosure.
35 .\" Begin code excerpt.
40 .\" .VS ?version? ?br?
41 .\" Begin vertical sidebar, for use in marking newly-changed parts
42 .\" of man pages. The first argument is ignored and used for recording
43 .\" the version when the .VS was added, so that the sidebars can be
44 .\" found and removed when they reach a certain age. If another argument
45 .\" is present, then a line break is forced before starting the sidebar.
48 .\" End of vertical sidebar.
51 .\" Begin an indented unfilled display.
54 .\" End of indented unfilled display.
57 .\" Start of list of standard options for a Tk widget. The manpage
58 .\" argument defines where to look up the standard options; if
59 .\" omitted, defaults to "options". The options follow on successive
60 .\" lines, in three columns separated by tabs.
63 .\" End of list of standard options for a Tk widget.
65 .\" .OP cmdName dbName dbClass
66 .\" Start of description of a specific option. cmdName gives the
67 .\" option's name as specified in the class command, dbName gives
68 .\" the option's name in the option database, and dbClass gives
69 .\" the option's class in the option database.
72 .\" Print arg1 underlined, then print arg2 normally.
75 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
78 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
79 .\" (for trailing punctuation) and then a closing parenthesis.
81 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
85 .\" # Start an argument description
89 . ie !"\\$2"" .TP \\n()Cu
94 \&\\$1 \\fI\\$2\\fP (\\$3)
107 .\" # define tabbing values for .AP
110 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
113 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
114 .nr )C \\n()Bu+\\w'(in/out)'u+2n
116 .AS Tcl_Interp Tcl_CreateInterp in/out
117 .\" # BS - start boxed text
118 .\" # ^y = starting y location
126 .if n \l'\\n(.lu\(ul'
129 .\" # BE - end boxed text (draw box now)
134 .ie n \l'\\n(^lu\(ul'
136 .\" Draw four-sided box normally, but don't draw top of
137 .\" box if the box started on an earlier page.
139 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
142 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
149 .\" # VS - start vertical sidebar
150 .\" # ^Y = starting y location
151 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
155 .ie n 'mc \s12\(br\s0
158 .\" # VE - end of vertical sidebar
166 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
173 .\" # Special macro to handle page bottom: finish off current
174 .\" # box/sidebar if in box/sidebar mode, then invoked standard
175 .\" # page bottom macro.
182 .\" Draw three-sided box if this is the box's first page,
183 .\" draw two sides but no top otherwise.
184 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
188 .nr ^x \\n(^tu+1v-\\n(^Yu
189 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
202 .\" # DS - begin display
208 .\" # DE - end display
214 .\" # SO - start of list of standard options
216 'ie '\\$1'' .ds So \\fBoptions\\fR
217 'el .ds So \\fB\\$1\\fR
218 .SH "STANDARD OPTIONS"
224 .\" # SE - end of list of standard options
229 See the \\*(So manual entry for details on the standard options.
231 .\" # OP - start of full description for a single option
236 Command-Line Name: \\fB\\$1\\fR
237 Database Name: \\fB\\$2\\fR
238 Database Class: \\fB\\$3\\fR
242 .\" # CS - begin code excerpt
248 .\" # CE - end code excerpt
253 .\" # UL - underline word
257 .\" # QW - apply quotation marks to word
259 .ie '\\*(lq'"' ``\\$1''\\$2
260 .\"" fix emacs highlighting
261 .el \\*(lq\\$1\\*(rq\\$2
263 .\" # PQ - apply parens and quotation marks to word
265 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
266 .\"" fix emacs highlighting
267 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
269 .\" # QR - quoted range
271 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
272 .\"" fix emacs highlighting
273 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
275 .\" # MT - "empty" string
280 '\" Note: do not modify the .SH NAME line immediately below!
282 info \- Return information about the state of the Tcl interpreter
284 \fBinfo \fIoption \fR?\fIarg arg ...\fR?
288 This command provides information about various internals of the Tcl
290 The legal \fIoption\fRs (which may be abbreviated) are:
292 \fBinfo args \fIprocname\fR
294 Returns a list containing the names of the arguments to procedure
295 \fIprocname\fR, in order. \fIProcname\fR must be the name of a
296 Tcl command procedure.
298 \fBinfo body \fIprocname\fR
300 Returns the body of procedure \fIprocname\fR. \fIProcname\fR must be
301 the name of a Tcl command procedure.
303 \fBinfo class\fI subcommand class\fR ?\fIarg ...\fR
305 Returns information about the class, \fIclass\fR. The \fIsubcommand\fRs are
306 described in \fBCLASS INTROSPECTION\fR below.
311 Returns a count of the total number of commands that have been invoked
314 \fBinfo commands \fR?\fIpattern\fR?
316 If \fIpattern\fR is not specified,
317 returns a list of names of all the Tcl commands visible
318 (i.e. executable without using a qualified name) to the current namespace,
319 including both the built-in commands written in C and
320 the command procedures defined using the \fBproc\fR command.
321 If \fIpattern\fR is specified,
322 only those names matching \fIpattern\fR are returned.
323 Matching is determined using the same rules as for \fBstring match\fR.
324 \fIpattern\fR can be a qualified name like \fBFoo::print*\fR.
325 That is, it may specify a particular namespace
326 using a sequence of namespace names separated by double colons (\fB::\fR),
327 and may have pattern matching special characters
328 at the end to specify a set of commands in that namespace.
329 If \fIpattern\fR is a qualified name,
330 the resulting list of command names has each one qualified with the name
331 of the specified namespace, and only the commands defined in the named
332 namespace are returned.
333 .\" Technically, most of this hasn't changed; that's mostly just the
334 .\" way it always worked. Hardly anyone knew that though.
336 \fBinfo complete \fIcommand\fR
338 Returns 1 if \fIcommand\fR is a complete Tcl command in the sense of
339 having no unclosed quotes, braces, brackets or array element names.
340 If the command does not appear to be complete then 0 is returned.
341 This command is typically used in line-oriented input environments
342 to allow users to type in commands that span multiple lines; if the
343 command is not complete, the script can delay evaluating it until additional
344 lines have been typed to complete the command.
348 Returns the name of the currently executing \fBcoroutine\fR, or the empty
349 string if either no coroutine is currently executing, or the current coroutine
350 has been deleted (but has not yet returned or yielded since deletion).
353 \fBinfo default \fIprocname arg varname\fR
355 \fIProcname\fR must be the name of a Tcl command procedure and \fIarg\fR
356 must be the name of an argument to that procedure. If \fIarg\fR
357 does not have a default value then the command returns \fB0\fR.
358 Otherwise it returns \fB1\fR and places the default value of \fIarg\fR
359 into variable \fIvarname\fR.
361 \fBinfo errorstack \fR?\fIinterp\fR?
363 Returns, in a form that is programmatically easy to parse, the function names
364 and arguments at each level from the call stack of the last error in the given
365 \fIinterp\fR, or in the current one if not specified.
368 This form is an even-sized list alternating tokens and parameters. Tokens are
369 currently either \fBCALL\fR, \fBUP\fR, or \fBINNER\fR, but other values may be
370 introduced in the future. \fBCALL\fR indicates a procedure call, and its
371 parameter is the corresponding \fBinfo level\fR \fB0\fR. \fBUP\fR indicates a
372 shift in variable frames generated by \fBuplevel\fR or similar, and applies to
373 the previous \fBCALL\fR item. Its parameter is the level offset. \fBINNER\fR
375 .QW "inner context" ,
376 which is the innermost atomic command or bytecode instruction that raised the
377 error, along with its arguments when available. While \fBCALL\fR and \fBUP\fR
378 allow to follow complex call paths, \fBINNER\fR homes in on the offending
379 operation in the innermost procedure call, even going to sub-expression
382 This information is also present in the \fB\-errorstack\fR entry of the
383 options dictionary returned by 3-argument \fBcatch\fR; \fBinfo errorstack\fR
384 is a convenient way of retrieving it for uncaught errors at top-level in an
385 interactive \fBtclsh\fR.
389 \fBinfo exists \fIvarName\fR
391 Returns \fB1\fR if the variable named \fIvarName\fR exists in the
392 current context (either as a global or local variable) and has been
393 defined by being given a value, returns \fB0\fR otherwise.
395 \fBinfo frame\fR ?\fInumber\fR?
397 This command provides access to all frames on the stack, even those
398 hidden from \fBinfo level\fR. If \fInumber\fR is not specified, this
399 command returns a number giving the frame level of the command. This
400 is 1 if the command is invoked at top-level. If \fInumber\fR is
401 specified, then the result is a dictionary containing the location
402 information for the command at the \fInumber\fRed level on the stack.
405 If \fInumber\fR is positive (> 0) then it selects a particular stack
406 level (1 refers to the outer-most active command, 2 to the command it
407 called, and so on, up to the current frame level which refers to
408 \fBinfo frame\fR itself); otherwise it gives a level relative to the
409 current command (0 refers to the current command, i.e., \fBinfo
410 frame\fR itself, -1 to its caller, and so on).
412 This is similar to how \fBinfo level\fR works, except that this
413 subcommand reports all frames, like \fBsource\fRd scripts,
414 \fBeval\fRs, \fBuplevel\fRs, etc.
416 Note that for nested commands, like
417 .QW "foo [bar [x]]" ,
420 will be seen by an \fBinfo frame\fR invoked within
422 This is the same as for \fBinfo level\fR and error stack traces.
424 The result dictionary may contain the keys listed below, with the
425 specified meanings for their values:
429 This entry is always present and describes the nature of the location
430 for the command. The recognized values are \fBsource\fR, \fBproc\fR,
431 \fBeval\fR, and \fBprecompiled\fR.
434 \fBsource\fR\0\0\0\0\0\0\0\0
436 means that the command is found in a script loaded by the \fBsource\fR
439 \fBproc\fR\0\0\0\0\0\0\0\0
441 means that the command is found in dynamically created procedure body.
443 \fBeval\fR\0\0\0\0\0\0\0\0
445 means that the command is executed by \fBeval\fR or \fBuplevel\fR.
447 \fBprecompiled\fR\0\0\0\0\0\0\0\0
449 means that the command is found in a pre-compiled script (loadable by
450 the package \fBtbcload\fR), and no further information will be
456 This entry provides the number of the line the command is at inside of
457 the script it is a part of. This information is not present for type
458 \fBprecompiled\fR. For type \fBsource\fR this information is counted
459 relative to the beginning of the file, whereas for the last two types
460 the line is counted relative to the start of the script.
464 This entry is present only for type \fBsource\fR. It provides the
465 normalized path of the file the command is in.
469 This entry provides the string representation of the command. This is
470 usually the unsubstituted form, however for commands which are a
471 canonically-constructed list (e.g., as produced by the \fBlist\fR command)
472 executed by \fBeval\fR it is the substituted form as they have no other
473 string representation. Care is taken that the canonicality property of
474 the latter is not spoiled.
478 This entry is present only if the command is found in the body of a
479 regular Tcl procedure. It then provides the name of that procedure.
483 This entry is present only if the command is found in the body of an
484 anonymous Tcl procedure, i.e. a lambda. It then provides the entire
485 definition of the lambda in question.
489 This entry is present only if the queried frame has a corresponding
490 frame returned by \fBinfo level\fR. It provides the index of this
491 frame, relative to the current level (0 and negative numbers).
493 A thing of note is that for procedures statically defined in files the
494 locations of commands in their bodies will be reported with type
495 \fBsource\fR and absolute line numbers, and not as type
496 \fBproc\fR. The same is true for procedures nested in statically
497 defined procedures, and literal eval scripts in files or statically
500 In contrast, procedure definitions and \fBeval\fR within a dynamically
501 \fBeval\fRuated environment count line numbers relative to the start of
502 their script, even if they would be able to count relative to the
503 start of the outer dynamic script. That type of number usually makes
506 A different way of describing this behaviour is that file based
507 locations are tracked as deeply as possible, and where this is not
508 possible the lines are counted based on the smallest possible
509 \fBeval\fR or procedure body, as that scope is usually easier to find
510 than any dynamic outer scope.
512 The syntactic form \fB{*}\fR is handled like \fBeval\fR. I.e. if it
513 is given a literal list argument the system tracks the line number
514 within the list words as well, and otherwise all line numbers are
515 counted relative to the start of each word (smallest scope)
518 \fBinfo functions \fR?\fIpattern\fR?
520 If \fIpattern\fR is not specified, returns a list of all the math
521 functions currently defined.
522 If \fIpattern\fR is specified, only those functions whose name matches
523 \fIpattern\fR are returned. Matching is determined using the same
524 rules as for \fBstring match\fR.
526 \fBinfo globals \fR?\fIpattern\fR?
528 If \fIpattern\fR is not specified, returns a list of all the names
529 of currently-defined global variables.
530 Global variables are variables in the global namespace.
531 If \fIpattern\fR is specified, only those names matching \fIpattern\fR
532 are returned. Matching is determined using the same rules as for
537 Returns the name of the computer on which this invocation is being
539 Note that this name is not guaranteed to be the fully qualified domain
540 name of the host. Where machines have several different names (as is
541 common on systems with both TCP/IP (DNS) and NetBIOS-based networking
542 installed,) it is the name that is suitable for TCP/IP networking that
545 \fBinfo level\fR ?\fInumber\fR?
547 If \fInumber\fR is not specified, this command returns a number
548 giving the stack level of the invoking procedure, or 0 if the
549 command is invoked at top-level. If \fInumber\fR is specified,
550 then the result is a list consisting of the name and arguments for the
551 procedure call at level \fInumber\fR on the stack. If \fInumber\fR
552 is positive then it selects a particular stack level (1 refers
553 to the top-most active procedure, 2 to the procedure it called, and
554 so on); otherwise it gives a level relative to the current level
555 (0 refers to the current procedure, -1 to its caller, and so on).
556 See the \fBuplevel\fR command for more information on what stack
561 Returns the name of the library directory in which standard Tcl
563 This is actually the value of the \fBtcl_library\fR
564 variable and may be changed by setting \fBtcl_library\fR.
566 \fBinfo loaded \fR?\fIinterp\fR?
568 Returns a list describing all of the packages that have been loaded into
569 \fIinterp\fR with the \fBload\fR command.
570 Each list element is a sub-list with two elements consisting of the
571 name of the file from which the package was loaded and the name of
573 For statically-loaded packages the file name will be an empty string.
574 If \fIinterp\fR is omitted then information is returned for all packages
575 loaded in any interpreter in the process.
576 To get a list of just the packages in the current interpreter, specify
577 an empty string for the \fIinterp\fR argument.
579 \fBinfo locals \fR?\fIpattern\fR?
581 If \fIpattern\fR is not specified, returns a list of all the names
582 of currently-defined local variables, including arguments to the
583 current procedure, if any.
584 Variables defined with the \fBglobal\fR, \fBupvar\fR and
585 \fBvariable\fR commands will not be returned.
586 If \fIpattern\fR is specified, only those names matching \fIpattern\fR
587 are returned. Matching is determined using the same rules as for
590 \fBinfo nameofexecutable\fR
592 Returns the full path name of the binary file from which the application
593 was invoked. If Tcl was unable to identify the file, then an empty
596 \fBinfo object\fI subcommand object\fR ?\fIarg ...\fR
598 Returns information about the object, \fIobject\fR. The \fIsubcommand\fRs are
599 described in \fBOBJECT INTROSPECTION\fR below.
602 \fBinfo patchlevel\fR
604 Returns the value of the global variable \fBtcl_patchLevel\fR, which holds
605 the exact version of the Tcl library by default.
607 \fBinfo procs \fR?\fIpattern\fR?
609 If \fIpattern\fR is not specified, returns a list of all the
610 names of Tcl command procedures in the current namespace.
611 If \fIpattern\fR is specified,
612 only those procedure names in the current namespace
613 matching \fIpattern\fR are returned.
614 Matching is determined using the same rules as for
616 If \fIpattern\fR contains any namespace separators, they are used to
617 select a namespace relative to the current namespace (or relative to
618 the global namespace if \fIpattern\fR starts with \fB::\fR) to match
619 within; the matching pattern is taken to be the part after the last
622 \fBinfo script\fR ?\fIfilename\fR?
624 If a Tcl script file is currently being evaluated (i.e. there is a
625 call to \fBTcl_EvalFile\fR active or there is an active invocation
626 of the \fBsource\fR command), then this command returns the name
627 of the innermost file being processed. If \fIfilename\fR is specified,
628 then the return value of this command will be modified for the
629 duration of the active invocation to return that name. This is
630 useful in virtual file system applications.
631 Otherwise the command returns an empty string.
633 \fBinfo sharedlibextension\fR
635 Returns the extension used on this platform for the names of files
636 containing shared libraries (for example, \fB.so\fR under Solaris).
637 If shared libraries are not supported on this platform then an empty
640 \fBinfo tclversion\fR
642 Returns the value of the global variable \fBtcl_version\fR, which holds the
643 major and minor version of the Tcl library by default.
645 \fBinfo vars\fR ?\fIpattern\fR?
647 If \fIpattern\fR is not specified,
648 returns a list of all the names of currently-visible variables.
649 This includes locals and currently-visible globals.
650 If \fIpattern\fR is specified, only those names matching \fIpattern\fR
651 are returned. Matching is determined using the same rules as for
653 \fIpattern\fR can be a qualified name like \fBFoo::option*\fR.
654 That is, it may specify a particular namespace
655 using a sequence of namespace names separated by double colons (\fB::\fR),
656 and may have pattern matching special characters
657 at the end to specify a set of variables in that namespace.
658 If \fIpattern\fR is a qualified name,
659 the resulting list of variable names
660 has each matching namespace variable qualified with the name
662 Note that a currently-visible variable may not yet
665 been set (e.g. a variable declared but not set by \fBvariable\fR).
666 .SS "CLASS INTROSPECTION"
669 The following \fIsubcommand\fR values are supported by \fBinfo class\fR:
672 \fBinfo class call\fI class method\fR
674 Returns a description of the method implementations that are used to provide a
675 stereotypical instance of \fIclass\fR's implementation of \fImethod\fR
676 (stereotypical instances being objects instantiated by a class without having
677 any object-specific definitions added). This consists of a list of lists of
678 four elements, where each sublist consists of a word that describes the
679 general type of method implementation (being one of \fBmethod\fR for an
680 ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a
681 method that is invoked as part of unknown method handling), a word giving the
682 name of the particular method invoked (which is always the same as
683 \fImethod\fR for the \fBmethod\fR type, and
685 for the \fBunknown\fR type), a word giving the fully qualified name of the
686 class that defined the method, and a word describing the type of method
687 implementation (see \fBinfo class methodtype\fR).
690 Note that there is no inspection of whether the method implementations
691 actually use \fBnext\fR to transfer control along the call chain.
695 \fBinfo class constructor\fI class\fR
697 This subcommand returns a description of the definition of the constructor of
698 class \fIclass\fR. The definition is described as a two element list; the first
699 element is the list of arguments to the constructor in a form suitable for
700 passing to another call to \fBproc\fR or a method definition, and the second
701 element is the body of the constructor. If no constructor is present, this
702 returns the empty list.
705 \fBinfo class definition\fI class method\fR
707 This subcommand returns a description of the definition of the method named
708 \fImethod\fR of class \fIclass\fR. The definition is described as a two element
709 list; the first element is the list of arguments to the method in a form
710 suitable for passing to another call to \fBproc\fR or a method definition, and
711 the second element is the body of the method.
714 \fBinfo class destructor\fI class\fR
716 This subcommand returns the body of the destructor of class \fIclass\fR. If no
717 destructor is present, this returns the empty string.
720 \fBinfo class filters\fI class\fR
722 This subcommand returns the list of filter methods set on the class.
725 \fBinfo class forward\fI class method\fR
727 This subcommand returns the argument list for the method forwarding called
728 \fImethod\fR that is set on the class called \fIclass\fR.
731 \fBinfo class instances\fI class\fR ?\fIpattern\fR?
733 This subcommand returns a list of instances of class \fIclass\fR. If the
734 optional \fIpattern\fR argument is present, it constrains the list of returned
735 instances to those that match it according to the rules of \fBstring match\fR.
738 \fBinfo class methods\fI class\fR ?\fIoptions...\fR?
740 This subcommand returns a list of all public (i.e. exported) methods of the
741 class called \fIclass\fR. Any of the following \fIoption\fRs may be
742 specified, controlling exactly which method names are returned:
748 If the \fB\-all\fR flag is given, the list of methods will include those
749 methods defined not just by the class, but also by the class's superclasses
755 If the \fB\-private\fR flag is given, the list of methods will also include
756 the private (i.e. non-exported) methods of the class (and superclasses and
757 mixins, if \fB\-all\fR is also given).
761 \fBinfo class methodtype\fI class method\fR
763 This subcommand returns a description of the type of implementation used for
764 the method named \fImethod\fR of class \fIclass\fR. When the result is
765 \fBmethod\fR, further information can be discovered with \fBinfo class
766 definition\fR, and when the result is \fBforward\fR, further information can
767 be discovered with \fBinfo class forward\fR.
770 \fBinfo class mixins\fI class\fR
772 This subcommand returns a list of all classes that have been mixed into the
773 class named \fIclass\fR.
776 \fBinfo class subclasses\fI class\fR ?\fIpattern\fR?
778 This subcommand returns a list of direct subclasses of class \fIclass\fR. If
779 the optional \fIpattern\fR argument is present, it constrains the list of
780 returned classes to those that match it according to the rules of
784 \fBinfo class superclasses\fI class\fR
786 This subcommand returns a list of direct superclasses of class \fIclass\fR in
787 inheritance precedence order.
790 \fBinfo class variables\fI class\fR
792 This subcommand returns a list of all variables that have been declared for
793 the class named \fIclass\fR (i.e. that are automatically present in the
794 class's methods, constructor and destructor).
795 .SS "OBJECT INTROSPECTION"
797 The following \fIsubcommand\fR values are supported by \fBinfo object\fR:
800 \fBinfo object call\fI object method\fR
802 Returns a description of the method implementations that are used to provide
803 \fIobject\fR's implementation of \fImethod\fR. This consists of a list of
804 lists of four elements, where each sublist consists of a word that describes
805 the general type of method implementation (being one of \fBmethod\fR for an
806 ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a
807 method that is invoked as part of unknown method handling), a word giving the
808 name of the particular method invoked (which is always the same as
809 \fImethod\fR for the \fBmethod\fR type, and
811 for the \fBunknown\fR type), a word giving what defined the method (the fully
812 qualified name of the class, or the literal string \fBobject\fR if the method
813 implementation is on an instance), and a word describing the type of method
814 implementation (see \fBinfo object methodtype\fR).
817 Note that there is no inspection of whether the method implementations
818 actually use \fBnext\fR to transfer control along the call chain.
822 \fBinfo object class\fI object\fR ?\fIclassName\fR?
824 If \fIclassName\fR is unspecified, this subcommand returns class of the
825 \fIobject\fR object. If \fIclassName\fR is present, this subcommand returns a
826 boolean value indicating whether the \fIobject\fR is of that class.
829 \fBinfo object definition\fI object method\fR
831 This subcommand returns a description of the definition of the method named
832 \fImethod\fR of object \fIobject\fR. The definition is described as a two
833 element list; the first element is the list of arguments to the method in a
834 form suitable for passing to another call to \fBproc\fR or a method definition,
835 and the second element is the body of the method.
838 \fBinfo object filters\fI object\fR
840 This subcommand returns the list of filter methods set on the object.
843 \fBinfo object forward\fI object method\fR
845 This subcommand returns the argument list for the method forwarding called
846 \fImethod\fR that is set on the object called \fIobject\fR.
849 \fBinfo object isa\fI category object\fR ?\fIarg\fR?
851 This subcommand tests whether an object belongs to a particular category,
852 returning a boolean value that indicates whether the \fIobject\fR argument
853 meets the criteria for the category. The supported categories are:
857 \fBinfo object isa class\fI object\fR
859 This returns whether \fIobject\fR is a class (i.e. an instance of
860 \fBoo::class\fR or one of its subclasses).
863 \fBinfo object isa metaclass\fI object\fR
865 This returns whether \fIobject\fR is a class that can manufacture classes
866 (i.e. is \fBoo::class\fR or a subclass of it).
869 \fBinfo object isa mixin\fI object class\fR
871 This returns whether \fIclass\fR is directly mixed into \fIobject\fR.
874 \fBinfo object isa object\fI object\fR
876 This returns whether \fIobject\fR really is an object.
879 \fBinfo object isa typeof\fI object class\fR
881 This returns whether \fIclass\fR is the type of \fIobject\fR (i.e. whether
882 \fIobject\fR is an instance of \fIclass\fR or one of its subclasses, whether
887 \fBinfo object methods\fI object\fR ?\fIoption...\fR?
889 This subcommand returns a list of all public (i.e. exported) methods of the
890 object called \fIobject\fR. Any of the following \fIoption\fRs may be
891 specified, controlling exactly which method names are returned:
897 If the \fB\-all\fR flag is given, the list of methods will include those
898 methods defined not just by the object, but also by the object's class and
899 mixins, plus the superclasses of those classes.
904 If the \fB\-private\fR flag is given, the list of methods will also include
905 the private (i.e. non-exported) methods of the object (and classes, if
906 \fB\-all\fR is also given).
910 \fBinfo object methodtype\fI object method\fR
912 This subcommand returns a description of the type of implementation used for
913 the method named \fImethod\fR of object \fIobject\fR. When the result is
914 \fBmethod\fR, further information can be discovered with \fBinfo object
915 definition\fR, and when the result is \fBforward\fR, further information can
916 be discovered with \fBinfo object forward\fR.
919 \fBinfo object mixins\fI object\fR
921 This subcommand returns a list of all classes that have been mixed into the
922 object named \fIobject\fR.
925 \fBinfo object namespace\fI object\fR
927 This subcommand returns the name of the internal namespace of the object named
931 \fBinfo object variables\fI object\fR
933 This subcommand returns a list of all variables that have been declared for
934 the object named \fIobject\fR (i.e. that are automatically present in the
938 \fBinfo object vars\fI object\fR ?\fIpattern\fR?
940 This subcommand returns a list of all variables in the private namespace of
941 the object named \fIobject\fR. If the optional \fIpattern\fR argument is
942 given, it is a filter (in the syntax of a \fBstring match\fR glob pattern)
943 that constrains the list of variables returned. Note that this is different
944 from the list returned by \fBinfo object variables\fR; that can include
945 variables that are currently unset, whereas this can include variables that
946 are not automatically included by any of \fIobject\fR's methods (or those of
947 its class, superclasses or mixins).
951 This command prints out a procedure suitable for saving in a Tcl
955 proc printProc {procName} {
956 set result [list proc $procName]
958 foreach var [\fBinfo args\fR $procName] {
959 if {[\fBinfo default\fR $procName $var def]} {
960 lappend formals [list $var $def]
962 # Still need the list-quoting because variable
963 # names may properly contain spaces.
964 lappend formals [list $var]
967 puts [lappend result $formals [\fBinfo body\fR $procName]]
970 .SS "EXAMPLES WITH OBJECTS"
973 Every object necessarily knows what its class is; this information is
974 trivially extractable through introspection:
979 puts [\fBinfo object class\fR o]
980 \fI\(-> prints "::c"\fR
981 puts [\fBinfo object class\fR c]
982 \fI\(-> prints "::oo::class"\fR
985 The introspection capabilities can be used to discover what class implements a
986 method and get how it is defined. This procedure illustrates how:
989 proc getDef {obj method} {
990 foreach inf [\fBinfo object call\fR $obj $method] {
991 lassign $inf calltype name locus methodtype
992 # Assume no forwards or filters, and hence no $calltype
993 # or $methodtype checks...
994 if {$locus eq "object"} {
995 return [\fBinfo object definition\fR $obj $name]
997 return [\fBinfo class definition\fR $locus $name]
1000 error "no definition for $method"
1004 This is an alternate way of looking up the definition; it is implemented by
1005 manually scanning the list of methods up the inheritance tree. This code
1006 assumes that only single inheritance is in use, and that there is no complex
1007 use of mixed-in classes (in such cases, using \fBinfo object call\fR as above
1008 is the simplest way of doing this by far):
1011 proc getDef {obj method} {
1012 if {$method in [\fBinfo object methods\fR $obj]} {
1013 # Assume no forwards
1014 return [\fBinfo object definition\fR $obj $method]
1016 set cls [\fBinfo object class\fR $obj]
1017 while {$method ni [\fBinfo class methods\fR $cls]} {
1018 # Assume the simple case
1019 set cls [lindex [\fBinfo class superclass\fR $cls] 0]
1021 error "no definition for $method"
1024 # Assume no forwards
1025 return [\fBinfo class definition\fR $cls $method]
1031 global(n), oo::class(n), oo::define(n), oo::object(n), proc(n), self(n),
1033 tcl_library(n), tcl_patchLevel(n), tcl_version(n)
1035 command, information, interpreter, introspection, level, namespace,
1040 '\" Local Variables:
OSDN Git Service
