189 lines
6.8 KiB
Plaintext
189 lines
6.8 KiB
Plaintext
'\"
|
|
'\" Copyright (c) 1991-1993 The Regents of the University of California.
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" SCCS: @(#) library.n 1.20 96/03/25 20:18:29
|
|
.so man.macros
|
|
.TH library n "" Tcl "Tcl Built-In Commands"
|
|
.BS
|
|
.SH NAME
|
|
library \- standard library of Tcl procedures
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fBauto_execok \fIcmd\fR
|
|
\fBauto_load \fIcmd\fR
|
|
\fBauto_mkindex \fIdir pattern pattern ...\fR
|
|
\fBauto_reset\fR
|
|
\fBparray \fIarrayName\fR
|
|
.BE
|
|
|
|
.SH INTRODUCTION
|
|
.PP
|
|
Tcl includes a library of Tcl procedures for commonly-needed functions.
|
|
The procedures defined in the Tcl library are generic ones suitable
|
|
for use by many different applications.
|
|
The location of the Tcl library is returned by the \fBinfo library\fR
|
|
command.
|
|
In addition to the Tcl library, each application will normally have
|
|
its own library of support procedures as well; the location of this
|
|
library is normally given by the value of the \fB$\fIapp\fB_library\fR
|
|
global variable, where \fIapp\fR is the name of the application.
|
|
For example, the location of the Tk library is kept in the variable
|
|
\fB$tk_library\fR.
|
|
.PP
|
|
To access the procedures in the Tcl library, an application should
|
|
source the file \fBinit.tcl\fR in the library, for example with
|
|
the Tcl command
|
|
.CS
|
|
\fBsource [info library]/init.tcl\fR
|
|
.CE
|
|
If the library procedure \fBTcl_Init\fR is invoked from an application's
|
|
\fBTcl_AppInit\fR procedure, this happens automatically.
|
|
The code in \fBinit.tcl\fR will define the \fBunknown\fR procedure
|
|
and arrange for the other procedures to be loaded on-demand using
|
|
the auto-load mechanism defined below.
|
|
|
|
.SH "COMMAND PROCEDURES"
|
|
.PP
|
|
The following procedures are provided in the Tcl library:
|
|
.TP
|
|
\fBauto_execok \fIcmd\fR
|
|
Determines whether there is an executable file by the name \fIcmd\fR.
|
|
This command examines the directories in the current search path
|
|
(given by the PATH environment variable) to see if there is an
|
|
executable file named \fIcmd\fR in any of those directories.
|
|
If so, it returns 1; if not it returns 0. \fBAuto_exec\fR
|
|
remembers information about previous searches in an array
|
|
named \fBauto_execs\fR; this avoids the path search in
|
|
future calls for the same \fIcmd\fR. The command \fBauto_reset\fR
|
|
may be used to force \fBauto_execok\fR to forget its cached
|
|
information.
|
|
.TP
|
|
\fBauto_load \fIcmd\fR
|
|
This command attempts to load the definition for a Tcl command named
|
|
\fIcmd\fR.
|
|
To do this, it searches an \fIauto-load path\fR, which is a list of
|
|
one or more directories.
|
|
The auto-load path is given by the global variable \fB$auto_path\fR
|
|
if it exists.
|
|
If there is no \fB$auto_path\fR variable, then the TCLLIBPATH environment
|
|
variable is used, if it exists.
|
|
Otherwise the auto-load path consists of just the Tcl library directory.
|
|
Within each directory in the auto-load path there must be a file
|
|
\fBtclIndex\fR that describes one
|
|
.VS
|
|
or more commands defined in that directory
|
|
and a script to evaluate to load each of the commands.
|
|
The \fBtclIndex\fR file should be generated with the
|
|
\fBauto_mkindex\fR command.
|
|
If \fIcmd\fR is found in an index file, then the appropriate
|
|
script is evaluated to create the command.
|
|
.VE
|
|
The \fBauto_load\fR command returns 1 if \fIcmd\fR was successfully
|
|
created.
|
|
The command returns 0 if there was no index entry for \fIcmd\fR
|
|
or if the script didn't actually define \fIcmd\fR (e.g. because
|
|
index information is out of date).
|
|
If an error occurs while processing the script, then that error
|
|
is returned.
|
|
\fBAuto_load\fR only reads the index information once and saves it
|
|
in the array \fBauto_index\fR; future calls to \fBauto_load\fR
|
|
check for \fIcmd\fR in the array rather than re-reading the index
|
|
files.
|
|
The cached index information may be deleted with the command
|
|
\fBauto_reset\fR.
|
|
This will force the next \fBauto_load\fR command to reload the
|
|
index database from disk.
|
|
.TP
|
|
\fBauto_mkindex \fIdir pattern pattern ...\fR
|
|
.VS
|
|
Generates an index suitable for use by \fBauto_load\fR.
|
|
The command searches \fIdir\fR for all files whose names match
|
|
any of the \fIpattern\fR arguments
|
|
.VE
|
|
(matching is done with the \fBglob\fR command),
|
|
generates an index of all the Tcl command
|
|
procedures defined in all the matching files, and stores the
|
|
index information in a file named \fBtclIndex\fR in \fIdir\fR.
|
|
If no pattern is given a pattern of \fB*.tcl\fR will be assumed.
|
|
For example, the command
|
|
.RS
|
|
.CS
|
|
\fBauto_mkindex foo *.tcl\fR
|
|
.CE
|
|
.LP
|
|
will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR
|
|
and generate a new index file \fBfoo/tclIndex\fR.
|
|
.PP
|
|
\fBAuto_mkindex\fR parses the Tcl scripts in a relatively
|
|
unsophisticated way: if any line contains the word \fBproc\fR
|
|
as its first characters then it is assumed to be a procedure
|
|
definition and the next word of the line is taken as the
|
|
procedure's name.
|
|
Procedure definitions that don't appear in this way (e.g. they
|
|
have spaces before the \fBproc\fR) will not be indexed.
|
|
.RE
|
|
.TP
|
|
\fBauto_reset\fR
|
|
Destroys all the information cached by \fBauto_execok\fR and
|
|
\fBauto_load\fR.
|
|
This information will be re-read from disk the next time it is
|
|
needed.
|
|
\fBAuto_reset\fR also deletes any procedures listed in the auto-load
|
|
index, so that fresh copies of them will be loaded the next time
|
|
that they're used.
|
|
.TP
|
|
\fBparray \fIarrayName\fR
|
|
Prints on standard output the names and values of all the elements
|
|
in the array \fIarrayName\fR.
|
|
\fBArrayName\fR must be an array accessible to the caller of \fBparray\fR.
|
|
It may be either local or global.
|
|
|
|
.SH "VARIABLES"
|
|
.PP
|
|
The following global variables are defined or used by the procedures in
|
|
the Tcl library:
|
|
.TP
|
|
\fBauto_execs\fR
|
|
Used by \fBauto_execok\fR to record information about whether
|
|
particular commands exist as executable files.
|
|
.TP
|
|
\fBauto_index\fR
|
|
Used by \fBauto_load\fR to save the index information read from
|
|
disk.
|
|
.TP
|
|
\fBauto_noexec\fR
|
|
If set to any value, then \fBunknown\fR will not attempt to auto-exec
|
|
any commands.
|
|
.TP
|
|
\fBauto_noload\fR
|
|
If set to any value, then \fBunknown\fR will not attempt to auto-load
|
|
any commands.
|
|
.TP
|
|
\fBauto_path\fR
|
|
If set, then it must contain a valid Tcl list giving directories to
|
|
search during auto-load operations.
|
|
.TP
|
|
\fBenv(TCL_LIBRARY)\fR
|
|
If set, then it specifies the location of the directory containing
|
|
library scripts (the value of this variable will be returned by
|
|
the command \fBinfo library\fR). If this variable isn't set then
|
|
a default value is used.
|
|
.TP
|
|
\fBenv(TCLLIBPATH)\fR
|
|
If set, then it must contain a valid Tcl list giving directories to
|
|
search during auto-load operations.
|
|
This variable is only used if \fBauto_path\fR is not defined.
|
|
.TP
|
|
\fBunknown_active\fR
|
|
This variable is set by \fBunknown\fR to indicate that it is active.
|
|
It is used to detect errors where \fBunknown\fR recurses on itself
|
|
infinitely.
|
|
The variable is unset before \fBunknown\fR returns.
|
|
|
|
.SH KEYWORDS
|
|
auto-exec, auto-load, library, unknown
|