321 lines
19 KiB
HTML
321 lines
19 KiB
HTML
<HTML><HEAD><TITLE>Tcl Built-In Commands - library manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="library.htm#M2" NAME="L613">NAME</A>
|
|
<DL><DD>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</DL>
|
|
<DD><A HREF="library.htm#M3" NAME="L614">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>auto_execok </B><I>cmd</I>
|
|
<DD><B>auto_import </B><I>pattern</I>
|
|
<DD><B>auto_load </B><I>cmd</I>
|
|
<DD><B>auto_mkindex </B><I>dir pattern pattern ...</I>
|
|
<DD><B>auto_mkindex_old </B><I>dir pattern pattern ...</I>
|
|
<DD><B>auto_qualify </B><I>command namespace</I>
|
|
<DD><B>auto_reset</B>
|
|
<DD><B>tcl_findLibrary </B><I>basename version patch initScript enVarName varName</I>
|
|
<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="L615">INTRODUCTION</A>
|
|
<DD><A HREF="library.htm#M5" NAME="L616">COMMAND PROCEDURES</A>
|
|
<DL>
|
|
<DD><A HREF="library.htm#M6" NAME="L617"><B>auto_execok </B><I>cmd</I></A>
|
|
<DD><A HREF="library.htm#M7" NAME="L618"><B>auto_import </B><I>pattern</I></A>
|
|
<DD><A HREF="library.htm#M8" NAME="L619"><B>auto_load </B><I>cmd</I></A>
|
|
<DD><A HREF="library.htm#M9" NAME="L620"><B>auto_mkindex </B><I>dir pattern pattern ...</I></A>
|
|
<DD><A HREF="library.htm#M10" NAME="L621"><B>auto_reset</B></A>
|
|
<DD><A HREF="library.htm#M11" NAME="L622"><B>auto_qualify </B><I>command namespace</I></A>
|
|
<DD><A HREF="library.htm#M12" NAME="L623"><B>tcl_findLibrary </B><I>basename version patch initScript enVarName varName</I></A>
|
|
<DD><A HREF="library.htm#M13" NAME="L624"><B>parray </B><I>arrayName</I></A>
|
|
<DD><A HREF="library.htm#M14" NAME="L625"><B>tcl_endOfWord </B><I>str start</I></A>
|
|
<DD><A HREF="library.htm#M15" NAME="L626"><B>tcl_startOfNextWord </B><I>str start</I></A>
|
|
<DD><A HREF="library.htm#M16" NAME="L627"><B>tcl_startOfPreviousWord </B><I>str start</I></A>
|
|
<DD><A HREF="library.htm#M17" NAME="L628"><B>tcl_wordBreakAfter </B><I>str start</I></A>
|
|
<DD><A HREF="library.htm#M18" NAME="L629"><B>tcl_wordBreakBefore </B><I>str start</I></A>
|
|
</DL>
|
|
<DD><A HREF="library.htm#M19" NAME="L630">VARIABLES</A>
|
|
<DL>
|
|
<DD><A HREF="library.htm#M20" NAME="L631"><B>auto_execs</B></A>
|
|
<DD><A HREF="library.htm#M21" NAME="L632"><B>auto_index</B></A>
|
|
<DD><A HREF="library.htm#M22" NAME="L633"><B>auto_noexec</B></A>
|
|
<DD><A HREF="library.htm#M23" NAME="L634"><B>auto_noload</B></A>
|
|
<DD><A HREF="library.htm#M24" NAME="L635"><B>auto_path</B></A>
|
|
<DD><A HREF="library.htm#M25" NAME="L636"><B>env(TCL_LIBRARY)</B></A>
|
|
<DD><A HREF="library.htm#M26" NAME="L637"><B>env(TCLLIBPATH)</B></A>
|
|
<DD><A HREF="library.htm#M27" NAME="L638"><B>tcl_nonwordchars</B></A>
|
|
<DD><A HREF="library.htm#M28" NAME="L639"><B>tcl_wordchars</B></A>
|
|
<DD><A HREF="library.htm#M29" NAME="L640"><B>unknown_pending</B></A>
|
|
</DL>
|
|
<DD><A HREF="library.htm#M30" NAME="L641">SEE ALSO</A>
|
|
<DD><A HREF="library.htm#M31" NAME="L642">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
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
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>auto_execok </B><I>cmd</I><BR>
|
|
<B>auto_import </B><I>pattern</I><BR>
|
|
<B>auto_load </B><I>cmd</I><BR>
|
|
<B>auto_mkindex </B><I>dir pattern pattern ...</I><BR>
|
|
<B>auto_mkindex_old </B><I>dir pattern pattern ...</I><BR>
|
|
<B>auto_qualify </B><I>command namespace</I><BR>
|
|
<B>auto_reset</B><BR>
|
|
<B>tcl_findLibrary </B><I>basename version patch initScript enVarName varName</I><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="../TkCmd/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><A HREF="../TkLib/Init.htm">Tcl_Init</A></B> is invoked from an application's
|
|
<B><A HREF="../TkLib/AppInit.htm">Tcl_AppInit</A></B> procedure, this happens automatically.
|
|
The code in <B>init.tcl</B> will define the <B><A HREF="../TkCmd/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 or shell builtin
|
|
by the name <I>cmd</I>. If so, it returns a list of arguments to be
|
|
passed to <B><A HREF="../TkCmd/exec.htm">exec</A></B> to execute the executable file or shell builtin
|
|
named by <I>cmd</I>. 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
|
|
<I>cmd</I>. On Windows platforms, the search is expanded with the same
|
|
directories and file extensions as used by <B><A HREF="../TkCmd/exec.htm">exec</A></B>. <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_import </B><I>pattern</I></A><DD>
|
|
<B>Auto_import</B> is invoked during <B>namespace import</B> to see if
|
|
the imported commands specified by <I>pattern</I> 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, <B>auto_import</B>
|
|
does nothing. The pattern matching is performed according to the
|
|
matching rules of <B>namespace import</B>.
|
|
<P><DT><A NAME="M8"><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="M9"><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="../TkCmd/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 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.
|
|
<P><B>Auto_mkindex_old</B> parses the Tcl scripts in a relatively
|
|
unsophisticated way: if any line contains the word <B><A HREF="../TkCmd/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="../TkCmd/proc.htm">proc</A></B>) will not be indexed. If your
|
|
script contains "dangerous" code, such as global initialization
|
|
code or procedure names with special characters like <B>$</B>,
|
|
<B>*</B>, <B>[</B> or <B>]</B>, you are safer using auto_mkindex_old.
|
|
<P><DT><A NAME="M10"><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="M11"><B>auto_qualify </B><I>command namespace</I></A><DD>
|
|
Computes a list of fully qualified names for <I>command</I>. 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 <I>command</I> is
|
|
relative and <I>namespace</I> is not <B>::</B>, the list returned has
|
|
two elements: <I>command</I> scoped by <I>namespace</I>, as if it were
|
|
a command in the <I>namespace</I> namespace; and <I>command</I> as if it
|
|
were a command in the global namespace. Otherwise, if either
|
|
<I>command</I> is absolute (it begins with <B>::</B>), or
|
|
<I>namespace</I> is <B>::</B>, the list contains only <I>command</I> as
|
|
if it were a command in the global namespace.
|
|
<P>
|
|
<B>Auto_qualify</B> is used by the auto-loading facilities in Tcl, both
|
|
for producing auto-loading indexes such as <I>pkgIndex.tcl</I>, and for
|
|
performing the actual auto-loading of functions at runtime.
|
|
<P><DT><A NAME="M12"><B>tcl_findLibrary </B><I>basename version patch initScript enVarName varName</I></A><DD>
|
|
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 <I>basenameversion</I>
|
|
(e.g., tk8.0), but it might be "library" when in the build hierarchies.
|
|
The <I>initScript</I> 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 <I>varName</I>.
|
|
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 <I>enVarName</I>;
|
|
relative to the Tcl library directory;
|
|
relative to the executable file in the standard installation
|
|
bin or bin/<I>arch</I> directory;
|
|
relative to the executable file in the current build tree;
|
|
relative to the executable file in a parallel build tree.
|
|
<P><DT><A NAME="M13"><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="M14"><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="M15"><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="M16"><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="M17"><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="M18"><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="M19">VARIABLES</A></H3>
|
|
The following global variables are defined or used by the procedures in
|
|
the Tcl library:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M20"><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="M21"><B>auto_index</B></A><DD>
|
|
Used by <B>auto_load</B> to save the index information read from
|
|
disk.
|
|
<P><DT><A NAME="M22"><B>auto_noexec</B></A><DD>
|
|
If set to any value, then <B><A HREF="../TkCmd/unknown.htm">unknown</A></B> will not attempt to auto-exec
|
|
any commands.
|
|
<P><DT><A NAME="M23"><B>auto_noload</B></A><DD>
|
|
If set to any value, then <B><A HREF="../TkCmd/unknown.htm">unknown</A></B> will not attempt to auto-load
|
|
any commands.
|
|
<P><DT><A NAME="M24"><B>auto_path</B></A><DD>
|
|
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.
|
|
<P><DT><A NAME="M25"><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
|
|
assigned to the <B>tcl_library</B> variable and therefore returned by
|
|
the command <B><A HREF="../TkCmd/info.htm">info library</A></B>). If this variable isn't set then
|
|
a default value is used.
|
|
<P><DT><A NAME="M26"><B>env(TCLLIBPATH)</B></A><DD>
|
|
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 <B>auto_path</B> variable.
|
|
<P><DT><A NAME="M27"><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="M28"><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="M29"><B>unknown_pending</B></A><DD>
|
|
Used by <B><A HREF="../TkCmd/unknown.htm">unknown</A></B> to record the command(s) for which it is
|
|
searching.
|
|
It is used to detect errors where <B><A HREF="../TkCmd/unknown.htm">unknown</A></B> recurses on itself
|
|
infinitely.
|
|
The variable is unset before <B><A HREF="../TkCmd/unknown.htm">unknown</A></B> returns.
|
|
|
|
<P></DL>
|
|
<H3><A NAME="M30">SEE ALSO</A></H3>
|
|
<B><A HREF="../TkCmd/info.htm">info</A></B>, <B><A HREF="../TkCmd/re_syntax.htm">re_syntax</A></B>
|
|
<H3><A NAME="M31">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>
|