'\"
'\" 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.
'\" 
'\" RCS: @(#) $Id: library.n,v 1.11 2000/04/15 18:42:56 ericm Exp $
'\" RCS: @(#) $Id: library.n,v 1.11.2.1 2000/08/07 21:29:39 hobbs Exp $
.so man.macros
.TH library n "8.0" Tcl "Tcl Built-In Commands"
.BS
.SH NAME
library \- 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
.VS
\fBtcl_endOfWord \fIstr start\fR
\fBtcl_startOfNextWord \fIstr start\fR
\fBtcl_startOfPreviousWord \fIstr start\fR

environment variable) in its search for an executable file named
\fIcmd\fR.  On Windows platforms, the search is expanded with the same
directories and file extensions as used by \fBexec\fR. \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_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
\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
if it exists.
If there is no \fB$auto_path\fR variable, then the TCLLIBPATH environment
\fB$auto_path\fR variable, then the TCLLIBPATH environment variable is
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
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
and a script to evaluate to load each of the commands.
The \fBtclIndex\fR file should be generated with the
\fBauto_mkindex\fR command.
each of the commands.  The \fBtclIndex\fR file should be generated
with the \fBauto_mkindex\fR command.  If \fIcmd\fR is found in an
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
index file, then the appropriate script is evaluated to create the
command.  The \fBauto_load\fR command returns 1 if \fIcmd\fR was
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
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.
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
\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
files.
The cached index information may be deleted with the command
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.
\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
Generates an index suitable for use by \fBauto_load\fR.  The command
searches \fIdir\fR for all files whose names match any of the
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
\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
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
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
\fBAuto_mkindex\fR parses the Tcl scripts by sourcing them into a
slave interpreter and monitoring the proc and namespace commands that
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.
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
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.  If your 
script contains "dangerous" code, such as global initialization
code or procedure names with special characters like \fB$\fR,
\fB*\fR, \fB[\fR or \fB]\fR, you are safer using auto_mkindex_old.
.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
\fBauto_load\fR.  This information will be re-read from disk the next
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.
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
their initialization.  They call this procedure to look for their
script library in several standard directories.
The last component of the name of the library directory is 
normally \fIbasenameversion\fP