## Tcl9.0.3/Tk9.0.3 Documentation > Tcl Commands > tm

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    tm — Tcl 機能単位を捜して組込むための便益　　　　Facilities for locating and loading of Tcl Modules
  構文 SYNOPSIS
  説明 DESCRIPTION
    ::tcl::tm::path add ?path...?
    ::tcl::tm::path remove ?path...?
    ::tcl::tm::path list
    ::tcl::tm::roots paths
  MODULE DEFINITION
  FINDING MODULES
  省略時設定の経路　　DEFAULT PATHS
  SYSTEM SPECIFIC PATHS
    file normalize [info library]/../tcl X/X.y
    file normalize EXEC/tcl X/X.y
  SITE SPECIFIC PATHS
    file normalize [info library]/../tcl X/site-tcl
  USER SPECIFIC PATHS
    $::env(TCL X_y_TM_PATH)
    $::env(TCL X.y_TM_PATH)
  SEE ALSO
  KEYWORDS

### NAME

tm — Tcl 機能単位を捜して組込むための便益　　　　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 paths

### 説明 DESCRIPTION

この説明書はTcl機能単位を捜して組込むための便益を記述する(Tcl機能単位の定義については MODULE DEFINITION 参照)｡次の命令に対応している｡　　　　　　 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 paths
  path add に似ていて､その頂の上に置く｡本命令は経路のリストを容れた一個の引数を取り､それぞれを､この解釈実行機能の仔番号と同じか小さい Tcl 解釈実行機能の主版番号の X と仔版番号の y では “tcl X/site-tcl” と “tcl X/X.y” により拡張し､結果の経路を捜索すべき経路のリストに加える｡　　　　　　 Similar to path add, and layered on top of it. This command takes a single argument containing a list of paths, extends each with “tcl X/site-tcl”, and “tcl X/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

Tcl 機能単位 は一個のファイル内に含まれた Tcl 梱包であり､それ以外のファイルは要求されない｡このファイルは source 命令により利用できなければならない｡言換えると Tcl 機能単位 は常に次を経由して移入される：　　　　　 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

load 命令は直接には使用されない｡この制限は一部で信じられている程には実際上の限界ではない｡凡そ 8.4 以降 Tcl source 命令は最初の ^Z 文字迄のみを読む｡これにより､任意の Tcl 記述譜と任意の二進データとを一個のファイルに結合することができる様になった､そこでその記述譜は付属のデータを何処かに処理して完全に移入して梱包を起動するために選ぶ｡　　　　　　　　 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

Tcl 機能単位 の為のデレクトリー樹枝はファイル系の他の部分とは別れていて且つ auto_path から独立している｡　　　　 The directory tree for storing Tcl modules is separate from other parts of the filesystem and independent of auto_path.

Tcl 機能単位 は命令 ::tcl::tm::path list の結果の中に列挙された全てのディレクトリーを捜される｡これは機能単位経路と呼ばれる｡ auto_path も tcl_pkgPath 変数も使われない｡機能単位経路上の全てのディレクトリーは次の一つの制限に従わなければならない:　　　　 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.

これは梱包名前付けに曖昧さを避ける為の要請である｡もし､譬えば､二つのディレクトリー “foo/” と “foo/cool” が経路上にあるとすると､ cool::ice と名付けられた梱包は cool::ice か ice と謂う名前経由で見つかるかもしれない､後者は潜在的に､曖昧に梱包は修飾されずに ice と名付けられるかもしれない｡　　　　　　 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:

  梱包の名前に生じた全ての “::” は､我々が使っているOSでの適切なディレクトリー分割文字によって置換えられる｡ 譬えばユニックス上では､それは “/” である｡　　　　　　　 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:

  要求された梱包が encoding::base64 では｡生成される部分経路は “encoding/base64” になる｡　　　　　 The requested package is encoding::base64. The generated partial path is “encoding/base64”.

この翻訳の後､梱包は､それらを一つずつ繋げて､最初から最後まで部分経路から完全な捜索文様を形成して､全ての機能単位経路が捜索される｡ 註意すべきは､捜索算法は､ファイル名称が MODULE DEFINITION の節に与えられた正規表現に合致しない全てのファイルを拒絶する｡残りのファイルに対して提供された記述譜が生成され必要に応じて基礎データ梱包に追加する｡　 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.

註意すべきは機能単位形式内の梱包は索引に関する制御は有していない又､その為に梱包基礎データに込められた記述譜を提供する｡機能単位ファイル MF には記述譜は常に次の通り：　　　　　　　　 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

梱包名 PNAME と梱包版番号 PVERSION の両方共､下の定義に従って 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

ここで PNAME′ は FINDING MODULES の節内に定義された通りの､機能単位の部分経路であり､全てのディレクトリー区切りを “::” に変更することにより PNAME に変換され､又､機能単位経路は我々が機能単位ファイルのもとで発見した経路(捜索すべき経路のリストから)である｡　　　　　　　　　　　 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.

註意すべきは又､我々はここで梱包名称と経路の間の接続を創生している｡ Tcl は梱包名称を比較すべき時には大文字小文字を区別するが､ NTFS の如く､区別しないファイル系も存在する｡幸いにも､この様なファイル系も比較の際にその情報を使わないにも拘らず名前を大文字小文字を区別して保存している｡　　　　　 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.

この様な状況から､Tcl 機能単位の中の梱包の名前に､大文字小文字の混合を許容することも可能であるが､区別しない比較方法でも､名前の重複を回避する必要がある｡言換えると､Tcl 機能単位に Foo と言う梱包を配備すると､最早 foo や fOo 等 の様な名前の Tcl 機能単位は許容されない｡ 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

機能単位経路上の経路の省略時設定のリストは tclsh によって次の様に計算される､ここで X はTcl 解釈実行機能の主版番号であり y はTcl 解釈実行機能の仔版番号より小さいか等しい｡　　　　　　　 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]/../tcl X/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.

  譬えば､ Tcl 8.4 では捜索される経路は次の通り:　　　　　　 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

  この定義は､ Tcl X.y について定義された梱包は同じ主番号 X 及び y より大きい仔番号を有する全ての解釈実行系にも使うことができることを假定している｡　　　　 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/tcl X/X.y
  ここで､EXEC は file normalize [info nameofexecutable]/../lib 又は file normalize [::tcl::pkgconfig get libdir,runtime] である｡　　　　　　　　　　　　　　 Where EXEC is file normalize [info nameofexecutable]/../lib or file normalize [::tcl::pkgconfig get libdir,runtime]

  この経路の群は､以前にえられたものと等価に扱われる､但し､ EXEC_PREFIX 内に固着させられたものを除く｡機械語翻訳での条件 PREFIX = EXEC_PREFIX では二組は同一である｡　　　　　　 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]/../tcl X/site-tcl
  註意すべきは､これは常に一個の見出しである､理由は X は特別な値(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(TCL X_y_TM_PATH)
  経路のリストはそれぞれ(Unixでは) :と(Windowsでは) ; によって区切られる｡これは使用者と配布所に固有であり､この環境変数は使用者の輪郭だけでなく､系の構成設定記述譜によっても同じく設定され得る｡　　　　　 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(TCL X.y_TM_PATH)
  以前の変数と同じ意味､且つ同じ内容である｡但し､主と仔の版番号を隔てる為の点 '.' の使用は､この名前を非移植性に低下させるのでその使用は落胆される｡この変数の運用は元の規格即ち TIP 189 による旧版の両立性の為にのみ守られてきた｡　　　　　　　　　　 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.

これ等の経路が見え､従って､使用者の$::env(PATH)内の全ての Tcl 殻によって共有される｡ These paths are seen and therefore shared by all Tcl shells in the $::env(PATH) of the user.

註意すべきは､あの X と y は､上に陳述した一般則に従う｡言換えると､譬ば Tcl 9.1 は次の４つの環境変数を捜すことになる｡　　　　　　 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)

環境変数から初期化された経路は､波付符号置換を蒙る(filename参照)｡ 使用者が知らない為に その波付符号置換が失敗する様な､どの経路も捜索経路から省略される｡ 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.

### SEE ALSO

package, Tcl Improvement Proposal #189 “Tcl Modules” (online at https://core.tcl-lang.org/tips/doc/trunk/tip/189.md), Tcl Improvement Proposal #190 “Implementation Choices for Tcl Modules” (online at https://core.tcl-lang.org/tips/doc/trunk/tip/190.md)

### KEYWORDS

modules, package
Copyright © 2004-2010 Andreas Kupries <andreas_kupries(at)users.sourceforge.net>