| '\" |
| '\" 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 $ |
| '\" The definitions below are for supplemental macros used in Tcl/Tk |
| '\" manual entries. |
| '\" |
| '\" .AP type name in/out ?indent? |
| '\" Start paragraph describing an argument to a library procedure. |
| '\" type is type of argument (int, etc.), in/out is either "in", "out", |
| '\" or "in/out" to describe whether procedure reads or modifies arg, |
| '\" and indent is equivalent to second arg of .IP (shouldn't ever be |
| '\" needed; use .AS below instead) |
| '\" |
| '\" .AS ?type? ?name? |
| '\" Give maximum sizes of arguments for setting tab stops. Type and |
| '\" name are examples of largest possible arguments that will be passed |
| '\" to .AP later. If args are omitted, default tab stops are used. |
| '\" |
| '\" .BS |
| '\" Start box enclosure. From here until next .BE, everything will be |
| '\" enclosed in one large box. |
| '\" |
| '\" .BE |
| '\" End of box enclosure. |
| '\" |
| '\" .CS |
| '\" Begin code excerpt. |
| '\" |
| '\" .CE |
| '\" End code excerpt. |
| '\" |
| '\" .VS ?version? ?br? |
| '\" Begin vertical sidebar, for use in marking newly-changed parts |
| '\" of man pages. The first argument is ignored and used for recording |
| '\" the version when the .VS was added, so that the sidebars can be |
| '\" found and removed when they reach a certain age. If another argument |
| '\" is present, then a line break is forced before starting the sidebar. |
| '\" |
| '\" .VE |
| '\" End of vertical sidebar. |
| '\" |
| '\" .DS |
| '\" Begin an indented unfilled display. |
| '\" |
| '\" .DE |
| '\" End of indented unfilled display. |
| '\" |
| '\" .SO |
| '\" Start of list of standard options for a Tk widget. The |
| '\" options follow on successive lines, in four columns separated |
| '\" by tabs. |
| '\" |
| '\" .SE |
| '\" End of list of standard options for a Tk widget. |
| '\" |
| '\" .OP cmdName dbName dbClass |
| '\" Start of description of a specific option. cmdName gives the |
| '\" option's name as specified in the class command, dbName gives |
| '\" the option's name in the option database, and dbClass gives |
| '\" the option's class in the option database. |
| '\" |
| '\" .UL arg1 arg2 |
| '\" Print arg1 underlined, then print arg2 normally. |
| '\" |
| '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| '\" |
| '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| .if t .wh -1.3i ^B |
| .nr ^l \n(.l |
| .ad b |
| '\" # Start an argument description |
| .de AP |
| .ie !"\\$4"" .TP \\$4 |
| .el \{\ |
| . ie !"\\$2"" .TP \\n()Cu |
| . el .TP 15 |
| .\} |
| .ta \\n()Au \\n()Bu |
| .ie !"\\$3"" \{\ |
| \&\\$1 \\fI\\$2\\fP (\\$3) |
| .\".b |
| .\} |
| .el \{\ |
| .br |
| .ie !"\\$2"" \{\ |
| \&\\$1 \\fI\\$2\\fP |
| .\} |
| .el \{\ |
| \&\\fI\\$1\\fP |
| .\} |
| .\} |
| .. |
| '\" # define tabbing values for .AP |
| .de AS |
| .nr )A 10n |
| .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| .nr )B \\n()Au+15n |
| .\" |
| .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| .. |
| .AS Tcl_Interp Tcl_CreateInterp in/out |
| '\" # BS - start boxed text |
| '\" # ^y = starting y location |
| '\" # ^b = 1 |
| .de BS |
| .br |
| .mk ^y |
| .nr ^b 1u |
| .if n .nf |
| .if n .ti 0 |
| .if n \l'\\n(.lu\(ul' |
| .if n .fi |
| .. |
| '\" # BE - end boxed text (draw box now) |
| .de BE |
| .nf |
| .ti 0 |
| .mk ^t |
| .ie n \l'\\n(^lu\(ul' |
| .el \{\ |
| .\" Draw four-sided box normally, but don't draw top of |
| .\" box if the box started on an earlier page. |
| .ie !\\n(^b-1 \{\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .el \}\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .\} |
| .fi |
| .br |
| .nr ^b 0 |
| .. |
| '\" # VS - start vertical sidebar |
| '\" # ^Y = starting y location |
| '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| .de VS |
| .if !"\\$2"" .br |
| .mk ^Y |
| .ie n 'mc \s12\(br\s0 |
| .el .nr ^v 1u |
| .. |
| '\" # VE - end of vertical sidebar |
| .de VE |
| .ie n 'mc |
| .el \{\ |
| .ev 2 |
| .nf |
| .ti 0 |
| .mk ^t |
| \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| .sp -1 |
| .fi |
| .ev |
| .\} |
| .nr ^v 0 |
| .. |
| '\" # Special macro to handle page bottom: finish off current |
| '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| '\" # page bottom macro. |
| .de ^B |
| .ev 2 |
| 'ti 0 |
| 'nf |
| .mk ^t |
| .if \\n(^b \{\ |
| .\" Draw three-sided box if this is the box's first page, |
| .\" draw two sides but no top otherwise. |
| .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .\} |
| .if \\n(^v \{\ |
| .nr ^x \\n(^tu+1v-\\n(^Yu |
| \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| .\} |
| .bp |
| 'fi |
| .ev |
| .if \\n(^b \{\ |
| .mk ^y |
| .nr ^b 2 |
| .\} |
| .if \\n(^v \{\ |
| .mk ^Y |
| .\} |
| .. |
| '\" # DS - begin display |
| .de DS |
| .RS |
| .nf |
| .sp |
| .. |
| '\" # DE - end display |
| .de DE |
| .fi |
| .RE |
| .sp |
| .. |
| '\" # SO - start of list of standard options |
| .de SO |
| .SH "STANDARD OPTIONS" |
| .LP |
| .nf |
| .ta 5.5c 11c |
| .ft B |
| .. |
| '\" # SE - end of list of standard options |
| .de SE |
| .fi |
| .ft R |
| .LP |
| See the \\fBoptions\\fR manual entry for details on the standard options. |
| .. |
| '\" # OP - start of full description for a single option |
| .de OP |
| .LP |
| .nf |
| .ta 4c |
| Command-Line Name: \\fB\\$1\\fR |
| Database Name: \\fB\\$2\\fR |
| Database Class: \\fB\\$3\\fR |
| .fi |
| .IP |
| .. |
| '\" # CS - begin code excerpt |
| .de CS |
| .RS |
| .nf |
| .ta .25i .5i .75i 1i |
| .. |
| '\" # CE - end code excerpt |
| .de CE |
| .fi |
| .RE |
| .. |
| .de UL |
| \\$1\l'|0\(ul'\\$2 |
| .. |
| .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 |