## Tcl8.6.17/Tk8.6.17 Documentation > Tcl C API > CrtCommand

### 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_CreateCommand — 新しいC 言語の命令を実装する implement new commands in C
  SYNOPSIS
    #include <tcl.h>
    Tcl_Command
    Tcl_CreateCommand(interp, cmdName, proc, clientData, deleteProc)
  引数 ARGUMENTS
    Tcl_Interp *interp (入力in)
    const char *cmdName (入力in)
    Tcl_CmdProc *proc (入力in)
    ClientData clientData (入力in)
    Tcl_CmdDeleteProc *deleteProc (入力in)
  説明 DESCRIPTION
  SEE ALSO
  KEYWORDS

### NAME

Tcl_CreateCommand — 新しいC 言語の命令を実装する implement new commands in C

### SYNOPSIS

#include <tcl.h>
Tcl_Command
Tcl_CreateCommand(interp, cmdName, proc, clientData, deleteProc)

### 引数 ARGUMENTS

Tcl_Interp *interp (入力in)
  その中に新しい命令を作成する解釈実行機能｡ Interpreter in which to create new command.

const char *cmdName (入力in)
  命令の名前｡ Name of command.

Tcl_CmdProc *proc (入力in)
  新しい命令の実装: proc は何時であれ cmdName が命令として起動されたときに呼ばれる｡ 　　 Implementation of new command: proc will be called whenever cmdName is invoked as a command.

ClientData clientData (入力in)
  proc と deleteProc に渡される任意の１語｡ 　　 Arbitrary one-word value to pass to proc and deleteProc.

Tcl_CmdDeleteProc *deleteProc (入力in)
  解釈実行機能から cmdName が削除される前に呼ばれる手続函数; 命令固有の一掃を許容する｡もし NULL なら､命令が削除される前に何も手続函数は呼ばれない｡ 　　 Procedure to call before cmdName is deleted from the interpreter; allows for command-specific cleanup. If NULL, then no procedure is called before the command is deleted.

### 説明 DESCRIPTION

Tcl_CreateCommand は新しい命令を interp 内に定義し､何時であれ Tcl 命令として cmdName が起動された時( Tcl_Eval 経由で) Tcl 解釈実行機能が命令を処理する為に､ proc を呼出すことになる様に､手続函数 proc と結合する｡それは､新しい文字列基準の命令が定義される Tcl_CreateObjCommand とは異なる; 前者は､対象の代りに文字列引数の配列をとって命令手続函数が定義される｡ Tcl_CreateObjCommand に登録された対象基準の命令手続函数は､ Tcl_CreateCommand によって定義された文字列基準の命令手続函数に較べ本質的に高速に実行する事ができる｡之こそが､それらが､引数として Tcl 対象を取り､又､より効果的に操作できる内部表現を残すことができるような対象を取る理由である｡又､Tcl's の解釈実行機能は今や､内部的に対象を使う｡ Tcl_CreateCommand によって登録された文字基準の命令手続函数を起動する為に､文字列基準命令手続函数によって返される文字列結果を保有する為に新しい Tcl 対象を呼び､作成する前に､それぞれの対象引数から表現される文字列を生成し持込まなければならない｡ Tcl_CreateCommand は以前の版との互換性を保つ為に運営されている｡ Tcl_CreateCommand defines a new command in interp and associates it with procedure proc such that whenever cmdName is invoked as a Tcl command (via a call to Tcl_Eval) the Tcl interpreter will call proc to process the command. It differs from Tcl_CreateObjCommand in that a new string-based command is defined; that is, a command procedure is defined that takes an array of argument strings instead of values. The value-based command procedures registered by Tcl_CreateObjCommand can execute significantly faster than the string-based command procedures defined by Tcl_CreateCommand. This is because they take Tcl values as arguments and those values can retain an internal representation that can be manipulated more efficiently. Also, Tcl's interpreter now uses values internally. In order to invoke a string-based command procedure registered by Tcl_CreateCommand, it must generate and fetch a string representation from each argument value before the call. New commands should be defined using Tcl_CreateObjCommand. We support Tcl_CreateCommand for backwards compatibility.

手続函数 Tcl_DeleteCommand と Tcl_GetCommandInfo と Tcl_SetCommandInfo は Tcl_CreateCommand と共に使われる｡ 　　　 The procedures Tcl_DeleteCommand, Tcl_GetCommandInfo, and Tcl_SetCommandInfo are used in conjunction with Tcl_CreateCommand.

Tcl_CreateCommand は､既存の命令 cmdName が既に解釈実行機能と結合している場合､削除する｡それは引続く Tcl_GetCommandName への呼出し内の命令の参照に使われる字句解析結果を返すかもしれない｡もし cmdName が何かの名前空間修飾子 :: を含んでいる場合､命令は指定された名前空間を追加される; そうでない場合､命令は大域名前空間に追加される｡もし Tcl_CreateCommand が削除されている処理課程内の解釈実行機能の為に呼ばれると､新しい命令をつくることなく NULL を返す｡ Proc は Tcl_CmdProc 型に合致する引数と結果を有するべきである: Tcl_CreateCommand will delete an existing command cmdName, if one is already associated with the interpreter. It returns a token that may be used to refer to the command in subsequent calls to Tcl_GetCommandName. If cmdName contains any :: namespace qualifiers, then the command is added to the specified namespace; otherwise the command is added to the global namespace. If Tcl_CreateCommand is called for an interpreter that is in the process of being deleted, then it does not create a new command and it returns NULL. Proc should have arguments and result that match the type Tcl_CmdProc:

    typedef int Tcl_CmdProc(
            ClientData clientData,
            Tcl_Interp *interp,
            int argc,
            const char *argv[]);

proc が起動されたとき､ clientData と interp 假引数は Tcl_CreateCommand に与えられた clientData と interp 引数の複写になる｡典型的には､ clientData は､応用譜固有のデータ構造を指し､それには命令が起動された時に何をなすべきかが記述されている｡ argc と argv は命令への引数を記述し､ argc は引数の個数を与え(命令の名前も含む)､ argv は文字列として引数の値を与える｡ argv 配列は argc+1 個の値を含むことになる; argc の最初の値は文字列引数を指し､最後の値は NULL である｡註意すべきは､文字列引数は､それが恒常的な文字列を指すとか､又､解釈実行機能の他の部分と共有されるかもしれない様に修正すべきではない｡　　　　 When proc is invoked the clientData and interp parameters will be copies of the clientData and interp arguments given to Tcl_CreateCommand. Typically, clientData points to an application-specific data structure that describes what to do when the command procedure is invoked. Argc and argv describe the arguments to the command, argc giving the number of arguments (including the command name) and argv giving the values of the arguments as strings. The argv array will contain argc+1 values; the first argc values point to the argument strings, and the last value is NULL. Note that the argument strings should not be modified as they may point to constant strings or may be shared with other parts of the interpreter.

註意すべきは､引数文字列は Tcl.の 8.1 版以降標準化された UTF-8 で符号化されている｡ 　　　 Note that the argument strings are encoded in normalized UTF-8 since version 8.1 of Tcl.

Proc は予測される TCL_OK か TCL_ERROR か TCL_RETURN か TCL_BREAK か TCL_CONTINUE か の内の一つの整数符号を返す筈である｡大多数の通常の命令は､ TCL_OK か TCL_ERROR だけを返す｡更に proc は解釈実行機能の結果を設定しなければならない ; TCL_OK 符号を返す場合､之は命令の結果を与え､ TCL_ERROR の場合､不都合伝言文を与える｡ Tcl_SetResult 手続函数は､返り値を設定する容易な相互干渉作用を提供する; その解釈実行機能の欄が如何に管理されるかの完全な詳細については取扱説明書の Tcl_Interpを参照されたい｡手続函数命令を起動する前に､ Tcl_Eval は解釈実行機能の結果に空文字列を指させる､そこで単純な命令は何もすることなく空の結果を返すことができる｡ Proc must return an integer code that is expected to be one of TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CONTINUE. See the Tcl overview man page for details on what these codes mean. Most normal commands will only return TCL_OK or TCL_ERROR. In addition, proc must set the interpreter result; in the case of a TCL_OK return code this gives the result of the command, and in the case of TCL_ERROR it gives an error message. The Tcl_SetResult procedure provides an easy interface for setting the return value; for complete details on how the interpreter result field is managed, see the Tcl_Interp man page. Before invoking a command procedure, Tcl_Eval sets the interpreter result to point to an empty string, so simple commands can return an empty result by doing nothing at all.

argv の内容は Tcl に属し､一度の proc の返りまで生残ることを保障されない: proc はそれを修正するべきではないし､解釈実行機能の結果は何処であれ argv 値の範囲を指させるべきではない｡何かを argv 配列から返したいと望む場合は､条件 TCL_VOLATILE と共に Tcl_SetResult を呼ぶべきである｡ 　　　 The contents of the argv array belong to Tcl and are not guaranteed to persist once proc returns: proc should not modify them, nor should it set the interpreter result to point anywhere within the argv values. Call Tcl_SetResult with status TCL_VOLATILE if you want to return something from the argv array.

DeleteProc は､(もしも) cmdName が削除された時に起動される｡これは Tcl_DeleteCommand か Tcl_DeleteInterp の呼出しを通し､或は Tcl_CreateCommand 命令への他の呼出し内の cmdName の改名により生じ得る｡DeleteProc は命令が削除される前に起動され､応用譜に命令に結合したどの様な命令も解除する機会を与える｡ DeleteProc は Tcl_CmdDeleteProc 型に合致する引数と結果を有するべきである: DeleteProc will be invoked when (if) cmdName is deleted. This can occur through a call to Tcl_DeleteCommand or Tcl_DeleteInterp, or by replacing cmdName in another call to Tcl_CreateCommand. DeleteProc is invoked before the command is deleted, and gives the application an opportunity to release any structures associated with the command. DeleteProc should have arguments and result that match the type Tcl_CmdDeleteProc:

    typedef void Tcl_CmdDeleteProc(
            ClientData clientData);

clientData 引数は Tcl_CreateCommand に渡した clientData 引数と同じになる｡ The clientData argument will be the same as the clientData argument passed to Tcl_CreateCommand.

### SEE ALSO

Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult

### KEYWORDS

bind, command, create, delete, interpreter, namespace
Copyright © 1989-1993 The Regents of the University of California.
Copyright © 1994-1997 Sun Microsystems, Inc.