Ubuntu Manpage: tm - Facilities for locating and loading of Tcl Modules

name
synopsis
description
module definition
finding modules
default paths
see also
keywords

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 processes 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 independent
       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  separator
              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 MODULE
       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-sensitive
       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 comparing.

       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 interpreter.

       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
       environment 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 interpreters
              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::pkgconfig
              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  configuration
              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 discouraged.  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)

KEYWORDS

       modules, package