diff options
Diffstat (limited to 'tcl8.6/doc/library.n')
| -rw-r--r-- | tcl8.6/doc/library.n | 320 |
1 files changed, 0 insertions, 320 deletions
diff --git a/tcl8.6/doc/library.n b/tcl8.6/doc/library.n deleted file mode 100644 index 6f8f265..0000000 --- a/tcl8.6/doc/library.n +++ /dev/null @@ -1,320 +0,0 @@ -'\" -'\" 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 -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 -(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: |