Ubuntu Manpage: auto_execok, auto_import, auto_load, auto_mkindex, auto_mkindex_old, auto

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

SYNOPSIS

       auto_execok cmd
       auto_import pattern
       auto_load cmd
       auto_mkindex dir pattern pattern ...
       auto_mkindex_old dir pattern pattern ...
       auto_qualify command namespace
       auto_reset
       tcl_findLibrary basename version patch initScript enVarName varName
       parray arrayName ?pattern?
       tcl_endOfWord str start
       tcl_startOfNextWord str start
       tcl_startOfPreviousWord str start
       tcl_wordBreakAfter str start
       tcl_wordBreakBefore str start
_________________________________________________________________________________________________

INTRODUCTION

       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  info  library  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  $app_library  global  variable,  where  app  is the name of the application.  For
       example, the location of the Tk library is kept in the variable $tk_library.

       To access the procedures in the  Tcl  library,  an  application  should  source  the  file
       init.tcl in the library, for example with the Tcl command
              source [file join [info library] init.tcl]
       If  the library procedure Tcl_Init is invoked from an application's Tcl_AppInit procedure,
       this happens automatically.  The code in init.tcl will define the  unknown  procedure  and
       arrange  for  the  other  procedures  to be loaded on-demand using the auto-load mechanism
       defined below.

COMMAND PROCEDURES

       The following procedures are provided in the Tcl library:

       auto_execok 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 exec 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 exec. Auto_execok remembers information about previous searches in an array
              named  auto_execs;   this  avoids the path search in future calls for the same cmd.
              The command auto_reset may be used  to  force  auto_execok  to  forget  its  cached
              information.

       auto_import pattern
              Auto_import  is  invoked  during  namespace  import 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,  auto_import  does
              nothing.   The  pattern  matching  is  performed according to the matching rules of
              namespace import.

       auto_load 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 $auto_path  if  it  exists.   If
              there  is no $auto_path 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
              tclIndex that describes one or more commands defined in that directory and a script
              to  evaluate  to  load each of the commands.  The tclIndex file should be generated
              with the auto_mkindex command.  If  cmd  is  found  in  an  index  file,  then  the
              appropriate  script  is  evaluated  to  create  the command.  The auto_load command
              returns 1 if cmd was successfully created.  The command returns 0 if there  was  no
              index  entry  for  cmd  or  if the script did not 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.  Auto_load only reads the index information once and
              saves it in the array auto_index;  future calls to auto_load check for cmd  in  the
              array  rather than re-reading the index files.  The cached index information may be
              deleted with the command auto_reset.  This will force the next auto_load command to
              reload the index database from disk.

       auto_mkindex dir pattern pattern ...
              Generates an index suitable for use by auto_load.  The command searches dir for all
              files whose names match any of the pattern arguments (matching  is  done  with  the
              glob  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  tclIndex  in
              dir.  If  no pattern is given a pattern of *.tcl will be assumed.  For example, the
              command
                     auto_mkindex foo *.tcl

              will read all the .tcl files in subdirectory foo and  generate  a  new  index  file
              foo/tclIndex.

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

              Auto_mkindex_old  parses  the  Tcl scripts in a relatively unsophisticated way:  if
              any line contains the word proc 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 do not appear in this way (e.g. they have  spaces
              before  the  proc)  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 auto_mkindex_old.

       auto_reset
              Destroys all the information cached by auto_execok and auto_load.  This information
              will be re-read from disk the next time it is needed.  Auto_reset also deletes  any
              procedures  listed  in  the  auto-load  index, so that fresh copies of them will be
              loaded the next time that they are used.

       auto_qualify 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 namespace, 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 absolute (it begins with ::), or namespace is ::, the list contains only
              command as if it were a command in the global namespace.

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

       tcl_findLibrary 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 basenameversion (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 environment 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 parallel build
              tree.

       parray arrayName ?pattern?
              Prints  on  standard  output  the names and values of all the elements in the array
              arrayName, or just the names that match pattern (using the matching rules of string
              match) and their values if pattern is given.  ArrayName must be an array accessible
              to the caller of parray.  It may be either local or global.

       tcl_endOfWord 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 tcl_wordchars and tcl_nonwordchars below for more details on
              how Tcl determines which characters are word characters.

       tcl_startOfNextWord 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  following  a  non-word character.  Returns -1 if there are no more
              start-of-word locations after the starting point.

       tcl_startOfPreviousWord 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 starting point.

       tcl_wordBreakAfter str start
              Returns the index of the first word boundary after the starting 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.

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

VARIABLES

The following global variables are defined or used by the procedures in the Tcl library:

auto_execs
Used by auto_execok to record information about whether particular commands exist
as executable files.

auto_index
Used by auto_load to save the index information read from disk.

auto_noexec
If set to any value, then unknown will not attempt to auto-exec any commands.

auto_noload
If set to any value, then unknown will not attempt to auto-load any commands.

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

env(TCL_LIBRARY)
If set, then it specifies the location of the directory containing library scripts
(the value of this variable will be assigned to the tcl_library variable and
therefore returned by the command info library). If this variable is not set then
a default value is used.

env(TCLLIBPATH)
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 auto_path variable.

tcl_nonwordchars
This variable contains a regular expression that is used by routines like
tcl_endOfWord 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.

tcl_wordchars
This variable contains a regular expression that is used by routines like
tcl_endOfWord 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.

KEYWORDS