15. 定義コマンド

@deffnコマンドと他の定義コマンド(definition commands)で， 関数，変数，マクロ，コマンド，ユーザーオプション，スペシャルフォーム，そ してその他の一様な書式での人工物のようなものを記述可能になります．

Infoファイルでは，定義は構成要素のカテゴリ -- `関数'，`変数'，またはあ らゆるもの -- を定義の最初の行の始めに現し，構成要素の名前と引数が続き ます．印刷されたマニュアルでは，コマンドはTeXに構成要素の名前とその引 数を左端のマージンに印刷させ，カテゴリを次に右端のマージンに印刷させます． 両方の出力形式で，定義の本体は字下げされます．また，構成要素の名前は適切 な索引に入ります．@deffnは関数の索引に名前が入り，@defvr は変数の索引に入る等のようになります．

マニュアルは，与えられた名前に対し一つ以上の定義は不要で含めるべきではあ りません．概要を含む付録は，定義コマンドより@tableを使用すべきで す．

15.1 定義のテンプレート

@deffnコマンドは，関数に似ている構成要素の定義に使用されます． @deffnコマンドで定義を書くために，@deffnコマンドを行の最 初に書き，同じ行に構成要素のカテゴリ，構成要素自身の名前と，(存在する場 合は)引数を続けてください．そして，続く行に定義の本体を書いてください． (本体に例を埋め込むこともできます．)終りに，単独行に書かれた@end deffnコマンドで定義を終えてください．(他の定義コマンドも同じ書式が続き ます．)

定義のテンプレートは以下のようになります．

@deffn category name arguments...
body-of-definition
@end deffn

例えば，以下のようにします．

@deffn Command forward-word count
このコマンドは，ポイントを@var{count}語前に(または，@var{count}が
負の場合は後ろに)移動します．...@end deffn

以下を生成します．

Command: forward-word count

このコマンドは，ポイントをcount語前に(または，countが負の場 合は後ろに)移動します．...

タイトルのようなカテゴリ名は大文字にしてください．`Interactive Command' といった文節のようにカテゴリ名に空白が含まれている場合，周りにカッコを書 いてください．例えば以下のようにします．

@deffn {Interactive Command} isearch-forward
...
@end deffn

そうしない場合，二番目の単語は構成要素の名前と誤解されます．

定義コマンドには，それ以外に一般的なものもあります．例えば， @deffnコマンドは関数やそれに似たもの -- 引数を取る構成要素 -- に対する一般的な定義コマンドです．このコマンドを使用するときは，構成要素 が属するカテゴリを指定すべきです．@deffnコマンドには，三つの既に 定義されている専門的な変種の，@defun，@defmac，そして @defspecを処理し，それらはカテゴリを指定します．それぞれ"関数"， "マクロ"，そして"スペシャルフォーム"です．(Lispではスペシャルフォー ムは関数に似た構成要素です．) @defvrコマンドも，変数の特定の種類 を記述するため専門分野に相違のあるものとして，前もって定義されたものがあ ります．

@defunのような専門的に定義されているものに対するテンプレートは， カテゴリを指定する必要が無い以外，一般の定義のテンプレートに似ています．

@defun name arguments...
body-of-definition
@end defun

このため以下のようにします．

@defun buffer-end flag
この関数は@var{flag}が1より小さい場合@code{(point-min)}を返し，そ
れ以外では@code{(point-max)}を返します．...
@end defun

以下を生成します．

Function: buffer-end flag

この関数はflagが1より小さい場合(point-min)を返し，それ以外 では(point-max)を返します．...

定義の内部に@exampleの使用を含んでいる関数定義の詳細な例は， See section A Sample Function Definition.

それ以外の特別なコマンドは，@defunのように動作します．

実装が困難なため，@deffn内部とそれ以外のすべての定義コマンドの内 部にあるマクロは展開されないことに注意してください．

15.2 オプションと繰り返しの引数

オプションや繰り返しの引数を取る構成要素もあり，それは角カッコと丸カッコ を使用する特有なglyphで指定されているかもしれません．例えば，スペシャ ルフォームは，引数リストを簡単な関数より複雑な方法で分けられた引数に区切 ることもよくあります．

角カッコで囲まれた引数はオプションです．このため[optional-arg]のよ うな文節は，optional-argがオプションだということを意味します．丸カッ コに続く引数はオプションで，一度以上繰り返すこともできます． このため，repeated-args...は0以上の引数を意味します．いくつか の引数がLispのリスト構造の追加のレベルにまとめられるとき，カッコが使用さ れます．

想像上のスペシャルフォームの例の@defspecの行は以下のようになります．

Special Form: foobar (var [from to [inc]]) body...

この例では，引数fromとtoがオプションですが，両方とも有るか両 方とも無いことが必要です．それらが有る場合，incも同様にオプション で指定してかまいません．これらの引数はbodyと分けるため，リストに引 数varでまとめられ，それは形式の残りの全ての要素を含みます．

Texinfoソースファイルでは，この@defspec行は以下のように書かれま す(この例のように二行以上には分割されません)．

@defspec foobar (@var{var} [@var{from} @var{to}
    [@var{inc}]]) @var{body}@dots{}

関数はコマンドと変数の索引で`foobar'の下にリストアップされます．

15.3 二つ以上の`最初の'行

定義に対し二つ以上の`最初の'またはヘッダ行を作成するため，最初の @deffn行に@deffnxで始まる行を続けてください． @deffnxコマンドは，その行と前の行の間に余分な縦方向の空白を生成 しない以外，@deffnと同じように動作します．

例えば以下のようにします．

@deffn {Interactive Command} isearch-forward
@deffnx {Interactive Command} isearch-backward
この二つの検索コマンドは似ていて...
@end deffn

以下を生成します．

Interactive Command: isearch-forward

Interactive Command: isearch-backward

この二つの検索コマンドは似ていて...

それぞれの定義コマンドには`x'が付きます．@defunx， @defvrx，@deftypefunxなどです．

`x'の形式は@itemxと全く同じように動作します．@itemxを参照してください．

15.4 定義コマンド

Texinfoは1ダース以上の定義コマンドを提供していて，それらの全てをこのセ クションで記述します．

定義コマンドは自動的に構成要素の名前を適切な索引に入れます．例えば， @deffn，@defun，そして@defmacは関数の索引に関数 名を入れます．@defvrと@defvarは変数の索引に変数名を入れ ます．

以下のほとんどの例はLispの例ですが，コマンドは他のプログラミング言語でも 使用可能です．

15.4.1 関数とそれに類似した構成要素

このセクションは関数やそれに類似した構成要素の記述のためのコマンドを記述 します．

@deffn category name arguments...

@deffnコマンドは，関数，対話式コマンド，そして引数を取る類似の構 成要素のための一般的な定義コマンドです．定義されている構成要素のカテゴリ を記述する用語を選択する必要があります．例えば，"関数"は，構成要素が関 数の場合使用されます．@deffnコマンドは，行の最初に，同じ行に記述 する構成要素のカテゴリ，この特定の構成要素の名前，そして，存在する場合そ の引数を続けます．単独行の@end deffnで定義を終了してください．

例えば，定義を以下のようにします．

@deffn Command forward-char nchars ポイントを@var{nchars}文字前に移動します． @end deffn

これは，一つの引数ncharsを持つforward-charという名前の"コマ ンド"の，どちらかというと簡潔な定義を表示します．

@deffnは，ncharsのような引数名を@varが使用されてい るかのようにイタリックまたは大文字で印刷し，それは，これらの名前がメタ構 文変数と考えるためです -- それは実際の引数の値を意味します．記述のテキ ストで引数の値を述べるため，明示的に@varで引数名を書いてください． 上記の例では，このように`@var{nchars}'を使用しています．

@deffnのテンプレートは以下のとおりです．

@deffn category name arguments... body-of-definition @end deffn

@defun name arguments...

@defunコマンドは関数に対する定義コマンドです．@defunは， `@deffn Function ...'と同じです．

例えば，以下のようにします．

@defun set symbol new-value シンボル@var{symbol}の値を@var{new-value}に変更します． @end defun

これは，引数がsymbolとnew-valueの関数setの，どちらか というと簡潔な定義を表示します．@defun行の引数名は，@var で囲まれているかのように自動的にイタリックまたは大文字で現れます．単独行 の@end defunで定義を終了してください．

テンプレートは以下のとおりです．

@defun function-name arguments... body-of-definition @end defun

@defunは関数索引に項目を生成します．

@defmac name arguments...

@defmacコマンドはマクロの定義コマンドです．@defmacは `@deffn Macro ...'と同じで，@defunのように動作します．

@defspec name arguments...

@defspecコマンドは，スペシャルフォームの定義コマンドです．(Lisp では，スペシャルフォームは関数によく似た構成要素です．see section `Special Forms' in GNU Emacs Lisp Reference Manual．)@defspecは `@deffn {Special Form} ...'と同じで，@defunのように 動作します．

15.4.2 変数とそれに類似した構成要素

変数とそれに類似した構成要素を定義するためのコマンドは以下のものです．

@defvr category name

@defvrコマンドは変数のようなものの一般的な定義コマンドです -- 構成要素は値を記録します．定義された構成要素のカテゴリを記述するための， 用語を選択する必要があります．例えば，"変数"は構成要素が変数の場合使用 されます．@defvrコマンドを行の最初に書き，同じ行に構成要素のカテ ゴリと構成要素の名前を続けてください．

タイトルのようにカテゴリ名を大文字にしてください．カテゴリ名が"User Option"のようにスペースを含む場合，カッコで囲んでください．そうしない場 合，二番目の単語は構成要素の名前だと誤解されます．例えば，以下のようにし ます．

@defvr {User Option} fill-column このバッファローカル変数は， 補充された行の最大幅を指定します． ... @end defvr

単独行の@end defvrで定義を終了してください．

テンプレートは以下の通りです．

@defvr category name body-of-definition @end defvr

@defvrはnameに対し，変数索引の項目を作成します．

@defvar name

@defvarコマンドは，変数の定義コマンドです．@defvarは `@defvr Variable ...'と同じです．

例えば，以下のようにします．

@defvar kill-ring ... @end defvar

テンプレートは以下の通りです．

@defvar name body-of-definition @end defvar

@defvarは，nameに対し変数索引の項目を作成します．

@defopt name

@defoptコマンドは，ユーザオプション(user options)，すなは ち，ユーザが好みで変更する変数に対する定義コマンドです．Emacsは多くのそ のようなものがあります(see section `Variables' in The GNU Emacs Manual)． @defoptは`@defvr {User Option} ...'と同じで， @defvarのように動作します．

15.4.3 型のある言語の関数

@deftypefnコマンドとその変形は，CやC++のような変数の型と関数を宣 言する必要がある言語の関数を記述するためのものです．

@deftypefn category data-type name arguments...

@deftypefnコマンドは，関数と，引数を取るものや型のある類似の構成 要素の定義コマンドです．@deftypefnは行の最初に書き，同じ行に記述 される構成要素のカテゴリ，戻り値の型，この特定の構成要素の名前と，存在す る場合引数が続きます．

例えば，以下のようにします．

@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) ... @end deftypefn

("..."の前のテキストは，二行で表示され，Texinfoファイルでは実際に は単一行です．)Infoでは以下を生成します．

-- Library Function: int foobar (int FOO, float BAR) ...

これは，foobarが"ライブラリ関数"で，それはintを返し，引 数はfoo(int)とbar(float)だということを意味しま す．

@deftypefnで書いた引数名は，暗黙で@varにはなりません --- @deftypefnの引数の実際の名前は，データ型名とキーワードで通常はバ ラバラなので，Texinfoは助けなしに見つけることができません．代わりに， @varを引数名の周りに明示的に書く必要があります．上の例では，引数 名は`foo'と`bar'です．

@deftypefnのテンプレートは以下の通りです．

@deftypefn category data-type name arguments ... body-of-description @end deftypefn

categoryやdata typeが1単語以上の場合，単一の引数にするためカッ コで囲む必要があることに注意してください．

Adaのようなパッケージ言語のプロシージャを記述する場合，前の段落で記述さ れている慣習と幾分反対の方法として，@deftypefnの使用を手法として 考えるかもしれません．

例えば以下のようにします．

@deftypefn stacks private push (@var{s}:in out stack; @var{n}:in integer) ... @end deftypefn

(@deftypefnの引数は，三行に分割されていますが，実際のTexinfoファ イルでは単一行になります．)

この例では，プロシージャは`プロシージャ'と分類するのではなくパッケージ stacksに属するものとして分類され，そのデータ型はprivateと して記述されます．(プロシージャの名前はpushで，その引数はs とnです．)

@deftypefnはnameに対し関数索引に項目を作成します．

@deftypefun data-type name arguments...

@deftypefunコマンドは，型のある言語の関数のための特別な定義コマ ンドです．そのコマンドは`@deftypefn Function ...'と同じです．

このため以下のようにします．

@deftypefun int foobar (int @var{foo}, float @var{bar}) ... @end deftypefun

Infoでは以下を生成します．

-- Function: int foobar (int FOO, float BAR) ...

テンプレートは以下の通りです．

@deftypefun type name arguments... body-of-description @end deftypefun

@deftypefunはnameに対し関数索引に項目を作成します．

15.4.4 型のある言語の変数

型のある言語の変数は，型のある言語の関数に似た方法で処理されます． See section 15.4.3 型のある言語の関数. 一般的な定義コマンド@deftypevrは @deftypefnに対応し，特別な定義コマンド@deftypevarは @deftypefunに対応します．

@deftypevr category data-type name

@deftypevrコマンドは，型のある言語の変数のようなもののための一般 的な定義コマンドです---値を記録する構成要素です．定義される構成要素のカ テゴリを記述するための用語を選択する必要があります．例えば，"変数"は構 成要素が変数の場合使用します．

@deftypevrコマンドは，行の最初に書かれ，同じ行に記述される構成要 素のカテゴリ，データの型，そして特定の構成要素の名前が続きます．

例えば，以下のようにします．

@deftypevr {Global Flag} int enable ... @end deftypevr

Infoでは以下を生成します．

-- Global Flag: int enable ...

テンプレートは以下の通りです．

@deftypevr category data-type name body-of-description @end deftypevr

@deftypevrは，nameに対し変数索引に項目を作成します．

@deftypevar data-type name

@deftypevarコマンドは，型のある言語の変数のための特別な定義コマ ンドです．@deftypevarは`@deftypevr Variable ...'と同じ です．

例えば，以下のようにします．

@deftypevar int fubar ... @end deftypevar

Infoでは以下を生成します．

-- Variable: int fubar ...

テンプレートは以下の通りです．

@deftypevar data-type name body-of-description @end deftypevar

@deftypevarは，nameに対し，変数索引の項目を作成します．

15.4.5 オブジェクト指向プログラミング

オブジェクト指向プログラミングで使用するような，抽象的なオブジェクトに関 する記述を書式化するためのコマンドには以下のものがあります．クラスは抽象 的なオブジェクトの定義された型です．クラスのインスタンスはクラスの型を持 つ特定のオブジェクトです．インスタンス変数はクラスに属するがそれぞれのイ ンスタンスが独自の値を持つ変数です．

定義では，クラス名はクラスに対するプログラミングシステムで本当に定義され た名前の場合，@codeをその周りに書くべきです．そうしない場合，通 常のテキストフォントで印刷されます．

@defcv category class name

@defcvコマンドは，オブジェクト指向プログラミングで，クラスに関連 する変数に対する一般的な定義コマンドです．@defcvコマンドは三つの 引数をとります．定義している事柄のカテゴリ名，属するクラス，そしてその名 前です．このようにします．

@defcv {Class Option} Window border-pattern ... @end defcv

これは，Windowクラスのborder-patternクラスオプションの定義 の最初の行の書き方を説明しています．

テンプレートは以下の通りです．

@defcv category class name ... @end defcv

@defcvは変数索引に項目を作成します．

@defivar class name

@defivarコマンドは，オブジェクト指向プログラミングのインスタンス 変数に対する定義コマンドです．@defivarは`@defcv {Instance Variable} ...'と同じです．

テンプレートは以下の通りです．

@defivar class instance-variable-name body-of-definition @end defivar

@defivarは変数索引に項目を作成します．

@deftypeivar class data-type name

@deftypeivarコマンドは，オブジェクト指向プログラミングの型を付け られたインスタンス変数に対する定義コマンドです．それは，@defivar に，インスタンス変数の型を指定するためのdata-typeパラメータが付い たものに似ています．@deftypeivarは変数索引に項目を作成します．

@defop category class name arguments...

@defopコマンドは，オブジェクト指向プログラミングのメソッドに似た 構成要素に対する定義コマンドです．これらの構成要素は関数のように引数を取 りますが，オブジェクトの特定のクラスに関連付けされています．

例えば，メソッドとしてクラスに関連付けされているラッパー(wrappers) と呼ばれる概念を持つシステムもありますが，それは関数というよりマクロのよ うに動作します．@defop Wrapperをこれらの一つとしての記述に使用す ることが可能です．

メソッドとオペレーション(operations)を分けた方が便利なときもありま す．オペレーションをメソッドの詳述と考えることができます．このため，ウィ ンドウシステムは全てのウィンドウクラスがexposeと言う名前のメソッ ドを持つことを指定できます．我々は，このウィンドウシステムが一般的なウィ ンドウ上にexposeオペレーションを定義していると言っているのです． 特に，オペレーションは名前を持ち，引数のパターンも指定されています．全て のオペレーションを実装したメソッドは，オペレーションで使用されるアプリケー ションが実装したメソッドを知ることなくそれを行うので．同じ引数を受け入れ るようにする必要があります．

メソッドよりオペレーションを説明した方がより意味があることもよくあります． 例えば，ウィンドウアプリケーション開発者は，exposeオペレーション を知っている必要がありますが，与えられたウィンドウのクラスが，このオペレー ションを実装した独自のメソッドを持つかどうかを考慮する必要はありません． このオペレーションを記述するため以下のように書きます．

@defop Operation windows expose

@defopコマンドは，行の最初に書かれ，同じ行にオペレーションのカテ ゴリの全体的な名前，オペレーションクラスの名前，オペレーションの名前，そ して，存在する場合その引数を続けます．

テンプレートは以下の通りです．

@defop category class name arguments... body-of-definition @end defop

@defopは`expose on windows'のような項目を，関数索 引に作成します．

@deftypeop category class data-type name arguments...

@deftypeopコマンドは，オブジェクト指向プログラミングの型付のオペ レーションに対する定義コマンドです．それは@defopに，メソッドの戻 り値を指定するdata-typeパラメータを加えたものに似ています． @deftypeopは関数索引に項目を作成します．

@defmethod class name arguments...

@defmethodコマンドは，オブジェクト指向プログラミングのメソッドに 対する定義コマンドです．メソッドは特定のオブジェクトのクラスとそのサブク ラスのためのオペレーションを実装する関数のようなものです．

@defmethodは`@defop Method ...'と同じです．コマンドは 行の最初に書かれ，メソッドのクラス名，メソッド名，そして存在する場合はそ の引数が続きます．

例えば，以下のようにします．

@defmethod bar-class bar-method argument ... @end defmethod

これは，クラスbar-classのbar-methodと呼ばれるメソッドに対 する定義を説明しています．メソッドは引数を取ります．

テンプレートは以下の通りです．

@defmethod class method-name arguments... body-of-definition @end defmethod

@defmethodは，関数索引に`bar-method on bar-class' のような項目を作成します．

@deftypemethod class data-type name arguments...

@deftypemethodコマンドは，C++やJavaのようなオブジェクト指向の型 のある言語のメソッドのに対する定義コマンドです．それは， @defmethodコマンドにメソッドの戻り値を指定するための data-typeパラメータを追加したものに似ています．

15.4.6 データの型

データの型に対するコマンドには以下のものがあります．

@deftp category name attributes...

@deftpコマンドは，データの型に対する一般的な定義コマンドです．そ のコマンドは行の最初に書かれ，同じ行にカテゴリ，型の名前(intや floatのようなもの)，そして型のオブジェクトの属性名が続きます．こ のため，このコマンドをintやfloatを記述するために使用するこ とが可能で，その場合，カテゴリとしてdata typeを使用することも可能 でしょう．(データの型は，実行可能なオペレーションを決定する目的に対する， 特定のオブジェクトのカテゴリです．)

例えばLispでは，pairは特定のデータの型に名前を付け，その型のオブジェ クトはCARとCDRと呼ばれる二つのスロットを持ちます．pair の定義の最初の行を書く方法は以下のようになります．

@deftp {Data type} pair car cdr ... @end deftp

テンプレートは以下の通りです．

@deftp category name-of-type attributes... body-of-definition @end deftp

@deftpはデータの型の索引に項目を作成します．

15.5 定義を書くための慣習

@deffn，@defunやその他の定義コマンドの一つを使用し定義を 書くとき，forward-word関数に対するcount引数のように，意味を 示す引数の使用に注意してください．また，integerのように引数名が型 名を含んでいる場合，引数が実際にその型であるよう注意してください．

15.6 関数定義の見本

関数定義は，@defunと@end defunを使用します．関数名は @defunコマンドの直後に続き，同じ行にパラメータリストが続きます．

section `Calling Functions' in The GNU Emacs Lisp Reference Manualの 定義には以下のものがあります．

Function: apply function &rest arguments

applyはargumentsでfunctionを呼び出し，funcall に似ていますが，一点が異なります．argumentsの終りは， function に与えられる単一の引数ではなく引数のリストです．我々は， このリストが他の引数にappendされるとも言っています．

applyはfunction呼び出しの結果を返します．funcallのよ うに，functionはLisp関数やプリミティブ関数である必要があります．ス ペシャルフォームとマクロは，applyでは意味がありません．

(setq f 'list) => list (apply f 'x 'y 'z) error--> Wrong type argument: listp, z (apply '+ 1 2 '(3 4)) => 10 (apply '+ '(1 2 3 4)) => 10 (apply 'append '((a b c) nil (x y z) nil)) => (a b c x y z)

applyを使用した興味深い例は，mapcarの記述で見付かります．

Texinfoソースファイルでは，この例は以下のようになります．

@defun apply function &rest arguments
@code{apply}は@var{arguments}で@var{function}を呼び出し，
@code{funcall}に似ていますが，1点異なります．@var{arguments}の終り
は，@var{function}に与えられた単一の引数ではなく引数のリストです．我々
は，このリストが他の引数に@dfn{加えられる}とも言っています．

@code{apply}は@var{function}呼び出しの結果を返します．
@code{funcall}のように，@var{function}はLisp関数やプリミティブ関数
である必要があります．スペシャルフォームとマクロは，@code{apply}では
意味がありません．

@example
(setq f 'list)
    @result{} list
(apply f 'x 'y 'z)
@error{} Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
    @result{} 10
(apply '+ '(1 2 3 4))
    @result{} 10

(apply 'append '((a b c) nil (x y z) nil))
    @result{} (a b c x y z)
@end example

@code{apply}を使用した興味深い例は，@code{mapcar}の記述で見付かり
ます．
@end defun

このマニュアルでは，この関数はapplyの下のコマンドと変数索引にリス トアップされています．

通常の変数とユーザーオプションは，変数が引数を取らない以外，関数に対する ものに似た書式を使用し記述されます．