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.  The pattern matching is  performed  according  to
              the matching rules of 1mnamespace import22m.

       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
