1 |
578 |
markom |
'\"
|
2 |
|
|
'\" Copyright (c) 1991-1993 The Regents of the University of California.
|
3 |
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
4 |
|
|
'\"
|
5 |
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
6 |
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
7 |
|
|
'\"
|
8 |
|
|
'\" RCS: @(#) $Id: library.n,v 1.1.1.1 2002-01-16 10:25:24 markom Exp $
|
9 |
|
|
.so man.macros
|
10 |
|
|
.TH library n "8.0" Tcl "Tcl Built-In Commands"
|
11 |
|
|
.BS
|
12 |
|
|
.SH NAME
|
13 |
|
|
library \- standard library of Tcl procedures
|
14 |
|
|
.SH SYNOPSIS
|
15 |
|
|
.nf
|
16 |
|
|
\fBauto_execok \fIcmd\fR
|
17 |
|
|
\fBauto_load \fIcmd\fR
|
18 |
|
|
\fBauto_mkindex \fIdir pattern pattern ...\fR
|
19 |
|
|
\fBauto_mkindex_old \fIdir pattern pattern ...\fR
|
20 |
|
|
\fBauto_reset\fR
|
21 |
|
|
\fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR
|
22 |
|
|
\fBparray \fIarrayName\fR
|
23 |
|
|
.VS
|
24 |
|
|
\fBtcl_endOfWord \fIstr start\fR
|
25 |
|
|
\fBtcl_startOfNextWord \fIstr start\fR
|
26 |
|
|
\fBtcl_startOfPreviousWord \fIstr start\fR
|
27 |
|
|
\fBtcl_wordBreakAfter \fIstr start\fR
|
28 |
|
|
\fBtcl_wordBreakBefore \fIstr start\fR
|
29 |
|
|
.VE
|
30 |
|
|
.BE
|
31 |
|
|
|
32 |
|
|
.SH INTRODUCTION
|
33 |
|
|
.PP
|
34 |
|
|
Tcl includes a library of Tcl procedures for commonly-needed functions.
|
35 |
|
|
The procedures defined in the Tcl library are generic ones suitable
|
36 |
|
|
for use by many different applications.
|
37 |
|
|
The location of the Tcl library is returned by the \fBinfo library\fR
|
38 |
|
|
command.
|
39 |
|
|
In addition to the Tcl library, each application will normally have
|
40 |
|
|
its own library of support procedures as well; the location of this
|
41 |
|
|
library is normally given by the value of the \fB$\fIapp\fB_library\fR
|
42 |
|
|
global variable, where \fIapp\fR is the name of the application.
|
43 |
|
|
For example, the location of the Tk library is kept in the variable
|
44 |
|
|
\fB$tk_library\fR.
|
45 |
|
|
.PP
|
46 |
|
|
To access the procedures in the Tcl library, an application should
|
47 |
|
|
source the file \fBinit.tcl\fR in the library, for example with
|
48 |
|
|
the Tcl command
|
49 |
|
|
.CS
|
50 |
|
|
\fBsource [file join [info library] init.tcl]\fR
|
51 |
|
|
.CE
|
52 |
|
|
If the library procedure \fBTcl_Init\fR is invoked from an application's
|
53 |
|
|
\fBTcl_AppInit\fR procedure, this happens automatically.
|
54 |
|
|
The code in \fBinit.tcl\fR will define the \fBunknown\fR procedure
|
55 |
|
|
and arrange for the other procedures to be loaded on-demand using
|
56 |
|
|
the auto-load mechanism defined below.
|
57 |
|
|
|
58 |
|
|
.SH "COMMAND PROCEDURES"
|
59 |
|
|
.PP
|
60 |
|
|
The following procedures are provided in the Tcl library:
|
61 |
|
|
.TP
|
62 |
|
|
\fBauto_execok \fIcmd\fR
|
63 |
|
|
Determines whether there is an executable file by the name \fIcmd\fR.
|
64 |
|
|
This command examines the directories in the current search path
|
65 |
|
|
(given by the PATH environment variable) to see if there is an
|
66 |
|
|
executable file named \fIcmd\fR in any of those directories.
|
67 |
|
|
If so, it returns 1; if not it returns 0. \fBAuto_exec\fR
|
68 |
|
|
remembers information about previous searches in an array
|
69 |
|
|
named \fBauto_execs\fR; this avoids the path search in
|
70 |
|
|
future calls for the same \fIcmd\fR. The command \fBauto_reset\fR
|
71 |
|
|
may be used to force \fBauto_execok\fR to forget its cached
|
72 |
|
|
information.
|
73 |
|
|
.TP
|
74 |
|
|
\fBauto_load \fIcmd\fR
|
75 |
|
|
This command attempts to load the definition for a Tcl command named
|
76 |
|
|
\fIcmd\fR.
|
77 |
|
|
To do this, it searches an \fIauto-load path\fR, which is a list of
|
78 |
|
|
one or more directories.
|
79 |
|
|
The auto-load path is given by the global variable \fB$auto_path\fR
|
80 |
|
|
if it exists.
|
81 |
|
|
If there is no \fB$auto_path\fR variable, then the TCLLIBPATH environment
|
82 |
|
|
variable is used, if it exists.
|
83 |
|
|
Otherwise the auto-load path consists of just the Tcl library directory.
|
84 |
|
|
Within each directory in the auto-load path there must be a file
|
85 |
|
|
\fBtclIndex\fR that describes one
|
86 |
|
|
or more commands defined in that directory
|
87 |
|
|
and a script to evaluate to load each of the commands.
|
88 |
|
|
The \fBtclIndex\fR file should be generated with the
|
89 |
|
|
\fBauto_mkindex\fR command.
|
90 |
|
|
If \fIcmd\fR is found in an index file, then the appropriate
|
91 |
|
|
script is evaluated to create the command.
|
92 |
|
|
The \fBauto_load\fR command returns 1 if \fIcmd\fR was successfully
|
93 |
|
|
created.
|
94 |
|
|
The command returns 0 if there was no index entry for \fIcmd\fR
|
95 |
|
|
or if the script didn't actually define \fIcmd\fR (e.g. because
|
96 |
|
|
index information is out of date).
|
97 |
|
|
If an error occurs while processing the script, then that error
|
98 |
|
|
is returned.
|
99 |
|
|
\fBAuto_load\fR only reads the index information once and saves it
|
100 |
|
|
in the array \fBauto_index\fR; future calls to \fBauto_load\fR
|
101 |
|
|
check for \fIcmd\fR in the array rather than re-reading the index
|
102 |
|
|
files.
|
103 |
|
|
The cached index information may be deleted with the command
|
104 |
|
|
\fBauto_reset\fR.
|
105 |
|
|
This will force the next \fBauto_load\fR command to reload the
|
106 |
|
|
index database from disk.
|
107 |
|
|
.TP
|
108 |
|
|
\fBauto_mkindex \fIdir pattern pattern ...\fR
|
109 |
|
|
Generates an index suitable for use by \fBauto_load\fR.
|
110 |
|
|
The command searches \fIdir\fR for all files whose names match
|
111 |
|
|
any of the \fIpattern\fR arguments
|
112 |
|
|
(matching is done with the \fBglob\fR command),
|
113 |
|
|
generates an index of all the Tcl command
|
114 |
|
|
procedures defined in all the matching files, and stores the
|
115 |
|
|
index information in a file named \fBtclIndex\fR in \fIdir\fR.
|
116 |
|
|
If no pattern is given a pattern of \fB*.tcl\fR will be assumed.
|
117 |
|
|
For example, the command
|
118 |
|
|
.RS
|
119 |
|
|
.CS
|
120 |
|
|
\fBauto_mkindex foo *.tcl\fR
|
121 |
|
|
.CE
|
122 |
|
|
.LP
|
123 |
|
|
will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR
|
124 |
|
|
and generate a new index file \fBfoo/tclIndex\fR.
|
125 |
|
|
.PP
|
126 |
|
|
\fBAuto_mkindex\fR parses the Tcl scripts by sourcing them
|
127 |
|
|
into a slave interpreter and monitoring the proc and
|
128 |
|
|
namespace commands that are executed.
|
129 |
|
|
Extensions can use the (undocumented)
|
130 |
|
|
auto_mkindex_parser package to register other commands that
|
131 |
|
|
can contribute to the auto_load index.
|
132 |
|
|
You will have to read through init.tcl to see how this works.
|
133 |
|
|
.PP
|
134 |
|
|
\fBAuto_mkindex_old\fR parses the Tcl scripts in a relatively
|
135 |
|
|
unsophisticated way: if any line contains the word \fBproc\fR
|
136 |
|
|
as its first characters then it is assumed to be a procedure
|
137 |
|
|
definition and the next word of the line is taken as the
|
138 |
|
|
procedure's name.
|
139 |
|
|
Procedure definitions that don't appear in this way (e.g. they
|
140 |
|
|
have spaces before the \fBproc\fR) will not be indexed.
|
141 |
|
|
.RE
|
142 |
|
|
.TP
|
143 |
|
|
\fBauto_reset\fR
|
144 |
|
|
Destroys all the information cached by \fBauto_execok\fR and
|
145 |
|
|
\fBauto_load\fR.
|
146 |
|
|
This information will be re-read from disk the next time it is
|
147 |
|
|
needed.
|
148 |
|
|
\fBAuto_reset\fR also deletes any procedures listed in the auto-load
|
149 |
|
|
index, so that fresh copies of them will be loaded the next time
|
150 |
|
|
that they're used.
|
151 |
|
|
.TP
|
152 |
|
|
\fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR
|
153 |
|
|
This is a standard search procedure for use by extensions during
|
154 |
|
|
their initialization. They call this procedure to look for their
|
155 |
|
|
script library in several standard directories.
|
156 |
|
|
The last component of the name of the library directory is
|
157 |
|
|
normally \fIbasenameversion\fP
|
158 |
|
|
(e.g., tk8.0), but it might be "library" when in the build hierarchies.
|
159 |
|
|
The \fIinitScript\fR file will be sourced into the interpreter
|
160 |
|
|
once it is found. The directory in which this file is found is
|
161 |
|
|
stored into the global variable \fIvarName\fP.
|
162 |
|
|
If this variable is already defined (e.g., by C code during
|
163 |
|
|
application initialization) then no searching is done.
|
164 |
|
|
Otherwise the search looks in these directories:
|
165 |
|
|
the directory named by the environment variable \fIenVarName\fP;
|
166 |
|
|
relative to the Tcl library directory;
|
167 |
|
|
relative to the executable file in the standard installation
|
168 |
|
|
bin or bin/\fIarch\fP directory;
|
169 |
|
|
relative to the executable file in the current build tree;
|
170 |
|
|
relative to the executable file in a parallel build tree.
|
171 |
|
|
.TP
|
172 |
|
|
\fBparray \fIarrayName\fR
|
173 |
|
|
Prints on standard output the names and values of all the elements
|
174 |
|
|
in the array \fIarrayName\fR.
|
175 |
|
|
\fBArrayName\fR must be an array accessible to the caller of \fBparray\fR.
|
176 |
|
|
It may be either local or global.
|
177 |
|
|
.TP
|
178 |
|
|
\fBtcl_endOfWord \fIstr start\fR
|
179 |
|
|
.VS
|
180 |
|
|
Returns the index of the first end-of-word location that occurs after
|
181 |
|
|
a starting index \fIstart\fR in the string \fIstr\fR. An end-of-word
|
182 |
|
|
location is defined to be the first non-word character following the
|
183 |
|
|
first word character after the starting point. Returns -1 if there
|
184 |
|
|
are no more end-of-word locations after the starting point. See the
|
185 |
|
|
description of \fBtcl_wordchars\fR and \fBtcl_nonwordchars\fR below
|
186 |
|
|
for more details on how Tcl determines which characters are word
|
187 |
|
|
characters.
|
188 |
|
|
.TP
|
189 |
|
|
\fBtcl_startOfNextWord \fIstr start\fR
|
190 |
|
|
Returns the index of the first start-of-word location that occurs
|
191 |
|
|
after a starting index \fIstart\fR in the string \fIstr\fR. A
|
192 |
|
|
start-of-word location is defined to be the first word character
|
193 |
|
|
following a non-word character. Returns \-1 if there are no more
|
194 |
|
|
start-of-word locations after the starting point.
|
195 |
|
|
.TP
|
196 |
|
|
\fBtcl_startOfPreviousWord \fIstr start\fR
|
197 |
|
|
Returns the index of the first start-of-word location that occurs
|
198 |
|
|
before a starting index \fIstart\fR in the string \fIstr\fR. Returns
|
199 |
|
|
\-1 if there are no more start-of-word locations before the starting
|
200 |
|
|
point.
|
201 |
|
|
.TP
|
202 |
|
|
\fBtcl_wordBreakAfter \fIstr start\fR
|
203 |
|
|
Returns the index of the first word boundary after the starting index
|
204 |
|
|
\fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more
|
205 |
|
|
boundaries after the starting point in the given string. The index
|
206 |
|
|
returned refers to the second character of the pair that comprises a
|
207 |
|
|
boundary.
|
208 |
|
|
.TP
|
209 |
|
|
\fBtcl_wordBreakBefore \fIstr start\fR
|
210 |
|
|
Returns the index of the first word boundary before the starting index
|
211 |
|
|
\fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more
|
212 |
|
|
boundaries before the starting point in the given string. The index
|
213 |
|
|
returned refers to the second character of the pair that comprises a
|
214 |
|
|
boundary.
|
215 |
|
|
.VE
|
216 |
|
|
|
217 |
|
|
.SH "VARIABLES"
|
218 |
|
|
.PP
|
219 |
|
|
The following global variables are defined or used by the procedures in
|
220 |
|
|
the Tcl library:
|
221 |
|
|
.TP
|
222 |
|
|
\fBauto_execs\fR
|
223 |
|
|
Used by \fBauto_execok\fR to record information about whether
|
224 |
|
|
particular commands exist as executable files.
|
225 |
|
|
.TP
|
226 |
|
|
\fBauto_index\fR
|
227 |
|
|
Used by \fBauto_load\fR to save the index information read from
|
228 |
|
|
disk.
|
229 |
|
|
.TP
|
230 |
|
|
\fBauto_noexec\fR
|
231 |
|
|
If set to any value, then \fBunknown\fR will not attempt to auto-exec
|
232 |
|
|
any commands.
|
233 |
|
|
.TP
|
234 |
|
|
\fBauto_noload\fR
|
235 |
|
|
If set to any value, then \fBunknown\fR will not attempt to auto-load
|
236 |
|
|
any commands.
|
237 |
|
|
.TP
|
238 |
|
|
\fBauto_path\fR
|
239 |
|
|
If set, then it must contain a valid Tcl list giving directories to
|
240 |
|
|
search during auto-load operations.
|
241 |
|
|
This variable is initialized during startup to contain, in order:
|
242 |
|
|
the directories listed in the TCLLIBPATH environment variable,
|
243 |
|
|
the directory named by the $tcl_library variable,
|
244 |
|
|
the parent directory of $tcl_library,
|
245 |
|
|
the directories listed in the $tcl_pkgPath variable.
|
246 |
|
|
.TP
|
247 |
|
|
\fBenv(TCL_LIBRARY)\fR
|
248 |
|
|
If set, then it specifies the location of the directory containing
|
249 |
|
|
library scripts (the value of this variable will be
|
250 |
|
|
assigned to the \fBtcl_library\fR variable and therefore returned by
|
251 |
|
|
the command \fBinfo library\fR). If this variable isn't set then
|
252 |
|
|
a default value is used.
|
253 |
|
|
.TP
|
254 |
|
|
\fBenv(TCLLIBPATH)\fR
|
255 |
|
|
If set, then it must contain a valid Tcl list giving directories to
|
256 |
|
|
search during auto-load operations.
|
257 |
|
|
This variable is only used when
|
258 |
|
|
initializing the \fBauto_path\fR variable.
|
259 |
|
|
.TP
|
260 |
|
|
\fBtcl_nonwordchars\fR
|
261 |
|
|
.VS
|
262 |
|
|
This variable contains a regular expression that is used by routines
|
263 |
|
|
like \fBtcl_endOfWord\fR to identify whether a character is part of a
|
264 |
|
|
word or not. If the pattern matches a character, the character is
|
265 |
|
|
considered to be a non-word character. On Windows platforms, spaces,
|
266 |
|
|
tabs, and newlines are considered non-word characters. Under Unix,
|
267 |
|
|
everything but numbers, letters and underscores are considered
|
268 |
|
|
non-word characters.
|
269 |
|
|
.TP
|
270 |
|
|
\fBtcl_wordchars\fR
|
271 |
|
|
This variable contains a regular expression that is used by routines
|
272 |
|
|
like \fBtcl_endOfWord\fR to identify whether a character is part of a
|
273 |
|
|
word or not. If the pattern matches a character, the character is
|
274 |
|
|
considered to be a word character. On Windows platforms, words are
|
275 |
|
|
comprised of any character that is not a space, tab, or newline. Under
|
276 |
|
|
Unix, words are comprised of numbers, letters or underscores.
|
277 |
|
|
.VE
|
278 |
|
|
.TP
|
279 |
|
|
\fBunknown_active\fR
|
280 |
|
|
This variable is set by \fBunknown\fR to indicate that it is active.
|
281 |
|
|
It is used to detect errors where \fBunknown\fR recurses on itself
|
282 |
|
|
infinitely.
|
283 |
|
|
The variable is unset before \fBunknown\fR returns.
|
284 |
|
|
|
285 |
|
|
.SH KEYWORDS
|
286 |
|
|
auto-exec, auto-load, library, unknown, word, whitespace
|