.\"
.\"	@(#) %FreeBSD: src/usr.bin/m4/m4.1,v 1.10.2.1 2000/12/08 15:13:48 ru Exp %
.\"
.\" $FreeBSD$
.\"
.Dd January 26, 1993
.Dt M4 1
.Os
.Sh 名称
.Nm m4
.Nd マクロ言語プロセッサ
.Sh 書式
.Nm
.Oo
.Fl D Ns Ar name Ns Op Ar =value
.Oc
.Op Fl U Ns Ar name
.Op Ar filename 
\|.\|.\|.
.Sh 解説
.Nm
ユーティリティは、さまざまな言語
(たとえば C, ratfor, fortran, lex, yacc など) のフロントエンドとして
利用できるマクロプロセッサです。
引数で指定されたファイルが指定された順に処理されます。
ファイルが指定されていないか、ファイル名が \`-\' なら
標準入力が読まれます。処理されたテキストは標準出力へ送られます。
.Pp
マクロの呼出しは name(argument1[, argument2, ...,] argumentN) の
形式を取っています。
.Pp
マクロ名とそれに続く開き括弧 `(' との間にはスペースがあってはいけません。
もしマクロ名の直後に開き括弧が続いていなければ引数なしのマクロ呼出しとして
処理されます。
.Pp
マクロ名として先頭はアルファベットまたはアンダースコアが、2 文字目以降は
英数字またはアンダースコアが使えます。
よって正しいマクロ名にマッチする正規表現は [a-zA-Z_][a-zA-Z0-9_]*
となります。
.Pp
マクロの引数のうちで、先頭のクォートされていない空白、タブ、
改行文字は無視されます。
文字列をクォートするためには、左、および右シングルクォートを使用して
ください (例: ` this is a string with a leading space')。
組み込みマクロ changequote を使ってクォート文字を変更することができます。
.Pp
オプションは以下の通りです:
.Bl -tag -width "-Dname[=value]xxx"
.It Fl D Ns Ar name Ns Oo
.Ar =value
.Oc
シンボル
.Ar name
の値を value (無指定時は NULL) と定義します。
.It Fl "U" Ns Ar "name"
シンボル
.Ar name
を未定義にします。
.El
.Sh 文法
.Nm
には以下に示す組み込みマクロが実装されています。
これらのマクロは再定義可能であり、その場合には元の定義は失われます。
特に記述のない限り戻り値は NULL です。
.Bl -tag -width changequotexxx
.It changecom
コメントの開始文字列と終了文字列を変更します。
デフォルトでは、ポンド記号 `#' と改行文字です。
引数を指定しなかった場合はコメント機能がオフになります。
設定できる文字列の長さは最大で 5 文字です。
.It changequote
第 1、第 2 引数をクォートシンボルとして定義します。
引数の最初の文字のみ使用されることに注意してください。
引数が与えられなかった場合にはデフォルトの左右シングルクォートに
設定されます。
.It decr
引数の値を 1 だけ減少させます。
引数は正しく数値を表現する文字列でなければなりません。
.It define
第 1 引数で指定した名前の新しいマクロを定義します。
定義内容は第 2 引数で与えます。
定義中での $n (n は 0 から 9 まで) は それぞれそのマクロに与えられる
第 n 引数に置換されます。$0 はマクロ名そのものです。
指定されなかった引数は NULL 文字列に置換されます。
また $# は引数の数を表し、$* はコンマで区切られた全引数になります。
$@ は $* と同様ですが、更なる置換が行われないように全部の引数が
クォートされます。
.It defn
各引数で指定されたマクロの定義内容をクォートして返します。
これはマクロ定義の名称変更 (組み込みマクロであっても) に利用できます。
.It divert
.Nm
には 10 本の出力キューが用意されています
(0 から 9 までの番号がついています)。
処理の最後に、全てのキューは番号順に連結されて最終的な出力を
生成するようになっています。
初期状態では出力キューは 0 番に設定されています。
divert マクロを使って新しい出力キューを選ぶことが出来ます
(divert に不正な引数を与えると出力が破棄されてしまいます)。
.It divnum
現在の出力キューの番号を返します。
.It dnl
改行文字を含めた行末までの入力文字を破棄します。
.It dumpdef
引数で指定した項目に関して、その名前と定義を出力します。
引数が与えられなかった場合は全てのマクロについて出力します。
.It errprint
第 1 引数を標準エラー出力ストリームへ出力します。
.It eval
第 1 引数を計算式とみなして 32-bit 幅の算術演算を用いて計算します。
演算子としては標準の C で用いられるもの、すなわち 3 項、
算術、論理、シフト、関係、ビットの各演算子、および括弧が
利用可能です。
また数値も C と同様に 8 進、10 進、16 進で記述できます。
第 2 引数で (もしあれば) 演算結果の基数を指定でき、
第 3 引数で (もしあれば) 演算結果の最小桁数を指定できます。
.It expr
eval の別名です。
.It ifdef
第 1 引数で指定した名前のマクロが定義されていれば第 2 引数を返し、
定義されていなければ第 3 引数を返します。
第 3 引数が省略されていた場合は、その値は NULL になります。
ちなみに `unix' という単語があらかじめ定義されています。
.It ifelse
第 1 引数が第 2 引数とマッチしたら第 3 引数を返します。
マッチしなかった場合、その 3 個の引数は捨てられて次の 3 引数を
用いて同様の検査を繰り返します。
この処理は引数がなくなるか あるいは 1 つだけ残るまで繰り返され、
どれにもマッチしなかった場合には その最後に残った引数または NULL
(引数がなくなった場合) が返されます。
.It include
第 1 引数で指定されたファイルの内容を返します。
ファイルが読み込めなかった場合にはエラーメッセージを出力して処理を
中断します。
.It incr
引数を 1 だけ増加させます。
引数は正しく数値を表現する文字列でなければいけません。
.It index
第 2 引数が、第 1 引数の中で、何文字目に出現するかを返します
(たとえば index(the quick brown fox jumped, fox) では 16 が返ります)。
第 2 引数が第 1 引数の中に含まれていなかった場合には -1 を返します。
.It len
第 1 引数の文字数を返します。余分な引数は無視されます。
.It m4exit
第 1 引数 (指定されなかった場合は 0) を終了コードとして即座に終了します。
.It m4wrap
入力が最後の EOF に達したときに、どのような動作を行うかを設定します。
一般には種々の後始末を行うマクロを設定します
(たとえば、m4wrap("cleanup(tempfile)") とすると他の全ての処理が終了した
後に cleanup マクロが呼び出されます)。
.It maketemp
第 1 引数の中の文字列 XXXXX を現在のプロセス ID に置換します。
その他の部分はそのままです。
これはユニークなテンポラリファイル名の生成に利用できます。
.It paste
第 1 引数で指定されたファイルの内容をマクロ処理を一切行わずに include
します。
もしファイルが読み込めない場合にはエラーメッセージを出力して処理を
中断します。
.It popdef
各引数へ pushdef されている定義を戻します。
.It pushdef
define と同様の引数をとってマクロを定義しますが元の定義をスタックへ
保存しておきます。
保存された定義は後で popdef で戻すことができます。
.It shift
第 1 引数を除いた全ての引数を返します。
残りの引数はクォートされてコンマで区切られます。
クォートすることによって以降の処理で置換が行われないようにしています。
.It sinclude
エラーが起きても無視される点を除いて include と同じです。
.It spaste
エラーが起きても無視される点を除いて paste と同じです。
.It substr
第 1 引数の文字列のうちの、第 2 引数で指定されるオフセットから始まり
第 3 引数で指定される文字数の範囲の部分文字列を返します。
第 3 引数が省略された場合は残りの文字列全てを返します。
.It syscmd
第 1 引数をシェルに渡します。戻り値はありません。
.It sysval
最後に実行した syscmd の戻り値を返します。
.It translit
第 1 引数の中の文字を、第 2 引数で指定された文字集合から第 3 引数で
指定された文字集合へ書き直します。ただし
.Xr tr 1
式の省略指定を用いることはできません。
.It undefine
第 1 引数で指定されたマクロを未定義にします。
.It undivert
指定された出力キュー (引数がない場合は全てのキュー) の内容を掃き出します。
.It unix
OS プラットフォームを調べるために予め定義されているマクロです。
.El
.Sh 作者
.An Ozan Yigit Aq oz@sis.yorku.ca
および
.An Richard A. O'Keefe Aq ok@goanna.cs.rmit.OZ.AU