Ubuntu Manpage: auto_execok, auto_import, auto_load, auto_mkindex, auto_mkindex_old, auto_qualify, 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