Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

tm(n)                                       Tcl Built-In Commands                                      tm(n)



____________________________________________________________________________________________________________

NAME
       tm - Facilities for locating and loading of Tcl Modules

SYNOPSIS
       ::tcl::tm::path add ?path...?
       ::tcl::tm::path remove ?path...?
       ::tcl::tm::path list
       ::tcl::tm::roots ?path...?
____________________________________________________________________________________________________________

DESCRIPTION
       This  document  describes  the facilities for locating and loading Tcl Modules (see MODULE DEFINITION
       for the definition of a Tcl Module).  The following commands are supported:

       ::tcl::tm::path add ?path...?
              The paths are added at the head to the list of module paths,  in  order  of  appearance.  This
              means that the last argument ends up as the new head of the list.

              The  command  enforces  the restriction that no path may be an ancestor directory of any other
              path on the list. If any of the new paths violates this restriction an error will  be  raised,
              before  any  of  the paths have been added. In other words, if only one path argument violates
              the restriction then none will be added.

              If a path is already present as is, no error will be raised and no action will be taken.

              Paths are searched later in the order of their appearance in the list. As they  are  added  to
              the  front  of  the  list  they are searched in reverse order of addition. In other words, the
              paths added last are looked at first.

       ::tcl::tm::path remove ?path...?
              Removes the paths from the list of module paths. The command silently ignores all paths  which
              are not on the list.

       ::tcl::tm::path list
              Returns a list containing all registered module paths, in the order that they are searched for
              modules.

       ::tcl::tm::roots ?path...?
              Similar to path add, and layered on top of it. This command takes a  list  of  paths,  extends
              each  with  "tclX/site-tcl",  and  "tclX/X.y",  for major version X of the Tcl interpreter and
              minor version y less than or equal to the minor version  of  the  interpreter,  and  adds  the
              resulting set of paths to the list of paths to search.

              This command is used internally by the system to set up the system-specific default paths.

              The  command  has  been exposed to allow a build system to define additional root paths beyond
              those described by this document.

MODULE DEFINITION
       A Tcl Module is a Tcl Package contained in a single file, and no other files  required  by  it.  This
       file has to be sourceable. In other words, a Tcl Module is always imported via:
              source module_file

       The  load  command  is  not  directly used. This restriction is not an actual limitation, as some may
       believe.  Ever since 8.4 the Tcl source command reads only until the first ^Z character. This  allows
       us to combine an arbitrary Tcl script with arbitrary binary data into one file, where the script pro-cesses processes
       cesses the attached data in any it chooses to fully import and activate the package.

       The name of a module file has to match the regular expression:
              ([_[:alpha:]][:_[:alnum:]]*)-([[:digit:]].*)\.tm

       The first capturing parentheses provides the name of the package, the second clause its  version.  In
       addition  to  matching the pattern, the extracted version number must not raise an error when used in
       the command:
              package vcompare $version 0


FINDING MODULES
       The directory tree for storing Tcl modules is separate from other parts of the filesystem  and  inde-pendent independent
       pendent of auto_path.

       Tcl  Modules  are searched for in all directories listed in the result of the command ::tcl::tm::path
       list.  This is called the Module path. Neither the auto_path nor the tcl_pkgPath variables are  used.
       All directories on the module path have to obey one restriction:

              For any two directories, neither is an ancestor directory of the other.

       This  is  required  to avoid ambiguities in package naming. If for example the two directories "foo/"
       and "foo/cool" were on the path a package named cool::ice could be found via the names  cool::ice  or
       ice, the latter potentially obscuring a package named ice, unqualified.

       Before  the  search  is started, the name of the requested package is translated into a partial path,
       using the following algorithm:

              All occurrences of "::" in the package name are replaced by the appropriate directory  separa-tor separator
              tor character for the platform we are on. On Unix, for example, this is "/".

       Example:

              The requested package is encoding::base64. The generated partial path is "encoding/base64".

       After  this  translation the package is looked for in all module paths, by combining them one-by-one,
       first to last with the partial path to form a complete search pattern. Note that the search algorithm
       rejects  all files where the filename does not match the regular expression given in the section MOD-ULE MODULE
       ULE DEFINITION. For the remaining files provide scripts  are  generated  and  added  to  the  package
       ifneeded database.

       The  algorithm falls back to the previous unknown handler when none of the found module files satisfy
       the request. If the request was satisfied the fall-back is ignored.

       Note that packages in module form have no control over the index and provide scripts entered into the
       package database for them.  For a module file MF the index script is always:
              package ifneeded PNAME PVERSION [list source MF]
       and the provide script embedded in the above is:
              source MF

       Both  package name PNAME and package version PVERSION are extracted from the filename MF according to
       the definition below:
              MF = /module_path/PNAME'-PVERSION.tm

       Where PNAME' is the partial path of the module as defined in section FINDING MODULES, and  translated
       into  PNAME  by changing all directory separators to "::", and module_path is the path (from the list
       of paths to search) that we found the module file under.

       Note also that we are here creating a connection between package names and paths. Tcl is  case-sensi-tive case-sensitive
       tive  when  it  comes to comparing package names, but there are filesystems which are not, like NTFS.
       Luckily these filesystems do store the case of the name, despite not using the information when  com-paring. comparing.
       paring.

       Given  the  above we allow the names for packages in Tcl modules to have mixed-case, but also require
       that there are no collisions when comparing names in a case-insensitive manner. In other words, if  a
       package  Foo  is  deployed  in the form of a Tcl Module, packages like foo, fOo, etc. are not allowed
       anymore.

DEFAULT PATHS
       The default list of paths on the module path is computed by a tclsh as follows, where X is the  major
       version  of  the  Tcl  interpreter and y is less than or equal to the minor version of the Tcl inter-preter. interpreter.
       preter.

       All the default paths are added to the module path, even those paths which do not exist. Non-existent
       paths  are  filtered  out  during  actual  searches.  This  enables a user to create one of the paths
       searched when needed and all running applications will automatically pick up any  modules  placed  in
       them.

       The paths are added in the order as they are listed below, and for lists of paths defined by an envi-ronment environment
       ronment variable in the order they are found in the variable.

   SYSTEM SPECIFIC PATHS
       file normalize [info library]/../tclX/X.y
              In other words, the interpreter will look into a directory specified by its major version  and
              whose minor versions are less than or equal to the minor version of the interpreter.

              For example for Tcl 8.4 the paths searched are:
                     [info library]/../tcl8/8.4
                     [info library]/../tcl8/8.3
                     [info library]/../tcl8/8.2
                     [info library]/../tcl8/8.1
                     [info library]/../tcl8/8.0

              This  definition  assumes  that  a  package defined for Tcl X.y can also be used by all inter-preters interpreters
              preters which have the same major number X and a minor number greater than y.

       file normalize EXEC/tclX/X.y
              Where EXEC is file normalize [info nameofexecutable]/../lib or file normalize  [::tcl::pkgcon-fig [::tcl::pkgconfig
              fig get libdir,runtime]

              This  sets  of  paths  is  handled  equivalently  to  the set coming before, except that it is
              anchored in EXEC_PREFIX.  For a build with PREFIX = EXEC_PREFIX the two sets are identical.

   SITE SPECIFIC PATHS
       file normalize [info library]/../tclX/site-tcl
              Note that this is always a single entry because X is always  a  specific  value  (the  current
              major version of Tcl).

   USER SPECIFIC PATHS
       $::env(TCLX_y_TM_PATH)
              A  list  of paths, separated by either : (Unix) or ; (Windows). This is user and site specific
              as this environment variable can be set not only by the user's profile, but by system configu-ration configuration
              ration scripts as well.

       $::env(TCLX.y_TM_PATH)
              Same  meaning  and  content  as  the previous variable. However the use of dot '.' to separate
              major and minor version number makes this name less to non-portable and its  use  is  discour-aged. discouraged.
              aged. Support of this variable has been kept only for backward compatibility with the original
              specification, i.e. TIP 189.

       These paths are seen and therefore shared by all Tcl shells in the $::env(PATH) of the user.

       Note that X and y follow the general rules set out above. In other words, Tcl 8.4, for example,  will
       look at these 5 environment variables:
              $::env(TCL8.4_TM_PATH)  $::env(TCL8_4_TM_PATH)
              $::env(TCL8.3_TM_PATH)  $::env(TCL8_3_TM_PATH)
              $::env(TCL8.2_TM_PATH)  $::env(TCL8_2_TM_PATH)
              $::env(TCL8.1_TM_PATH)  $::env(TCL8_1_TM_PATH)
              $::env(TCL8.0_TM_PATH)  $::env(TCL8_0_TM_PATH)

SEE ALSO
       package(n),  Tcl  Improvement Proposal #189 "Tcl Modules" (online at http://tip.tcl.tk/189.html), Tcl
       Improvement   Proposal   #190   "Implementation    Choices    for    Tcl    Modules"    (online    at
       http://tip.tcl.tk/190.html)

KEYWORDS
       modules, package



Tcl                                                  8.5                                               tm(n)