diff options
Diffstat (limited to 'doc/library.n')
| -rw-r--r-- | doc/library.n | 249 |
1 files changed, 249 insertions, 0 deletions
diff --git a/doc/library.n b/doc/library.n new file mode 100644 index 0000000..215a569 --- /dev/null +++ b/doc/library.n @@ -0,0 +1,249 @@ +'\" +'\" 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.23 96/11/20 14:07:04 +.so man.macros +.TH library n "8.0" 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 +.VS +\fBtcl_endOfWord \fIstr start\fR +\fBtcl_startOfNextWord \fIstr start\fR +\fBtcl_startOfPreviousWord \fIstr start\fR +\fBtcl_wordBreakAfter \fIstr start\fR +\fBtcl_wordBreakBefore \fIstr start\fR +.VE +.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 [file join [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 +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. +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 +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 +(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. +.TP +\fBtcl_endOfWord \fIstr start\fR +.VS +Returns the index of the first end-of-word location that occurs after +a starting index \fIstart\fR in the string \fIstr\fR. An end-of-word +location is defined to be the first non-word character following the +first word character after the starting point. Returns -1 if there +are no more end-of-word locations after the starting point. See the +description of \fBtcl_wordchars\fR and \fBtcl_nonwordchars\fR below +for more details on how Tcl determines which characters are word +characters. +.TP +\fBtcl_startOfNextWord \fIstr start\fR +Returns the index of the first start-of-word location that occurs +after a starting index \fIstart\fR in the string \fIstr\fR. A +start-of-word location is defined to be the first word character +following a non-word character. Returns \-1 if there are no more +start-of-word locations after the starting point. +.TP +\fBtcl_startOfPreviousWord \fIstr start\fR +Returns the index of the first start-of-word location that occurs +before a starting index \fIstart\fR in the string \fIstr\fR. Returns +\-1 if there are no more start-of-word locations before the starting +point. +.TP +\fBtcl_wordBreakAfter \fIstr start\fR +Returns the index of the first word boundary after the starting index +\fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more +boundaries after the starting point in the given string. The index +returned refers to the second character of the pair that comprises a +boundary. +.TP +\fBtcl_wordBreakBefore \fIstr start\fR +Returns the index of the first word boundary before the starting index +\fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more +boundaries before the starting point in the given string. The index +returned refers to the second character of the pair that comprises a +boundary. +.VE + +.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 +\fBtcl_nonwordchars\fR +.VS +This variable contains a regular expression that is used by routines +like \fBtcl_endOfWord\fR to identify whether a character is part of a +word or not. If the pattern matches a character, the character is +considered to be a non-word character. On Windows platforms, spaces, +tabs, and newlines are considered non-word characters. Under Unix, +everything but numbers, letters and underscores are considered +non-word characters. +.TP +\fBtcl_wordchars\fR +This variable contains a regular expression that is used by routines +like \fBtcl_endOfWord\fR to identify whether a character is part of a +word or not. If the pattern matches a character, the character is +considered to be a word character. On Windows platforms, words are +comprised of any character that is not a space, tab, or newline. Under +Unix, words are comprised of numbers, letters or underscores. +.VE +.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, word, whitespace |