diff options
author | phk <phk@FreeBSD.org> | 1996-06-26 06:06:43 +0000 |
---|---|---|
committer | phk <phk@FreeBSD.org> | 1996-06-26 06:06:43 +0000 |
commit | 00febf60093a024ccc629fdfc81e02a40c5f6572 (patch) | |
tree | 4d70f77f44120e6541d1418223baf06562774975 /contrib/tcl/doc/library.n | |
download | FreeBSD-src-00febf60093a024ccc629fdfc81e02a40c5f6572.zip FreeBSD-src-00febf60093a024ccc629fdfc81e02a40c5f6572.tar.gz |
Tcl 7.5, various makefiles will be updated to use these sources as soon
as I get these back down to my machine.
Diffstat (limited to 'contrib/tcl/doc/library.n')
-rw-r--r-- | contrib/tcl/doc/library.n | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/contrib/tcl/doc/library.n b/contrib/tcl/doc/library.n new file mode 100644 index 0000000..232c799 --- /dev/null +++ b/contrib/tcl/doc/library.n @@ -0,0 +1,188 @@ +'\" +'\" 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. +'\" +'\" SCCS: @(#) library.n 1.20 96/03/25 20:18:29 +.so man.macros +.TH library n "" Tcl "Tcl Built-In Commands" +.BS +.SH NAME +library \- standard library of Tcl procedures +.SH SYNOPSIS +.nf +\fBauto_execok \fIcmd\fR +\fBauto_load \fIcmd\fR +\fBauto_mkindex \fIdir pattern pattern ...\fR +\fBauto_reset\fR +\fBparray \fIarrayName\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 +\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 [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 by the name \fIcmd\fR. +This command examines the directories in the current search path +(given by the PATH environment variable) to see if there is an +executable file named \fIcmd\fR in any of those directories. +If so, it returns 1; if not it returns 0. \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_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 +.VS +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. +.VE +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 +.VS +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 +.VE +(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 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. +.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 +\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. + +.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. +.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 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. +This variable is only used if \fBauto_path\fR is not defined. +.TP +\fBunknown_active\fR +This variable is set by \fBunknown\fR to indicate that it is active. +It is used to detect errors where \fBunknown\fR recurses on itself +infinitely. +The variable is unset before \fBunknown\fR returns. + +.SH KEYWORDS +auto-exec, auto-load, library, unknown |