<HTML><HEAD><TITLE>Tcl Built-In Commands - library manual page</TITLE></HEAD><BODY> <DL> <DD><A HREF="library.htm#M2" NAME="L522">NAME</A> <DL><DD>library - standard library of Tcl procedures</DL> <DD><A HREF="library.htm#M3" NAME="L523">SYNOPSIS</A> <DL> <DD><B>auto_execok </B><I>cmd</I> <DD><B>auto_load </B><I>cmd</I> <DD><B>auto_mkindex </B><I>dir pattern pattern ...</I> <DD><B>auto_reset</B> <DD><B>parray </B><I>arrayName</I> <DD><B>tcl_endOfWord </B><I>str start</I> <DD><B>tcl_startOfNextWord </B><I>str start</I> <DD><B>tcl_startOfPreviousWord </B><I>str start</I> <DD><B>tcl_wordBreakAfter </B><I>str start</I> <DD><B>tcl_wordBreakBefore </B><I>str start</I> </DL> <DD><A HREF="library.htm#M4" NAME="L524">INTRODUCTION</A> <DD><A HREF="library.htm#M5" NAME="L525">COMMAND PROCEDURES</A> <DL> <DD><A HREF="library.htm#M6" NAME="L526"><B>auto_execok </B><I>cmd</I></A> <DD><A HREF="library.htm#M7" NAME="L527"><B>auto_load </B><I>cmd</I></A> <DD><A HREF="library.htm#M8" NAME="L528"><B>auto_mkindex </B><I>dir pattern pattern ...</I></A> <DD><A HREF="library.htm#M9" NAME="L529"><B>auto_reset</B></A> <DD><A HREF="library.htm#M10" NAME="L530"><B>parray </B><I>arrayName</I></A> <DD><A HREF="library.htm#M11" NAME="L531"><B>tcl_endOfWord </B><I>str start</I></A> <DD><A HREF="library.htm#M12" NAME="L532"><B>tcl_startOfNextWord </B><I>str start</I></A> <DD><A HREF="library.htm#M13" NAME="L533"><B>tcl_startOfPreviousWord </B><I>str start</I></A> <DD><A HREF="library.htm#M14" NAME="L534"><B>tcl_wordBreakAfter </B><I>str start</I></A> <DD><A HREF="library.htm#M15" NAME="L535"><B>tcl_wordBreakBefore </B><I>str start</I></A> </DL> <DD><A HREF="library.htm#M16" NAME="L536">VARIABLES</A> <DL> <DD><A HREF="library.htm#M17" NAME="L537"><B>auto_execs</B></A> <DD><A HREF="library.htm#M18" NAME="L538"><B>auto_index</B></A> <DD><A HREF="library.htm#M19" NAME="L539"><B>auto_noexec</B></A> <DD><A HREF="library.htm#M20" NAME="L540"><B>auto_noload</B></A> <DD><A HREF="library.htm#M21" NAME="L541"><B>auto_path</B></A> <DD><A HREF="library.htm#M22" NAME="L542"><B>env(TCL_LIBRARY)</B></A> <DD><A HREF="library.htm#M23" NAME="L543"><B>env(TCLLIBPATH)</B></A> <DD><A HREF="library.htm#M24" NAME="L544"><B>tcl_nonwordchars</B></A> <DD><A HREF="library.htm#M25" NAME="L545"><B>tcl_wordchars</B></A> <DD><A HREF="library.htm#M26" NAME="L546"><B>unknown_active</B></A> </DL> <DD><A HREF="library.htm#M27" NAME="L547">KEYWORDS</A> </DL><HR> <H3><A NAME="M2">NAME</A></H3> library - standard library of Tcl procedures <H3><A NAME="M3">SYNOPSIS</A></H3> <B>auto_execok </B><I>cmd</I><BR> <B>auto_load </B><I>cmd</I><BR> <B>auto_mkindex </B><I>dir pattern pattern ...</I><BR> <B>auto_reset</B><BR> <B>parray </B><I>arrayName</I><BR> <B>tcl_endOfWord </B><I>str start</I><BR> <B>tcl_startOfNextWord </B><I>str start</I><BR> <B>tcl_startOfPreviousWord </B><I>str start</I><BR> <B>tcl_wordBreakAfter </B><I>str start</I><BR> <B>tcl_wordBreakBefore </B><I>str start</I><BR> <H3><A NAME="M4">INTRODUCTION</A></H3> 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 <B><A HREF="../TclCmd/info.htm">info library</A></B> 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 <B>$</B><I>app</I><B>_library</B> global variable, where <I>app</I> is the name of the application. For example, the location of the Tk library is kept in the variable <B>$tk_library</B>. <P> To access the procedures in the Tcl library, an application should source the file <B>init.tcl</B> in the library, for example with the Tcl command <PRE><B>source [file join [info library] init.tcl]</B></PRE> If the library procedure <B>Tcl_Init</B> is invoked from an application's <B><A HREF="../TclLib/AppInit.htm">Tcl_AppInit</A></B> procedure, this happens automatically. The code in <B>init.tcl</B> will define the <B><A HREF="../TclCmd/unknown.htm">unknown</A></B> procedure and arrange for the other procedures to be loaded on-demand using the auto-load mechanism defined below. <H3><A NAME="M5">COMMAND PROCEDURES</A></H3> The following procedures are provided in the Tcl library: <P> <DL> <P><DT><A NAME="M6"><B>auto_execok </B><I>cmd</I></A><DD> Determines whether there is an executable file by the name <I>cmd</I>. 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 <I>cmd</I> in any of those directories. If so, it returns 1; if not it returns 0. <B>Auto_exec</B> remembers information about previous searches in an array named <B>auto_execs</B>; this avoids the path search in future calls for the same <I>cmd</I>. The command <B>auto_reset</B> may be used to force <B>auto_execok</B> to forget its cached information. <P><DT><A NAME="M7"><B>auto_load </B><I>cmd</I></A><DD> This command attempts to load the definition for a Tcl command named <I>cmd</I>. To do this, it searches an <I>auto-load path</I>, which is a list of one or more directories. The auto-load path is given by the global variable <B>$auto_path</B> if it exists. If there is no <B>$auto_path</B> 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 <B>tclIndex</B> that describes one or more commands defined in that directory and a script to evaluate to load each of the commands. The <B>tclIndex</B> file should be generated with the <B>auto_mkindex</B> command. If <I>cmd</I> is found in an index file, then the appropriate script is evaluated to create the command. The <B>auto_load</B> command returns 1 if <I>cmd</I> was successfully created. The command returns 0 if there was no index entry for <I>cmd</I> or if the script didn't actually define <I>cmd</I> (e.g. because index information is out of date). If an error occurs while processing the script, then that error is returned. <B>Auto_load</B> only reads the index information once and saves it in the array <B>auto_index</B>; future calls to <B>auto_load</B> check for <I>cmd</I> in the array rather than re-reading the index files. The cached index information may be deleted with the command <B>auto_reset</B>. This will force the next <B>auto_load</B> command to reload the index database from disk. <P><DT><A NAME="M8"><B>auto_mkindex </B><I>dir pattern pattern ...</I></A><DD> Generates an index suitable for use by <B>auto_load</B>. The command searches <I>dir</I> for all files whose names match any of the <I>pattern</I> arguments (matching is done with the <B><A HREF="../TclCmd/glob.htm">glob</A></B> 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 <B>tclIndex</B> in <I>dir</I>. If no pattern is given a pattern of <B>*.tcl</B> will be assumed. For example, the command <PRE><B>auto_mkindex foo *.tcl</B></PRE> <P> will read all the <B>.tcl</B> files in subdirectory <B>foo</B> and generate a new index file <B>foo/tclIndex</B>. <P><B>Auto_mkindex</B> parses the Tcl scripts in a relatively unsophisticated way: if any line contains the word <B><A HREF="../TclCmd/proc.htm">proc</A></B> 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 <B><A HREF="../TclCmd/proc.htm">proc</A></B>) will not be indexed. <P><DT><A NAME="M9"><B>auto_reset</B></A><DD> Destroys all the information cached by <B>auto_execok</B> and <B>auto_load</B>. This information will be re-read from disk the next time it is needed. <B>Auto_reset</B> 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. <P><DT><A NAME="M10"><B>parray </B><I>arrayName</I></A><DD> Prints on standard output the names and values of all the elements in the array <I>arrayName</I>. <B>ArrayName</B> must be an array accessible to the caller of <B>parray</B>. It may be either local or global. <P><DT><A NAME="M11"><B>tcl_endOfWord </B><I>str start</I></A><DD> Returns the index of the first end-of-word location that occurs after a starting index <I>start</I> in the string <I>str</I>. 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 <B>tcl_wordchars</B> and <B>tcl_nonwordchars</B> below for more details on how Tcl determines which characters are word characters. <P><DT><A NAME="M12"><B>tcl_startOfNextWord </B><I>str start</I></A><DD> Returns the index of the first start-of-word location that occurs after a starting index <I>start</I> in the string <I>str</I>. 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. <P><DT><A NAME="M13"><B>tcl_startOfPreviousWord </B><I>str start</I></A><DD> Returns the index of the first start-of-word location that occurs before a starting index <I>start</I> in the string <I>str</I>. Returns -1 if there are no more start-of-word locations before the starting point. <P><DT><A NAME="M14"><B>tcl_wordBreakAfter </B><I>str start</I></A><DD> Returns the index of the first word boundary after the starting index <I>start</I> in the string <I>str</I>. 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. <P><DT><A NAME="M15"><B>tcl_wordBreakBefore </B><I>str start</I></A><DD> Returns the index of the first word boundary before the starting index <I>start</I> in the string <I>str</I>. 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. <P></DL> <H3><A NAME="M16">VARIABLES</A></H3> The following global variables are defined or used by the procedures in the Tcl library: <P> <DL> <P><DT><A NAME="M17"><B>auto_execs</B></A><DD> Used by <B>auto_execok</B> to record information about whether particular commands exist as executable files. <P><DT><A NAME="M18"><B>auto_index</B></A><DD> Used by <B>auto_load</B> to save the index information read from disk. <P><DT><A NAME="M19"><B>auto_noexec</B></A><DD> If set to any value, then <B><A HREF="../TclCmd/unknown.htm">unknown</A></B> will not attempt to auto-exec any commands. <P><DT><A NAME="M20"><B>auto_noload</B></A><DD> If set to any value, then <B><A HREF="../TclCmd/unknown.htm">unknown</A></B> will not attempt to auto-load any commands. <P><DT><A NAME="M21"><B>auto_path</B></A><DD> If set, then it must contain a valid Tcl list giving directories to search during auto-load operations. <P><DT><A NAME="M22"><B>env(TCL_LIBRARY)</B></A><DD> If set, then it specifies the location of the directory containing library scripts (the value of this variable will be returned by the command <B><A HREF="../TclCmd/info.htm">info library</A></B>). If this variable isn't set then a default value is used. <P><DT><A NAME="M23"><B>env(TCLLIBPATH)</B></A><DD> If set, then it must contain a valid Tcl list giving directories to search during auto-load operations. This variable is only used if <B>auto_path</B> is not defined. <P><DT><A NAME="M24"><B>tcl_nonwordchars</B></A><DD> This variable contains a regular expression that is used by routines like <B>tcl_endOfWord</B> 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. <P><DT><A NAME="M25"><B>tcl_wordchars</B></A><DD> This variable contains a regular expression that is used by routines like <B>tcl_endOfWord</B> 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. <P><DT><A NAME="M26"><B>unknown_active</B></A><DD> This variable is set by <B><A HREF="../TclCmd/unknown.htm">unknown</A></B> to indicate that it is active. It is used to detect errors where <B><A HREF="../TclCmd/unknown.htm">unknown</A></B> recurses on itself infinitely. The variable is unset before <B><A HREF="../TclCmd/unknown.htm">unknown</A></B> returns. <P></DL> <H3><A NAME="M27">KEYWORDS</A></H3> <A href="../Keywords/A.htm#auto-exec">auto-exec</A>, <A href="../Keywords/A.htm#auto-load">auto-load</A>, <A href="../Keywords/L.htm#library">library</A>, <A href="../Keywords/U.htm#unknown">unknown</A>, <A href="../Keywords/W.htm#word">word</A>, <A href="../Keywords/W.htm#whitespace">whitespace</A> <HR><PRE> <A HREF="../copyright.htm">Copyright</A> © 1991-1993 The Regents of the University of California. <A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc. <A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE> </BODY></HTML>