1mNAME0m
       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

1mSYNOPSIS0m
       1mauto_execok 4m22mcmd0m
       1mauto_import 4m22mpattern0m
       1mauto_load 4m22mcmd0m
       1mauto_mkindex 4m22mdir24m 4mpattern24m 4mpattern24m 4m...0m
       1mauto_mkindex_old 4m22mdir24m 4mpattern24m 4mpattern24m 4m...0m
       1mauto_qualify 4m22mcommand24m 4mnamespace0m
       1mauto_reset0m
       1mtcl_findLibrary 4m22mbasename24m 4mversion24m 4mpatch24m 4minitScript24m 4menVarName24m 4mvarName0m
       1mparray 4m22marrayName0m
       1mtcl_endOfWord 4m22mstr24m 4mstart0m
       1mtcl_startOfNextWord 4m22mstr24m 4mstart0m
       1mtcl_startOfPreviousWord 4m22mstr24m 4mstart0m
       1mtcl_wordBreakAfter 4m22mstr24m 4mstart0m
       1mtcl_wordBreakBefore 4m22mstr24m 4mstart0m


1mINTRODUCTION0m
       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 1minfo library 22mcommand.  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 1m$4m22mapp24m1m_library 22mglobal variable, where 4mapp24m is the name of the
       application.   For  example,  the location of the Tk library is kept in
       the variable 1m$tk_library22m.

       To access the procedures in the  Tcl  library,  an  application  should
       source  the file 1minit.tcl 22min the library, for example with the Tcl com-
       mand
              1msource [file join [info library] init.tcl]0m
       If the library procedure 1mTcl_Init  22mis  invoked  from  an  application's
       1mTcl_AppInit   22mprocedure,  this  happens  automatically.   The  code  in
       1minit.tcl 22mwill define the 1munknown 22mprocedure and arrange  for  the  other
       procedures to be loaded on-demand using the auto-load mechanism defined
       below.


1mCOMMAND PROCEDURES0m
       The following procedures are provided in the Tcl library:

       1mauto_execok 4m22mcmd0m
              Determines whether there is an executable file or shell  builtin
              by  the  name  4mcmd24m.  If so, it returns a list of arguments to be
              passed to 1mexec 22mto execute the executable file or  shell  builtin
              named by 4mcmd24m.  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 4mcmd24m.  On Windows platforms, the  search  is  expanded
              with  the  same directories and file extensions as used by 1mexec22m.
              1mAuto_exec 22mremembers information about previous  searches  in  an
              array  named  1mauto_execs22m;  this avoids the path search in future
              calls for the same 4mcmd24m.  The command 1mauto_reset 22mmay be  used  to
              force 1mauto_execok 22mto forget its cached information.

       1mauto_import 4m22mpattern0m
              1mAuto_import  22mis  invoked  during  1mnamespace import 22mto see if the
              imported commands specified by 4mpattern24m 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, 1mauto_import0m
              does nothing.

       1mauto_load 4m22mcmd0m
              This command attempts to load the definition for a  Tcl  command
              named  4mcmd24m.  To do this, it searches an 4mauto-load24m 4mpath24m, which is
              a list of one or more directories.  The auto-load path is  given
              by  the global variable 1m$auto_path 22mif it exists.  If there is no
              1m$auto_path 22mvariable, 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 1mtclIndex 22mthat describes one
              or more commands defined in that directory and a script to eval-
              uate  to load each of the commands.  The 1mtclIndex 22mfile should be
              generated with the 1mauto_mkindex 22mcommand.  If 4mcmd24m is found in  an
              index  file,  then the appropriate script is evaluated to create
              the command.  The 1mauto_load 22mcommand returns 1 if  4mcmd24m  was  suc-
              cessfully  created.  The command returns 0 if there was no index
              entry for 4mcmd24m or if the script didn't actually define 4mcmd24m  (e.g.
              because  index  information is out of date).  If an error occurs
              while processing  the  script,  then  that  error  is  returned.
              1mAuto_load  22monly reads the index information once and saves it in
              the array 1mauto_index22m;  future calls to 1mauto_load 22mcheck  for  4mcmd0m
              in the array rather than re-reading the index files.  The cached
              index information may be deleted with  the  command  1mauto_reset22m.
              This  will  force the next 1mauto_load 22mcommand to reload the index
              database from disk.

       1mauto_mkindex 4m22mdir24m 4mpattern24m 4mpattern24m 4m...0m
              Generates an index suitable for use by 1mauto_load22m.   The  command
              searches  4mdir24m for all files whose names match any of the 4mpattern0m
              arguments (matching is done with the 1mglob 22mcommand), generates an
              index  of  all  the  Tcl  command  procedures defined in all the
              matching files, and stores the index information in a file named
              1mtclIndex  22min 4mdir24m. If no pattern is given a pattern of 1m*.tcl 22mwill
              be assumed.  For example, the command
                     1mauto_mkindex foo *.tcl0m

              will read all the 1m.tcl 22mfiles in subdirectory 1mfoo 22mand generate  a
              new index file 1mfoo/tclIndex22m.

              1mAuto_mkindex  22mparses  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.

              1mAuto_mkindex_old 22mparses the Tcl scripts in  a  relatively  unso-
              phisticated  way:   if  any  line  contains the word 1mproc 22mas 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  1mproc22m)  will  not be indexed.  If your
              script contains "dangerous" code, such as global  initialization
              code  or procedure names with special characters like 1m$22m, 1m*22m, 1m[ 22mor
              1m]22m, you are safer using auto_mkindex_old.

       1mauto_reset0m
              Destroys  all  the  information  cached   by   1mauto_execok   22mand
              1mauto_load22m.   This information will be re-read from disk the next
              time it is  needed.   1mAuto_reset  22malso  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.

       1mauto_qualify 4m22mcommand24m 4mnamespace0m
              Computes a list of fully qualified names for 4mcommand24m.  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 4mcommand0m
              is relative and 4mnamespace24m is not 1m::22m, the list returned  has  two
              elements:   4mcommand24m scoped by 4mnamespace24m, as if it were a command
              in the 4mnamespace24m namespace; and 4mcommand24m as if it were a  command
              in  the global namespace.  Otherwise, if either 4mcommand24m is abso-
              lute (it begins with 1m::22m), or 4mnamespace24m is 1m::22m, the list  contains
              only 4mcommand24m as if it were a command in the global namespace.

              1mAuto_qualify 22mis used by the auto-loading facilities in Tcl, both
              for producing auto-loading indexes such as 4mpkgIndex.tcl24m, and for
              performing the actual auto-loading of functions at runtime.

       1mtcl_findLibrary 4m22mbasename24m 4mversion24m 4mpatch24m 4minitScript24m 4menVarName24m 4mvarName0m
              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 4mbase-0m
              4mnameversion24m (e.g., tk8.0), but it might be "library" when in the
              build hierarchies.  The 4minitScript24m 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  4mvarName24m.   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 4menVarName24m; relative to the Tcl library  directory;
              relative to the executable file in the standard installation bin
              or bin/4march24m directory; relative to the executable  file  in  the
              current  build tree; relative to the executable file in a paral-
              lel build tree.

       1mparray 4m22marrayName0m
              Prints on standard output the names and values of all  the  ele-
              ments in the array 4marrayName24m.  1mArrayName 22mmust be an array acces-
              sible to the caller of  1mparray22m.   It  may  be  either  local  or
              global.

       1mtcl_endOfWord 4m22mstr24m 4mstart0m
              Returns  the index of the first end-of-word location that occurs
              after a starting index 4mstart24m in the string 4mstr24m.  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  1mtcl_wordchars  22mand  1mtcl_nonword-0m
              1mchars 22mbelow for more details on how Tcl determines which charac-
              ters are word characters.

       1mtcl_startOfNextWord 4m22mstr24m 4mstart0m
              Returns the index  of  the  first  start-of-word  location  that
              occurs after a starting index 4mstart24m in the string 4mstr24m.  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.

       1mtcl_startOfPreviousWord 4m22mstr24m 4mstart0m
              Returns the index  of  the  first  start-of-word  location  that
              occurs before a starting index 4mstart24m in the string 4mstr24m.  Returns
              -1 if there are  no  more  start-of-word  locations  before  the
              starting point.

       1mtcl_wordBreakAfter 4m22mstr24m 4mstart0m
              Returns  the index of the first word boundary after the starting
              index 4mstart24m in the string 4mstr24m.  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.

       1mtcl_wordBreakBefore 4m22mstr24m 4mstart0m
              Returns the index of the first word boundary before the starting
              index 4mstart24m in the string 4mstr24m.  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.


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

       1mauto_execs0m
              Used by 1mauto_execok 22mto record information about whether particu-
              lar commands exist as executable files.

       1mauto_index0m
              Used  by 1mauto_load 22mto save the index information read from disk.

       1mauto_noexec0m
              If set to any value, then 1munknown 22mwill not attempt to  auto-exec
              any commands.

       1mauto_noload0m
              If  set to any value, then 1munknown 22mwill not attempt to auto-load
              any commands.

       1mauto_path0m
              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 $tcl_library  variable,  the  parent  directory  of
              $tcl_library,  the  directories listed in the $tcl_pkgPath vari-
              able.

       1menv(TCL_LIBRARY)0m
              If set, then it specifies the location of the directory contain-
              ing library scripts (the value of this variable will be assigned
              to the 1mtcl_library 22mvariable and therefore returned by  the  com-
              mand  1minfo  library22m).  If this variable isn't set then a default
              value is used.

       1menv(TCLLIBPATH)0m
              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 1mauto_path 22mvariable.

       1mtcl_nonwordchars0m
              This variable contains a regular expression that is used by rou-
              tines like 1mtcl_endOfWord 22mto 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.

       1mtcl_wordchars0m
              This variable contains a regular expression that is used by rou-
              tines like 1mtcl_endOfWord 22mto 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.

       1munknown_pending0m
              Used by 1munknown 22mto record the command(s) for which it is search-
              ing.   It  is  used  to  detect errors where 1munknown 22mrecurses on
              itself  infinitely.   The  variable  is  unset  before   1munknown0m
              returns.


1mSEE ALSO0m
       info(n), re_syntax(n)


1mKEYWORDS0m
