diff options
Diffstat (limited to 'doc/info.n')
| -rw-r--r-- | doc/info.n | 160 |
1 files changed, 136 insertions, 24 deletions
@@ -21,7 +21,7 @@ info \- Return information about the state of the Tcl interpreter .PP This command provides information about various internals of the Tcl interpreter. -The legal \fIoption\fR's (which may be abbreviated) are: +The legal \fIoption\fRs (which may be abbreviated) are: .TP \fBinfo args \fIprocname\fR Returns a list containing the names of the arguments to procedure @@ -37,8 +37,11 @@ Returns a count of the total number of commands that have been invoked in this interpreter. .TP \fBinfo commands \fR?\fIpattern\fR? -If \fIpattern\fR isn't specified, -returns a list of names of all the Tcl commands in the current namespace, +If \fIpattern\fR is not specified, +.\" Do not move this .VS above the .TP +.VS 8.5 +returns a list of names of all the Tcl commands visible +(i.e. executable without using a qualified name) to the current namespace, including both the built-in commands written in C and the command procedures defined using the \fBproc\fR command. If \fIpattern\fR is specified, @@ -51,21 +54,25 @@ and may have pattern matching special characters at the end to specify a set of commands in that namespace. If \fIpattern\fR is a qualified name, the resulting list of command names has each one qualified with the name -of the specified namespace. +of the specified namespace, and only the commands defined in the named +namespace are returned. +.\" Technically, most of this hasn't changed; that's mostly just the +.\" way it always worked. Hardly anyone knew that though. +.VE 8.5 .TP \fBinfo complete \fIcommand\fR Returns 1 if \fIcommand\fR is a complete Tcl command in the sense of having no unclosed quotes, braces, brackets or array element names. -If the command doesn't appear to be complete then 0 is returned. +If the command does not appear to be complete then 0 is returned. This command is typically used in line-oriented input environments to allow users to type in commands that span multiple lines; if the -command isn't complete, the script can delay evaluating it until additional +command is not complete, the script can delay evaluating it until additional lines have been typed to complete the command. .TP \fBinfo default \fIprocname arg varname\fR \fIProcname\fR must be the name of a Tcl command procedure and \fIarg\fR must be the name of an argument to that procedure. If \fIarg\fR -doesn't have a default value then the command returns \fB0\fR. +does not have a default value then the command returns \fB0\fR. Otherwise it returns \fB1\fR and places the default value of \fIarg\fR into variable \fIvarname\fR. .TP @@ -73,18 +80,125 @@ into variable \fIvarname\fR. Returns \fB1\fR if the variable named \fIvarName\fR exists in the current context (either as a global or local variable) and has been defined by being given a value, returns \fB0\fR otherwise. -.VS 8.4 +.TP +\fBinfo frame\fR ?\fInumber\fR? +This command provides access to all frames on the stack, even those +hidden from \fBinfo level\fR. If \fInumber\fR is not specified, this +command returns a number giving the frame level of the command. This +is 1 if the command is invoked at top-level. If \fInumber\fR is +specified, then the result is a dictionary containing the location +information for the command at the \fInumber\fRed level on the stack. +.RS +.PP +If \fInumber\fR is positive (> 0) then it selects a particular stack +level (1 refers to the top-most active command, i.e., \fBinfo frame\fR +itself, 2 to the command it was called from, and so on); otherwise it +gives a level relative to the current command (0 refers to the current +command, i.e., \fBinfo frame\fR itself, -1 to its caller, and so on). +.PP +This is similar to how \fBinfo level\fR works, except that this +subcommand reports all frames, like \fBsource\fRd scripts, +\fBeval\fRs, \fBuplevel\fRs, etc. +.PP +Note that for nested commands, like +.QW "foo [bar [x]]" , +only +.QW x +will be seen by an \fBinfo frame\fR invoked within +.QW x . +This is the same as for \fBinfo level\fR and error stack traces. +.PP +The result dictionary may contain the keys listed below, with the +specified meanings for their values: +.TP +\fBtype\fR +This entry is always present and describes the nature of the location +for the command. The recognized values are \fBsource\fR, \fBproc\fR, +\fBeval\fR, and \fBprecompiled\fR. +.RS +.TP +\fBsource\fR\0\0\0\0\0\0\0\0 +means that the command is found in a script loaded by the \fBsource\fR +command. +.TP +\fBproc\fR\0\0\0\0\0\0\0\0 +means that the command is found in dynamically created procedure body. +.TP +\fBeval\fR\0\0\0\0\0\0\0\0 +means that the command is executed by \fBeval\fR or \fBuplevel\fR. +.TP +\fBprecompiled\fR\0\0\0\0\0\0\0\0 +means that the command is found in a precompiled script (loadable by +the package \fBtbcload\fR), and no further information will be +available. +.RE +.TP +\fBline\fR +This entry provides the number of the line the command is at inside of +the script it is a part of. This information is not present for type +\fBprecompiled\fR. For type \fBsource\fR this information is counted +relative to the beginning of the file, whereas for the last two types +the line is counted relative to the start of the script. +.TP +\fBfile\fR +This entry is present only for type \fBsource\fR. It provides the +normalized path of the file the command is in. +.TP +\fBcmd\fR +This entry provides the string representation of the command. This is +usually the unsubstituted form, however for commands which are a pure +list executed by eval it is the substituted form as they have no other +string representation. Care is taken that the pure-List property of +the latter is not spoiled. +.TP +\fBproc\fR +This entry is present only if the command is found in the body of a +regular Tcl procedure. It then provides the name of that procedure. +.TP +\fBlambda\fR +This entry is present only if the command is found in the body of an +anonymous Tcl procedure, i.e. a lambda. It then provides the entire +definition of the lambda in question. +.TP +\fBlevel\fR +This entry is present only if the queried frame has a corresponding +frame returned by \fBinfo level\fR. It provides the index of this +frame, relative to the current level (0 and negative numbers). +.PP +A thing of note is that for procedures statically defined in files the +locations of commands in their bodies will be reported with type +\fBsource\fR and absolute line numbers, and not as type +\fBproc\fR. The same is true for procedures nested in statically +defined procedures, and literal eval scripts in files or statically +defined procedures. +.PP +In contrast, a procedure definition or \fBeval\fR within a dynamically +\fBeval\fRuated environment count linenumbers relative to the start of +their script, even if they would be able to count relative to the +start of the outer dynamic script. That type of number usually makes +more sense. +.PP +A different way of describing this behaviour is that file based +locations are tracked as deeply as possible, and where this is not +possible the lines are counted based on the smallest possible +\fBeval\fR or procedure body, as that scope is usually easier to find +than any dynamic outer scope. +.PP +The syntactic form \fB{*}\fR is handled like \fBeval\fR. I.e. if it +is given a literal list argument the system tracks the linenumber +within the list words as well, and otherwise all linenumbers are +counted relative to the start of each word (smallest scope) +.RE .TP \fBinfo functions \fR?\fIpattern\fR? -If \fIpattern\fR isn't specified, returns a list of all the math +If \fIpattern\fR is not specified, returns a list of all the math functions currently defined. If \fIpattern\fR is specified, only those functions whose name matches \fIpattern\fR are returned. Matching is determined using the same rules as for \fBstring match\fR. -.VE .TP \fBinfo globals \fR?\fIpattern\fR? -If \fIpattern\fR isn't specified, returns a list of all the names +If \fIpattern\fR is not specified, returns a list of all the names of currently-defined global variables. Global variables are variables in the global namespace. If \fIpattern\fR is specified, only those names matching \fIpattern\fR @@ -94,13 +208,11 @@ are returned. Matching is determined using the same rules as for \fBinfo hostname\fR Returns the name of the computer on which this invocation is being executed. -.VS Note that this name is not guaranteed to be the fully qualified domain name of the host. Where machines have several different names (as is common on systems with both TCP/IP (DNS) and NetBIOS-based networking installed,) it is the name that is suitable for TCP/IP networking that is returned. -.VE .TP \fBinfo level\fR ?\fInumber\fR? If \fInumber\fR is not specified, this command returns a number @@ -135,7 +247,7 @@ To get a list of just the packages in the current interpreter, specify an empty string for the \fIinterp\fR argument. .TP \fBinfo locals \fR?\fIpattern\fR? -If \fIpattern\fR isn't specified, returns a list of all the names +If \fIpattern\fR is not specified, returns a list of all the names of currently-defined local variables, including arguments to the current procedure, if any. Variables defined with the \fBglobal\fR, \fBupvar\fR and @@ -154,7 +266,7 @@ Returns the value of the global variable \fBtcl_patchLevel\fR; see the \fBtclvars\fR manual entry for more information. .TP \fBinfo procs \fR?\fIpattern\fR? -If \fIpattern\fR isn't specified, returns a list of all the +If \fIpattern\fR is not specified, returns a list of all the names of Tcl command procedures in the current namespace. If \fIpattern\fR is specified, only those procedure names in the current namespace @@ -180,7 +292,7 @@ Otherwise the command returns an empty string. \fBinfo sharedlibextension\fR Returns the extension used on this platform for the names of files containing shared libraries (for example, \fB.so\fR under Solaris). -If shared libraries aren't supported on this platform then an empty +If shared libraries are not supported on this platform then an empty string is returned. .TP \fBinfo tclversion\fR @@ -188,7 +300,7 @@ Returns the value of the global variable \fBtcl_version\fR; see the \fBtclvars\fR manual entry for more information. .TP \fBinfo vars\fR ?\fIpattern\fR? -If \fIpattern\fR isn't specified, +If \fIpattern\fR is not specified, returns a list of all the names of currently-visible variables. This includes locals and currently-visible globals. If \fIpattern\fR is specified, only those names matching \fIpattern\fR @@ -203,11 +315,14 @@ If \fIpattern\fR is a qualified name, the resulting list of variable names has each matching namespace variable qualified with the name of its namespace. -Note that a currently-visible variable may not yet "exist" if it has not +Note that a currently-visible variable may not yet +.QW exist +if it has not been set (e.g. a variable declared but not set by \fBvariable\fR). .SH EXAMPLE This command prints out a procedure suitable for saving in a Tcl script: +.PP .CS proc printProc {procName} { set result [list proc $procName] @@ -224,13 +339,10 @@ proc printProc {procName} { puts [lappend result $formals [\fBinfo body\fR $procName]] } .CE - .SH "SEE ALSO" global(n), proc(n) - .SH KEYWORDS command, information, interpreter, level, namespace, procedure, variable - -'\" Local Variables: -'\" mode: nroff -'\" End: +.\" Local Variables: +.\" mode: nroff +.\" End: |