関数の説明では、まず説明対象の関数名が記載されます。続いて同じ行に、引数名の一覧が列挙されます。これらの名前は、説明本文においても引数の値を表すものとして用いられます。
引数リストにキーワード &optional
が現れることは、それ以降の引数を省略できることを示します(省略された引数のデフォルト値は nil
です)。関数を呼び出す際に &optional と記述しないでください。
キーワード &rest(直後に単一の引数名が続く必要があります)は、その後に任意の数の引数が続くことができることを示します。&rest
に続く単一の引数名は、関数に渡された残りのすべての引数のリストを値として受け取ります。関数を呼び出す際に &rest と記述しないでください。
架空の関数 foo の説明は以下の通りです:
関数 foo は、integer2 から integer1 を引き、その結果に残りのすべての引数を加算します。integer2 が指定されていない場合は、デフォルトで数値 19 が使用されます。
(foo 1 5 3 9)
⇒ 16
(foo 5)
⇒ 14
より一般的に、
(foo w x y...) ≡ (+ (- x w) y...)
慣例として、名前に型名が含まれる引数(例:integer、integer1、buffer)は、その型であると想定されます。型の複数形(buffersなど)は、多くの場合、その型のオブジェクトのリストを意味します。objectという名前の引数は、任意の型である可能性があります。(Emacsのオブジェクト型の一覧については、Lispデータ型を参照してください。)それ以外の形式の名前を持つ引数(例:new-file)は、その関数固有のものです。関数にドキュメント文字列がある場合は、引数の型がそこに記述されているはずです(ドキュメントを参照してください)。
&optional および &rest によって修飾される引数のより詳細な説明については、ラムダ式を参照してください。
コマンド、マクロ、および特殊形式の記述形式は同一ですが、「Function」という語がそれぞれ「Command」、「Macro」、または「Special Form」に置き換えられます。コマンドは単に対話的に呼び出せる関数であり、マクロは引数を関数とは異なる方法で処理しますが(引数は評価されません)、提示形式は同様です。
マクロや特殊形式の記述では、任意引数や繰り返し引数を指定するために、より複雑な記法が用いられます。これは、引数リストをより複雑な方法で個別の引数に分割できるためです。‘[optional-arg]’はoptional-argが任意であることを意味し、‘repeated-args…’は0個以上の引数を表します。複数の引数をさらに階層的なリスト構造にグループ化する場合には、括弧が使用されます。以下に例を示します。
この仮想的な特殊形式は、body形式を実行し、その後各反復で変数varをインクリメントするループを実装しています。最初の反復では変数の値はfromとなり、それ以降の反復では1ずつ(またはincが指定されている場合はその値だけ)インクリメントされます。varがtoと等しい場合、bodyを実行する前にループを終了します。以下に例を示します:
(count-loop (i 0 10) (prin1 i) (princ " ") (prin1 (aref vector i)) (terpri))
from と to が省略されている場合、ループ開始前に
var が nil にバインドされ、反復処理の開始時に
var が nil
以外であればループを終了します。以下に例を示します。
(count-loop (done)
(if (pending)
(fixit)
(setq done t)))
この特殊な形式では、引数 from と to は省略可能ですが、両方が指定されているか、あるいは両方が省略されている必要があります。これらが指定されている場合、inc も任意で指定できます。これらの引数は、形式の残りのすべての要素を含む body と区別するため、引数 var とともにリストにまとめられています。