diff options
Diffstat (limited to 'tcl8.6/doc/tm.n')
-rw-r--r-- | tcl8.6/doc/tm.n | 308 |
1 files changed, 0 insertions, 308 deletions
diff --git a/tcl8.6/doc/tm.n b/tcl8.6/doc/tm.n deleted file mode 100644 index 5602686..0000000 --- a/tcl8.6/doc/tm.n +++ /dev/null @@ -1,308 +0,0 @@ -'\" -'\" Copyright (c) 2004-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net> -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tm n 8.5 Tcl "Tcl Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tm \- Facilities for locating and loading of Tcl Modules -.SH SYNOPSIS -.nf -\fB::tcl::tm::path add \fR?\fIpath\fR...? -\fB::tcl::tm::path remove \fR?\fIpath\fR...? -\fB::tcl::tm::path list\fR -\fB::tcl::tm::roots \fR?\fIpath\fR...? -.fi -.BE -.SH DESCRIPTION -.PP -This document describes the facilities for locating and loading Tcl -Modules (see \fBMODULE DEFINITION\fR for the definition of a Tcl Module). -The following commands are supported: -.TP -\fB::tcl::tm::path add \fR?\fIpath\fR...? -. -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. -.RS -.PP -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. -.PP -If a path is already present as is, no error will be raised and no -action will be taken. -.PP -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. -.RE -.TP -\fB::tcl::tm::path remove \fR?\fIpath\fR...? -. -Removes the paths from the list of module paths. The command silently -ignores all paths which are not on the list. -.TP -\fB::tcl::tm::path list\fR -. -Returns a list containing all registered module paths, in the order -that they are searched for modules. -.TP -\fB::tcl::tm::roots \fR?\fIpath\fR...? -. -Similar to \fBpath add\fR, and layered on top of it. This command -takes a list of paths, extends each with -.QW "\fBtcl\fIX\fB/site-tcl\fR" , -and -.QW "\fBtcl\fIX\fB/\fIX\fB.\fIy\fR" , -for major version \fIX\fR of the -Tcl interpreter and minor version \fIy\fR 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. -.RS -.PP -This command is used internally by the system to set up the -system-specific default paths. -.PP -The command has been exposed to allow a build system to define -additional root paths beyond those described by this document. -.RE -.SH "MODULE DEFINITION" -.PP -A Tcl Module is a Tcl Package contained in a single file, and no other -files required by it. This file has to be \fBsource\fRable. In other -words, a Tcl Module is always imported via: -.PP -.CS -source module_file -.CE -.PP -The \fBload\fR command is not directly used. This restriction is not -an actual limitation, as some may believe. -Ever since 8.4 the Tcl \fBsource\fR 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. -.PP -The name of a module file has to match the regular expression: -.PP -.CS -([_[:alpha:]][:_[:alnum:]]*)-([[:digit:]].*)\e.tm -.CE -.PP -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: -.PP -.CS -package vcompare $version 0 -.CE -.SH "FINDING MODULES" -.PP -The directory tree for storing Tcl modules is separate from other -parts of the filesystem and independent of \fBauto_path\fR. -.PP -Tcl Modules are searched for in all directories listed in the result -of the command \fB::tcl::tm::path list\fR. -This is called the \fIModule path\fR. Neither the \fBauto_path\fR nor -the \fBtcl_pkgPath\fR variables are used. -All directories on the module path have to obey one restriction: -.RS -.PP -For any two directories, neither is an ancestor directory of the -other. -.RE -.PP -This is required to avoid ambiguities in package naming. If for -example the two directories -.QW "\fIfoo/\fR" -and -.QW "\fIfoo/cool\fR" -were on -the path a package named \fBcool::ice\fR could be found via the -names \fBcool::ice\fR or \fBice\fR, the latter potentially -obscuring a package named \fBice\fR, unqualified. -.PP -Before the search is started, the name of the requested package is -translated into a partial path, using the following algorithm: -.RS -.PP -All occurrences of -.QW "\fB::\fR" -in the package name are replaced by -the appropriate directory separator character for the platform we are -on. On Unix, for example, this is -.QW "\fB/\fR" . -.RE -.PP -Example: -.RS -.PP -The requested package is \fBencoding::base64\fR. The generated -partial path is -.QW "\fIencoding/base64\fR" . -.RE -.PP -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 \fBMODULE DEFINITION\fR. For the remaining -files \fIprovide scripts\fR are generated and added to the package -ifneeded database. -.PP -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. -.PP -Note that packages in module form have \fIno\fR control over the -\fIindex\fR and \fIprovide script\fRs entered into the package -database for them. -For a module file \fBMF\fR the \fIindex script\fR is always: -.PP -.CS -package ifneeded \fBPNAME PVERSION\fR [list source \fBMF\fR] -.CE -.PP -and the \fIprovide script\fR embedded in the above is: -.PP -.CS -source \fBMF\fR -.CE -.PP -Both package name \fBPNAME\fR and package version \fBPVERSION\fR are -extracted from the filename \fBMF\fR according to the definition -below: -.PP -.CS -\fBMF\fR = /module_path/\fBPNAME\(fm\fR-\fBPVERSION\fR.tm -.CE -.PP -Where \fBPNAME\(fm\fR is the partial path of the module as defined in -section \fBFINDING MODULES\fR, and translated into \fBPNAME\fR by -changing all directory separators to -.QW "\fB::\fR" , -and \fBmodule_path\fR is the path (from the list of paths to search) -that we found the module file under. -.PP -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. -.PP -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 \fBFoo\fR is deployed in the form of a Tcl Module, -packages like \fBfoo\fR, \fBfOo\fR, etc. are not allowed -anymore. -.SH "DEFAULT PATHS" -.PP -The default list of paths on the module path is computed by a -\fBtclsh\fR as follows, where \fIX\fR is the major version of the Tcl -interpreter and \fIy\fR is less than or equal to the minor version of -the Tcl interpreter. -.PP -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. -.PP -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. -.SS "SYSTEM SPECIFIC PATHS" -.TP -\fBfile normalize [info library]/../tcl\fIX\fB/\fIX\fB.\fIy\fR -. -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. -.RS -.PP -For example for Tcl 8.4 the paths searched are: -.PP -.CS -\fB[info library]/../tcl8/8.4\fR -\fB[info library]/../tcl8/8.3\fR -\fB[info library]/../tcl8/8.2\fR -\fB[info library]/../tcl8/8.1\fR -\fB[info library]/../tcl8/8.0\fR -.CE -.PP -This definition assumes that a package defined for Tcl \fIX\fB.\fIy\fR -can also be used by all interpreters which have the same major number -\fIX\fR and a minor number greater than \fIy\fR. -.RE -.TP -\fBfile normalize EXEC/tcl\fIX\fB/\fIX\fB.\fIy\fR -. -Where \fBEXEC\fR is \fBfile normalize [info nameofexecutable]/../lib\fR -or \fBfile normalize [::tcl::pkgconfig get libdir,runtime]\fR -.RS -.PP -This sets of paths is handled equivalently to the set coming before, -except that it is anchored in \fBEXEC_PREFIX\fR. -For a build with \fBPREFIX\fR = \fBEXEC_PREFIX\fR the two sets are -identical. -.RE -.SS "SITE SPECIFIC PATHS" -.TP -\fBfile normalize [info library]/../tcl\fIX\fB/site-tcl\fR -. -Note that this is always a single entry because \fIX\fR is always a -specific value (the current major version of Tcl). -.SS "USER SPECIFIC PATHS" -.TP -\fB$::env(TCL\fIX\fB_\fIy\fB_TM_PATH)\fR -. -A list of paths, separated by either \fB:\fR (Unix) or \fB;\fR -(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. -.TP -\fB$::env(TCL\fIX\fB.\fIy\fB_TM_PATH)\fR -. -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. -.PP -These paths are seen and therefore shared by all Tcl shells in the -\fB$::env(PATH)\fR of the user. -.PP -Note that \fIX\fR and \fIy\fR follow the general rules set out -above. In other words, Tcl 8.4, for example, will look at these 10 -environment variables: -.PP -.CS -\fB$::env(TCL8.4_TM_PATH)\fR \fB$::env(TCL8_4_TM_PATH)\fR -\fB$::env(TCL8.3_TM_PATH)\fR \fB$::env(TCL8_3_TM_PATH)\fR -\fB$::env(TCL8.2_TM_PATH)\fR \fB$::env(TCL8_2_TM_PATH)\fR -\fB$::env(TCL8.1_TM_PATH)\fR \fB$::env(TCL8_1_TM_PATH)\fR -\fB$::env(TCL8.0_TM_PATH)\fR \fB$::env(TCL8_0_TM_PATH)\fR -.CE -.SH "SEE ALSO" -package(n), Tcl Improvement Proposal #189 -.QW "\fITcl Modules\fR" -(online at http://tip.tcl.tk/189.html), Tcl Improvement Proposal #190 -.QW "\fIImplementation Choices for Tcl Modules\fR" -(online at http://tip.tcl.tk/190.html) -.SH "KEYWORDS" -modules, package -.\" Local Variables: -.\" mode: nroff -.\" End: |