Import Tcl 8.5.15 (as of svn r89086)
This commit is contained in:
Zachary Ware
348
doc/info.n
Normal file
348
doc/info.n
Normal file
@@ -0,0 +1,348 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
|
||||
'\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies
|
||||
'\" Copyright (c) 1998-2000 Ajuba Solutions
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH info n 8.4 Tcl "Tcl Built-In Commands"
|
||||
.BS
|
||||
'\" Note: do not modify the .SH NAME line immediately below!
|
||||
.SH NAME
|
||||
info \- Return information about the state of the Tcl interpreter
|
||||
.SH SYNOPSIS
|
||||
\fBinfo \fIoption \fR?\fIarg arg ...\fR?
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
This command provides information about various internals of the Tcl
|
||||
interpreter.
|
||||
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
|
||||
\fIprocname\fR, in order. \fIProcname\fR must be the name of a
|
||||
Tcl command procedure.
|
||||
.TP
|
||||
\fBinfo body \fIprocname\fR
|
||||
Returns the body of procedure \fIprocname\fR. \fIProcname\fR must be
|
||||
the name of a Tcl command procedure.
|
||||
.TP
|
||||
\fBinfo cmdcount\fR
|
||||
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 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,
|
||||
only those names matching \fIpattern\fR are returned.
|
||||
Matching is determined using the same rules as for \fBstring match\fR.
|
||||
\fIpattern\fR can be a qualified name like \fBFoo::print*\fR.
|
||||
That is, it may specify a particular namespace
|
||||
using a sequence of namespace names separated by double colons (\fB::\fR),
|
||||
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, 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 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 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
|
||||
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
|
||||
\fBinfo exists \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.
|
||||
.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 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.
|
||||
.TP
|
||||
\fBinfo globals \fR?\fIpattern\fR?
|
||||
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
|
||||
are returned. Matching is determined using the same rules as for
|
||||
\fBstring match\fR.
|
||||
.TP
|
||||
\fBinfo hostname\fR
|
||||
Returns the name of the computer on which this invocation is being
|
||||
executed.
|
||||
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.
|
||||
.TP
|
||||
\fBinfo level\fR ?\fInumber\fR?
|
||||
If \fInumber\fR is not specified, this command returns a number
|
||||
giving the stack level of the invoking procedure, or 0 if the
|
||||
command is invoked at top-level. If \fInumber\fR is specified,
|
||||
then the result is a list consisting of the name and arguments for the
|
||||
procedure call at level \fInumber\fR on the stack. If \fInumber\fR
|
||||
is positive then it selects a particular stack level (1 refers
|
||||
to the top-most active procedure, 2 to the procedure it called, and
|
||||
so on); otherwise it gives a level relative to the current level
|
||||
(0 refers to the current procedure, -1 to its caller, and so on).
|
||||
See the \fBuplevel\fR command for more information on what stack
|
||||
levels mean.
|
||||
.TP
|
||||
\fBinfo library\fR
|
||||
Returns the name of the library directory in which standard Tcl
|
||||
scripts are stored.
|
||||
This is actually the value of the \fBtcl_library\fR
|
||||
variable and may be changed by setting \fBtcl_library\fR.
|
||||
See the \fBtclvars\fR manual entry for more information.
|
||||
.TP
|
||||
\fBinfo loaded \fR?\fIinterp\fR?
|
||||
Returns a list describing all of the packages that have been loaded into
|
||||
\fIinterp\fR with the \fBload\fR command.
|
||||
Each list element is a sub-list with two elements consisting of the
|
||||
name of the file from which the package was loaded and the name of
|
||||
the package.
|
||||
For statically-loaded packages the file name will be an empty string.
|
||||
If \fIinterp\fR is omitted then information is returned for all packages
|
||||
loaded in any interpreter in the process.
|
||||
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 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
|
||||
\fBvariable\fR commands will not be returned.
|
||||
If \fIpattern\fR is specified, only those names matching \fIpattern\fR
|
||||
are returned. Matching is determined using the same rules as for
|
||||
\fBstring match\fR.
|
||||
.TP
|
||||
\fBinfo nameofexecutable\fR
|
||||
Returns the full path name of the binary file from which the application
|
||||
was invoked. If Tcl was unable to identify the file, then an empty
|
||||
string is returned.
|
||||
.TP
|
||||
\fBinfo patchlevel\fR
|
||||
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 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
|
||||
matching \fIpattern\fR are returned.
|
||||
Matching is determined using the same rules as for
|
||||
\fBstring match\fR.
|
||||
If \fIpattern\fR contains any namespace separators, they are used to
|
||||
select a namespace relative to the current namespace (or relative to
|
||||
the global namespace if \fIpattern\fR starts with \fB::\fR) to match
|
||||
within; the matching pattern is taken to be the part after the last
|
||||
namespace separator.
|
||||
.TP
|
||||
\fBinfo script\fR ?\fIfilename\fR?
|
||||
If a Tcl script file is currently being evaluated (i.e. there is a
|
||||
call to \fBTcl_EvalFile\fR active or there is an active invocation
|
||||
of the \fBsource\fR command), then this command returns the name
|
||||
of the innermost file being processed. If \fIfilename\fR is specified,
|
||||
then the return value of this command will be modified for the
|
||||
duration of the active invocation to return that name. This is
|
||||
useful in virtual file system applications.
|
||||
Otherwise the command returns an empty string.
|
||||
.TP
|
||||
\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 are not supported on this platform then an empty
|
||||
string is returned.
|
||||
.TP
|
||||
\fBinfo tclversion\fR
|
||||
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 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
|
||||
are returned. Matching is determined using the same rules as for
|
||||
\fBstring match\fR.
|
||||
\fIpattern\fR can be a qualified name like \fBFoo::option*\fR.
|
||||
That is, it may specify a particular namespace
|
||||
using a sequence of namespace names separated by double colons (\fB::\fR),
|
||||
and may have pattern matching special characters
|
||||
at the end to specify a set of variables in that namespace.
|
||||
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
|
||||
.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]
|
||||
set formals {}
|
||||
foreach var [\fBinfo args\fR $procName] {
|
||||
if {[\fBinfo default\fR $procName $var def]} {
|
||||
lappend formals [list $var $def]
|
||||
} else {
|
||||
# Still need the list-quoting because variable
|
||||
# names may properly contain spaces.
|
||||
lappend formals [list $var]
|
||||
}
|
||||
}
|
||||
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:
|
||||
Reference in New Issue
Block a user