通讯编程

开发平台：
Visual C++

library.n：源码内容
							'"
'" 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.16 2001/08/24 06:03:15 dgp Exp $
.so man.macros
.TH library n "8.0" Tcl "Tcl Built-In Commands"
.BS
.SH 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
.SH SYNOPSIS
.nf
fBauto_execok fIcmdfR
fBauto_import fIpatternfR
fBauto_load fIcmdfR
fBauto_mkindex fIdir pattern pattern ...fR
fBauto_mkindex_old fIdir pattern pattern ...fR
fBauto_qualify fIcommand namespacefR
fBauto_resetfR
fBtcl_findLibrary fIbasename version patch initScript enVarName varNamefR
fBparray fIarrayNamefR
.VS
fBtcl_endOfWord fIstr startfR
fBtcl_startOfNextWord fIstr startfR
fBtcl_startOfPreviousWord fIstr startfR
fBtcl_wordBreakAfter fIstr startfR
fBtcl_wordBreakBefore fIstr startfR
.VE
.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 libraryfR
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$fIappfB_libraryfR
global variable, where fIappfR is the name of the application.
For example, the location of the Tk library is kept in the variable
fB$tk_libraryfR.
.PP
To access the procedures in the Tcl library, an application should
source the file fBinit.tclfR in the library, for example with
the Tcl command
.CS
fBsource [file join [info library] init.tcl]fR
.CE
If the library procedure fBTcl_InitfR is invoked from an application's
fBTcl_AppInitfR procedure, this happens automatically.
The code in fBinit.tclfR will define the fBunknownfR 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 fIcmdfR
Determines whether there is an executable file or shell builtin
by the name fIcmdfR.  If so, it returns a list of arguments to be
passed to fBexecfR to execute the executable file or shell builtin
named by fIcmdfR.  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
fIcmdfR.  On Windows platforms, the search is expanded with the same
directories and file extensions as used by fBexecfR. fBAuto_execfR
remembers information about previous searches in an array named
fBauto_execsfR;  this avoids the path search in future calls for the
same fIcmdfR.  The command fBauto_resetfR may be used to force
fBauto_execokfR to forget its cached information.
.TP
fBauto_import fIpatternfR
fBAuto_importfR is invoked during fBnamespace importfR to see if
the imported commands specified by fIpatternfR 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_importfR
does nothing.  The pattern matching is performed according to the
matching rules of fBnamespace importfR.
.TP
fBauto_load fIcmdfR
This command attempts to load the definition for a Tcl command named
fIcmdfR.  To do this, it searches an fIauto-load pathfR, which is
a list of one or more directories.  The auto-load path is given by the
global variable fB$auto_pathfR if it exists.  If there is no
fB$auto_pathfR 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 fBtclIndexfR that describes one or more
commands defined in that directory and a script to evaluate to load
each of the commands.  The fBtclIndexfR file should be generated
with the fBauto_mkindexfR command.  If fIcmdfR is found in an
index file, then the appropriate script is evaluated to create the
command.  The fBauto_loadfR command returns 1 if fIcmdfR was
successfully created.  The command returns 0 if there was no index
entry for fIcmdfR or if the script didn't actually define fIcmdfR
(e.g. because index information is out of date).  If an error occurs
while processing the script, then that error is returned.
fBAuto_loadfR only reads the index information once and saves it in
the array fBauto_indexfR;  future calls to fBauto_loadfR check for
fIcmdfR in the array rather than re-reading the index files.  The
cached index information may be deleted with the command
fBauto_resetfR.  This will force the next fBauto_loadfR command to
reload the index database from disk.
.TP
fBauto_mkindex fIdir pattern pattern ...fR
Generates an index suitable for use by fBauto_loadfR.  The command
searches fIdirfR for all files whose names match any of the
fIpatternfR arguments (matching is done with the fBglobfR
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 fBtclIndexfR in fIdirfR. If no pattern is given a pattern of
fB*.tclfR will be assumed.  For example, the command
.RS
.CS
fBauto_mkindex foo *.tclfR
.CE
.LP
will read all the fB.tclfR files in subdirectory fBfoofR and
generate a new index file fBfoo/tclIndexfR.
.PP
fBAuto_mkindexfR 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_oldfR parses the Tcl scripts in a relatively
unsophisticated way:  if any line contains the word fBprocfR
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 fBprocfR) 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_resetfR
Destroys all the information cached by fBauto_execokfR and
fBauto_loadfR.  This information will be re-read from disk the next
time it is needed.  fBAuto_resetfR 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 namespacefR
Computes a list of fully qualified names for fIcommandfR.  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 fIcommandfR is
relative and fInamespacefR is not fB::fR, the list returned has
two elements:  fIcommandfR scoped by fInamespacefR, as if it were
a command in the fInamespacefR namespace; and fIcommandfR as if it
were a command in the global namespace.  Otherwise, if either
fIcommandfR is absolute (it begins with fB::fR), or
fInamespacefR is fB::fR, the list contains only fIcommandfR as
if it were a command in the global namespace.
.RS
.PP
fBAuto_qualifyfR is used by the auto-loading facilities in Tcl, both
for producing auto-loading indexes such as fIpkgIndex.tclfR, and for
performing the actual auto-loading of functions at runtime.
.RE
.TP
fBtcl_findLibrary fIbasename version patch initScript enVarName varNamefR
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 fIbasenameversionfP
(e.g., tk8.0), but it might be "library" when in the build hierarchies.
The fIinitScriptfR 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 fIvarNamefP.
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 fIenVarNamefP;
relative to the Tcl library directory;
relative to the executable file in the standard installation
bin or bin/fIarchfP directory;
relative to the executable file in the current build tree;
relative to the executable file in a parallel build tree.
.TP
fBparray fIarrayNamefR
Prints on standard output the names and values of all the elements
in the array fIarrayNamefR.
fBArrayNamefR must be an array accessible to the caller of fBparrayfR.
It may be either local or global.
.TP
fBtcl_endOfWord fIstr startfR
.VS
Returns the index of the first end-of-word location that occurs after
a starting index fIstartfR in the string fIstrfR.  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_wordcharsfR and fBtcl_nonwordcharsfR below
for more details on how Tcl determines which characters are word
characters.
.TP
fBtcl_startOfNextWord fIstr startfR
Returns the index of the first start-of-word location that occurs
after a starting index fIstartfR in the string fIstrfR.  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 startfR
Returns the index of the first start-of-word location that occurs
before a starting index fIstartfR in the string fIstrfR.  Returns
-1 if there are no more start-of-word locations before the starting
point.
.TP
fBtcl_wordBreakAfter fIstr startfR
Returns the index of the first word boundary after the starting index
fIstartfR in the string fIstrfR.  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 startfR
Returns the index of the first word boundary before the starting index
fIstartfR in the string fIstrfR.  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.
.VE
.SH "VARIABLES"
.PP
The following global variables are defined or used by the procedures in
the Tcl library:
.TP
fBauto_execsfR
Used by fBauto_execokfR to record information about whether
particular commands exist as executable files.
.TP
fBauto_indexfR
Used by fBauto_loadfR to save the index information read from
disk.
.TP
fBauto_noexecfR
If set to any value, then fBunknownfR will not attempt to auto-exec
any commands.
.TP
fBauto_noloadfR
If set to any value, then fBunknownfR will not attempt to auto-load
any commands.
.TP
fBauto_pathfR
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.
.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_libraryfR variable and therefore returned by
the command fBinfo libraryfR).  If this variable isn't 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 "/" as the path separator, regardless of platform.
This variable is only used when initializing the fBauto_pathfR variable.
.TP
fBtcl_nonwordcharsfR
.VS
This variable contains a regular expression that is used by routines
like fBtcl_endOfWordfR 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_wordcharsfR
This variable contains a regular expression that is used by routines
like fBtcl_endOfWordfR 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.
.VE
.TP
fBunknown_pendingfR
Used by fBunknownfR to record the command(s) for which it is
searching.
It is used to detect errors where fBunknownfR recurses on itself
infinitely.
The variable is unset before fBunknownfR returns.
.SH "SEE ALSO"
info(n), re_syntax(n)
.SH KEYWORDS
auto-exec, auto-load, library, unknown, word, whitespace 

						