readconf
1.6
設定ファイル読み込みモジュール
|
readconf モジュールは、 Unix 系のプログラムで使用される設定ファイルを読み込むための、 関数 readconf() と構造体 RCConfItem などを提供します。
読み込み中にエラーが発生した場合、途中で停止しません。 発生したエラーの情報を、エラー情報構造体 RCError の配列 RCRaisedErrors に格納します。
設定ファイルは、次のような定義式の行の集まりです。
シャープ記号 (#
) で始まるコメントを書くことも出来ます。
値の型は、読み込み時にアプリケーションが指定します。 例えば Item = 3.14
と記述しても、 アプリケーションが文字列型で読み込むように指定した場合は、 文字列として読み込まれます。 また、整数型と指定すれば型違いエラーが発生します。
文字列型を定義する場合は、引用符で囲むことができます。 両端の引用符は読み込み時に取り除かれます。
文字列は引用符で囲む必要はありませんが、 その場合コメント開始文字 #
を含めることができません。 コメント開始文字 #
を含める場合は、 文字列の両端を引用符で囲んでください。
なお、文字列型の定義中にエスケープ文字を使用することは出来ません。 したがって文字列中に改行文字を入力する方法はありません。
以下は設定ファイルの記述例です。
readconf() の使い方は、次のような手順になります。
設定項目構造体配列はグローバル変数として定義するとよいでしょう。
配列を定義する際は初期値として、項目名、型、 デフォルト値を与えます。 デフォルト値は値を読み込めなかった時に使用されます。 配列を定義する際は文字列として与えますが、 readconf() 実行時に指定した型に変換されます。
オプションで、読み込んだ値を検証する関数のアドレスを登録することも出来ます。 この検証関数は値を読み込んだ時に呼び出されます。 値が適正だったら true を、適正でなければ false を返すように定義してください。 false が返ると読み込みエラーが発生し、項目の値はデフォルト値が設定されます。
もう一つのオプションとして、 読み込んだ文字列を数値に変換する関数のアドレスを登録することも出来ます。 この変換関数は、整数または実数型として定義された項目の値を文字列として読み込んだ時に、 検証関数より先に呼び出されます。 引数で渡された文字列を数値に変換して、 変換が成功したら true を、変換できなかったら false を返すように定義してください。 false が返ると読み込みエラーが発生し、項目の値はデフォルト値が設定されます。
以下の配列の定義例では、8つの設定項目を定義しています。 また、配列の各項目に対応するインデックスも列挙型として定義しています。
項目名は、文字列で指定します。 設定ファイルを読み込む際には、大文字と小文字は無視されるので、 同じ名前を指定しないように注意してください。
項目名に使用可能な文字は、空白文字とコメント開始文字 (#) と 等号記号 (=) を除く文字です。例えば英数字や、 マイナス記号 (-) や、ドット (.) などを使用することができます。
型に指定できるのは、次の 4 つです。
型 | シンボル |
---|---|
文字列 | RCValueTypeString |
整数(long) | RCValueTypeInteger |
実数(double) | RCValueTypeReal |
真偽値(bool) | RCValueTypeBool |
真偽値は、 true/false もしくは yes/no で表される文字列として 設定ファイル中に記述できます。 (ただし引用符では囲みません。)
デフォルト値は、設定ファイルに指定した項目名が定義されていない場合や、 設定ファイルを読み込めなかった場合に値に設定されます。
型が整数型や実数型であっても文字列で指定します。
読み込んだ値を検証するための関数へのポインタを登録します。
検証関数は、登録した項目の値を読み込んだ時に呼び出されます。 プロトタイプ宣言は次のようになります。
name
には、読み込んだ値を設定する項目の名前が渡されます。type
には、読み込んだ値の型が渡されます。value
には、読み込んだ値が渡されます。引数 name
と type
に渡されるのは、 検証関数を登録した項目の名前と型ですので、 検証関数の中で名前と型をチェックする必要はないでしょう。 しかし、もし同じ検証関数を別の複数の項目に登録するのであれば、 これらの引数を使って区別することができます。
検証関数は、値が適正だったら true を、 適正でなければ false を返すように定義してください。 false が返ると readconf() は読み込みエラーを発生させ、 項目の値にはデフォルト値を設定します。
読み込んだ文字列を変換するための関数へのポインタを登録します。
変換関数は、整数型もしくは実数型の項目の値を読み込んだ時に、 検証関数より前に呼び出されます。 プロトタイプ宣言は次のようになります。
name
には、読み込んだ値を設定する項目の名前が渡されます。type
には、読み込んだ値を変換する型が渡されます。string
には、読み込んだ値の文字列が渡されます。value
には、変換した値を格納するための変数へのポインタが渡されます。引数 name
と type
に渡されるのは、 変換関数を登録した項目の名前と型ですので、 変換関数の中でこれらをチェックする必要はないでしょう。 しかし、もし同じ変換関数を複数の項目に登録するのであれば、 これらの引数を使って区別することができます。
変換関数は、値を変換できたら true を、 変換できなかったら false を返すように定義してください。 false が返ると readconf() は読み込みエラーを発生させ、 項目の値にはデフォルト値を設定します。
readconf() を呼び出す場合は、設定項目構造体配列のアドレス、 配列の要素数、設定ファイルのパス名を指定します。
配列の要素数は、上の定義例のように、 列挙型としてインデックスを定義した最後に、 要素数も定義すると便利です。 また、配列の要素数を算出する ELEMENTSOF() マクロを定義してありますので、 こちらを使うことも出来ます。
エラー情報構造体配列 RCRaisedErrors には、 設定ファイル読み込み時に発生したエラー情報が格納されます。 発生したエラー情報の数、すなわち配列の要素数は RCNumRaisedErrors に格納されます。
エラー情報構造体配列を解放するには、 RCFreeRaisedErrors() を使用します。
設定項目構造体配列には、 readconf() によって読み込まれた値が メンバ RCConfItem.value に設定されます。 RCConfItem.value は共用体 RCConfValue で、 RCConfItem.type で指定された型に対応したメンバに値が設定されます。 型とメンバの対応は次のようになります。
型 | シンボル | メンバ |
---|---|---|
文字列 | RCValueTypeString | string |
整数(long) | RCValueTypeInteger | integer |
実数(double) | RCValueTypeReal | real |
真偽値(bool) | RCValueTypeBool | boolean |