Manual Pages for UNIX Darwin command on man tcl

Manual Pages for UNIX Darwin command on man tcl_findLibrary

library(n) Tcl Built-In Commands library(n)

NAME

autoexecok, autoimport, autoload, automkindex, automkindexold, autoqualify, autoreset, tclfindLibrary, parray, tclendOfWord, tclstartOfNextWord, tclstartOfPreviousWord, tclwordBreakAfter,

tclwordBreakBefore - standard library of Tcl procedures

SYNOPSIS

aauuttooeexxeeccookk cmd aauuttooiimmppoorrtt pattern aauuttoollooaadd cmd aauuttoommkkiinnddeexx dir pattern pattern ... aauuttoommkkiinnddeexxoolldd dir pattern pattern ... aauuttooqquuaalliiffyy command namespace aauuttoorreesseett ttccllffiinnddLLiibbrraarryy basename version patch initScript enVarName varName ppaarrrraayy arrayName ttcclleennddOOffWWoorrdd str start | ttccllssttaarrttOOffNNeexxttWWoorrdd str start | ttccllssttaarrttOOffPPrreevviioouussWWoorrdd str start | ttccllwwoorrddBBrreeaakkAAfftteerr str start | ttccllwwoorrddBBrreeaakkBBeeffoorree str start | IINNTTRROODDUUCCTTIIOONN

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 iinnffoo lliibbrraarryy command. In addition to the Tcl library,

each application will normally have its own library of support proce-

dures as well; the location of this library is normally given by the

value of the $$applliibbrraarryy global variable, where app is the name of the

application. For example, the location of the Tk library is kept in

the variable $$ttkklliibbrraarryy.

To access the procedures in the Tcl library, an application should

source the file iinniitt..ttccll in the library, for example with the Tcl com-

mand ssoouurrccee [[ffiillee jjooiinn [[iinnffoo lliibbrraarryy]] iinniitt..ttccll]] If the library procedure TTccllIInniitt is invoked from an application's TTccllAAppppIInniitt procedure, this happens automatically. The code in iinniitt..ttccll will define the uunnkknnoowwnn procedure and arrange for the other

procedures to be loaded on-demand using the auto-load mechanism defined

below. CCOOMMMMAANNDD PPRROOCCEEDDUURREESS The following procedures are provided in the Tcl library: aauuttooeexxeeccookk cmd Determines whether there is an executable file or shell builtin by the name cmd. If so, it returns a list of arguments to be passed to eexxeecc to execute the executable file or shell builtin named by cmd. 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 cmd. On Windows platforms, the search is expanded with the same directories and file extensions as used by eexxeecc. AAuuttooeexxeecc remembers information about previous searches in an array named aauuttooeexxeeccss; this avoids the path search in future calls for the same cmd. The command aauuttoorreesseett may be used to force aauuttooeexxeeccookk to forget its cached information. aauuttooiimmppoorrtt pattern AAuuttooiimmppoorrtt is invoked during nnaammeessppaaccee iimmppoorrtt to see if the imported commands specified by pattern 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, aauuttooiimmppoorrtt does nothing. The pattern matching is performed according to the matching rules of nnaammeessppaaccee iimmppoorrtt. aauuttoollooaadd cmd This command attempts to load the definition for a Tcl command

named cmd. To do this, it searches an auto-load path, which is

a list of one or more directories. The auto-load path is given

by the global variable $$aauuttooppaatthh if it exists. If there is no

$$aauuttooppaatthh 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 ttccllIInnddeexx that describes one

or more commands defined in that directory and a script to eval-

uate to load each of the commands. The ttccllIInnddeexx file should be generated with the aauuttoommkkiinnddeexx command. If cmd is found in an index file, then the appropriate script is evaluated to create

the command. The aauuttoollooaadd command returns 1 if cmd was suc-

cessfully created. The command returns 0 if there was no index entry for cmd or if the script didn't actually define cmd (e.g. because index information is out of date). If an error occurs while processing the script, then that error is returned. AAuuttoollooaadd only reads the index information once and saves it in the array aauuttooiinnddeexx; future calls to aauuttoollooaadd check for cmd

in the array rather than re-reading the index files. The cached

index information may be deleted with the command aauuttoorreesseett. This will force the next aauuttoollooaadd command to reload the index database from disk. aauuttoommkkiinnddeexx dir pattern pattern ... Generates an index suitable for use by aauuttoollooaadd. The command searches dir for all files whose names match any of the pattern arguments (matching is done with the gglloobb 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 ttccllIInnddeexx in dir. If no pattern is given a pattern of **..ttccll will be assumed. For example, the command aauuttoommkkiinnddeexx ffoooo **..ttccll will read all the ..ttccll files in subdirectory ffoooo and generate a new index file ffoooo//ttccllIInnddeexx. AAuuttoommkkiinnddeexx 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) automkindexparser package to register other commands that can contribute to the autoload index. You will have to read through auto.tcl to see how this works.

AAuuttoommkkiinnddeexxoolldd parses the Tcl scripts in a relatively unso-

phisticated way: if any line contains the word pprroocc 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 pprroocc) will not be indexed. If your script contains "dangerous" code, such as global initialization

code or procedure names with special characters like $$, **, [[ or

]], you are safer using automkindexold. aauuttoorreesseett Destroys all the information cached by aauuttooeexxeeccookk and

aauuttoollooaadd. This information will be re-read from disk the next

time it is needed. AAuuttoorreesseett 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. aauuttooqquuaalliiffyy command namespace Computes a list of fully qualified names for command. This list mirrors the path a standard Tcl interpreter follows for command

lookups: first it looks for the command in the current names-

pace, and then in the global namespace. Accordingly, if command is relative and namespace is not ::::, the list returned has two elements: command scoped by namespace, as if it were a command in the namespace namespace; and command as if it were a command

in the global namespace. Otherwise, if either command is abso-

lute (it begins with ::::), or namespace is ::::, the list contains only command as if it were a command in the global namespace.

AAuuttooqquuaalliiffyy is used by the auto-loading facilities in Tcl, both

for producing auto-loading indexes such as pkgIndex.tcl, and for

performing the actual auto-loading of functions at runtime.

ttccllffiinnddLLiibbrraarryy basename version patch initScript enVarName varName 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 base-

nameversion (e.g., tk8.0), but it might be "library" when in the build hierarchies. The initScript 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 varName. 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 environ-

ment variable enVarName; relative to the Tcl library directory; relative to the executable file in the standard installation bin or bin/arch directory; relative to the executable file in the

current build tree; relative to the executable file in a paral-

lel build tree. ppaarrrraayy arrayName

Prints on standard output the names and values of all the ele-

ments in the array arrayName. AArrrraayyNNaammee must be an array acces-

sible to the caller of ppaarrrraayy. It may be either local or global. ttcclleennddOOffWWoorrdd str start

Returns the index of the first end-of-word location that occurs |

after a starting index start in the string str. 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 ttccllwwoorrddcchhaarrss and ttccllnnoonnwwoorrdd- |

cchhaarrss below for more details on how Tcl determines which charac- |

ters are word characters. | ttccllssttaarrttOOffNNeexxttWWoorrdd str | start | |

Returns the index of the first start-of-word location that |

occurs after a starting index start in the string str. A start- |

of-word location is defined to be the first word character fol- |

lowing a non-word character. Returns -1 if there are no more |

start-of-word locations after the starting point. |

ttccllssttaarrttOOffPPrreevviioouussWWoorrdd str | start | |

Returns the index of the first start-of-word location that |

occurs before a starting index start in the string str. Returns |

-1 if there are no more start-of-word locations before the |

index start in the string str. 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. | ttccllwwoorrddBBrreeaakkBBeeffoorree str | start | | Returns the index of the first word boundary before the starting |

index start in the string str. 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. VVAARRIIAABBLLEESS The following global variables are defined or used by the procedures in the Tcl library: aauuttooeexxeeccss

Used by aauuttooeexxeeccookk to record information about whether particu-

lar commands exist as executable files. aauuttooiinnddeexx Used by aauuttoollooaadd to save the index information read from disk. aauuttoonnooeexxeecc

If set to any value, then uunnkknnoowwnn will not attempt to auto-exec

any commands. aauuttoonnoollooaadd

If set to any value, then uunnkknnoowwnn will not attempt to auto-load

any commands. aauuttooppaatthh If set, then it must contain a valid Tcl list giving directories

to search during auto-load operations. This variable is ini-

tialized during startup to contain, in order: the directories listed in the TCLLIBPATH environment variable, the directory

named by the $tcllibrary variable, the parent directory of

$tcllibrary, the directories listed in the $tclpkgPath vari-

able. eennvv((TTCCLLLLIIBBRRAARRYY))

If set, then it specifies the location of the directory contain-

ing library scripts (the value of this variable will be assigned

to the ttcclllliibbrraarryy variable and therefore returned by the com-

mand iinnffoo lliibbrraarryy). If this variable isn't set then a default value is used. eennvv((TTCCLLLLIIBBPPAATTHH)) 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 ini-

tializing the aauuttooppaatthh variable. ttccllnnoonnwwoorrddcchhaarrss

This variable contains a regular expression that is used by rou- |

tines like ttcclleennddOOffWWoorrdd to identify whether a character is part |

of a word or not. If the pattern matches a character, the char- |

acter 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. |

ttccllwwoorrdd- |

cchhaarrss | |

This variable contains a regular expression that is used by rou- |

tines like ttcclleennddOOffWWoorrdd to identify whether a character is part |

of a word or not. If the pattern matches a character, the char- |

acter is considered to be a word character. On Windows plat- |

forms, words are comprised of any character that is not a space, | tab, or newline. Under Unix, words are comprised of numbers, | letters or underscores. uunnkknnoowwnnppeennddiinngg

Used by uunnkknnoowwnn to record the command(s) for which it is search-

ing. It is used to detect errors where uunnkknnoowwnn recurses on itself infinitely. The variable is unset before uunnkknnoowwnn returns.