Tcl Built-In Commands library(1T)
NAME
autoexecok, autoimport, autoload, automkindex,
automkindexold, autoqualify, autoreset, tclfindLibrary,
parray, tclendOfWord, tclstartOfNextWord,
tclstartOfPreviousWord, tclwordBreakAfter,
tclwordBreakBefore - standard library of Tcl procedures
SYNOPSIS
autoexecok cmd
autoimport pattern
autoload cmd
automkindex dir pattern pattern ...
automkindexold dir pattern pattern ...
autoqualify command namespace
autoreset
tclfindLibrary basename version patch initScript enVarName varName
parray arrayName
tclendOfWord str start
tclstartOfNextWord str start
tclstartOfPreviousWord str start
tclwordBreakAfter str start
tclwordBreakBefore str start
INTRODUCTION
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 applica-
tions. The location of the Tcl library is returned by the
info library 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 nor-
mally given by the value of the $applibrary global vari-
able, where app is the name of the application. For exam-
ple, the location of the Tk library is kept in the variable
$tklibrary.
To access the procedures in the Tcl library, an application
should source the file init.tcl in the library, for example
with the Tcl command
source [file join [info library] init.tcl]
If the library procedure TclInit is invoked from an
application's TclAppInit procedure, this happens automati-
cally. The code in init.tcl will define the unknown pro-
cedure and arrange for the other procedures to be loaded
on-demand using the auto-load mechanism defined below.
Tcl Last change: 8.0 1
Tcl Built-In Commands library(1T)
COMAND PROCEDURES
The following procedures are provided in the Tcl library:
autoexecok cmd
Determines whether there is an executable file or shell
builtin by the name cmd. If so, it returns a list of
arguments to be passed to exec to execute the execut-
able file or shell builtin named by cmd. 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 execut-
able file named cmd. On Windows platforms, the search
is expanded with the same directories and file exten-
sions as used by exec. Autoexec remembers information
about previous searches in an array named autoexecs;
this avoids the path search in future calls for the
same cmd. The command autoreset may be used to force
autoexecok to forget its cached information.
autoimport pattern
Autoimport is invoked during namespace import to see
if the imported commands specified by pattern 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, autoimport does noth-
ing. The pattern matching is performed according to
the matching rules of namespace import.
autoload cmd
This command attempts to load the definition for a Tcl
command named cmd. To do this, it searches an auto-
load path, which is a list of one or more directories.
The auto-load path is given by the global variable
$autopath if it exists. If there is no $autopath
variable, then the TCLIBPATH environment variable is
used, if it exists. Otherwise the auto-load path con-
sists of just the Tcl library directory. Within each
directory in the auto-load path there must be a file
tclIndex that describes one or more commands defined in
that directory and a script to evaluate to load each of
the commands. The tclIndex file should be generated
with the automkindex command. If cmd is found in an
index file, then the appropriate script is evaluated to
create the command. The autoload command returns 1 if
cmd was successfully created. The command returns 0 if
there was no index entry for cmd or if the script
didn't actually define cmd (e.g. because index informa-
tion is out of date). If an error occurs while pro-
cessing the script, then that error is returned.
Autoload only reads the index information once and
saves it in the array autoindex; future calls to
Tcl Last change: 8.0 2
Tcl Built-In Commands library(1T)
autoload check for cmd in the array rather than re-
reading the index files. The cached index information
may be deleted with the command autoreset. This will
force the next autoload command to reload the index
database from disk.
automkindex dir pattern pattern ...
Generates an index suitable for use by autoload. The
command searches dir for all files whose names match
any of the pattern arguments (matching is done with the
glob command), generates an index of all the Tcl com-
mand procedures defined in all the matching files, and
stores the index information in a file named tclIndex
in dir. If no pattern is given a pattern of *.tcl will
be assumed. For example, the command
automkindex foo *.tcl
will read all the .tcl files in subdirectory foo and
generate a new index file foo/tclIndex.
Automkindex 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) automkindexparser package to
register other commands that can contribute to the
autoload index. You will have to read through auto.tcl
to see how this works.
Automkindexold parses the Tcl scripts in a relatively
unsophisticated way: if any line contains the word
proc 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 proc) will not be indexed. If your script
contains "dangerous" code, such as global initializa-
tion code or procedure names with special characters
like $, *, [ or ], you are safer using
automkindexold.
autoreset
Destroys all the information cached by autoexecok and
autoload. This information will be re-read from disk
the next time it is needed. Autoreset 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.
autoqualify command namespace
Computes a list of fully qualified names for command.
This list mirrors the path a standard Tcl interpreter
follows for command lookups: first it looks for the
Tcl Last change: 8.0 3
Tcl Built-In Commands library(1T)
command in the current namespace, and then in the glo-
bal namespace. Accordingly, if command is relative and
namespace is not ::, the list returned has two ele-
ments: command scoped by namespace, as if it were a
command in the namespace namespace; and command as if
it were a command in the global namespace. Otherwise,
if either command is absolute (it begins with ::), or
namespace is ::, the list contains only command as if
it were a command in the global namespace.
Autoqualify is used by the auto-loading facilities in
Tcl, both for producing auto-loading indexes such as
pkgIndex.tcl, and for performing the actual auto-
loading of functions at runtime.
Name
tclfindLibrary basename version patch initScript enVarName var-
This is a standard search procedure for use by exten-
sions during their initialization. They call this pro-
cedure to look for their script library in several
standard directories. The last component of the name
of the library directory is normally basenameversion
(e.g., tk8.0), but it might be "library" when in the
build hierarchies. The initScript 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 varName. 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 enVarName; relative to the Tcl
library directory; relative to the executable file in
the standard installation bin or bin/arch directory;
relative to the executable file in the current build
tree; relative to the executable file in a parallel
build tree.
parray arrayName
Prints on standard output the names and values of all
the elements in the array arrayName. ArrayName must be
an array accessible to the caller of parray. It may be
either local or global.
tclendOfWord str start
Returns the index of the first end-of-word location
that occurs after a starting index start in the string
str. An end-of-word location is defined to be the
first non-word character following the first word char-
acter after the starting point. Returns -1 if there
are no more end-of-word locations after the starting
point. See the description of tclwordchars and
tclnonwordchars below for more details on how Tcl
Tcl Last change: 8.0 4
Tcl Built-In Commands library(1T)
determines which characters are word characters.
tclstartOfNextWord str start
Returns the index of the first start-of-word location
that occurs after a starting index start in the string
str. 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.
tclstartOfPreviousWord str start
Returns the index of the first start-of-word location
that occurs before a starting index start in the string
str. Returns -1 if there are no more start-of-word
locations before the starting point.
tclwordBreakAfter str start
Returns the index of the first word boundary after the
starting index start in the string str. 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.
tclwordBreakBefore str start
Returns the index of the first word boundary before the
starting index start in the string str. 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.
VARIABLES
The following global variables are defined or used by the
procedures in the Tcl library:
autoexecs
Used by autoexecok to record information about whether
particular commands exist as executable files.
autoindex
Used by autoload to save the index information read
from disk.
autonoexec
If set to any value, then unknown will not attempt to
auto-exec any commands.
autonoload
If set to any value, then unknown will not attempt to
auto-load any commands.
autopath
Tcl Last change: 8.0 5
Tcl Built-In Commands library(1T)
If set, then it must contain a valid Tcl list giving
directories to search during auto-load operations.
This variable is initialized during startup to contain,
in order: the directories listed in the TCLIBPATH
environment variable, the directory named by the
$tcllibrary variable, the parent directory of
$tcllibrary, the directories listed in the
$tclpkgPath variable.
env(TCLIBRARY)
If set, then it specifies the location of the directory
containing library scripts (the value of this variable
will be assigned to the tcllibrary variable and there-
fore returned by the command info library). If this
variable isn't set then a default value is used.
env(TCLIBPATH)
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 "/"
as the path separator, regardless of platform. This
variable is only used when initializing the autopath
variable.
tclnonwordchars
This variable contains a regular expression that is
used by routines like tclendOfWord 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 under-
scores are considered non-word characters.
tclwordchars
This variable contains a regular expression that is
used by routines like tclendOfWord 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.
unknownpending
Used by unknown to record the command(s) for which it
is searching. It is used to detect errors where
unknown recurses on itself infinitely. The variable is
unset before unknown returns.
Tcl Last change: 8.0 6
Tcl Built-In Commands library(1T)
SEE ALSO
info(1T), resyntax(1T)
KEYWORDS
auto-exec, auto-load, library, unknown, word, whitespace
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWTcl
Interface Stability Uncommitted
NOTES
Source for Tcl is available on http:/opensolaris.org.
Tcl Last change: 8.0 7
|
