321 lines
14 KiB
Plaintext
321 lines
14 KiB
Plaintext
'\"
|
|
'\" 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.
|
|
'\"
|
|
.TH library n "8.0" Tcl "Tcl Built-In Commands"
|
|
.so man.macros
|
|
.BS
|
|
.SH NAME
|
|
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
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fBauto_execok \fIcmd\fR
|
|
\fBauto_import \fIpattern\fR
|
|
\fBauto_load \fIcmd\fR
|
|
\fBauto_mkindex \fIdir pattern pattern ...\fR
|
|
\fBauto_qualify \fIcommand namespace\fR
|
|
\fBauto_reset\fR
|
|
\fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR
|
|
\fBparray \fIarrayName\fR ?\fIpattern\fR?
|
|
\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
|
|
.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
|
|
\fBtk_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
|
|
.PP
|
|
.CS
|
|
\fBsource [file join [info library] init.tcl]\fR
|
|
.CE
|
|
.PP
|
|
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 or shell builtin
|
|
by the name \fIcmd\fR. If so, it returns a list of arguments to be
|
|
passed to \fBexec\fR to execute the executable file or shell builtin
|
|
named by \fIcmd\fR. If not, it returns an empty string. This command
|
|
examines the directories in the current search path (given by the PATH
|
|
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_execok\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. The pattern matching is performed according to the
|
|
matching rules of \fBnamespace import\fR.
|
|
.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 \fBauto_path\fR if it exists. If there is no
|
|
\fBauto_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 did not 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
|
|
.PP
|
|
.CS
|
|
\fBauto_mkindex foo *.tcl\fR
|
|
.CE
|
|
.PP
|
|
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
|
|
child 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
|
|
(which has the same syntax as \fBauto_mkindex\fR)
|
|
parses the Tcl scripts in a relatively
|
|
unsophisticated way: if any line contains the word
|
|
.QW \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 do not appear in this way (e.g.\ they
|
|
have spaces before the \fBproc\fR) will not be indexed. If your
|
|
script contains
|
|
.QW 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 \fBauto_mkindex_old\fR.
|
|
.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 are 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\fR
|
|
(e.g., tk8.0), but it might be
|
|
.QW library
|
|
when in the build hierarchies.
|
|
The \fIinitScript\fR file will be sourced into the interpreter
|
|
once it is found. The directory in which this file is found is
|
|
stored into the global variable \fIvarName\fR.
|
|
If this variable is already defined (e.g., by C code during
|
|
application initialization) then no searching is done.
|
|
Otherwise the search looks in these directories:
|
|
the directory named by the environment variable \fIenVarName\fR;
|
|
relative to the Tcl library directory;
|
|
relative to the executable file in the standard installation
|
|
bin or bin/\fIarch\fR directory;
|
|
relative to the executable file in the current build tree;
|
|
relative to the executable file in a parallel build tree.
|
|
.TP
|
|
\fBparray \fIarrayName\fR ?\fIpattern\fR?
|
|
Prints on standard output the names and values of all the elements in the
|
|
array \fIarrayName\fR, or just the names that match \fIpattern\fR (using the
|
|
matching rules of \fBstring match\fR) and their values if \fIpattern\fR is
|
|
given.
|
|
\fIArrayName\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
|
|
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.
|
|
.SH "VARIABLES"
|
|
.PP
|
|
The following global variables are defined or used by the procedures in
|
|
the Tcl library. They fall into two broad classes, handling unknown
|
|
commands and packages, and determining what are words.
|
|
.SS "AUTOLOADING AND PACKAGE MANAGEMENT VARIABLES"
|
|
.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 (including for package index
|
|
files when using the default \fBpackage unknown\fR handler).
|
|
This variable is initialized during startup to contain, in order:
|
|
the directories listed in the \fBTCLLIBPATH\fR environment variable,
|
|
the directory named by the \fBtcl_library\fR global variable,
|
|
the parent directory of \fBtcl_library\fR,
|
|
the directories listed in the \fBtcl_pkgPath\fR variable.
|
|
Additional locations to look for files and package indices should
|
|
normally be added to this variable using \fBlappend\fR.
|
|
.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
|
|
assigned to the \fBtcl_library\fR variable and therefore returned by
|
|
the command \fBinfo library\fR). If this variable is not 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. Directories must be specified in
|
|
Tcl format, using
|
|
.QW /
|
|
as the path separator, regardless of platform.
|
|
This variable is only used when initializing the \fBauto_path\fR variable.
|
|
.SS "WORD BOUNDARY DETERMINATION VARIABLES"
|
|
These variables are only used in the \fBtcl_endOfWord\fR,
|
|
\fBtcl_startOfNextWord\fR, \fBtcl_startOfPreviousWord\fR,
|
|
\fBtcl_wordBreakAfter\fR, and \fBtcl_wordBreakBefore\fR commands.
|
|
.TP
|
|
\fBtcl_nonwordchars\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 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.
|
|
.SH "SEE ALSO"
|
|
env(n), info(n), re_syntax(n)
|
|
.SH KEYWORDS
|
|
auto-exec, auto-load, library, unknown, word, whitespace
|
|
'\"Local Variables:
|
|
'\"mode: nroff
|
|
'\"End:
|