セクションファイル (Section file, secfile)は、Freeciv がデータを保存するファイルの標準形式です。
ルールセットなどのファイルは、この INI に似た形式で保存され、ディスク容量を節約するために圧縮されることがあります。
ソースコードでは、secfile 読み取りのメインフロントエンドは utility/registry_ini.[ch]
にあり、このマニュアルの大部分はコメントからコピーされています。
空白とコメント[]
- 空白行は無視されます。
- 最初の非空白文字が ';' である行も無視されます。 (コメント行)
- オプションで「#」をコメントに使用することもできます。
各行の形式[]
インクルード[]
*include "filename"
指定されたファイルをその時点でインクルードします。
(「*」は行の最初の文字でなければなりません。)
ファイルは、FREECIV_DATA_PATH
を調べることによって見つかります。 有限回の再帰インクルードが許可されます。
セクション名[]
[name]
の行は、その名前のセクションの開始を示します。ファイル内の最初の非コメント行はこの形式でなければなりません。 括弧内のスペースは名前に含まれますが、この機能 (?) はおそらく使用すべきではありません。セクションを分割して複数個所で表記することは自由ですが、このセクションを利用する関数がファイルを読むとき、後に同名のセクションが見つかった場合は残りのコードを破棄します (これは現在 [scenario]
セクションのみを制限しています)。
値と型[]
セクション内では、各行は次のいずれかの形式になります。 指定された名前の文字列、負の整数、正の整数、実数、ブール値の真と偽が利用できます。
subname = "stringvalue" subname = -digits subname = digits subname = ([+-])?digits.(digits)? subname = TRUE sunname = FALSE
これらのエントリは、次の関数で「sectionname.subname」として参照されます。
セクション名にドット ('.') を含めないでください。
サブネームに含むことはできますが、特別な意味はありません。
正式には、セクション名とエントリ名は英数字または _.,-[]
のいずれかで構成されますが、原則として文字とアンダースコアのみを使用してください。
等号の前後に任意の空白を入れることができます。
等号の後に (前には不可) 改行を入れることができます。
エスケープ[]
バックスラッシュは、文字列内のエスケープ文字です (二重引用符で囲まれた文字列内のみです)。 認識されるエスケープは、\n
、\\
、および \"
です。
その他の \<char>
は、<char>
として扱われます。
行末のバックスラッシュは改行文字を削除します ($...$-strings または *...*-files 内であっても)。
Lua スクリプトの script.code
エントリでよく使用される文字列 $something$ の代替構文があります。これは、引用符をエスケープする必要がなく、 Lua は \ 自体を扱います。
string型[]
- Gettext マーキング: 次のように文字列を囲むことができます。
foo = _("文字列値")
- レジストリはこれらの余分なマーキングを無視しますが、これは gettext ツールを介して翻訳する文字列をマーキングするのに役立ちます。
- 複数行の文字列: 文字列には改行を埋め込むことができます。
foo = _(" これは 複数行にわたる文字列です ")
- これは以下と同等です:
foo = _("\nこれは\n複数行にわたる文字列です\n")
- 末尾の二重引用符の位置を間違えると、ファイルの読み取りでエラーが発生する可能性があることに注意してください。
- ファイルから読み取る文字列: ファイルは文字列値として読み取ることができます。
foo = *filename.txt*
vector型[]
エントリには、コンマで区切られた複数の値を含めることができます。
foo = 10, 11, "x"
これらは、「foo」、「foo,1」、および「foo,2」という名前でアクセスされます (上記のようにセクション接頭辞付き)。 したがって、上記は次と同等です。
foo = 10 foo,1 = 11 foo,2 = "x"
整数と文字列を混在させることができますが、呼び出し元のプログラムは、おそらく同じ型の要素を予想することに注意してください。 またベクトルの最初の要素は「foo,0」ではないことに注意してください。 これは後続の要素があるかどうかに関係なく、最初の要素の名前を同じにするためです。 ただし便宜上「foo,0」を検索すると「foo」が返されます。 したがって、データファイル上の名前として「foo,0」を使うべきではありません。)
行の最後の非コメント非空白文字がコンマの場合、その行は次の行に続くと見なされます。
foo = 10, 11, "x"
これは上記の元のベクトル形式の例と同等です。 このような複数行ベクトルは、列見出し、ベクトル、テーブルの行、または書き間違いの可能性があります。
table型[]
foo = { "bar", "baz", "bax" "wow", 10, -5 "cool", "str" "hmm", 314, 99, 33, 11 }
これは以下と同等です。
foo0.bar = "wow" foo0.baz = 10 foo0.bax = -5 foo1.bar = "cool" foo1.baz = "str" foo2.bar = "hmm" foo2.baz = 314 foo2.bax = 99 foo2.bax,1 = 33 foo2.bax,2 = 11
最初の行はベース名と列名 ("" 内の文字列でなければなりません) を指定し、その後の行にはデータがあります。 列に文字列と整数値を混在させ、列見出しよりも多くの値または少ない値を行に含めることができますが、この情報を (レジストリを介して) 使用するコードは、より厳しい条件を設定する場合があります。 行に列見出しよりも多くのエントリがある場合、最後の列はベクトルとして扱われます (上記のように)。 オプションで、'=' および/または '{' の後に改行を入れることができます。 参考までに、sectionname.entryname パスの長さは 1024 を超えることはできません。
上記の新しい形式と古い形式は同等です。内部的にはデータは古い形式に変換されます。 原則としてデータを内部的にもテーブル (2 次元配列) として表現することを推奨しますが、現在の方法で十分であり、比較的単純です。
データを表形式で保存する機能には制限があります。section_file が想定どおりに作成されている限り、表形式のデータ (欠損値や余分な値がない) を表形式で保存できます。 (section_file_save() を参照してください)。