.\"     @(#) $OpenBSD: m4.1,v 1.24 2002/04/18 18:57:23 espie Exp %
.\" %FreeBSD: src/usr.bin/m4/m4.1,v 1.26 2004/07/03 01:28:20 tjr Exp %
.\"
.\" $FreeBSD$
.\"
.Dd July 3, 2004
.Dt M4 1
.Os
.Sh 名称
.Nm m4
.Nd マクロ言語プロセッサ
.Sh 書式
.Nm
.Op Fl d Ar flags
.Op Fl t Ar name
.Op Fl gs
.Op Fl D Ar name Ns Op = Ns Ar value
.Op Fl U Ar name
.Op Fl I Ar dirname
.Op Ar
.Sh 解説
.Nm
ユーティリティは、さまざまな言語
(たとえば C, ratfor, fortran, lex, yacc など) のフロントエンドとして
利用できるマクロプロセッサです。
.Nm
ユーティリティは、標準入力から読み込みます。
また、処理結果のテキストを標準出力へ書き出します。
.Pp
マクロの呼び出しは
.Ic name Ns Pq Ar argument1 Ns Op , Ar argument2 , ... , argumentN
の
形式を取っています。
.Pp
マクロ名とそれに続く開き括弧
.Pq Ql \&(
との間にはスペースがあってはいけません。
もしマクロ名の直後に開き括弧が続いていなければ引数なしのマクロ呼び出しとして
処理されます。
.Pp
マクロ名として先頭はアルファベットまたはアンダスコアが、2 文字目以降は
英数字またはアンダスコアが使えます。
よって正しいマクロ名にマッチする正規表現は
.Dq Li [a-zA-Z_][a-zA-Z0-9_]*
となります。
.Pp
マクロの引数のうちで、先頭のクォートされていない空白、タブ、
改行文字
.Pq Ql \en
は無視されます。
文字列をクォートするためには、左、および右シングルクォートを使用して
ください (例: 
.Sq "\ this is a string with a leading space" )
。
組み込みマクロ
.Ic changequote
を使ってクォート文字を変更することができます。
.Pp
大抵の組み込みマクロは、引数がないと意味をなしませんので、
開き括弧が後に続かない場合、特別のものとして認識されません。
.Pp
オプションは以下の通りです:
.Bl -tag -width indent
.It Fl s
.Xr cpp 1
用に、
.Ic #line
ディレクティブを出力します。
.It Fl D Ar name Ns Op = Ns Ar value
シンボル
.Ar name
の値を value (無指定時は
.Dv NULL ) と定義します。
.It Fl U Ar name
シンボル
.Ar name
を未定義にします。
.It Fl I Ar dirname
include パスに
ディレクトリ
.Ar dirname
を追加します。
.It Fl d Ar flags
トレースフラグをセットします。
.Ar flags
引数は、以下の通りです:
.Pp
.Bl -tag -width indent -compact
.It Cm a
マクロの引数を表示します。
.It Cm c
マクロの展開を複数行で表示します。
.It Cm e
マクロの展開結果を表示します。
.It Cm f
ファイル名の場所を表示します。
.It Cm l
行数を表示します。
.It Cm q
引数と現在のクォートの結果を引用します。
.It Cm t
すべてのマクロをトレースします。
.It Cm x
マクロを展開する時に番号を付けます。
.It Cm V
すべてのオプションフラグをオンにします。
.El
.Pp
デフォルトでは、トレースは
.Cm eq
にセットしています。
.It Fl t Ar macro
.Ar macro
をトレーシングします。
.It Fl g
GNU-m4 互換モードを有効にします。
このモードでは
.Ic changequote
に 2 つの空のパラメータをつけることで
クォートの使用をやめられます。
.Ic translit
は、
単一の文字範囲 (例えば
.Li a-z )
を扱い、
正規表現で
.Xr emacs 1
のように動作します。
変換の数は無制限です。
.El
.Sh 文法
.Nm
ユーティリティには以下に示す組み込みマクロが実装されています。
これらのマクロは再定義可能であり、その場合には元の定義は失われます。
特に記述のない限り戻り値は NULL です。
.\" 原文 NULL -> null
.Bl -tag -width ".Ic changequote"
.It Ic builtin
指定した組み込みマクロを呼び出します。
名前が再定義されていたとしても名前の持つ本来の機能を呼び出します。
.It Ic changecom
コメントの開始文字列と終了文字列を変更します。
デフォルトでは、ポンド記号
.Pq Ql #
と改行文字です。
引数を指定しなかった場合はコメントシーケンスがリセットされます。
GNU モードの
.Nm
では、コメントはオフです。
設定できる文字列の長さは最大で 5 文字です。
.It Ic changequote
第 1、第 2 引数をクォートシンボルとして定義します。
シンボルは、長さ 5 文字以内にしてください。
引数が与えられなかった場合にはデフォルトの左右シングルクォートに
設定されます。
.It Ic decr
引数の値を 1 だけ減少させます。
引数は正しく数値を表現する文字列でなければなりません。
.It Ic define
第 1 引数で指定した名前の新しいマクロを定義します。
定義内容は第 2 引数で与えます。
定義中での
.Sq Li $ Ns Ar n
(
.Ar n
は 0 から 9 まで) は それぞれそのマクロに与えられる
第
.Ar n
引数に置換されます。
.Ql $0
はマクロ名そのものです。
指定されなかった引数は NULL 文字列に置換されます。
.\" 原文 NULL -> null
また
.Ql $#
は引数の数を表し、
.Ql $*
はコンマで区切られた全引数になります。
.Ql $@
は
.Ql $*
と同様ですが、更なる置換が行われないように全部の引数が
クォートされます。
.It Ic defn
各引数で指定されたマクロの定義内容をクォートして返します。
これはマクロ定義の名称変更 (組み込みマクロであっても) に利用できます。
.It Ic divert
.Nm
には 10 本の出力キューが用意されています
(0 から 9 までの番号がついています)。
処理の最後に、全てのキューは番号順に連結されて最終的な出力を
生成するようになっています。
初期状態では出力キューは 0 番に設定されています。
.Ic divert
マクロを使って新しい出力キューを選ぶことが出来ます
(
.Ic divert
に不正な引数を与えると出力が破棄されてしまいます)。
.It Ic divnum
現在の出力キューの番号を返します。
.It Ic dnl
改行文字を含めた行末までの入力文字を破棄します。
.It Ic dumpdef
引数で指定した項目に関して、その名前と定義を出力します。
引数が与えられなかった場合は全てのマクロについて出力します。
.It Ic errprint
第 1 引数を標準エラー出力ストリームへ出力します。
.It Ic esyscmd
その最初の引数をシェルへ渡し、シェルの標準出力を返します。
シェルはその標準入力および標準エラー出力を
.Nm
と共有することに注意してください。
.It Ic eval
第 1 引数を計算式とみなして 32-bit 幅の算術演算を用いて計算します。
演算子としては標準の C で用いられるもの、すなわち 3 項、
算術、論理、シフト、関係、ビットの各演算子、および括弧が
利用可能です。
また数値も C と同様に 8 進、10 進、16 進で記述できます。
第 2 引数で (もしあれば) 演算結果の基数を指定でき、
第 3 引数で (もしあれば) 演算結果の最小桁数を指定できます。
.It Ic expr
.Ic eval
の別名です。
.It Ic ifdef
第 1 引数で指定した名前のマクロが定義されていれば第 2 引数を返し、
定義されていなければ第 3 引数を返します。
第 3 引数が省略されていた場合は、その値は
.Dv NULL
になります。
ちなみに
.Ic unix
という単語があらかじめ定義されています。
.It Ic ifelse
第 1 引数が第 2 引数とマッチしたら第 3 引数を返します。
.Ic マッチしなかった場合 (ifelse)、
その 3 個の引数は捨てられて次の 3 引数を
用いて同様の検査を繰り返します。
この処理は引数がなくなるか あるいは 1 つだけ残るまで繰り返され、
どれにもマッチしなかった場合には その最後に残った引数または
.Dv NULL
(引数がなくなった場合) が返されます。
.It Ic include
第 1 引数で指定されたファイルの内容を返します。
指定通りの名前のファイルが見つからなかった場合は、
include パスを探します。
最初にまず
コマンドラインで
.Fl I
指定されたディレクトリを順に、
次に
環境変数
.Ev M4PATH
に設定されたコロン区切りのディレクトリリストを順に探します。
ファイルを include できない場合は、
エラーメッセージを表示して異常終了します。
.It Ic incr
引数を 1 だけ増加させます。
引数は正しく数値を表現する文字列でなければいけません。
.It Ic index
第 2 引数が、第 1 引数の中で、何文字目に出現するかを返します
(たとえば
.Fn index "the quick brown fox jumped" fox
では 16 が返ります)。
第 2 引数が第 1 引数の中に含まれていなかった場合には 
.Ic index
は -1 を返します。
.It Ic indir
第 1 引数として渡される項目のマクロを間接的に呼びます。
それ以降は、第 1 引数のマクロに対する引数です。
.It Ic len
第 1 引数の文字数を返します。余分な引数は無視されます。
.It Ic m4exit
第 1 引数 (指定されなかった場合は 0) を終了コードとして即座に終了します。
.It Ic m4wrap
入力が最後の
.Dv EOF
に達したときに、どのような動作を行うかを設定します。
一般には種々の後始末を行うマクロを設定します
(たとえば、
.Fn m4wrap cleanup(tempfile)
) とすると他の全ての処理が終了した
後に
.Ic cleanup
マクロが呼び出されます)。
.It Ic maketemp
第 1 引数の中の文字列
.Dq Li XXXXX
を現在のプロセス ID に置換します。
その他の部分はそのままです。
これはユニークなテンポラリファイル名の生成に利用できます。
.It Ic paste
第 1 引数で指定されたファイルの内容をマクロ処理を一切行わずに include
します。
もしファイルが読み込めない場合にはエラーメッセージを出力して処理を
中断します。
.It Ic patsubst
文字列のうち、正規表現にマッチする部分が置換文字列で置き換えられます。
通常は次の代入規則が適用されます:
アンパサンド
.Pq Ql &
は、正規表現にマッチした文字列で置き換えられます。
文字列
.Sq \e Ns Ar #
.Ns ( Ar #
は数値)
は、一致する後方参照と置き換えられます。
.It Ic popdef
各引数へ
.Ic pushdef
されている定義を戻します。
.It Ic pushdef
.Ic define
と同様の引数をとってマクロを定義しますが元の定義をスタックへ
保存しておきます。
保存された定義は後で
.Ic popdef
で戻すことができます。
.It Ic regexp
正規表現に基づき、文字を見つけます。
第 2 引数までの場合は
最初にマッチする文字位置を、
マッチする文字がない場合は -1 を返します。
第 3 引数がある場合、
その中に含まれるパターンを置き換えた文字列を返します。
.It Ic shift
第 1 引数を除いた全ての引数を返します。
残りの引数はクォートされてコンマで区切られます。
クォートすることによって以降の処理で置換が行われないようにしています。
.It Ic sinclude
エラーが起きても無視される点を除いて
.Ic include
と同じです。
.It Ic spaste
エラーが起きても無視される点を除いて
.Ic paste
と同じです。
.It Ic substr
第 1 引数の文字列のうちの、第 2 引数で指定されるオフセットから始まり
第 3 引数で指定される文字数の範囲の部分文字列を返します。
第 3 引数が省略された場合は残りの文字列全てを返します。
.It Ic syscmd
第 1 引数をシェルに渡します。戻り値はありません。
.It Ic sysval
最後に実行した
.Ic syscmd
の戻り値を返します。
.It Ic traceon
引数がある場合はそのマクロの展開をトレースをオンにします。
引数がない場合はすべてのマクロをトレースをオンにします。
.It Ic traceoff
引数がある場合はそのマクロの展開をトレースをオフにします。
引数がない場合はすべてのマクロをトレースをオフにします。
.It Ic translit
第 1 引数の中の文字を、第 2 引数で指定された文字集合から第 3 引数で
指定された文字集合へ書き直します。ただし
.Xr tr 1
式の省略指定を用いることはできません。
.It Ic undefine
引数で指定されたマクロを未定義にします。
.It Ic undivert
指定された出力キュー (引数がない場合は全てのキュー) の内容を掃き出します。
.It Ic unix
OS プラットフォームを調べるために予め定義されているマクロです。
.It Ic __line__
現在のファイルの行番号を返します。
.It Ic __file__
現在のファイル名を返します。
.El
.Sh 診断
.Ex -std
.Pp
入力ファイルから終了状態を変更するために、
.Ic m4exit
マクロを使用することができます。
.Sh 互換性
.Nm
ユーティリティは、GNU-m4 から加えられた少々の拡張に加えて、
.St -susv2
に追従しています。
フラグ
.Fl I , d , t
は非標準です。
.Pp
トレースと
.Ic dumpdef
の出力フォーマットは、
どの標準でも規定されていませんので
変更される可能性があります。
これらに依存するべきではありません。
現在のトレース出力フォーマットは、
.Nm autoconf
が機能できるよう GNU-m4 に基づいて厳密に作成されています。
.Pp
移植性のためには、
.Ic builtin ,
.Ic esyscmd ,
.Ic expr ,
.Ic indir ,
.Ic paste ,
.Ic patsubst ,
.Ic regexp ,
.Ic spaste ,
.Ic unix ,
.Ic __line__ ,
および
.Ic __file__
のマクロは、使用しないほうがよいです。
.Pp
他の多くの
.Nm
の実装では、
すべての組み込みマクロは引数なしでも展開されます。
.Pp
他の多くの
.Nm
の実装は、
バッファサイズに関して、きびしい制限があります。
.Sh 規格
.Nm
ユーティリティは
.St -p1003.1-2001
に適合します。
.Sh 歴史 
.Nm
コマンドは、PWB UNIX から登場しました。
.Sh 作者
.An -nosplit
.An Ozan Yigit Aq oz@sis.yorku.ca
および
.An Richard A. O'Keefe Aq ok@goanna.cs.rmit.OZ.AU .
.br
.An Marc Espie Aq espie@cvs.openbsd.org
による GNU-m4 互換性拡張
.Sh バグ
.Nm
ユーティリティは、マルチバイト文字を認識しません。