2 '\" Copyright (c) 1991-1993 The Regents of the University of California.
3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 .TH library n "8.0" Tcl "Tcl Built-In Commands"
9 .\" The -*- nroff -*- definitions below are for supplemental macros used
10 .\" in Tcl/Tk manual entries.
12 .\" .AP type name in/out ?indent?
13 .\" Start paragraph describing an argument to a library procedure.
14 .\" type is type of argument (int, etc.), in/out is either "in", "out",
15 .\" or "in/out" to describe whether procedure reads or modifies arg,
16 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 .\" needed; use .AS below instead)
20 .\" Give maximum sizes of arguments for setting tab stops. Type and
21 .\" name are examples of largest possible arguments that will be passed
22 .\" to .AP later. If args are omitted, default tab stops are used.
25 .\" Start box enclosure. From here until next .BE, everything will be
26 .\" enclosed in one large box.
29 .\" End of box enclosure.
32 .\" Begin code excerpt.
37 .\" .VS ?version? ?br?
38 .\" Begin vertical sidebar, for use in marking newly-changed parts
39 .\" of man pages. The first argument is ignored and used for recording
40 .\" the version when the .VS was added, so that the sidebars can be
41 .\" found and removed when they reach a certain age. If another argument
42 .\" is present, then a line break is forced before starting the sidebar.
45 .\" End of vertical sidebar.
48 .\" Begin an indented unfilled display.
51 .\" End of indented unfilled display.
54 .\" Start of list of standard options for a Tk widget. The manpage
55 .\" argument defines where to look up the standard options; if
56 .\" omitted, defaults to "options". The options follow on successive
57 .\" lines, in three columns separated by tabs.
60 .\" End of list of standard options for a Tk widget.
62 .\" .OP cmdName dbName dbClass
63 .\" Start of description of a specific option. cmdName gives the
64 .\" option's name as specified in the class command, dbName gives
65 .\" the option's name in the option database, and dbClass gives
66 .\" the option's class in the option database.
69 .\" Print arg1 underlined, then print arg2 normally.
72 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
75 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
76 .\" (for trailing punctuation) and then a closing parenthesis.
78 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
82 .\" # Start an argument description
86 . ie !"\\$2"" .TP \\n()Cu
91 \&\\$1 \\fI\\$2\\fP (\\$3)
104 .\" # define tabbing values for .AP
107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
113 .AS Tcl_Interp Tcl_CreateInterp in/out
114 .\" # BS - start boxed text
115 .\" # ^y = starting y location
123 .if n \l'\\n(.lu\(ul'
126 .\" # BE - end boxed text (draw box now)
131 .ie n \l'\\n(^lu\(ul'
133 .\" Draw four-sided box normally, but don't draw top of
134 .\" box if the box started on an earlier page.
136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 .\" # VS - start vertical sidebar
147 .\" # ^Y = starting y location
148 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
152 .ie n 'mc \s12\(br\s0
155 .\" # VE - end of vertical sidebar
163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
170 .\" # Special macro to handle page bottom: finish off current
171 .\" # box/sidebar if in box/sidebar mode, then invoked standard
172 .\" # page bottom macro.
179 .\" Draw three-sided box if this is the box's first page,
180 .\" draw two sides but no top otherwise.
181 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .nr ^x \\n(^tu+1v-\\n(^Yu
186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
199 .\" # DS - begin display
205 .\" # DE - end display
211 .\" # SO - start of list of standard options
213 'ie '\\$1'' .ds So \\fBoptions\\fR
214 'el .ds So \\fB\\$1\\fR
215 .SH "STANDARD OPTIONS"
221 .\" # SE - end of list of standard options
226 See the \\*(So manual entry for details on the standard options.
228 .\" # OP - start of full description for a single option
233 Command-Line Name: \\fB\\$1\\fR
234 Database Name: \\fB\\$2\\fR
235 Database Class: \\fB\\$3\\fR
239 .\" # CS - begin code excerpt
245 .\" # CE - end code excerpt
250 .\" # UL - underline word
254 .\" # QW - apply quotation marks to word
256 .ie '\\*(lq'"' ``\\$1''\\$2
257 .\"" fix emacs highlighting
258 .el \\*(lq\\$1\\*(rq\\$2
260 .\" # PQ - apply parens and quotation marks to word
262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
263 .\"" fix emacs highlighting
264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
266 .\" # QR - quoted range
268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
269 .\"" fix emacs highlighting
270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
272 .\" # MT - "empty" string
278 auto_execok, auto_import, auto_load, auto_mkindex, auto_qualify, auto_reset, tcl_findLibrary, parray, tcl_endOfWord, tcl_startOfNextWord, tcl_startOfPreviousWord, tcl_wordBreakAfter, tcl_wordBreakBefore \- standard library of Tcl procedures
281 \fBauto_execok \fIcmd\fR
282 \fBauto_import \fIpattern\fR
283 \fBauto_load \fIcmd\fR
284 \fBauto_mkindex \fIdir pattern pattern ...\fR
285 \fBauto_qualify \fIcommand namespace\fR
287 \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR
288 \fBparray \fIarrayName\fR
289 \fBtcl_endOfWord \fIstr start\fR
290 \fBtcl_startOfNextWord \fIstr start\fR
291 \fBtcl_startOfPreviousWord \fIstr start\fR
292 \fBtcl_wordBreakAfter \fIstr start\fR
293 \fBtcl_wordBreakBefore \fIstr start\fR
297 Tcl includes a library of Tcl procedures for commonly-needed functions.
298 The procedures defined in the Tcl library are generic ones suitable
299 for use by many different applications.
300 The location of the Tcl library is returned by the \fBinfo library\fR
302 In addition to the Tcl library, each application will normally have
303 its own library of support procedures as well; the location of this
304 library is normally given by the value of the \fB$\fIapp\fB_library\fR
305 global variable, where \fIapp\fR is the name of the application.
306 For example, the location of the Tk library is kept in the variable
309 To access the procedures in the Tcl library, an application should
310 source the file \fBinit.tcl\fR in the library, for example with
314 \fBsource [file join [info library] init.tcl]\fR
317 If the library procedure \fBTcl_Init\fR is invoked from an application's
318 \fBTcl_AppInit\fR procedure, this happens automatically.
319 The code in \fBinit.tcl\fR will define the \fBunknown\fR procedure
320 and arrange for the other procedures to be loaded on-demand using
321 the auto-load mechanism defined below.
322 .SH "COMMAND PROCEDURES"
324 The following procedures are provided in the Tcl library:
326 \fBauto_execok \fIcmd\fR
327 Determines whether there is an executable file or shell builtin
328 by the name \fIcmd\fR. If so, it returns a list of arguments to be
329 passed to \fBexec\fR to execute the executable file or shell builtin
330 named by \fIcmd\fR. If not, it returns an empty string. This command
331 examines the directories in the current search path (given by the PATH
332 environment variable) in its search for an executable file named
333 \fIcmd\fR. On Windows platforms, the search is expanded with the same
334 directories and file extensions as used by \fBexec\fR. \fBAuto_execok\fR
335 remembers information about previous searches in an array named
336 \fBauto_execs\fR; this avoids the path search in future calls for the
337 same \fIcmd\fR. The command \fBauto_reset\fR may be used to force
338 \fBauto_execok\fR to forget its cached information.
340 \fBauto_import \fIpattern\fR
341 \fBAuto_import\fR is invoked during \fBnamespace import\fR to see if
342 the imported commands specified by \fIpattern\fR reside in an
343 autoloaded library. If so, the commands are loaded so that they will
344 be available to the interpreter for creating the import links. If the
345 commands do not reside in an autoloaded library, \fBauto_import\fR
346 does nothing. The pattern matching is performed according to the
347 matching rules of \fBnamespace import\fR.
349 \fBauto_load \fIcmd\fR
350 This command attempts to load the definition for a Tcl command named
351 \fIcmd\fR. To do this, it searches an \fIauto-load path\fR, which is
352 a list of one or more directories. The auto-load path is given by the
353 global variable \fBauto_path\fR if it exists. If there is no
354 \fBauto_path\fR variable, then the TCLLIBPATH environment variable is
355 used, if it exists. Otherwise the auto-load path consists of just the
356 Tcl library directory. Within each directory in the auto-load path
357 there must be a file \fBtclIndex\fR that describes one or more
358 commands defined in that directory and a script to evaluate to load
359 each of the commands. The \fBtclIndex\fR file should be generated
360 with the \fBauto_mkindex\fR command. If \fIcmd\fR is found in an
361 index file, then the appropriate script is evaluated to create the
362 command. The \fBauto_load\fR command returns 1 if \fIcmd\fR was
363 successfully created. The command returns 0 if there was no index
364 entry for \fIcmd\fR or if the script did not actually define \fIcmd\fR
365 (e.g. because index information is out of date). If an error occurs
366 while processing the script, then that error is returned.
367 \fBAuto_load\fR only reads the index information once and saves it in
368 the array \fBauto_index\fR; future calls to \fBauto_load\fR check for
369 \fIcmd\fR in the array rather than re-reading the index files. The
370 cached index information may be deleted with the command
371 \fBauto_reset\fR. This will force the next \fBauto_load\fR command to
372 reload the index database from disk.
374 \fBauto_mkindex \fIdir pattern pattern ...\fR
376 Generates an index suitable for use by \fBauto_load\fR. The command
377 searches \fIdir\fR for all files whose names match any of the
378 \fIpattern\fR arguments (matching is done with the \fBglob\fR
379 command), generates an index of all the Tcl command procedures defined
380 in all the matching files, and stores the index information in a file
381 named \fBtclIndex\fR in \fIdir\fR. If no pattern is given a pattern of
382 \fB*.tcl\fR will be assumed. For example, the command
386 \fBauto_mkindex foo *.tcl\fR
389 will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR and
390 generate a new index file \fBfoo/tclIndex\fR.
392 \fBAuto_mkindex\fR parses the Tcl scripts by sourcing them into a
393 slave interpreter and monitoring the proc and namespace commands that
394 are executed. Extensions can use the (undocumented)
395 auto_mkindex_parser package to register other commands that can
396 contribute to the auto_load index. You will have to read through
397 auto.tcl to see how this works.
399 \fBAuto_mkindex_old\fR
400 (which has the same syntax as \fBauto_mkindex\fR)
401 parses the Tcl scripts in a relatively
402 unsophisticated way: if any line contains the word
404 as its first characters then it is assumed to be a procedure
405 definition and the next word of the line is taken as the
407 Procedure definitions that do not appear in this way (e.g.\ they
408 have spaces before the \fBproc\fR) will not be indexed. If your
411 code, such as global initialization
412 code or procedure names with special characters like \fB$\fR,
413 \fB*\fR, \fB[\fR or \fB]\fR, you are safer using \fBauto_mkindex_old\fR.
418 Destroys all the information cached by \fBauto_execok\fR and
419 \fBauto_load\fR. This information will be re-read from disk the next
420 time it is needed. \fBAuto_reset\fR also deletes any procedures
421 listed in the auto-load index, so that fresh copies of them will be
422 loaded the next time that they are used.
424 \fBauto_qualify \fIcommand namespace\fR
425 Computes a list of fully qualified names for \fIcommand\fR. This list
426 mirrors the path a standard Tcl interpreter follows for command
427 lookups: first it looks for the command in the current namespace, and
428 then in the global namespace. Accordingly, if \fIcommand\fR is
429 relative and \fInamespace\fR is not \fB::\fR, the list returned has
430 two elements: \fIcommand\fR scoped by \fInamespace\fR, as if it were
431 a command in the \fInamespace\fR namespace; and \fIcommand\fR as if it
432 were a command in the global namespace. Otherwise, if either
433 \fIcommand\fR is absolute (it begins with \fB::\fR), or
434 \fInamespace\fR is \fB::\fR, the list contains only \fIcommand\fR as
435 if it were a command in the global namespace.
438 \fBAuto_qualify\fR is used by the auto-loading facilities in Tcl, both
439 for producing auto-loading indexes such as \fIpkgIndex.tcl\fR, and for
440 performing the actual auto-loading of functions at runtime.
443 \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR
444 This is a standard search procedure for use by extensions during
445 their initialization. They call this procedure to look for their
446 script library in several standard directories.
447 The last component of the name of the library directory is
448 normally \fIbasenameversion\fR
449 (e.g., tk8.0), but it might be
451 when in the build hierarchies.
452 The \fIinitScript\fR file will be sourced into the interpreter
453 once it is found. The directory in which this file is found is
454 stored into the global variable \fIvarName\fR.
455 If this variable is already defined (e.g., by C code during
456 application initialization) then no searching is done.
457 Otherwise the search looks in these directories:
458 the directory named by the environment variable \fIenVarName\fR;
459 relative to the Tcl library directory;
460 relative to the executable file in the standard installation
461 bin or bin/\fIarch\fR directory;
462 relative to the executable file in the current build tree;
463 relative to the executable file in a parallel build tree.
465 \fBparray \fIarrayName\fR
466 Prints on standard output the names and values of all the elements
467 in the array \fIarrayName\fR.
468 \fIArrayName\fR must be an array accessible to the caller of \fBparray\fR.
469 It may be either local or global.
471 \fBtcl_endOfWord \fIstr start\fR
472 Returns the index of the first end-of-word location that occurs after
473 a starting index \fIstart\fR in the string \fIstr\fR. An end-of-word
474 location is defined to be the first non-word character following the
475 first word character after the starting point. Returns -1 if there
476 are no more end-of-word locations after the starting point. See the
477 description of \fBtcl_wordchars\fR and \fBtcl_nonwordchars\fR below
478 for more details on how Tcl determines which characters are word
481 \fBtcl_startOfNextWord \fIstr start\fR
482 Returns the index of the first start-of-word location that occurs
483 after a starting index \fIstart\fR in the string \fIstr\fR. A
484 start-of-word location is defined to be the first word character
485 following a non-word character. Returns \-1 if there are no more
486 start-of-word locations after the starting point.
488 \fBtcl_startOfPreviousWord \fIstr start\fR
489 Returns the index of the first start-of-word location that occurs
490 before a starting index \fIstart\fR in the string \fIstr\fR. Returns
491 \-1 if there are no more start-of-word locations before the starting
494 \fBtcl_wordBreakAfter \fIstr start\fR
495 Returns the index of the first word boundary after the starting index
496 \fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more
497 boundaries after the starting point in the given string. The index
498 returned refers to the second character of the pair that comprises a
501 \fBtcl_wordBreakBefore \fIstr start\fR
502 Returns the index of the first word boundary before the starting index
503 \fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more
504 boundaries before the starting point in the given string. The index
505 returned refers to the second character of the pair that comprises a
509 The following global variables are defined or used by the procedures in
510 the Tcl library. They fall into two broad classes, handling unknown
511 commands and packages, and determining what are words.
512 .SS "AUTOLOADING AND PACKAGE MANAGEMENT VARIABLES"
515 Used by \fBauto_execok\fR to record information about whether
516 particular commands exist as executable files.
519 Used by \fBauto_load\fR to save the index information read from
523 If set to any value, then \fBunknown\fR will not attempt to auto-exec
527 If set to any value, then \fBunknown\fR will not attempt to auto-load
532 If set, then it must contain a valid Tcl list giving directories to
533 search during auto-load operations (including for package index
534 files when using the default \fBpackage unknown\fR handler).
535 This variable is initialized during startup to contain, in order:
536 the directories listed in the \fBTCLLIBPATH\fR environment variable,
537 the directory named by the \fBtcl_library\fR global variable,
538 the parent directory of \fBtcl_library\fR,
539 the directories listed in the \fBtcl_pkgPath\fR variable.
540 Additional locations to look for files and package indices should
541 normally be added to this variable using \fBlappend\fR.
543 \fBenv(TCL_LIBRARY)\fR
544 If set, then it specifies the location of the directory containing
545 library scripts (the value of this variable will be
546 assigned to the \fBtcl_library\fR variable and therefore returned by
547 the command \fBinfo library\fR). If this variable is not set then
548 a default value is used.
550 \fBenv(TCLLIBPATH)\fR
551 If set, then it must contain a valid Tcl list giving directories to
552 search during auto-load operations. Directories must be specified in
555 as the path separator, regardless of platform.
556 This variable is only used when initializing the \fBauto_path\fR variable.
557 .SS "WORD BOUNDARY DETERMINATION VARIABLES"
558 These variables are only used in the \fBtcl_endOfWord\fR,
559 \fBtcl_startOfNextWord\fR, \fBtcl_startOfPreviousWord\fR,
560 \fBtcl_wordBreakAfter\fR, and \fBtcl_wordBreakBefore\fR commands.
562 \fBtcl_nonwordchars\fR
563 This variable contains a regular expression that is used by routines
564 like \fBtcl_endOfWord\fR to identify whether a character is part of a
565 word or not. If the pattern matches a character, the character is
566 considered to be a non-word character. On Windows platforms, spaces,
567 tabs, and newlines are considered non-word characters. Under Unix,
568 everything but numbers, letters and underscores are considered
572 This variable contains a regular expression that is used by routines
573 like \fBtcl_endOfWord\fR to identify whether a character is part of a
574 word or not. If the pattern matches a character, the character is
575 considered to be a word character. On Windows platforms, words are
576 comprised of any character that is not a space, tab, or newline. Under
577 Unix, words are comprised of numbers, letters or underscores.
579 env(n), info(n), re_syntax(n)
581 auto-exec, auto-load, library, unknown, word, whitespace
OSDN Git Service
