/** -*- c -*- */
/** 
    @mainpage Akaxiso API reference

    <p> Under Construction </p>

    @see @ref datamodel
 */
/**
 @page datamodel Akaxiso Datamodel

Akaxiso library has its own datamodel based on XML Schema datamodel.
See the following links.

 @par simpleTypes
 @ref aka_simpletype

 @par Arrays and pointers
 @ref arrays_pointers

 @par Particles
 @ref particles \n
 @ref aka_sequence \n
 @ref aka_choice \n
 @ref aka_all \n
 @ref aka_simplecontent \n

 @par Document
 @ref document \n

 @par Namespace
 @ref namespace

*/

/**
@page aka_simpletype Simple Types

Akaxiso's simple type is a text node surrounded by tags like the following list.\n

@code
<?xml version="1.0"?>
<simpletype>VALUE</simpletype>
@endcode

Akaxiso does not support mixed text nodes, therefore any serializable text node is always a simple type.\n

To use a serializable simpleType, define leaf class as a derivation of aka2::simpletype<>.\n
Here's the sample of a leaf class of long values.\n
On failure of reading a given text or writing to std::ostream, throw aka2::error as an exception. 

@code
struct long_leaf : aka2::simpletype<long> {
  void write_text(const void *elm, std::ostream &ostm, aka::entity_complements &ecomps) {
    const long &value = *static_cast<long*>(elm);
    ostm << value;
  }
  void read_text(void *elm, const std::string &entity, aka::entity_compliments &ecomps) {
    long &value = *static_cast<long*>(elm);
    aka::isstream istm(entity);
    istm >> value;
    if (istm.fail())
      throw aka::error("Failed to read long value.", __FILE__, __LINE__);
  }
};
@endcode

You may need additional information to read/write text values, which aka2::entity_complements give.
Currently preconditions supports only namespace properties, and would be extended.

Akaxiso has predefined leaf classes for builtin types.

@code
------------------------------------------------------------
Numeric types          min           max   XML-Schema type
char                  -128           128   xs:byte
unsigned char            0           255   xs:unsignedByte
short               -32768         32767   xs:short   
unsigned short           0         65535   xs:unsignedShort 
long           -2147483648    2147483647   xs:int, xs:integer
unsigned long            0        2^32-1   xs:unsignedInt,
LONGLONG             -2^63        2^63-1   xs:long, 
ULONGLONG                0        2^64-1   xs:unsignedLong,
int                  compiler-dependent.   (Not mapped.)
------------------------------------------------------------
boolean type
bool     true/false (0/1)     xs:boolean
------------------------------------------------------------
floating-point number
float
double
------------------------------------------------------------
string type.
std::string
------------------------------------------------------------
aka::nill  empty type.
------------------------------------------------------------
@endcode

*/


/**
 @page arrays_pointers Arrays and pointers

 Akaxiso datamodel represents XMLSchema's occurence by using arrays and pointers.

 @section array Array
 Akaxiso's arrays are defined by using STL or STL-compatible containers.
 The following interface(concept) is supported.
 - <a href="http://www.sgi.com/tech/stl/Sequence.html" target="_blank">Sequence</a>
 - <a href="http://www.sgi.com/tech/stl/SortedAssociativeContainer.html" target="_blank">Sorted associative container</a>

 To define leaf classes for arrays, use aka2::sequential_array<> template or aka2::associative_array<> template.

@code
typedef std::vector<long> long_array;
typedef aka2::sequential_array<long_array, xiso::leaf<long> > long_array_leaf;
@endcode

 
 @section pointer Pointer
 Akaxiso can use pointers as a serializable member for aka:sequence and @ref aka_all.
 Pointer members should be declared by using aka2::deep_ptr<> template.

@code
struct sequence {
  aka2::deep_ptr<long> longptr_;
};

struct sequence_leaf : aka2::sequence<sequence, sequence_leaf> {
  void model() {
    // The part surrounded by brackets, [], is optional.
    ptrmember("pointer_to_long_value", &sequence::longptr_[, xiso::leaf<long>()]);
  }
};
@endcode
*/


/**
 @page particles Akaxiso Particles

 @section aka_sequence aka:sequence
 aka:sequence is a particle in akaxiso datamodel based on xs:sequence.\n
\n
This particle has child element sequence like xs:sequence, and the real values are defined as value-class members.\n
aka:sequence is equvalent to the following XML Schema definitions.\n

When used as xs:complexType,
@code
<xs:complexType name="aka:sequence">
  <xs:sequence>
    <!-- 0 or more -->
    <xs:element ..../>, <xs:group ..../>
  </xs:sequence>
  <!-- 0 or more -->
  <xs:attribute ..../>
</xs:complexType>
@endcode


When used as xs:group,
@code
<xs:group name="aka:sequence_group">
  <xs:sequence>
    <!-- 0 or more -->
    <xs:element ..../>, <xs:group ..../>
  </xs:sequence>
</xs:group>
@endcode


Expample is here.\n
Code surrounded by [ ] is optional, because xiso::leaf<> is implicitly specified.

@code
// Value class
struct foo {
  std::string member1_;
  long member2_;
};

// leaf class
struct foo_leaf : aka::sequence<foo, foo_leaf> {
  void model() {
    member("member1", &foo::member1_[, xiso::leaf<std::string>()]);
    member("member2", &foo::member2_[, xiso::leaf<long>()]);
  }
};
@endcode


@section aka_choice aka:choice

@code
<xs:complexType name="aka:choice">
  <xs:choice>
    <!-- 0 or more -->
    <xs:element ... />
  </xs:choice>
</xs:complexType>
@endcode

@code
<xs:group name="aka:choice_group">
  <xs:choice>
    <!-- 0 or more -->
    <xs:element ... />
  </xs:choice>
</xs:group>
@endcode


@section aka_all aka:all

@code
<xs:compexType name="aka:all">
  <xs:all>
    <!-- 0 or more -->
    <xs:element .../>
  </xs:all>
  <!-- 0 or more -->
  <xs:attribute ... />
</xs:complexType>
@endcode
@code
<xs:group name="aka:all_group">
  <xs:all>
    <!-- 0 or more -->
    <xs:element .../>
  </xs:all>
</xs:group>
@endcode

*/

/**
 @page aka_simplecontent simpleContent
*/

/**
 @page attribute Attributes
*/

/**
 @page document Document declaration

 Document is declared by using aka2::doctype(const std::string &name, const L &) function.
 See the following example.

@code
 struct foo {
  long value_;
 };
 struct foo_leaf : aka2::sequence<foo, foo_leaf> {
  void model() {
    member("value", &foo::value_);
  }
 };

int main() {
  aka2::initialize();
  // Users can use document "foo".
  aka2::doctype("foo", foo_leaf());

  //... code continues.
}
@endcode

If the root type is aka2::any (xs:anyType), then use aka2::doctype(const std::string &name).
Deserialized document is aka2::any.

@code
int main() {
  aka2::initialize();
  // aka2::any (xs:anyType) document declaration.
  aka2::doctype("anyType_document");

  //... code continues.
}
@endcode

If the root type is fixed simpleType value, then use aka2::doctype(const std::string &name, const L&, const std::string &fixed_value).

@code
int main() {
  aka2::initialize();
  aka2::doctype("fixed_document", xiso::leaf<std::string>(), "fixed_value");
};
@endcode

*/

/**
 @page namespace Namespace

 Use aka2::xmlns() to register namespace.
 Here's an example to define a document type in "aka"(http://akaxiso.sourceforge.jp) namespace.
@code
 struct foo {
  long value_;
 };

 struct foo_leaf : aka2::sequence<foo, foo_leaf> {
  void model() {
    member("aka:value", &foo::value_);
  }
 };

 int main() {
   aka2::initialize();
   aka2::xmlns("aka", "http://akaxiso.sourceforge.jp"); 
   aka2::doctype("aka:foo", foo_leaf());

   // ... code continues.
 }
@endcode

By calling aka2::xmlns(), namespace prefix "aka" and namespace URI "http://akaxiso.sourceforge.jp" is associated.\n
The leaf class, foo_leaf, defines a qualified element by using qualified tag-name of "aka:value".\n
Document name is also qualified .
*/
