--- /dev/null
+'\"
+'\" 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$
+.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 \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
+\fBtcl_wordBreakAfter \fIstr start\fR
+\fBtcl_wordBreakBefore \fIstr start\fR
+.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 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
+\fB$tk_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
+.CS
+\fBsource [file join [info library] init.tcl]\fR
+.CE
+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_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. 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 \fB$auto_path\fR if it exists. If there is no
+\fB$auto_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 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.
+\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
+.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.
+.PP
+\fBAuto_mkindex\fR 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_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 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
+(e.g., tk8.0), but it might be "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\fP.
+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\fP;
+relative to the Tcl library directory;
+relative to the executable file in the standard installation
+bin or bin/\fIarch\fP 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
+Prints on standard output the names and values of all the elements
+in the array \fIarrayName\fR.
+\fBArrayName\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
+.VS
+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.
+.VE
+
+.SH "VARIABLES"
+.PP
+The following global variables are defined or used by the procedures in
+the Tcl library:
+.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.
+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_library\fR variable and therefore returned by
+the command \fBinfo library\fR). 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_path\fR variable.
+.TP
+\fBtcl_nonwordchars\fR
+.VS
+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.
+.VE
+.TP
+\fBunknown_pending\fR
+Used by \fBunknown\fR to record the command(s) for which it is
+searching.
+It is used to detect errors where \fBunknown\fR recurses on itself
+infinitely.
+The variable is unset before \fBunknown\fR returns.
+
+.SH "SEE ALSO"
+info(n), re_syntax(n)
+
+.SH KEYWORDS
+auto-exec, auto-load, library, unknown, word, whitespace
OSDN Git Service
