名称

m4 — マクロ言語プロセッサ

書式

m4	[ -gPs][ -Dname[ = value]][ -d flags][ -I dirname][ -o filename][ -t macro][ -Uname][ file ...]

解説

m4 ユーティリティは、あらゆる言語 (例えば、C、ratfor、fortran、lex と yacc) のフロントエンドとして使用することができるマクロプロセッサです。入力ファイルが与えられないなら、 m4 は、標準入力から読み込み、そうでなければ、コマンド行で指定されたファイルは、与えられた順序で処理されます。入力ファイルは、m4 のファイルが、パスまたは標準入力を意味する単一のダッシュ (‘-’) を含んでいる通常ファイルを指定できます。 m4 は、他の方法で指定されなければ、標準出力に処理されたテキストを書き込みます。

マクロの呼び出しは、 name(argument1[, argument2, ..., argumentN]) の形式です。

マクロ名と開き括弧 (‘(’) に空白が続いてはいけません。マクロ名に開き括弧が続かないなら、それは、引数なしとして処理されます。

マクロ名は、先導する英字または下線から成り、英数字または下線文字が続きます、例えば、有効なマクロ名は、パターン“[a-zA-Z_][a-zA-Z0-9_]*”にマッチします。

マクロへの引数において、先導する引用されていない空白、タブと改行 (‘\n’) 文字は、無視されます。文字列を引用するために、左と右のシングルクォート、

(例えば、‘ this is a string with a leading space’) を使用します。 changequote 組み込みマクロで引用文字を変更することができます。

ほとんどの組み込みマクロは、引数なしでは意味をなさず、したがって、開き括弧が続かないとき、特別のものとして認識されません。

オプションは、次の通りです:

-D name[ = value]

ある値 (または NULL) を持つためにシンボル name を定義します。

-d flags

トレースフラグを設定します。 flags は、次を保持します:

a

マクロの引数を印刷します。

c

いくつかの行に渡ってマクロの展開を印刷します。

e

マクロの展開の結果を印刷します。

f

ファイル名の位置を印刷します。

l

行番号を印刷します。

q

現在の引用で引数と拡張を引用します。

t

すべてのマクロをトレースするようにして開始します。

x

マクロの展開に番号付けをします。

V

すべてのオプションをオンにします。

デフォルトで、トレースは、“eq”に設定されます。

-g

GNU-m4 互換モードを有効にします。このモードで、translit は、単一の文字範囲 (例えば、a-z) を扱い、正規表現は、emacs 振る舞いを模倣し、複数の m4wrap 呼び出しは、スタックとして扱われ、転換 (diversion) の数は、無制限で、マクロ定義のための空の名前が許可され、 eval は、‘0rbase:value’を理解します。

-I dirname

インクルードパスにディレクトリ dirname を追加します。

-o filename

filename にトレース出力を送ります。

-P

すべての組み込みマクロの前に‘m4_’を付けます。例えば、 define と記述する代わりに m4_define を使用します。

-s

cpp(1) に適している、行同期デイレクティブをに出力します。

-t macro

macro に対してトレースをオンにします。

-U name

シンボル name を未定義とします。

構文

m4 は、次の組み込みマクロを提供しています。それらは、本来の意味を失って、再定義することもできます。返り値は、特に指定のない限りヌル文字 (null) です。

builtin( name)

上書き可能な再定義される、その name で組み込みマクロを呼び出します。

changecom( startcomment, endcomment)

コメントの開始とコメントシーケンスの終りを変更します。コメントシーケンスは、長さ 5 文字以内です。デフォルト値は、ハッシュ記号 (#) と改行文字です。

# This is a comment

引数なしで、コメントは、オフにされます。 1 つの単一引数で、終りのコメントシーケンスは、改行文字に設定されます。

changequote( beginquote, endquote)

開き引用と閉じ引用シーケンスを定義します。引用シーケンスは、長さ 5 文字以内です。デフォルト値は、バッククォート文字 (`) とクォート文字 (') です。

`Here is a quoted string'

引数なしで、デフォルトの引用が復旧されます。 1 つの単一引数で、閉じ引用シーケンスは、改行文字に設定されます。

decr( arg)

引数 arg を 1 だけ減少させます。引数 arg は、有効な数値の文字列でなければなりません。

define( name, value)

最初の引数 name によって指定された新しいマクロを 2 番目の引数 value を持つように定義します。それぞれ‘$n’が現れると (ここで、 n は、0 から 9) それは、 n 番目の引数によって置き換えられます。‘$0’は、呼び出されたマクロの名前です。未定義の引数は、空の文字列で置き換えられます。‘$#’は、引数の数で置き換えられます。‘$*’は、コンマで区切られたすべての引数で置き換えられます。‘$@’は、‘$*’と同じですが、すべての引数は、さらなる展開に対して引用されます。

defn( name, ...)

各引数のために引用された定義を返します。マクロ定義 (組み込みマクロさえ) の名前を変更するために、これを使用することができます。

divert( num)

(0 から 9 と番号が付けられた) 10 個の出力キューがあります。 m4 の処理の終わりで、最終の出力を作成するために番号順にすべてのキューを連結します。最初の出力キューは、0 です。 divert マクロによって、利用者は、新しい出力キュー (divert に不正な引数を渡すと、出力は、廃棄されます) を選択することができます。

divnum

現在の出力キュー番号を返します。

dnl

次の改行を含んで終りまでの入力文字を廃棄します。

dumpdef( name, ...)

指定された項目、または引数が渡されないなら、すべての名前と定義を印刷します。

errprint( msg)

標準エラー出力ストリームに最初の引数を印刷します。

esyscmd( cmd)

最初の引数をシェルに渡し、シェルの標準出力を返します。シェルは、その標準入力と標準エラーを m4 と共有することに注意してください。

eval( expr)

32 ビットの算術を使用して、演算式として最初の引数を計算します。演算子は、標準 C の 3 項演算子、算術演算子、論理演算子、シフト演算子、関係演算子、ビット演算子と括弧演算子です。利用者は、C のような 8 進数、10 進数と 16 進数を指定することができます。 2 番目の引数 (があるなら) は、結果のための基数を指定し、 3 番目の引数 (があるなら) は、結果の最小桁数を指定します。

expr( expr)

これは、 eval の別名です。

format( formatstring, arg1, ...)

ある意味、 printf(3) に似た arg1 と続く引数で置き換えられるエスケープシーケンスがある formatstring を返します。この組み込みマクロは、GNU-m4 互換モードでのみ利用可能であり、実装されたパラメータのみは、次の autoconf 互換のためにあります: 左のパディングのフラグ、オプションのフィールドの幅、最大のフィールドの幅、 * 指定のフィールドの幅、そして %s と %c データタイプです。

ifdef( name, yes, no)

最初の引数によって指定されたマクロが定義されているなら、2 番目の引数を返し、そうでなければ、3 番目の引数を返します。 3 番目の引数がないなら、値は、 NULL です。単語“unix”は、あらかじめ定義されています。

ifelse( a, b, yes, ...)

最初の引数 a が 2 番目の引数 b にマッチするなら、 ifelse() は、3 番目の引数 yes を返します。マッチが失敗するなら、3 つの引数は、廃棄され、次の 3 つの引数は、 0 または 1 つの引数が残るまで、使用され、他のマッチが見つからなかったなら、この最後の引数または NULL のいずれかが返されます。

include( name)

最初の引数で指定されたファイルの内容を返します。いつものファイルが見つからないなら、次の include パスを調べます: ディレクトリのコロンで分離されたリストとして、最初に、コマンド行で -I で指定されたディレクトリ、次に環境変数 M4PATH で指定されたディレクトリ。 include は、ファイルをインクルードできないなら、エラーメッセージで異常終了します。

incr( arg)

引数を 1 だけ増加させます。引数は、有効な数値の文字列でなければなりません。

index( string, substring)

最初の引数の 2 番目の引数のインデックス (例えば、 index(the quick brown fox jumped, fox) は、16 を返します) を返します。 2 番目の引数のインデックスが見つからないなら、-1 を返します。

indir( macro, arg1, ...)

名前が最初の引数として渡されるマクロを間接的に呼び出します。残りの引数は、最初に引数として、次は 2 番目の引数として ...。

len( arg)

最初の引数の文字の数を返します。余分な引数は、無視されます。

m4exit( code)

最初の引数によって指定された返り値 (引数がなければ、0) で直ちに終了します、

m4wrap( todo)

最終の EOF で起こることを定義することができます、通常、クリーンアップの目的 (例えば、 m4wrap("cleanup(tempfile)") によって、マクロのクリーンアップは、他のすべての処理が終わった後に呼び出されます)。

m4wrap() への複数の呼び出しは、最終の EOF の順に挿入されます。

maketemp( template)

mkstemp と同様です。

mkstemp( template)

最初の引数で mkstemp(3) を呼び出し、修正された文字列を返します。ユニークな一時ファイル名を作成するために、これを使用することができます。

paste( file)

マクロの処理なしで最初の引数によって指定されたファイルの内容をインクルードします。ファイルをインクルードすることができないなら、エラーメッセージで異常終了します。

patsubst( string, regexp, replacement)

replacement 文字列で string 文字列の正規表現を置換します。通常の置換パターンは、次を適用します: アンパサンド (‘&’) は、正規表現とマッチする文字列と置き換えられます。文字列‘\#’、(ここで‘#’は、数字) は、対応する後方参照によって置き換えられます。

popdef( arg, ...)

各引数の pushdef された定義を復旧します。

pushdef( macro, def)

define と同じ引数を取りますが、 popdef() によって後で検索されるためにスタックに定義を保存します。

regexp( string, regexp, replacement)

string 文字列で正規表現を見つけます。それ以上引数が与えられないなら、最初のマッチした位置を返します、マッチしなければ、-1 を返します。 3 番目の引数が提供されるなら、置換されたサブパターンで replacement 文字列を返します。

shift( arg1, ...)

最初の引数を除いて、すべてを返します、残りの引数は、中間のコンマで引用され押し返されます。引用は、続いて行なわれる余分なスキャンの影響を無効にします。

sinclude( file)

あらゆるエラーを無視することを除いて、 include と同様です。

spaste( file)

あらゆるエラーを無視することを除いて、 paste() と同様です。

substr( string, offset, length)

2 番目の引数によって指定されたオフセットから始めて、 3 番目の引数によって指定された長さの部分文字列を返します。 3 番目の引数がが存在しないなら、文字列の残りを返します。

syscmd( cmd)

最初の引数をシェルに渡します。何も返されません。

sysval

最後の syscmd からの返り値を返します。

traceon( arg, ...)

与えられた引数のためのマクロ展開のトレースを有効にし、引数が与えられないなら、すべてのトレースを有効にします。

traceoff( arg, ...)

与えられた引数のためのマクロ展開のトレースを無効にし、引数が与えられないなら、すべてのトレースを無効にします。

translit( string, mapfrom, mapto)

最初の引数の (複数の) 文字を 2 番目の引数によって与えられたセットから、 3 番目の引数によって与えられたセットに変換します。 tr(1) スタイルの略語を使用することはできません。

undefine( name1, ...)

引数によって指定されたマクロのための定義を削除します。

undivert( arg, ...)

指定された出力キュー (または、引数がなければ、すべてのキュー) をフラッシュします。

unix

OS のプラットフォームをテストするためのあらかじめ定義されたマクロ。

__line__

現在のファイルの行番号を返します。

__file__

現在のファイルの名前を返します。

終了ステータス

The m4 utility exits 0 on success, and >0 if an error occurs.

ただし、 m4exit マクロは、終了ステータスを修正することができることに注意してください。

規格

m4 ユーティリティは、ほとんど IEEE Std 1003.1-2008 (“POSIX.1”) 仕様に準拠しています。

フラグ[ -dgIot]とマクロ builtin, esyscmd, expr, format, indir, paste, patsubst, regexp, spaste, unix, __line__ と __file__ は、その仕様に対して拡張されています。

maketemp は、 mkstemp の同意語であるはずですが、代りに、安全でないテンポラリファイル名前を生成する関数です。変更は、既知の互換性の問題を引き起こしません。

トレースと dumpdef の出力形式は、あらゆる標準で明記されていません、変更されそうで、依存するべきではありません。トレースの現在の形式は、 autoconf が動作することを可能にするために gnu-m4 で厳密にモデル化されています。

組み込みの pushdef と popdef は、スタックとしてマクロ定義を扱います。しかしながら、 define は、未定義の方法でスタックと情報をやりとりします。この実装で、 define は、最も上位の定義のみを置き換えます。他の実装は、代わりのスタックのすべての定義を消すかもしれません。

すべての組み込みマクロは、他の多くの m4 の引数なしで拡張を行います。

他の多くの m4 は、バッファサイズに関してひどいサイズ制限をしています。

作者

Ozan Yigit <oz@sis.yorku.ca>と Richard A. O'Keefe <ok@goanna.cs.rmit.OZ.AU>.

マーク Espie<espie@cvs.openbsd.org>による GNU-m4 互換性の拡張は、 Marc Espie <espie@cvs.openbsd.org>によります。