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