Provided by: tcl8.4-doc_8.4.20-7_all bug

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
       tcl_endOfWord str starttcl_startOfNextWord str starttcl_startOfPreviousWord str starttcl_wordBreakAfter str starttcl_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_exec 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 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.  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 don't 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're 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
              Prints  on  standard  output  the names and values of all the elements in the array
              arrayName.  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 isn't 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.

       unknown_pending
              Used by unknown to record the command(s) for which it is searching.  It is used  to
              detect  errors  where unknown recurses on itself infinitely.  The variable is unset
              before unknown returns.

SEE ALSO

       info(3tcl), re_syntax(3tcl)

KEYWORDS

       auto-exec, auto-load, library, unknown, word, whitespace