tm(n)

📦
version 9.0.3 · 5 versions
, in alpine 3.23, alpine 3.24, fedora 43, fedora 44, nixos 26.05

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

okay bestie, gather round, because today we're talking about tm — the whole vibe of locating and loading Tcl Modules. she's giving ✨module-path energy✨ and honestly? iconic. this is the n section of the manual, so yes she's a Tcl command page, no cap. 🎀

✨ NAME ✨

tm — facilities for locating and loading of Tcl Modules. that's the whole job. she finds them, she loads them, she slays. 💅

🦋 SYNOPSIS 🦋

::tcl::tm::path add ?path...?
::tcl::tm::path remove ?path...?
::tcl::tm::path list
::tcl::tm::roots paths

four little commands. four little besties. let's get into it. 🌸

🌈 DESCRIPTION 🌈

so this document describes all the facilities for locating and loading Tcl Modules — and if you're wondering what even is a Tcl Module, girl, scroll down to MODULE DEFINITION, it's all there. here are the supported commands:

  • ::tcl::tm::path add ?path...? — adds the paths to the head of the list of module paths, in order of appearance. meaning: the last argument ends up as the new head of the list. yes that's a little chaotic, we love that for her. 🫶
    • the command is strict about one thing: 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 gets 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. it's all-or-nothing, babe.
    • if a path is already present as is, no error will be raised and no action will be taken. she's chill like that. 💅
    • paths are searched later in the order of their appearance in the list. since they get added to the front of the list, they're searched in reverse order of addition. in other words: the paths added last are looked at first. main character gets first dibs.
  • ::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. no drama, no error, just vibes. 🙈
  • ::tcl::tm::path list — returns a list containing all registered module paths, in the order that they are searched for modules. this is the receipt, bestie. 📋
  • ::tcl::tm::roots paths — similar to path add, and layered on top of it. this command takes a single argument containing 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. so if you're a build system, hi, this one's for you.

🎀 MODULE DEFINITION 🎀

a Tcl Module is a Tcl Package contained in a single file, and no other files required by it. one file. that's it. she travels light. ✈️

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. and ngl, 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. which means we can combine an arbitrary Tcl script with arbitrary binary data into one file, where the script processes the attached data in any way it chooses to fully import and activate the package. it's giving multimedia file, but make it Tcl. 💀

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

and in addition to matching the pattern, the extracted version number must not raise an error when used in the command:

package vcompare $version 0

like, match the pattern and survive the vibe check. both. ✋

🔥 FINDING MODULES 🔥

the directory tree for storing Tcl modules is separate from other parts of the filesystem and independent of auto_path. she does not run with that crowd.

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. not even a little. 🚫

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. like, 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. and we do not do ambiguity in this house. 😭

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 time, bestie:

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. periodt. 💅

🌸 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. she's manifesting, honestly. ✨

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. she's legacy, we respect her, we don't invite her to the group chat. 💀

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 9.1, for example, will look at these 4 environment variables:

$::env(TCL9.1_TM_PATH)  $::env(TCL9_1_TM_PATH)
$::env(TCL9.0_TM_PATH)  $::env(TCL9_0_TM_PATH)

paths initialized from the environment variables undergo tilde substitution (see filename). any path whose tilde substitution fails because the user is unknown will be omitted from search paths. no user, no path, no problem. 🙈

⭐ SEE ALSO ⭐

👑 KEYWORDS 👑

  • modules
  • package

and that's the whole page, bestie!! 🎀 this one comes to you from Tcl version 8.5 — so if you're reading a newer interpreter, just know this queen was written for 8.5 and she still ate. 💖 go forth and ::tcl::tm::path list something. mwah. ✨🌸🦋

📦 where this page comes from