## Tcl9.0.3/Tk9.0.3 Documentation > Tcl C API > Ensemble

### 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
    Tcl_CreateEnsemble, Tcl_FindEnsemble, Tcl_GetEnsembleFlags, Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace, Tcl_GetEnsembleParameterList, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsembleSubcommandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMappingDict, Tcl_SetEnsembleParameterList, Tcl_SetEnsembleSubcommandList, Tcl_SetEnsembleUnknownHandler — 集団命令の操作 manipulate ensemble commands
  SYNOPSIS
    #include <tcl.h>
    Tcl_Command
    Tcl_CreateEnsemble(interp, name, namespacePtr, ensFlags)
    Tcl_Command
    Tcl_FindEnsemble(interp, cmdNameObj, flags)
    int
    Tcl_IsEnsemble(token)
    int
    Tcl_GetEnsembleFlags(interp, token, ensFlagsPtr)
    int
    Tcl_SetEnsembleFlags(interp, token, ensFlags)
    int
    Tcl_GetEnsembleMappingDict(interp, token, dictObjPtr)
    int
    Tcl_SetEnsembleMappingDict(interp, token, dictObj)
    int
    Tcl_GetEnsembleParameterList(interp, token, listObjPtr)
    int
    Tcl_SetEnsembleParameterList(interp, token, listObj)
    int
    Tcl_GetEnsembleSubcommandList(interp, token, listObjPtr)
    int
    Tcl_SetEnsembleSubcommandList(interp, token, listObj)
    int
    Tcl_GetEnsembleUnknownHandler(interp, token, listObjPtr)
    int
    Tcl_SetEnsembleUnknownHandler(interp, token, listObj)
    int
    Tcl_GetEnsembleNamespace(interp, token, namespacePtrPtr)
  引数 ARGUMENTS
    Tcl_Interp *interp (入出力in/out)
    const char *name (入力in)
    Tcl_Namespace *namespacePtr (in)
    int ensFlags (入力in)
    Tcl_Obj *cmdNameObj (入力in)
    int flags (入力in)
    Tcl_Command token (入力in)
    int *ensFlagsPtr (out)
    Tcl_Obj *dictObj (入力in)
    Tcl_Obj **dictObjPtr (出力out)
    Tcl_Obj *listObj (入力in)
    Tcl_Obj **listObjPtr (出力out)
    Tcl_Namespace **namespacePtrPtr (出力out)
  説明 DESCRIPTION
  ENSEMBLE PROPERTIES
  flags (read-write)
  mapping dictionary (read-write)
  formal pre-subcommand parameter list (read-write)
  subcommand list (read-write)
  unknown subcommand handler command prefix (read-write)
  bound namespace (read-only)
  参照回数管理 REFERENCE COUNT MANAGEMENT
  SEE ALSO
  KEYWORDS

### NAME

Tcl_CreateEnsemble, Tcl_FindEnsemble, Tcl_GetEnsembleFlags, Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace, Tcl_GetEnsembleParameterList, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsembleSubcommandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMappingDict, Tcl_SetEnsembleParameterList, Tcl_SetEnsembleSubcommandList, Tcl_SetEnsembleUnknownHandler — 集団命令の操作 manipulate ensemble commands

### SYNOPSIS

#include <tcl.h>
Tcl_Command
Tcl_CreateEnsemble(interp, name, namespacePtr, ensFlags)
Tcl_Command
Tcl_FindEnsemble(interp, cmdNameObj, flags)
int
Tcl_IsEnsemble(token)
int
Tcl_GetEnsembleFlags(interp, token, ensFlagsPtr)
int
Tcl_SetEnsembleFlags(interp, token, ensFlags)
int
Tcl_GetEnsembleMappingDict(interp, token, dictObjPtr)
int
Tcl_SetEnsembleMappingDict(interp, token, dictObj)
int
Tcl_GetEnsembleParameterList(interp, token, listObjPtr)
int
Tcl_SetEnsembleParameterList(interp, token, listObj)
int
Tcl_GetEnsembleSubcommandList(interp, token, listObjPtr)
int
Tcl_SetEnsembleSubcommandList(interp, token, listObj)
int
Tcl_GetEnsembleUnknownHandler(interp, token, listObjPtr)
int
Tcl_SetEnsembleUnknownHandler(interp, token, listObj)
int
Tcl_GetEnsembleNamespace(interp, token, namespacePtrPtr)

### 引数 ARGUMENTS

Tcl_Interp *interp (入出力in/out)
  その中に､集団が生成されるか見付けられる解釈実行機能｡亦､其処に結果の伝言The interpreter in which the ensemble is to be created or found. Also where error result messages are written. The functions whose names start with Tcl_GetEnsemble may have a NULL for the interp, but all other functions must not.

const char *name (入力in)
  生成されるべき集団命令の名前｡　 The name of the ensemble command to be created.

Tcl_Namespace *namespacePtr (in)
  其処に集団命令が束縛されるべき名前空間､又は現在の名前空間については NULL｡　 The namespace to which the ensemble command is to be bound, or NULL for the current namespace.

int ensFlags (入力in)
  集団の基本的構成設定を記述する旗印の論理和組合わせ｡現在唯一つのビット TCL_ENSEMBLE_PREFIX が意味を有し､それは 集団命令も亦副命令の不明瞭な前置辞に合致する時に存在する｡　 An OR'ed set of flag bits describing the basic configuration of the ensemble. Currently only one bit has meaning, TCL_ENSEMBLE_PREFIX, which is present when the ensemble command should also match unambiguous prefixes of subcommands.

Tcl_Obj *cmdNameObj (入力in)
  捜すべき集団命令の名前を保有する値｡ 　　　 A value holding the name of the ensemble command to look up.

int flags (入力in)
  Tcl_FindEnsemble の振舞いを制御する旗印ビットの論理和の組｡現在 TCL_LEAVE_ERR_MSG のみが供給されている｡　 　　 An OR'ed set of flag bits controlling the behavior of Tcl_FindEnsemble. Currently only TCL_LEAVE_ERR_MSG is supported.

Tcl_Command token (入力in)
  通常の命令字句であって､集団命令を参照している､又は使用者が Tcl_IsEnsemble 内の集団命令として試験する為に使用することを望むもの｡　 A normal command token that refers to an ensemble command, or which you wish to use for testing as an ensemble command in Tcl_IsEnsemble.

int *ensFlagsPtr (out)
  その中に現在の集団旗印ビットを書く変数への指示子; 現在の処､TCL_ENSEMBLE_PREFIX ビットのみが定義されている｡　 Pointer to a variable into which to write the current ensemble flag bits; currently only the bit TCL_ENSEMBLE_PREFIX is defined.

Tcl_Obj *dictObj (入力in)
  集団の中で､副命令から実装命令前置辞に対応付ける辞書の為に使用する辞書値｡対応付け辞書が取外された場合は NULL でもよい｡　 A dictionary value to use for the subcommand to implementation command prefix mapping dictionary in the ensemble. May be NULL if the mapping dictionary is to be removed.

Tcl_Obj **dictObjPtr (出力out)
  その中に現在の集団対応付け辞書を書くべき変数への指示子｡　 Pointer to a variable into which to write the current ensemble mapping dictionary.

Tcl_Obj *listObj (入力in)
  公式の前置-副命令假引数､又は辞書内の副命令の定義されたリスト､又は未知の副命令取っ手命令前置辞に使用するリスト値｡もし､副命令リスト又は未知の取っ手が除去されている場合は NULL でも好い｡　 A list value to use for the list of formal pre-subcommand parameters, the defined list of subcommands in the dictionary or the unknown subcommand handler command prefix. May be NULL if the subcommand list or unknown handler are to be removed.

Tcl_Obj **listObjPtr (出力out)
  公式の前部-副命令假引数の現在のリスト､又は副命令の定義されたリスト､又は現在の未知の取っ手前置辞をその中に書込む変数への指示子｡　 　 Pointer to a variable into which to write the current list of formal pre-subcommand parameters, the defined list of subcommands or the current unknown handler prefix.

Tcl_Namespace **namespacePtrPtr (出力out)
  其処に集団が束縛される名前空間の取っ手をその中に書く為の変数への指示子｡　 　 Pointer to a variable into which to write the handle of the namespace to which the ensemble is bound.

### 説明 DESCRIPTION

集団は命令であり､他の Tcl 命令によって実装された副命令の集まりから構成される名前空間に束縛される｡集団命令への第１の引数は常に副命令が実行することを述べる選択機能として解釈される｡ 　　　 An ensemble is a command, bound to some namespace, which consists of a collection of subcommands implemented by other Tcl commands. The first argument to the ensemble command is always interpreted as a selector that states what subcommand to execute.

集団は Tcl_CreateEnsemble を使い作成される､それは４つの引数を取る:その中で働く解釈実行機能､作成すべき集団の名前､集団に束縛する為の解釈実行機能内の名前空間､集団の旗印の省略時設定の組｡その函数の結果は集団の為の命令字句であり､それは下の ENSEMBLE PROPERTIES 内で記述された API を使う更なる集団の構成設定に使用できる｡ 　　　 Ensembles are created using Tcl_CreateEnsemble, which takes four arguments: the interpreter to work within, the name of the ensemble to create, the namespace within the interpreter to bind the ensemble to, and the default set of ensemble flags. The result of the function is the command token for the ensemble, which may be used to further configure the ensemble using the API described below in ENSEMBLE PROPERTIES.

集団命令の名前を与えられ､ Tcl_FindEnsemble を使って､命令の字句が取出される｡もし､与えられた命令の名前( cmdNameObj 内に)が集団命令を参照しない場合､函数の結果は NULL で､(もし TCL_LEAVE_ERR_MSG ビットが flags 内に設定されると)不都合伝言文が解釈実行機能の結果内に残される｡ 　　　　 Given the name of an ensemble command, the token for that command may be retrieved using Tcl_FindEnsemble. If the given command name (in cmdNameObj) does not refer to an ensemble command, the result of the function is NULL and (if the TCL_LEAVE_ERR_MSG bit is set in flags) an error message is left in the interpreter result.

命令字句結果は､それが Tcl_IsEnsemble を使用して集団を参照しているかを検査する｡之は､字句が集団を参照していると 1 を､それ以外は 0 を返す｡ 　　　 A command token may be checked to see if it refers to an ensemble using Tcl_IsEnsemble. This returns 1 if the token refers to an ensemble, or 0 otherwise.

#### ENSEMBLE PROPERTIES

全ての集団は４つの読み書き特性と､一つの読出し専用特性を有する｡その特性は: Every ensemble has four read-write properties and a read-only property. The properties are:

flags (read-write)
  集団の為の旗印の組､ビット欄として表現される｡現在､公表された旗印は TCL_ENSEMBLE_PREFIX のみで､厳密合致と同じように､不明瞭な副命令の前置辞の実施の決定が許容される時に設定される｡その旗印は Tcl_GetEnsembleFlagsR と Tcl_SetEnsembleFlags を使ってそれぞれ読み､書きされる｡これ等の函数両方の結果は Tcl 結果符号(もし字句が集団を参照していない場合は TCL_OK か TCL_ERROR )である｡ 　　　 The set of flags for the ensemble, expressed as a bit-field. Currently, the only public flag is TCL_ENSEMBLE_PREFIX which is set when unambiguous prefixes of subcommands are permitted to be resolved to implementations as well as exact matches. The flags may be read and written using Tcl_GetEnsembleFlags and Tcl_SetEnsembleFlags respectively. The result of both of those functions is a Tcl result code (TCL_OK, or TCL_ERROR if the token does not refer to an ensemble).

mapping dictionary (read-write)
  副命令の名前から命令前置辞として使う語のリスト(集団命令自身か副命令名の命令の最初の２語を置換える)､又は､もし全ての副命令が集団に束縛された名前空間内の重複しない名前に対応されている場合は､ NULL への対応を含む辞書｡省略時設定は NULL｡ Tcl_GetEnsembleMappingDict と Tcl_SetEnsembleMappingDict を使ってそれぞれ読み又は書込まれ得る｡これ等の函数両方の結果は Tcl 結果符号(もし字句が集団を参照していない場合は TCL_OK か TCL_ERROR )である､又､ Tcl_GetEnsembleMappingDict から得られる辞書はそれが非共有であっても常に不変として扱われるべきである｡ Tcl_SetEnsembleMappingDict 経由で設定された前置辞内の全ての命令名は完全に修飾されていなければならない｡ 　　　 A dictionary containing a mapping from subcommand names to lists of words to use as a command prefix (replacing the first two words of the command which are the ensemble command itself and the subcommand name), or NULL if every subcommand is to be mapped to the command with the same unqualified name in the ensemble's bound namespace. Defaults to NULL. May be read and written using Tcl_GetEnsembleMappingDict and Tcl_SetEnsembleMappingDict respectively. The result of both of those functions is a Tcl result code (TCL_OK, or TCL_ERROR if the token does not refer to an ensemble) and the dictionary obtained from Tcl_GetEnsembleMappingDict should always be treated as immutable even if it is unshared. All command names in prefixes set via Tcl_SetEnsembleMappingDict must be fully qualified.

formal pre-subcommand parameter list (read-write)
  公式の假引数のリスト(不都合伝言文を作成する時にのみ使われる名前)､それは集団の名前と副命令引数との間の集団の起動の時にできる｡NULL (省略時設定)は空リストと等価である｡それぞれ Tcl_GetEnsembleParameterList と Tcl_SetEnsembleParameterList を使って読み書きされるかもしれない｡これ等の両方の函数の結果は Tcl 結果符号(字句が集団を参照していない場合は TCL_OK か TCL_ERROR)であり､ Tcl_GetEnsembleParameterList から得られた辞書は､たとえそれが非共有でも､常に変更不能として扱われるべきである｡ 　　　 A list of formal parameter names (the names only being used when generating error messages) that come at invocation of the ensemble between the name of the ensemble and the subcommand argument. NULL (the default) is equivalent to the empty list. May be read and written using Tcl_GetEnsembleParameterList and Tcl_SetEnsembleParameterList respectively. The result of both of those functions is a Tcl result code (TCL_OK, or TCL_ERROR if the token does not refer to an ensemble) and the dictionary obtained from Tcl_GetEnsembleParameterList should always be treated as immutable even if it is unshared.

subcommand list (read-write)
  集団の為の全ての副命令の名前のリスト､但しそれが対応辞書の鍵か(上述)､束縛された名前空間により移送された命令の組(その場合 NULL)かの場合は NULL ｡ Tcl_GetEnsembleSubcommandList と Tcl_SetEnsembleSubcommandList を使ってそれぞれ読み又は書込まれ得る｡これ等の函数両方の結果は Tcl 結果符号(もし字句が集団を参照していない場合は TCL_OK か TCL_ERROR)である､又､ Tcl_GetEnsembleSubcommandList から得られるリストはそれが非共有であっても常に不変として扱われるべきである｡ 　　　 A list of all the subcommand names for the ensemble, or NULL if this is to be derived from either the keys of the mapping dictionary (see above) or (if that is also NULL) from the set of commands exported by the bound namespace. May be read and written using Tcl_GetEnsembleSubcommandList and Tcl_SetEnsembleSubcommandList respectively. The result of both of those functions is a Tcl result code (TCL_OK, or TCL_ERROR if the token does not refer to an ensemble) and the list obtained from Tcl_GetEnsembleSubcommandList should always be treated as immutable even if it is unshared.

unknown subcommand handler command prefix (read-write)
  副命令が集団には未知の時に､どの副命令の先頭にでも付加する語(現在の前置辞の規則に従って)のリスト; 更なる詳細は namespace ensemble 命令を参照されたい｡もし NULL の場合､未知の副命令と遭遇した時は､省略時設定の挙動 - 適切な不都合伝言文の生成 -が使われることになる｡ Tcl_GetEnsembleUnknownHandler か Tcl_SetEnsembleUnknownHandler を使って夫々読まれるか書かれるかもしれない｡これ等の両方の函数の結果は Tcl 結果符号(もし字句が集団を参照していない場合は TCL_OK か TCL_ERROR )である､又､ Tcl_GetEnsembleUnknownHandler から得られるリストはそれが非共有であっても常に不変として扱われるべきである｡ 　　　 A list of words to prepend on the front of any subcommand when the subcommand is unknown to the ensemble (according to the current prefix handling rule); see the namespace ensemble command for more details. If NULL, the default behavior - generate a suitable error message - will be used when an unknown subcommand is encountered. May be read and written using Tcl_GetEnsembleUnknownHandler and Tcl_SetEnsembleUnknownHandler respectively. The result of both functions is a Tcl result code (TCL_OK, or TCL_ERROR if the token does not refer to an ensemble) and the list obtained from Tcl_GetEnsembleUnknownHandler should always be treated as immutable even if it is unshared.

bound namespace (read-only)
  集団が束縛されている名前空間; 名前空間が削除された時､集団もそうなる､又､この名前空間は､もし対応辞書と副命令リストの両方が NULL.の場合は､その移送された命令のリストが使われる名前空間である｡ Tcl 結果符号(もし字句が集団を参照していない場合は TCL_OK か TCL_ERROR )を返す Tcl_GetEnsembleNamespace を使って読込まれるかもしれない ｡ 　　 The namespace to which the ensemble is bound; when the namespace is deleted, so too will the ensemble, and this namespace is also the namespace whose list of exported commands is used if both the mapping dictionary and the subcommand list properties are NULL. May be read using Tcl_GetEnsembleNamespace which returns a Tcl result code (TCL_OK, or TCL_ERROR if the token does not refer to an ensemble).

### 参照回数管理 REFERENCE COUNT MANAGEMENT

Tcl_FindEnsembleはそのcmdNameObj引数の回数を修正しない; 読出すのみである｡註意すべきは､しかしながら､この函数は解釈実行機能の結果を設定するかもしれず;もし､それが対象への参照を保持しているのみの場合､それは削除される｡ Tcl_FindEnsemble does not modify the reference count of its cmdNameObj argument; it only reads. Note however that this function may set the interpreter result; if that is the only place that is holding a reference to the object, it will be deleted.

集団特性捕獲者(Tcl_GetEnsembleMappingDictとTcl_GetEnsembleParameterListとTcl_GetEnsembleSubcommandListとTcl_GetEnsembleUnknownHandler)は､それが提供した値の参照回数を操作しない; それらが非ヌルの場合､それは最低1の参照回数を有すことになる｡註意 これ等の函数は､解釈実行機能の結果を設定し得る｡ The ensemble property getters (Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleParameterList, Tcl_GetEnsembleSubcommandList, and Tcl_GetEnsembleUnknownHandler) do not manipulate the reference count of the values they provide out; if those are non-NULL, they will have a reference count of at least 1. Note that these functions may set the interpreter result.

集団特性捕獲者(Tcl_SetEnsembleMappingDictとTcl_SetEnsembleParameterListとTcl_SetEnsembleSubcommandListとTcl_SetEnsembleUnknownHandler)は､ 若し成功すると､与えらえた特性の新しい値の参照回数を増加する(且つ､もし関連があると､特性の古い値の参照回数を減ずる)｡もし､特性設定処理が TCL_ERRORを返すと､Tcl_Obj引数の参照回数は変らずに残される｡ The ensemble property setters (Tcl_SetEnsembleMappingDict, Tcl_SetEnsembleParameterList, Tcl_SetEnsembleSubcommandList, and Tcl_SetEnsembleUnknownHandler) will increment the reference count of the new value of the property they are given if they succeed (and decrement the reference count of the old value of the property, if relevant). If the property setters return TCL_ERROR, the reference count of the Tcl_Obj argument is left unchanged.

### SEE ALSO

namespace, Tcl_DeleteCommandFromToken

### KEYWORDS

command, ensemble
Copyright © 2005 Donal K. Fellows