赤紫蘇２で使用する主要な関数、クラスについての説明です。
(現在、Doxygenによる、APIリファレンスを作成中です。)
関数初期化・終了
赤紫蘇の初期化、終了時のリソース解放処理などを行います。
| 関数名 |
動作 |
| aka::initialize() |
赤紫蘇２の初期化
Xerces-C++を使っている場合、xercesc::XMLPlatformUtils::Initialize()が内部で呼ばれる。 |
| aka::uninitialize() |
赤紫蘇２の終了
Xerces-C++を使っている場合、xercesc::XMLPlatformUtils::Terminate()が内部で呼ばれる。 |
名前空間、ドキュメントタイプの登録
赤紫蘇２は、名前空間を処理するために、あらかじめ、名前空間URIとプレフィックスとの対応付けを行う必要があります。
対応付けられた名前空間は、ライブラリ内のスタティックなオブジェクトで管理されており、プロセス内において、一意となります。
また、ドキュメント型の登録は、そのタグ名とleafクラスを対応付けることにより、行われます。
| 関数名 |
動作 |
| aka::xmlns(const std::string &prefix, const std::string &url) |
名前空間の登録
prefixで、名前空間プレフィックスを、uriで名前空間URIを指定。
指定された名前空間は、ライブラリ内で常に一意となる。 |
template<class L>
aka::doctype(const std::string &docname, const L &) |
ドキュメント型の登録
docnameでドキュメント名を指定。
leaf引数で、ルートの型に対応するleafクラスを渡す。 |
| aka::doctype(const std::string &docname) |
ドキュメント型の登録
ただし、ルートの型がxs:anyTypeの場合に使用する。
xs:anyTypeは、赤紫蘇組み込み型ではaka::anyに対応する。 |
デシリアライズ
デシリアライズは、以下の関数を呼び出すことにより行います。戻り値は、aka::documentクラスのインスタンスとなります。このクラスは、デシリアライズされたドキュメントのルートノードへのポインタを格納しています。
aka::documentは、一種のスマートポインタであり、ドキュメントのデストラクト時に、ルートノードのインスタンスを解放します。
明示的に、ルートノードインスタンスを、aka::documentの管理下から切り離すこともできます。
デシリアライズ関数は、入力ソースに応じて、複数定義されており、デシリアライズ時のエラーメッセージは、それぞれの入力ソースの名前を含みます。
たとえば、aka::deserialize_file()を用いた場合、エラーメッセージにファイル名が含まれます。
エラー発生時には、例外が投げられます。例外クラスは、std::exceptionの派生クラスです。
| 関数名 |
動作 |
| aka::document aka::deserialize(std::istream &istm) |
std::istreamを入力としてデシリアライズを行う。
戻り値は、aka::documentで返される。 |
| aka::document aka::deserialize(const char *document); |
上記と同様。
ただし、const char*が指すドキュメントをデシリアライズする。
ドキュメントは、0終端していなければならない。 |
aka::document aka::deserialize(const std::string &document);
|
上記と同様。
ただし、const std::string&で示されるドキュメントをデシリアライズする。ドキュメントは、0終端していなければならない。 |
| aka::document aka::deserialize_stdin(); |
標準入力からデシリアライズする。 |
aka::document aka::deserialize_file(const std::string &filename);
|
ファイルの内容をデシリアライズする。 |
デシリアライズ関数から返される、aka::documentのインスタンスから、以下の(テンプレート)関数を用い、ドキュメント名の確認、ルートオブジェクトへのポインタ取得を行うことができます。
| 関数名 |
動作 |
| bool aka::document_of(const aka::document &doc, const std::string &tagname) |
ドキュメントからドキュメント名(ルートのタグ名)を取得 |
template<class T>
T* root_cast(aka2::document &doc) |
渡されたドキュメントから、ルートオブジェクトのインスタンスへのポインタをT*として取得する。取得されるインスタンス、aka::documentクラスの破棄時に自動的に解放される。 |
template<class T>
const T* root_cast(const aka2::document &doc) |
上記のconst版。 |
template<class T>
T* adopt_root(aka2::document &doc) |
渡されたドキュメントから、ルートオブジェクトへのポインタをT*として取得する。取得されるポインタは、aka::documentクラスの管理下から切り離される。ユーザが取得されたインスタンスを解放する必要がある。
|
シリアライズ
シリアライズは、aka::xml_serializerクラスを用いて行います。
aka::xml_serializerクラスは、XML-Namespace 1.1をサポートしており、必要な名前空間を、自動的に必要な場所で宣言します。また、名前空間の宣言は、ルートノード、もしくは、子ノード(XML-Namespace 1.1のスタイル)のどちらかを選ぶことができます。
using_prefix()メソッド、using_uri()メソッドにより、明示的な名前空間の使用が行われた場合には、ルートノードにおける名前空間の宣言が行われます。それ以外の場合には、XML-Namespace1.1のスタイルが用いられ、名前空間の出現時に、名前空間が宣言されます。
| aka::xml_serializer メソッド名 |
動作 |
| xml_serializer_base(const std::string &encoding) |
コンストラクタ。encodingにてエンコーディング名を指定。 |
| void default_ns_prefix(const std::string &prefix); |
デフォルト名前空間として使用する名前空間プレフィックスを指定。 |
| void using_prefix(const std::string &prefix) |
prefixで指定される名前空間を、ルートノードで宣言する。
prefixは、あらかじめ、aka::xmlns()を用いて定義されている必要がある。 |
|
void default_ns_uri(const std::string &uri);
|
デフォルト名前空間として使用する名前空間のURIを指定。 |
| void using_uri(const std::string &uri); |
uriで指定される名前空間を、ルートノードで宣言する。
uriは、あらかじめ、aka::xmlns()を用いて定義されている必要がある。 |
| void enable_ns11(bool value) |
valueがtrueの場合、XML-Namespace 1.1を使用する。
falseの場合には、子ノードにおける名前空間宣言が抑制される。
(falseを指定した場合、using_prefix()、using_uri()を用いて、
ルートノードでの名前空間宣言を行う必要がある。) |
template <class R>
void serialize(const R &root, const std::string &name, std::ostream &ostm) |
ルートオブジェクトとドキュメント名を指定し、シリアライズを行う。
第一引数は、ドキュメントのルートクラス(R)のインスタンス
第二引数は、ドキュメントのタグ名。
第三引数は、出力先。 |
| void serialize(const document &doc, std::ostream &ostm) |
docで渡されるドキュメントをシリアライズし、ostmに出力する。 |
aka::documentのインスタンスをアプリケーションが持っており、また、名前空間の細かい指定が必要ではない場合には、以下の関数で、簡便にシリアライズできます。
| 関数名 |
動作 |
| aka::serialize(const aka::document &doc, std::ostream &ostm) |
docで渡されるドキュメントをシリアライズし、ostmに出力する。 |
値クラスの初期化、コピー、比較
leafクラスには、シリアライザブルなメンバや、デフォルト値の情報が格納されています。
この情報を用いた、インスタンスの初期化、コピー、比較を、以下の関数を用いて行います。
| 関数名 |
動作 |
template<class T, class L>
void aka::construct_element(T &element, const L &); |
leafクラス、Lを用いて、T型のインスタンスを初期化します。 |
template<class T>
void aka::construct_element(T &element); |
xiso::leaf<T>クラスを用いて、T型のインスタンスを初期化します。 |
template<class T, class L>
void aka::copy_element(T &dest, const T& src, const L &); |
leafクラス、Lを用いて、srcをdestにコピーします。
コピーされるのは、シリアライズ対象となっている要素のみです。
xs:sequence、xs:allの場合、クラスのメンバ、xs:choiceの場合、choiceコンテナ内の要素となります。 |
template<class T>
void aka::copy_element(T &dest, const T& src); |
上記と同様のコピーを行います。
ただし、leafクラスとして、xiso::leaf<T>を用います。 |
template<class T, class L>
bool aka::equals(const T &lhs, const T& rhs, const L &); |
leafクラス、Lを用いて、lhslとrhsを比較します。
比較対照となるのは、シリアライズ対象となっている要素のみです。
xs:sequence、xs:allの場合、クラスのメンバ、xs:choiceの場合、choiceコンテナ内の要素となります。
値が等しい場合trueを、異なる場合、falseを返します。 |
template<class T>
bool aka::equals(const T& lhs, const T& rhs); |
上記と同様の比較動作を行います。
ただし、leafクラスとして、xiso::leaf<T>を用います。 |
xs:choice関連
xs:choiceに対応するオブジェクトは、aka::itemを要素とするコンテナとして定義されます。
aka::itemは、タグ名と要素オブジェクトへを持ち、保持する要素インスタンスへの参照を取得することができます。
また、xs:choiceに対応するleafクラスから、コンテナへの要素の挿入、取得を行うためのヘルパクラス(binderクラス)を使用することができます。binderクラスを使用することで、要素を挿入する時のタグ名のチェックや、タグ名による要素の検索を行うことができます。
| 名前 |
動作 |
| binderクラス |
aka::choice<>テンプレートを継承する型の関連型として、binderクラスを使用できます。binderクラスは、leafクラス名::binderで定義されており、デフォルトコンストラクタは、xs:choiceに対応するクラスのインスタンスを引数としてとります。
ex.
leafクラス名をchoice_leaf、コンテナ名をchoiceとします。その場合、binderクラスは、以下の形式でbinderクラスとしてインスタンシングできます。
choice_leaf::binder binder(choiceコンテナインスタンス); |
mocクラスは、以下のメソッドを持ちます。
leaf::binderクラス
メソッド |
動作 |
template<class I>
void push_back(I &item, const std::string & tagname)
|
choiceの要素をコンテナに挿入します。
一つ目の引数は、挿入するオブジェクトのインスタンス、二つ目の引数は、対応するタグ名となります。
choiceの子要素として、定義されていないタグ名を用いた場合、もしくは、class Iに対するタグ名が正しくない場合、例外が投げられます。例外は、std::exceptionの派生型です。
push_back()メソッドは、aka::sequential_choice<>のbinderクラスにのみ実装されています。 |
template<class I>
void insert(I &item, const std::string & tagname)
|
choiceの要素をコンテナに挿入します。
一つ目の引数は、挿入するオブジェクトのインスタンス、二つ目の引数は、対応するタグ名となります。
choiceの子要素として、定義されていないタグ名を用いた場合、もしくは、class Iに対するタグ名が正しくない場合、例外が投げられます。例外は、std::exceptionの派生型です。
insert()メソッドは、aka::associative_choice<>のbinderクラスにのみ実装されています。 |
