Sgry.Ini - INI ファイル形式を扱う C# クラス

概要

このページでは Sgry.Ini という INI ファイル形式を扱う C# のクラスを公開しています。 非常に制約の緩い zlib ライセンスでの配布であること、 1 ソースファイルで記述されていることから、 既存プロジェクトへの組み込みも簡単に行えると思います。

（2014/7/19追記。本プロジェクトはGitHubに移管しました。そちらの新バージョンをご利用ください）

INI 形式について

このライブラリが扱う INI 形式について、簡単に説明をしておきます。 INI 形式は厳密なフォーマット仕様こそ存在しませんが、 非常に広くに使われているフォーマットです。 INI 形式では、「A は B である」という情報を次のような形式のテキストで表します。 

A=B

この一行で「イコール記号の左側の値が、イコール記号の右側の値である」という情報になります。 たとえば「名前が山本である」という情報は次のようになります。 

名前=山本

なおこれは必ず一行に収まっている必要があり、 改行を含んだデータを書き込むことはできません。

このライブラリでは、 こうした一つの情報を INI 形式の「エントリー」と呼びます。 またイコール記号の左側の値を「エントリー名」、 イコール記号の右側の値を「エントリー値」または単に「値」と呼びます。 INI 形式とは、基本的にはエントリーが集まったものになります。

さて、当然ですが、この形式ですと同じエントリー名のエントリーを複数定義することはできません。 そこで複数のエントリーをまとめてグループ化する仕組みが使われています。 まず具体例を先に挙げます。 

[User1]
FamilyName=YAMAMOTO
FirstName=Suguru
Sex=Male
[User2]
FamilyName=YAMADA
FirstName=Taro
Sex=Male

ここで大カッコで囲われた見出しのような行があることに気づくと思いますが、 実際にそれらは見出しの意味を持っています。 つまり、ある見出しの行から後ろにあるエントリーは、 その見出しのセクション（章）で書かれていると言えます。 そして次の見出しの行が見つかったら、 その後ろにあるエントリーからは新しく見つかった見出しのセクション （章）で書かれていると言えます。

このライブラリでは、 見出しの意味を持つ行を「セクション開始行」と呼び、 セクション開始行から次のセクション開始行までの区間を 「セクション」と呼びます。 またセクション開始行の大カッコの中身を、 そこから始まるセクションの名前として使用します。 したがって先ほどの例でいえば セクション User1 の FirstName は Suguru であり、 セクション User2 の FirstName は Taro となります。

機能

ファイルやストリームからデータを読み出す

ファイルやメモリなどにある INI データを解析して内容をロードする場合は Load メソッドを使います。 また INI データのロード元として System.IO.TextReader を、 INI データの出力先として System.IO.TextWriter を指定できるため、 ファイルだけでなくメモリ上のバッファなどに対しても読み書き可能です。 ごく単純な例を次に示します。 

Ini ini = new Ini();
ini.Load( "data.ini", Encoding.UTF8 );

値の取り出し

ロードしたデータの読み出しは Get メソッドを使います。 Get メソッドでは String 型、Bool 型、Double 型といった基本的なデータを直接扱えます。 次に例を示します。 

/* ファイル data.ini の内容:
[Profile]
Name=Suguru
IsGeek=True
*/

// ファイルの内容をロード
Ini ini = new Ini();
ini.Load( "data.ini" );

// データを取り出す
ini.Get( "Profile", "Name", null ); // "Suguru" が返る
ini.Get( "Profile", "IsGeek", false ); // true が返る
ini.Get( "Profile", "Age", 20 ); // Age は INI 中に無いので 20 が返る

Get メソッドは、 Ini ファイルの主な用途が設定ファイルであることを考えて第 3 引数で 「デフォルト値」を指定できるようになっています。 これによって「値が見つからなければデフォルト値を設定する」 という設定読み出し処理で頻繁に出てくる面倒なコーディングの手間が軽減される・・・ かもしれません。

なお数値の取得用には専用のメソッド GetInt を用意しています。 もちろん Get メソッドでも数値は取得できますが、 GetInt は数値の取得と同時に範囲チェックも行ってくれます。 設定項目の場合、たとえば日付のデータは 1 以上 31 以下でなければいけませんし、 ウィンドウの幅は正の数でなければいけません。 こうしたデータを読み出す場合に GetInt を使えば「許容する最小値と最大値」を指定できるので、 読み出した後でチェックする手間を省略できます。

ちなみに、厳密には Get メソッドには文字列用の Get メソッドと 値型を汎用的に扱う Get<T> メソッドがありますが、 ただ普通に使う場合は Get という 2 つのメソッドがあることを意識する必要は無いはずです。 システム標準の基本的な型でない独自の型などを使う場合は 若干話がややこしくなるかもしれませんので注意してください。

値の変更や追加

INI データの内容を変更する場合は Set メソッドを使います。 指定したセクションの、指定したエントリ名を持った値がすでに存在する場合、 その値は Set メソッドで指定した値に書き換えられます。 逆に存在しない場合、新たに指定したエントリが作成されて、 そこに指定した値が設定されます。

値として使うオブジェクトの型は、何でも OK です。 内部でそのオブジェクトの ToString メソッドを呼び出して、 その結果文字列を使うからです。

値の削除

INI データ中の値を削除するには Remove メソッドを使います。 Remove メソッドには削除したい値（エントリー）がある セクションの名前とエントリー名を指定します。

ファイルやストリームにデータを保存

INI データをファイルなどのストリームに保存するには Save メソッドを使います。 Save メソッドには TextWriter を与えるか、 ファイルパスを与えます。 次に例を示します。 

// data.ini というファイルに UTF-8 で保存
ini.Save( "data.ini", Encoding.UTF8 );

// メモリ上のバッファ(StringBuilder)に INI 形式テキストとして書き込む
StringBuilder buf = new StringBuilder();
StringWriter writer = new StringWriter( buf );
ini.Save( writer );
buf.ToString() // INI 形式テキストが返る

ライセンス

このプログラムソースは zlib ライセンスの下で公開します。 同ライセンスの下では、 商用・非商用を問わず自由に使用、コピー、改変、結合、掲載などを行う事が許可されます。 zlib ライセンスの内容については拙作のテキストエディタエンジン Azuki 用に書いたページをご参照ください。

→ Azuki 用の zlib ライセンスの説明ページへ移動

ダウンロード

ソース：Sgry.Ini-2.1.1.zip (v2.1.1)

更新履歴

[v2.1.1] 2009-10-17
・ファイルを開くときに共有モードで開くように

[v2.1.0] 2009-08-02
・Ini.Get を enum に対応させた

[v2.0.0] 2009-03-29
・ジェネリックを使ってフルスクラッチで書き換え

[v1.1.4] 2008-08-24
・zlib license に切り替え

[v1.1.3] 2008-05-03
・.NET Compact Framework でも使えるように

[v1.1.2] 2007-04-01
・インデクサでセクションを削除すると問題が起こっていたのを修正

[v1.1.1] 2007-02-05
・インタフェースの実装抜けを修正

[v1.1.0] 2007-02-03
・インタフェースを再設計

[v1.0.0] 2007-01-01
・MIT License の著作権表示を追記

[v1.0.0] 2006-09-24
・リリース

戻る