diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/info.n | 70 |
1 files changed, 38 insertions, 32 deletions
@@ -3,7 +3,7 @@ '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies '\" Copyright (c) 1998-2000 Ajuba Solutions -'\" Copyright (c) 2007-2008 Donal K. Fellows +'\" Copyright (c) 2007-2012 Donal K. Fellows '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -79,9 +79,9 @@ lines have been typed to complete the command. .TP \fBinfo coroutine\fR .VS 8.6 -Returns the name of the currently executing coroutine, or the empty string if -either no coroutine is currently executing, or the current coroutine has been -deleted (but has not yet returned or yielded since deletion). +Returns the name of the currently executing \fBcoroutine\fR, or the empty +string if either no coroutine is currently executing, or the current coroutine +has been deleted (but has not yet returned or yielded since deletion). .VE 8.6 .TP \fBinfo default \fIprocname arg varname\fR @@ -97,23 +97,27 @@ into variable \fIvarname\fR. Returns, in a form that is programmatically easy to parse, the function names and arguments at each level from the call stack of the last error in the given \fIinterp\fR, or in the current one if not specified. - +.RS +.PP This form is an even-sized list alternating tokens and parameters. Tokens are currently either \fBCALL\fR, \fBUP\fR, or \fBINNER\fR, but other values may be introduced in the future. \fBCALL\fR indicates a procedure call, and its -parameter is the corresponding [info level 0]. \fBUP\fR indicates a shift in -variable frames generated by uplevel or similar, and applies to the previous -CALL item. Its parameter is the level offset. \fBINNER\fR identifies the -"inner context", which is the innermost atomic command or bytecode instruction -that raised the error, along with its arguments when available. While -\fBCALL\fR and \fBUP\fR allow to follow complex call paths, \fBINNER\fR homes -in on the offending operation in the innermost proc call, even going to -sub-expr granularity. - -This information is also present in the -\fB\-errorstack\fR entry of the options dictionary returned by 3-argument -\fBcatch\fR; \fBinfo errorstack\fR is a convenient way of retrieving it for -uncaught errors at toplevel in an interactive tclsh. +parameter is the corresponding \fBinfo level\fR \fB0\fR. \fBUP\fR indicates a +shift in variable frames generated by \fBuplevel\fR or similar, and applies to +the previous \fBCALL\fR item. Its parameter is the level offset. \fBINNER\fR +identifies the +.QW "inner context" , +which is the innermost atomic command or bytecode instruction that raised the +error, along with its arguments when available. While \fBCALL\fR and \fBUP\fR +allow to follow complex call paths, \fBINNER\fR homes in on the offending +operation in the innermost procedure call, even going to sub-expression +granularity. +.PP +This information is also present in the \fB\-errorstack\fR entry of the +options dictionary returned by 3-argument \fBcatch\fR; \fBinfo errorstack\fR +is a convenient way of retrieving it for uncaught errors at top-level in an +interactive \fBtclsh\fR. +.RE .VE 8.6 .TP \fBinfo exists \fIvarName\fR @@ -176,7 +180,7 @@ 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 +means that the command is found in a pre-compiled script (loadable by the package \fBtbcload\fR), and no further information will be available. .RE @@ -197,9 +201,10 @@ normalized path of the file the command is in. \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 +usually the unsubstituted form, however for commands which are a +canonically-constructed list (e.g., as produced by the \fBlist\fR command) +executed by \fBeval\fR it is the substituted form as they have no other +string representation. Care is taken that the canonicality property of the latter is not spoiled. .TP \fBproc\fR @@ -226,8 +231,8 @@ locations of commands in their bodies will be reported with type 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 +In contrast, procedure definitions and \fBeval\fR within a dynamically +\fBeval\fRuated environment count line numbers relative to the start of their script, even if they would be able to count relative to the start of the outer dynamic script. That type of number usually makes more sense. @@ -239,8 +244,8 @@ possible the lines are counted based on the smallest possible 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 +is given a literal list argument the system tracks the line number +within the list words as well, and otherwise all line numbers are counted relative to the start of each word (smallest scope) .RE .TP @@ -671,7 +676,7 @@ This subcommand returns a list of all variables in the private namespace of the object named \fIobject\fR. If the optional \fIpattern\fR argument is given, it is a filter (in the syntax of a \fBstring match\fR glob pattern) that constrains the list of variables returned. Note that this is different -from the lit returned by \fBinfo object variables\fR; that can include +from the list returned by \fBinfo object variables\fR; that can include variables that are currently unset, whereas this can include variables that are not automatically included by any of \fIobject\fR's methods (or those of its class, superclasses or mixins). @@ -731,10 +736,11 @@ proc getDef {obj method} { } .CE .PP -This is an alternate way of implementing the definition lookup is by manually -scanning the list of methods up the inheritance tree. This code assumes that -only single inheritance is in use, and that there is no complex use of -mixed-in classes: +This is an alternate way of looking up the definition; it is implemented by +manually scanning the list of methods up the inheritance tree. This code +assumes that only single inheritance is in use, and that there is no complex +use of mixed-in classes (in such cases, using \fBinfo object call\fR as above +is the simplest way of doing this by far): .PP .CS proc getDef {obj method} { @@ -746,7 +752,7 @@ proc getDef {obj method} { while {$method ni [\fBinfo class methods\fR $cls]} { # Assume the simple case set cls [lindex [\fBinfo class superclass\fR $cls] 0] - if {$cls eq {}} { + if {$cls eq ""} { error "no definition for $method" } } |