赤紫蘇2 リファレンス

プログラムの開始から終了まで

akaxiso2.0-beta3


赤紫蘇2リファレンス

1.概要
1.1 赤紫蘇2の構成
1.2 プログラムの
開始から終了まで
1.3 文字コードと
文字コード変換エンジン
1.4 名前空間とQName
1.5 マルチスレッディング

2. 赤紫蘇2データモデル
2.1 チュートリアル
2.2 パーティクル
2.3 aka:sequence
2.3.1 単純型の子要素
2.3.2 複合型の子要素
2.3.1 配列型
2.4 aka::all
2.5 aka:choice
2.5.1 複雑型の子要素
2.5.2 単純型の子要素
2.5.3 バインダクラス
2.5.4 子要素オブジェクト
(aka::item)の扱い
2.5.5 子要素の出現頻度
2.6 属性
2.7 aka:simpleContent
2.8 単純型(aka:simleType)
2.8.1

組み込み型

2.9

配列とポインタ

2.,10 ワイルドカード

3 XMLによる永続化
3.1 シリアライズ
3.2 デシリアライズ

付表
A ライブラリ主要API
B XML Schemaとの
機能対応表
C リリースノート

赤紫蘇2の一般的な使い方の例として、プログラムの開始から終了までを、サンプルプログラムを用いて、説明します。

シリアライズのプログラム例

例として、C++のlong型の変数をシリアライズし、以下のXML文書を生成するプログラムを示します。

<?xml version="1.0" encoding="eucJP"?>

<test>1</test>

このXML文書は、トップノードのみを持ち、その値として整数を持つドキュメントとなります。この場合、C++オブジェクトとしての値を、long型の変数に割り当てることとします。以下、プログラム例となります。

#include <akaxiso2/akaxiso2.h>

int main() {

  aka::initialize(); /* 赤紫蘇2の初期化 */

  aka::doctype("test", xiso::xs::long_leaf()); /* ドキュメント型の登録 */

  long value = 1;
  aka::serialize(value, "test",  std::cout); /* シリアライズ */

  aka::uninitialize();
}

このプログラムの処理の流れについて、説明します。

赤紫蘇2の初期化

プログラムの最初に必要とされるのは、赤紫蘇2の初期化処理です。このために、aka::initialize()を呼び出します。

赤紫蘇2は、名前空間データベースや文字コード変換エンジン、XMLパーサ(Xerces-C++使用時)を、プログラムの実行時に初期化する必要があります。また、赤紫蘇2ドキュメントモデルを表現するオブジェクトもグローバルなオブジェクト上で管理されており、これも、初期化する必要があります。これを行うのが、aka::initialize()関数です。

赤紫蘇2ドキュメントモデルの登録

この後、シリアライズ(デシリアライズ)するドキュメントを登録します。このために、aka::doctype()関数を呼び出します。aka::doctype()関数は、ルートノードのタグ名と、対応するleafクラス(XML型情報クラス)インスタンスを渡すことにより行われます。今回の例では、赤紫蘇2がC++の組み込み型のために定義しているleafクラスを使用しています。leafクラス定義の詳細は、赤紫蘇2データモデルをご参照ください。

この時点で、<test>ドキュメントのシリアライズ、デシリアライズが可能となります。

シリアライズ

この文書のルートノードは、long型の変数です。変数valに1を代入していますが、これが、C++上でのドキュメントの値となります。これを、aka::serialize()関数によりシリアライズします。aka::serialize()関数は、シリアライズされるC++オブジェクトとルートエレメントのタグ名、出力ストリームを引数としてとります。

内部では、xml_serializerクラスを用いたシリアライズが行われます。この際、デフォルトの文字コード変換エンジンを使用して、LCP(Local Code Page、UNIX環境では、eucJP)での出力が行われます。デフォルトのシリアライザは、コンパイル時の設定により、選択可能です。赤紫蘇2 コンパイルとビルド をご参照ください。

赤紫蘇2の終了

プログラムの実行が終了する前に、aka::uninitialize()を呼び出してください。(これは、必須ではありません。)これにより、赤紫蘇2で使用されていたリソースが開放されます。

デシリアライズのプログラム例

今度は、上記のXML文書をデシリアライズして、long型変数の値を得るためのプログラムを示します。XML文書を標準入力から取得し、デシリアライズすることとします。いかにプログラム例を示します。

#include <akaxiso2/akaxiso2.h>

int main() {

  aka::initialize(); /* 赤紫蘇2の初期化 */

  aka::doctype("test", xiso::xs::long_leaf()); /* ドキュメント型の登録 */

  aka2::document doc;
  try {
     doc = aka::deserialize_stdin(); /* デシリアライズ */
  }
  catch (const std::exception &e) {
    std::cerr << "deserialization error occured." << std::endl
                << e.what() << std::endl; 
    return 1;
 }
  catch( ... ) {
    std::cerr << "Unhandled exception." << std::endl;
    return 1;
  }
  
  if (aka::document_of(doc, "test")) { /* ドキュメント型の判定 */
    const long &value = aka2::root_cast<long>(doc);
    std::cout << "document value is " << value << "." std::endl;
  }
  else {
    std::cerr << "Unknown document." << std::endl;
 }

  aka::uninitialize(); /* 赤紫蘇2の終了処理 */
}

赤紫蘇2の初期化、赤紫蘇2ドキュメントモデルの登録までは、シリアライズのプログラム例と同じです。

デシリアライズ

デシリアライズは、aka::deserialize()関数を用いて行いますが、今回は標準入力からXML文書の入力を行うため、aka::deserialize_stdin()関数を用います。デシリアライズ関数群は、内部で、xml_deserializerクラスを用いて、デシリアライズを行います。この際、デフォルトの文字コード変換エンジンと、XMLパーサを使用します。

デシリアライズにより得られる結果は、aka::document型のオブジェクトとして返されます。このオブジェクトの中に、デシリアライズされたC++オブジェクトが格納されます。得られた値を取得するためには、aka::root_cast<>()テンプレート関数を使用し、戻り値の型を指定して、long型変数への参照を取得します。

デシリアライズされたオブジェクトは、docインスタンスの破棄時に自動的に開放されます(内部ではリファレンスカウントで管理されている)。また、docインスタンスの管理下から、明示的に、得られたC++オブジェクトを切り離したい場合には、aka::adopt_root<>()テンプレート関数を用います。詳細については、デシリアライズをご参照ください。

以降、プログラムの終了は、シリアライズのプログラム例と同様、aka::uninitialize()を呼び出し、赤紫蘇2が使用するグローバルなリソースを開放し、終了します。


赤紫蘇2トップへ sourceforgeプロジェクトページへ