 |
ActiveTcl User Guide
|
 |
|
- NAME
- 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
- SYNOPSIS
- auto_execok cmd
- auto_import pattern
- auto_load cmd
- auto_mkindex dir pattern pattern ...
- auto_mkindex_old dir pattern pattern ...
- auto_qualify command namespace
- auto_reset
- tcl_findLibrary basename version patch initScript
enVarName varName
- parray arrayName
- tcl_endOfWord str start
- tcl_startOfNextWord str start
- tcl_startOfPreviousWord str start
- tcl_wordBreakAfter str start
- tcl_wordBreakBefore str start
- INTRODUCTION
- COMMAND PROCEDURES
- auto_execok
cmd
- auto_import
pattern
- auto_load
cmd
- auto_mkindex dir
pattern pattern ...
- auto_reset
- auto_qualify
command namespace
- tcl_findLibrary
basename version patch initScript enVarName varName
- parray
arrayName
- tcl_endOfWord
str start
- tcl_startOfNextWord str start
- tcl_startOfPreviousWord str start
- tcl_wordBreakAfter
str start
- tcl_wordBreakBefore str start
- VARIABLES
- auto_execs
- auto_index
- auto_noexec
- auto_noload
- auto_path
- env(TCL_LIBRARY)
- env(TCLLIBPATH)
- tcl_nonwordchars
- tcl_wordchars
- unknown_pending
- SEE ALSO
- KEYWORDS
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
auto_execok cmd
auto_import pattern
auto_load cmd
auto_mkindex dir pattern pattern ...
auto_mkindex_old dir pattern pattern ...
auto_qualify command namespace
auto_reset
tcl_findLibrary basename version patch initScript
enVarName varName
parray arrayName
tcl_endOfWord str start
tcl_startOfNextWord str start
tcl_startOfPreviousWord str start
tcl_wordBreakAfter str start
tcl_wordBreakBefore str start
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 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 normally given by the value of the
$app_library global variable, where app
is the name of the application. For example, the location of the Tk
library is kept in the variable $tk_library.
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 Tcl_Init is invoked from an
application's Tcl_AppInit procedure, this happens
automatically. The code in init.tcl will define the unknown procedure and arrange
for the other procedures to be loaded on-demand using the auto-load
mechanism defined below.
The following procedures are provided in the Tcl library:
- auto_execok 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 executable 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 executable file named cmd. On Windows
platforms, the search is expanded with the same directories and
file extensions as used by exec. Auto_exec remembers
information about previous searches in an array named
auto_execs; this avoids the path search in future calls for
the same cmd. The command auto_reset may be used to
force auto_execok to forget its cached information.
- auto_import pattern
- Auto_import 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,
auto_import does nothing. The pattern matching is performed
according to the matching rules of namespace import.
- auto_load 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 $auto_path if it exists. If
there is no $auto_path 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
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
auto_mkindex command. If cmd is found in an index
file, then the appropriate script is evaluated to create the
command. The auto_load 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 information is out of date). If an
error occurs while processing the script, then that error is
returned. Auto_load only reads the index information once
and saves it in the array auto_index; future calls to
auto_load check for cmd in the array rather than
re-reading the index files. The cached index information may be
deleted with the command auto_reset. This will force the
next auto_load command to reload the index database from
disk.
- auto_mkindex dir pattern pattern
...
- Generates an index suitable for use by auto_load. 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 command 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
auto_mkindex foo *.tcl
will read all the .tcl files in subdirectory foo
and generate a new index file foo/tclIndex.
Auto_mkindex 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.
Auto_mkindex_old 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
initialization code or procedure names with special characters like
$, *, [ or ], you are safer using
auto_mkindex_old.
- auto_reset
- Destroys all the information cached by auto_execok and
auto_load. This information will be re-read from disk the
next time it is needed. Auto_reset 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.
- auto_qualify 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 command in the current
namespace, and then in the global namespace. Accordingly, if
command is relative and namespace is not ::,
the list returned has two elements: 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.
Auto_qualify 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.
- tcl_findLibrary basename version patch
initScript enVarName varName
- 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
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.
- tcl_endOfWord 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 character after the starting point.
Returns -1 if there are no more end-of-word locations after the
starting point. See the description of tcl_wordchars and
tcl_nonwordchars below for more details on how Tcl
determines which characters are word characters.
- tcl_startOfNextWord 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.
- tcl_startOfPreviousWord 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.
- tcl_wordBreakAfter 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.
- tcl_wordBreakBefore 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.
The following global variables are defined or used by the
procedures in the Tcl library:
- auto_execs
- Used by auto_execok to record information about whether
particular commands exist as executable files.
- auto_index
- Used by auto_load to save the index information read
from disk.
- auto_noexec
- If set to any value, then unknown will not attempt to
auto-exec any commands.
- auto_noload
- If set to any value, then unknown will not attempt to
auto-load any commands.
- auto_path
- 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 TCLLIBPATH environment variable, the directory named
by the $tcl_library variable, the parent directory of $tcl_library,
the directories listed in the $tcl_pkgPath variable.
- env(TCL_LIBRARY)
- If set, then it specifies the location of the directory
containing library scripts (the value of this variable will be
assigned to the tcl_library variable and therefore returned
by the command info
library). If this variable isn't set then a default value
is used.
- env(TCLLIBPATH)
- 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 auto_path variable.
- tcl_nonwordchars
- This variable contains a regular expression that is used by
routines like tcl_endOfWord 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.
- tcl_wordchars
- This variable contains a regular expression that is used by
routines like tcl_endOfWord 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.
- unknown_pending
- 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.
info, re_syntax
auto-exec, auto-load, library, unknown, word, whitespace
Copyright © 1991-1993 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.