diff options
Diffstat (limited to 'doc/library.n')
| -rw-r--r-- | doc/library.n | 129 |
1 files changed, 72 insertions, 57 deletions
diff --git a/doc/library.n b/doc/library.n index ea3b5ed..5e00b1e 100644 --- a/doc/library.n +++ b/doc/library.n @@ -5,18 +5,20 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: library.n,v 1.12 2000/04/26 22:36:10 ericm Exp $ +'\" RCS: @(#) $Id: library.n,v 1.13 2000/04/28 00:47:49 ericm Exp $ .so man.macros .TH library n "8.0" Tcl "Tcl Built-In Commands" .BS .SH NAME -auto_execok, auto_load, auto_mkindex, auto_mkindex_old, auto_reset, tcl_findLibrary, parray, tcl_endOfWord, tcl_startOfNextWord, tcl_startOfPreviousWord, tcl_wordBreakAfter, tcl_wordBreakBefore \- standard library of Tcl procedures +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 .SH SYNOPSIS .nf \fBauto_execok \fIcmd\fR +\fBauto_import \fIpattern\fR \fBauto_load \fIcmd\fR \fBauto_mkindex \fIdir pattern pattern ...\fR \fBauto_mkindex_old \fIdir pattern pattern ...\fR +\fBauto_qualify \fIcommand namespace\fR \fBauto_reset\fR \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR \fBparray \fIarrayName\fR @@ -73,65 +75,61 @@ remembers information about previous searches in an array named same \fIcmd\fR. The command \fBauto_reset\fR may be used to force \fBauto_execok\fR to forget its cached information. .TP +\fBauto_import \fIpattern\fR +\fBAuto_import\fR is invoked during \fBnamespace import\fR to see if +the imported commands specified by \fIpattern\fR reside in an +autoloaded library. If so, the commands are loaded so that they will +be available to the interpreter for creating the import links. If the +commands do not reside in an autoloaded library, \fBauto_import\fR +does nothing. +.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. +\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 +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. +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 by sourcing them -into a slave interpreter and monitoring the proc and -namespace commands that are executed. -Extensions can use the (undocumented) -auto_mkindex_parser package to register other commands that -can contribute to the auto_load index. -You will have to read through auto.tcl to see how this works. +\fBAuto_mkindex\fR parses the Tcl scripts by sourcing them into a +slave interpreter and monitoring the proc and namespace commands that +are executed. Extensions can use the (undocumented) +auto_mkindex_parser package to register other commands that can +contribute to the auto_load index. You will have to read through +auto.tcl to see how this works. .PP \fBAuto_mkindex_old\fR parses the Tcl scripts in a relatively unsophisticated way: if any line contains the word \fBproc\fR @@ -147,12 +145,29 @@ code or procedure names with special characters like \fB$\fR, .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. +\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 +\fBauto_qualify \fIcommand namespace\fR +Computes a list of fully qualified names for \fIcommand\fR. This list +mirrors the path a standard Tcl interpreter follows for command +lookups: first it looks for the command in the current namespace, and +then in the global namespace. Accordingly, if \fIcommand\fR is +relative and \fInamespace\fR is not \fB::\fR, the list returned has +two elements: \fIcommand\fR scoped by \fInamespace\fR, as if it were +a command in the \fInamespace\fR namespace; and \fIcommand\fR as if it +were a command in the global namespace. Otherwise, if either +\fIcommand\fR is absolute (it begins with \fB::\fR), or +\fInamespace\fR is \fB::\fR, the list contains only \fIcommand\fR as +if it were a command in the global namespace. +.RS +.PP +\fBAuto_qualify\fR is used by the auto-loading facilities in Tcl, both +for producing auto-loading indexes such as \fIpkgIndex.tcl\fR, and for +performing the actual auto-loading of functions at runtime. +.RE .TP \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR This is a standard search procedure for use by extensions during |