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 '\" RCS: @(#) $Id: library.n,v 1.16 2001/08/24 06:03:15 dgp Exp $
9 '\" The definitions below are for supplemental macros used in Tcl/Tk
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
55 '\" options follow on successive lines, in four columns separated
59 '\" End of list of standard options for a Tk widget.
61 '\" .OP cmdName dbName dbClass
62 '\" Start of description of a specific option. cmdName gives the
63 '\" option's name as specified in the class command, dbName gives
64 '\" the option's name in the option database, and dbClass gives
65 '\" the option's class in the option database.
68 '\" Print arg1 underlined, then print arg2 normally.
70 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
72 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
76 '\" # Start an argument description
80 . ie !"\\$2"" .TP \\n()Cu
85 \&\\$1 \\fI\\$2\\fP (\\$3)
98 '\" # define tabbing values for .AP
101 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
104 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
105 .nr )C \\n()Bu+\\w'(in/out)'u+2n
107 .AS Tcl_Interp Tcl_CreateInterp in/out
108 '\" # BS - start boxed text
109 '\" # ^y = starting y location
117 .if n \l'\\n(.lu\(ul'
120 '\" # BE - end boxed text (draw box now)
125 .ie n \l'\\n(^lu\(ul'
127 .\" Draw four-sided box normally, but don't draw top of
128 .\" box if the box started on an earlier page.
130 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
133 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
140 '\" # VS - start vertical sidebar
141 '\" # ^Y = starting y location
142 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
146 .ie n 'mc \s12\(br\s0
149 '\" # VE - end of vertical sidebar
157 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
164 '\" # Special macro to handle page bottom: finish off current
165 '\" # box/sidebar if in box/sidebar mode, then invoked standard
166 '\" # page bottom macro.
173 .\" Draw three-sided box if this is the box's first page,
174 .\" draw two sides but no top otherwise.
175 .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
176 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
179 .nr ^x \\n(^tu+1v-\\n(^Yu
180 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
193 '\" # DS - begin display
199 '\" # DE - end display
205 '\" # SO - start of list of standard options
207 .SH "STANDARD OPTIONS"
213 '\" # SE - end of list of standard options
218 See the \\fBoptions\\fR manual entry for details on the standard options.
220 '\" # OP - start of full description for a single option
225 Command-Line Name: \\fB\\$1\\fR
226 Database Name: \\fB\\$2\\fR
227 Database Class: \\fB\\$3\\fR
231 '\" # CS - begin code excerpt
237 '\" # CE - end code excerpt
245 .TH library n "8.0" Tcl "Tcl Built-In Commands"
248 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
251 \fBauto_execok \fIcmd\fR
252 \fBauto_import \fIpattern\fR
253 \fBauto_load \fIcmd\fR
254 \fBauto_mkindex \fIdir pattern pattern ...\fR
255 \fBauto_mkindex_old \fIdir pattern pattern ...\fR
256 \fBauto_qualify \fIcommand namespace\fR
258 \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR
259 \fBparray \fIarrayName\fR
261 \fBtcl_endOfWord \fIstr start\fR
262 \fBtcl_startOfNextWord \fIstr start\fR
263 \fBtcl_startOfPreviousWord \fIstr start\fR
264 \fBtcl_wordBreakAfter \fIstr start\fR
265 \fBtcl_wordBreakBefore \fIstr start\fR
271 Tcl includes a library of Tcl procedures for commonly-needed functions.
272 The procedures defined in the Tcl library are generic ones suitable
273 for use by many different applications.
274 The location of the Tcl library is returned by the \fBinfo library\fR
276 In addition to the Tcl library, each application will normally have
277 its own library of support procedures as well; the location of this
278 library is normally given by the value of the \fB$\fIapp\fB_library\fR
279 global variable, where \fIapp\fR is the name of the application.
280 For example, the location of the Tk library is kept in the variable
283 To access the procedures in the Tcl library, an application should
284 source the file \fBinit.tcl\fR in the library, for example with
287 \fBsource [file join [info library] init.tcl]\fR
289 If the library procedure \fBTcl_Init\fR is invoked from an application's
290 \fBTcl_AppInit\fR procedure, this happens automatically.
291 The code in \fBinit.tcl\fR will define the \fBunknown\fR procedure
292 and arrange for the other procedures to be loaded on-demand using
293 the auto-load mechanism defined below.
295 .SH "COMMAND PROCEDURES"
297 The following procedures are provided in the Tcl library:
299 \fBauto_execok \fIcmd\fR
300 Determines whether there is an executable file or shell builtin
301 by the name \fIcmd\fR. If so, it returns a list of arguments to be
302 passed to \fBexec\fR to execute the executable file or shell builtin
303 named by \fIcmd\fR. If not, it returns an empty string. This command
304 examines the directories in the current search path (given by the PATH
305 environment variable) in its search for an executable file named
306 \fIcmd\fR. On Windows platforms, the search is expanded with the same
307 directories and file extensions as used by \fBexec\fR. \fBAuto_exec\fR
308 remembers information about previous searches in an array named
309 \fBauto_execs\fR; this avoids the path search in future calls for the
310 same \fIcmd\fR. The command \fBauto_reset\fR may be used to force
311 \fBauto_execok\fR to forget its cached information.
313 \fBauto_import \fIpattern\fR
314 \fBAuto_import\fR is invoked during \fBnamespace import\fR to see if
315 the imported commands specified by \fIpattern\fR reside in an
316 autoloaded library. If so, the commands are loaded so that they will
317 be available to the interpreter for creating the import links. If the
318 commands do not reside in an autoloaded library, \fBauto_import\fR
319 does nothing. The pattern matching is performed according to the
320 matching rules of \fBnamespace import\fR.
322 \fBauto_load \fIcmd\fR
323 This command attempts to load the definition for a Tcl command named
324 \fIcmd\fR. To do this, it searches an \fIauto-load path\fR, which is
325 a list of one or more directories. The auto-load path is given by the
326 global variable \fB$auto_path\fR if it exists. If there is no
327 \fB$auto_path\fR variable, then the TCLLIBPATH environment variable is
328 used, if it exists. Otherwise the auto-load path consists of just the
329 Tcl library directory. Within each directory in the auto-load path
330 there must be a file \fBtclIndex\fR that describes one or more
331 commands defined in that directory and a script to evaluate to load
332 each of the commands. The \fBtclIndex\fR file should be generated
333 with the \fBauto_mkindex\fR command. If \fIcmd\fR is found in an
334 index file, then the appropriate script is evaluated to create the
335 command. The \fBauto_load\fR command returns 1 if \fIcmd\fR was
336 successfully created. The command returns 0 if there was no index
337 entry for \fIcmd\fR or if the script didn't actually define \fIcmd\fR
338 (e.g. because index information is out of date). If an error occurs
339 while processing the script, then that error is returned.
340 \fBAuto_load\fR only reads the index information once and saves it in
341 the array \fBauto_index\fR; future calls to \fBauto_load\fR check for
342 \fIcmd\fR in the array rather than re-reading the index files. The
343 cached index information may be deleted with the command
344 \fBauto_reset\fR. This will force the next \fBauto_load\fR command to
345 reload the index database from disk.
347 \fBauto_mkindex \fIdir pattern pattern ...\fR
348 Generates an index suitable for use by \fBauto_load\fR. The command
349 searches \fIdir\fR for all files whose names match any of the
350 \fIpattern\fR arguments (matching is done with the \fBglob\fR
351 command), generates an index of all the Tcl command procedures defined
352 in all the matching files, and stores the index information in a file
353 named \fBtclIndex\fR in \fIdir\fR. If no pattern is given a pattern of
354 \fB*.tcl\fR will be assumed. For example, the command
357 \fBauto_mkindex foo *.tcl\fR
360 will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR and
361 generate a new index file \fBfoo/tclIndex\fR.
363 \fBAuto_mkindex\fR parses the Tcl scripts by sourcing them into a
364 slave interpreter and monitoring the proc and namespace commands that
365 are executed. Extensions can use the (undocumented)
366 auto_mkindex_parser package to register other commands that can
367 contribute to the auto_load index. You will have to read through
368 auto.tcl to see how this works.
370 \fBAuto_mkindex_old\fR parses the Tcl scripts in a relatively
371 unsophisticated way: if any line contains the word \fBproc\fR
372 as its first characters then it is assumed to be a procedure
373 definition and the next word of the line is taken as the
375 Procedure definitions that don't appear in this way (e.g. they
376 have spaces before the \fBproc\fR) will not be indexed. If your
377 script contains "dangerous" code, such as global initialization
378 code or procedure names with special characters like \fB$\fR,
379 \fB*\fR, \fB[\fR or \fB]\fR, you are safer using auto_mkindex_old.
383 Destroys all the information cached by \fBauto_execok\fR and
384 \fBauto_load\fR. This information will be re-read from disk the next
385 time it is needed. \fBAuto_reset\fR also deletes any procedures
386 listed in the auto-load index, so that fresh copies of them will be
387 loaded the next time that they're used.
389 \fBauto_qualify \fIcommand namespace\fR
390 Computes a list of fully qualified names for \fIcommand\fR. This list
391 mirrors the path a standard Tcl interpreter follows for command
392 lookups: first it looks for the command in the current namespace, and
393 then in the global namespace. Accordingly, if \fIcommand\fR is
394 relative and \fInamespace\fR is not \fB::\fR, the list returned has
395 two elements: \fIcommand\fR scoped by \fInamespace\fR, as if it were
396 a command in the \fInamespace\fR namespace; and \fIcommand\fR as if it
397 were a command in the global namespace. Otherwise, if either
398 \fIcommand\fR is absolute (it begins with \fB::\fR), or
399 \fInamespace\fR is \fB::\fR, the list contains only \fIcommand\fR as
400 if it were a command in the global namespace.
403 \fBAuto_qualify\fR is used by the auto-loading facilities in Tcl, both
404 for producing auto-loading indexes such as \fIpkgIndex.tcl\fR, and for
405 performing the actual auto-loading of functions at runtime.
408 \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR
409 This is a standard search procedure for use by extensions during
410 their initialization. They call this procedure to look for their
411 script library in several standard directories.
412 The last component of the name of the library directory is
413 normally \fIbasenameversion\fP
414 (e.g., tk8.0), but it might be "library" when in the build hierarchies.
415 The \fIinitScript\fR file will be sourced into the interpreter
416 once it is found. The directory in which this file is found is
417 stored into the global variable \fIvarName\fP.
418 If this variable is already defined (e.g., by C code during
419 application initialization) then no searching is done.
420 Otherwise the search looks in these directories:
421 the directory named by the environment variable \fIenVarName\fP;
422 relative to the Tcl library directory;
423 relative to the executable file in the standard installation
424 bin or bin/\fIarch\fP directory;
425 relative to the executable file in the current build tree;
426 relative to the executable file in a parallel build tree.
428 \fBparray \fIarrayName\fR
429 Prints on standard output the names and values of all the elements
430 in the array \fIarrayName\fR.
431 \fBArrayName\fR must be an array accessible to the caller of \fBparray\fR.
432 It may be either local or global.
434 \fBtcl_endOfWord \fIstr start\fR
436 Returns the index of the first end-of-word location that occurs after
437 a starting index \fIstart\fR in the string \fIstr\fR. An end-of-word
438 location is defined to be the first non-word character following the
439 first word character after the starting point. Returns -1 if there
440 are no more end-of-word locations after the starting point. See the
441 description of \fBtcl_wordchars\fR and \fBtcl_nonwordchars\fR below
442 for more details on how Tcl determines which characters are word
445 \fBtcl_startOfNextWord \fIstr start\fR
446 Returns the index of the first start-of-word location that occurs
447 after a starting index \fIstart\fR in the string \fIstr\fR. A
448 start-of-word location is defined to be the first word character
449 following a non-word character. Returns \-1 if there are no more
450 start-of-word locations after the starting point.
452 \fBtcl_startOfPreviousWord \fIstr start\fR
453 Returns the index of the first start-of-word location that occurs
454 before a starting index \fIstart\fR in the string \fIstr\fR. Returns
455 \-1 if there are no more start-of-word locations before the starting
458 \fBtcl_wordBreakAfter \fIstr start\fR
459 Returns the index of the first word boundary after the starting index
460 \fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more
461 boundaries after the starting point in the given string. The index
462 returned refers to the second character of the pair that comprises a
465 \fBtcl_wordBreakBefore \fIstr start\fR
466 Returns the index of the first word boundary before the starting index
467 \fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more
468 boundaries before the starting point in the given string. The index
469 returned refers to the second character of the pair that comprises a
475 The following global variables are defined or used by the procedures in
479 Used by \fBauto_execok\fR to record information about whether
480 particular commands exist as executable files.
483 Used by \fBauto_load\fR to save the index information read from
487 If set to any value, then \fBunknown\fR will not attempt to auto-exec
491 If set to any value, then \fBunknown\fR will not attempt to auto-load
495 If set, then it must contain a valid Tcl list giving directories to
496 search during auto-load operations.
497 This variable is initialized during startup to contain, in order:
498 the directories listed in the TCLLIBPATH environment variable,
499 the directory named by the $tcl_library variable,
500 the parent directory of $tcl_library,
501 the directories listed in the $tcl_pkgPath variable.
503 \fBenv(TCL_LIBRARY)\fR
504 If set, then it specifies the location of the directory containing
505 library scripts (the value of this variable will be
506 assigned to the \fBtcl_library\fR variable and therefore returned by
507 the command \fBinfo library\fR). If this variable isn't set then
508 a default value is used.
510 \fBenv(TCLLIBPATH)\fR
511 If set, then it must contain a valid Tcl list giving directories to
512 search during auto-load operations. Directories must be specified in
513 Tcl format, using "/" as the path separator, regardless of platform.
514 This variable is only used when initializing the \fBauto_path\fR variable.
516 \fBtcl_nonwordchars\fR
518 This variable contains a regular expression that is used by routines
519 like \fBtcl_endOfWord\fR to identify whether a character is part of a
520 word or not. If the pattern matches a character, the character is
521 considered to be a non-word character. On Windows platforms, spaces,
522 tabs, and newlines are considered non-word characters. Under Unix,
523 everything but numbers, letters and underscores are considered
527 This variable contains a regular expression that is used by routines
528 like \fBtcl_endOfWord\fR to identify whether a character is part of a
529 word or not. If the pattern matches a character, the character is
530 considered to be a word character. On Windows platforms, words are
531 comprised of any character that is not a space, tab, or newline. Under
532 Unix, words are comprised of numbers, letters or underscores.
535 \fBunknown_pending\fR
536 Used by \fBunknown\fR to record the command(s) for which it is
538 It is used to detect errors where \fBunknown\fR recurses on itself
540 The variable is unset before \fBunknown\fR returns.
543 info(n), re_syntax(n)
546 auto-exec, auto-load, library, unknown, word, whitespace
OSDN Git Service
