From 5e527213a2430bb3018e5eebd909aef294edf9b5 Mon Sep 17 00:00:00 2001 From: Karen Arutyunov Date: Fri, 18 Dec 2020 18:48:46 +0300 Subject: Switch to build2 --- doc/custom-literals.xsd | 48 - doc/cxx/makefile | 20 - doc/cxx/parser/guide/figure-1.png | Bin 34195 -> 0 bytes doc/cxx/parser/guide/figure-1.svg | 373 -- doc/cxx/parser/guide/guide.html2ps | 65 - doc/cxx/parser/guide/index.xhtml | 4158 -------------------- doc/cxx/parser/guide/makefile | 55 - doc/cxx/parser/makefile | 20 - doc/cxx/tree/guide/guide.html2ps | 65 - doc/cxx/tree/guide/index.xhtml | 2732 ------------- doc/cxx/tree/guide/makefile | 53 - doc/cxx/tree/makefile | 40 - doc/cxx/tree/manual/index.xhtml | 6822 --------------------------------- doc/cxx/tree/manual/makefile | 53 - doc/cxx/tree/manual/manual.html2ps | 66 - doc/cxx/tree/reference/footer.html | 6 - doc/cxx/tree/reference/libxsd.doxygen | 1291 ------- doc/cxx/tree/reference/makefile | 18 - doc/default.css | 319 -- doc/doc.sh | 105 - doc/makefile | 142 - doc/xsd-epilogue.1 | 566 --- doc/xsd-epilogue.xhtml | 422 -- doc/xsd-parser-header.1 | 4 - doc/xsd-parser-header.xhtml | 1 - doc/xsd-prologue.1 | 119 - doc/xsd-prologue.xhtml | 122 - doc/xsd-tree-header.1 | 4 - doc/xsd-tree-header.xhtml | 1 - 29 files changed, 17690 deletions(-) delete mode 100644 doc/custom-literals.xsd delete mode 100644 doc/cxx/makefile delete mode 100644 doc/cxx/parser/guide/figure-1.png delete mode 100644 doc/cxx/parser/guide/figure-1.svg delete mode 100644 doc/cxx/parser/guide/guide.html2ps delete mode 100644 doc/cxx/parser/guide/index.xhtml delete mode 100644 doc/cxx/parser/guide/makefile delete mode 100644 doc/cxx/parser/makefile delete mode 100644 doc/cxx/tree/guide/guide.html2ps delete mode 100644 doc/cxx/tree/guide/index.xhtml delete mode 100644 doc/cxx/tree/guide/makefile delete mode 100644 doc/cxx/tree/makefile delete mode 100644 doc/cxx/tree/manual/index.xhtml delete mode 100644 doc/cxx/tree/manual/makefile delete mode 100644 doc/cxx/tree/manual/manual.html2ps delete mode 100644 doc/cxx/tree/reference/footer.html delete mode 100644 doc/cxx/tree/reference/libxsd.doxygen delete mode 100644 doc/cxx/tree/reference/makefile delete mode 100644 doc/default.css delete mode 100755 doc/doc.sh delete mode 100644 doc/makefile delete mode 100644 doc/xsd-epilogue.1 delete mode 100644 doc/xsd-epilogue.xhtml delete mode 100644 doc/xsd-parser-header.1 delete mode 100644 doc/xsd-parser-header.xhtml delete mode 100644 doc/xsd-prologue.1 delete mode 100644 doc/xsd-prologue.xhtml delete mode 100644 doc/xsd-tree-header.1 delete mode 100644 doc/xsd-tree-header.xhtml (limited to 'doc') diff --git a/doc/custom-literals.xsd b/doc/custom-literals.xsd deleted file mode 100644 index c6f7613..0000000 --- a/doc/custom-literals.xsd +++ /dev/null @@ -1,48 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/doc/cxx/makefile b/doc/cxx/makefile deleted file mode 100644 index 1395edc..0000000 --- a/doc/cxx/makefile +++ /dev/null @@ -1,20 +0,0 @@ -# file : doc/cxx/makefile -# license : GNU GPL v2 + exceptions; see accompanying LICENSE file - -include $(dir $(lastword $(MAKEFILE_LIST)))../../build/bootstrap.make - -docs := parser tree - -default := $(out_base)/ -install := $(out_base)/.install -dist := $(out_base)/.dist -dist-win := $(out_base)/.dist-win -clean := $(out_base)/.clean - -$(default): $(addprefix $(out_base)/,$(addsuffix /,$(docs))) -$(install): $(addprefix $(out_base)/,$(addsuffix /.install,$(docs))) -$(dist): $(addprefix $(out_base)/,$(addsuffix /.dist,$(docs))) -$(dist-win): $(addprefix $(out_base)/,$(addsuffix /.dist-win,$(docs))) -$(clean): $(addprefix $(out_base)/,$(addsuffix /.clean,$(docs))) - -$(foreach m,$(docs),$(call import,$(src_base)/$m/makefile)) diff --git a/doc/cxx/parser/guide/figure-1.png b/doc/cxx/parser/guide/figure-1.png deleted file mode 100644 index 15d1723..0000000 Binary files a/doc/cxx/parser/guide/figure-1.png and /dev/null differ diff --git a/doc/cxx/parser/guide/figure-1.svg b/doc/cxx/parser/guide/figure-1.svg deleted file mode 100644 index d994a79..0000000 --- a/doc/cxx/parser/guide/figure-1.svg +++ /dev/null @@ -1,373 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - class people_pimpl{ void person ();}; - - - - class person_pimpl{ void first_name (string); void last_name (string); void gender (); void age (short); void post_person ();}; - - - - class string_pimpl{ string post_string ();}; - - - class short_pimpl{ short post_short ();}; - - - class gender_pimpl{ void post_gender ();}; - - - - - - - diff --git a/doc/cxx/parser/guide/guide.html2ps b/doc/cxx/parser/guide/guide.html2ps deleted file mode 100644 index af5e0f2..0000000 --- a/doc/cxx/parser/guide/guide.html2ps +++ /dev/null @@ -1,65 +0,0 @@ -@html2ps { - option { - toc: hb; - colour: 1; - hyphenate: 1; - titlepage: 1; - } - - datefmt: "%B %Y"; - - titlepage { - content: " -
-

C++/Parser Mapping

-

Getting Started Guide

-

 

-

 

-

 

-

 

-

 

-

 

-
-

Copyright © 2009-2020 Code Synthesis Tools CC.

- -

Permission is granted to copy, distribute and/or modify this - document under the terms of the - GNU Free - Documentation License, version 1.2; with no Invariant Sections, - no Front-Cover Texts and no Back-Cover Texts. -

- -

This document is available in the following formats: - XHTML, - PDF, and - PostScript.

"; - } - - toc { - indent: 2em; - } - - header { - odd-right: $H; - even-left: $H; - } - - footer { - odd-left: $D; - odd-center: $T; - odd-right: $N; - - even-left: $N; - even-center: $T; - even-right: $D; - } -} - -body { - font-size: 12pt; - text-align: justify; -} - -pre { - font-size: 10pt; -} diff --git a/doc/cxx/parser/guide/index.xhtml b/doc/cxx/parser/guide/index.xhtml deleted file mode 100644 index 1399214..0000000 --- a/doc/cxx/parser/guide/index.xhtml +++ /dev/null @@ -1,4158 +0,0 @@ - - - - - - C++/Parser Mapping Getting Started Guide - - - - - - - - - - - - - -
-
- -
- -
-
C++/Parser Mapping
-
Getting Started Guide
- -

Copyright © 2009-2020 Code Synthesis Tools CC.

- -

Permission is granted to copy, distribute and/or modify this - document under the terms of the - GNU Free - Documentation License, version 1.2; with no Invariant Sections, - no Front-Cover Texts and no Back-Cover Texts. -

- -

This document is available in the following formats: - XHTML, - PDF, and - PostScript.

- -
- -

Table of Contents

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Preface - - - -
About This Document
More Information
-
1Introduction - - - -
1.1Mapping Overview
1.2Benefits
-
2Hello World Example - - - - - -
2.1Writing XML Document and Schema
2.2Translating Schema to C++
2.3Implementing Application Logic
2.4Compiling and Running
-
3Parser Skeletons - - - - - -
3.1Implementing the Gender Parser
3.2Implementing the Person Parser
3.3Implementing the People Parser
3.4Connecting the Parsers Together
-
4Type Maps - - - - -
4.1Object Model
4.2Type Map File Format
4.3Parser Implementations
-
5Mapping Configuration - - - - - - -
5.1C++ Standard
5.2Character Type and Encoding
5.3Underlying XML Parser
5.4XML Schema Validation
5.5Support for Polymorphism
-
6Built-In XML Schema Type Parsers - - - - - - - - - - - - - - -
6.1QName Parser
6.2NMTOKENS and IDREFS Parsers
6.3base64Binary and hexBinary Parsers
6.4Time Zone Representation
6.5date Parser
6.6dateTime Parser
6.7duration Parser
6.8gDay Parser
6.9gMonth Parser
6.10gMonthDay Parser
6.11gYear Parser
6.12gYearMonth Parser
6.13time Parser
-
7Document Parser and Error Handling - - - - -
7.1Xerces-C++ Document Parser
7.2Expat Document Parser
7.3Error Handling
-
Appendix A — Supported XML Schema Constructs
-
- -

Preface

- -

About This Document

- -

The goal of this document is to provide you with an understanding of - the C++/Parser programming model and allow you to efficiently evaluate - XSD against your project's technical requirements. As such, this - document is intended for C++ developers and software architects - who are looking for an XML processing solution. Prior experience - with XML and C++ is required to understand this document. Basic - understanding of XML Schema is advantageous but not expected - or required. -

- - -

More Information

- -

Beyond this guide, you may also find the following sources of - information useful:

- -
    -
  • XSD - Compiler Command Line Manual
  • - -
  • The examples/cxx/parser/ directory in the XSD - distribution contains a collection of examples and a README - file with an overview of each example.
  • - -
  • The README file in the XSD distribution explains - how to compile the examples on various platforms.
  • - -
  • The xsd-users - mailing list is the place to ask technical questions about XSD and the C++/Parser mapping. - Furthermore, the archives - may already have answers to some of your questions.
  • - -
- - - -

1 Introduction

- -

Welcome to CodeSynthesis XSD and the C++/Parser mapping. XSD is a - cross-platform W3C XML Schema to C++ data binding compiler. C++/Parser - is a W3C XML Schema to C++ mapping that represents an XML vocabulary - as a set of parser skeletons which you can implement to perform XML - processing as required by your application logic. -

- -

1.1 Mapping Overview

- -

The C++/Parser mapping provides event-driven, stream-oriented - XML parsing, XML Schema validation, and C++ data binding. It was - specifically designed and optimized for high performance and - small footprint. Based on the static analysis of the schemas, XSD - generates compact, highly-optimized hierarchical state machines - that combine data extraction, validation, and even dispatching - in a single step. As a result, the generated code is typically - 2-10 times faster than general-purpose validating XML parsers - while maintaining the lowest static and dynamic memory footprints. -

- -

To speed up application development, the C++/Parser mapping - can be instructed to generate sample parser implementations - and a test driver which can then be filled with the application - logic code. The mapping also provides a wide range of - mechanisms for controlling and customizing the generated code.

- -

The next chapter shows how to create a simple application that uses - the C++/Parser mapping to parse, validate, and extract data from a - simple XML document. The following chapters show how to - use the C++/Parser mapping in more detail.

- -

1.2 Benefits

- -

Traditional XML access APIs such as Document Object Model (DOM) - or Simple API for XML (SAX) have a number of drawbacks that - make them less suitable for creating robust and maintainable - XML processing applications. These drawbacks include: -

- -
    -
  • Generic representation of XML in terms of elements, attributes, - and text forces an application developer to write a substantial - amount of bridging code that identifies and transforms pieces - of information encoded in XML to a representation more suitable - for consumption by the application logic.
  • - -
  • String-based flow control defers error detection to runtime. - It also reduces code readability and maintainability.
  • - -
  • Lack of type safety because the data is represented - as text.
  • - -
  • Resulting applications are hard to debug, change, and - maintain.
  • -
- -

In contrast, statically-typed, vocabulary-specific parser - skeletons produced by the C++/Parser mapping allow you to - operate in your domain terms instead of the generic elements, - attributes, and text. Static typing helps catch errors at - compile-time rather than at run-time. Automatic code generation - frees you for more interesting tasks (such as doing something - useful with the information stored in the XML documents) and - minimizes the effort needed to adapt your applications to - changes in the document structure. To summarize, the C++/Parser - mapping has the following key advantages over generic XML - access APIs:

- -
    -
  • Ease of use. The generated code hides all the complexity - associated with recreating the document structure, maintaining the - dispatch state, and converting the data from the text representation - to data types suitable for manipulation by the application logic. - Parser skeletons also provide a convenient mechanism for building - custom in-memory representations.
  • - -
  • Natural representation. The generated parser skeletons - implement parser callbacks as virtual functions with names - corresponding to elements and attributes in XML. As a result, - you process the XML data using your domain vocabulary instead - of generic elements, attributes, and text. -
  • - -
  • Concise code. With a separate parser skeleton for each - XML Schema type, the application implementation is - simpler and thus easier to read and understand.
  • - -
  • Safety. The XML data is delivered to parser callbacks as - statically typed objects. The parser callbacks themselves are virtual - functions. This helps catch programming errors at compile-time - rather than at runtime.
  • - -
  • Maintainability. Automatic code generation minimizes the - effort needed to adapt the application to changes in the - document structure. With static typing, the C++ compiler - can pin-point the places in the application code that need to be - changed.
  • - -
  • Efficiency. The generated parser skeletons combine - data extraction, validation, and even dispatching in a single - step. This makes them much more efficient than traditional - architectures with separate stages for validation and data - extraction/dispatch.
  • -
- - - - -

2 Hello World Example

- -

In this chapter we will examine how to parse a very simple XML - document using the XSD-generated C++/Parser skeletons. - The code presented in this chapter is based on the hello - example which can be found in the examples/cxx/parser/ - directory of the XSD distribution.

- -

2.1 Writing XML Document and Schema

- -

First, we need to get an idea about the structure - of the XML documents we are going to process. Our - hello.xml, for example, could look like this:

- -
-<?xml version="1.0"?>
-<hello>
-
-  <greeting>Hello</greeting>
-
-  <name>sun</name>
-  <name>moon</name>
-  <name>world</name>
-
-</hello>
-  
- -

Then we can write a description of the above XML in the - XML Schema language and save it into hello.xsd:

- -
-<?xml version="1.0"?>
-<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
-
-  <xs:complexType name="hello">
-    <xs:sequence>
-      <xs:element name="greeting" type="xs:string"/>
-      <xs:element name="name" type="xs:string" maxOccurs="unbounded"/>
-    </xs:sequence>
-  </xs:complexType>
-
-  <xs:element name="hello" type="hello"/>
-
-</xs:schema>
-  
- -

Even if you are not familiar with XML Schema, it - should be easy to connect declarations in hello.xsd - to elements in hello.xml. The hello type - is defined as a sequence of the nested greeting and - name elements. Note that the term sequence in XML - Schema means that elements should appear in a particular order - as opposed to appearing multiple times. The name - element has its maxOccurs property set to - unbounded which means it can appear multiple times - in an XML document. Finally, the globally-defined hello - element prescribes the root element for our vocabulary. For an - easily-approachable introduction to XML Schema refer to - XML Schema Part 0: - Primer.

- -

The above schema is a specification of our XML vocabulary; it tells - everybody what valid documents of our XML-based language should look - like. The next step is to compile this schema to generate - the object model and parsing functions.

- -

2.2 Translating Schema to C++

- -

Now we are ready to translate our hello.xsd to C++ parser - skeletons. To do this we invoke the XSD compiler from a terminal - (UNIX) or a command prompt (Windows): -

- -
-$ xsd cxx-parser --xml-parser expat hello.xsd
-  
- -

The --xml-parser option indicates that we want to - use Expat as the underlying XML parser (see Section - 5.3, "Underlying XML Parser"). The XSD compiler produces two - C++ files: hello-pskel.hxx and hello-pskel.cxx. - The following code fragment is taken from hello-pskel.hxx; - it should give you an idea about what gets generated: -

- -
-class hello_pskel
-{
-public:
-  // Parser callbacks. Override them in your implementation.
-  //
-  virtual void
-  pre ();
-
-  virtual void
-  greeting (const std::string&);
-
-  virtual void
-  name (const std::string&);
-
-  virtual void
-  post_hello ();
-
-  // Parser construction API.
-  //
-  void
-  greeting_parser (xml_schema::string_pskel&);
-
-  void
-  name_parser (xml_schema::string_pskel&);
-
-  void
-  parsers (xml_schema::string_pskel& /* greeting */,
-           xml_schema::string_pskel& /* name */);
-
-private:
-  ...
-};
-  
- -

The first four member functions shown above are called parser - callbacks. You would normally override them in your implementation - of the parser to do something useful. Let's go through all of - them one by one.

- -

The pre() function is an initialization callback. It is - called when a new element of type hello is about - to be parsed. You would normally use this function to allocate a new - instance of the resulting type or clear accumulators that are used - to gather information during parsing. The default implementation - of this function does nothing.

- -

The post_hello() function is a finalization callback. Its - name is constructed by adding the parser skeleton name to the - post_ prefix. The finalization callback is called when - parsing of the element is complete and the result, if any, should - be returned. Note that in our case the return type of - post_hello() is void which means there - is nothing to return. More on parser return types later. -

- -

You may be wondering why the finalization callback is called - post_hello() instead of post() just - like pre(). The reason for this is that - finalization callbacks can have different return types and - result in function signature clashes across inheritance - hierarchies. To prevent this the signatures of finalization - callbacks are made unique by adding the type name to their names.

- -

The greeting() and name() functions are - called when the greeting and name elements - have been parsed, respectively. Their arguments are of type - std::string and contain the data extracted from XML.

- -

The last three functions are for connecting parsers to each other. - For example, there is a predefined parser for built-in XML Schema type - string in the XSD runtime. We will be using - it to parse the contents of greeting and - name elements, as shown in the next section.

- -

2.3 Implementing Application Logic

- -

At this point we have all the parts we need to do something useful - with the information stored in our XML document. The first step is - to implement the parser: -

- -
-#include <iostream>
-#include "hello-pskel.hxx"
-
-class hello_pimpl: public hello_pskel
-{
-public:
-  virtual void
-  greeting (const std::string& g)
-  {
-    greeting_ = g;
-  }
-
-  virtual void
-  name (const std::string& n)
-  {
-    std::cout << greeting_ << ", " << n << "!" << std::endl;
-  }
-
-private:
-  std::string greeting_;
-};
-  
- -

We left both pre() and post_hello() with the - default implementations; we don't have anything to initialize or - return. The rest is pretty straightforward: we store the greeting - in a member variable and later, when parsing names, use it to - say hello.

- -

An observant reader my ask what happens if the name - element comes before greeting? Don't we need to - make sure greeting_ was initialized and report - an error otherwise? The answer is no, we don't have to do - any of this. The hello_pskel parser skeleton - performs validation of XML according to the schema from which - it was generated. As a result, it will check the order - of the greeting and name elements - and report an error if it is violated.

- -

Now it is time to put this parser implementation to work:

- -
-using namespace std;
-
-int
-main (int argc, char* argv[])
-{
-  try
-  {
-    // Construct the parser.
-    //
-    xml_schema::string_pimpl string_p;
-    hello_pimpl hello_p;
-
-    hello_p.greeting_parser (string_p);
-    hello_p.name_parser (string_p);
-
-    // Parse the XML instance.
-    //
-    xml_schema::document doc_p (hello_p, "hello");
-
-    hello_p.pre ();
-    doc_p.parse (argv[1]);
-    hello_p.post_hello ();
-  }
-  catch (const xml_schema::exception& e)
-  {
-    cerr << e << endl;
-    return 1;
-  }
-}
-  
- -

The first part of this code snippet instantiates individual parsers - and assembles them into a complete vocabulary parser. - xml_schema::string_pimpl is an implementation of a parser - for built-in XML Schema type string. It is provided by - the XSD runtime along with parsers for other built-in types (for - more information on the built-in parsers see Chapter 6, - "Built-In XML Schema Type Parsers"). We use string_pimpl - to parse the greeting and name elements as - indicated by the calls to greeting_parser() and - name_parser(). -

- -

Then we instantiate a document parser (doc_p). The - first argument to its constructor is the parser for - the root element (hello_p in our case). The - second argument is the root element name. -

- -

The final piece is the calls to pre(), parse(), - and post_hello(). The call to parse() - perform the actual XML parsing while the calls to pre() and - post_hello() make sure that the parser for the root - element can perform proper initialization and cleanup.

- -

While our parser implementation and test driver are pretty small and - easy to write by hand, for bigger XML vocabularies it can be a - substantial effort. To help with this task XSD can automatically - generate sample parser implementations and a test driver from your - schemas. You can request the generation of a sample implementation with - empty function bodies by specifying the --generate-noop-impl - option. Or you can generate a sample implementation that prints the - data store in XML by using the --generate-print-impl - option. To request the generation of a test driver you can use the - --generate-test-driver option. For more information - on these options refer to the - XSD - Compiler Command Line Manual. The 'generated' example - in the XSD distribution shows the sample implementation generation - feature in action.

- - -

2.4 Compiling and Running

- -

After saving all the parts from the previous section in - driver.cxx, we are ready to compile our first - application and run it on the test XML document. On a UNIX - system this can be done with the following commands: -

- -
-$ c++ -I.../libxsd -c driver.cxx hello-pskel.cxx
-$ c++ -o driver driver.o hello-pskel.o -lexpat
-$ ./driver hello.xml
-Hello, sun!
-Hello, moon!
-Hello, world!
-  
- -

Here .../libxsd represents the path to the - libxsd directory in the XSD distribution. - We can also test the error handling. To test XML well-formedness - checking, we can try to parse hello-pskel.hxx:

- -
-$ ./driver hello-pskel.hxx
-hello-pskel.hxx:1:0: not well-formed (invalid token)
-  
- -

We can also try to parse a valid XML but not from our - vocabulary, for example hello.xsd:

- -
-$ ./driver hello.xsd
-hello.xsd:2:0: expected element 'hello' instead of
-'http://www.w3.org/2001/XMLSchema#schema'
-  
- - - - - -

3 Parser Skeletons

- -

As we have seen in the previous chapter, the XSD compiler generates - a parser skeleton class for each type defined in XML Schema. In - this chapter we will take a closer look at different functions - that comprise a parser skeleton as well as the way to connect - our implementations of these parser skeletons to create a complete - parser.

- -

In this and subsequent chapters we will use the following schema - that describes a collection of person records. We save it in - people.xsd:

- -
-<?xml version="1.0"?>
-<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
-
-  <xs:simpleType name="gender">
-    <xs:restriction base="xs:string">
-      <xs:enumeration value="male"/>
-      <xs:enumeration value="female"/>
-    </xs:restriction>
-  </xs:simpleType>
-
-  <xs:complexType name="person">
-    <xs:sequence>
-      <xs:element name="first-name" type="xs:string"/>
-      <xs:element name="last-name" type="xs:string"/>
-      <xs:element name="gender" type="gender"/>
-      <xs:element name="age" type="xs:short"/>
-    </xs:sequence>
-  </xs:complexType>
-
-  <xs:complexType name="people">
-    <xs:sequence>
-      <xs:element name="person" type="person" maxOccurs="unbounded"/>
-    </xs:sequence>
-  </xs:complexType>
-
-  <xs:element name="people" type="people"/>
-
-</xs:schema>
-  
- -

A sample XML instance to go along with this schema is saved - in people.xml:

- -
-<?xml version="1.0"?>
-<people>
-  <person>
-    <first-name>John</first-name>
-    <last-name>Doe</last-name>
-    <gender>male</gender>
-    <age>32</age>
-  </person>
-  <person>
-    <first-name>Jane</first-name>
-    <last-name>Doe</last-name>
-    <gender>female</gender>
-    <age>28</age>
-  </person>
-</people>
-  
- -

Compiling people.xsd with the XSD compiler results - in three parser skeletons being generated: gender_pskel, - person_pskel, and people_pskel. We are going - to examine and implement each of them in the subsequent sections.

- -

3.1 Implementing the Gender Parser

- -

The generated gender_pskel parser skeleton looks like - this:

- -
-class gender_pskel: public virtual xml_schema::string_pskel
-{
-public:
-  // Parser callbacks. Override them in your implementation.
-  //
-  virtual void
-  pre ();
-
-  virtual void
-  post_gender ();
-};
-  
- -

Notice that gender_pskel inherits from - xml_schema::string_skel which is a parser skeleton - for built-in XML Schema type string and is - predefined in the XSD runtime library. This is an example - of the general rule that parser skeletons follow: if a type - in XML Schema inherits from another then there will be an - equivalent inheritance between the corresponding parser - skeleton classes.

- -

The pre() and post_gender() callbacks - should look familiar from the previous chapter. Let's now - implement the parser. Our implementation will simply print - the gender to cout:

- - -
-class gender_pimpl: public gender_pskel,
-                    public xml_schema::string_pimpl
-{
-public:
-  virtual void
-  post_gender ()
-  {
-    std::string s = post_string ();
-    cout << "gender: " << s << endl;
-  }
-};
-  
- -

While the code is quite short, there is a lot going on. First, - notice that we are inheriting from gender_pskel and - from xml_schema::string_pimpl. We've encountered - xml_schema::string_pimpl already; it is an - implementation of the xml_schema::string_pskel parser - skeleton for built-in XML Schema type string.

- -

This is another common theme in the C++/Parser programming model: - reusing implementations of the base parsers in the derived ones with - the C++ mixin idiom. In our case, string_pimpl will - do all the dirty work of extracting the data and we can just get - it at the end with the call to post_string().

- -

In case you are curious, here is what - xml_schema::string_pskel and - xml_schema::string_pimpl look like:

- -
-namespace xml_schema
-{
-  class string_pskel: public simple_content
-  {
-  public:
-    virtual std::string
-    post_string () = 0;
-  };
-
-  class string_pimpl: public virtual string_pskel
-  {
-  public:
-    virtual void
-    _pre ();
-
-    virtual void
-    _characters (const xml_schema::ro_string&);
-
-    virtual std::string
-    post_string ();
-
-  protected:
-    std::string str_;
-  };
-}
-  
- -

There are three new pieces in this code that we haven't seen yet. - They are the simple_content class as well as - the _pre() and _characters() functions. - The simple_content class is defined in the XSD - runtime and is a base class for all parser skeletons that conform - to the simple content model in XML Schema. Types with the - simple content model cannot have nested elements—only text - and attributes. There is also the complex_content - class which corresponds to the complex content mode (types with - nested elements, for example, person from - people.xsd).

- -

The _pre() function is a parser callback. Remember we - talked about the pre() and post_*() callbacks - in the previous chapter? There are actually two more callbacks - with similar roles: _pre() and _post (). - As a result, each parser skeleton has four special callbacks:

- -
-  virtual void
-  pre ();
-
-  virtual void
-  _pre ();
-
-  virtual void
-  _post ();
-
-  virtual void
-  post_name ();
-  
- -

pre() and _pre() are initialization - callbacks. They get called in that order before a new instance of the type - is about to be parsed. The difference between pre() and - _pre() is conventional: pre() can - be completely overridden by a derived parser. The derived - parser can also override _pre() but has to always call - the original version. This allows you to partition initialization - into customizable and required parts.

- -

Similarly, _post() and post_name() are - finalization callbacks with exactly the same semantics: - post_name() can be completely overridden by the derived - parser while the original _post() should always be called. -

- -

The final bit we need to discuss in this section is the - _characters() function. As you might have guessed, it - is also a callback. A low-level one that delivers raw character content - for the type being parsed. You will seldom need to use this callback - directly. Using implementations for the built-in parsers provided by - the XSD runtime is usually a simpler and more convenient - alternative.

- -

At this point you might be wondering why some post_*() - callbacks, for example post_string(), return some data - while others, for example post_gender(), have - void as a return type. This is a valid concern - and it will be addressed in the next chapter.

- -

3.2 Implementing the Person Parser

- -

The generated person_pskel parser skeleton looks like - this:

- -
-class person_pskel: public xml_schema::complex_content
-{
-public:
-  // Parser callbacks. Override them in your implementation.
-  //
-  virtual void
-  pre ();
-
-  virtual void
-  first_name (const std::string&);
-
-  virtual void
-  last_name (const std::string&);
-
-  virtual void
-  gender ();
-
-  virtual void
-  age (short);
-
-  virtual void
-  post_person ();
-
-  // Parser construction API.
-  //
-  void
-  first_name_parser (xml_schema::string_pskel&);
-
-  void
-  last_name_parser (xml_schema::string_pskel&);
-
-  void
-  gender_parser (gender_pskel&);
-
-  void
-  age_parser (xml_schema::short_pskel&);
-
-  void
-  parsers (xml_schema::string_pskel& /* first-name */,
-           xml_schema::string_pskel& /* last-name */,
-           gender_pskel&             /* gender */,
-           xml_schema::short_pskel&  /* age */);
-};
-  
- - -

As you can see, we have a parser callback for each of the nested - elements found in the person XML Schema type. - The implementation of this parser is straightforward:

- -
-class person_pimpl: public person_pskel
-{
-public:
-  virtual void
-  first_name (const std::string& n)
-  {
-    cout << "first: " << f << endl;
-  }
-
-  virtual void
-  last_name (const std::string& l)
-  {
-    cout << "last: " << l << endl;
-  }
-
-  virtual void
-  age (short a)
-  {
-    cout << "age: " << a << endl;
-  }
-};
-  
- -

Notice that we didn't override the gender() callback - because all the printing is done by gender_pimpl.

- - -

3.3 Implementing the People Parser

- -

The generated people_pskel parser skeleton looks like - this:

- -
-class people_pskel: public xml_schema::complex_content
-{
-public:
-  // Parser callbacks. Override them in your implementation.
-  //
-  virtual void
-  pre ();
-
-  virtual void
-  person ();
-
-  virtual void
-  post_people ();
-
-  // Parser construction API.
-  //
-  void
-  person_parser (person_pskel&);
-
-  void
-  parsers (person_pskel& /* person */);
-};
-  
- -

The person() callback will be called after parsing each - person element. While person_pimpl does - all the printing, one useful thing we can do in this callback is to - print an extra newline after each person record so that our - output is more readable:

- -
-class people_pimpl: public people_pskel
-{
-public:
-  virtual void
-  person ()
-  {
-    cout << endl;
-  }
-};
-  
- -

Now it is time to put everything together.

- - -

3.4 Connecting the Parsers Together

- -

At this point we have all the individual parsers implemented - and can proceed to assemble them into a complete parser - for our XML vocabulary. The first step is to instantiate - all the individual parsers that we will need:

- -
-xml_schema::short_pimpl short_p;
-xml_schema::string_pimpl string_p;
-
-gender_pimpl gender_p;
-person_pimpl person_p;
-people_pimpl people_p;
-  
- -

Notice that our schema uses two built-in XML Schema types: - string for the first-name and - last-name elements as well as short - for age. We will use predefined parsers that - come with the XSD runtime to handle these types. The next - step is to connect all the individual parsers. We do this - with the help of functions defined in the parser - skeletons and marked with the "Parser Construction API" - comment. One way to do it is to connect each individual - parser by calling the *_parser() functions:

- -
-person_p.first_name_parser (string_p);
-person_p.last_name_parser (string_p);
-person_p.gender_parser (gender_p);
-person_p.age_parser (short_p);
-
-people_p.person_parser (person_p);
-  
- -

You might be wondering what happens if you do not provide - a parser by not calling one of the *_parser() functions. - In that case the corresponding XML content will be skipped, - including validation. This is an efficient way to ignore parts - of the document that you are not interested in.

- - -

An alternative, shorter, way to connect the parsers is by using - the parsers() functions which connects all the parsers - for a given type at once:

- -
-person_p.parsers (string_p, string_p, gender_p, short_p);
-people_p.parsers (person_p);
-  
- -

The following figure illustrates the resulting connections. Notice - the correspondence between return types of the post_*() - functions and argument types of element callbacks that are connected - by the arrows.

- - -
- -

The last step is the construction of the document parser and - invocation of the complete parser on our sample XML instance:

- -
-xml_schema::document doc_p (people_p, "people");
-
-people_p.pre ();
-doc_p.parse ("people.xml");
-people_p.post_people ();
-  
- -

Let's consider xml_schema::document in - more detail. While the exact definition of this class - varies depending on the underlying parser selected, - here is the common part:

- -
-namespace xml_schema
-{
-  class document
-  {
-  public:
-    document (xml_schema::parser_base&,
-              const std::string& root_element_name,
-              bool polymorphic = false);
-
-    document (xml_schema::parser_base&,
-              const std::string& root_element_namespace,
-              const std::string& root_element_name,
-              bool polymorphic = false);
-
-    void
-    parse (const std::string& file);
-
-    void
-    parse (std::istream&);
-
-    ...
-
-  };
-}
-  
- -

xml_schema::document is a root parser for - the vocabulary. The first argument to its constructors is the - parser for the type of the root element (people_impl - in our case). Because a type parser is only concerned with - the element's content and not with the element's name, we need - to specify the root element's name somewhere. That's - what is passed as the second and third arguments to the - document's constructors.

- -

There are also two overloaded parse() functions - defined in the document class (there are actually - more but the others are specific to the underlying XML parser). - The first version parses a local file identified by a name. The - second version reads the data from an input stream. For more - information on the xml_schema::document class - refer to Chapter 7, "Document Parser and Error - Handling".

- -

Let's now consider a step-by-step list of actions that happen - as we parse through people.xml. The content of - people.xml is repeated below for convenience.

- -
-<?xml version="1.0"?>
-<people>
-  <person>
-    <first-name>John</first-name>
-    <last-name>Doe</last-name>
-    <gender>male</gender>
-    <age>32</age>
-  </person>
-  <person>
-    <first-name>Jane</first-name>
-    <last-name>Doe</last-name>
-    <gender>female</gender>
-    <age>28</age>
-  </person>
-</people>
-  
- - -
    -
  1. people_p.pre() is called from - main(). We did not provide any implementation - for this callback so this call is a no-op.
  2. - -
  3. doc_p.parse("people.xml") is called from - main(). The parser opens the file and starts - parsing its content.
  4. - -
  5. The parser encounters the root element. doc_p - verifies that the root element is correct and calls - _pre() on people_p which is also - a no-op. Parsing is now delegated to people_p.
  6. - -
  7. The parser encounters the person element. - people_p determines that person_p - is responsible for parsing this element. pre() - and _pre() callbacks are called on person_p. - Parsing is now delegated to person_p.
  8. - -
  9. The parser encounters the first-name element. - person_p determines that string_p - is responsible for parsing this element. pre() - and _pre() callbacks are called on string_p. - Parsing is now delegated to string_p.
  10. - -
  11. The parser encounters character content consisting of - "John". The _characters() callback is - called on string_p.
  12. - -
  13. The parser encounters the end of first-name - element. The _post() and post_string() - callbacks are called on string_p. The - first_name() callback is called on person_p - with the return value of post_string(). The - first_name() implementation prints - "first: John" to cout. - Parsing is now returned to person_p.
  14. - -
  15. Steps analogous to 5-7 are performed for the last-name, - gender, and age elements.
  16. - -
  17. The parser encounters the end of person - element. The _post() and post_person() - callbacks are called on person_p. The - person() callback is called on people_p. - The person() implementation prints a new line - to cout. Parsing is now returned to - people_p.
  18. - -
  19. Steps 4-9 are performed for the second person - element.
  20. - -
  21. The parser encounters the end of people - element. The _post() callback is called on - people_p. The doc_p.parse("people.xml") - call returns to main().
  22. - -
  23. people_p.post_people() is called from - main() which is a no-op.
  24. - -
- - - - - -

4 Type Maps

- -

There are many useful things you can do inside parser callbacks as they - are right now. There are, however, times when you want to propagate - some information from one parser to another or to the caller of the - parser. One common task that would greatly benefit from such a - possibility is building a tree-like in-memory object model of the - data stored in XML. During execution, each individual sub-parser - would create a sub-tree and return it to its parent parser - which can then incorporate this sub-tree into the whole tree.

- -

In this chapter we will discuss the mechanisms offered by the - C++/Parser mapping for returning information from individual - parsers and see how to use them to build an object model - of our people vocabulary.

- -

4.1 Object Model

- -

An object model for our person record example could - look like this (saved in the people.hxx file):

- -
-#include <string>
-#include <vector>
-
-enum gender
-{
-  male,
-  female
-};
-
-class person
-{
-public:
-  person (const std::string& first,
-          const std::string& last,
-          ::gender gender,
-          short age)
-    : first_ (first), last_ (last),
-      gender_ (gender), age_ (age)
-  {
-  }
-
-  const std::string&
-  first () const
-  {
-    return first_;
-  }
-
-  const std::string&
-  last () const
-  {
-    return last_;
-  }
-
-  ::gender
-  gender () const
-  {
-    return gender_;
-  }
-
-  short
-  age () const
-  {
-    return age_;
-  }
-
-private:
-  std::string first_;
-  std::string last_;
-  ::gender gender_;
-  short age_;
-};
-
-typedef std::vector<person> people;
-  
- -

While it is clear which parser is responsible for which part of - the object model, it is not exactly clear how, for - example, gender_pimpl will deliver gender - to person_pimpl. You might have noticed that - string_pimpl manages to deliver its value to the - first_name() callback of person_pimpl. Let's - see how we can utilize the same mechanism to propagate our - own data.

- -

There is a way to tell the XSD compiler that you want to - exchange data between parsers. More precisely, for each - type defined in XML Schema, you can tell the compiler two things. - First, the return type of the post_*() callback - in the parser skeleton generated for this type. And, second, - the argument type for callbacks corresponding to elements and - attributes of this type. For example, for XML Schema type - gender we can specify the return type for - post_gender() in the gender_pskel - skeleton and the argument type for the gender() callback - in the person_pskel skeleton. As you might have guessed, - the generated code will then pass the return value from the - post_*() callback as an argument to the element or - attribute callback.

- -

The way to tell the XSD compiler about these XML Schema to - C++ mappings is with type map files. Here is a simple type - map for the gender type from the previous paragraph:

- -
-include "people.hxx";
-gender ::gender ::gender;
-  
- -

The first line indicates that the generated code must include - people.hxx in order to get the definition for the - gender type. The second line specifies that both - argument and return types for the gender - XML Schema type should be the ::gender C++ enum - (we use fully-qualified C++ names to avoid name clashes). - The next section will describe the type map format in detail. - We save this type map in people.map and - then translate our schemas with the --type-map - option to let the XSD compiler know about our type map:

- -
-$ xsd cxx-parser --type-map people.map people.xsd
-  
- -

If we now look at the generated people-pskel.hxx, - we will see the following changes in the gender_pskel and - person_pskel skeletons:

- -
-#include "people.hxx"
-
-class gender_pskel: public virtual xml_schema::string_pskel
-{
-  virtual ::gender
-  post_gender () = 0;
-
-  ...
-};
-
-class person_pskel: public xml_schema::complex_content
-{
-  virtual void
-  gender (::gender);
-
-  ...
-};
-  
- -

Notice that #include "people.hxx" was added to - the generated header file from the type map to provide the - definition for the gender enum.

- -

4.2 Type Map File Format

- -

Type map files are used to define a mapping between XML Schema - and C++ types. The compiler uses this information - to determine return types of post_*() - callbacks in parser skeletons corresponding to XML Schema - types as well as argument types for callbacks corresponding - to elements and attributes of these types.

- -

The compiler has a set of predefined mapping rules that map - the built-in XML Schema types to suitable C++ types (discussed - below) and all other types to void. - By providing your own type maps you can override these predefined - rules. The format of the type map file is presented below: -

- -
-namespace <schema-namespace> [<cxx-namespace>]
-{
-  (include <file-name>;)*
-  ([type] <schema-type> <cxx-ret-type> [<cxx-arg-type>];)*
-}
-  
- -

Both <schema-namespace> and - <schema-type> are regex patterns while - <cxx-namespace>, - <cxx-ret-type>, and - <cxx-arg-type> are regex pattern - substitutions. All names can be optionally enclosed in - " ", for example, to include white-spaces.

- -

<schema-namespace> determines XML - Schema namespace. Optional <cxx-namespace> - is prefixed to every C++ type name in this namespace declaration. - <cxx-ret-type> is a C++ type name that is - used as a return type for the post_*() callback. - Optional <cxx-arg-type> is an argument - type for callbacks corresponding to elements and attributes - of this type. If <cxx-arg-type> is not - specified, it defaults to <cxx-ret-type> - if <cxx-ret-type> ends with * or - & (that is, it is a pointer or a reference) and - const <cxx-ret-type>& - otherwise. - <file-name> is a file name either in the - " " or < > format - and is added with the #include directive to - the generated code.

- -

The # character starts a comment that ends - with a new line or end of file. To specify a name that contains - # enclose it in " ". - For example:

- -
-namespace http://www.example.com/xmlns/my my
-{
-  include "my.hxx";
-
-  # Pass apples by value.
-  #
-  apple apple;
-
-  # Pass oranges as pointers.
-  #
-  orange orange_t*;
-}
-  
- -

In the example above, for the - http://www.example.com/xmlns/my#orange - XML Schema type, the my::orange_t* C++ type will - be used as both return and argument types.

- -

Several namespace declarations can be specified in a single - file. The namespace declaration can also be completely - omitted to map types in a schema without a namespace. For - instance:

- -
-include "my.hxx";
-apple apple;
-
-namespace http://www.example.com/xmlns/my
-{
-  orange "const orange_t*";
-}
-  
- -

The compiler has a number of predefined mapping rules for - the built-in XML Schema types which can be presented as the - following map files. The string-based XML Schema types are - mapped to either std::string or - std::wstring depending on the character type - selected (see Section 5.2, "Character Type and - Encoding" for more information). The binary XML Schema - types are mapped to either std::auto_ptr<xml_schema::buffer> - or std::unique_ptr<xml_schema::buffer> - depending on the C++ standard selected (C++98 or C++11, - respectively; refer to the --std XSD compiler - command line option for details).

- -
-namespace http://www.w3.org/2001/XMLSchema
-{
-  boolean bool bool;
-
-  byte "signed char" "signed char";
-  unsignedByte "unsigned char" "unsigned char";
-
-  short short short;
-  unsignedShort "unsigned short" "unsigned short";
-
-  int int int;
-  unsignedInt "unsigned int" "unsigned int";
-
-  long "long long" "long long";
-  unsignedLong "unsigned long long" "unsigned long long";
-
-  integer "long long" "long long";
-
-  negativeInteger "long long" "long long";
-  nonPositiveInteger "long long" "long long";
-
-  positiveInteger "unsigned long long" "unsigned long long";
-  nonNegativeInteger "unsigned long long" "unsigned long long";
-
-  float float float;
-  double double double;
-  decimal double double;
-
-  string std::string;
-  normalizedString std::string;
-  token std::string;
-  Name std::string;
-  NMTOKEN std::string;
-  NCName std::string;
-  ID std::string;
-  IDREF std::string;
-  language std::string;
-  anyURI std::string;
-
-  NMTOKENS xml_schema::string_sequence;
-  IDREFS xml_schema::string_sequence;
-
-  QName xml_schema::qname;
-
-  base64Binary std::[auto|unique]_ptr<xml_schema::buffer>
-               std::[auto|unique]_ptr<xml_schema::buffer>;
-  hexBinary std::[auto|unique]_ptr<xml_schema::buffer>
-            std::[auto|unique]_ptr<xml_schema::buffer>;
-
-  date xml_schema::date;
-  dateTime xml_schema::date_time;
-  duration xml_schema::duration;
-  gDay xml_schema::gday;
-  gMonth xml_schema::gmonth;
-  gMonthDay xml_schema::gmonth_day;
-  gYear xml_schema::gyear;
-  gYearMonth xml_schema::gyear_month;
-  time xml_schema::time;
-}
-  
- -

For more information about the mapping of the built-in XML Schema types - to C++ types refer to Chapter 6, "Built-In XML Schema Type - Parsers". The last predefined rule maps anything that wasn't - mapped by previous rules to void:

- -
-namespace .*
-{
-  .* void void;
-}
-  
- - -

When you provide your own type maps with the - --type-map option, they are evaluated first. This - allows you to selectively override any of the predefined rules. - Note also that if you change the mapping - of a built-in XML Schema type then it becomes your responsibility - to provide the corresponding parser skeleton and implementation - in the xml_schema namespace. You can include the - custom definitions into the generated header file using the - --hxx-prologue-* options.

- -

4.3 Parser Implementations

- -

With the knowledge from the previous section, we can proceed - with creating a type map that maps types in the people.xsd - schema to our object model classes in - people.hxx. In fact, we already have the beginning - of our type map file in people.map. Let's extend - it with the rest of the types:

- -
-include "people.hxx";
-
-gender ::gender ::gender;
-person ::person;
-people ::people;
-  
- -

There are a few things to note about this type map. We did not - provide the argument types for person and - people because the default constant reference is - exactly what we need. We also did not provide any mappings - for built-in XML Schema types string and - short because they are handled by the predefined - rules and we are happy with the result. Note also that - all C++ types are fully qualified. This is done to avoid - potential name conflicts in the generated code. Now we can - recompile our schema and move on to implementing the parsers:

- -
-$ xsd cxx-parser --xml-parser expat --type-map people.map people.xsd
-  
- -

Here is the implementation of our three parsers in full. One - way to save typing when implementing your own parsers is - to open the generated code and copy the signatures of parser - callbacks into your code. Or you could always auto generate the - sample implementations and fill them with your code.

- - -
-#include "people-pskel.hxx"
-
-class gender_pimpl: public gender_pskel,
-                    public xml_schema::string_pimpl
-{
-public:
-  virtual ::gender
-  post_gender ()
-  {
-    return post_string () == "male" ? male : female;
-  }
-};
-
-class person_pimpl: public person_pskel
-{
-public:
-  virtual void
-  first_name (const std::string& f)
-  {
-    first_ = f;
-  }
-
-  virtual void
-  last_name (const std::string& l)
-  {
-    last_ = l;
-  }
-
-  virtual void
-  gender (::gender g)
-  {
-    gender_ = g;
-  }
-
-  virtual void
-  age (short a)
-  {
-    age_ = a;
-  }
-
-  virtual ::person
-  post_person ()
-  {
-    return ::person (first_, last_, gender_, age_);
-  }
-
-private:
-  std::string first_;
-  std::string last_;
-  ::gender gender_;
-  short age_;
-};
-
-class people_pimpl: public people_pskel
-{
-public:
-  virtual void
-  person (const ::person& p)
-  {
-    people_.push_back (p);
-  }
-
-  virtual ::people
-  post_people ()
-  {
-    ::people r;
-    r.swap (people_);
-    return r;
-  }
-
-private:
-  ::people people_;
-};
-  
- -

This code fragment should look familiar by now. Just note that - all the post_*() callbacks now have return types instead - of void. Here is the implementation of the test - driver for this example:

- -
-#include <iostream>
-
-using namespace std;
-
-int
-main (int argc, char* argv[])
-{
-  // Construct the parser.
-  //
-  xml_schema::short_pimpl short_p;
-  xml_schema::string_pimpl string_p;
-
-  gender_pimpl gender_p;
-  person_pimpl person_p;
-  people_pimpl people_p;
-
-  person_p.parsers (string_p, string_p, gender_p, short_p);
-  people_p.parsers (person_p);
-
-  // Parse the document to obtain the object model.
-  //
-  xml_schema::document doc_p (people_p, "people");
-
-  people_p.pre ();
-  doc_p.parse (argv[1]);
-  people ppl = people_p.post_people ();
-
-  // Print the object model.
-  //
-  for (people::iterator i (ppl.begin ()); i != ppl.end (); ++i)
-  {
-    cout << "first:  " << i->first () << endl
-         << "last:   " << i->last () << endl
-         << "gender: " << (i->gender () == male ? "male" : "female") << endl
-         << "age:    " << i->age () << endl
-         << endl;
-  }
-}
-  
- -

The parser creation and assembly part is exactly the same as in - the previous chapter. The parsing part is a bit different: - post_people() now has a return value which is the - complete object model. We store it in the - ppl variable. The last bit of the code simply iterates - over the people vector and prints the information - for each person. We save the last two code fragments to - driver.cxx and proceed to compile and test - our new application:

- - -
-$ c++ -I.../libxsd -c driver.cxx people-pskel.cxx
-$ c++ -o driver driver.o people-pskel.o -lexpat
-$ ./driver people.xml
-first:  John
-last:   Doe
-gender: male
-age:    32
-
-first:  Jane
-last:   Doe
-gender: female
-age:    28
-  
- - - - - -

5 Mapping Configuration

- -

The C++/Parser mapping has a number of configuration parameters that - determine the overall properties and behavior of the generated code. - Configuration parameters are specified with the XSD command line - options and include the C++ standard, the character type that is used - by the generated code, the underlying XML parser, whether the XML Schema - validation is performed in the generated code, and support for XML Schema - polymorphism. This chapter describes these configuration - parameters in more detail. For more ways to configure the generated - code refer to the - XSD - Compiler Command Line Manual. -

- -

5.1 C++ Standard

- -

The C++/Parser mapping provides support for ISO/IEC C++ 1998/2003 (C++98) - and ISO/IEC C++ 2011 (C++11). To select the C++ standard for the - generated code we use the --std XSD compiler command - line option. While the majority of the examples in this guide use - C++98, support for the new functionality and library components - introduced in C++11 are discussed throughout the document.

- -

5.2 Character Type and Encoding

- -

The C++/Parser mapping has built-in support for two character types: - char and wchar_t. You can select the - character type with the --char-type command line - option. The default character type is char. The - string-based built-in XML Schema types are returned as either - std::string or std::wstring depending - on the character type selected.

- -

Another aspect of the mapping that depends on the character type - is character encoding. For the char character type - the default encoding is UTF-8. Other supported encodings are - ISO-8859-1, Xerces-C++ Local Code Page (LPC), as well as - custom encodings. You can select which encoding should be used - in the object model with the --char-encoding command - line option.

- -

For the wchar_t character type the encoding is - automatically selected between UTF-16 and UTF-32/UCS-4 depending - on the size of the wchar_t type. On some platforms - (for example, Windows with Visual C++ and AIX with IBM XL C++) - wchar_t is 2 bytes long. For these platforms the - encoding is UTF-16. On other platforms wchar_t is 4 bytes - long and UTF-32/UCS-4 is used.

- -

Note also that the character encoding that is used in the object model - is independent of the encodings used in input and output XML. In fact, - all three (object mode, input XML, and output XML) can have different - encodings.

- -

5.3 Underlying XML Parser

- -

The C++/Parser mapping can be used with either Xerces-C++ or Expat - as the underlying XML parser. You can select the XML parser with - the --xml-parser command line option. Valid values - for this option are xerces and expat. - The default XML parser is Xerces-C++.

- -

The generated code is identical for both parsers except for the - xml_schema::document class in which some of the - parse() functions are parser-specific as described - in Chapter 7, "Document Parser and Error Handling".

- - -

5.4 XML Schema Validation

- -

The C++/Parser mapping provides support for validating a - commonly-used subset of W3C XML Schema in the generated code. - For the list of supported XML Schema constructs refer to - Appendix A, "Supported XML Schema Constructs".

- -

By default validation in the generated code is disabled if - the underlying XML parser is validating (Xerces-C++) and - enabled otherwise (Expat). See Section 5.3, - "Underlying XML Parser" for more information about - the underlying XML parser. You can override the default - behavior with the --generate-validation - and --suppress-validation command line options.

- - -

5.5 Support for Polymorphism

- -

By default the XSD compiler generates non-polymorphic code. If your - vocabulary uses XML Schema polymorphism in the form of xsi:type - and/or substitution groups, then you will need to compile your schemas - with the --generate-polymorphic option to produce - polymorphism-aware code as well as pass true as the last - argument to the xml_schema::document's constructors.

- -

When using the polymorphism-aware generated code, you can specify - several parsers for a single element by passing a parser map - instead of an individual parser to the parser connection function - for the element. One of the parsers will then be looked up and used - depending on the xsi:type attribute value or an element - name from a substitution group. Consider the following schema as an - example:

- -
-<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
-
-  <xs:complexType name="person">
-    <xs:sequence>
-      <xs:element name="name" type="xs:string"/>
-    </xs:sequence>
-  </xs:complexType>
-
-  <!-- substitution group root -->
-  <xs:element name="person" type="person"/>
-
-  <xs:complexType name="superman">
-    <xs:complexContent>
-      <xs:extension base="person">
-        <xs:attribute name="can-fly" type="xs:boolean"/>
-      </xs:extension>
-    </xs:complexContent>
-  </xs:complexType>
-
-  <xs:element name="superman"
-              type="superman"
-              substitutionGroup="person"/>
-
-  <xs:complexType name="batman">
-    <xs:complexContent>
-      <xs:extension base="superman">
-        <xs:attribute name="wing-span" type="xs:unsignedInt"/>
-      </xs:extension>
-    </xs:complexContent>
-  </xs:complexType>
-
-  <xs:element name="batman"
-              type="batman"
-              substitutionGroup="superman"/>
-
-  <xs:complexType name="supermen">
-    <xs:sequence>
-      <xs:element ref="person" maxOccurs="unbounded"/>
-    </xs:sequence>
-  </xs:complexType>
-
-  <xs:element name="supermen" type="supermen"/>
-
-</xs:schema>
-  
- -

Conforming XML documents can use the superman - and batman types in place of the person - type either by specifying the type with the xsi:type - attributes or by using the elements from the substitution - group, for instance:

- - -
-<supermen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
-
-  <person>
-    <name>John Doe</name>
-  </person>
-
-  <superman can-fly="false">
-    <name>James "007" Bond</name>
-  </superman>
-
-  <superman can-fly="true" wing-span="10" xsi:type="batman">
-    <name>Bruce Wayne</name>
-  </superman>
-
-</supermen>
-  
- -

To print the data stored in such XML documents we can implement - the parsers as follows:

- -
-class person_pimpl: public virtual person_pskel
-{
-public:
-  virtual void
-  pre ()
-  {
-    cout << "starting to parse person" << endl;
-  }
-
-  virtual void
-  name (const std::string& v)
-  {
-    cout << "name: " << v << endl;
-  }
-
-  virtual void
-  post_person ()
-  {
-    cout << "finished parsing person" << endl;
-  }
-};
-
-class superman_pimpl: public virtual superman_pskel,
-                      public person_pimpl
-{
-public:
-  virtual void
-  pre ()
-  {
-    cout << "starting to parse superman" << endl;
-  }
-
-  virtual void
-  can_fly (bool v)
-  {
-    cout << "can-fly: " << v << endl;
-  }
-
-  virtual void
-  post_person ()
-  {
-    post_superman ();
-  }
-
-  virtual void
-  post_superman ()
-  {
-    cout << "finished parsing superman" << endl
-  }
-};
-
-class batman_pimpl: public virtual batman_pskel,
-                    public superman_pimpl
-{
-public:
-  virtual void
-  pre ()
-  {
-    cout << "starting to parse batman" << endl;
-  }
-
-  virtual void
-  wing_span (unsigned int v)
-  {
-    cout << "wing-span: " << v << endl;
-  }
-
-  virtual void
-  post_superman ()
-  {
-    post_batman ();
-  }
-
-  virtual void
-  post_batman ()
-  {
-    cout << "finished parsing batman" << endl;
-  }
-};
-  
- -

Note that because the derived type parsers (superman_pskel - and batman_pskel) are called via the person_pskel - interface, we have to override the post_person() - virtual function in superman_pimpl to call - post_superman() and the post_superman() - virtual function in batman_pimpl to call - post_batman().

- -

The following code fragment shows how to connect the parsers together. - Notice that for the person element in the supermen_p - parser we specify a parser map instead of a specific parser and we pass - true as the last argument to the document parser constructor - to indicate that we are parsing potentially-polymorphic XML documents:

- -
-int
-main (int argc, char* argv[])
-{
-  // Construct the parser.
-  //
-  xml_schema::string_pimpl string_p;
-  xml_schema::boolean_pimpl boolean_p;
-  xml_schema::unsigned_int_pimpl unsigned_int_p;
-
-  person_pimpl person_p;
-  superman_pimpl superman_p;
-  batman_pimpl batman_p;
-
-  xml_schema::parser_map_impl person_map;
-  supermen_pimpl supermen_p;
-
-  person_p.parsers (string_p);
-  superman_p.parsers (string_p, boolean_p);
-  batman_p.parsers (string_p, boolean_p, unsigned_int_p);
-
-  // Here we are specifying a parser map which containes several
-  // parsers that can be used to parse the person element.
-  //
-  person_map.insert (person_p);
-  person_map.insert (superman_p);
-  person_map.insert (batman_p);
-
-  supermen_p.person_parser (person_map);
-
-  // Parse the XML document. The last argument to the document's
-  // constructor indicates that we are parsing polymorphic XML
-  // documents.
-  //
-  xml_schema::document doc_p (supermen_p, "supermen", true);
-
-  supermen_p.pre ();
-  doc_p.parse (argv[1]);
-  supermen_p.post_supermen ();
-}
-  
- -

When polymorphism-aware code is generated, each element's - *_parser() function is overloaded to also accept - an object of the xml_schema::parser_map type. - For example, the supermen_pskel class from the - above example looks like this:

- -
-class supermen_pskel: public xml_schema::parser_complex_content
-{
-public:
-
-  ...
-
-  // Parser construction API.
-  //
-  void
-  parsers (person_pskel&);
-
-  // Individual element parsers.
-  //
-  void
-  person_parser (person_pskel&);
-
-  void
-  person_parser (const xml_schema::parser_map&);
-
-  ...
-};
-  
- -

Note that you can specify both the individual (static) parser and - the parser map. The individual parser will be used when the static - element type and the dynamic type of the object being parsed are - the same. This is the case, for example, when there is no - xsi:type attribute and the element hasn't been - substituted. Because the individual parser for an element is - cached and no map lookup is necessary, it makes sense to specify - both the individual parser and the parser map when most of the - objects being parsed are of the static type and optimal - performance is important. The following code fragment shows - how to change the above example to set both the individual - parser and the parser map:

- -
-int
-main (int argc, char* argv[])
-{
-  ...
-
-  person_map.insert (superman_p);
-  person_map.insert (batman_p);
-
-  supermen_p.person_parser (person_p);
-  supermen_p.person_parser (person_map);
-
-  ...
-}
-  
- - -

The xml_schema::parser_map interface and the - xml_schema::parser_map_impl default implementation - are presented below:

- -
-namespace xml_schema
-{
-  class parser_map
-  {
-  public:
-    virtual parser_base*
-    find (const ro_string* type) const = 0;
-  };
-
-  class parser_map_impl: public parser_map
-  {
-  public:
-    void
-    insert (parser_base&);
-
-    virtual parser_base*
-    find (const ro_string* type) const;
-
-  private:
-    parser_map_impl (const parser_map_impl&);
-
-    parser_map_impl&
-    operator= (const parser_map_impl&);
-
-    ...
-  };
-}
-  
- -

The type argument in the find() virtual - function is the type name and namespace from the xsi:type attribute - (the namespace prefix is resolved to the actual XML namespace) - or the type of an element from the substitution group in the form - "<name> <namespace>" with the space and the - namespace part absent if the type does not have a namespace. - You can obtain a parser's dynamic type in the same format - using the _dynamic_type() function. The static - type can be obtained by calling the static _static_type() - function, for example person_pskel::_static_type(). - Both functions return a C string (const char* or - const wchar_t*, depending on the character type - used) which is valid for as long as the application is running. - The following example shows how we can implement our own parser - map using std::map:

- - -
-#include <map>
-#include <string>
-
-class parser_map: public xml_schema::parser_map
-{
-public:
- void
- insert (xml_schema::parser_base& p)
- {
-   map_[p._dynamic_type ()] = &p;
- }
-
- virtual xml_schema::parser_base*
- find (const xml_schema::ro_string* type) const
- {
-   map::const_iterator i = map_.find (type);
-   return i != map_.end () ? i->second : 0;
- }
-
-private:
-  typedef std::map<std::string, xml_schema::parser_base*> map;
-  map map_;
-};
-  
- -

Most of code presented in this section is taken from the - polymorphism example which can be found in the - examples/cxx/parser/ directory of the XSD distribution. - Handling of xsi:type and substitution groups when used - on root elements requires a number of special actions as shown in - the polyroot example.

- - - - - -

6 Built-In XML Schema Type Parsers

- -

The XSD runtime provides parser implementations for all built-in - XML Schema types as summarized in the following table. Declarations - for these types are automatically included into each generated - header file. As a result you don't need to include any headers - to gain access to these parser implementations. Note that some - parsers return either std::string or - std::wstring depending on the character type selected.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
XML Schema typeParser implementation in the xml_schema namespaceParser return type
anyType and anySimpleType types
anyTypeany_type_pimplvoid
anySimpleTypeany_simple_type_pimplvoid
fixed-length integral types
bytebyte_pimplsigned char
unsignedByteunsigned_byte_pimplunsigned char
shortshort_pimplshort
unsignedShortunsigned_short_pimplunsigned short
intint_pimplint
unsignedIntunsigned_int_pimplunsigned int
longlong_pimpllong long
unsignedLongunsigned_long_pimplunsigned long long
arbitrary-length integral types
integerinteger_pimpllong long
nonPositiveIntegernon_positive_integer_pimpllong long
nonNegativeIntegernon_negative_integer_pimplunsigned long long
positiveIntegerpositive_integer_pimplunsigned long long
negativeIntegernegative_integer_pimpllong long
boolean types
booleanboolean_pimplbool
fixed-precision floating-point types
floatfloat_pimplfloat
doubledouble_pimpldouble
arbitrary-precision floating-point types
decimaldecimal_pimpldouble
string-based types
stringstring_pimplstd::string or std::wstring
normalizedStringnormalized_string_pimplstd::string or std::wstring
tokentoken_pimplstd::string or std::wstring
Namename_pimplstd::string or std::wstring
NMTOKENnmtoken_pimplstd::string or std::wstring
NCNamencname_pimplstd::string or std::wstring
languagelanguage_pimplstd::string or std::wstring
qualified name
QNameqname_pimplxml_schema::qname
Section 6.1, - "QName Parser"
ID/IDREF types
IDid_pimplstd::string or std::wstring
IDREFidref_pimplstd::string or std::wstring
list types
NMTOKENSnmtokens_pimplxml_schema::string_sequence
Section - 6.2, "NMTOKENS and IDREFS Parsers"
IDREFSidrefs_pimplxml_schema::string_sequence
Section - 6.2, "NMTOKENS and IDREFS Parsers"
URI types
anyURIuri_pimplstd::string or std::wstring
binary types
base64Binarybase64_binary_pimplstd::[auto|unique]_ptr< xml_schema::buffer>
- Section 6.3, "base64Binary and - hexBinary Parsers"
hexBinaryhex_binary_pimplstd::[auto|unique]_ptr< xml_schema::buffer>
- Section 6.3, "base64Binary and - hexBinary Parsers"
date/time types
datedate_pimplxml_schema::date
Section 6.5, - "date Parser"
dateTimedate_time_pimplxml_schema::date_time
Section 6.6, - "dateTime Parser"
durationduration_pimplxml_schema::duration
Section 6.7, - "duration Parser"
gDaygday_pimplxml_schema::gday
Section 6.8, - "gDay Parser"
gMonthgmonth_pimplxml_schema::gmonth
Section 6.9, - "gMonth Parser"
gMonthDaygmonth_day_pimplxml_schema::gmonth_day
Section 6.10, - "gMonthDay Parser"
gYeargyear_pimplxml_schema::gyear
Section 6.11, - "gYear Parser"
gYearMonthgyear_month_pimplxml_schema::gyear_month
Section - 6.12, "gYearMonth Parser"
timetime_pimplxml_schema::time
Section 6.13, - "time Parser"
- -

6.1 QName Parser

- -

The return type of the qname_pimpl parser implementation - is xml_schema::qname which represents an XML qualified - name. Its interface is presented below. - Note that the std::string type in the interface becomes - std::wstring if the selected character type is - wchar_t.

- -
-namespace xml_schema
-{
-  class qname
-  {
-  public:
-    explicit
-    qname (const std::string& name);
-    qname (const std::string& prefix, const std::string& name);
-
-    const std::string&
-    prefix () const;
-
-    void
-    prefix (const std::string&);
-
-    const std::string&
-    name () const;
-
-    void
-    name (const std::string&);
-  };
-
-  bool
-  operator== (const qname&, const qname&);
-
-  bool
-  operator!= (const qname&, const qname&);
-}
-  
- - -

6.2 NMTOKENS and IDREFS Parsers

- -

The return type of the nmtokens_pimpl and - idrefs_pimpl parser implementations is - xml_schema::string_sequence which represents a - sequence of strings. Its interface is presented below. - Note that the std::string type in the interface becomes - std::wstring if the selected character type is - wchar_t.

- -
-namespace xml_schema
-{
-  class string_sequence: public std::vector<std::string>
-  {
-  public:
-    string_sequence ();
-
-    explicit
-    string_sequence (std::vector<std::string>::size_type n,
-                     const std::string& x = std::string ());
-
-    template <typename I>
-    string_sequence (const I& begin, const I& end);
-  };
-
-  bool
-  operator== (const string_sequence&, const string_sequence&);
-
-  bool
-  operator!= (const string_sequence&, const string_sequence&);
-}
-  
- - -

6.3 base64Binary and hexBinary Parsers

- -

The return type of the base64_binary_pimpl and - hex_binary_pimpl parser implementations is either - std::auto_ptr<xml_schema::buffer> (C++98) or - std::unique_ptr<xml_schema::buffer> (C++11), - depending on the C++ standard selected (--std XSD - compiler option). The xml_schema::buffer type - represents a binary buffer and its interface is presented below.

- -
-namespace xml_schema
-{
-  class buffer
-  {
-  public:
-    typedef std::size_t size_t;
-
-    class bounds {}; // Out of bounds exception.
-
-  public:
-    explicit
-    buffer (size_t size = 0);
-    buffer (size_t size, size_t capacity);
-    buffer (const void* data, size_t size);
-    buffer (const void* data, size_t size, size_t capacity);
-    buffer (void* data,
-            size_t size,
-            size_t capacity,
-            bool assume_ownership);
-
-  public:
-    buffer (const buffer&);
-
-    buffer&
-    operator= (const buffer&);
-
-    void
-    swap (buffer&);
-
-  public:
-    size_t
-    capacity () const;
-
-    bool
-    capacity (size_t);
-
-  public:
-    size_t
-    size () const;
-
-    bool
-    size (size_t);
-
-  public:
-    const char*
-    data () const;
-
-    char*
-    data ();
-
-    const char*
-    begin () const;
-
-    char*
-    begin ();
-
-    const char*
-    end () const;
-
-    char*
-    end ();
-  };
-
-  bool
-  operator== (const buffer&, const buffer&);
-
-  bool
-  operator!= (const buffer&, const buffer&);
-}
-  
- -

If the assume_ownership argument to the constructor - is true, the instance assumes the ownership of the - memory block pointed to by the data argument and will - eventually release it by calling operator delete(). The - capacity() and size() modifier functions - return true if the underlying buffer has moved. -

- -

The bounds exception is thrown if the constructor - arguments violate the (size <= capacity) - constraint.

- - -

6.4 Time Zone Representation

- -

The date, dateTime, gDay, - gMonth, gMonthDay, gYear, - gYearMonth, and time XML Schema built-in - types all include an optional time zone component. The following - xml_schema::time_zone base class is used to represent - this information:

- -
-namespace xml_schema
-{
-  class time_zone
-  {
-  public:
-    time_zone ();
-    time_zone (short hours, short minutes);
-
-    bool
-    zone_present () const;
-
-    void
-    zone_reset ();
-
-    short
-    zone_hours () const;
-
-    void
-    zone_hours (short);
-
-    short
-    zone_minutes () const;
-
-    void
-    zone_minutes (short);
-  };
-
-  bool
-  operator== (const time_zone&, const time_zone&);
-
-  bool
-  operator!= (const time_zone&, const time_zone&);
-}
-  
- -

The zone_present() accessor function returns true - if the time zone is specified. The zone_reset() modifier - function resets the time zone object to the not specified - state. If the time zone offset is negative then both hours and - minutes components are represented as negative integers.

- - -

6.5 date Parser

- -

The return type of the date_pimpl parser implementation - is xml_schema::date which represents a year, a day, and a month - with an optional time zone. Its interface is presented below. - For more information on the base xml_schema::time_zone - class refer to Section 6.4, "Time Zone - Representation".

- -
-namespace xml_schema
-{
-  class date
-  {
-  public:
-    date (int year, unsigned short month, unsigned short day);
-    date (int year, unsigned short month, unsigned short day,
-          short zone_hours, short zone_minutes);
-
-    int
-    year () const;
-
-    void
-    year (int);
-
-    unsigned short
-    month () const;
-
-    void
-    month (unsigned short);
-
-    unsigned short
-    day () const;
-
-    void
-    day (unsigned short);
-  };
-
-  bool
-  operator== (const date&, const date&);
-
-  bool
-  operator!= (const date&, const date&);
-}
-  
- -

6.6 dateTime Parser

- -

The return type of the date_time_pimpl parser implementation - is xml_schema::date_time which represents a year, a month, a day, - hours, minutes, and seconds with an optional time zone. Its interface - is presented below. - For more information on the base xml_schema::time_zone - class refer to Section 6.4, "Time Zone - Representation".

- -
-namespace xml_schema
-{
-  class date_time
-  {
-  public:
-    date_time (int year, unsigned short month, unsigned short day,
-               unsigned short hours, unsigned short minutes,
-               double seconds);
-
-    date_time (int year, unsigned short month, unsigned short day,
-               unsigned short hours, unsigned short minutes,
-               double seconds, short zone_hours, short zone_minutes);
-
-    int
-    year () const;
-
-    void
-    year (int);
-
-    unsigned short
-    month () const;
-
-    void
-    month (unsigned short);
-
-    unsigned short
-    day () const;
-
-    void
-    day (unsigned short);
-
-    unsigned short
-    hours () const;
-
-    void
-    hours (unsigned short);
-
-    unsigned short
-    minutes () const;
-
-    void
-    minutes (unsigned short);
-
-    double
-    seconds () const;
-
-    void
-    seconds (double);
-  };
-
-  bool
-  operator== (const date_time&, const date_time&);
-
-  bool
-  operator!= (const date_time&, const date_time&);
-}
-  
- -

6.7 duration Parser

- -

The return type of the duration_pimpl parser implementation - is xml_schema::duration which represents a potentially - negative duration in the form of years, months, days, hours, minutes, - and seconds. Its interface is presented below.

- -
-namespace xml_schema
-{
-  class duration
-  {
-  public:
-    duration (bool negative,
-              unsigned int years, unsigned int months, unsigned int days,
-              unsigned int hours, unsigned int minutes, double seconds);
-
-    bool
-    negative () const;
-
-    void
-    negative (bool);
-
-    unsigned int
-    years () const;
-
-    void
-    years (unsigned int);
-
-    unsigned int
-    months () const;
-
-    void
-    months (unsigned int);
-
-    unsigned int
-    days () const;
-
-    void
-    days (unsigned int);
-
-    unsigned int
-    hours () const;
-
-    void
-    hours (unsigned int);
-
-    unsigned int
-    minutes () const;
-
-    void
-    minutes (unsigned int);
-
-    double
-    seconds () const;
-
-    void
-    seconds (double);
-  };
-
-  bool
-  operator== (const duration&, const duration&);
-
-  bool
-  operator!= (const duration&, const duration&);
-}
-  
- - -

6.8 gDay Parser

- -

The return type of the gday_pimpl parser implementation - is xml_schema::gday which represents a day of the month with - an optional time zone. Its interface is presented below. - For more information on the base xml_schema::time_zone - class refer to Section 6.4, "Time Zone - Representation".

- -
-namespace xml_schema
-{
-  class gday
-  {
-  public:
-    explicit
-    gday (unsigned short day);
-    gday (unsigned short day, short zone_hours, short zone_minutes);
-
-    unsigned short
-    day () const;
-
-    void
-    day (unsigned short);
-  };
-
-  bool
-  operator== (const gday&, const gday&);
-
-  bool
-  operator!= (const gday&, const gday&);
-}
-  
- -

6.9 gMonth Parser

- -

The return type of the gmonth_pimpl parser implementation - is xml_schema::gmonth which represents a month of the year - with an optional time zone. Its interface is presented below. - For more information on the base xml_schema::time_zone - class refer to Section 6.4, "Time Zone - Representation".

- -
-namespace xml_schema
-{
-  class gmonth
-  {
-  public:
-    explicit
-    gmonth (unsigned short month);
-    gmonth (unsigned short month, short zone_hours, short zone_minutes);
-
-    unsigned short
-    month () const;
-
-    void
-    month (unsigned short);
-  };
-
-  bool
-  operator== (const gmonth&, const gmonth&);
-
-  bool
-  operator!= (const gmonth&, const gmonth&);
-}
-  
- -

6.10 gMonthDay Parser

- -

The return type of the gmonth_day_pimpl parser implementation - is xml_schema::gmonth_day which represents a day and a month - of the year with an optional time zone. Its interface is presented below. - For more information on the base xml_schema::time_zone - class refer to Section 6.4, "Time Zone - Representation".

- -
-namespace xml_schema
-{
-  class gmonth_day
-  {
-  public:
-    gmonth_day (unsigned short month, unsigned short day);
-    gmonth_day (unsigned short month, unsigned short day,
-                short zone_hours, short zone_minutes);
-
-    unsigned short
-    month () const;
-
-    void
-    month (unsigned short);
-
-    unsigned short
-    day () const;
-
-    void
-    day (unsigned short);
-  };
-
-  bool
-  operator== (const gmonth_day&, const gmonth_day&);
-
-  bool
-  operator!= (const gmonth_day&, const gmonth_day&);
-}
-  
- -

6.11 gYear Parser

- -

The return type of the gyear_pimpl parser implementation - is xml_schema::gyear which represents a year with - an optional time zone. Its interface is presented below. - For more information on the base xml_schema::time_zone - class refer to Section 6.4, "Time Zone - Representation".

- -
-namespace xml_schema
-{
-  class gyear
-  {
-  public:
-    explicit
-    gyear (int year);
-    gyear (int year, short zone_hours, short zone_minutes);
-
-    int
-    year () const;
-
-    void
-    year (int);
-  };
-
-  bool
-  operator== (const gyear&, const gyear&);
-
-  bool
-  operator!= (const gyear&, const gyear&);
-}
-  
- -

6.12 gYearMonth Parser

- -

The return type of the gyear_month_pimpl parser implementation - is xml_schema::gyear_month which represents a year and a month - with an optional time zone. Its interface is presented below. - For more information on the base xml_schema::time_zone - class refer to Section 6.4, "Time Zone - Representation".

- -
-namespace xml_schema
-{
-  class gyear_month
-  {
-  public:
-    gyear_month (int year, unsigned short month);
-    gyear_month (int year, unsigned short month,
-                 short zone_hours, short zone_minutes);
-
-    int
-    year () const;
-
-    void
-    year (int);
-
-    unsigned short
-    month () const;
-
-    void
-    month (unsigned short);
-  };
-
-  bool
-  operator== (const gyear_month&, const gyear_month&);
-
-  bool
-  operator!= (const gyear_month&, const gyear_month&);
-}
-  
- - -

6.13 time Parser

- -

The return type of the time_pimpl parser implementation - is xml_schema::time which represents hours, minutes, - and seconds with an optional time zone. Its interface is presented below. - For more information on the base xml_schema::time_zone - class refer to Section 6.4, "Time Zone - Representation".

- -
-namespace xml_schema
-{
-  class time
-  {
-  public:
-    time (unsigned short hours, unsigned short minutes, double seconds);
-    time (unsigned short hours, unsigned short minutes, double seconds,
-          short zone_hours, short zone_minutes);
-
-    unsigned short
-    hours () const;
-
-    void
-    hours (unsigned short);
-
-    unsigned short
-    minutes () const;
-
-    void
-    minutes (unsigned short);
-
-    double
-    seconds () const;
-
-    void
-    seconds (double);
-  };
-
-  bool
-  operator== (const time&, const time&);
-
-  bool
-  operator!= (const time&, const time&);
-}
-  
- - - - - -

7 Document Parser and Error Handling

- -

In this chapter we will discuss the xml_schema::document - type as well as the error handling mechanisms provided by the mapping - in more detail. As mentioned in Section 3.4, - "Connecting the Parsers Together", the interface of - xml_schema::document depends on the underlying XML - parser selected (Section 5.3, "Underlying XML - Parser"). The following sections describe the - document type interface for Xerces-C++ and - Expat as underlying parsers.

- -

7.1 Xerces-C++ Document Parser

- -

When Xerces-C++ is used as the underlying XML parser, the - document type has the following interface. Note that - if the character type is wchar_t, then the string type - in the interface becomes std::wstring - (see Section 5.2, "Character Type and Encoding").

- -
-namespace xml_schema
-{
-  class parser_base;
-  class error_handler;
-
-  class flags
-  {
-  public:
-    // Do not validate XML documents with the Xerces-C++ validator.
-    //
-    static const unsigned long dont_validate;
-
-    // Do not initialize the Xerces-C++ runtime.
-    //
-    static const unsigned long dont_initialize;
-
-    // Disable handling of subsequent imports for the same namespace
-    // in Xerces-C++ 3.1.0 and later.
-    //
-    static const unsigned long no_multiple_imports;
-  };
-
-  class properties
-  {
-  public:
-    // Add a location for a schema with a target namespace.
-    //
-    void
-    schema_location (const std::string& namespace_,
-                     const std::string& location);
-
-    // Add a location for a schema without a target namespace.
-    //
-    void
-    no_namespace_schema_location (const std::string& location);
-  };
-
-  class document
-  {
-  public:
-    document (parser_base& root,
-              const std::string& root_element_name,
-	      bool polymorphic = false);
-
-    document (parser_base& root,
-              const std::string& root_element_namespace,
-              const std::string& root_element_name,
-	      bool polymorphic = false);
-
-  public:
-    // Parse URI or a local file.
-    //
-    void
-    parse (const std::string& uri,
-           flags = 0,
-           const properties& = properties ());
-
-    // Parse URI or a local file with a user-provided error_handler
-    // object.
-    //
-    void
-    parse (const std::string& uri,
-           error_handler&,
-           flags = 0,
-           const properties& = properties ());
-
-    // Parse URI or a local file with a user-provided ErrorHandler
-    // object. Note that you must initialize the Xerces-C++ runtime
-    // before calling this function.
-    //
-    void
-    parse (const std::string& uri,
-           xercesc::ErrorHandler&,
-           flags = 0,
-           const properties& = properties ());
-
-    // Parse URI or a local file using a user-provided SAX2XMLReader
-    // object. Note that you must initialize the Xerces-C++ runtime
-    // before calling this function.
-    //
-    void
-    parse (const std::string& uri,
-           xercesc::SAX2XMLReader&,
-           flags = 0,
-           const properties& = properties ());
-
-  public:
-    // Parse std::istream.
-    //
-    void
-    parse (std::istream&,
-           flags = 0,
-           const properties& = properties ());
-
-    // Parse std::istream with a user-provided error_handler object.
-    //
-    void
-    parse (std::istream&,
-           error_handler&,
-           flags = 0,
-           const properties& = properties ());
-
-    // Parse std::istream with a user-provided ErrorHandler object.
-    // Note that you must initialize the Xerces-C++ runtime before
-    // calling this function.
-    //
-    void
-    parse (std::istream&,
-           xercesc::ErrorHandler&,
-           flags = 0,
-           const properties& = properties ());
-
-    // Parse std::istream using a user-provided SAX2XMLReader object.
-    // Note that you must initialize the Xerces-C++ runtime before
-    // calling this function.
-    //
-    void
-    parse (std::istream&,
-           xercesc::SAX2XMLReader&,
-           flags = 0,
-           const properties& = properties ());
-
-  public:
-    // Parse std::istream with a system id.
-    //
-    void
-    parse (std::istream&,
-           const std::string& system_id,
-           flags = 0,
-           const properties& = properties ());
-
-    // Parse std::istream with a system id and a user-provided
-    // error_handler object.
-    //
-    void
-    parse (std::istream&,
-           const std::string& system_id,
-           error_handler&,
-           flags = 0,
-           const properties& = properties ());
-
-    // Parse std::istream with a system id and a user-provided
-    // ErrorHandler object. Note that you must initialize the
-    // Xerces-C++ runtime before calling this function.
-    //
-    void
-    parse (std::istream&,
-           const std::string& system_id,
-           xercesc::ErrorHandler&,
-           flags = 0,
-           const properties& = properties ());
-
-    // Parse std::istream with a system id using a user-provided
-    // SAX2XMLReader object. Note that you must initialize the
-    // Xerces-C++ runtime before calling this function.
-    //
-    void
-    parse (std::istream&,
-           const std::string& system_id,
-           xercesc::SAX2XMLReader&,
-           flags = 0,
-           const properties& = properties ());
-
-  public:
-    // Parse std::istream with system and public ids.
-    //
-    void
-    parse (std::istream&,
-           const std::string& system_id,
-           const std::string& public_id,
-           flags = 0,
-           const properties& = properties ());
-
-    // Parse std::istream with system and public ids and a user-provided
-    // error_handler object.
-    //
-    void
-    parse (std::istream&,
-           const std::string& system_id,
-           const std::string& public_id,
-           error_handler&,
-           flags = 0,
-           const properties& = properties ());
-
-    // Parse std::istream with system and public ids and a user-provided
-    // ErrorHandler object. Note that you must initialize the Xerces-C++
-    // runtime before calling this function.
-    //
-    void
-    parse (std::istream&,
-           const std::string& system_id,
-           const std::string& public_id,
-           xercesc::ErrorHandler&,
-           flags = 0,
-           const properties& = properties ());
-
-    // Parse std::istream with system and public ids using a user-
-    // provided SAX2XMLReader object. Note that you must initialize
-    // the Xerces-C++ runtime before calling this function.
-    //
-    void
-    parse (std::istream&,
-           const std::string& system_id,
-           const std::string& public_id,
-           xercesc::SAX2XMLReader&,
-           flags = 0,
-           const properties& = properties ());
-
-  public:
-    // Parse InputSource. Note that you must initialize the Xerces-C++
-    // runtime before calling this function.
-    //
-    void
-    parse (const xercesc::InputSource&,
-           flags = 0,
-           const properties& = properties ());
-
-    // Parse InputSource with a user-provided error_handler object.
-    // Note that you must initialize the Xerces-C++ runtime before
-    // calling this function.
-    //
-    void
-    parse (const xercesc::InputSource&,
-           error_handler&,
-           flags = 0,
-           const properties& = properties ());
-
-    // Parse InputSource with a user-provided ErrorHandler object.
-    // Note that you must initialize the Xerces-C++ runtime before
-    // calling this function.
-    //
-    void
-    parse (const xercesc::InputSource&,
-           xercesc::ErrorHandler&,
-           flags = 0,
-           const properties& = properties ());
-
-    // Parse InputSource using a user-provided SAX2XMLReader object.
-    // Note that you must initialize the Xerces-C++ runtime before
-    // calling this function.
-    //
-    void
-    parse (const xercesc::InputSource&,
-           xercesc::SAX2XMLReader&,
-           flags = 0,
-           const properties& = properties ());
-  };
-}
-  
- -

The document class is a root parser for - the vocabulary. The first argument to its constructors is the - parser for the type of the root element. The parser_base - class is the base type for all parser skeletons. The second and - third arguments to the document's constructors are - the root element's name and namespace. The last argument, - polymorphic, specifies whether the XML documents - being parsed use polymorphism. For more information on support - for XML Schema polymorphism in the C++/Parser mapping refer - to Section 5.5, "Support for Polymorphism".

- -

The rest of the document interface consists of overloaded - parse() functions. The last two arguments in each of these - functions are flags and properties. The - flags argument allows you to modify the default behavior - of the parsing functions. The properties argument allows - you to override the schema location attributes specified in XML - documents. Note that the schema location paths are relative to an - XML document unless they are complete URIs. For example if you want - to use a local schema file then you will need to use a URI in the - form file:///absolute/path/to/your/schema.

- -

A number of overloaded parse() functions have the - system_id and public_id arguments. The - system id is a system identifier of the resources being - parsed (for example, URI or a full file path). The public id is a - public identifier of the resource (for example, an - application-specific name or a relative file path). The system id - is used to resolve relative paths (for example, schema paths). In - diagnostics messages the public id is used if it is available. - Otherwise the system id is used.

- -

The error handling mechanisms employed by the document - parser are described in Section 7.3, "Error - Handling".

- -

7.2 Expat Document Parser

- -

When Expat is used as the underlying XML parser, the - document type has the following interface. Note that - if the character type is wchar_t, then the string type - in the interface becomes std::wstring - (see Section 5.2, "Character Type and Encoding").

- -
-namespace xml_schema
-{
-  class parser_base;
-  class error_handler;
-
-  class document
-  {
-  public:
-    document (parser_base&,
-              const std::string& root_element_name,
-              bool polymorphic = false);
-
-    document (parser_base&,
-              const std::string& root_element_namespace,
-              const std::string& root_element_name,
-              bool polymorphic = false);
-
-  public:
-    // Parse a local file. The file is accessed with std::ifstream
-    // in binary mode. The std::ios_base::failure exception is used
-    // to report io errors (badbit and failbit).
-    void
-    parse (const std::string& file);
-
-    // Parse a local file with a user-provided error_handler
-    // object. The file is accessed with std::ifstream in binary
-    // mode. The std::ios_base::failure exception is used to report
-    // io errors (badbit and failbit).
-    //
-    void
-    parse (const std::string& file, error_handler&);
-
-  public:
-    // Parse std::istream.
-    //
-    void
-    parse (std::istream&);
-
-    // Parse std::istream with a user-provided error_handler object.
-    //
-    void
-    parse (std::istream&, error_handler&);
-
-    // Parse std::istream with a system id.
-    //
-    void
-    parse (std::istream&, const std::string& system_id);
-
-    // Parse std::istream with a system id and a user-provided
-    // error_handler object.
-    //
-    void
-    parse (std::istream&,
-           const std::string& system_id,
-           error_handler&);
-
-    // Parse std::istream with system and public ids.
-    //
-    void
-    parse (std::istream&,
-           const std::string& system_id,
-           const std::string& public_id);
-
-    // Parse std::istream with system and public ids and a user-provided
-    // error_handler object.
-    //
-    void
-    parse (std::istream&,
-           const std::string& system_id,
-           const std::string& public_id,
-           error_handler&);
-
-  public:
-    // Parse a chunk of input. You can call these functions multiple
-    // times with the last call having the last argument true.
-    //
-    void
-    parse (const void* data, std::size_t size, bool last);
-
-    void
-    parse (const void* data, std::size_t size, bool last,
-           error_handler&);
-
-    void
-    parse (const void* data, std::size_t size, bool last,
-           const std::string& system_id);
-
-    void
-    parse (const void* data, std::size_t size, bool last,
-           const std::string& system_id,
-           error_handler&);
-
-    void
-    parse (const void* data, std::size_t size, bool last,
-           const std::string& system_id,
-           const std::string& public_id);
-
-    void
-    parse (const void* data, std::size_t size, bool last,
-           const std::string& system_id,
-           const std::string& public_id,
-           error_handler&);
-
-  public:
-    // Low-level Expat-specific parsing API.
-    //
-    void
-    parse_begin (XML_Parser);
-
-    void
-    parse_begin (XML_Parser, const std::string& public_id);
-
-    void
-    parse_begin (XML_Parser, error_handler&);
-
-    void
-    parse_begin (XML_Parser,
-                 const std::string& public_id,
-                 error_handler&);
-    void
-    parse_end ();
-  };
-}
-  
- -

The document class is a root parser for - the vocabulary. The first argument to its constructors is the - parser for the type of the root element. The parser_base - class is the base type for all parser skeletons. The second and - third arguments to the document's constructors are - the root element's name and namespace. The last argument, - polymorphic, specifies whether the XML documents - being parsed use polymorphism. For more information on support - for XML Schema polymorphism in the C++/Parser mapping refer - to Section 5.5, "Support for Polymorphism".

- -

A number of overloaded parse() functions have the - system_id and public_id arguments. The - system id is a system identifier of the resources being - parsed (for example, URI or a full file path). The public id is a - public identifier of the resource (for example, an - application-specific name or a relative file path). The system id - is used to resolve relative paths. In diagnostics messages the - public id is used if it is available. Otherwise the system id - is used.

- -

The parse_begin() and parse_end() functions - present a low-level, Expat-specific parsing API for maximum control. - A typical use-case would look like this (pseudo-code):

- -
-xxx_pimpl root_p;
-document doc_p (root_p, "root");
-
-root_p.pre ();
-doc_p.parse_begin (xml_parser, "file.xml");
-
-while (more_data_to_parse)
-{
-  // Call XML_Parse or XML_ParseBuffer.
-
-  if (status == XML_STATUS_ERROR)
-    break;
-}
-
-// Call parse_end even in case of an error to translate
-// XML and Schema errors to exceptions or error_handler
-// calls.
-//
-doc.parse_end ();
-result_type result (root_p.post_xxx ());
-  
- -

Note that if your vocabulary uses XML namespaces, the - XML_ParserCreateNS() functions should be used to create - the XML parser. Space (XML_Char (' ')) should be used - as a separator (the second argument to XML_ParserCreateNS()). -

- -

The error handling mechanisms employed by the document - parser are described in Section 7.3, "Error - Handling".

- - -

7.3 Error Handling

- -

There are three categories of errors that can result from running - a parser on an XML document: System, XML, and Application. - The System category contains memory allocation and file/stream - operation errors. The XML category covers XML parsing and - well-formedness checking as well as XML Schema validation errors. - Finally, the Application category is for application logic errors - that you may want to propagate from parser implementations to the - caller of the parser. -

- -

The System errors are mapped to the standard exceptions. The - out of memory condition is indicated by throwing an instance - of std::bad_alloc. The stream operation errors - are reported either by throwing an instance of - std::ios_base::failure if exceptions are enabled - or by setting the stream state.

- -

Note that if you are parsing std::istream on - which exceptions are not enabled, then you will need to - check the stream state before calling the post() - callback, as shown in the following example:

- -
-int
-main (int argc, char* argv[])
-{
-  ...
-
-  std::ifstream ifs (argv[1]);
-
-  if (ifs.fail ())
-  {
-    cerr << argv[1] << ": unable to open" << endl;
-    return 1;
-  }
-
-  root_p.pre ();
-  doc_p.parse (ifs);
-
-  if (ifs.fail ())
-  {
-    cerr << argv[1] << ": io failure" << endl;
-    return 1;
-  }
-
-  result_type result (root_p.post_xxx ());
-}
-  
- -

The above example can be rewritten to use exceptions - as shown below:

- -
-int
-main (int argc, char* argv[])
-{
-  try
-  {
-    ...
-
-    std::ifstream ifs;
-    ifs.exceptions (std::ifstream::badbit | std::ifstream::failbit);
-    ifs.open (argv[1]);
-
-    root_p.pre ();
-    doc_p.parse (ifs);
-    result_type result (root_p.post_xxx ());
-  }
-  catch (const std::ifstream::failure&)
-  {
-    cerr << argv[1] << ": unable to open or io failure" << endl;
-    return 1;
-  }
-}
-  
- - -

For reporting application errors from parsing callbacks, you - can throw any exceptions of your choice. They are propagated to - the caller of the parser without any alterations.

- -

The XML errors can be reported either by throwing the - xml_schema::parsing exception or by a callback - to the xml_schema::error_handler object (and - xercesc::ErrorHandler object in case of Xerces-C++).

- -

The xml_schema::parsing exception contains - a list of warnings and errors that were accumulated during - parsing. Note that this exception is thrown only if there - was an error. This makes it impossible to obtain warnings - from an otherwise successful parsing using this mechanism. - The following listing shows the definition of - xml_schema::parsing exception. Note that if the - character type is wchar_t, then the string type - and output stream type in the definition become - std::wstring and std::wostream, - respectively (see Section 5.2, "Character Type - and Encoding").

- -
-namespace xml_schema
-{
-  class exception: public std::exception
-  {
-  protected:
-    virtual void
-    print (std::ostream&) const = 0;
-  };
-
-  inline std::ostream&
-  operator<< (std::ostream& os, const exception& e)
-  {
-    e.print (os);
-    return os;
-  }
-
-
-  class severity
-  {
-  public:
-    enum value
-    {
-      warning,
-      error
-    };
-  };
-
-
-  class error
-  {
-  public:
-    error (xml_schema::severity,
-           const std::string& id,
-           unsigned long line,
-           unsigned long column,
-           const std::string& message);
-
-    xml_schema::severity
-    severity () const;
-
-    const std::string&
-    id () const;
-
-    unsigned long
-    line () const;
-
-    unsigned long
-    column () const;
-
-    const std::string&
-    message () const;
-  };
-
-  std::ostream&
-  operator<< (std::ostream&, const error&);
-
-
-  class diagnostics: public std::vector<error>
-  {
-  };
-
-  std::ostream&
-  operator<< (std::ostream&, const diagnostics&);
-
-
-  class parsing: public exception
-  {
-  public:
-    parsing ();
-    parsing (const xml_schema::diagnostics&);
-
-    const xml_schema::diagnostics&
-    diagnostics () const;
-
-    virtual const char*
-    what () const throw ();
-
-  protected:
-    virtual void
-    print (std::ostream&) const;
-  };
-}
-  
- -

The following example shows how we can catch and print this - exception. The code will print diagnostics messages one per line - in case of an error.

- -
-int
-main (int argc, char* argv[])
-{
-  try
-  {
-    // Parse.
-  }
-  catch (const xml_schema::parsing& e)
-  {
-    cerr << e << endl;
-    return 1;
-  }
-}
-  
- -

With the error_handler approach the diagnostics - messages are delivered as parsing progresses. The following - listing presents the definition of the error_handler - interface. Note that if the character type is wchar_t, - then the string type in the interface becomes std::wstring - (see Section 5.2, "Character Type and Encoding").

- -
-namespace xml_schema
-{
-  class error_handler
-  {
-  public:
-    class severity
-    {
-    public:
-      enum value
-      {
-        warning,
-        error,
-        fatal
-      };
-    };
-
-    virtual bool
-    handle (const std::string& id,
-            unsigned long line,
-            unsigned long column,
-            severity,
-            const std::string& message) = 0;
-  };
-}
-  
- -

The return value of the handle() function indicates whether - parsing should continue if possible. The error with the fatal severity - level terminates the parsing process regardless of the returned value. - At the end of the parsing process with an error that was reported via - the error_handler object, an empty - xml_schema::parsing exception is thrown to indicate - the failure to the caller. You can alter this behavior by throwing - your own exception from the handle() function.

- - - - - -

Appendix A — Supported XML Schema Constructs

- -

The C++/Parser mapping supports validation of the following W3C XML - Schema constructs in the generated code.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ConstructNotes
Structure
element
attribute
any
anyAttribute
all
sequence
choice
complex type, empty content
complex type, mixed content
complex type, simple content extension
complex type, simple content restrictionSimple type facets are not validated.
complex type, complex content extension
complex type, complex content restriction
list
Datatypes
byte
unsignedByte
short
unsignedShort
int
unsignedInt
long
unsignedLong
integer
nonPositiveInteger
nonNegativeInteger
positiveInteger
negativeInteger
boolean
float
double
decimal
string
normalizedString
token
Name
NMTOKEN
NCName
language
anyURI
IDIdentity constraint is not enforced.
IDREFIdentity constraint is not enforced.
NMTOKENS
IDREFSIdentity constraint is not enforced.
QName
base64Binary
hexBinary
date
dateTime
duration
gDay
gMonth
gMonthDay
gYear
gYearMonth
time
- - -
-
- - - diff --git a/doc/cxx/parser/guide/makefile b/doc/cxx/parser/guide/makefile deleted file mode 100644 index 4fca5e9..0000000 --- a/doc/cxx/parser/guide/makefile +++ /dev/null @@ -1,55 +0,0 @@ -# file : doc/cxx/parser/guide/makefile -# license : GNU GPL v2 + exceptions; see accompanying LICENSE file - -include $(dir $(lastword $(MAKEFILE_LIST)))../../../../build/bootstrap.make - -default := $(out_base)/ -install := $(out_base)/.install -dist := $(out_base)/.dist -dist-win := $(out_base)/.dist-win -clean := $(out_base)/.clean - -# Build. -# -$(default): $(out_base)/cxx-parser-guide.ps $(out_base)/cxx-parser-guide.pdf - -$(out_base)/cxx-parser-guide.ps: $(src_base)/index.xhtml \ - $(src_base)/figure-1.png \ - $(src_base)/guide.html2ps \ - | $(out_base)/. - $(call message,html2ps $<,html2ps -f $(src_base)/guide.html2ps -o $@ $<) - -$(out_base)/cxx-parser-guide.pdf: $(out_base)/cxx-parser-guide.ps | $(out_base)/. - $(call message,ps2pdf $<,ps2pdf14 $< $@) - -# Install & Dist. -# -$(install): path := $(subst $(src_root)/doc/,,$(src_base)) -$(dist): path := $(subst $(src_root)/,,$(src_base)) - -$(install): $(out_base)/cxx-parser-guide.ps $(out_base)/cxx-parser-guide.pdf - $(call install-data,$(src_base)/figure-1.png,$(install_doc_dir)/xsd/$(path)/figure-1.png) - $(call install-data,$(src_base)/index.xhtml,$(install_doc_dir)/xsd/$(path)/index.xhtml) - $(call install-data,$(out_base)/cxx-parser-guide.ps,$(install_doc_dir)/xsd/$(path)/cxx-parser-guide.ps) - $(call install-data,$(out_base)/cxx-parser-guide.pdf,$(install_doc_dir)/xsd/$(path)/cxx-parser-guide.pdf) - -$(dist): $(out_base)/cxx-parser-guide.ps $(out_base)/cxx-parser-guide.pdf - $(call install-data,$(src_base)/figure-1.png,$(dist_prefix)/$(path)/figure-1.png) - $(call install-data,$(src_base)/index.xhtml,$(dist_prefix)/$(path)/index.xhtml) - $(call install-data,$(out_base)/cxx-parser-guide.ps,$(dist_prefix)/$(path)/cxx-parser-guide.ps) - $(call install-data,$(out_base)/cxx-parser-guide.pdf,$(dist_prefix)/$(path)/cxx-parser-guide.pdf) - -$(dist-win): $(dist) - - -# Clean -# -$(clean): -ifneq ($(xsd_clean_gen),n) - $(call message,rm $$1,rm -f $$1,$(out_base)/cxx-parser-guide.ps) - $(call message,rm $$1,rm -f $$1,$(out_base)/cxx-parser-guide.pdf) -endif - -# How to. -# -$(call include,$(bld_root)/install.make) diff --git a/doc/cxx/parser/makefile b/doc/cxx/parser/makefile deleted file mode 100644 index 7ed09eb..0000000 --- a/doc/cxx/parser/makefile +++ /dev/null @@ -1,20 +0,0 @@ -# file : doc/cxx/parser/makefile -# license : GNU GPL v2 + exceptions; see accompanying LICENSE file - -include $(dir $(lastword $(MAKEFILE_LIST)))../../../build/bootstrap.make - -docs := guide - -default := $(out_base)/ -install := $(out_base)/.install -dist := $(out_base)/.dist -dist-win := $(out_base)/.dist-win -clean := $(out_base)/.clean - -$(default): $(addprefix $(out_base)/,$(addsuffix /,$(docs))) -$(install): $(addprefix $(out_base)/,$(addsuffix /.install,$(docs))) -$(dist): $(addprefix $(out_base)/,$(addsuffix /.dist,$(docs))) -$(dist-win): $(addprefix $(out_base)/,$(addsuffix /.dist-win,$(docs))) -$(clean): $(addprefix $(out_base)/,$(addsuffix /.clean,$(docs))) - -$(foreach m,$(docs),$(call import,$(src_base)/$m/makefile)) diff --git a/doc/cxx/tree/guide/guide.html2ps b/doc/cxx/tree/guide/guide.html2ps deleted file mode 100644 index 4606eb4..0000000 --- a/doc/cxx/tree/guide/guide.html2ps +++ /dev/null @@ -1,65 +0,0 @@ -@html2ps { - option { - toc: hb; - colour: 1; - hyphenate: 1; - titlepage: 1; - } - - datefmt: "%B %Y"; - - titlepage { - content: " -
-

C++/Tree Mapping

-

Getting Started Guide

-

 

-

 

-

 

-

 

-

 

-

 

-
-

Copyright © 2009-2020 Code Synthesis Tools CC.

- -

Permission is granted to copy, distribute and/or modify this - document under the terms of the - GNU Free - Documentation License, version 1.2; with no Invariant Sections, - no Front-Cover Texts and no Back-Cover Texts. -

- -

This document is available in the following formats: - XHTML, - PDF, and - PostScript.

"; - } - - toc { - indent: 2em; - } - - header { - odd-right: $H; - even-left: $H; - } - - footer { - odd-left: $D; - odd-center: $T; - odd-right: $N; - - even-left: $N; - even-center: $T; - even-right: $D; - } -} - -body { - font-size: 12pt; - text-align: justify; -} - -pre { - font-size: 10pt; -} diff --git a/doc/cxx/tree/guide/index.xhtml b/doc/cxx/tree/guide/index.xhtml deleted file mode 100644 index 6465776..0000000 --- a/doc/cxx/tree/guide/index.xhtml +++ /dev/null @@ -1,2732 +0,0 @@ - - - - - - C++/Tree Mapping Getting Started Guide - - - - - - - - - - - - - -
-
- -
- -
-
C++/Tree Mapping
-
Getting Started Guide
- -

Copyright © 2009-2020 Code Synthesis Tools CC.

- -

Permission is granted to copy, distribute and/or modify this - document under the terms of the - GNU Free - Documentation License, version 1.2; with no Invariant Sections, - no Front-Cover Texts and no Back-Cover Texts. -

- -

This document is available in the following formats: - XHTML, - PDF, and - PostScript.

- -
- -

Table of Contents

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Preface - - - -
About This Document
More Information
-
1Introduction - - - -
1.1Mapping Overview
1.2Benefits
-
2Hello World Example - - - - - - - - -
2.1Writing XML Document and Schema
2.2Translating Schema to C++
2.3Implementing Application Logic
2.4Compiling and Running
2.5Adding Serialization
2.6Selecting Naming Convention
2.7Generating Documentation
-
3Overall Mapping Configuration - - - - - - -
3.1C++ Standard
3.2Character Type and Encoding
3.3Support for Polymorphism
3.4Namespace Mapping
3.5Thread Safety
-
4Working with Object Models - - - - - - -
4.1Attribute and Element Cardinalities
4.2Accessing the Object Model
4.3Modifying the Object Model
4.4Creating the Object Model from Scratch
4.5Mapping for the Built-in XML Schema Types
-
5Parsing - - - -
5.1XML Schema Validation and Searching
5.2Error Handling
-
6Serialization - - - -
6.1Namespace and Schema Information
6.2Error Handling
-
-
- -

Preface

- -

About This Document

- -

The goal of this document is to provide you with an understanding of - the C++/Tree programming model and allow you to efficiently evaluate - XSD against your project's technical requirements. As such, this - document is intended for C++ developers and software architects - who are looking for an XML processing solution. For a more in-depth - description of the C++/Tree mapping refer to the - C++/Tree - Mapping User Manual.

- -

Prior experience with XML and C++ is required to understand this - document. Basic understanding of XML Schema is advantageous but - not expected or required. -

- - -

More Information

- -

Beyond this guide, you may also find the following sources of - information useful:

- - - - - -

1 Introduction

- -

Welcome to CodeSynthesis XSD and the C++/Tree mapping. XSD is a - cross-platform W3C XML Schema to C++ data binding compiler. C++/Tree - is a W3C XML Schema to C++ mapping that represents the data stored - in XML as a statically-typed, vocabulary-specific object model. -

- -

1.1 Mapping Overview

- -

Based on a formal description of an XML vocabulary (schema), the - C++/Tree mapping produces a tree-like data structure suitable for - in-memory processing. The core of the mapping consists of C++ - classes that constitute the object model and are derived from - types defined in XML Schema as well as XML parsing and - serialization code.

- -

Besides the core features, C++/Tree provide a number of additional - mapping elements that can be useful in some applications. These - include serialization and extraction to/from formats others than - XML, such as unstructured text (useful for debugging) and binary - representations such as XDR and CDR for high-speed data processing - as well as automatic documentation generation. The C++/Tree mapping - also provides a wide range of mechanisms for controlling and - customizing the generated code.

- -

A typical application that uses C++/Tree for XML processing usually - performs the following three steps: it first reads (parses) an XML - document to an in-memory object model, it then performs some useful - computations on that object model which may involve modification - of the model, and finally it may write (serialize) the modified - object model back to XML.

- -

The next chapter presents a simple application that performs these - three steps. The following chapters show how to use the C++/Tree - mapping in more detail.

- -

1.2 Benefits

- -

Traditional XML access APIs such as Document Object Model (DOM) - or Simple API for XML (SAX) have a number of drawbacks that - make them less suitable for creating robust and maintainable - XML processing applications. These drawbacks include: -

- -
    -
  • Generic representation of XML in terms of elements, attributes, - and text forces an application developer to write a substantial - amount of bridging code that identifies and transforms pieces - of information encoded in XML to a representation more suitable - for consumption by the application logic.
  • - -
  • String-based flow control defers error detection to runtime. - It also reduces code readability and maintainability.
  • - -
  • Lack of type safety because the data is represented as text.
  • - -
  • Resulting applications are hard to debug, change, and - maintain.
  • -
- -

In contrast, statically-typed, vocabulary-specific object model - produced by the C++/Tree mapping allows you to operate in your - domain terms instead of the generic elements, attributes, and - text. Static typing helps catch errors at compile-time rather - than at run-time. Automatic code generation frees you for more - interesting tasks (such as doing something useful with the - information stored in the XML documents) and minimizes the - effort needed to adapt your applications to changes in the - document structure. To summarize, the C++/Tree object model has - the following key advantages over generic XML access APIs:

- -
    -
  • Ease of use. The generated code hides all the complexity - associated with parsing and serializing XML. This includes navigating - the structure and converting between the text representation and - data types suitable for manipulation by the application - logic.
  • - -
  • Natural representation. The object representation allows - you to access the XML data using your domain vocabulary instead - of generic elements, attributes, and text.
  • - -
  • Concise code. With the object representation the - application implementation is simpler and thus easier - to read and understand.
  • - -
  • Safety. The generated object model is statically - typed and uses functions instead of strings to access the - information. This helps catch programming errors at compile-time - rather than at runtime.
  • - -
  • Maintainability. Automatic code generation minimizes the - effort needed to adapt the application to changes in the - document structure. With static typing, the C++ compiler - can pin-point the places in the client code that need to be - changed.
  • - -
  • Compatibility. Sequences of elements are represented in - the object model as containers conforming to the standard C++ - sequence requirements. This makes it possible to use standard - C++ algorithms on the object representation and frees you from - learning yet another container interface, as is the case with - DOM.
  • - -
  • Efficiency. If the application makes repetitive use - of the data extracted from XML, then the C++/Tree object model - is more efficient because the navigation is performed using - function calls rather than string comparisons and the XML - data is extracted only once. Furthermore, the runtime memory - usage is reduced due to more efficient data storage - (for instance, storing numeric data as integers instead of - strings) as well as the static knowledge of cardinality - constraints.
  • -
- - - - - -

2 Hello World Example

- -

In this chapter we will examine how to parse, access, modify, and - serialize a very simple XML document using the XSD-generated - C++/Tree object model. The code presented in this chapter is - based on the hello example which can be found in - the examples/cxx/tree/ directory of the XSD - distribution.

- -

2.1 Writing XML Document and Schema

- -

First, we need to get an idea about the structure - of the XML documents we are going to process. Our - hello.xml, for example, could look like this:

- -
-<?xml version="1.0"?>
-<hello>
-
-  <greeting>Hello</greeting>
-
-  <name>sun</name>
-  <name>moon</name>
-  <name>world</name>
-
-</hello>
-  
- -

Then we can write a description of the above XML in the - XML Schema language and save it into hello.xsd:

- -
-<?xml version="1.0"?>
-<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
-
-  <xs:complexType name="hello_t">
-    <xs:sequence>
-      <xs:element name="greeting" type="xs:string"/>
-      <xs:element name="name" type="xs:string" maxOccurs="unbounded"/>
-    </xs:sequence>
-  </xs:complexType>
-
-  <xs:element name="hello" type="hello_t"/>
-
-</xs:schema>
-  
- -

Even if you are not familiar with XML Schema, it - should be easy to connect declarations in hello.xsd - to elements in hello.xml. The hello_t type - is defined as a sequence of the nested greeting and - name elements. Note that the term sequence in XML - Schema means that elements should appear in a particular order - as opposed to appearing multiple times. The name - element has its maxOccurs property set to - unbounded which means it can appear multiple times - in an XML document. Finally, the globally-defined hello - element prescribes the root element for our vocabulary. For an - easily-approachable introduction to XML Schema refer to - XML Schema Part 0: - Primer.

- -

The above schema is a specification of our XML vocabulary; it tells - everybody what valid documents of our XML-based language should look - like. We can also update our hello.xml to include the - information about the schema so that XML parsers can validate - our document:

- -
-<?xml version="1.0"?>
-<hello xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-       xsi:noNamespaceSchemaLocation="hello.xsd">
-
-  <greeting>Hello</greeting>
-
-  <name>sun</name>
-  <name>moon</name>
-  <name>world</name>
-
-</hello>
-      
- - -

The next step is to compile the schema to generate the object - model and parsing functions.

- -

2.2 Translating Schema to C++

- -

Now we are ready to translate our hello.xsd to C++. - To do this we invoke the XSD compiler from a terminal (UNIX) or - a command prompt (Windows): -

- -
-$ xsd cxx-tree hello.xsd
-  
- -

The XSD compiler produces two C++ files: hello.hxx and - hello.cxx. The following code fragment is taken from - hello.hxx; it should give you an idea about what gets - generated: -

- -
-class hello_t
-{
-public:
-  // greeting
-  //
-  typedef xml_schema::string greeting_type;
-
-  const greeting_type&
-  greeting () const;
-
-  greeting_type&
-  greeting ();
-
-  void
-  greeting (const greeting_type& x);
-
-  // name
-  //
-  typedef xml_schema::string name_type;
-  typedef xsd::sequence<name_type> name_sequence;
-  typedef name_sequence::iterator name_iterator;
-  typedef name_sequence::const_iterator name_const_iterator;
-
-  const name_sequence&
-  name () const;
-
-  name_sequence&
-  name ();
-
-  void
-  name (const name_sequence& s);
-
-  // Constructor.
-  //
-  hello_t (const greeting_type&);
-
-  ...
-
-};
-
-std::auto_ptr<hello_t>
-hello (const std::string& uri);
-
-std::auto_ptr<hello_t>
-hello (std::istream&);
-  
- -

The hello_t C++ class corresponds to the - hello_t XML Schema type. For each element - in this type a set of C++ type definitions as well as - accessor and modifier functions are generated inside the - hello_t class. Note that the type definitions - and member functions for the greeting and - name elements are different because of the - cardinality differences between these two elements - (greeting is a required single element and - name is a sequence of elements).

- -

The xml_schema::string type used in the type - definitions is a C++ class provided by the XSD runtime - that corresponds to built-in XML Schema type - string. The xml_schema::string - is based on std::string and can be used as - such. Similarly, the sequence class template - that is used in the name_sequence type - definition is based on and has the same interface as - std::vector. The mapping between the built-in - XML Schema types and C++ types is described in more detail in - Section 4.5, "Mapping for the Built-in XML Schema - Types". The hello_t class also includes a - constructor with an initializer for the required - greeting element as its argument.

- -

The hello overloaded global functions correspond - to the hello global element in XML Schema. A - global element in XML Schema is a valid document root. - By default XSD generated a set of parsing functions for each - global element defined in XML Schema (this can be overridden - with the --root-element-* options). Parsing - functions return a dynamically allocated object model as an - automatic pointer. The actual pointer used depends on the - C++ standard selected. For C++98 it is std::auto_ptr - as shown above. For C++11 it is std::unique_ptr. - For example, if we modify our XSD compiler invocation to - select C++11:

- -
-$ xsd cxx-tree --std c++11 hello.xsd
-  
- -

Then the parsing function signatures will become:

- -
-std::unique_ptr<hello_t>
-hello (const std::string& uri);
-
-std::unique_ptr<hello_t>
-hello (std::istream&);
-  
- -

For more information on parsing functions see Chapter 5, - "Parsing".

- -

2.3 Implementing Application Logic

- -

At this point we have all the parts we need to do something useful - with the information stored in our XML document: -

- -
-#include <iostream>
-#include "hello.hxx"
-
-using namespace std;
-
-int
-main (int argc, char* argv[])
-{
-  try
-  {
-    auto_ptr<hello_t> h (hello (argv[1]));
-
-    for (hello_t::name_const_iterator i (h->name ().begin ());
-         i != h->name ().end ();
-         ++i)
-    {
-      cerr << h->greeting () << ", " << *i << "!" << endl;
-    }
-  }
-  catch (const xml_schema::exception& e)
-  {
-    cerr << e << endl;
-    return 1;
-  }
-}
-  
- -

The first part of our application calls one of the parsing - functions to parser an XML file specified in the command line. - We then use the returned object model to iterate over names - and print a greeting line for each of them. Finally, we - catch and print the xml_schema::exception - exception in case something goes wrong. This exception - is the root of the exception hierarchy used by the - XSD-generated code. -

- - -

2.4 Compiling and Running

- -

After saving our application from the previous section in - driver.cxx, we are ready to compile our first - program and run it on the test XML document. On a UNIX - system this can be done with the following commands: -

- -
-$ c++ -I.../libxsd -c driver.cxx hello.cxx
-$ c++ -o driver driver.o hello.o -lxerces-c
-$ ./driver hello.xml
-Hello, sun!
-Hello, moon!
-Hello, world!
-  
- -

Here .../libxsd represents the path to the - libxsd directory in the XSD distribution. - Note also that we are required to link our application - with the Xerces-C++ library because the generated code - uses it as the underlying XML parser.

- -

2.5 Adding Serialization

- -

While parsing and accessing the XML data may be everything - you need, there are applications that require creating new - or modifying existing XML documents. By default XSD does - not produce serialization code. We will need to request - it with the --generate-serialization options:

- -
-$ xsd cxx-tree --generate-serialization hello.xsd
-  
- -

If we now examine the generated hello.hxx file, - we will find a set of overloaded serialization functions, - including the following version:

- -
-void
-hello (std::ostream&,
-       const hello_t&,
-       const xml_schema::namespace_infomap& =
-         xml_schema::namespace_infomap ());
-
-  
- -

Just like with parsing functions, XSD generates serialization - functions for each global element unless instructed otherwise - with one of the --root-element-* options. For more - information on serialization functions see Chapter 6, - "Serialization".

- -

We first examine an application that modifies an existing - object model and serializes it back to XML:

- -
-#include <iostream>
-#include "hello.hxx"
-
-using namespace std;
-
-int
-main (int argc, char* argv[])
-{
-  try
-  {
-    auto_ptr<hello_t> h (hello (argv[1]));
-
-    // Change the greeting phrase.
-    //
-    h->greeting ("Hi");
-
-    // Add another entry to the name sequence.
-    //
-    h->name ().push_back ("mars");
-
-    // Serialize the modified object model to XML.
-    //
-    xml_schema::namespace_infomap map;
-    map[""].name = "";
-    map[""].schema = "hello.xsd";
-
-    hello (cout, *h, map);
-  }
-  catch (const xml_schema::exception& e)
-  {
-    cerr << e << endl;
-    return 1;
-  }
-}
-  
- -

First, our application parses an XML document and obtains its - object model as in the previous example. Then it changes the - greeting string and adds another entry to the list of names. - Finally, it serializes the object model back to XML by calling - the serialization function.

- -

The first argument we pass to the serialization function is - cout which results in the XML being written to - the standard output for us to inspect. We could have also - written the result to a file or memory buffer by creating an - instance of std::ofstream or std::ostringstream - and passing it instead of cout. The second argument is the - object model we want to serialize. The final argument is an optional - namespace information map for our vocabulary. It captures information - such as namespaces, namespace prefixes to which they should be mapped, - and schemas associated with these namespaces. If we don't provide - this argument then generic namespace prefixes (p1, - p2, etc.) will be automatically assigned to XML namespaces - and no schema information will be added to the resulting document - (see Chapter 6, "Serialization" for details). - In our case, the prefix (map key) and namespace name are empty - because our vocabulary does not use XML namespaces.

- -

If we now compile and run this application we will see the - output as shown in the following listing:

- -
-<?xml version="1.0"?>
-<hello xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-       xsi:noNamespaceSchemaLocation="hello.xsd">
-
-  <greeting>Hi</greeting>
-
-  <name>sun</name>
-  <name>moon</name>
-  <name>world</name>
-  <name>mars</name>
-
-</hello>
-  
- -

We can also create and serialize an object model from scratch - as shown in the following example:

- -
-#include <iostream>
-#include <fstream>
-#include "hello.hxx"
-
-using namespace std;
-
-int
-main (int argc, char* argv[])
-{
-  try
-  {
-    hello_t h ("Hi");
-
-    hello_t::name_sequence& ns (h.name ());
-
-    ns.push_back ("Jane");
-    ns.push_back ("John");
-
-    // Serialize the object model to XML.
-    //
-    xml_schema::namespace_infomap map;
-    map[""].name = "";
-    map[""].schema = "hello.xsd";
-
-    std::ofstream ofs (argv[1]);
-    hello (ofs, h, map);
-  }
-  catch (const xml_schema::exception& e)
-  {
-    cerr << e << endl;
-    return 1;
-  }
-}
-  
- -

In this example we used the generated constructor to create - an instance of type hello_t. To reduce typing, - we obtained a reference to the name sequence which we then - used to add a few names. The serialization part is identical - to the previous example except this time we are writing to - a file. If we compile and run this program, it produces the - following XML file:

- -
-<?xml version="1.0"?>
-<hello xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-       xsi:noNamespaceSchemaLocation="hello.xsd">
-
-  <greeting>Hi</greeting>
-
-  <name>Jane</name>
-  <name>John</name>
-
-</hello>
-  
- -

2.6 Selecting Naming Convention

- -

By default XSD uses the so-called K&R (Kernighan and Ritchie) - identifier naming convention in the generated code. In this - convention both type and function names are in lower case and - words are separated by underscores. If your application code or - schemas use a different notation, you may want to change the - naming convention used in the generated code for consistency. - XSD supports a set of widely-used naming conventions - that you can select with the --type-naming and - --function-naming options. You can also further - refine one of the predefined conventions or create a completely - custom naming scheme by using the --*-regex options.

- -

As an example, let's assume that our "Hello World" application - uses the so-called upper-camel-case naming convention for types - (that is, each word in a type name is capitalized) and the K&R - convention for function names. Since K&R is the default - convention for both type and function names, we only need to - change the type naming scheme:

- -
-$ xsd cxx-tree --type-naming ucc hello.xsd
-  
- -

The ucc argument to the --type-naming - options stands for upper-camel-case. If we now examine the - generated hello.hxx, we will see the following - changes compared to the declarations shown in the previous - sections:

- -
-class Hello_t
-{
-public:
-  // greeting
-  //
-  typedef xml_schema::String GreetingType;
-
-  const GreetingType&
-  greeting () const;
-
-  GreetingType&
-  greeting ();
-
-  void
-  greeting (const GreetingType& x);
-
-  // name
-  //
-  typedef xml_schema::String NameType;
-  typedef xsd::sequence<NameType> NameSequence;
-  typedef NameSequence::iterator NameIterator;
-  typedef NameSequence::const_iterator NameConstIterator;
-
-  const NameSequence&
-  name () const;
-
-  NameSequence&
-  name ();
-
-  void
-  name (const NameSequence& s);
-
-  // Constructor.
-  //
-  Hello_t (const GreetingType&);
-
-  ...
-
-};
-
-std::auto_ptr<Hello_t>
-hello (const std::string& uri);
-
-std::auto_ptr<Hello_t>
-hello (std::istream&);
-  
- -

Notice that the type names in the xml_schema namespace, - for example xml_schema::String, now also use the - upper-camel-case naming convention. The only thing that we may - be unhappy about in the above code is the _t - suffix in Hello_t. If we are not in a position - to change the schema, we can touch-up the ucc - convention with a custom translation rule using the - --type-regex option:

- -
-$ xsd cxx-tree --type-naming ucc --type-regex '/ (.+)_t/\u$1/' hello.xsd
-  
- -

This results in the following changes to the generated code:

- -
-class Hello
-{
-public:
-  // greeting
-  //
-  typedef xml_schema::String GreetingType;
-
-  const GreetingType&
-  greeting () const;
-
-  GreetingType&
-  greeting ();
-
-  void
-  greeting (const GreetingType& x);
-
-  // name
-  //
-  typedef xml_schema::String NameType;
-  typedef xsd::sequence<NameType> NameSequence;
-  typedef NameSequence::iterator NameIterator;
-  typedef NameSequence::const_iterator NameConstIterator;
-
-  const NameSequence&
-  name () const;
-
-  NameSequence&
-  name ();
-
-  void
-  name (const NameSequence& s);
-
-  // Constructor.
-  //
-  Hello (const GreetingType&);
-
-  ...
-
-};
-
-std::auto_ptr<Hello>
-hello (const std::string& uri);
-
-std::auto_ptr<Hello>
-hello (std::istream&);
-  
- -

For more detailed information on the --type-naming, - --function-naming, --type-regex, and - other --*-regex options refer to the NAMING - CONVENTION section in the XSD - Compiler Command Line Manual.

- -

2.7 Generating Documentation

- -

While our object model is quite simple, real-world vocabularies - can be quite complex with hundreds of types, elements, and - attributes. For such vocabularies figuring out which types - provide which member functions by studying the generated - source code or schemas can be a daunting task. To provide - application developers with a more accessible way of - understanding the generated object models, the XSD compiler - can be instructed to produce source code with documentation - comments in the Doxygen format. Then the source code can be - processed with the Doxygen - documentation system to extract this information and produce - documentation in various formats. -

- -

In this section we will see how to generate documentation - for our "Hello World" vocabulary. To showcase the full power - of the XSD documentation facilities, we will first document - our schema. The XSD compiler will then transfer - this information from the schema to the generated code and - then to the object model documentation. Note that the - documentation in the schema is not required for XSD to - generate useful documentation. Below you will find - our hello.xsd with added documentation:

- -
-<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
-
-  <xs:complexType name="hello_t">
-
-    <xs:annotation>
-      <xs:documentation>
-        The hello_t type consists of a greeting phrase and a
-        collection of names to which this greeting applies.
-      </xs:documentation>
-    </xs:annotation>
-
-    <xs:sequence>
-
-      <xs:element name="greeting" type="xs:string">
-        <xs:annotation>
-          <xs:documentation>
-            The greeting element contains the greeting phrase
-            for this hello object.
-          </xs:documentation>
-        </xs:annotation>
-      </xs:element>
-
-      <xs:element name="name" type="xs:string" maxOccurs="unbounded">
-        <xs:annotation>
-          <xs:documentation>
-            The name elements contains names to be greeted.
-          </xs:documentation>
-        </xs:annotation>
-      </xs:element>
-
-    </xs:sequence>
-  </xs:complexType>
-
-  <xs:element name="hello" type="hello_t">
-    <xs:annotation>
-      <xs:documentation>
-        The hello element is a root of the Hello XML vocabulary.
-        Every conforming document should start with this element.
-      </xs:documentation>
-    </xs:annotation>
-  </xs:element>
-
-</xs:schema>
-  
- -

The first step in obtaining the documentation is to recompile - our schema with the --generate-doxygen option:

- -
-$ xsd cxx-tree --generate-serialization --generate-doxygen hello.xsd
-  
- -

Now the generated hello.hxx file contains comments - in the Doxygen format. The next step is to process this file - with the Doxygen documentation system. If your project does - not use Doxygen then you first need to create a configuration - file for your project:

- -
-$ doxygen -g hello.doxygen
-  
- -

You only need to perform this step once. Now we can generate - the documentation by executing the following command in the - directory with the generated source code:

- -
-$ doxygen hello.doxygen
-  
- -

While the generated documentation can be useful as is, we can - go one step further and link (using the Doxygen tags mechanism) - the documentation for our object model with the documentation - for the XSD runtime library which defines C++ classes for the - built-in XML Schema types. This way we can seamlessly browse - between documentation for the hello_t class which - is generated by the XSD compiler and the xml_schema::string - class which is defined in the XSD runtime library. The Doxygen - configuration file for the XSD runtime is provided with the XSD - distribution.

- -

You can view the result of the steps described in this section - on the Hello - Example Documentation page.

- - - - -

3 Overall Mapping Configuration

- -

The C++/Tree mapping has a number of configuration parameters that - determine the overall properties and behavior of the generated code. - Configuration parameters are specified with the XSD command line - options. This chapter describes configuration aspects that are most - commonly encountered by application developers. These include: the - C++ standard, the character type that is used by the generated code, - handling of vocabularies that use XML Schema polymorphism, XML Schema - to C++ namespace mapping, and thread safety. For more ways to configure - the generated code refer to the - XSD - Compiler Command Line Manual. -

- -

3.1 C++ Standard

- -

The C++/Tree mapping provides support for ISO/IEC C++ 1998/2003 (C++98) - and ISO/IEC C++ 2011 (C++11). To select the C++ standard for the - generated code we use the --std XSD compiler command - line option. While the majority of the examples in this guide use - C++98, support for the new functionality and library components - introduced in C++11 are discussed throughout the document.

- -

3.2 Character Type and Encoding

- -

The C++/Tree mapping has built-in support for two character types: - char and wchar_t. You can select the - character type with the --char-type command line - option. The default character type is char. The - character type affects all string and string-based types that - are used in the mapping. These include the string-based built-in - XML Schema types, exception types, stream types, etc.

- -

Another aspect of the mapping that depends on the character type - is character encoding. For the char character type - the default encoding is UTF-8. Other supported encodings are - ISO-8859-1, Xerces-C++ Local Code Page (LPC), as well as - custom encodings. You can select which encoding should be used - in the object model with the --char-encoding command - line option.

- -

For the wchar_t character type the encoding is - automatically selected between UTF-16 and UTF-32/UCS-4 depending - on the size of the wchar_t type. On some platforms - (for example, Windows with Visual C++ and AIX with IBM XL C++) - wchar_t is 2 bytes long. For these platforms the - encoding is UTF-16. On other platforms wchar_t is 4 bytes - long and UTF-32/UCS-4 is used.

- -

Note also that the character encoding that is used in the object model - is independent of the encodings used in input and output XML. In fact, - all three (object mode, input XML, and output XML) can have different - encodings.

- -

3.3 Support for Polymorphism

- -

By default XSD generates non-polymorphic code. If your vocabulary - uses XML Schema polymorphism in the form of xsi:type - and/or substitution groups, then you will need to compile - your schemas with the --generate-polymorphic option - to produce polymorphism-aware code. For more information on - working with polymorphic object models, refer to - Section 2.11, - "Mapping for xsi:type and Substitution Groups" in - the C++/Tree Mapping User Manual.

- -

3.4 Namespace Mapping

- -

XSD maps XML namespaces specified in the targetNamespace - attribute in XML Schema to one or more nested C++ namespaces. By - default, a namespace URI is mapped to a sequence of C++ namespace - names by removing the protocol and host parts and splitting the - rest into a sequence of names with '/' as the name - separator.

- -

The default mapping of namespace URIs to C++ namespaces - can be altered using the --namespace-map and - --namespace-regex compiler options. For example, - to map namespace URI https://www.codesynthesis.com/my to - C++ namespace cs::my, we can use the following option:

- -
---namespace-map https://www.codesynthesis.com/my=cs::my
-  
- -

A vocabulary without a namespace is mapped to the global scope. This - also can be altered with the above options by using an empty name - for the XML namespace:

- -
---namespace-map =cs
-  
- -

3.5 Thread Safety

- -

XSD-generated code is thread-safe in the sense that you can - use different instantiations of the object model in several - threads concurrently. This is possible due to the generated - code not relying on any writable global variables. If you need - to share the same object between several threads then you will - need to provide some form of synchronization. One approach would - be to use the generated code customization mechanisms to embed - synchronization primitives into the generated C++ classes. For more - information on generated code customization refer to the - C++/Tree - Mapping Customization Guide.

- -

If you also would like to call parsing and/or serialization - functions from several threads potentially concurrently, then - you will need to make sure the Xerces-C++ runtime is initialized - and terminated only once. The easiest way to do this is to - initialize/terminate Xerces-C++ from main() when - there are no threads yet/anymore:

- -
-#include <xercesc/util/PlatformUtils.hpp>
-
-int
-main ()
-{
-  xercesc::XMLPlatformUtils::Initialize ();
-
-  {
-    // Start/terminate threads and parse/serialize here.
-  }
-
-  xercesc::XMLPlatformUtils::Terminate ();
-}
-  
- -

Because you initialize the Xerces-C++ runtime yourself you should - also pass the xml_schema::flags::dont_initialize flag - to parsing and serialization functions. See Chapter 5, - "Parsing" and Chapter 6, "Serialization" for - more information.

- - - - - -

4 Working with Object Models

- -

As we have seen in the previous chapters, the XSD compiler generates - a C++ class for each type defined in XML Schema. Together these classes - constitute an object model for an XML vocabulary. In this chapter we - will take a closer look at different elements that comprise an - object model class as well as how to create, access, and modify - object models.

- -

In this and subsequent chapters we will use the following schema - that describes a collection of person records. We save it in - people.xsd:

- -
-<?xml version="1.0"?>
-<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
-
-  <xs:simpleType name="gender_t">
-    <xs:restriction base="xs:string">
-      <xs:enumeration value="male"/>
-      <xs:enumeration value="female"/>
-    </xs:restriction>
-  </xs:simpleType>
-
-  <xs:complexType name="person_t">
-    <xs:sequence>
-      <xs:element name="first-name" type="xs:string"/>
-      <xs:element name="middle-name" type="xs:string" minOccurs="0"/>
-      <xs:element name="last-name" type="xs:string"/>
-      <xs:element name="gender" type="gender_t"/>
-      <xs:element name="age" type="xs:short"/>
-    </xs:sequence>
-    <xs:attribute name="id" type="xs:unsignedInt" use="required"/>
-  </xs:complexType>
-
-  <xs:complexType name="people_t">
-    <xs:sequence>
-      <xs:element name="person" type="person_t" maxOccurs="unbounded"/>
-    </xs:sequence>
-  </xs:complexType>
-
-  <xs:element name="people" type="people_t"/>
-
-</xs:schema>
-  
- -

A sample XML instance to go along with this schema is saved - in people.xml:

- -
-<?xml version="1.0"?>
-<people xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-        xsi:noNamespaceSchemaLocation="people.xsd">
-
-  <person id="1">
-    <first-name>John</first-name>
-    <last-name>Doe</last-name>
-    <gender>male</gender>
-    <age>32</age>
-  </person>
-
-  <person id="2">
-    <first-name>Jane</first-name>
-    <middle-name>Mary</middle-name>
-    <last-name>Doe</last-name>
-    <gender>female</gender>
-    <age>28</age>
-  </person>
-
-</people>
-  
- -

Compiling people.xsd with the XSD compiler results - in three generated C++ classes: gender_t, - person_t, and people_t. - The gender_t class is modelled after the C++ - enum type. Its definition is presented below:

- -
-class gender_t: public xml_schema::string
-{
-public:
-  enum value
-  {
-    male,
-    female
-  };
-
-  gender_t (value);
-  gender_t (const xml_schema::string&);
-
-  gender_t&
-  operator= (value);
-
-  operator value () const;
-};
-  
- -

The following listing shows how we can use this type:

- -
-gender_t m (gender_t::male);
-gender_t f ("female");
-
-if (m == "female" || f == gender_t::male)
-{
-  ...
-}
-
-switch (m)
-{
-case gender_t::male:
-  {
-    ...
-  }
-case gender_t::female:
-  {
-    ...
-  }
-}
-  
- -

The other two classes will be examined in detail in the subsequent - sections.

- -

4.1 Attribute and Element Cardinalities

- -

As we have seen in the previous chapters, XSD generates a different - set of type definitions and member functions for elements with - different cardinalities. The C++/Tree mapping divides all the possible - element and attribute cardinalities into three cardinality classes: - one, optional, and sequence.

- -

The one cardinality class covers all elements that should - occur exactly once as well as required attributes. In our - example, the first-name, last-name, - gender, and age elements as well as - the id attribute belong to this cardinality class. - The following code fragment shows type definitions as well as the - accessor and modifier functions that are generated for the - gender element in the person_t class:

- -
-class person_t
-{
-  // gender
-  //
-  typedef gender_t gender_type;
-
-  const gender_type&
-  gender () const;
-
-  gender_type&
-  gender ();
-
-  void
-  gender (const gender_type&);
-};
-  
- -

The gender_type type is an alias for the element's type. - The first two accessor functions return read-only (constant) and - read-write references to the element's value, respectively. The - modifier function sets the new value for the element.

- -

The optional cardinality class covers all elements that - can occur zero or one time as well as optional attributes. In our - example, the middle-name element belongs to this - cardinality class. The following code fragment shows the type - definitions as well as the accessor and modifier functions that - are generated for this element in the person_t class:

- -
-class person_t
-{
-  // middle-name
-  //
-  typedef xml_schema::string middle_name_type;
-  typedef xsd::optional<middle_name_type> middle_name_optional;
-
-  const middle_name_optional&
-  middle_name () const;
-
-  middle_name_optional&
-  middle_name ();
-
-  void
-  middle_name (const middle_name_type&);
-
-  void
-  middle_name (const middle_name_optional&);
-};
-  
- -

As with the gender element, middle_name_type - is an alias for the element's type. The middle_name_optional - type is a container for the element's optional value. It can be queried - for the presence of the value using the present() function. - The value itself can be retrieved using the get() - accessor and set using the set() modifier. The container - can be reverted to the value not present state with the call to the - reset() function. The following example shows how we - can use this container:

- -
-person_t::middle_name_optional n ("John");
-
-if (n.present ())
-{
-  cout << n.get () << endl;
-}
-
-n.set ("Jane");
-n.reset ();
-  
- - -

Unlike the one cardinality class, the accessor functions - for the optional class return read-only (constant) and - read-write references to the container instead of the element's - value directly. The modifier functions set the new value for the - element.

- -

Finally, the sequence cardinality class covers all elements - that can occur more than once. In our example, the - person element in the people_t type - belongs to this cardinality class. The following code fragment shows - the type definitions as well as the accessor and modifier functions - that are generated for this element in the people_t - class:

- -
-class people_t
-{
-  // person
-  //
-  typedef person_t person_type;
-  typedef xsd::sequence<person_type> person_sequence;
-  typedef person_sequence::iterator person_iterator;
-  typedef person_sequence::const_iterator person_const_iterator;
-
-  const person_sequence&
-  person () const;
-
-  person_sequence&
-  person ();
-
-  void
-  person (const person_sequence&);
-};
-  
- -

Identical to the other cardinality classes, person_type - is an alias for the element's type. The person_sequence - type is a sequence container for the element's values. It is based - on and has the same interface as std::vector and - therefore can be used in similar ways. The person_iterator - and person_const_iterator types are read-only - (constant) and read-write iterators for the person_sequence - container.

- -

Similar to the optional cardinality class, the - accessor functions for the sequence class return - read-only (constant) and read-write references to the sequence - container. The modifier functions copies the entries from - the passed sequence.

- -

C++/Tree is a "flattening" mapping in a sense that many levels of - nested compositors (choice and sequence), - all potentially with their own cardinalities, are in the end mapped - to a flat set of elements with one of the three cardinality classes - discussed above. While this results in a simple and easy to use API - for most types, in certain cases, the order of elements in the actual - XML documents is not preserved once parsed into the object model. To - overcome this limitation we can mark certain schema types, for which - content order is not sufficiently preserved, as ordered. For more - information on this functionality refer to - Section - 2.8.4, "Element Order" in the C++/Tree Mapping User Manual.

- -

For complex schemas with many levels of nested compositors - (choice and sequence) it can also - be hard to deduce the cardinality class of a particular element. - The generated Doxygen documentation can greatly help with - this task. For each element and attribute the documentation - clearly identifies its cardinality class. Alternatively, you - can study the generated header files to find out the cardinality - class of a particular attribute or element.

- -

In the next sections we will examine how to access and modify - information stored in an object model using accessor and modifier - functions described in this section.

- -

4.2 Accessing the Object Model

- -

In this section we will learn how to get to the information - stored in the object model for our person records vocabulary. - The following application accesses and prints the contents - of the people.xml file:

- -
-#include <iostream>
-#include "people.hxx"
-
-using namespace std;
-
-int
-main ()
-{
-  auto_ptr<people_t> ppl (people ("people.xml"));
-
-  // Iterate over individual person records.
-  //
-  people_t::person_sequence& ps (ppl->person ());
-
-  for (people_t::person_iterator i (ps.begin ()); i != ps.end (); ++i)
-  {
-    person_t& p (*i);
-
-    // Print names: first-name and last-name are required elements,
-    // middle-name is optional.
-    //
-    cout << "name:   " << p.first_name () << " ";
-
-    if (p.middle_name ().present ())
-      cout << p.middle_name ().get () << " ";
-
-    cout << p.last_name () << endl;
-
-    // Print gender, age, and id which are all required.
-    //
-    cout << "gender: " << p.gender () << endl
-         << "age:    " << p.age () << endl
-         << "id:     " << p.id () << endl
-         << endl;
-  }
-}
-  
- -

This code shows common patterns of accessing elements and attributes - with different cardinality classes. For the sequence element - (person in people_t) we first obtain a - reference to the container and then iterate over individual - records. The values of elements and attributes with the - one cardinality class (first-name, - last-name, gender, age, - and id) can be obtained directly by calling the - corresponding accessor functions. For the optional element - middle-name we first check if the value is present - and only then call get() to retrieve it.

- -

Note that when we want to reduce typing by creating a variable - representing a fragment of the object model that we are currently - working with (ps and p above), we obtain - a reference to that fragment instead of making a potentially - expensive copy. This is generally a good rule to follow when - creating high-performance applications.

- -

If we run the above application on our sample - people.xml, the output looks as follows:

- -
-name:   John Doe
-gender: male
-age:    32
-id:     1
-
-name:   Jane Mary Doe
-gender: female
-age:    28
-id:     2
-  
- - -

4.3 Modifying the Object Model

- -

In this section we will learn how to modify the information - stored in the object model for our person records vocabulary. - The following application changes the contents of the - people.xml file:

- -
-#include <iostream>
-#include "people.hxx"
-
-using namespace std;
-
-int
-main ()
-{
-  auto_ptr<people_t> ppl (people ("people.xml"));
-
-  // Iterate over individual person records and increment
-  // the age.
-  //
-  people_t::person_sequence& ps (ppl->person ());
-
-  for (people_t::person_iterator i (ps.begin ()); i != ps.end (); ++i)
-  {
-    // Alternative way: i->age ()++;
-    //
-    i->age (i->age () + 1);
-  }
-
-  // Add middle-name to the first record and remove it from
-  // the second.
-  //
-  person_t& john (ps[0]);
-  person_t& jane (ps[1]);
-
-  john.middle_name ("Mary");
-  jane.middle_name ().reset ();
-
-  // Add another John record.
-  //
-  ps.push_back (john);
-
-  // Serialize the modified object model to XML.
-  //
-  xml_schema::namespace_infomap map;
-  map[""].name = "";
-  map[""].schema = "people.xsd";
-
-  people (cout, *ppl, map);
-}
-  
- -

The first modification the above application performs is iterating - over person records and incrementing the age value. This code - fragment shows how to modify the value of a required attribute - or element. The next modification shows how to set a new value - for the optional middle-name element as well - as clear its value. Finally the example adds a copy of the - John Doe record to the person element sequence.

- -

Note that in this case using references for the ps, - john, and jane variables is no longer - a performance improvement but a requirement for the application - to function correctly. If we hadn't used references, all our changes - would have been made on copies without affecting the object model.

- -

If we run the above application on our sample people.xml, - the output looks as follows:

- -
-<?xml version="1.0"?>
-<people xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-        xsi:noNamespaceSchemaLocation="people.xsd">
-
-  <person id="1">
-    <first-name>John</first-name>
-    <middle-name>Mary</middle-name>
-    <last-name>Doe</last-name>
-    <gender>male</gender>
-    <age>33</age>
-  </person>
-
-  <person id="2">
-    <first-name>Jane</first-name>
-    <last-name>Doe</last-name>
-    <gender>female</gender>
-    <age>29</age>
-  </person>
-
-  <person id="1">
-    <first-name>John</first-name>
-    <middle-name>Mary</middle-name>
-    <last-name>Doe</last-name>
-    <gender>male</gender>
-    <age>33</age>
-  </person>
-
-</people>
-  
- - -

4.4 Creating the Object Model from Scratch

- -

In this section we will learn how to create a new object model - for our person records vocabulary. The following application - recreates the content of the original people.xml - file:

- -
-#include <iostream>
-#include "people.hxx"
-
-using namespace std;
-
-int
-main ()
-{
-  people_t ppl;
-  people_t::person_sequence& ps (ppl.person ());
-
-  // Add the John Doe record.
-  //
-  ps.push_back (
-    person_t ("John",         // first-name
-              "Doe",          // last-name
-              gender_t::male, // gender
-              32,             // age
-              1));
-
-  // Add the Jane Doe record.
-  //
-  ps.push_back (
-    person_t ("Jane",           // first-name
-              "Doe",            // last-name
-              gender_t::female, // gender
-              28,               // age
-              2));              // id
-
-  // Add middle name to the Jane Doe record.
-  //
-  person_t& jane (ps.back ());
-  jane.middle_name ("Mary");
-
-  // Serialize the object model to XML.
-  //
-  xml_schema::namespace_infomap map;
-  map[""].name = "";
-  map[""].schema = "people.xsd";
-
-  people (cout, ppl, map);
-}
-  
- -

The only new part in the above application is the calls - to the people_t and person_t - constructors. As a general rule, for each C++ class - XSD generates a constructor with initializers - for each element and attribute belonging to the one - cardinality class. For our vocabulary, the following - constructors are generated:

- -
-class person_t
-{
-  person_t (const first_name_type&,
-            const last_name_type&,
-            const gender_type&,
-            const age_type&,
-            const id_type&);
-};
-
-class people_t
-{
-  people_t ();
-};
-  
- -

Note also that we set the middle-name element - on the Jane Doe record by obtaining a reference to that record - in the object model and setting the middle-name - value on it. This is a general rule that should be followed - in order to obtain the best performance: if possible, - direct modifications to the object model should be preferred - to modifications on temporaries with subsequent copying. The - following code fragment shows a semantically equivalent but - slightly slower version:

- -
-// Add the Jane Doe record.
-//
-person_t jane ("Jane",           // first-name
-               "Doe",            // last-name
-               gender_t::female, // gender
-               28,               // age
-               2);               // id
-
-jane.middle_name ("Mary");
-
-ps.push_back (jane);
-  
- -

We can also go one step further to reduce copying and improve - the performance of our application by using the non-copying - push_back() function which assumes ownership - of the passed objects:

- -
-// Add the John Doe record. C++98 version.
-//
-auto_ptr<person_t> john_p (
-  new person_t ("John",           // first-name
-                "Doe",            // last-name
-                gender_t::male,   // gender
-                32,               // age
-                1));
-ps.push_back (john_p); // assumes ownership
-
-// Add the Jane Doe record. C++11 version
-//
-unique_ptr<person_t> jane_p (
-  new person_t ("Jane",           // first-name
-                "Doe",            // last-name
-                gender_t::female, // gender
-                28,               // age
-                2));              // id
-ps.push_back (std::move (jane_p)); // assumes ownership
-  
- -

For more information on the non-copying modifier functions refer to - Section - 2.8, "Mapping for Local Elements and Attributes" in the C++/Tree Mapping - User Manual. The above application produces the following output:

- -
-<?xml version="1.0" ?>
-<people xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-        xsi:noNamespaceSchemaLocation="people.xsd">
-
-  <person id="1">
-    <first-name>John</first-name>
-    <last-name>Doe</last-name>
-    <gender>male</gender>
-    <age>32</age>
-  </person>
-
-  <person id="2">
-    <first-name>Jane</first-name>
-    <middle-name>Mary</middle-name>
-    <last-name>Doe</last-name>
-    <gender>female</gender>
-    <age>28</age>
-  </person>
-
-</people>
-  
- -

4.5 Mapping for the Built-in XML Schema Types

- -

Our person record vocabulary uses several built-in XML Schema - types: string, short, and - unsignedInt. Until now we haven't talked about - the mapping of built-in XML Schema types to C++ types and how - to work with them. This section provides an overview - of the built-in types. For more detailed information refer - to Section - 2.5, "Mapping for Built-in Data Types" in the C++/Tree Mapping - User Manual.

- -

In XML Schema, built-in types are defined in the XML Schema namespace. - By default, the C++/Tree mapping maps this namespace to C++ - namespace xml_schema (this mapping can be altered - with the --namespace-map option). The following table - summarizes the mapping of XML Schema built-in types to C++ types:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
XML Schema typeAlias in the xml_schema namespaceC++ type
fixed-length integral types
bytebytesigned char
unsignedByteunsigned_byteunsigned char
shortshort_short
unsignedShortunsigned_shortunsigned short
intint_int
unsignedIntunsigned_intunsigned int
longlong_long long
unsignedLongunsigned_longunsigned long long
arbitrary-length integral types
integerintegerlong long
nonPositiveIntegernon_positive_integerlong long
nonNegativeIntegernon_negative_integerunsigned long long
positiveIntegerpositive_integerunsigned long long
negativeIntegernegative_integerlong long
boolean types
booleanbooleanbool
fixed-precision floating-point types
floatfloat_float
doubledouble_double
arbitrary-precision floating-point types
decimaldecimaldouble
string types
stringstringtype derived from std::basic_string
normalizedStringnormalized_stringtype derived from string
tokentokentype derived from normalized_string
Namenametype derived from token
NMTOKENnmtokentype derived from token
NMTOKENSnmtokenstype derived from sequence<nmtoken>
NCNamencnametype derived from name
languagelanguagetype derived from token
qualified name
QNameqnamexml_schema::qname
ID/IDREF types
IDidtype derived from ncname
IDREFidreftype derived from ncname
IDREFSidrefstype derived from sequence<idref>
URI types
anyURIuritype derived from std::basic_string
binary types
base64Binarybase64_binaryxml_schema::base64_binary
hexBinaryhex_binaryxml_schema::hex_binary
date/time types
datedatexml_schema::date
dateTimedate_timexml_schema::date_time
durationdurationxml_schema::duration
gDaygdayxml_schema::gday
gMonthgmonthxml_schema::gmonth
gMonthDaygmonth_dayxml_schema::gmonth_day
gYeargyearxml_schema::gyear
gYearMonthgyear_monthxml_schema::gyear_month
timetimexml_schema::time
entity types
ENTITYentitytype derived from name
ENTITIESentitiestype derived from sequence<entity>
- -

As you can see from the table above a number of built-in - XML Schema types are mapped to fundamental C++ types such - as int or bool. All string-based - XML Schema types are mapped to C++ types that are derived - from either std::string or - std::wstring, depending on the character - type selected. For access and modification purposes these - types can be treated as std::string. A number - of built-in types, such as qname, the binary - types, and the date/time types do not have suitable - fundamental or standard C++ types to map to. As a result, - these types are implemented from scratch in the XSD runtime. - For more information on their interfaces refer to - Section - 2.5, "Mapping for Built-in Data Types" in the C++/Tree Mapping - User Manual.

- - - - - -

5 Parsing

- -

We have already seen how to parse XML to an object model in this guide - before. In this chapter we will discuss the parsing topic in more - detail.

- -

By default, the C++/Tree mapping provides a total of 14 overloaded - parsing functions. They differ in the input methods used to - read XML as well as the error reporting mechanisms. It is also possible - to generate types for root elements instead of parsing and serialization - functions. This may be useful if your XML vocabulary has multiple - root elements. For more information on element types refer to - Section - 2.9, "Mapping for Global Elements" in the C++/Tree Mapping User - Manual.

- - -

In this section we will discuss the most commonly used versions of - the parsing functions. For a comprehensive description of parsing - refer to Chapter - 3, "Parsing" in the C++/Tree Mapping User Manual. For the people - global element from our person record vocabulary, we will concentrate - on the following three parsing functions:

- -
-std::[auto|unique]_ptr<people_t>
-people (const std::string& uri,
-	xml_schema::flags f = 0,
-	const xml_schema::properties& p = xml_schema::properties ());
-
-std::[auto|unique]_ptr<people_t>
-people (std::istream& is,
-        xml_schema::flags f = 0,
-        const xml_schema::properties& p = xml_schema::properties ());
-
-std::[auto|unique]_ptr<people_t>
-people (std::istream& is,
-        const std::string& resource_id,
-        xml_schema::flags f = 0,
-        const xml_schema::properties& p = ::xml_schema::properties ());
-  
- -

The first function parses a local file or a URI. We have already - used this parsing function in the previous chapters. The second - and third functions read XML from a standard input stream. The - last function also requires a resource id. This id is used to - identify the XML document being parser in diagnostics messages - as well as to resolve relative paths to other documents (for example, - schemas) that might be referenced from the XML document.

- -

The last two arguments to all three parsing functions are parsing - flags and properties. The flags argument provides a number of ways - to fine-tune the parsing process. The properties argument allows - to pass additional information to the parsing functions. We will - use these two arguments in Section 5.1, "XML Schema - Validation and Searching" below. All three functions return - the object model as either std::auto_ptr (C++98) or - std::unique_ptr (C++11), depending on the C++ standard - selected (--std XSD compiler option). The following - example shows how we can use the above parsing functions:

- -
-using std::auto_ptr;
-
-// Parse a local file or URI.
-//
-auto_ptr<people_t> p1 (people ("people.xml"));
-auto_ptr<people_t> p2 (people ("http://example.com/people.xml"));
-
-// Parse a local file via ifstream.
-//
-std::ifstream ifs ("people.xml");
-auto_ptr<people_t> p3 (people (ifs, "people.xml"));
-
-// Parse an XML string.
-//
-std::string str ("..."); // XML in a string.
-std::istringstream iss (str);
-auto_ptr<people_t> p4 (people (iss));
-  
- - -

5.1 XML Schema Validation and Searching

- -

The C++/Tree mapping relies on the underlying Xerces-C++ XML - parser for full XML document validation. The XML Schema - validation is enabled by default and can be disabled by - passing the xml_schema::flags::dont_validate - flag to the parsing functions, for example:

- -
-auto_ptr<people_t> p (
-  people ("people.xml", xml_schema::flags::dont_validate));
-  
- -

Even when XML Schema validation is disabled, the generated - code still performs a number of checks to prevent - construction of an inconsistent object model (for example, an - object model with missing required attributes or elements).

- -

When XML Schema validation is enabled, the XML parser needs - to locate a schema to validate against. There are several - methods to provide the schema location information to the - parser. The easiest and most commonly used method is to - specify schema locations in the XML document itself - with the schemaLocation or - noNamespaceSchemaLocation attributes, for example:

- -
-<?xml version="1.0" ?>
-<people xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-        xsi:noNamespaceSchemaLocation="people.xsd"
-        xsi:schemaLocation="http://www.w3.org/XML/1998/namespace xml.xsd">
-  
- -

As you might have noticed, we used this method in all the sample XML - documents presented in this guide up until now. Note that the - schema locations specified with these two attributes are relative - to the document's path unless they are absolute URIs (that is - start with http://, file://, etc.). - In particular, if you specify just file names as your schema - locations, as we did above, then the schemas should reside in - the same directory as the XML document itself.

- -

Another method of providing the schema location information - is via the xml_schema::properties argument, as - shown in the following example:

- -
-xml_schema::properties props;
-props.no_namespace_schema_location ("people.xsd");
-props.schema_location ("http://www.w3.org/XML/1998/namespace", "xml.xsd");
-
-auto_ptr<people_t> p (people ("people.xml", 0, props));
-  
- -

The schema locations provided with this method overrides - those specified in the XML document. As with the previous - method, the schema locations specified this way are - relative to the document's path unless they are absolute URIs. - In particular, if you want to use local schemas that are - not related to the document being parsed, then you will - need to use the file:// URI. The following - example shows how to use schemas that reside in the current - working directory:

- -
-#include <unistd.h> // getcwd
-#include <limits.h> // PATH_MAX
-
-char cwd[PATH_MAX];
-if (getcwd (cwd, PATH_MAX) == 0)
-{
-  // Buffer too small?
-}
-
-xml_schema::properties props;
-
-props.no_namespace_schema_location (
-  "file:///" + std::string (cwd) + "/people.xsd");
-
-props.schema_location (
-  "http://www.w3.org/XML/1998/namespace",
-  "file:///" + std::string (cwd) + "/xml.xsd");
-
-auto_ptr<people_t> p (people ("people.xml", 0, props));
-  
- -

A third method is the most useful if you are planning to parse - several XML documents of the same vocabulary. In that case - it may be beneficial to pre-parse and cache the schemas in - the XML parser which can then be used to parse all documents - without re-parsing the schemas. For more information on - this method refer to the caching example in the - examples/cxx/tree/ directory of the XSD - distribution. It is also possible to convert the schemas into - a pre-compiled binary representation and embed this representation - directly into the application executable. With this approach your - application can perform XML Schema validation without depending on - any external schema files. For more information on how to achieve - this refer to the embedded example in the - examples/cxx/tree/ directory of the XSD distribution.

- -

When the XML parser cannot locate a schema for the - XML document, the validation fails and XML document - elements and attributes for which schema definitions could - not be located are reported in the diagnostics. For - example, if we remove the noNamespaceSchemaLocation - attribute in people.xml from the previous chapter, - then we will get the following diagnostics if we try to parse - this file with validation enabled:

- -
-people.xml:2:63 error: no declaration found for element 'people'
-people.xml:4:18 error: no declaration found for element 'person'
-people.xml:4:18 error: attribute 'id' is not declared for element 'person'
-people.xml:5:17 error: no declaration found for element 'first-name'
-people.xml:6:18 error: no declaration found for element 'middle-name'
-people.xml:7:16 error: no declaration found for element 'last-name'
-people.xml:8:13 error: no declaration found for element 'gender'
-people.xml:9:10 error: no declaration found for element 'age'
-  
- -

5.2 Error Handling

- -

The parsing functions offer a number of ways to handle error conditions - with the C++ exceptions being the most commonly used mechanism. All - C++/Tree exceptions derive from common base xml_schema::exception - which in turn derives from std::exception. The easiest - way to uniformly handle all possible C++/Tree exceptions and print - detailed information about the error is to catch and print - xml_schema::exception, as shown in the following - example:

- -
-try
-{
-  auto_ptr<people_t> p (people ("people.xml"));
-}
-catch (const xml_schema::exception& e)
-{
-  cerr << e << endl;
-}
-  
- -

Each individual C++/Tree exception also allows you to obtain - error details programmatically. For example, the - xml_schema::parsing exception is thrown when - the XML parsing and validation in the underlying XML parser - fails. It encapsulates various diagnostics information - such as the file name, line and column numbers, as well as the - error or warning message for each entry. For more information - about this and other exceptions that can be thrown during - parsing, refer to - Section - 3.3, "Error Handling" in the C++/Tree Mapping - User Manual.

- -

Note that if you are parsing std::istream on which - exceptions are not enabled, then you will need to check the - stream state after the call to the parsing function in order - to detect any possible stream failures, for example:

- -
-std::ifstream ifs ("people.xml");
-
-if (ifs.fail ())
-{
-  cerr << "people.xml: unable to open" << endl;
-  return 1;
-}
-
-auto_ptr<people_t> p (people (ifs, "people.xml"));
-
-if (ifs.fail ())
-{
-  cerr << "people.xml: read error" << endl;
-  return 1;
-}
-  
- -

The above example can be rewritten to use exceptions as - shown below:

- -
-try
-{
-  std::ifstream ifs;
-  ifs.exceptions (std::ifstream::badbit | std::ifstream::failbit);
-  ifs.open ("people.xml");
-
-  auto_ptr<people_t> p (people (ifs, "people.xml"));
-}
-catch (const std::ifstream::failure&)
-{
-  cerr << "people.xml: unable to open or read error" << endl;
-  return 1;
-}
-  
- - - - - -

6 Serialization

- -

We have already seen how to serialize an object model back to XML - in this guide before. In this chapter we will discuss the - serialization topic in more detail.

- -

By default, the C++/Tree mapping provides a total of 8 overloaded - serialization functions. They differ in the output methods used to write - XML as well as the error reporting mechanisms. It is also possible to - generate types for root elements instead of parsing and serialization - functions. This may be useful if your XML vocabulary has multiple - root elements. For more information on element types refer to - Section - 2.9, "Mapping for Global Elements" in the C++/Tree Mapping User - Manual.

- - -

In this section we will discuss the most commonly - used version of serialization functions. For a comprehensive description - of serialization refer to - Chapter - 4, "Serialization" in the C++/Tree Mapping User Manual. For the - people global element from our person record vocabulary, - we will concentrate on the following serialization function:

- -
-void
-people (std::ostream& os,
-        const people_t& x,
-        const xml_schema::namespace_infomap& map =
-          xml_schema::namespace_infomap (),
-        const std::string& encoding = "UTF-8",
-        xml_schema::flags f = 0);
-  
- -

This function serializes the object model passed as the second - argument to the standard output stream passed as the first - argument. The third argument is a namespace information map - which we will discuss in more detail in the next section. - The fourth argument is a character encoding that the resulting - XML document should be in. Possible valid values for this - argument are "US-ASCII", "ISO8859-1", "UTF-8", "UTF-16BE", - "UTF-16LE", "UCS-4BE", and "UCS-4LE". Finally, the flags - argument allows fine-tuning of the serialization process. - The following example shows how we can use the above serialization - function:

- -
-people_t& p = ...
-
-xml_schema::namespace_infomap map;
-map[""].schema = "people.xsd";
-
-// Serialize to stdout.
-//
-people (std::cout, p, map);
-
-// Serialize to a file.
-//
-std::ofstream ofs ("people.xml");
-people (ofs, p, map);
-
-// Serialize to a string.
-//
-std::ostringstream oss;
-people (oss, p, map);
-std::string xml (oss.str ());
-  
- - -

6.1 Namespace and Schema Information

- -

While XML serialization can be done just from the object - model alone, it is often desirable to assign meaningful - prefixes to XML namespaces used in the vocabulary as - well as to provide the schema location information. - This is accomplished by passing the namespace information - map to the serialization function. The key in this map is - a namespace prefix that should be assigned to an XML namespace - specified in the name variable of the - map value. You can also assign an optional schema location for - this namespace in the schema variable. Based - on each key-value entry in this map, the serialization - function adds two attributes to the resulting XML document: - the namespace-prefix mapping attribute and schema location - attribute. The empty prefix indicates that the namespace - should be mapped without a prefix. For example, the following - map:

- -
-xml_schema::namespace_infomap map;
-
-map[""].name = "http://www.example.com/example";
-map[""].schema = "example.xsd";
-
-map["x"].name = "http://www.w3.org/XML/1998/namespace";
-map["x"].schema = "xml.xsd";
-  
- -

Results in the following XML document:

- -
-<?xml version="1.0" ?>
-<example
-  xmlns="http://www.example.com/example"
-  xmlns:x="http://www.w3.org/XML/1998/namespace"
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:schemaLocation="http://www.example.com/example example.xsd
-                      http://www.w3.org/XML/1998/namespace xml.xsd">
-  
- -

The empty namespace indicates that the vocabulary has no target - namespace. For example, the following map results in only the - noNamespaceSchemaLocation attribute being added:

- -
-xml_schema::namespace_infomap map;
-
-map[""].name = "";
-map[""].schema = "example.xsd";
-  
- -

6.2 Error Handling

- -

Similar to the parsing functions, the serialization functions offer a - number of ways to handle error conditions with the C++ exceptions being - the most commonly used mechanisms. As with parsing, the easiest way to - uniformly handle all possible serialization exceptions and print - detailed information about the error is to catch and print - xml_schema::exception:

- -
-try
-{
-  people_t& p = ...
-
-  xml_schema::namespace_infomap map;
-  map[""].schema = "people.xsd";
-
-  people (std::cout, p, map));
-}
-catch (const xml_schema::exception& e)
-{
-  cerr << e << endl;
-}
-  
- -

The most commonly encountered serialization exception is - xml_schema::serialization. It is thrown - when the XML serialization in the underlying XML writer - fails. It encapsulates various diagnostics information - such as the file name, line and column numbers, as well as the - error or warning message for each entry. For more information - about this and other exceptions that can be thrown during - serialization, refer to - Section - 4.4, "Error Handling" in the C++/Tree Mapping - User Manual.

- -

Note that if you are serializing to std::ostream on - which exceptions are not enabled, then you will need to check the - stream state after the call to the serialization function in order - to detect any possible stream failures, for example:

- -
-std::ofstream ofs ("people.xml");
-
-if (ofs.fail ())
-{
-  cerr << "people.xml: unable to open" << endl;
-  return 1;
-}
-
-people (ofs, p, map));
-
-if (ofs.fail ())
-{
-  cerr << "people.xml: write error" << endl;
-  return 1;
-}
-  
- -

The above example can be rewritten to use exceptions as - shown below:

- -
-try
-{
-  std::ofstream ofs;
-  ofs.exceptions (std::ofstream::badbit | std::ofstream::failbit);
-  ofs.open ("people.xml");
-
-  people (ofs, p, map));
-}
-catch (const std::ofstream::failure&)
-{
-  cerr << "people.xml: unable to open or write error" << endl;
-  return 1;
-}
-  
- -
-
- - - diff --git a/doc/cxx/tree/guide/makefile b/doc/cxx/tree/guide/makefile deleted file mode 100644 index 3b95fff..0000000 --- a/doc/cxx/tree/guide/makefile +++ /dev/null @@ -1,53 +0,0 @@ -# file : doc/cxx/tree/guide/makefile -# license : GNU GPL v2 + exceptions; see accompanying LICENSE file - -include $(dir $(lastword $(MAKEFILE_LIST)))../../../../build/bootstrap.make - -default := $(out_base)/ -install := $(out_base)/.install -dist := $(out_base)/.dist -dist-win := $(out_base)/.dist-win -clean := $(out_base)/.clean - -# Build. -# -$(default): $(out_base)/cxx-tree-guide.ps $(out_base)/cxx-tree-guide.pdf - - -$(out_base)/cxx-tree-guide.ps: $(src_base)/index.xhtml \ - $(src_base)/guide.html2ps \ - | $(out_base)/. - $(call message,html2ps $<,html2ps -f $(src_base)/guide.html2ps -o $@ $<) - -$(out_base)/cxx-tree-guide.pdf: $(out_base)/cxx-tree-guide.ps | $(out_base)/. - $(call message,ps2pdf $<,ps2pdf14 $< $@) - -# Install & Dist. -# -$(install): path := $(subst $(src_root)/doc/,,$(src_base)) -$(dist): path := $(subst $(src_root)/,,$(src_base)) - -$(install): $(out_base)/cxx-tree-guide.ps $(out_base)/cxx-tree-guide.pdf - $(call install-data,$(src_base)/index.xhtml,$(install_doc_dir)/xsd/$(path)/index.xhtml) - $(call install-data,$(out_base)/cxx-tree-guide.ps,$(install_doc_dir)/xsd/$(path)/cxx-tree-guide.ps) - $(call install-data,$(out_base)/cxx-tree-guide.pdf,$(install_doc_dir)/xsd/$(path)/cxx-tree-guide.pdf) - -$(dist): $(out_base)/cxx-tree-guide.ps $(out_base)/cxx-tree-guide.pdf - $(call install-data,$(src_base)/index.xhtml,$(dist_prefix)/$(path)/index.xhtml) - $(call install-data,$(out_base)/cxx-tree-guide.ps,$(dist_prefix)/$(path)/cxx-tree-guide.ps) - $(call install-data,$(out_base)/cxx-tree-guide.pdf,$(dist_prefix)/$(path)/cxx-tree-guide.pdf) - -$(dist-win): $(dist) - - -# Clean -# -$(clean): -ifneq ($(xsd_clean_gen),n) - $(call message,rm $$1,rm -f $$1,$(out_base)/cxx-tree-guide.ps) - $(call message,rm $$1,rm -f $$1,$(out_base)/cxx-tree-guide.pdf) -endif - -# How to. -# -$(call include,$(bld_root)/install.make) diff --git a/doc/cxx/tree/makefile b/doc/cxx/tree/makefile deleted file mode 100644 index deb254c..0000000 --- a/doc/cxx/tree/makefile +++ /dev/null @@ -1,40 +0,0 @@ -# file : doc/cxx/tree/makefile -# license : GNU GPL v2 + exceptions; see accompanying LICENSE file - -include $(dir $(lastword $(MAKEFILE_LIST)))../../../build/bootstrap.make - -docs := guide manual - -default := $(out_base)/ -install := $(out_base)/.install -dist := $(out_base)/.dist -dist-win := $(out_base)/.dist-win -clean := $(out_base)/.clean - -# Build. -# -$(default): $(addprefix $(out_base)/,$(addsuffix /,$(docs))) - -# Install & Dist. -# -dist-common := $(out_base)/.dist-common - -$(install): path := $(subst $(src_root)/doc/,,$(src_base)) -$(dist-common): path := $(subst $(src_root)/,,$(src_base)) - -$(install): $(addprefix $(out_base)/,$(addsuffix /.install,$(docs))) - $(call install-dir,$(src_base)/reference,$(install_doc_dir)/xsd/$(path)/reference) - -$(dist-common): - $(call install-dir,$(src_base)/reference,$(dist_prefix)/$(path)/reference) - -$(dist): $(dist-common) $(addprefix $(out_base)/,$(addsuffix /.dist,$(docs))) -$(dist-win): $(dist-common) $(addprefix $(out_base)/,$(addsuffix /.dist-win,$(docs))) - -# Clean. -# -$(clean): $(addprefix $(out_base)/,$(addsuffix /.clean,$(docs))) - -$(call include,$(bld_root)/install.make) - -$(foreach m,$(docs),$(call import,$(src_base)/$m/makefile)) diff --git a/doc/cxx/tree/manual/index.xhtml b/doc/cxx/tree/manual/index.xhtml deleted file mode 100644 index 550c07e..0000000 --- a/doc/cxx/tree/manual/index.xhtml +++ /dev/null @@ -1,6822 +0,0 @@ - - - - - - C++/Tree Mapping User Manual - - - - - - - - - - - - - - -
-
- -
- -
-
C++/Tree Mapping User Manual
- -

Copyright © 2009-2020 Code Synthesis Tools CC.

- -

Permission is granted to copy, distribute and/or modify this - document under the terms of the - GNU Free - Documentation License, version 1.2; with no Invariant Sections, - no Front-Cover Texts and no Back-Cover Texts. -

- -

This document is available in the following formats: - XHTML, - PDF, and - PostScript.

-
- -

Table of Contents

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Preface - - - -
About This Document
More Information
-
1Introduction
2C++/Tree Mapping - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
2.1Preliminary Information - - - - - - -
2.1.1C++ Standard
2.1.2Identifiers
2.1.3Character Type and Encoding
2.1.4XML Schema Namespace
2.1.5Anonymous Types
-
2.2Error Handling - - -
2.2.1xml_schema::duplicate_id
-
2.3Mapping for import and include - - - - -
2.3.1Import
2.3.2Inclusion with Target Namespace
2.3.3Inclusion without Target Namespace
-
2.4Mapping for Namespaces
2.5Mapping for Built-in Data Types - - - - - - - - - - - - - - - - - -
2.5.1Inheritance from Built-in Data Types
2.5.2Mapping for anyType
2.5.3Mapping for anySimpleType
2.5.4Mapping for QName
2.5.5Mapping for IDREF
2.5.6Mapping for base64Binary and hexBinary
2.5.7Time Zone Representation
2.5.8Mapping for date
2.5.9Mapping for dateTime
2.5.10Mapping for duration
2.5.11Mapping for gDay
2.5.12Mapping for gMonth
2.5.13Mapping for gMonthDay
2.5.14Mapping for gYear
2.5.15Mapping for gYearMonth
2.5.16Mapping for time
-
2.6Mapping for Simple Types - - - - - -
2.6.1Mapping for Derivation by Restriction
2.6.2Mapping for Enumerations
2.6.3Mapping for Derivation by List
2.6.4Mapping for Derivation by Union
-
2.7Mapping for Complex Types - - - -
2.7.1Mapping for Derivation by Extension
2.7.2Mapping for Derivation by Restriction
-
2.8Mapping for Local Elements and Attributes - - - - - -
2.8.1Mapping for Members with the One Cardinality Class
2.8.2Mapping for Members with the Optional Cardinality Class
2.8.3Mapping for Members with the Sequence Cardinality Class
2.8.4Element Order
-
2.9Mapping for Global Elements - - - -
2.9.1Element Types
2.9.2Element Map
-
2.10Mapping for Global Attributes
2.11Mapping for xsi:type and Substitution Groups
2.12Mapping for any and anyAttribute - - - - - - -
2.12.1Mapping for any with the One Cardinality Class
2.12.2Mapping for any with the Optional Cardinality Class
2.12.3Mapping for any with the Sequence Cardinality Class
2.12.4Element Wildcard Order
2.12.5Mapping for anyAttribute
-
2.13Mapping for Mixed Content Models
-
3Parsing - - - - - - - - - - - - - - - - - - - - - - -
3.1Initializing the Xerces-C++ Runtime
3.2Flags and Properties
3.3Error Handling - - - - - - - - - - -
3.3.1xml_schema::parsing
3.3.2xml_schema::expected_element
3.3.3xml_schema::unexpected_element
3.3.4xml_schema::expected_attribute
3.3.5xml_schema::unexpected_enumerator
3.3.6xml_schema::expected_text_content
3.3.7xml_schema::no_type_info
3.3.8xml_schema::not_derived
3.3.9xml_schema::not_prefix_mapping
-
3.4Reading from a Local File or URI
3.5Reading from std::istream
3.6Reading from xercesc::InputSource
3.7Reading from DOM
-
4Serialization - - - - - - - - - - - - - - - - - - - - - - -
4.1Initializing the Xerces-C++ Runtime
4.2Namespace Infomap and Character Encoding
4.3Flags
4.4Error Handling - - - - -
4.4.1xml_schema::serialization
4.4.2xml_schema::unexpected_element
4.4.3xml_schema::no_type_info
-
4.5Serializing to std::ostream
4.6Serializing to xercesc::XMLFormatTarget
4.7Serializing to DOM
-
5Additional Functionality - - - - - - - -
5.1DOM Association
5.2Binary Serialization
-
Appendix A — Default and Fixed Values
-
- -

Preface

- -

About This Document

- -

This document describes the mapping of W3C XML Schema - to the C++ programming language as implemented by - CodeSynthesis - XSD - an XML Schema to C++ data binding compiler. The mapping - represents information stored in XML instance documents as a - statically-typed, tree-like in-memory data structure and is - called C++/Tree. -

- -

Revision 4.1.0
- This revision of the manual describes the C++/Tree - mapping as implemented by CodeSynthesis XSD version 4.1.0. -

- -

This document is available in the following formats: - XHTML, - PDF, and - PostScript.

- -

More Information

- -

Beyond this manual, you may also find the following sources of - information useful:

- - - - -

1 Introduction

- -

C++/Tree is a W3C XML Schema to C++ mapping that represents the - data stored in XML as a statically-typed, vocabulary-specific - object model. Based on a formal description of an XML vocabulary - (schema), the C++/Tree mapping produces a tree-like data structure - suitable for in-memory processing as well as XML parsing and - serialization code.

- -

A typical application that processes XML documents usually - performs the following three steps: it first reads (parses) an XML - instance document to an object model, it then performs - some useful computations on that model which may involve - modification of the model, and finally it may write (serialize) - the modified object model back to XML. -

- -

The C++/Tree mapping consists of C++ types that represent the - given vocabulary (Chapter 2, "C++/Tree Mapping"), - a set of parsing functions that convert XML documents to - a tree-like in-memory data structure (Chapter 3, - "Parsing"), and a set of serialization functions that convert - the object model back to XML (Chapter 4, - "Serialization"). Furthermore, the mapping provides a number - of additional features, such as DOM association and binary - serialization, that can be useful in some applications - (Chapter 5, "Additional Functionality"). -

- - - - - -

2 C++/Tree Mapping

- -

2.1 Preliminary Information

- -

2.1.1 C++ Standard

- -

The C++/Tree mapping provides support for ISO/IEC C++ 1998/2003 (C++98) - and ISO/IEC C++ 2011 (C++11). To select the C++ standard for the - generated code we use the --std XSD compiler command - line option. While the majority of the examples in this manual use - C++98, support for the new functionality and library components - introduced in C++11 are discussed throughout the document.

- -

2.1.2 Identifiers

- -

XML Schema names may happen to be reserved C++ keywords or contain - characters that are illegal in C++ identifiers. To avoid C++ compilation - problems, such names are changed (escaped) when mapped to C++. If an - XML Schema name is a C++ keyword, the "_" suffix is added to it. All - character of an XML Schema name that are not allowed in C++ identifiers - are replaced with "_". -

- -

For example, XML Schema name try will be mapped to - C++ identifier try_. Similarly, XML Schema name - strange.na-me will be mapped to C++ identifier - strange_na_me. -

- -

Furthermore, conflicts between type names and function names in the - same scope are resolved using name escaping. Such conflicts include - both a global element (which is mapped to a set of parsing and/or - serialization functions or element types, see Section - 2.9, "Mapping for Global Elements") and a global type sharing the - same name as well as a local element or attribute inside a type having - the same name as the type itself.

- -

For example, if we had a global type catalog - and a global element with the same name then the type would be - mapped to a C++ class with name catalog while the - parsing functions corresponding to the global element would have - their names escaped as catalog_. -

- -

By default the mapping uses the so-called K&R (Kernighan and - Ritchie) identifier naming convention which is also used throughout - this manual. In this convention both type and function names are in - lower case and words are separated by underscores. If your application - code or schemas use a different notation, you may want to change the - naming convention used by the mapping for consistency. - The compiler supports a set of widely-used naming conventions - that you can select with the --type-naming and - --function-naming options. You can also further - refine one of the predefined conventions or create a completely - custom naming scheme by using the --*-regex options. - For more detailed information on these options refer to the NAMING - CONVENTION section in the XSD - Compiler Command Line Manual.

- -

2.1.3 Character Type and Encoding

- -

The code that implements the mapping, depending on the - --char-type option, is generated using either - char or wchar_t as the character - type. In this document code samples use symbol C - to refer to the character type you have selected when translating - your schemas, for example std::basic_string<C>. -

- -

Another aspect of the mapping that depends on the character type - is character encoding. For the char character type - the default encoding is UTF-8. Other supported encodings are - ISO-8859-1, Xerces-C++ Local Code Page (LPC), as well as - custom encodings and can be selected with the - --char-encoding command line option.

- -

For the wchar_t character type the encoding is - automatically selected between UTF-16 and UTF-32/UCS-4 depending - on the size of the wchar_t type. On some platforms - (for example, Windows with Visual C++ and AIX with IBM XL C++) - wchar_t is 2 bytes long. For these platforms the - encoding is UTF-16. On other platforms wchar_t is 4 bytes - long and UTF-32/UCS-4 is used.

- -

2.1.4 XML Schema Namespace

- -

The mapping relies on some predefined types, classes, and functions - that are logically defined in the XML Schema namespace reserved for - the XML Schema language (http://www.w3.org/2001/XMLSchema). - By default, this namespace is mapped to C++ namespace - xml_schema. It is automatically accessible - from a C++ compilation unit that includes a header file generated - from an XML Schema definition. -

- -

Note that, if desired, the default mapping of this namespace can be - changed as described in Section 2.4, "Mapping for - Namespaces". -

- - -

2.1.5 Anonymous Types

- -

For the purpose of code generation, anonymous types defined in - XML Schema are automatically assigned names that are derived - from enclosing attributes and elements. Otherwise, such types - follows standard mapping rules for simple and complex type - definitions (see Section 2.6, "Mapping for Simple Types" - and Section 2.7, "Mapping for Complex Types"). - For example, in the following schema fragment: -

- -
-<element name="object">
-  <complexType>
-    ...
-  </complexType>
-</element>
-  
- -

The anonymous type defined inside element object will - be given name object. The compiler has a number of - options that control the process of anonymous type naming. For more - information refer to the XSD - Compiler Command Line Manual.

- - -

2.2 Error Handling

- -

The mapping uses the C++ exception handling mechanism as a primary way - of reporting error conditions. All exceptions that are specified in - this mapping derive from xml_schema::exception which - itself is derived from std::exception: -

- -
-struct exception: virtual std::exception
-{
-  friend
-  std::basic_ostream<C>&
-  operator<< (std::basic_ostream<C>& os, const exception& e)
-  {
-    e.print (os);
-    return os;
-  }
-
-protected:
-  virtual void
-  print (std::basic_ostream<C>&) const = 0;
-};
-  
- -

The exception hierarchy supports "virtual" operator<< - which allows you to obtain diagnostics corresponding to the thrown - exception using the base exception interface. For example:

- -
-try
-{
-  ...
-}
-catch (const xml_schema::exception& e)
-{
-  cerr << e << endl;
-}
-  
- -

The following sub-sections describe exceptions thrown by the - types that constitute the object model. - Section 3.3, "Error Handling" of - Chapter 3, "Parsing" describes exceptions - and error handling mechanisms specific to the parsing functions. - Section 4.4, "Error Handling" of - Chapter 4, "Serialization" describes exceptions - and error handling mechanisms specific to the serialization functions. -

- - -

2.2.1 xml_schema::duplicate_id

- -
-struct duplicate_id: virtual exception
-{
-  duplicate_id (const std::basic_string<C>& id);
-
-  const std::basic_string<C>&
-  id () const;
-
-  virtual const char*
-  what () const throw ();
-};
-  
- -

The xml_schema::duplicate_id is thrown when - a conflicting instance of xml_schema::id (see - Section 2.5, "Mapping for Built-in Data Types") - is added to a tree. The offending ID value can be obtained using - the id function. -

- -

2.3 Mapping for import and include

- -

2.3.1 Import

- -

The XML Schema import element is mapped to the C++ - Preprocessor #include directive. The value of - the schemaLocation attribute is used to derive - the name of the header file that appears in the #include - directive. For instance: -

- -
-<import namespace="https://www.codesynthesis.com/test"
-        schemaLocation="test.xsd"/>
-  
- -

is mapped to:

- -
-#include "test.hxx"
-  
- -

Note that you will need to compile imported schemas separately - in order to produce corresponding header files.

- -

2.3.2 Inclusion with Target Namespace

- -

The XML Schema include element which refers to a schema - with a target namespace or appears in a schema without a target namespace - follows the same mapping rules as the import element, - see Section 2.3.1, "Import". -

- -

2.3.3 Inclusion without Target Namespace

- -

For the XML Schema include element which refers to a schema - without a target namespace and appears in a schema with a target - namespace (such inclusion sometimes called "chameleon inclusion"), - declarations and definitions from the included schema are generated - in-line in the namespace of the including schema as if they were - declared and defined there verbatim. For example, consider the - following two schemas: -

- -
-<-- common.xsd -->
-<schema>
-  <complexType name="type">
-  ...
-  </complexType>
-</schema>
-
-<-- test.xsd -->
-<schema targetNamespace="https://www.codesynthesis.com/test">
-  <include schemaLocation="common.xsd"/>
-</schema>
-  
- -

The fragment of interest from the generated header file for - text.xsd would look like this:

- -
-// test.hxx
-namespace test
-{
-  class type
-  {
-    ...
-  };
-}
-  
- -

2.4 Mapping for Namespaces

- -

An XML Schema namespace is mapped to one or more nested C++ - namespaces. XML Schema namespaces are identified by URIs. - By default, a namespace URI is mapped to a sequence of - C++ namespace names by removing the protocol and host parts - and splitting the rest into a sequence of names with '/' - as the name separator. For instance: -

- -
-<schema targetNamespace="https://www.codesynthesis.com/system/test">
-  ...
-</schema>
-  
- -

is mapped to:

- -
-namespace system
-{
-  namespace test
-  {
-    ...
-  }
-}
-  
- -

The default mapping of namespace URIs to C++ namespace names can be - altered using the --namespace-map and - --namespace-regex options. See the - XSD - Compiler Command Line Manual for more information. -

- -

2.5 Mapping for Built-in Data Types

- -

The mapping of XML Schema built-in data types to C++ types is - summarized in the table below.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
XML Schema typeAlias in the xml_schema namespaceC++ type
anyType and anySimpleType types
anyTypetypeSection 2.5.2, "Mapping for anyType"
anySimpleTypesimple_typeSection 2.5.3, "Mapping for anySimpleType"
fixed-length integral types
bytebytesigned char
unsignedByteunsigned_byteunsigned char
shortshort_short
unsignedShortunsigned_shortunsigned short
intint_int
unsignedIntunsigned_intunsigned int
longlong_long long
unsignedLongunsigned_longunsigned long long
arbitrary-length integral types
integerintegerlong long
nonPositiveIntegernon_positive_integerlong long
nonNegativeIntegernon_negative_integerunsigned long long
positiveIntegerpositive_integerunsigned long long
negativeIntegernegative_integerlong long
boolean types
booleanbooleanbool
fixed-precision floating-point types
floatfloat_float
doubledouble_double
arbitrary-precision floating-point types
decimaldecimaldouble
string types
stringstringtype derived from std::basic_string
normalizedStringnormalized_stringtype derived from string
tokentokentype derived from normalized_string
Namenametype derived from token
NMTOKENnmtokentype derived from token
NMTOKENSnmtokenstype derived from sequence<nmtoken>
NCNamencnametype derived from name
languagelanguagetype derived from token
qualified name
QNameqnameSection 2.5.4, "Mapping for QName"
ID/IDREF types
IDidtype derived from ncname
IDREFidrefSection 2.5.5, "Mapping for IDREF"
IDREFSidrefstype derived from sequence<idref>
URI types
anyURIuritype derived from std::basic_string
binary types
base64Binarybase64_binarySection 2.5.6, "Mapping for - base64Binary and hexBinary"
hexBinaryhex_binary
date/time types
datedateSection 2.5.8, "Mapping for - date"
dateTimedate_timeSection 2.5.9, "Mapping for - dateTime"
durationdurationSection 2.5.10, "Mapping for - duration"
gDaygdaySection 2.5.11, "Mapping for - gDay"
gMonthgmonthSection 2.5.12, "Mapping for - gMonth"
gMonthDaygmonth_daySection 2.5.13, "Mapping for - gMonthDay"
gYeargyearSection 2.5.14, "Mapping for - gYear"
gYearMonthgyear_monthSection 2.5.15, "Mapping for - gYearMonth"
timetimeSection 2.5.16, "Mapping for - time"
entity types
ENTITYentitytype derived from name
ENTITIESentitiestype derived from sequence<entity>
- -

All XML Schema built-in types are mapped to C++ classes that are - derived from the xml_schema::simple_type class except - where the mapping is to a fundamental C++ type.

- -

The sequence class template is defined in an - implementation-specific namespace. It conforms to the - sequence interface as defined by the ISO/ANSI Standard for - C++ (ISO/IEC 14882:1998, Section 23.1.1, "Sequences"). - Practically, this means that you can treat such a sequence - as if it was std::vector. One notable extension - to the standard interface that is available only for - sequences of non-fundamental C++ types is the addition of - the overloaded push_back and insert - member functions which instead of the constant reference - to the element type accept automatic pointer (std::auto_ptr - or std::unique_ptr, depending on the C++ standard - selected) to the element type. These functions assume ownership - of the pointed to object and reset the passed automatic pointer. -

- -

2.5.1 Inheritance from Built-in Data Types

- -

In cases where the mapping calls for an inheritance from a built-in - type which is mapped to a fundamental C++ type, a proxy type is - used instead of the fundamental C++ type (C++ does not allow - inheritance from fundamental types). For instance:

- -
-<simpleType name="my_int">
-  <restriction base="int"/>
-</simpleType>
-  
- -

is mapped to:

- -
-class my_int: public fundamental_base<int>
-{
-  ...
-};
-  
- -

The fundamental_base class template provides a close - emulation (though not exact) of a fundamental C++ type. - It is defined in an implementation-specific namespace and has the - following interface:

- -
-template <typename X>
-class fundamental_base: public simple_type
-{
-public:
-  fundamental_base ();
-  fundamental_base (X)
-  fundamental_base (const fundamental_base&)
-
-public:
-  fundamental_base&
-  operator= (const X&);
-
-public:
-  operator const X & () const;
-  operator X& ();
-
-  template <typename Y>
-  operator Y () const;
-
-  template <typename Y>
-  operator Y ();
-};
-  
- -

2.5.2 Mapping for anyType

- -

The XML Schema anyType built-in data type is mapped to the - xml_schema::type C++ class:

- -
-class type
-{
-public:
-  virtual
-  ~type ();
-
-  type ();
-  type (const type&);
-
-  type&
-  operator= (const type&);
-
-  virtual type*
-  _clone () const;
-
-  // anyType DOM content.
-  //
-public:
-  typedef element_optional dom_content_optional;
-
-  const dom_content_optional&
-  dom_content () const;
-
-  dom_content_optional&
-  dom_content ();
-
-  void
-  dom_content (const xercesc::DOMElement&);
-
-  void
-  dom_content (xercesc::DOMElement*);
-
-  void
-  dom_content (const dom_content_optional&);
-
-  const xercesc::DOMDocument&
-  dom_content_document () const;
-
-  xercesc::DOMDocument&
-  dom_content_document ();
-
-  bool
-  null_content () const;
-
-  // DOM association.
-  //
-public:
-  const xercesc::DOMNode*
-  _node () const;
-
-  xercesc::DOMNode*
-  _node ();
-};
-  
- -

When xml_schema::type is used to create an instance - (as opposed to being a base of a derived type), it represents - the XML Schema anyType type. anyType - allows any attributes and any content in any order. In the - C++/Tree mapping this content can be represented as a DOM - fragment, similar to XML Schema wildcards (Section - 2.12, "Mapping for any and - anyAttribute").

- -

To enable automatic extraction of anyType content - during parsing, the --generate-any-type option must be - specified. Because the DOM API is used to access such content, the - Xerces-C++ runtime should be initialized by the application prior to - parsing and should remain initialized for the lifetime of objects - with the DOM content. For more information on the Xerces-C++ runtime - initialization see Section 3.1, "Initializing the - Xerces-C++ Runtime".

- -

The DOM content is stored as the optional DOM element container - and the DOM content accessors and modifiers presented above are - identical to those generated for an optional element wildcard. - Refer to Section 2.12.2, "Mapping for any - with the Optional Cardinality Class" for details on their - semantics.

- -

The dom_content_document() function returns the - DOM document used to store the raw XML content corresponding - to the anyType instance. It is equivalent to the - dom_document() function generated for types - with wildcards.

- -

The null_content() accessor is an optimization function - that allows us to check for the lack of content without actually - creating its empty representation, that is, empty DOM document for - anyType or empty string for anySimpleType - (see the following section for details on anySimpleType).

- -

For more information on DOM association refer to - Section 5.1, "DOM Association".

- -

2.5.3 Mapping for anySimpleType

- -

The XML Schema anySimpleType built-in data type is mapped - to the xml_schema::simple_type C++ class:

- -
-class simple_type: public type
-{
-public:
-  simple_type ();
-  simple_type (const C*);
-  simple_type (const std::basic_string<C>&);
-
-  simple_type (const simple_type&);
-
-  simple_type&
-  operator= (const simple_type&);
-
-  virtual simple_type*
-  _clone () const;
-
-  // anySimpleType text content.
-  //
-public:
-  const std::basic_string<C>&
-  text_content () const;
-
-  std::basic_string<C>&
-  text_content ();
-
-  void
-  text_content (const std::basic_string<C>&);
-};
-  
- -

When xml_schema::simple_type is used to create an instance - (as opposed to being a base of a derived type), it represents - the XML Schema anySimpleType type. anySimpleType - allows any simple content. In the C++/Tree mapping this content can - be represented as a string and accessed or modified with the - text_content() functions shown above.

- -

2.5.4 Mapping for QName

- -

The XML Schema QName built-in data type is mapped to the - xml_schema::qname C++ class:

- -
-class qname: public simple_type
-{
-public:
-  qname (const ncname&);
-  qname (const uri&, const ncname&);
-  qname (const qname&);
-
-public:
-  qname&
-  operator= (const qname&);
-
-public:
-  virtual qname*
-  _clone () const;
-
-public:
-  bool
-  qualified () const;
-
-  const uri&
-  namespace_ () const;
-
-  const ncname&
-  name () const;
-};
-  
- -

The qualified accessor function can be used to determine - if the name is qualified.

- -

2.5.5 Mapping for IDREF

- -

The XML Schema IDREF built-in data type is mapped to the - xml_schema::idref C++ class. This class implements the - smart pointer C++ idiom:

- -
-class idref: public ncname
-{
-public:
-  idref (const C* s);
-  idref (const C* s, std::size_t n);
-  idref (std::size_t n, C c);
-  idref (const std::basic_string<C>&);
-  idref (const std::basic_string<C>&,
-         std::size_t pos,
-         std::size_t n = npos);
-
-public:
-  idref (const idref&);
-
-public:
-  virtual idref*
-  _clone () const;
-
-public:
-  idref&
-  operator= (C c);
-
-  idref&
-  operator= (const C* s);
-
-  idref&
-  operator= (const std::basic_string<C>&)
-
-  idref&
-  operator= (const idref&);
-
-public:
-  const type*
-  operator-> () const;
-
-  type*
-  operator-> ();
-
-  const type&
-  operator* () const;
-
-  type&
-  operator* ();
-
-  const type*
-  get () const;
-
-  type*
-  get ();
-
-  // Conversion to bool.
-  //
-public:
-  typedef void (idref::*bool_convertible)();
-  operator bool_convertible () const;
-};
-  
- -

The object, idref instance refers to, is the immediate - container of the matching id instance. For example, - with the following instance document and schema: -

- - -
-<!-- test.xml -->
-<root>
-  <object id="obj-1" text="hello"/>
-  <reference>obj-1</reference>
-</root>
-
-<!-- test.xsd -->
-<schema>
-  <complexType name="object_type">
-    <attribute name="id" type="ID"/>
-    <attribute name="text" type="string"/>
-  </complexType>
-
-  <complexType name="root_type">
-    <sequence>
-      <element name="object" type="object_type"/>
-      <element name="reference" type="IDREF"/>
-    </sequence>
-  </complexType>
-
-  <element name="root" type="root_type"/>
-</schema>
-  
- -

The ref instance in the code below will refer to - an object of type object_type:

- -
-root_type& root = ...;
-xml_schema::idref& ref (root.reference ());
-object_type& obj (dynamic_cast<object_type&> (*ref));
-cout << obj.text () << endl;
-  
- -

The smart pointer interface of the idref class always - returns a pointer or reference to xml_schema::type. - This means that you will need to manually cast such pointer or - reference to its real (dynamic) type before you can use it (unless - all you need is the base interface provided by - xml_schema::type). As a special extension to the XML - Schema language, the mapping supports static typing of idref - references by employing the refType extension attribute. - The following example illustrates this mechanism: -

- -
-<!-- test.xsd -->
-<schema
-  xmlns:xse="https://www.codesynthesis.com/xmlns/xml-schema-extension">
-
-  ...
-
-      <element name="reference" type="IDREF" xse:refType="object_type"/>
-
-  ...
-
-</schema>
-  
- -

With this modification we do not need to do manual casting anymore: -

- -
-root_type& root = ...;
-root_type::reference_type& ref (root.reference ());
-object_type& obj (*ref);
-cout << ref->text () << endl;
-  
- - -

2.5.6 Mapping for base64Binary and - hexBinary

- -

The XML Schema base64Binary and hexBinary - built-in data types are mapped to the - xml_schema::base64_binary and - xml_schema::hex_binary C++ classes, respectively. The - base64_binary and hex_binary classes - support a simple buffer abstraction by inheriting from the - xml_schema::buffer class: -

- -
-class bounds: public virtual exception
-{
-public:
-  virtual const char*
-  what () const throw ();
-};
-
-class buffer
-{
-public:
-  typedef std::size_t size_t;
-
-public:
-  buffer (size_t size = 0);
-  buffer (size_t size, size_t capacity);
-  buffer (const void* data, size_t size);
-  buffer (const void* data, size_t size, size_t capacity);
-  buffer (void* data,
-          size_t size,
-          size_t capacity,
-          bool assume_ownership);
-
-public:
-  buffer (const buffer&);
-
-  buffer&
-  operator= (const buffer&);
-
-  void
-  swap (buffer&);
-
-public:
-  size_t
-  capacity () const;
-
-  bool
-  capacity (size_t);
-
-public:
-  size_t
-  size () const;
-
-  bool
-  size (size_t);
-
-public:
-  const char*
-  data () const;
-
-  char*
-  data ();
-
-  const char*
-  begin () const;
-
-  char*
-  begin ();
-
-  const char*
-  end () const;
-
-  char*
-  end ();
-};
-  
- -

The last overloaded constructor reuses an existing data buffer instead - of making a copy. If the assume_ownership argument is - true, the instance assumes ownership of the - memory block pointed to by the data argument and will - eventually release it by calling operator delete. The - capacity and size modifier functions return - true if the underlying buffer has moved. -

- -

The bounds exception is thrown if the constructor - arguments violate the (size <= capacity) - constraint.

- -

The base64_binary and hex_binary classes - support the buffer interface and perform automatic - decoding/encoding from/to the Base64 and Hex formats, respectively: -

- -
-class base64_binary: public simple_type, public buffer
-{
-public:
-  base64_binary (size_t size = 0);
-  base64_binary (size_t size, size_t capacity);
-  base64_binary (const void* data, size_t size);
-  base64_binary (const void* data, size_t size, size_t capacity);
-  base64_binary (void* data,
-                 size_t size,
-                 size_t capacity,
-                 bool assume_ownership);
-
-public:
-  base64_binary (const base64_binary&);
-
-  base64_binary&
-  operator= (const base64_binary&);
-
-  virtual base64_binary*
-  _clone () const;
-
-public:
-  std::basic_string<C>
-  encode () const;
-};
-  
- -
-class hex_binary: public simple_type, public buffer
-{
-public:
-  hex_binary (size_t size = 0);
-  hex_binary (size_t size, size_t capacity);
-  hex_binary (const void* data, size_t size);
-  hex_binary (const void* data, size_t size, size_t capacity);
-  hex_binary (void* data,
-              size_t size,
-              size_t capacity,
-              bool assume_ownership);
-
-public:
-  hex_binary (const hex_binary&);
-
-  hex_binary&
-  operator= (const hex_binary&);
-
-  virtual hex_binary*
-  _clone () const;
-
-public:
-  std::basic_string<C>
-  encode () const;
-};
-  
- - -

2.5.7 Time Zone Representation

- -

The date, dateTime, gDay, - gMonth, gMonthDay, gYear, - gYearMonth, and time XML Schema built-in - types all include an optional time zone component. The following - xml_schema::time_zone base class is used to represent - this information:

- -
-class time_zone
-{
-public:
-  time_zone ();
-  time_zone (short hours, short minutes);
-
-  bool
-  zone_present () const;
-
-  void
-  zone_reset ();
-
-  short
-  zone_hours () const;
-
-  void
-  zone_hours (short);
-
-  short
-  zone_minutes () const;
-
-  void
-  zone_minutes (short);
-};
-
-bool
-operator== (const time_zone&, const time_zone&);
-
-bool
-operator!= (const time_zone&, const time_zone&);
-  
- -

The zone_present() accessor function returns true - if the time zone is specified. The zone_reset() modifier - function resets the time zone object to the not specified - state. If the time zone offset is negative then both hours and - minutes components are represented as negative integers.

- - -

2.5.8 Mapping for date

- -

The XML Schema date built-in data type is mapped to the - xml_schema::date C++ class which represents a year, a day, - and a month with an optional time zone. Its interface is presented - below. For more information on the base xml_schema::time_zone - class refer to Section 2.5.7, "Time Zone - Representation".

- -
-class date: public simple_type, public time_zone
-{
-public:
-  date (int year, unsigned short month, unsigned short day);
-  date (int year, unsigned short month, unsigned short day,
-        short zone_hours, short zone_minutes);
-
-public:
-  date (const date&);
-
-  date&
-  operator= (const date&);
-
-  virtual date*
-  _clone () const;
-
-public:
-  int
-  year () const;
-
-  void
-  year (int);
-
-  unsigned short
-  month () const;
-
-  void
-  month (unsigned short);
-
-  unsigned short
-  day () const;
-
-  void
-  day (unsigned short);
-};
-
-bool
-operator== (const date&, const date&);
-
-bool
-operator!= (const date&, const date&);
-  
- -

2.5.9 Mapping for dateTime

- -

The XML Schema dateTime built-in data type is mapped to the - xml_schema::date_time C++ class which represents a year, a month, - a day, hours, minutes, and seconds with an optional time zone. Its interface - is presented below. For more information on the base - xml_schema::time_zone class refer to Section - 2.5.7, "Time Zone Representation".

- -
-class date_time: public simple_type, public time_zone
-{
-public:
-  date_time (int year, unsigned short month, unsigned short day,
-             unsigned short hours, unsigned short minutes,
-             double seconds);
-
-  date_time (int year, unsigned short month, unsigned short day,
-             unsigned short hours, unsigned short minutes,
-             double seconds, short zone_hours, short zone_minutes);
-public:
-  date_time (const date_time&);
-
-  date_time&
-  operator= (const date_time&);
-
-  virtual date_time*
-  _clone () const;
-
-public:
-  int
-  year () const;
-
-  void
-  year (int);
-
-  unsigned short
-  month () const;
-
-  void
-  month (unsigned short);
-
-  unsigned short
-  day () const;
-
-  void
-  day (unsigned short);
-
-  unsigned short
-  hours () const;
-
-  void
-  hours (unsigned short);
-
-  unsigned short
-  minutes () const;
-
-  void
-  minutes (unsigned short);
-
-  double
-  seconds () const;
-
-  void
-  seconds (double);
-};
-
-bool
-operator== (const date_time&, const date_time&);
-
-bool
-operator!= (const date_time&, const date_time&);
-  
- - -

2.5.10 Mapping for duration

- -

The XML Schema duration built-in data type is mapped to the - xml_schema::duration C++ class which represents a potentially - negative duration in the form of years, months, days, hours, minutes, - and seconds. Its interface is presented below.

- -
-class duration: public simple_type
-{
-public:
-  duration (bool negative,
-            unsigned int years, unsigned int months, unsigned int days,
-            unsigned int hours, unsigned int minutes, double seconds);
-public:
-  duration (const duration&);
-
-  duration&
-  operator= (const duration&);
-
-  virtual duration*
-  _clone () const;
-
-public:
-  bool
-  negative () const;
-
-  void
-  negative (bool);
-
-  unsigned int
-  years () const;
-
-  void
-  years (unsigned int);
-
-  unsigned int
-  months () const;
-
-  void
-  months (unsigned int);
-
-  unsigned int
-  days () const;
-
-  void
-  days (unsigned int);
-
-  unsigned int
-  hours () const;
-
-  void
-  hours (unsigned int);
-
-  unsigned int
-  minutes () const;
-
-  void
-  minutes (unsigned int);
-
-  double
-  seconds () const;
-
-  void
-  seconds (double);
-};
-
-bool
-operator== (const duration&, const duration&);
-
-bool
-operator!= (const duration&, const duration&);
-  
- - -

2.5.11 Mapping for gDay

- -

The XML Schema gDay built-in data type is mapped to the - xml_schema::gday C++ class which represents a day of the - month with an optional time zone. Its interface is presented below. - For more information on the base xml_schema::time_zone - class refer to Section 2.5.7, "Time Zone - Representation".

- -
-class gday: public simple_type, public time_zone
-{
-public:
-  explicit
-  gday (unsigned short day);
-  gday (unsigned short day, short zone_hours, short zone_minutes);
-
-public:
-  gday (const gday&);
-
-  gday&
-  operator= (const gday&);
-
-  virtual gday*
-  _clone () const;
-
-public:
-  unsigned short
-  day () const;
-
-  void
-  day (unsigned short);
-};
-
-bool
-operator== (const gday&, const gday&);
-
-bool
-operator!= (const gday&, const gday&);
-  
- - -

2.5.12 Mapping for gMonth

- -

The XML Schema gMonth built-in data type is mapped to the - xml_schema::gmonth C++ class which represents a month of the - year with an optional time zone. Its interface is presented below. - For more information on the base xml_schema::time_zone - class refer to Section 2.5.7, "Time Zone - Representation".

- -
-class gmonth: public simple_type, public time_zone
-{
-public:
-  explicit
-  gmonth (unsigned short month);
-  gmonth (unsigned short month,
-          short zone_hours, short zone_minutes);
-
-public:
-  gmonth (const gmonth&);
-
-  gmonth&
-  operator= (const gmonth&);
-
-  virtual gmonth*
-  _clone () const;
-
-public:
-  unsigned short
-  month () const;
-
-  void
-  month (unsigned short);
-};
-
-bool
-operator== (const gmonth&, const gmonth&);
-
-bool
-operator!= (const gmonth&, const gmonth&);
-  
- - -

2.5.13 Mapping for gMonthDay

- -

The XML Schema gMonthDay built-in data type is mapped to the - xml_schema::gmonth_day C++ class which represents a day and - a month of the year with an optional time zone. Its interface is presented - below. For more information on the base xml_schema::time_zone - class refer to Section 2.5.7, "Time Zone - Representation".

- -
-class gmonth_day: public simple_type, public time_zone
-{
-public:
-  gmonth_day (unsigned short month, unsigned short day);
-  gmonth_day (unsigned short month, unsigned short day,
-              short zone_hours, short zone_minutes);
-
-public:
-  gmonth_day (const gmonth_day&);
-
-  gmonth_day&
-  operator= (const gmonth_day&);
-
-  virtual gmonth_day*
-  _clone () const;
-
-public:
-  unsigned short
-  month () const;
-
-  void
-  month (unsigned short);
-
-  unsigned short
-  day () const;
-
-  void
-  day (unsigned short);
-};
-
-bool
-operator== (const gmonth_day&, const gmonth_day&);
-
-bool
-operator!= (const gmonth_day&, const gmonth_day&);
-  
- - -

2.5.14 Mapping for gYear

- -

The XML Schema gYear built-in data type is mapped to the - xml_schema::gyear C++ class which represents a year with - an optional time zone. Its interface is presented below. For more - information on the base xml_schema::time_zone class refer - to Section 2.5.7, "Time Zone Representation".

- -
-class gyear: public simple_type, public time_zone
-{
-public:
-  explicit
-  gyear (int year);
-  gyear (int year, short zone_hours, short zone_minutes);
-
-public:
-  gyear (const gyear&);
-
-  gyear&
-  operator= (const gyear&);
-
-  virtual gyear*
-  _clone () const;
-
-public:
-  int
-  year () const;
-
-  void
-  year (int);
-};
-
-bool
-operator== (const gyear&, const gyear&);
-
-bool
-operator!= (const gyear&, const gyear&);
-  
- - -

2.5.15 Mapping for gYearMonth

- -

The XML Schema gYearMonth built-in data type is mapped to - the xml_schema::gyear_month C++ class which represents - a year and a month with an optional time zone. Its interface is presented - below. For more information on the base xml_schema::time_zone - class refer to Section 2.5.7, "Time Zone - Representation".

- -
-class gyear_month: public simple_type, public time_zone
-{
-public:
-  gyear_month (int year, unsigned short month);
-  gyear_month (int year, unsigned short month,
-               short zone_hours, short zone_minutes);
-public:
-  gyear_month (const gyear_month&);
-
-  gyear_month&
-  operator= (const gyear_month&);
-
-  virtual gyear_month*
-  _clone () const;
-
-public:
-  int
-  year () const;
-
-  void
-  year (int);
-
-  unsigned short
-  month () const;
-
-  void
-  month (unsigned short);
-};
-
-bool
-operator== (const gyear_month&, const gyear_month&);
-
-bool
-operator!= (const gyear_month&, const gyear_month&);
-  
- - -

2.5.16 Mapping for time

- -

The XML Schema time built-in data type is mapped to - the xml_schema::time C++ class which represents hours, - minutes, and seconds with an optional time zone. Its interface is - presented below. For more information on the base - xml_schema::time_zone class refer to - Section 2.5.7, "Time Zone Representation".

- -
-class time: public simple_type, public time_zone
-{
-public:
-  time (unsigned short hours, unsigned short minutes, double seconds);
-  time (unsigned short hours, unsigned short minutes, double seconds,
-        short zone_hours, short zone_minutes);
-
-public:
-  time (const time&);
-
-  time&
-  operator= (const time&);
-
-  virtual time*
-  _clone () const;
-
-public:
-  unsigned short
-  hours () const;
-
-  void
-  hours (unsigned short);
-
-  unsigned short
-  minutes () const;
-
-  void
-  minutes (unsigned short);
-
-  double
-  seconds () const;
-
-  void
-  seconds (double);
-};
-
-bool
-operator== (const time&, const time&);
-
-bool
-operator!= (const time&, const time&);
-  
- - - - -

2.6 Mapping for Simple Types

- -

An XML Schema simple type is mapped to a C++ class with the same - name as the simple type. The class defines a public copy constructor, - a public copy assignment operator, and a public virtual - _clone function. The _clone function is - declared const, does not take any arguments, and returns - a pointer to a complete copy of the instance allocated in the free - store. The _clone function shall be used to make copies - when static type and dynamic type of the instance may differ (see - Section 2.11, "Mapping for xsi:type - and Substitution Groups"). For instance:

- -
-<simpleType name="object">
-  ...
-</simpleType>
-  
- -

is mapped to:

- -
-class object: ...
-{
-public:
-  object (const object&);
-
-public:
-  object&
-  operator= (const object&);
-
-public:
-  virtual object*
-  _clone () const;
-
-  ...
-
-};
-  
- -

The base class specification and the rest of the class definition - depend on the type of derivation used to define the simple type.

- - -

2.6.1 Mapping for Derivation by Restriction

- -

XML Schema derivation by restriction is mapped to C++ public - inheritance. The base type of the restriction becomes the base - type for the resulting C++ class. In addition to the members described - in Section 2.6, "Mapping for Simple Types", the - resulting C++ class defines a public constructor with the base type - as its single argument. For instance:

- -
-<simpleType name="object">
-  <restriction base="base">
-    ...
-  </restriction>
-</simpleType>
-  
- -

is mapped to:

- -
-class object: public base
-{
-public:
-  object (const base&);
-  object (const object&);
-
-public:
-  object&
-  operator= (const object&);
-
-public:
-  virtual object*
-  _clone () const;
-};
-  
- - -

2.6.2 Mapping for Enumerations

- -

XML Schema restriction by enumeration is mapped to a C++ class - with semantics similar to C++ enum. Each XML Schema - enumeration element is mapped to a C++ enumerator with the - name derived from the value attribute and defined - in the class scope. In addition to the members - described in Section 2.6, "Mapping for Simple Types", - the resulting C++ class defines a public constructor that can be called - with one of the enumerators as its single argument, a public constructor - that can be called with enumeration's base value as its single - argument, a public assignment operator that can be used to assign the - value of one of the enumerators, and a public implicit conversion - operator to the underlying C++ enum type.

- -

Furthermore, for string-based enumeration types, the resulting C++ - class defines a public constructor with a single argument of type - const C* and a public constructor with a single - argument of type const std::basic_string<C>&. - For instance:

- -
-<simpleType name="color">
-  <restriction base="string">
-    <enumeration value="red"/>
-    <enumeration value="green"/>
-    <enumeration value="blue"/>
-  </restriction>
-</simpleType>
-  
- -

is mapped to:

- -
-class color: public xml_schema::string
-{
-public:
-  enum value
-  {
-    red,
-    green,
-    blue
-  };
-
-public:
-  color (value);
-  color (const C*);
-  color (const std::basic_string<C>&);
-  color (const xml_schema::string&);
-  color (const color&);
-
-public:
-  color&
-  operator= (value);
-
-  color&
-  operator= (const color&);
-
-public:
-  virtual color*
-  _clone () const;
-
-public:
-  operator value () const;
-};
-  
- -

2.6.3 Mapping for Derivation by List

- -

XML Schema derivation by list is mapped to C++ public - inheritance from xml_schema::simple_type - (Section 2.5.3, "Mapping for - anySimpleType") and a suitable sequence type. - The list item type becomes the element type of the sequence. - In addition to the members described in Section 2.6, - "Mapping for Simple Types", the resulting C++ class defines - a public default constructor, a public constructor - with the first argument of type size_type and - the second argument of list item type that creates - a list object with the specified number of copies of the specified - element value, and a public constructor with the two arguments - of an input iterator type that creates a list object from an - iterator range. For instance: -

- -
-<simpleType name="int_list">
-  <list itemType="int"/>
-</simpleType>
-  
- -

is mapped to:

- -
-class int_list: public simple_type,
-                public sequence<int>
-{
-public:
-  int_list ();
-  int_list (size_type n, int x);
-
-  template <typename I>
-  int_list (const I& begin, const I& end);
-  int_list (const int_list&);
-
-public:
-  int_list&
-  operator= (const int_list&);
-
-public:
-  virtual int_list*
-  _clone () const;
-};
-  
- -

The sequence class template is defined in an - implementation-specific namespace. It conforms to the - sequence interface as defined by the ISO/ANSI Standard for - C++ (ISO/IEC 14882:1998, Section 23.1.1, "Sequences"). - Practically, this means that you can treat such a sequence - as if it was std::vector. One notable extension - to the standard interface that is available only for - sequences of non-fundamental C++ types is the addition of - the overloaded push_back and insert - member functions which instead of the constant reference - to the element type accept automatic pointer (std::auto_ptr - or std::unique_ptr, depending on the C++ standard - selected) to the element type. These functions assume ownership - of the pointed to object and reset the passed automatic pointer. -

- -

2.6.4 Mapping for Derivation by Union

- -

XML Schema derivation by union is mapped to C++ public - inheritance from xml_schema::simple_type - (Section 2.5.3, "Mapping for - anySimpleType") and std::basic_string<C>. - In addition to the members described in Section 2.6, - "Mapping for Simple Types", the resulting C++ class defines a - public constructor with a single argument of type const C* - and a public constructor with a single argument of type - const std::basic_string<C>&. For instance: -

- -
-<simpleType name="int_string_union">
-  <xsd:union memberTypes="xsd:int xsd:string"/>
-</simpleType>
-  
- -

is mapped to:

- -
-class int_string_union: public simple_type,
-                        public std::basic_string<C>
-{
-public:
-  int_string_union (const C*);
-  int_string_union (const std::basic_string<C>&);
-  int_string_union (const int_string_union&);
-
-public:
-  int_string_union&
-  operator= (const int_string_union&);
-
-public:
-  virtual int_string_union*
-  _clone () const;
-};
-  
- -

2.7 Mapping for Complex Types

- -

An XML Schema complex type is mapped to a C++ class with the same - name as the complex type. The class defines a public copy constructor, - a public copy assignment operator, and a public virtual - _clone function. The _clone function is - declared const, does not take any arguments, and returns - a pointer to a complete copy of the instance allocated in the free - store. The _clone function shall be used to make copies - when static type and dynamic type of the instance may differ (see - Section 2.11, "Mapping for xsi:type - and Substitution Groups").

- -

Additionally, the resulting C++ class - defines two public constructors that take an initializer for each - member of the complex type and all its base types that belongs to - the One cardinality class (see Section 2.8, "Mapping - for Local Elements and Attributes"). In the first constructor, - the arguments are passed as constant references and the newly created - instance is initialized with copies of the passed objects. In the - second constructor, arguments that are complex types (that is, - they themselves contain elements or attributes) are passed as - either std::auto_ptr (C++98) or std::unique_ptr - (C++11), depending on the C++ standard selected. In this case the newly - created instance is directly initialized with and assumes ownership - of the pointed to objects and the std::[auto|unique]_ptr - arguments are reset to 0. For instance:

- -
-<complexType name="complex">
-  <sequence>
-    <element name="a" type="int"/>
-    <element name="b" type="string"/>
-  </sequence>
-</complexType>
-
-<complexType name="object">
-  <sequence>
-    <element name="s-one" type="boolean"/>
-    <element name="c-one" type="complex"/>
-    <element name="optional" type="int" minOccurs="0"/>
-    <element name="sequence" type="string" maxOccurs="unbounded"/>
-  </sequence>
-</complexType>
-  
- -

is mapped to:

- -
-class complex: public xml_schema::type
-{
-public:
-  object (const int& a, const xml_schema::string& b);
-  object (const complex&);
-
-public:
-  object&
-  operator= (const complex&);
-
-public:
-  virtual complex*
-  _clone () const;
-
-  ...
-
-};
-
-class object: public xml_schema::type
-{
-public:
-  object (const bool& s_one, const complex& c_one);
-  object (const bool& s_one, std::[auto|unique]_ptr<complex> c_one);
-  object (const object&);
-
-public:
-  object&
-  operator= (const object&);
-
-public:
-  virtual object*
-  _clone () const;
-
-  ...
-
-};
-  
- -

Notice that the generated complex class does not - have the second (std::[auto|unique]_ptr) version of the - constructor since all its required members are of simple types.

- -

If an XML Schema complex type has an ultimate base which is an XML - Schema simple type then the resulting C++ class also defines a public - constructor that takes an initializer for the base type as well as - for each member of the complex type and all its base types that - belongs to the One cardinality class. For instance:

- -
-<complexType name="object">
-  <simpleContent>
-    <extension base="date">
-      <attribute name="lang" type="language" use="required"/>
-    </extension>
-  </simpleContent>
-</complexType>
-  
- -

is mapped to:

- -
-class object: public xml_schema::string
-{
-public:
-  object (const xml_schema::language& lang);
-
-  object (const xml_schema::date& base,
-          const xml_schema::language& lang);
-
-  ...
-
-};
-  
- -

Furthermore, for string-based XML Schema complex types, the resulting C++ - class also defines two public constructors with the first arguments - of type const C* and std::basic_string<C>&, - respectively, followed by arguments for each member of the complex - type and all its base types that belongs to the One cardinality - class. For enumeration-based complex types the resulting C++ - class also defines a public constructor with the first arguments - of the underlying enum type followed by arguments for each member - of the complex type and all its base types that belongs to the One - cardinality class. For instance:

- -
-<simpleType name="color">
-  <restriction base="string">
-    <enumeration value="red"/>
-    <enumeration value="green"/>
-    <enumeration value="blue"/>
-  </restriction>
-</simpleType>
-
-<complexType name="object">
-  <simpleContent>
-    <extension base="color">
-      <attribute name="lang" type="language" use="required"/>
-    </extension>
-  </simpleContent>
-</complexType>
-  
- -

is mapped to:

- -
-class color: public xml_schema::string
-{
-public:
-  enum value
-  {
-    red,
-    green,
-    blue
-  };
-
-public:
-  color (value);
-  color (const C*);
-  color (const std::basic_string<C>&);
-
-  ...
-
-};
-
-class object: color
-{
-public:
-  object (const color& base,
-          const xml_schema::language& lang);
-
-  object (const color::value& base,
-          const xml_schema::language& lang);
-
-  object (const C* base,
-          const xml_schema::language& lang);
-
-  object (const std::basic_string<C>& base,
-          const xml_schema::language& lang);
-
-  ...
-
-};
-  
- -

Additional constructors can be requested with the - --generate-default-ctor and - --generate-from-base-ctor options. See the - XSD - Compiler Command Line Manual for details.

- -

If an XML Schema complex type is not explicitly derived from any type, - the resulting C++ class is derived from xml_schema::type. - In cases where an XML Schema complex type is defined using derivation - by extension or restriction, the resulting C++ base class specification - depends on the type of derivation and is described in the subsequent - sections. -

- -

The mapping for elements and attributes that are defined in a complex - type is described in Section 2.8, "Mapping for Local - Elements and Attributes". -

- -

2.7.1 Mapping for Derivation by Extension

- -

XML Schema derivation by extension is mapped to C++ public - inheritance. The base type of the extension becomes the base - type for the resulting C++ class. -

- -

2.7.2 Mapping for Derivation by Restriction

- -

XML Schema derivation by restriction is mapped to C++ public - inheritance. The base type of the restriction becomes the base - type for the resulting C++ class. XML Schema elements and - attributes defined within restriction do not result in any - definitions in the resulting C++ class. Instead, corresponding - (unrestricted) definitions are inherited from the base class. - In the future versions of this mapping, such elements and - attributes may result in redefinitions of accessors and - modifiers to reflect their restricted semantics. -

- - - -

2.8 Mapping for Local Elements and Attributes

- -

XML Schema element and attribute definitions are called local - if they appear within a complex type definition, an element group - definition, or an attribute group definitions. -

- -

Local XML Schema element and attribute definitions have the same - C++ mapping. Therefore, in this section, local elements and - attributes are collectively called members. -

- -

While there are many different member cardinality combinations - (determined by the use attribute for attributes and - the minOccurs and maxOccurs attributes - for elements), the mapping divides all possible cardinality - combinations into three cardinality classes: -

- -
-
one
-
attributes: use == "required"
-
attributes: use == "optional" and has default or fixed value
-
elements: minOccurs == "1" and maxOccurs == "1"
- -
optional
-
attributes: use == "optional" and doesn't have default or fixed value
-
elements: minOccurs == "0" and maxOccurs == "1"
- -
sequence
-
elements: maxOccurs > "1"
-
- -

An optional attribute with a default or fixed value acquires this value - if the attribute hasn't been specified in an instance document (see - Appendix A, "Default and Fixed Values"). This - mapping places such optional attributes to the One cardinality - class.

- -

A member is mapped to a set of public type definitions - (typedefs) and a set of public accessor and modifier - functions. Type definitions have names derived from the member's - name. The accessor and modifier functions have the same name as the - member. For example: -

- -
-<complexType name="object">
-  <sequence>
-    <element name="member" type="string"/>
-  </sequence>
-</complexType>
-  
- -

is mapped to:

- -
-class object: public xml_schema::type
-{
-public:
-  typedef xml_schema::string member_type;
-
-  const member_type&
-  member () const;
-
-  ...
-
-};
-  
- -

In addition, if a member has a default or fixed value, a static - accessor function is generated that returns this value. For - example:

- -
-<complexType name="object">
-  <attribute name="data" type="string" default="test"/>
-</complexType>
-  
- -

is mapped to:

- -
-class object: public xml_schema::type
-{
-public:
-  typedef xml_schema::string data_type;
-
-  const data_type&
-  data () const;
-
-  static const data_type&
-  data_default_value ();
-
-  ...
-
-};
-  
- -

Names and semantics of type definitions for the member as well - as signatures of the accessor and modifier functions depend on - the member's cardinality class and are described in the following - sub-sections. -

- - -

2.8.1 Mapping for Members with the One Cardinality Class

- -

For the One cardinality class, the type definitions consist of - an alias for the member's type with the name created by appending - the _type suffix to the member's name. -

- -

The accessor functions come in constant and non-constant versions. - The constant accessor function returns a constant reference to the - member and can be used for read-only access. The non-constant - version returns an unrestricted reference to the member and can - be used for read-write access. -

- -

The first modifier function expects an argument of type reference to - constant of the member's type. It makes a deep copy of its argument. - Except for member's types that are mapped to fundamental C++ types, - the second modifier function is provided that expects an argument - of type automatic pointer (std::auto_ptr or - std::unique_ptr, depending on the C++ standard selected) - to the member's type. It assumes ownership of the pointed to object - and resets the passed automatic pointer. For instance:

- -
-<complexType name="object">
-  <sequence>
-    <element name="member" type="string"/>
-  </sequence>
-</complexType>
-  
- -

is mapped to:

- -
-class object: public xml_schema::type
-{
-public:
-  // Type definitions.
-  //
-  typedef xml_schema::string member_type;
-
-  // Accessors.
-  //
-  const member_type&
-  member () const;
-
-  member_type&
-  member ();
-
-  // Modifiers.
-  //
-  void
-  member (const member_type&);
-
-  void
-  member (std::[auto|unique]_ptr<member_type>);
-  ...
-
-};
-  
- -

In addition, if requested by specifying the --generate-detach - option and only for members of non-fundamental C++ types, the mapping - provides a detach function that returns an automatic pointer to the - member's type, for example:

- -
-class object: public xml_schema::type
-{
-public:
-  ...
-
-  std::[auto|unique]_ptr<member_type>
-  detach_member ();
-  ...
-
-};
-  
- -

This function detaches the value from the tree leaving the member - value uninitialized. Accessing such an uninitialized value prior to - re-initializing it results in undefined behavior.

- -

The following code shows how one could use this mapping:

- -
-void
-f (object& o)
-{
-  using xml_schema::string;
-
-  string s (o.member ());                // get
-  object::member_type& sr (o.member ()); // get
-
-  o.member ("hello");           // set, deep copy
-  o.member () = "hello";        // set, deep copy
-
-  // C++98 version.
-  //
-  std::auto_ptr<string> p (new string ("hello"));
-  o.member (p);                 // set, assumes ownership
-  p = o.detach_member ();       // detach, member is uninitialized
-  o.member (p);                 // re-attach
-
-  // C++11 version.
-  //
-  std::unique_ptr<string> p (new string ("hello"));
-  o.member (std::move (p));     // set, assumes ownership
-  p = o.detach_member ();       // detach, member is uninitialized
-  o.member (std::move (p));     // re-attach
-}
-  
- - -

2.8.2 Mapping for Members with the Optional Cardinality Class

- -

For the Optional cardinality class, the type definitions consist of - an alias for the member's type with the name created by appending - the _type suffix to the member's name and an alias for - the container type with the name created by appending the - _optional suffix to the member's name. -

- -

Unlike accessor functions for the One cardinality class, accessor - functions for the Optional cardinality class return references to - corresponding containers rather than directly to members. The - accessor functions come in constant and non-constant versions. - The constant accessor function returns a constant reference to - the container and can be used for read-only access. The non-constant - version returns an unrestricted reference to the container - and can be used for read-write access. -

- -

The modifier functions are overloaded for the member's - type and the container type. The first modifier function - expects an argument of type reference to constant of the - member's type. It makes a deep copy of its argument. - Except for member's types that are mapped to fundamental C++ types, - the second modifier function is provided that expects an argument - of type automatic pointer (std::auto_ptr or - std::unique_ptr, depending on the C++ standard selected) - to the member's type. It assumes ownership of the pointed to object - and resets the passed automatic pointer. The last modifier function - expects an argument of type reference to constant of the container - type. It makes a deep copy of its argument. For instance: -

- -
-<complexType name="object">
-  <sequence>
-    <element name="member" type="string" minOccurs="0"/>
-  </sequence>
-</complexType>
-  
- -

is mapped to:

- -
-class object: public xml_schema::type
-{
-public:
-  // Type definitions.
-  //
-  typedef xml_schema::string member_type;
-  typedef optional<member_type> member_optional;
-
-  // Accessors.
-  //
-  const member_optional&
-  member () const;
-
-  member_optional&
-  member ();
-
-  // Modifiers.
-  //
-  void
-  member (const member_type&);
-
-  void
-  member (std::[auto|unique]_ptr<member_type>);
-
-  void
-  member (const member_optional&);
-
-  ...
-
-};
-  
- - -

The optional class template is defined in an - implementation-specific namespace and has the following - interface. The [auto|unique]_ptr-based constructor - and modifier function are only available if the template - argument is not a fundamental C++ type. -

- -
-template <typename X>
-class optional
-{
-public:
-  optional ();
-
-  // Makes a deep copy.
-  //
-  explicit
-  optional (const X&);
-
-  // Assumes ownership.
-  //
-  explicit
-  optional (std::[auto|unique]_ptr<X>);
-
-  optional (const optional&);
-
-public:
-  optional&
-  operator= (const X&);
-
-  optional&
-  operator= (const optional&);
-
-  // Pointer-like interface.
-  //
-public:
-  const X*
-  operator-> () const;
-
-  X*
-  operator-> ();
-
-  const X&
-  operator* () const;
-
-  X&
-  operator* ();
-
-  typedef void (optional::*bool_convertible) ();
-  operator bool_convertible () const;
-
-  // Get/set interface.
-  //
-public:
-  bool
-  present () const;
-
-  const X&
-  get () const;
-
-  X&
-  get ();
-
-  // Makes a deep copy.
-  //
-  void
-  set (const X&);
-
-  // Assumes ownership.
-  //
-  void
-  set (std::[auto|unique]_ptr<X>);
-
-  // Detach and return the contained value.
-  //
-  std::[auto|unique]_ptr<X>
-  detach ();
-
-  void
-  reset ();
-};
-
-template <typename X>
-bool
-operator== (const optional<X>&, const optional<X>&);
-
-template <typename X>
-bool
-operator!= (const optional<X>&, const optional<X>&);
-
-template <typename X>
-bool
-operator< (const optional<X>&, const optional<X>&);
-
-template <typename X>
-bool
-operator> (const optional<X>&, const optional<X>&);
-
-template <typename X>
-bool
-operator<= (const optional<X>&, const optional<X>&);
-
-template <typename X>
-bool
-operator>= (const optional<X>&, const optional<X>&);
-  
- - -

The following code shows how one could use this mapping:

- -
-void
-f (object& o)
-{
-  using xml_schema::string;
-
-  if (o.member ().present ())       // test
-  {
-    string& s (o.member ().get ()); // get
-    o.member ("hello");             // set, deep copy
-    o.member ().set ("hello");      // set, deep copy
-    o.member ().reset ();           // reset
-  }
-
-  // Same as above but using pointer notation:
-  //
-  if (o.member ())                  // test
-  {
-    string& s (*o.member ());       // get
-    o.member ("hello");             // set, deep copy
-    *o.member () = "hello";         // set, deep copy
-    o.member ().reset ();           // reset
-  }
-
-  // C++98 version.
-  //
-  std::auto_ptr<string> p (new string ("hello"));
-  o.member (p);                     // set, assumes ownership
-
-  p = new string ("hello");
-  o.member ().set (p);              // set, assumes ownership
-
-  p = o.member ().detach ();        // detach, member is reset
-  o.member ().set (p);              // re-attach
-
-  // C++11 version.
-  //
-  std::unique_ptr<string> p (new string ("hello"));
-  o.member (std::move (p));         // set, assumes ownership
-
-  p.reset (new string ("hello"));
-  o.member ().set (std::move (p));  // set, assumes ownership
-
-  p = o.member ().detach ();        // detach, member is reset
-  o.member ().set (std::move (p));  // re-attach
-}
-  
- - -

2.8.3 Mapping for Members with the Sequence Cardinality Class

- -

For the Sequence cardinality class, the type definitions consist of an - alias for the member's type with the name created by appending - the _type suffix to the member's name, an alias of - the container type with the name created by appending the - _sequence suffix to the member's name, an alias of - the iterator type with the name created by appending the - _iterator suffix to the member's name, and an alias - of the constant iterator type with the name created by appending the - _const_iterator suffix to the member's name. -

- -

The accessor functions come in constant and non-constant versions. - The constant accessor function returns a constant reference to the - container and can be used for read-only access. The non-constant - version returns an unrestricted reference to the container and can - be used for read-write access. -

- -

The modifier function expects an argument of type reference to - constant of the container type. The modifier function - makes a deep copy of its argument. For instance: -

- - -
-<complexType name="object">
-  <sequence>
-    <element name="member" type="string" minOccurs="unbounded"/>
-  </sequence>
-</complexType>
-  
- -

is mapped to:

- -
-class object: public xml_schema::type
-{
-public:
-  // Type definitions.
-  //
-  typedef xml_schema::string member_type;
-  typedef sequence<member_type> member_sequence;
-  typedef member_sequence::iterator member_iterator;
-  typedef member_sequence::const_iterator member_const_iterator;
-
-  // Accessors.
-  //
-  const member_sequence&
-  member () const;
-
-  member_sequence&
-  member ();
-
-  // Modifier.
-  //
-  void
-  member (const member_sequence&);
-
-  ...
-
-};
-  
- -

The sequence class template is defined in an - implementation-specific namespace. It conforms to the - sequence interface as defined by the ISO/ANSI Standard for - C++ (ISO/IEC 14882:1998, Section 23.1.1, "Sequences"). - Practically, this means that you can treat such a sequence - as if it was std::vector. Two notable extensions - to the standard interface that are available only for - sequences of non-fundamental C++ types are the addition of - the overloaded push_back and insert - as well as the detach_back and detach - member functions. The additional push_back and - insert functions accept an automatic pointer - (std::auto_ptr or std::unique_ptr, - depending on the C++ standard selected) to the - element type instead of the constant reference. They assume - ownership of the pointed to object and reset the passed - automatic pointer. The detach_back and - detach functions detach the element - value from the sequence container and, by default, remove - the element from the sequence. These additional functions - have the following signatures:

- -
-template <typename X>
-class sequence
-{
-public:
-  ...
-
-  void
-  push_back (std::[auto|unique]_ptr<X>)
-
-  iterator
-  insert (iterator position, std::[auto|unique]_ptr<X>)
-
-  std::[auto|unique]_ptr<X>
-  detach_back (bool pop = true);
-
-  iterator
-  detach (iterator position,
-          std::[auto|unique]_ptr<X>& result,
-          bool erase = true)
-
-  ...
-}
-  
- -

The following code shows how one could use this mapping:

- -
-void
-f (object& o)
-{
-  using xml_schema::string;
-
-  object::member_sequence& s (o.member ());
-
-  // Iteration.
-  //
-  for (object::member_iterator i (s.begin ()); i != s.end (); ++i)
-  {
-    string& value (*i);
-  }
-
-  // Modification.
-  //
-  s.push_back ("hello");  // deep copy
-
-  // C++98 version.
-  //
-  std::auto_ptr<string> p (new string ("hello"));
-  s.push_back (p);        // assumes ownership
-  p = s.detach_back ();   // detach and pop
-  s.push_back (p);        // re-append
-
-  // C++11 version.
-  //
-  std::unique_ptr<string> p (new string ("hello"));
-  s.push_back (std::move (p)); // assumes ownership
-  p = s.detach_back ();        // detach and pop
-  s.push_back (std::move (p)); // re-append
-
-  // Setting a new container.
-  //
-  object::member_sequence n;
-  n.push_back ("one");
-  n.push_back ("two");
-  o.member (n);           // deep copy
-}
-  
- -

2.8.4 Element Order

- -

C++/Tree is a "flattening" mapping in a sense that many levels of - nested compositors (choice and sequence), - all potentially with their own cardinalities, are in the end mapped - to a flat set of elements with one of the three cardinality classes - discussed in the previous sections. While this results in a simple - and easy to use API for most types, in certain cases, the order of - elements in the actual XML documents is not preserved once parsed - into the object model. And sometimes such order has - application-specific significance. As an example, consider a schema - that defines a batch of bank transactions:

- -
-<complexType name="withdraw">
-  <sequence>
-    <element name="account" type="unsignedInt"/>
-    <element name="amount" type="unsignedInt"/>
-  </sequence>
-</complexType>
-
-<complexType name="deposit">
-  <sequence>
-    <element name="account" type="unsignedInt"/>
-    <element name="amount" type="unsignedInt"/>
-  </sequence>
-</complexType>
-
-<complexType name="batch">
-  <choice minOccurs="0" maxOccurs="unbounded">
-    <element name="withdraw" type="withdraw"/>
-    <element name="deposit" type="deposit"/>
-  </choice>
-</complexType>
-  
- -

The batch can contain any number of transactions in any order - but the order of transactions in each actual batch is significant. - For instance, consider what could happen if we reorder the - transactions and apply all the withdrawals before deposits.

- -

For the batch schema type defined above the default - C++/Tree mapping will produce a C++ class that contains a pair of - sequence containers, one for each of the two elements. While this - will capture the content (transactions), the order of this content - as it appears in XML will be lost. Also, if we try to serialize the - batch we just loaded back to XML, all the withdrawal transactions - will appear before deposits.

- -

To overcome this limitation of a flattening mapping, C++/Tree - allows us to mark certain XML Schema types, for which content - order is important, as ordered.

- -

There are several command line options that control which - schema types are treated as ordered. To make an individual - type ordered, we use the --ordered-type option, - for example:

- -
---ordered-type batch
-  
- -

To automatically treat all the types that are derived from an ordered - type also ordered, we use the --ordered-type-derived - option. This is primarily useful if you would like to iterate - over the complete hierarchy's content using the content order - sequence (discussed below).

- -

Ordered types are also useful for handling mixed content. To - automatically mark all the types with mixed content as ordered - we use the --ordered-type-mixed option. For more - information on handling mixed content see Section - 2.13, "Mapping for Mixed Content Models".

- -

Finally, we can mark all the types in the schema we are - compiling with the --ordered-type-all option. - You should only resort to this option if all the types in - your schema truly suffer from the loss of content - order since, as we will discuss shortly, ordered types - require extra effort to access and, especially, modify. - See the - XSD - Compiler Command Line Manual for more information on - these options.

- -

Once a type is marked ordered, C++/Tree alters its mapping - in several ways. Firstly, for each local element, element - wildcard (Section 2.12.4, "Element Wildcard - Order"), and mixed content text (Section - 2.13, "Mapping for Mixed Content Models") in this type, a - content id constant is generated. Secondly, an addition sequence - is added to the class that captures the content order. Here - is how the mapping of our batch class changes - once we make it ordered:

- -
-class batch: public xml_schema::type
-{
-public:
-  // withdraw
-  //
-  typedef withdraw withdraw_type;
-  typedef sequence<withdraw_type> withdraw_sequence;
-  typedef withdraw_sequence::iterator withdraw_iterator;
-  typedef withdraw_sequence::const_iterator withdraw_const_iterator;
-
-  static const std::size_t withdraw_id = 1;
-
-  const withdraw_sequence&
-  withdraw () const;
-
-  withdraw_sequence&
-  withdraw ();
-
-  void
-  withdraw (const withdraw_sequence&);
-
-  // deposit
-  //
-  typedef deposit deposit_type;
-  typedef sequence<deposit_type> deposit_sequence;
-  typedef deposit_sequence::iterator deposit_iterator;
-  typedef deposit_sequence::const_iterator deposit_const_iterator;
-
-  static const std::size_t deposit_id = 2;
-
-  const deposit_sequence&
-  deposit () const;
-
-  deposit_sequence&
-  deposit ();
-
-  void
-  deposit (const deposit_sequence&);
-
-  // content_order
-  //
-  typedef xml_schema::content_order content_order_type;
-  typedef std::vector<content_order_type> content_order_sequence;
-  typedef content_order_sequence::iterator content_order_iterator;
-  typedef content_order_sequence::const_iterator content_order_const_iterator;
-
-  const content_order_sequence&
-  content_order () const;
-
-  content_order_sequence&
-  content_order ();
-
-  void
-  content_order (const content_order_sequence&);
-
-  ...
-};
-  
- -

Notice the withdraw_id and deposit_id - content ids as well as the extra content_order - sequence that does not correspond to any element in the - schema definition. The other changes to the mapping for ordered - types has to do with XML parsing and serialization code. During - parsing the content order is captured in the content_order - sequence while during serialization this sequence is used to - determine the order in which content is serialized. The - content_order sequence is also copied during - copy construction and assigned during copy assignment. It is also - taken into account during comparison.

- -

The entry type of the content_order sequence is the - xml_schema::content_order type that has the following - interface:

- -
-namespace xml_schema
-{
-  struct content_order
-  {
-    content_order (std::size_t id, std::size_t index = 0);
-
-    std::size_t id;
-    std::size_t index;
-  };
-
-  bool
-  operator== (const content_order&, const content_order&);
-
-  bool
-  operator!= (const content_order&, const content_order&);
-
-  bool
-  operator< (const content_order&, const content_order&);
-}
-  
- -

The content_order sequence describes the order of - content (elements, including wildcards, as well as mixed content - text). Each entry in this sequence consists of the content id - (for example, withdraw_id or deposit_id - in our case) as well as, for elements of the sequence cardinality - class, an index into the corresponding sequence container (the - index is unused for the one and optional cardinality classes). - For example, in our case, if the content id is withdraw_id, - then the index will point into the withdraw element - sequence.

- -

With all this information we can now examine how to iterate over - transaction in the batch in content order:

- -
-batch& b = ...
-
-for (batch::content_order_const_iterator i (b.content_order ().begin ());
-     i != b.content_order ().end ();
-     ++i)
-{
-  switch (i->id)
-  {
-  case batch::withdraw_id:
-    {
-      const withdraw& t (b.withdraw ()[i->index]);
-      cerr << t.account () << " withdraw " << t.amount () << endl;
-      break;
-    }
-  case batch::deposit_id:
-    {
-      const deposit& t (b.deposit ()[i->index]);
-      cerr << t.account () << " deposit " << t.amount () << endl;
-      break;
-    }
-  default:
-    {
-      assert (false); // Unknown content id.
-    }
-  }
-}
-  
- -

If we serialized our batch back to XML, we would also see that the - order of transactions in the output is exactly the same as in the - input rather than all the withdrawals first followed by all the - deposits.

- -

The most complex aspect of working with ordered types is - modifications. Now we not only need to change the content, - but also remember to update the order information corresponding - to this change. As a first example, we add a deposit transaction - to the batch:

- -
-using xml_schema::content_order;
-
-batch::deposit_sequence& d (b.deposit ());
-batch::withdraw_sequence& w (b.withdraw ());
-batch::content_order_sequence& co (b.content_order ());
-
-d.push_back (deposit (123456789, 100000));
-co.push_back (content_order (batch::deposit_id, d.size () - 1));
-  
- -

In the above example we first added the content (deposit - transaction) and then updated the content order information - by adding an entry with deposit_id content - id and the index of the just added deposit transaction.

- -

Removing the last transaction can be easy if we know which - transaction (deposit or withdrawal) is last:

- -
-d.pop_back ();
-co.pop_back ();
-  
- -

If, however, we do not know which transaction is last, then - things get a bit more complicated:

- -
-switch (co.back ().id)
-{
-case batch::withdraw_id:
-  {
-    d.pop_back ();
-    break;
-  }
-case batch::deposit_id:
-  {
-    w.pop_back ();
-    break;
-  }
-}
-
-co.pop_back ();
-  
- -

The following example shows how to add a transaction at the - beginning of the batch:

- -
-w.push_back (withdraw (123456789, 100000));
-co.insert (co.begin (),
-           content_order (batch::withdraw_id, w.size () - 1));
-  
- -

Note also that when we merely modify the content of one - of the elements in place, we do not need to update its - order since it doesn't change. For example, here is how - we can change the amount in the first withdrawal:

- -
-w[0].amount (10000);
-  
- -

For the complete working code shown in this section refer to the - order/element example in the - examples/cxx/tree/ directory in the XSD distribution.

- -

If both the base and derived types are ordered, then the - content order sequence is only added to the base and the content - ids are unique within the whole hierarchy. In this case - the content order sequence for the derived type contains - ordering information for both base and derived content.

- -

In some applications we may need to perform more complex - content processing. For example, in our case, we may need - to remove all the withdrawal transactions. The default - container, std::vector, is not particularly - suitable for such operations. What may be required by - some applications is a multi-index container that not - only allows us to iterate in content order similar to - std::vector but also search by the content - id as well as the content id and index pair.

- -

While C++/Tree does not provide this functionality by - default, it allows us to specify a custom container - type for content order with the --order-container - command line option. The only requirement from the - generated code side for such a container is to provide - the vector-like push_back(), - size(), and const iteration interfaces.

- -

As an example, here is how we can use the Boost Multi-Index - container for content order. First we create the - content-order-container.hxx header with the - following definition (in C++11, use the alias template - instead):

- -
-#ifndef CONTENT_ORDER_CONTAINER
-#define CONTENT_ORDER_CONTAINER
-
-#include <cstddef> // std::size_t
-
-#include <boost/multi_index_container.hpp>
-#include <boost/multi_index/member.hpp>
-#include <boost/multi_index/identity.hpp>
-#include <boost/multi_index/ordered_index.hpp>
-#include <boost/multi_index/random_access_index.hpp>
-
-struct by_id {};
-struct by_id_index {};
-
-template <typename T>
-struct content_order_container:
-  boost::multi_index::multi_index_container<
-    T,
-    boost::multi_index::indexed_by<
-      boost::multi_index::random_access<>,
-      boost::multi_index::ordered_unique<
-        boost::multi_index::tag<by_id_index>,
-        boost::multi_index::identity<T>
-      >,
-      boost::multi_index::ordered_non_unique<
-        boost::multi_index::tag<by_id>,
-        boost::multi_index::member<T, std::size_t, &T::id>
-      >
-    >
-  >
-{};
-
-#endif
-  
- -

Next we add the following two XSD compiler options to include - this header into every generated header file and to use the - custom container type (see the XSD compiler command line manual - for more information on shell quoting for the first option):

- -
---hxx-prologue '#include "content-order-container.hxx"'
---order-container content_order_container
-  
- -

With these changes we can now use the multi-index functionality, - for example, to search for a specific content id:

- -
-typedef batch::content_order_sequence::index<by_id>::type id_set;
-typedef id_set::iterator id_iterator;
-
-const id_set& ids (b.content_order ().get<by_id> ());
-
-std::pair<id_iterator, id_iterator> r (
-  ids.equal_range (std::size_t (batch::deposit_id));
-
-for (id_iterator i (r.first); i != r.second; ++i)
-{
-  const deposit& t (b.deposit ()[i->index]);
-  cerr << t.account () << " deposit " << t.amount () << endl;
-}
-  
- -

2.9 Mapping for Global Elements

- -

An XML Schema element definition is called global if it appears - directly under the schema element. - A global element is a valid root of an instance document. By - default, a global element is mapped to a set of overloaded - parsing and, optionally, serialization functions with the - same name as the element. It is also possible to generate types - for root elements instead of parsing and serialization functions. - This is primarily useful to distinguish object models with the - same root type but with different root elements. See - Section 2.9.1, "Element Types" for details. - It is also possible to request the generation of an element map - which allows uniform parsing and serialization of multiple root - elements. See Section 2.9.2, "Element Map" - for details. -

- -

The parsing functions read XML instance documents and return - corresponding object models as an automatic pointer - (std::auto_ptr or std::unique_ptr, - depending on the C++ standard selected). Their signatures - have the following pattern (type denotes - element's type and name denotes element's - name): -

- -
-std::[auto|unique]_ptr<type>
-name (....);
-  
- -

The process of parsing, including the exact signatures of the parsing - functions, is the subject of Chapter 3, "Parsing". -

- -

The serialization functions write object models back to XML instance - documents. Their signatures have the following pattern: -

- -
-void
-name (<stream type>&, const type&, ....);
-  
- -

The process of serialization, including the exact signatures of the - serialization functions, is the subject of Chapter 4, - "Serialization". -

- - -

2.9.1 Element Types

- -

The generation of element types is requested with the - --generate-element-type option. With this option - each global element is mapped to a C++ class with the - same name as the element. Such a class is derived from - xml_schema::element_type and contains the same set - of type definitions, constructors, and member function as would a - type containing a single element with the One cardinality class - named "value". In addition, the element type also - contains a set of member functions for accessing the element - name and namespace as well as its value in a uniform manner. - For example:

- -
-<complexType name="type">
-  <sequence>
-    ...
-  </sequence>
-</complexType>
-
-<element name="root" type="type"/>
-  
- -

is mapped to:

- -
-class type
-{
-  ...
-};
-
-class root: public xml_schema::element_type
-{
-public:
-  // Element value.
-  //
-  typedef type value_type;
-
-  const value_type&
-  value () const;
-
-  value_type&
-  value ();
-
-  void
-  value (const value_type&);
-
-  void
-  value (std::[auto|unique]_ptr<value_type>);
-
-  // Constructors.
-  //
-  root (const value_type&);
-
-  root (std::[auto|unique]_ptr<value_type>);
-
-  root (const xercesc::DOMElement&, xml_schema::flags = 0);
-
-  root (const root&, xml_schema::flags = 0);
-
-  virtual root*
-  _clone (xml_schema::flags = 0) const;
-
-  // Element name and namespace.
-  //
-  static const std::string&
-  name ();
-
-  static const std::string&
-  namespace_ ();
-
-  virtual const std::string&
-  _name () const;
-
-  virtual const std::string&
-  _namespace () const;
-
-  // Element value as xml_schema::type.
-  //
-  virtual const xml_schema::type*
-  _value () const;
-
-  virtual xml_schema::type*
-  _value ();
-};
-
-void
-operator<< (xercesc::DOMElement&, const root&);
-  
- -

The xml_schema::element_type class is a common - base type for all element types and is defined as follows:

- -
-namespace xml_schema
-{
-  class element_type
-  {
-  public:
-    virtual
-    ~element_type ();
-
-    virtual element_type*
-    _clone (flags f = 0) const = 0;
-
-    virtual const std::basic_string<C>&
-    _name () const = 0;
-
-    virtual const std::basic_string<C>&
-    _namespace () const = 0;
-
-    virtual xml_schema::type*
-    _value () = 0;
-
-    virtual const xml_schema::type*
-    _value () const = 0;
-  };
-}
-  
- -

The _value() member function returns a pointer to - the element value or 0 if the element is of a fundamental C++ - type and therefore is not derived from xml_schema::type. -

- -

Unlike parsing and serialization functions, element types - are only capable of parsing and serializing from/to a - DOMElement object. This means that the application - will need to perform its own XML-to-DOM parsing and DOM-to-XML - serialization. The following section describes a mechanism - provided by the mapping to uniformly parse and serialize - multiple root elements.

- - -

2.9.2 Element Map

- -

When element types are generated for root elements it is also - possible to request the generation of an element map with the - --generate-element-map option. The element map - allows uniform parsing and serialization of multiple root - elements via the common xml_schema::element_type - base type. The xml_schema::element_map class is - defined as follows:

- -
-namespace xml_schema
-{
-  class element_map
-  {
-  public:
-    static std::[auto|unique]_ptr<xml_schema::element_type>
-    parse (const xercesc::DOMElement&, flags = 0);
-
-    static void
-    serialize (xercesc::DOMElement&, const element_type&);
-  };
-}
-  
- -

The parse() function creates the corresponding - element type object based on the element name and namespace - and returns it as an automatic pointer (std::auto_ptr - or std::unique_ptr, depending on the C++ standard - selected) to xml_schema::element_type. - The serialize() function serializes the passed element - object to DOMElement. Note that in case of - serialize(), the DOMElement object - should have the correct name and namespace. If no element type is - available for an element, both functions throw the - xml_schema::no_element_info exception:

- -
-struct no_element_info: virtual exception
-{
-  no_element_info (const std::basic_string<C>& element_name,
-                   const std::basic_string<C>& element_namespace);
-
-  const std::basic_string<C>&
-  element_name () const;
-
-  const std::basic_string<C>&
-  element_namespace () const;
-
-  virtual const char*
-  what () const throw ();
-};
-  
- -

The application can discover the actual type of the element - object returned by parse() either using - dynamic_cast or by comparing element names and - namespaces. The following code fragments illustrate how the - element map can be used:

- -
-// Parsing.
-//
-DOMElement& e = ... // Parse XML to DOM.
-
-auto_ptr<xml_schema::element_type> r (
-  xml_schema::element_map::parse (e));
-
-if (root1 r1 = dynamic_cast<root1*> (r.get ()))
-{
-  ...
-}
-else if (r->_name == root2::name () &&
-         r->_namespace () == root2::namespace_ ())
-{
-  root2& r2 (static_cast<root2&> (*r));
-
-  ...
-}
-  
- -
-// Serialization.
-//
-xml_schema::element_type& r = ...
-
-string name (r._name ());
-string ns (r._namespace ());
-
-DOMDocument& doc = ... // Create a new DOMDocument with name and ns.
-DOMElement& e (*doc->getDocumentElement ());
-
-xml_schema::element_map::serialize (e, r);
-
-// Serialize DOMDocument to XML.
-  
- - - -

2.10 Mapping for Global Attributes

- -

An XML Schema attribute definition is called global if it appears - directly under the schema element. A global - attribute does not have any mapping. -

- - - -

2.11 Mapping for xsi:type and Substitution - Groups

- -

The mapping provides optional support for the XML Schema polymorphism - features (xsi:type and substitution groups) which can - be requested with the --generate-polymorphic option. - When used, the dynamic type of a member may be different from - its static type. Consider the following schema definition and - instance document: -

- -
-<!-- test.xsd -->
-<schema>
-  <complexType name="base">
-    <attribute name="text" type="string"/>
-  </complexType>
-
-  <complexType name="derived">
-    <complexContent>
-      <extension base="base">
-        <attribute name="extra-text" type="string"/>
-      </extension>
-    </complexContent>
-  </complexType>
-
-  <complexType name="root_type">
-    <sequence>
-      <element name="item" type="base" maxOccurs="unbounded"/>
-    </sequence>
-  </complexType>
-
-  <element name="root" type="root_type"/>
-</schema>
-
-<!-- test.xml -->
-<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
-  <item text="hello"/>
-  <item text="hello" extra-text="world" xsi:type="derived"/>
-</root>
-  
- -

In the resulting object model, the container for - the root::item member will have two elements: - the first element's type will be base while - the second element's (dynamic) type will be - derived. This can be discovered using the - dynamic_cast operator as shown in the following - example: -

- -
-void
-f (root& r)
-{
-  for (root::item_const_iterator i (r.item ().begin ());
-       i != r.item ().end ()
-       ++i)
-  {
-    if (derived* d = dynamic_cast<derived*> (&(*i)))
-    {
-      // derived
-    }
-    else
-    {
-      // base
-    }
-  }
-}
-  
- -

The _clone virtual function should be used instead of - copy constructors to make copies of members that might use - polymorphism: -

- -
-void
-f (root& r)
-{
-  for (root::item_const_iterator i (r.item ().begin ());
-       i != r.item ().end ()
-       ++i)
-  {
-    std::auto_ptr<base> c (i->_clone ());
-  }
-}
-  
- -

The mapping can often automatically determine which types are - polymorphic based on the substitution group declarations. However, - if your XML vocabulary is not using substitution groups or if - substitution groups are defined in a separate schema, then you will - need to use the --polymorphic-type option to specify - which types are polymorphic. When using this option you only need - to specify the root of a polymorphic type hierarchy and the mapping - will assume that all the derived types are also polymorphic. - Also note that you need to specify this option when compiling every - schema file that references the polymorphic type. Consider the following - two schemas as an example:

- -
-<!-- base.xsd -->
-<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
-
-  <xs:complexType name="base">
-    <xs:sequence>
-      <xs:element name="b" type="xs:int"/>
-    </xs:sequence>
-  </xs:complexType>
-
-  <!-- substitution group root -->
-  <xs:element name="base" type="base"/>
-
-</xs:schema>
-  
- -
-<!-- derived.xsd -->
-<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
-
-  <include schemaLocation="base.xsd"/>
-
-  <xs:complexType name="derived">
-    <xs:complexContent>
-      <xs:extension base="base">
-        <xs:sequence>
-          <xs:element name="d" type="xs:string"/>
-        </xs:sequence>
-      </xs:extension>
-    </xs:complexContent>
-  </xs:complexType>
-
-  <xs:element name="derived" type="derived" substitutionGroup="base"/>
-
-</xs:schema>
-  
- -

In this example we need to specify "--polymorphic-type base" - when compiling both schemas because the substitution group is declared - in a schema other than the one defining type base.

- -

You can also indicate that all types should be treated as polymorphic - with the --polymorphic-type-all. However, this may result - in slower generated code with a greater footprint.

- - - - - -

2.12 Mapping for any and anyAttribute

- -

For the XML Schema any and anyAttribute - wildcards an optional mapping can be requested with the - --generate-wildcard option. The mapping represents - the content matched by wildcards as DOM fragments. Because the - DOM API is used to access such content, the Xerces-C++ runtime - should be initialized by the application prior to parsing and - should remain initialized for the lifetime of objects with - the wildcard content. For more information on the Xerces-C++ - runtime initialization see Section 3.1, - "Initializing the Xerces-C++ Runtime". -

- -

The mapping for any is similar to the mapping for - local elements (see Section 2.8, "Mapping for Local - Elements and Attributes") except that the type used in the - wildcard mapping is xercesc::DOMElement. As with local - elements, the mapping divides all possible cardinality combinations - into three cardinality classes: one, optional, and - sequence. -

- -

The mapping for anyAttribute represents the attributes - matched by this wildcard as a set of xercesc::DOMAttr - objects with a key being the attribute's name and namespace.

- -

Similar to local elements and attributes, the any and - anyAttribute wildcards are mapped to a set of public type - definitions (typedefs) and a set of public accessor and modifier - functions. Type definitions have names derived from "any" - for the any wildcard and "any_attribute" - for the anyAttribute wildcard. The accessor and modifier - functions are named "any" for the any wildcard - and "any_attribute" for the anyAttribute - wildcard. Subsequent wildcards in the same type have escaped names - such as "any1" or "any_attribute1". -

- -

Because Xerces-C++ DOM nodes always belong to a DOMDocument, - each type with a wildcard has an associated DOMDocument - object. The reference to this object can be obtained using the accessor - function called dom_document. The access to the document - object from the application code may be necessary to create or modify - the wildcard content. For example: -

- -
-<complexType name="object">
-  <sequence>
-    <any namespace="##other"/>
-  </sequence>
-  <anyAttribute namespace="##other"/>
-</complexType>
-  
- -

is mapped to:

- -
-class object: public xml_schema::type
-{
-public:
-  // any
-  //
-  const xercesc::DOMElement&
-  any () const;
-
-  void
-  any (const xercesc::DOMElement&);
-
-  ...
-
-  // any_attribute
-  //
-  typedef attribute_set any_attribute_set;
-  typedef any_attribute_set::iterator any_attribute_iterator;
-  typedef any_attribute_set::const_iterator any_attribute_const_iterator;
-
-  const any_attribute_set&
-  any_attribute () const;
-
-  any_attribute_set&
-  any_attribute ();
-
-  ...
-
-  // DOMDocument object for wildcard content.
-  //
-  const xercesc::DOMDocument&
-  dom_document () const;
-
-  xercesc::DOMDocument&
-  dom_document ();
-
-  ...
-};
-  
- - -

Names and semantics of type definitions for the wildcards as well - as signatures of the accessor and modifier functions depend on the - wildcard type as well as the cardinality class for the any - wildcard. They are described in the following sub-sections. -

- - -

2.12.1 Mapping for any with the One Cardinality Class

- -

For any with the One cardinality class, - there are no type definitions. The accessor functions come in - constant and non-constant versions. The constant accessor function - returns a constant reference to xercesc::DOMElement and - can be used for read-only access. The non-constant version returns - an unrestricted reference to xercesc::DOMElement and can - be used for read-write access. -

- -

The first modifier function expects an argument of type reference - to constant xercesc::DOMElement and makes a deep copy - of its argument. The second modifier function expects an argument of - type pointer to xercesc::DOMElement. This modifier - function assumes ownership of its argument and expects the element - object to be created using the DOM document associated with this - instance. For example: -

- -
-<complexType name="object">
-  <sequence>
-    <any namespace="##other"/>
-  </sequence>
-</complexType>
-  
- -

is mapped to:

- -
-class object: public xml_schema::type
-{
-public:
-  // Accessors.
-  //
-  const xercesc::DOMElement&
-  any () const;
-
-  xercesc::DOMElement&
-  any ();
-
-  // Modifiers.
-  //
-  void
-  any (const xercesc::DOMElement&);
-
-  void
-  any (xercesc::DOMElement*);
-
-  ...
-
-};
-  
- - -

The following code shows how one could use this mapping:

- -
-void
-f (object& o, const xercesc::DOMElement& e)
-{
-  using namespace xercesc;
-
-  DOMElement& e1 (o.any ());             // get
-  o.any (e)                              // set, deep copy
-  DOMDocument& doc (o.dom_document ());
-  o.any (doc.createElement (...));       // set, assumes ownership
-}
-  
- -

2.12.2 Mapping for any with the Optional Cardinality Class

- -

For any with the Optional cardinality class, the type - definitions consist of an alias for the container type with name - any_optional (or any1_optional, etc., for - subsequent wildcards in the type definition). -

- -

Unlike accessor functions for the One cardinality class, accessor - functions for the Optional cardinality class return references to - corresponding containers rather than directly to DOMElement. - The accessor functions come in constant and non-constant versions. - The constant accessor function returns a constant reference to - the container and can be used for read-only access. The non-constant - version returns an unrestricted reference to the container - and can be used for read-write access. -

- -

The modifier functions are overloaded for xercesc::DOMElement - and the container type. The first modifier function expects an argument of - type reference to constant xercesc::DOMElement and - makes a deep copy of its argument. The second modifier function - expects an argument of type pointer to xercesc::DOMElement. - This modifier function assumes ownership of its argument and expects - the element object to be created using the DOM document associated - with this instance. The third modifier function expects an argument - of type reference to constant of the container type and makes a - deep copy of its argument. For instance: -

- -
-<complexType name="object">
-  <sequence>
-    <any namespace="##other" minOccurs="0"/>
-  </sequence>
-</complexType>
-  
- -

is mapped to:

- -
-class object: public xml_schema::type
-{
-public:
-  // Type definitions.
-  //
-  typedef element_optional any_optional;
-
-  // Accessors.
-  //
-  const any_optional&
-  any () const;
-
-  any_optional&
-  any ();
-
-  // Modifiers.
-  //
-  void
-  any (const xercesc::DOMElement&);
-
-  void
-  any (xercesc::DOMElement*);
-
-  void
-  any (const any_optional&);
-
-  ...
-
-};
-  
- - -

The element_optional container is a - specialization of the optional class template described - in Section 2.8.2, "Mapping for Members with the Optional - Cardinality Class". Its interface is presented below: -

- -
-class element_optional
-{
-public:
-  explicit
-  element_optional (xercesc::DOMDocument&);
-
-  // Makes a deep copy.
-  //
-  element_optional (const xercesc::DOMElement&, xercesc::DOMDocument&);
-
-  // Assumes ownership.
-  //
-  element_optional (xercesc::DOMElement*, xercesc::DOMDocument&);
-
-  element_optional (const element_optional&, xercesc::DOMDocument&);
-
-public:
-  element_optional&
-  operator= (const xercesc::DOMElement&);
-
-  element_optional&
-  operator= (const element_optional&);
-
-  // Pointer-like interface.
-  //
-public:
-  const xercesc::DOMElement*
-  operator-> () const;
-
-  xercesc::DOMElement*
-  operator-> ();
-
-  const xercesc::DOMElement&
-  operator* () const;
-
-  xercesc::DOMElement&
-  operator* ();
-
-  typedef void (element_optional::*bool_convertible) ();
-  operator bool_convertible () const;
-
-  // Get/set interface.
-  //
-public:
-  bool
-  present () const;
-
-  const xercesc::DOMElement&
-  get () const;
-
-  xercesc::DOMElement&
-  get ();
-
-  // Makes a deep copy.
-  //
-  void
-  set (const xercesc::DOMElement&);
-
-  // Assumes ownership.
-  //
-  void
-  set (xercesc::DOMElement*);
-
-  void
-  reset ();
-};
-
-bool
-operator== (const element_optional&, const element_optional&);
-
-bool
-operator!= (const element_optional&, const element_optional&);
-  
- - -

The following code shows how one could use this mapping:

- -
-void
-f (object& o, const xercesc::DOMElement& e)
-{
-  using namespace xercesc;
-
-  DOMDocument& doc (o.dom_document ());
-
-  if (o.any ().present ())                  // test
-  {
-    DOMElement& e1 (o.any ().get ());       // get
-    o.any ().set (e);                       // set, deep copy
-    o.any ().set (doc.createElement (...)); // set, assumes ownership
-    o.any ().reset ();                      // reset
-  }
-
-  // Same as above but using pointer notation:
-  //
-  if (o.member ())                          // test
-  {
-    DOMElement& e1 (*o.any ());             // get
-    o.any (e);                              // set, deep copy
-    o.any (doc.createElement (...));        // set, assumes ownership
-    o.any ().reset ();                      // reset
-  }
-}
-  
- - - -

2.12.3 Mapping for any with the Sequence Cardinality Class

- -

For any with the Sequence cardinality class, the type - definitions consist of an alias of the container type with name - any_sequence (or any1_sequence, etc., for - subsequent wildcards in the type definition), an alias of the iterator - type with name any_iterator (or any1_iterator, - etc., for subsequent wildcards in the type definition), and an alias - of the constant iterator type with name any_const_iterator - (or any1_const_iterator, etc., for subsequent wildcards - in the type definition). -

- -

The accessor functions come in constant and non-constant versions. - The constant accessor function returns a constant reference to the - container and can be used for read-only access. The non-constant - version returns an unrestricted reference to the container and can - be used for read-write access. -

- -

The modifier function expects an argument of type reference to - constant of the container type. The modifier function makes - a deep copy of its argument. For instance: -

- - -
-<complexType name="object">
-  <sequence>
-    <any namespace="##other" minOccurs="unbounded"/>
-  </sequence>
-</complexType>
-  
- -

is mapped to:

- -
-class object: public xml_schema::type
-{
-public:
-  // Type definitions.
-  //
-  typedef element_sequence any_sequence;
-  typedef any_sequence::iterator any_iterator;
-  typedef any_sequence::const_iterator any_const_iterator;
-
-  // Accessors.
-  //
-  const any_sequence&
-  any () const;
-
-  any_sequence&
-  any ();
-
-  // Modifier.
-  //
-  void
-  any (const any_sequence&);
-
-  ...
-
-};
-  
- -

The element_sequence container is a - specialization of the sequence class template described - in Section 2.8.3, "Mapping for Members with the - Sequence Cardinality Class". Its interface is similar to - the sequence interface as defined by the ISO/ANSI Standard for - C++ (ISO/IEC 14882:1998, Section 23.1.1, "Sequences") and is - presented below: -

- -
-class element_sequence
-{
-public:
-  typedef xercesc::DOMElement        value_type;
-  typedef xercesc::DOMElement*       pointer;
-  typedef const xercesc::DOMElement* const_pointer;
-  typedef xercesc::DOMElement&       reference;
-  typedef const xercesc::DOMElement& const_reference;
-
-  typedef <implementation-defined>   iterator;
-  typedef <implementation-defined>   const_iterator;
-  typedef <implementation-defined>   reverse_iterator;
-  typedef <implementation-defined>   const_reverse_iterator;
-
-  typedef <implementation-defined>   size_type;
-  typedef <implementation-defined>   difference_type;
-  typedef <implementation-defined>   allocator_type;
-
-public:
-  explicit
-  element_sequence (xercesc::DOMDocument&);
-
-  // DOMElement cannot be default-constructed.
-  //
-  // explicit
-  // element_sequence (size_type n);
-
-  element_sequence (size_type n,
-                    const xercesc::DOMElement&,
-                    xercesc::DOMDocument&);
-
-  template <typename I>
-  element_sequence (const I& begin,
-                    const I& end,
-                    xercesc::DOMDocument&);
-
-  element_sequence (const element_sequence&, xercesc::DOMDocument&);
-
-  element_sequence&
-  operator= (const element_sequence&);
-
-public:
-  void
-  assign (size_type n, const xercesc::DOMElement&);
-
-  template <typename I>
-  void
-  assign (const I& begin, const I& end);
-
-public:
-  // This version of resize can only be used to shrink the
-  // sequence because DOMElement cannot be default-constructed.
-  //
-  void
-  resize (size_type);
-
-  void
-  resize (size_type, const xercesc::DOMElement&);
-
-public:
-  size_type
-  size () const;
-
-  size_type
-  max_size () const;
-
-  size_type
-  capacity () const;
-
-  bool
-  empty () const;
-
-  void
-  reserve (size_type);
-
-  void
-  clear ();
-
-public:
-  const_iterator
-  begin () const;
-
-  const_iterator
-  end () const;
-
-  iterator
-  begin ();
-
-  iterator
-  end ();
-
-  const_reverse_iterator
-  rbegin () const;
-
-  const_reverse_iterator
-  rend () const
-
-    reverse_iterator
-  rbegin ();
-
-  reverse_iterator
-  rend ();
-
-public:
-  xercesc::DOMElement&
-  operator[] (size_type);
-
-  const xercesc::DOMElement&
-  operator[] (size_type) const;
-
-  xercesc::DOMElement&
-  at (size_type);
-
-  const xercesc::DOMElement&
-  at (size_type) const;
-
-  xercesc::DOMElement&
-  front ();
-
-  const xercesc::DOMElement&
-  front () const;
-
-  xercesc::DOMElement&
-  back ();
-
-  const xercesc::DOMElement&
-  back () const;
-
-public:
-  // Makes a deep copy.
-  //
-  void
-  push_back (const xercesc::DOMElement&);
-
-  // Assumes ownership.
-  //
-  void
-  push_back (xercesc::DOMElement*);
-
-  void
-  pop_back ();
-
-  // Makes a deep copy.
-  //
-  iterator
-  insert (iterator position, const xercesc::DOMElement&);
-
-  // Assumes ownership.
-  //
-  iterator
-  insert (iterator position, xercesc::DOMElement*);
-
-  void
-  insert (iterator position, size_type n, const xercesc::DOMElement&);
-
-  template <typename I>
-  void
-  insert (iterator position, const I& begin, const I& end);
-
-  iterator
-  erase (iterator position);
-
-  iterator
-  erase (iterator begin, iterator end);
-
-public:
-  // Note that the DOMDocument object of the two sequences being
-  // swapped should be the same.
-  //
-  void
-  swap (sequence& x);
-};
-
-inline bool
-operator== (const element_sequence&, const element_sequence&);
-
-inline bool
-operator!= (const element_sequence&, const element_sequence&);
-  
- - -

The following code shows how one could use this mapping:

- -
-void
-f (object& o, const xercesc::DOMElement& e)
-{
-  using namespace xercesc;
-
-  object::any_sequence& s (o.any ());
-
-  // Iteration.
-  //
-  for (object::any_iterator i (s.begin ()); i != s.end (); ++i)
-  {
-    DOMElement& e (*i);
-  }
-
-  // Modification.
-  //
-  s.push_back (e);                       // deep copy
-  DOMDocument& doc (o.dom_document ());
-  s.push_back (doc.createElement (...)); // assumes ownership
-}
-  
- -

2.12.4 Element Wildcard Order

- -

Similar to elements, element wildcards in ordered types - (Section 2.8.4, "Element Order") are assigned - content ids and are included in the content order sequence. - Continuing with the bank transactions example started in Section - 2.8.4, we can extend the batch by allowing custom transactions:

- -
-<complexType name="batch">
-  <choice minOccurs="0" maxOccurs="unbounded">
-    <element name="withdraw" type="withdraw"/>
-    <element name="deposit" type="deposit"/>
-    <any namespace="##other" processContents="lax"/>
-  </choice>
-</complexType>
-  
- -

This will lead to the following changes in the generated - batch C++ class:

- -
-class batch: public xml_schema::type
-{
-public:
-  ...
-
-  // any
-  //
-  typedef element_sequence any_sequence;
-  typedef any_sequence::iterator any_iterator;
-  typedef any_sequence::const_iterator any_const_iterator;
-
-  static const std::size_t any_id = 3UL;
-
-  const any_sequence&
-  any () const;
-
-  any_sequence&
-  any ();
-
-  void
-  any (const any_sequence&);
-
-  ...
-};
-  
- -

With this change we also need to update the iteration code to handle - the new content id:

- -
-for (batch::content_order_const_iterator i (b.content_order ().begin ());
-     i != b.content_order ().end ();
-     ++i)
-{
-  switch (i->id)
-  {
-    ...
-
-  case batch::any_id:
-    {
-      const DOMElement& e (b.any ()[i->index]);
-      ...
-      break;
-    }
-
-    ...
-  }
-}
-  
- -

For the complete working code that shows the use of wildcards in - ordered types refer to the order/element example in - the examples/cxx/tree/ directory in the XSD - distribution.

- -

2.12.5 Mapping for anyAttribute

- -

For anyAttribute the type definitions consist of an alias - of the container type with name any_attribute_set - (or any1_attribute_set, etc., for subsequent wildcards - in the type definition), an alias of the iterator type with name - any_attribute_iterator (or any1_attribute_iterator, - etc., for subsequent wildcards in the type definition), and an alias - of the constant iterator type with name any_attribute_const_iterator - (or any1_attribute_const_iterator, etc., for subsequent - wildcards in the type definition). -

- -

The accessor functions come in constant and non-constant versions. - The constant accessor function returns a constant reference to the - container and can be used for read-only access. The non-constant - version returns an unrestricted reference to the container and can - be used for read-write access. -

- -

The modifier function expects an argument of type reference to - constant of the container type. The modifier function makes - a deep copy of its argument. For instance: -

- - -
-<complexType name="object">
-  <sequence>
-    ...
-  </sequence>
-  <anyAttribute namespace="##other"/>
-</complexType>
-  
- -

is mapped to:

- -
-class object: public xml_schema::type
-{
-public:
-  // Type definitions.
-  //
-  typedef attribute_set any_attribute_set;
-  typedef any_attribute_set::iterator any_attribute_iterator;
-  typedef any_attribute_set::const_iterator any_attribute_const_iterator;
-
-  // Accessors.
-  //
-  const any_attribute_set&
-  any_attribute () const;
-
-  any_attribute_set&
-  any_attribute ();
-
-  // Modifier.
-  //
-  void
-  any_attribute (const any_attribute_set&);
-
-  ...
-
-};
-  
- -

The attribute_set class is an associative container - similar to the std::set class template as defined by - the ISO/ANSI Standard for C++ (ISO/IEC 14882:1998, Section 23.3.3, - "Class template set") with the key being the attribute's name - and namespace. Unlike std::set, attribute_set - allows searching using names and namespaces instead of - xercesc::DOMAttr objects. It is defined in an - implementation-specific namespace and its interface is presented - below: -

- -
-class attribute_set
-{
-public:
-  typedef xercesc::DOMAttr         key_type;
-  typedef xercesc::DOMAttr         value_type;
-  typedef xercesc::DOMAttr*        pointer;
-  typedef const xercesc::DOMAttr*  const_pointer;
-  typedef xercesc::DOMAttr&        reference;
-  typedef const xercesc::DOMAttr&  const_reference;
-
-  typedef <implementation-defined> iterator;
-  typedef <implementation-defined> const_iterator;
-  typedef <implementation-defined> reverse_iterator;
-  typedef <implementation-defined> const_reverse_iterator;
-
-  typedef <implementation-defined> size_type;
-  typedef <implementation-defined> difference_type;
-  typedef <implementation-defined> allocator_type;
-
-public:
-  attribute_set (xercesc::DOMDocument&);
-
-  template <typename I>
-  attribute_set (const I& begin, const I& end, xercesc::DOMDocument&);
-
-  attribute_set (const attribute_set&, xercesc::DOMDocument&);
-
-  attribute_set&
-  operator= (const attribute_set&);
-
-public:
-  const_iterator
-  begin () const;
-
-  const_iterator
-  end () const;
-
-  iterator
-  begin ();
-
-  iterator
-  end ();
-
-  const_reverse_iterator
-  rbegin () const;
-
-  const_reverse_iterator
-  rend () const;
-
-  reverse_iterator
-  rbegin ();
-
-  reverse_iterator
-  rend ();
-
-public:
-  size_type
-  size () const;
-
-  size_type
-  max_size () const;
-
-  bool
-  empty () const;
-
-  void
-  clear ();
-
-public:
-  // Makes a deep copy.
-  //
-  std::pair<iterator, bool>
-  insert (const xercesc::DOMAttr&);
-
-  // Assumes ownership.
-  //
-  std::pair<iterator, bool>
-  insert (xercesc::DOMAttr*);
-
-  // Makes a deep copy.
-  //
-  iterator
-  insert (iterator position, const xercesc::DOMAttr&);
-
-  // Assumes ownership.
-  //
-  iterator
-  insert (iterator position, xercesc::DOMAttr*);
-
-  template <typename I>
-  void
-  insert (const I& begin, const I& end);
-
-public:
-  void
-  erase (iterator position);
-
-  size_type
-  erase (const std::basic_string<C>& name);
-
-  size_type
-  erase (const std::basic_string<C>& namespace_,
-         const std::basic_string<C>& name);
-
-  size_type
-  erase (const XMLCh* name);
-
-  size_type
-  erase (const XMLCh* namespace_, const XMLCh* name);
-
-  void
-  erase (iterator begin, iterator end);
-
-public:
-  size_type
-  count (const std::basic_string<C>& name) const;
-
-  size_type
-  count (const std::basic_string<C>& namespace_,
-         const std::basic_string<C>& name) const;
-
-  size_type
-  count (const XMLCh* name) const;
-
-  size_type
-  count (const XMLCh* namespace_, const XMLCh* name) const;
-
-  iterator
-  find (const std::basic_string<C>& name);
-
-  iterator
-  find (const std::basic_string<C>& namespace_,
-        const std::basic_string<C>& name);
-
-  iterator
-  find (const XMLCh* name);
-
-  iterator
-  find (const XMLCh* namespace_, const XMLCh* name);
-
-  const_iterator
-  find (const std::basic_string<C>& name) const;
-
-  const_iterator
-  find (const std::basic_string<C>& namespace_,
-        const std::basic_string<C>& name) const;
-
-  const_iterator
-  find (const XMLCh* name) const;
-
-  const_iterator
-  find (const XMLCh* namespace_, const XMLCh* name) const;
-
-public:
-  // Note that the DOMDocument object of the two sets being
-  // swapped should be the same.
-  //
-  void
-  swap (attribute_set&);
-};
-
-bool
-operator== (const attribute_set&, const attribute_set&);
-
-bool
-operator!= (const attribute_set&, const attribute_set&);
-  
- -

The following code shows how one could use this mapping:

- -
-void
-f (object& o, const xercesc::DOMAttr& a)
-{
-  using namespace xercesc;
-
-  object::any_attribute_set& s (o.any_attribute ());
-
-  // Iteration.
-  //
-  for (object::any_attribute_iterator i (s.begin ()); i != s.end (); ++i)
-  {
-    DOMAttr& a (*i);
-  }
-
-  // Modification.
-  //
-  s.insert (a);                         // deep copy
-  DOMDocument& doc (o.dom_document ());
-  s.insert (doc.createAttribute (...)); // assumes ownership
-
-  // Searching.
-  //
-  object::any_attribute_iterator i (s.find ("name"));
-  i = s.find ("http://www.w3.org/XML/1998/namespace", "lang");
-}
-  
- - - -

2.13 Mapping for Mixed Content Models

- -

For XML Schema types with mixed content models C++/Tree provides - mapping support only if the type is marked as ordered - (Section 2.8.4, "Element Order"). Use the - --ordered-type-mixed XSD compiler option to - automatically mark all types with mixed content as ordered.

- -

For an ordered type with mixed content, C++/Tree adds an extra - text content sequence that is used to store the text fragments. - This text content sequence is also assigned the content id and - its entries are included in the content order sequence, just - like elements. As a result, it is possible to capture the order - between elements and text fragments.

- -

As an example, consider the following schema that describes text - with embedded links:

- -
-<complexType name="anchor">
-  <simpleContent>
-    <extension base="string">
-      <attribute name="href" type="anyURI" use="required"/>
-    </extension>
-  </simpleContent>
-</complexType>
-
-<complexType name="text" mixed="true">
-  <sequence>
-    <element name="a" type="anchor" minOccurs="0" maxOccurs="unbounded"/>
-  </sequence>
-</complexType>
-  
- -

The generated text C++ class will provide the following - API (assuming it is marked as ordered):

- -
-class text: public xml_schema::type
-{
-public:
-  // a
-  //
-  typedef anchor a_type;
-  typedef sequence<a_type> a_sequence;
-  typedef a_sequence::iterator a_iterator;
-  typedef a_sequence::const_iterator a_const_iterator;
-
-  static const std::size_t a_id = 1UL;
-
-  const a_sequence&
-  a () const;
-
-  a_sequence&
-  a ();
-
-  void
-  a (const a_sequence&);
-
-  // text_content
-  //
-  typedef xml_schema::string text_content_type;
-  typedef sequence<text_content_type> text_content_sequence;
-  typedef text_content_sequence::iterator text_content_iterator;
-  typedef text_content_sequence::const_iterator text_content_const_iterator;
-
-  static const std::size_t text_content_id = 2UL;
-
-  const text_content_sequence&
-  text_content () const;
-
-  text_content_sequence&
-  text_content ();
-
-  void
-  text_content (const text_content_sequence&);
-
-  // content_order
-  //
-  typedef xml_schema::content_order content_order_type;
-  typedef std::vector<content_order_type> content_order_sequence;
-  typedef content_order_sequence::iterator content_order_iterator;
-  typedef content_order_sequence::const_iterator content_order_const_iterator;
-
-  const content_order_sequence&
-  content_order () const;
-
-  content_order_sequence&
-  content_order ();
-
-  void
-  content_order (const content_order_sequence&);
-
-  ...
-};
-  
- -

Given this interface we can iterate over both link elements - and text in content order. The following code fragment converts - our format to plain text with references.

- -
-const text& t = ...
-
-for (text::content_order_const_iterator i (t.content_order ().begin ());
-     i != t.content_order ().end ();
-     ++i)
-{
-  switch (i->id)
-  {
-  case text::a_id:
-    {
-      const anchor& a (t.a ()[i->index]);
-      cerr << a << "[" << a.href () << "]";
-      break;
-    }
-  case text::text_content_id:
-    {
-      const xml_schema::string& s (t.text_content ()[i->index]);
-      cerr << s;
-      break;
-    }
-  default:
-    {
-      assert (false); // Unknown content id.
-    }
-  }
-}
-  
- -

For the complete working code that shows the use of mixed content - in ordered types refer to the order/mixed example in - the examples/cxx/tree/ directory in the XSD - distribution.

- - - - -

3 Parsing

- -

This chapter covers various aspects of parsing XML instance - documents in order to obtain corresponding tree-like object - model. -

- -

Each global XML Schema element in the form:

- -
-<element name="name" type="type"/>
-  
- -

is mapped to 14 overloaded C++ functions in the form:

- -
-// Read from a URI or a local file.
-//
-
-std::[auto|unique]_ptr<type>
-name (const std::basic_string<C>& uri,
-      xml_schema::flags = 0,
-      const xml_schema::properties& = xml_schema::properties ());
-
-std::[auto|unique]_ptr<type>
-name (const std::basic_string<C>& uri,
-      xml_schema::error_handler&,
-      xml_schema::flags = 0,
-      const xml_schema::properties& = xml_schema::properties ());
-
-std::[auto|unique]_ptr<type>
-name (const std::basic_string<C>& uri,
-      xercesc::DOMErrorHandler&,
-      xml_schema::flags = 0,
-      const xml_schema::properties& = xml_schema::properties ());
-
-
-// Read from std::istream.
-//
-
-std::[auto|unique]_ptr<type>
-name (std::istream&,
-      xml_schema::flags = 0,
-      const xml_schema::properties& = xml_schema::properties ());
-
-std::[auto|unique]_ptr<type>
-name (std::istream&,
-      xml_schema::error_handler&,
-      xml_schema::flags = 0,
-      const xml_schema::properties& = xml_schema::properties ());
-
-std::[auto|unique]_ptr<type>
-name (std::istream&,
-      xercesc::DOMErrorHandler&,
-      xml_schema::flags = 0,
-      const xml_schema::properties& = xml_schema::properties ());
-
-
-std::[auto|unique]_ptr<type>
-name (std::istream&,
-      const std::basic_string<C>& id,
-      xml_schema::flags = 0,
-      const xml_schema::properties& = xml_schema::properties ());
-
-std::[auto|unique]_ptr<type>
-name (std::istream&,
-      const std::basic_string<C>& id,
-      xml_schema::error_handler&,
-      xml_schema::flags = 0,
-      const xml_schema::properties& = xml_schema::properties ());
-
-std::[auto|unique]_ptr<type>
-name (std::istream&,
-      const std::basic_string<C>& id,
-      xercesc::DOMErrorHandler&,
-      xml_schema::flags = 0,
-      const xml_schema::properties& = xml_schema::properties ());
-
-
-// Read from InputSource.
-//
-
-std::[auto|unique]_ptr<type>
-name (xercesc::InputSource&,
-      xml_schema::flags = 0,
-      const xml_schema::properties& = xml_schema::properties ());
-
-std::[auto|unique]_ptr<type>
-name (xercesc::InputSource&,
-      xml_schema::error_handler&,
-      xml_schema::flags = 0,
-      const xml_schema::properties& = xml_schema::properties ());
-
-std::[auto|unique]_ptr<type>
-name (xercesc::InputSource&,
-      xercesc::DOMErrorHandler&,
-      xml_schema::flags = 0,
-      const xml_schema::properties& = xml_schema::properties ());
-
-
-// Read from DOM.
-//
-
-std::[auto|unique]_ptr<type>
-name (const xercesc::DOMDocument&,
-      xml_schema::flags = 0,
-      const xml_schema::properties& = xml_schema::properties ());
-
-std::[auto|unique]_ptr<type>
-name (xml_schema::dom::[auto|unique]_ptr<xercesc::DOMDocument>,
-      xml_schema::flags = 0,
-      const xml_schema::properties& = xml_schema::properties ());
-  
- -

You can choose between reading an XML instance from a local file, - URI, std::istream, xercesc::InputSource, - or a pre-parsed DOM instance in the form of - xercesc::DOMDocument. All the parsing functions - return a dynamically allocated object model as either - std::auto_ptr or std::unique_ptr, - depending on the C++ standard selected. Each of these parsing - functions is discussed in more detail in the following sections. -

- -

3.1 Initializing the Xerces-C++ Runtime

- -

Some parsing functions expect you to initialize the Xerces-C++ - runtime while others initialize and terminate it as part of their - work. The general rule is as follows: if a function has any arguments - or return a value that is an instance of a Xerces-C++ type, then - this function expects you to initialize the Xerces-C++ runtime. - Otherwise, the function initializes and terminates the runtime for - you. Note that it is legal to have nested calls to the Xerces-C++ - initialize and terminate functions as long as the calls are balanced. -

- -

You can instruct parsing functions that initialize and terminate - the runtime not to do so by passing the - xml_schema::flags::dont_initialize flag (see - Section 3.2, "Flags and Properties"). -

- - -

3.2 Flags and Properties

- -

Parsing flags and properties are the last two arguments of every - parsing function. They allow you to fine-tune the process of - instance validation and parsing. Both arguments are optional. -

- - -

The following flags are recognized by the parsing functions:

- -
-
xml_schema::flags::keep_dom
-
Keep association between DOM nodes and the resulting - object model nodes. For more information about DOM association - refer to Section 5.1, "DOM Association".
- -
xml_schema::flags::own_dom
-
Assume ownership of the DOM document passed. This flag only - makes sense together with the keep_dom flag in - the call to the parsing function with the - xml_schema::dom::[auto|unique]_ptr<DOMDocument> - argument.
- -
xml_schema::flags::dont_validate
-
Do not validate instance documents against schemas.
- -
xml_schema::flags::dont_initialize
-
Do not initialize the Xerces-C++ runtime.
-
- -

You can pass several flags by combining them using the bit-wise OR - operator. For example:

- -
-using xml_schema::flags;
-
-std::auto_ptr<type> r (
-  name ("test.xml", flags::keep_dom | flags::dont_validate));
-  
- -

By default, validation of instance documents is turned on even - though parsers generated by XSD do not assume instance - documents are valid. They include a number of checks that prevent - construction of inconsistent object models. This, - however, does not mean that an instance document that was - successfully parsed by the XSD-generated parsers is - valid per the corresponding schema. If an instance document is not - "valid enough" for the generated parsers to construct consistent - object model, one of the exceptions defined in - xml_schema namespace is thrown (see - Section 3.3, "Error Handling"). -

- -

For more information on the Xerces-C++ runtime initialization - refer to Section 3.1, "Initializing the Xerces-C++ - Runtime". -

- -

The xml_schema::properties class allows you to - programmatically specify schema locations to be used instead - of those specified with the xsi::schemaLocation - and xsi::noNamespaceSchemaLocation attributes - in instance documents. The interface of the properties - class is presented below: -

- -
-class properties
-{
-public:
-  void
-  schema_location (const std::basic_string<C>& namespace_,
-                   const std::basic_string<C>& location);
-  void
-  no_namespace_schema_location (const std::basic_string<C>& location);
-};
-  
- -

Note that all locations are relative to an instance document unless - they are URIs. For example, if you want to use a local file as your - schema, then you will need to pass - file:///absolute/path/to/your/schema as the location - argument. -

- -

3.3 Error Handling

- -

As discussed in Section 2.2, "Error Handling", - the mapping uses the C++ exception handling mechanism as its primary - way of reporting error conditions. However, to handle recoverable - parsing and validation errors and warnings, a callback interface maybe - preferred by the application.

- -

To better understand error handling and reporting strategies employed - by the parsing functions, it is useful to know that the - transformation of an XML instance document to a statically-typed - tree happens in two stages. The first stage, performed by Xerces-C++, - consists of parsing an XML document into a DOM instance. For short, - we will call this stage the XML-DOM stage. Validation, if not disabled, - happens during this stage. The second stage, - performed by the generated parsers, consist of parsing the DOM - instance into the statically-typed tree. We will call this stage - the DOM-Tree stage. Additional checks are performed during this - stage in order to prevent construction of inconsistent tree which - could otherwise happen when validation is disabled, for example.

- -

All parsing functions except the one that operates on a DOM instance - come in overloaded triples. The first function in such a triple - reports error conditions exclusively by throwing exceptions. It - accumulates all the parsing and validation errors of the XML-DOM - stage and throws them in a single instance of the - xml_schema::parsing exception (described below). - The second and the third functions in the triple use callback - interfaces to report parsing and validation errors and warnings. - The two callback interfaces are xml_schema::error_handler - and xercesc::DOMErrorHandler. For more information - on the xercesc::DOMErrorHandler interface refer to - the Xerces-C++ documentation. The xml_schema::error_handler - interface is presented below: -

- -
-class error_handler
-{
-public:
-  struct severity
-  {
-    enum value
-    {
-      warning,
-      error,
-      fatal
-    };
-  };
-
-  virtual bool
-  handle (const std::basic_string<C>& id,
-          unsigned long line,
-          unsigned long column,
-          severity,
-          const std::basic_string<C>& message) = 0;
-
-  virtual
-  ~error_handler ();
-};
-  
- -

The id argument of the error_handler::handle - function identifies the resource being parsed (e.g., a file name or - URI). -

- -

By returning true from the handle function - you instruct the parser to recover and continue parsing. Returning - false results in termination of the parsing process. - An error with the fatal severity level results in - termination of the parsing process no matter what is returned from - the handle function. It is safe to throw an exception - from the handle function. -

- -

The DOM-Tree stage reports error conditions exclusively by throwing - exceptions. Individual exceptions thrown by the parsing functions - are described in the following sub-sections. -

- - -

3.3.1 xml_schema::parsing

- -
-struct severity
-{
-  enum value
-  {
-    warning,
-    error
-  };
-
-  severity (value);
-  operator value () const;
-};
-
-struct error
-{
-  error (severity,
-         const std::basic_string<C>& id,
-         unsigned long line,
-         unsigned long column,
-         const std::basic_string<C>& message);
-
-  severity
-  severity () const;
-
-  const std::basic_string<C>&
-  id () const;
-
-  unsigned long
-  line () const;
-
-  unsigned long
-  column () const;
-
-  const std::basic_string<C>&
-  message () const;
-};
-
-std::basic_ostream<C>&
-operator<< (std::basic_ostream<C>&, const error&);
-
-struct diagnostics: std::vector<error>
-{
-};
-
-std::basic_ostream<C>&
-operator<< (std::basic_ostream<C>&, const diagnostics&);
-
-struct parsing: virtual exception
-{
-  parsing ();
-  parsing (const diagnostics&);
-
-  const diagnostics&
-  diagnostics () const;
-
-  virtual const char*
-  what () const throw ();
-};
-  
- -

The xml_schema::parsing exception is thrown if there - were parsing or validation errors reported during the XML-DOM stage. - If no callback interface was provided to the parsing function, the - exception contains a list of errors and warnings accessible using - the diagnostics function. The usual conditions when - this exception is thrown include malformed XML instances and, if - validation is turned on, invalid instance documents. -

- -

3.3.2 xml_schema::expected_element

- -
-struct expected_element: virtual exception
-{
-  expected_element (const std::basic_string<C>& name,
-                    const std::basic_string<C>& namespace_);
-
-
-  const std::basic_string<C>&
-  name () const;
-
-  const std::basic_string<C>&
-  namespace_ () const;
-
-
-  virtual const char*
-  what () const throw ();
-};
-  
- -

The xml_schema::expected_element exception is thrown - when an expected element is not encountered by the DOM-Tree stage. - The name and namespace of the expected element can be obtained using - the name and namespace_ functions respectively. -

- - -

3.3.3 xml_schema::unexpected_element

- -
-struct unexpected_element: virtual exception
-{
-  unexpected_element (const std::basic_string<C>& encountered_name,
-                      const std::basic_string<C>& encountered_namespace,
-                      const std::basic_string<C>& expected_name,
-                      const std::basic_string<C>& expected_namespace)
-
-
-  const std::basic_string<C>&
-  encountered_name () const;
-
-  const std::basic_string<C>&
-  encountered_namespace () const;
-
-
-  const std::basic_string<C>&
-  expected_name () const;
-
-  const std::basic_string<C>&
-  expected_namespace () const;
-
-
-  virtual const char*
-  what () const throw ();
-};
-  
- -

The xml_schema::unexpected_element exception is thrown - when an unexpected element is encountered by the DOM-Tree stage. - The name and namespace of the encountered element can be obtained - using the encountered_name and - encountered_namespace functions respectively. If an - element was expected instead of the encountered one, its name - and namespace can be obtained using the expected_name and - expected_namespace functions respectively. Otherwise - these functions return empty strings. -

- -

3.3.4 xml_schema::expected_attribute

- -
-struct expected_attribute: virtual exception
-{
-  expected_attribute (const std::basic_string<C>& name,
-                      const std::basic_string<C>& namespace_);
-
-
-  const std::basic_string<C>&
-  name () const;
-
-  const std::basic_string<C>&
-  namespace_ () const;
-
-
-  virtual const char*
-  what () const throw ();
-};
-  
- -

The xml_schema::expected_attribute exception is thrown - when an expected attribute is not encountered by the DOM-Tree stage. - The name and namespace of the expected attribute can be obtained using - the name and namespace_ functions respectively. -

- - -

3.3.5 xml_schema::unexpected_enumerator

- -
-struct unexpected_enumerator: virtual exception
-{
-  unexpected_enumerator (const std::basic_string<C>& enumerator);
-
-  const std::basic_string<C>&
-  enumerator () const;
-
-  virtual const char*
-  what () const throw ();
-};
-  
- -

The xml_schema::unexpected_enumerator exception is thrown - when an unexpected enumerator is encountered by the DOM-Tree stage. - The enumerator can be obtained using the enumerator - functions. -

- -

3.3.6 xml_schema::expected_text_content

- -
-struct expected_text_content: virtual exception
-{
-  virtual const char*
-  what () const throw ();
-};
-  
- -

The xml_schema::expected_text_content exception is thrown - when a content other than text is encountered and the text content was - expected by the DOM-Tree stage. -

- -

3.3.7 xml_schema::no_type_info

- -
-struct no_type_info: virtual exception
-{
-  no_type_info (const std::basic_string<C>& type_name,
-                const std::basic_string<C>& type_namespace);
-
-  const std::basic_string<C>&
-  type_name () const;
-
-  const std::basic_string<C>&
-  type_namespace () const;
-
-  virtual const char*
-  what () const throw ();
-};
-  
- -

The xml_schema::no_type_info exception is thrown - when there is no type information associated with a type specified - by the xsi:type attribute. This exception is thrown - by the DOM-Tree stage. The name and namespace of the type in question - can be obtained using the type_name and - type_namespace functions respectively. Usually, catching - this exception means that you haven't linked the code generated - from the schema defining the type in question with your application - or this schema has been compiled without the - --generate-polymorphic option. -

- - -

3.3.8 xml_schema::not_derived

- -
-struct not_derived: virtual exception
-{
-  not_derived (const std::basic_string<C>& base_type_name,
-               const std::basic_string<C>& base_type_namespace,
-               const std::basic_string<C>& derived_type_name,
-               const std::basic_string<C>& derived_type_namespace);
-
-  const std::basic_string<C>&
-  base_type_name () const;
-
-  const std::basic_string<C>&
-  base_type_namespace () const;
-
-
-  const std::basic_string<C>&
-  derived_type_name () const;
-
-  const std::basic_string<C>&
-  derived_type_namespace () const;
-
-  virtual const char*
-  what () const throw ();
-};
-  
- -

The xml_schema::not_derived exception is thrown - when a type specified by the xsi:type attribute is - not derived from the expected base type. This exception is thrown - by the DOM-Tree stage. The name and namespace of the expected - base type can be obtained using the base_type_name and - base_type_namespace functions respectively. The name - and namespace of the offending type can be obtained using the - derived_type_name and - derived_type_namespace functions respectively. -

- -

3.3.9 xml_schema::no_prefix_mapping

- -
-struct no_prefix_mapping: virtual exception
-{
-  no_prefix_mapping (const std::basic_string<C>& prefix);
-
-  const std::basic_string<C>&
-  prefix () const;
-
-  virtual const char*
-  what () const throw ();
-};
-  
- -

The xml_schema::no_prefix_mapping exception is thrown - during the DOM-Tree stage if a namespace prefix is encountered for - which a prefix-namespace mapping hasn't been provided. The namespace - prefix in question can be obtained using the prefix - function. -

- -

3.4 Reading from a Local File or URI

- -

Using a local file or URI is the simplest way to parse an XML instance. - For example:

- -
-using std::auto_ptr;
-
-auto_ptr<type> r1 (name ("test.xml"));
-auto_ptr<type> r2 (name ("https://www.codesynthesis.com/test.xml"));
-  
- -

Or, in the C++11 mode:

- -
-using std::unique_ptr;
-
-unique_ptr<type> r1 (name ("test.xml"));
-unique_ptr<type> r2 (name ("https://www.codesynthesis.com/test.xml"));
-  
- -

3.5 Reading from std::istream

- -

When using an std::istream instance, you may also - pass an optional resource id. This id is used to identify the - resource (for example in error messages) as well as to resolve - relative paths. For instance:

- -
-using std::auto_ptr;
-
-{
-  std::ifstream ifs ("test.xml");
-  auto_ptr<type> r (name (ifs, "test.xml"));
-}
-
-{
-  std::string str ("..."); // Some XML fragment.
-  std::istringstream iss (str);
-  auto_ptr<type> r (name (iss));
-}
-  
- -

3.6 Reading from xercesc::InputSource

- -

Reading from a xercesc::InputSource instance - is similar to the std::istream case except - the resource id is maintained by the InputSource - object. For instance:

- -
-xercesc::StdInInputSource is;
-std::auto_ptr<type> r (name (is));
-  
- -

3.7 Reading from DOM

- -

Reading from a xercesc::DOMDocument instance allows - you to setup a custom XML-DOM stage. Things like DOM - parser reuse, schema pre-parsing, and schema caching can be achieved - with this approach. For more information on how to obtain DOM - representation from an XML instance refer to the Xerces-C++ - documentation. In addition, the - C++/Tree Mapping - FAQ shows how to parse an XML instance to a Xerces-C++ - DOM document using the XSD runtime utilities. -

- -

The last parsing function is useful when you would like to perform - your own XML-to-DOM parsing and associate the resulting DOM document - with the object model nodes. The automatic DOMDocument - pointer is reset and the resulting object model assumes ownership - of the DOM document passed. For example:

- -
-// C++98 version.
-//
-xml_schema::dom::auto_ptr<xercesc::DOMDocument> doc = ...
-
-std::auto_ptr<type> r (
-  name (doc, xml_schema::flags::keep_dom | xml_schema::flags::own_dom));
-
-// At this point doc is reset to 0.
-
-// C++11 version.
-//
-xml_schema::dom::unique_ptr<xercesc::DOMDocument> doc = ...
-
-std::unique_ptr<type> r (
-  name (std::move (doc),
-        xml_schema::flags::keep_dom | xml_schema::flags::own_dom));
-
-// At this point doc is reset to 0.
-  
- -

4 Serialization

- -

This chapter covers various aspects of serializing a - tree-like object model to DOM or XML. - In this regard, serialization is complimentary to the reverse - process of parsing a DOM or XML instance into an object model - which is discussed in Chapter 3, - "Parsing". Note that the generation of the serialization code - is optional and should be explicitly requested with the - --generate-serialization option. See the - XSD - Compiler Command Line Manual for more information. -

- -

Each global XML Schema element in the form: -

- - -
-<xsd:element name="name" type="type"/>
-  
- -

is mapped to 8 overloaded C++ functions in the form:

- -
-// Serialize to std::ostream.
-//
-void
-name (std::ostream&,
-      const type&,
-      const xml_schema::namespace_fomap& =
-        xml_schema::namespace_infomap (),
-      const std::basic_string<C>& encoding = "UTF-8",
-      xml_schema::flags = 0);
-
-void
-name (std::ostream&,
-      const type&,
-      xml_schema::error_handler&,
-      const xml_schema::namespace_infomap& =
-        xml_schema::namespace_infomap (),
-      const std::basic_string<C>& encoding = "UTF-8",
-      xml_schema::flags = 0);
-
-void
-name (std::ostream&,
-      const type&,
-      xercesc::DOMErrorHandler&,
-      const xml_schema::namespace_infomap& =
-        xml_schema::namespace_infomap (),
-      const std::basic_string<C>& encoding = "UTF-8",
-      xml_schema::flags = 0);
-
-
-// Serialize to XMLFormatTarget.
-//
-void
-name (xercesc::XMLFormatTarget&,
-      const type&,
-      const xml_schema::namespace_infomap& =
-        xml_schema::namespace_infomap (),
-      const std::basic_string<C>& encoding = "UTF-8",
-      xml_schema::flags = 0);
-
-void
-name (xercesc::XMLFormatTarget&,
-      const type&,
-      xml_schema::error_handler&,
-      const xml_schema::namespace_infomap& =
-        xml_schema::namespace_infomap (),
-      const std::basic_string<C>& encoding = "UTF-8",
-      xml_schema::flags = 0);
-
-void
-name (xercesc::XMLFormatTarget&,
-      const type&,
-      xercesc::DOMErrorHandler&,
-      const xml_schema::namespace_infomap& =
-        xml_schema::namespace_infomap (),
-      const std::basic_string<C>& encoding = "UTF-8",
-      xml_schema::flags = 0);
-
-
-// Serialize to DOM.
-//
-xml_schema::dom::[auto|unique]_ptr<xercesc::DOMDocument>
-name (const type&,
-      const xml_schema::namespace_infomap&
-        xml_schema::namespace_infomap (),
-      xml_schema::flags = 0);
-
-void
-name (xercesc::DOMDocument&,
-      const type&,
-      xml_schema::flags = 0);
-  
- -

You can choose between writing XML to std::ostream or - xercesc::XMLFormatTarget and creating a DOM instance - in the form of xercesc::DOMDocument. Serialization - to ostream or XMLFormatTarget requires a - considerably less work while serialization to DOM provides - for greater flexibility. Each of these serialization functions - is discussed in more detail in the following sections. -

- - -

4.1 Initializing the Xerces-C++ Runtime

- -

Some serialization functions expect you to initialize the Xerces-C++ - runtime while others initialize and terminate it as part of their - work. The general rule is as follows: if a function has any arguments - or return a value that is an instance of a Xerces-C++ type, then - this function expects you to initialize the Xerces-C++ runtime. - Otherwise, the function initializes and terminates the runtime for - you. Note that it is legal to have nested calls to the Xerces-C++ - initialize and terminate functions as long as the calls are balanced. -

- -

You can instruct serialization functions that initialize and terminate - the runtime not to do so by passing the - xml_schema::flags::dont_initialize flag (see - Section 4.3, "Flags"). -

- -

4.2 Namespace Infomap and Character Encoding

- -

When a document being serialized uses XML namespaces, custom - prefix-namespace associations can to be established. If custom - prefix-namespace mapping is not provided then generic prefixes - (p1, p2, etc) are automatically assigned - to namespaces as needed. Also, if - you would like the resulting instance document to contain the - schemaLocation or noNamespaceSchemaLocation - attributes, you will need to provide namespace-schema associations. - The xml_schema::namespace_infomap class is used - to capture this information:

- -
-struct namespace_info
-{
-  namespace_info ();
-  namespace_info (const std::basic_string<C>& name,
-                  const std::basic_string<C>& schema);
-
-  std::basic_string<C> name;
-  std::basic_string<C> schema;
-};
-
-// Map of namespace prefix to namespace_info.
-//
-struct namespace_infomap: public std::map<std::basic_string<C>,
-                                          namespace_info>
-{
-};
-  
- -

Consider the following associations as an example:

- -
-xml_schema::namespace_infomap map;
-
-map["t"].name = "https://www.codesynthesis.com/test";
-map["t"].schema = "test.xsd";
-  
- -

This map, if passed to one of the serialization functions, - could result in the following XML fragment:

- -
-<?xml version="1.0" ?>
-<t:name xmlns:t="https://www.codesynthesis.com/test"
-        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-        xsi:schemaLocation="https://www.codesynthesis.com/test test.xsd">
-  
- -

As you can see, the serialization function automatically added namespace - mapping for the xsi prefix. You can change this by - providing your own prefix:

- -
-xml_schema::namespace_infomap map;
-
-map["xsn"].name = "http://www.w3.org/2001/XMLSchema-instance";
-
-map["t"].name = "https://www.codesynthesis.com/test";
-map["t"].schema = "test.xsd";
-  
- -

This could result in the following XML fragment:

- -
-<?xml version="1.0" ?>
-<t:name xmlns:t="https://www.codesynthesis.com/test"
-        xmlns:xsn="http://www.w3.org/2001/XMLSchema-instance"
-        xsn:schemaLocation="https://www.codesynthesis.com/test test.xsd">
-  
- -

To specify the location of a schema without a namespace you can use - an empty prefix as in the example below:

- -
-xml_schema::namespace_infomap map;
-
-map[""].schema = "test.xsd";
-  
- -

This would result in the following XML fragment:

- -
-<?xml version="1.0" ?>
-<name xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-      xsi:noNamespaceSchemaLocation="test.xsd">
-  
- -

To make a particular namespace default you can use an empty - prefix, for example:

- -
-xml_schema::namespace_infomap map;
-
-map[""].name = "https://www.codesynthesis.com/test";
-map[""].schema = "test.xsd";
-  
- -

This could result in the following XML fragment:

- -
-<?xml version="1.0" ?>
-<name xmlns="https://www.codesynthesis.com/test"
-      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-      xsi:schemaLocation="https://www.codesynthesis.com/test test.xsd">
-  
- - -

Another bit of information that you can pass to the serialization - functions is the character encoding method that you would like to use. - Common values for this argument are "US-ASCII", - "ISO8859-1", "UTF-8", - "UTF-16BE", "UTF-16LE", - "UCS-4BE", and "UCS-4LE". The default - encoding is "UTF-8". For more information on - encoding methods see the - "Character - Encoding" article from Wikipedia. -

- -

4.3 Flags

- -

Serialization flags are the last argument of every serialization - function. They allow you to fine-tune the process of serialization. - The flags argument is optional. -

- - -

The following flags are recognized by the serialization - functions:

- -
-
xml_schema::flags::dont_initialize
-
Do not initialize the Xerces-C++ runtime.
- -
xml_schema::flags::dont_pretty_print
-
Do not add extra spaces or new lines that make the resulting XML - slightly bigger but easier to read.
- -
xml_schema::flags::no_xml_declaration
-
Do not write XML declaration (<?xml ... ?>).
-
- -

You can pass several flags by combining them using the bit-wise OR - operator. For example:

- -
-std::auto_ptr<type> r = ...
-std::ofstream ofs ("test.xml");
-xml_schema::namespace_infomap map;
-name (ofs,
-      *r,
-      map,
-      "UTF-8",
-      xml_schema::flags::no_xml_declaration |
-      xml_schema::flags::dont_pretty_print);
-  
- -

For more information on the Xerces-C++ runtime initialization - refer to Section 4.1, "Initializing the Xerces-C++ - Runtime". -

- -

4.4 Error Handling

- -

As with the parsing functions (see Section 3.3, - "Error Handling"), to better understand error handling and - reporting strategies employed by the serialization functions, it - is useful to know that the transformation of a statically-typed - tree to an XML instance document happens in two stages. The first - stage, performed by the generated code, consist of building a DOM - instance from the statically-typed tree . For short, we will call - this stage the Tree-DOM stage. The second stage, performed by - Xerces-C++, consists of serializing the DOM instance into the XML - document. We will call this stage the DOM-XML stage. -

- -

All serialization functions except the two that serialize into - a DOM instance come in overloaded triples. The first function - in such a triple reports error conditions exclusively by throwing - exceptions. It accumulates all the serialization errors of the - DOM-XML stage and throws them in a single instance of the - xml_schema::serialization exception (described below). - The second and the third functions in the triple use callback - interfaces to report serialization errors and warnings. The two - callback interfaces are xml_schema::error_handler and - xercesc::DOMErrorHandler. The - xml_schema::error_handler interface is described in - Section 3.3, "Error Handling". For more information - on the xercesc::DOMErrorHandler interface refer to the - Xerces-C++ documentation. -

- -

The Tree-DOM stage reports error conditions exclusively by throwing - exceptions. Individual exceptions thrown by the serialization functions - are described in the following sub-sections. -

- -

4.4.1 xml_schema::serialization

- -
-struct serialization: virtual exception
-{
-  serialization ();
-  serialization (const diagnostics&);
-
-  const diagnostics&
-  diagnostics () const;
-
-  virtual const char*
-  what () const throw ();
-};
-  
- -

The xml_schema::diagnostics class is described in - Section 3.3.1, "xml_schema::parsing". - The xml_schema::serialization exception is thrown if - there were serialization errors reported during the DOM-XML stage. - If no callback interface was provided to the serialization function, - the exception contains a list of errors and warnings accessible using - the diagnostics function. -

- - -

4.4.2 xml_schema::unexpected_element

- -

The xml_schema::unexpected_element exception is - described in Section 3.3.3, - "xml_schema::unexpected_element". It is thrown - by the serialization functions during the Tree-DOM stage if the - root element name of the provided DOM instance does not match with - the name of the element this serialization function is for. -

- -

4.4.3 xml_schema::no_type_info

- -

The xml_schema::no_type_info exception is - described in Section 3.3.7, - "xml_schema::no_type_info". It is thrown - by the serialization functions during the Tree-DOM stage when there - is no type information associated with a dynamic type of an - element. Usually, catching this exception means that you haven't - linked the code generated from the schema defining the type in - question with your application or this schema has been compiled - without the --generate-polymorphic option. -

- -

4.5 Serializing to std::ostream

- -

In order to serialize to std::ostream you will need - an object model, an output stream and, optionally, a namespace - infomap. For instance:

- -
-// Obtain the object model.
-//
-std::auto_ptr<type> r = ...
-
-// Prepare namespace mapping and schema location information.
-//
-xml_schema::namespace_infomap map;
-
-map["t"].name = "https://www.codesynthesis.com/test";
-map["t"].schema = "test.xsd";
-
-// Write it out.
-//
-name (std::cout, *r, map);
-  
- -

Note that the output stream is treated as a binary stream. This - becomes important when you use a character encoding that is wider - than 8-bit char, for instance UTF-16 or UCS-4. For - example, things will most likely break if you try to serialize - to std::ostringstream with UTF-16 or UCS-4 as an - encoding. This is due to the special value, - '\0', that will most likely occur as part of such - serialization and it won't have the special meaning assumed by - std::ostringstream. -

- - -

4.6 Serializing to xercesc::XMLFormatTarget

- -

Serializing to an xercesc::XMLFormatTarget instance - is similar the std::ostream case. For instance: -

- -
-using std::auto_ptr;
-
-// Obtain the object model.
-//
-auto_ptr<type> r = ...
-
-// Prepare namespace mapping and schema location information.
-//
-xml_schema::namespace_infomap map;
-
-map["t"].name = "https://www.codesynthesis.com/test";
-map["t"].schema = "test.xsd";
-
-using namespace xercesc;
-
-XMLPlatformUtils::Initialize ();
-
-{
-  // Choose a target.
-  //
-  auto_ptr<XMLFormatTarget> ft;
-
-  if (argc != 2)
-  {
-    ft = auto_ptr<XMLFormatTarget> (new StdOutFormatTarget ());
-  }
-  else
-  {
-    ft = auto_ptr<XMLFormatTarget> (
-      new LocalFileFormatTarget (argv[1]));
-  }
-
-  // Write it out.
-  //
-  name (*ft, *r, map);
-}
-
-XMLPlatformUtils::Terminate ();
-  
- -

Note that we had to initialize the Xerces-C++ runtime before we - could call this serialization function.

- -

4.7 Serializing to DOM

- -

The mapping provides two overloaded functions that implement - serialization to a DOM instance. The first creates a DOM instance - for you and the second serializes to an existing DOM instance. - While serializing to a new DOM instance is similar to serializing - to std::ostream or xercesc::XMLFormatTarget, - serializing to an existing DOM instance requires quite a bit of work - from your side. You will need to set all the custom namespace mapping - attributes as well as the schemaLocation and/or - noNamespaceSchemaLocation attributes. The following - listing should give you an idea about what needs to be done: -

- -
-// Obtain the object model.
-//
-std::auto_ptr<type> r = ...
-
-using namespace xercesc;
-
-XMLPlatformUtils::Initialize ();
-
-{
-  // Create a DOM instance. Set custom namespace mapping and schema
-  // location attributes.
-  //
-  DOMDocument& doc = ...
-
-  // Serialize to DOM.
-  //
-  name (doc, *r);
-
-  // Serialize the DOM document to XML.
-  //
-  ...
-}
-
-XMLPlatformUtils::Terminate ();
-  
- -

For more information on how to create and serialize a DOM instance - refer to the Xerces-C++ documentation. In addition, the - C++/Tree Mapping - FAQ shows how to implement these operations using the XSD - runtime utilities. -

- -

5 Additional Functionality

- -

The C++/Tree mapping provides a number of optional features - that can be useful in certain situations. They are described - in the following sections.

- -

5.1 DOM Association

- -

Normally, after parsing is complete, the DOM document which - was used to extract the data is discarded. However, the parsing - functions can be instructed to preserve the DOM document - and create an association between the DOM nodes and object model - nodes. When there is an association between the DOM and - object model nodes, you can obtain the corresponding DOM element - or attribute node from an object model node as well as perform - the reverse transition: obtain the corresponding object model - from a DOM element or attribute node.

- -

Maintaining DOM association is normally useful when the application - needs access to XML constructs that are not preserved in the - object model, for example, XML comments. - Another useful aspect of DOM association is the ability of the - application to navigate the document tree using the generic DOM - interface (for example, with the help of an XPath processor) - and then move back to the statically-typed object model. Note - also that while you can change the underlying DOM document, - these changes are not reflected in the object model and will - be ignored during serialization. If you need to not only access - but also modify some aspects of XML that are not preserved in - the object model, then type customization with custom parsing - constructors and serialization operators should be used instead.

- -

To request DOM association you will need to pass the - xml_schema::flags::keep_dom flag to one of the - parsing functions (see Section 3.2, - "Flags and Properties" for more information). In this case the - DOM document is retained and will be released when the object model - is deleted. Note that since DOM nodes "out-live" the parsing function - call, you need to initialize the Xerces-C++ runtime before calling - one of the parsing functions with the keep_dom flag and - terminate it after the object model is destroyed (see - Section 3.1, "Initializing the Xerces-C++ Runtime").

- -

If the keep_dom flag is passed - as the second argument to the copy constructor and the copy - being made is of a complete tree, then the DOM association - is also maintained in the copy by cloning the underlying - DOM document and reestablishing the associations. For example:

- -
-using namespace xercesc;
-
-XMLPlatformUtils::Initialize ();
-
-{
-  // Parse XML to object model.
-  //
-  std::auto_ptr<type> r (root (
-    "root.xml",
-     xml_schema::flags::keep_dom |
-     xml_schema::flags::dont_initialize));
-
-   // Copy without DOM association.
-   //
-   type copy1 (*r);
-
-   // Copy with DOM association.
-   //
-   type copy2 (*r, xml_schema::flags::keep_dom);
-}
-
-XMLPlatformUtils::Terminate ();
-  
- - -

To obtain the corresponding DOM node from an object model node - you will need to call the _node accessor function - which returns a pointer to DOMNode. You can then query - this DOM node's type and cast it to either DOMAttr* - or DOMElement*. To obtain the corresponding object - model node from a DOM node, the DOM user data API is used. The - xml_schema::dom::tree_node_key variable contains - the key for object model nodes. The following schema and code - fragment show how to navigate from DOM to object model nodes - and in the opposite direction:

- -
-<complexType name="object">
-  <sequence>
-    <element name="a" type="string"/>
-  </sequence>
-</complexType>
-
-<element name="root" type="object"/>
-  
- -
-using namespace xercesc;
-
-XMLPlatformUtils::Initialize ();
-
-{
-  // Parse XML to object model.
-  //
-  std::auto_ptr<type> r (root (
-    "root.xml",
-     xml_schema::flags::keep_dom |
-     xml_schema::flags::dont_initialize));
-
-  DOMNode* n = r->_node ();
-  assert (n->getNodeType () == DOMNode::ELEMENT_NODE);
-  DOMElement* re = static_cast<DOMElement*> (n);
-
-  // Get the 'a' element. Note that it is not necessarily the
-  // first child node of 'root' since there could be whitespace
-  // nodes before it.
-  //
-  DOMElement* ae;
-
-  for (n = re->getFirstChild (); n != 0; n = n->getNextSibling ())
-  {
-    if (n->getNodeType () == DOMNode::ELEMENT_NODE)
-    {
-      ae = static_cast<DOMElement*> (n);
-      break;
-    }
-  }
-
-  // Get from the 'a' DOM element to xml_schema::string object model
-  // node.
-  //
-  xml_schema::type& t (
-    *reinterpret_cast<xml_schema::type*> (
-       ae->getUserData (xml_schema::dom::tree_node_key)));
-
-  xml_schema::string& a (dynamic_cast<xml_schema::string&> (t));
-}
-
-XMLPlatformUtils::Terminate ();
-  
- -

The 'mixed' example which can be found in the XSD distribution - shows how to handle the mixed content using DOM association.

- -

5.2 Binary Serialization

- -

Besides reading from and writing to XML, the C++/Tree mapping - also allows you to save the object model to and load it from a - number of predefined as well as custom data representation - formats. The predefined binary formats are CDR (Common Data - Representation) and XDR (eXternal Data Representation). A - custom format can easily be supported by providing - insertion and extraction operators for basic types.

- -

Binary serialization saves only the data without any meta - information or markup. As a result, saving to and loading - from a binary representation can be an order of magnitude - faster than parsing and serializing the same data in XML. - Furthermore, the resulting representation is normally several - times smaller than the equivalent XML representation. These - properties make binary serialization ideal for internal data - exchange and storage. A typical application that uses this - facility stores the data and communicates within the - system using a binary format and reads/writes the data - in XML when communicating with the outside world.

- -

In order to request the generation of insertion operators and - extraction constructors for a specific predefined or custom - data representation stream, you will need to use the - --generate-insertion and --generate-extraction - compiler options. See the - XSD - Compiler Command Line Manual for more information.

- -

Once the insertion operators and extraction constructors are - generated, you can use the xml_schema::istream - and xml_schema::ostream wrapper stream templates - to save the object model to and load it from a specific format. - The following code fragment shows how to do this using ACE - (Adaptive Communication Environment) CDR streams as an example:

- -
-<complexType name="object">
-  <sequence>
-    <element name="a" type="string"/>
-    <element name="b" type="int"/>
-  </sequence>
-</complexType>
-
-<element name="root" type="object"/>
-  
- -
-// Parse XML to object model.
-//
-std::auto_ptr<type> r (root ("root.xml"));
-
-// Save to a CDR stream.
-//
-ACE_OutputCDR ace_ocdr;
-xml_schema::ostream<ACE_OutputCDR> ocdr (ace_ocdr);
-
-ocdr << *r;
-
-// Load from a CDR stream.
-//
-ACE_InputCDR ace_icdr (buf, size);
-xml_schema::istream<ACE_InputCDR> icdr (ace_icdr);
-
-std::auto_ptr<object> copy (new object (icdr));
-
-// Serialize to XML.
-//
-root (std::cout, *copy);
-  
- -

The XSD distribution contains a number of examples that - show how to save the object model to and load it from - CDR, XDR, and a custom format.

- - - - -

Appendix A — Default and Fixed Values

- -

The following table summarizes the effect of default and fixed - values (specified with the default and fixed - attributes, respectively) on attribute and element values. The - default and fixed attributes are mutually - exclusive. It is also worthwhile to note that the fixed value semantics - is a superset of the default value semantics. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
defaultfixed
elementnot presentoptionalrequiredoptionalrequired
not presentinvalid instancenot presentinvalid instance
emptydefault value is usedfixed value is used
valuevalue is usedvalue is used provided it's the same as fixed
attributenot presentoptionalrequiredoptionalrequired
default value is usedinvalid schemafixed value is usedinvalid instance
emptyempty value is usedempty value is used provided it's the same as fixed
valuevalue is usedvalue is used provided it's the same as fixed
- -
-
- - - - diff --git a/doc/cxx/tree/manual/makefile b/doc/cxx/tree/manual/makefile deleted file mode 100644 index 7d46c91..0000000 --- a/doc/cxx/tree/manual/makefile +++ /dev/null @@ -1,53 +0,0 @@ -# file : doc/cxx/tree/manual/makefile -# license : GNU GPL v2 + exceptions; see accompanying LICENSE file - -include $(dir $(lastword $(MAKEFILE_LIST)))../../../../build/bootstrap.make - -default := $(out_base)/ -install := $(out_base)/.install -dist := $(out_base)/.dist -dist-win := $(out_base)/.dist-win -clean := $(out_base)/.clean - -# Build. -# -$(default): $(out_base)/cxx-tree-manual.ps $(out_base)/cxx-tree-manual.pdf - - -$(out_base)/cxx-tree-manual.ps: $(src_base)/index.xhtml \ - $(src_base)/manual.html2ps \ - | $(out_base)/. - $(call message,html2ps $<,html2ps -f $(src_base)/manual.html2ps -o $@ $<) - -$(out_base)/cxx-tree-manual.pdf: $(out_base)/cxx-tree-manual.ps | $(out_base)/. - $(call message,ps2pdf $<,ps2pdf14 $< $@) - -# Install & Dist. -# -$(install): path := $(subst $(src_root)/doc/,,$(src_base)) -$(dist): path := $(subst $(src_root)/,,$(src_base)) - -$(install): $(out_base)/cxx-tree-manual.ps $(out_base)/cxx-tree-manual.pdf - $(call install-data,$(src_base)/index.xhtml,$(install_doc_dir)/xsd/$(path)/index.xhtml) - $(call install-data,$(out_base)/cxx-tree-manual.ps,$(install_doc_dir)/xsd/$(path)/cxx-tree-manual.ps) - $(call install-data,$(out_base)/cxx-tree-manual.pdf,$(install_doc_dir)/xsd/$(path)/cxx-tree-manual.pdf) - -$(dist): $(out_base)/cxx-tree-manual.ps $(out_base)/cxx-tree-manual.pdf - $(call install-data,$(src_base)/index.xhtml,$(dist_prefix)/$(path)/index.xhtml) - $(call install-data,$(out_base)/cxx-tree-manual.ps,$(dist_prefix)/$(path)/cxx-tree-manual.ps) - $(call install-data,$(out_base)/cxx-tree-manual.pdf,$(dist_prefix)/$(path)/cxx-tree-manual.pdf) - -$(dist-win): $(dist) - - -# Clean -# -$(clean): -ifneq ($(xsd_clean_gen),n) - $(call message,rm $$1,rm -f $$1,$(out_base)/cxx-tree-manual.ps) - $(call message,rm $$1,rm -f $$1,$(out_base)/cxx-tree-manual.pdf) -endif - -# How to. -# -$(call include,$(bld_root)/install.make) diff --git a/doc/cxx/tree/manual/manual.html2ps b/doc/cxx/tree/manual/manual.html2ps deleted file mode 100644 index a4b4491..0000000 --- a/doc/cxx/tree/manual/manual.html2ps +++ /dev/null @@ -1,66 +0,0 @@ -@html2ps { - option { - toc: hb; - colour: 1; - hyphenate: 1; - titlepage: 1; - } - - datefmt: "%B %Y"; - - titlepage { - content: " -
-

C++/Tree Mapping User Manual

-

 

-

 

-

 

-

 

-

 

-

 

-

 

-
-

Revision $[revision]     $D

-

Copyright © 2009-2020 Code Synthesis Tools CC.

- -

Permission is granted to copy, distribute and/or modify this - document under the terms of the - GNU Free - Documentation License, version 1.2; with no Invariant Sections, - no Front-Cover Texts and no Back-Cover Texts. -

- -

This document is available in the following formats: - XHTML, - PDF, and - PostScript.

"; - } - - toc { - indent: 2em; - } - - header { - odd-right: $H; - even-left: $H; - } - - footer { - odd-left: $D; - odd-center: $T, v$[revision]; - odd-right: $N; - - even-left: $N; - even-center: $T, v$[revision]; - even-right: $D; - } -} - -body { - font-size: 12pt; - text-align: justify; -} - -pre { - font-size: 10pt; -} diff --git a/doc/cxx/tree/reference/footer.html b/doc/cxx/tree/reference/footer.html deleted file mode 100644 index 53291d6..0000000 --- a/doc/cxx/tree/reference/footer.html +++ /dev/null @@ -1,6 +0,0 @@ -
-
- Copyright © 2009-2020 Code Synthesis Tools CC. -
- - diff --git a/doc/cxx/tree/reference/libxsd.doxygen b/doc/cxx/tree/reference/libxsd.doxygen deleted file mode 100644 index b98074a..0000000 --- a/doc/cxx/tree/reference/libxsd.doxygen +++ /dev/null @@ -1,1291 +0,0 @@ -# Doxyfile 1.5.4 - -# This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project -# -# All text after a hash (#) is considered a comment and will be ignored -# The format is: -# TAG = value [value, ...] -# For lists items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (" ") - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- - -# This tag specifies the encoding used for all characters in the config file that -# follow. The default is UTF-8 which is also the encoding used for all text before -# the first occurrence of this tag. Doxygen uses libiconv (or the iconv built into -# libc) for the transcoding. See http://www.gnu.org/software/libiconv for the list of -# possible encodings. - -DOXYFILE_ENCODING = UTF-8 - -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded -# by quotes) that should identify the project. - -PROJECT_NAME = "C++/Tree Mapping Runtime Library" - -# The PROJECT_NUMBER tag can be used to enter a project or revision number. -# This could be handy for archiving the generated documentation or -# if some version control system is used. - -PROJECT_NUMBER = - -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) -# base path where the generated documentation will be put. -# If a relative path is entered, it will be relative to the location -# where doxygen was started. If left blank the current directory will be used. - -OUTPUT_DIRECTORY = - -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create -# 4096 sub-directories (in 2 levels) under the output directory of each output -# format and will distribute the generated files over these directories. -# Enabling this option can be useful when feeding doxygen a huge amount of -# source files, where putting all generated files in the same directory would -# otherwise cause performance problems for the file system. - -CREATE_SUBDIRS = NO - -# The OUTPUT_LANGUAGE tag is used to specify the language in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all constant output in the proper language. -# The default language is English, other supported languages are: -# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, -# Croatian, Czech, Danish, Dutch, Finnish, French, German, Greek, Hungarian, -# Italian, Japanese, Japanese-en (Japanese with English messages), Korean, -# Korean-en, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Russian, -# Serbian, Slovak, Slovene, Spanish, Swedish, and Ukrainian. - -OUTPUT_LANGUAGE = English - -# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will -# include brief member descriptions after the members that are listed in -# the file and class documentation (similar to JavaDoc). -# Set to NO to disable this. - -BRIEF_MEMBER_DESC = YES - -# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend -# the brief description of a member or function before the detailed description. -# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the -# brief descriptions will be completely suppressed. - -REPEAT_BRIEF = YES - -# This tag implements a quasi-intelligent brief description abbreviator -# that is used to form the text in various listings. Each string -# in this list, if found as the leading text of the brief description, will be -# stripped from the text and the result after processing the whole list, is -# used as the annotated text. Otherwise, the brief description is used as-is. -# If left blank, the following values are used ("$name" is automatically -# replaced with the name of the entity): "The $name class" "The $name widget" -# "The $name file" "is" "provides" "specifies" "contains" -# "represents" "a" "an" "the" - -ABBREVIATE_BRIEF = - -# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# Doxygen will generate a detailed section even if there is only a brief -# description. - -ALWAYS_DETAILED_SEC = NO - -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all -# inherited members of a class in the documentation of that class as if those -# members were ordinary class members. Constructors, destructors and assignment -# operators of the base classes will not be shown. - -INLINE_INHERITED_MEMB = NO - -# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full -# path before files name in the file list and in the header files. If set -# to NO the shortest path that makes the file name unique will be used. - -FULL_PATH_NAMES = NO - -# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag -# can be used to strip a user-defined part of the path. Stripping is -# only done if one of the specified strings matches the left-hand part of -# the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the -# path to strip. - -STRIP_FROM_PATH = - -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of -# the path mentioned in the documentation of a class, which tells -# the reader which header file to include in order to use a class. -# If left blank only the name of the header file containing the class -# definition is used. Otherwise one should specify the include paths that -# are normally passed to the compiler using the -I flag. - -STRIP_FROM_INC_PATH = - -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter -# (but less readable) file names. This can be useful is your file systems -# doesn't support long names like on DOS, Mac, or CD-ROM. - -SHORT_NAMES = NO - -# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen -# will interpret the first line (until the first dot) of a JavaDoc-style -# comment as the brief description. If set to NO, the JavaDoc -# comments will behave just like regular Qt-style comments -# (thus requiring an explicit @brief command for a brief description.) - -JAVADOC_AUTOBRIEF = NO - -# If the QT_AUTOBRIEF tag is set to YES then Doxygen will -# interpret the first line (until the first dot) of a Qt-style -# comment as the brief description. If set to NO, the comments -# will behave just like regular Qt-style comments (thus requiring -# an explicit \brief command for a brief description.) - -QT_AUTOBRIEF = NO - -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen -# treat a multi-line C++ special comment block (i.e. a block of //! or /// -# comments) as a brief description. This used to be the default behaviour. -# The new default is to treat a multi-line C++ comment block as a detailed -# description. Set this tag to YES if you prefer the old behaviour instead. - -MULTILINE_CPP_IS_BRIEF = NO - -# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented -# member inherits the documentation from any documented member that it -# re-implements. - -INHERIT_DOCS = YES - -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce -# a new page for each member. If set to NO, the documentation of a member will -# be part of the file/class/namespace that contains it. - -SEPARATE_MEMBER_PAGES = NO - -# The TAB_SIZE tag can be used to set the number of spaces in a tab. -# Doxygen uses this value to replace tabs by spaces in code fragments. - -TAB_SIZE = 8 - -# This tag can be used to specify a number of aliases that acts -# as commands in the documentation. An alias has the form "name=value". -# For example adding "sideeffect=\par Side Effects:\n" will allow you to -# put the command \sideeffect (or @sideeffect) in the documentation, which -# will result in a user-defined paragraph with heading "Side Effects:". -# You can put \n's in the value part of an alias to insert newlines. - -ALIASES = - -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C -# sources only. Doxygen will then generate output that is more tailored for C. -# For instance, some of the names that are used will be different. The list -# of all members will be omitted, etc. - -OPTIMIZE_OUTPUT_FOR_C = NO - -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java -# sources only. Doxygen will then generate output that is more tailored for Java. -# For instance, namespaces will be presented as packages, qualified scopes -# will look different, etc. - -OPTIMIZE_OUTPUT_JAVA = NO - -# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want to -# include (a tag file for) the STL sources as input, then you should -# set this tag to YES in order to let doxygen match functions declarations and -# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. -# func(std::string) {}). This also make the inheritance and collaboration -# diagrams that involve STL classes more complete and accurate. - -BUILTIN_STL_SUPPORT = YES - -# If you use Microsoft's C++/CLI language, you should set this option to YES to -# enable parsing support. - -CPP_CLI_SUPPORT = NO - -# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. -# Doxygen will parse them like normal C++ but will assume all classes use public -# instead of private inheritance when no explicit protection keyword is present. - -SIP_SUPPORT = NO - -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default -# all members of a group must be documented explicitly. - -DISTRIBUTE_GROUP_DOC = NO - -# Set the SUBGROUPING tag to YES (the default) to allow class member groups of -# the same type (for instance a group of public functions) to be put as a -# subgroup of that type (e.g. under the Public Functions section). Set it to -# NO to prevent subgrouping. Alternatively, this can be done per class using -# the \nosubgrouping command. - -SUBGROUPING = YES - -# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct (or union) is -# documented as struct with the name of the typedef. So -# typedef struct TypeS {} TypeT, will appear in the documentation as a struct -# with name TypeT. When disabled the typedef will appear as a member of a file, -# namespace, or class. And the struct will be named TypeS. This can typically -# be useful for C code where the coding convention is that all structs are -# typedef'ed and only the typedef is referenced never the struct's name. - -TYPEDEF_HIDES_STRUCT = NO - -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- - -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. -# Private class members and static file members will be hidden unless -# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES - -EXTRACT_ALL = NO - -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class -# will be included in the documentation. - -EXTRACT_PRIVATE = NO - -# If the EXTRACT_STATIC tag is set to YES all static members of a file -# will be included in the documentation. - -EXTRACT_STATIC = NO - -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) -# defined locally in source files will be included in the documentation. -# If set to NO only classes defined in header files are included. - -EXTRACT_LOCAL_CLASSES = YES - -# This flag is only useful for Objective-C code. When set to YES local -# methods, which are defined in the implementation section but not in -# the interface are included in the documentation. -# If set to NO (the default) only methods in the interface are included. - -EXTRACT_LOCAL_METHODS = NO - -# If this flag is set to YES, the members of anonymous namespaces will be extracted -# and appear in the documentation as a namespace called 'anonymous_namespace{file}', -# where file will be replaced with the base name of the file that contains the anonymous -# namespace. By default anonymous namespace are hidden. - -EXTRACT_ANON_NSPACES = NO - -# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all -# undocumented members of documented classes, files or namespaces. -# If set to NO (the default) these members will be included in the -# various overviews, but no documentation section is generated. -# This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_MEMBERS = NO - -# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. -# If set to NO (the default) these classes will be included in the various -# overviews. This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_CLASSES = NO - -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all -# friend (class|struct|union) declarations. -# If set to NO (the default) these declarations will be included in the -# documentation. - -HIDE_FRIEND_COMPOUNDS = NO - -# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any -# documentation blocks found inside the body of a function. -# If set to NO (the default) these blocks will be appended to the -# function's detailed documentation block. - -HIDE_IN_BODY_DOCS = NO - -# The INTERNAL_DOCS tag determines if documentation -# that is typed after a \internal command is included. If the tag is set -# to NO (the default) then the documentation will be excluded. -# Set it to YES to include the internal documentation. - -INTERNAL_DOCS = NO - -# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate -# file names in lower-case letters. If set to YES upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. - -CASE_SENSE_NAMES = YES - -# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen -# will show members with their full class and namespace scopes in the -# documentation. If set to YES the scope will be hidden. - -HIDE_SCOPE_NAMES = YES - -# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen -# will put a list of the files that are included by a file in the documentation -# of that file. - -SHOW_INCLUDE_FILES = NO - -# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] -# is inserted in the documentation for inline members. - -INLINE_INFO = YES - -# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen -# will sort the (detailed) documentation of file and class members -# alphabetically by member name. If set to NO the members will appear in -# declaration order. - -SORT_MEMBER_DOCS = NO - -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the -# brief documentation of file, namespace and class members alphabetically -# by member name. If set to NO (the default) the members will appear in -# declaration order. - -SORT_BRIEF_DOCS = NO - -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be -# sorted by fully-qualified names, including namespaces. If set to -# NO (the default), the class list will be sorted only by class name, -# not including the namespace part. -# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the -# alphabetical list. - -SORT_BY_SCOPE_NAME = NO - -# The GENERATE_TODOLIST tag can be used to enable (YES) or -# disable (NO) the todo list. This list is created by putting \todo -# commands in the documentation. - -GENERATE_TODOLIST = YES - -# The GENERATE_TESTLIST tag can be used to enable (YES) or -# disable (NO) the test list. This list is created by putting \test -# commands in the documentation. - -GENERATE_TESTLIST = YES - -# The GENERATE_BUGLIST tag can be used to enable (YES) or -# disable (NO) the bug list. This list is created by putting \bug -# commands in the documentation. - -GENERATE_BUGLIST = YES - -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or -# disable (NO) the deprecated list. This list is created by putting -# \deprecated commands in the documentation. - -GENERATE_DEPRECATEDLIST= YES - -# The ENABLED_SECTIONS tag can be used to enable conditional -# documentation sections, marked by \if sectionname ... \endif. - -ENABLED_SECTIONS = - -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines -# the initial value of a variable or define consists of for it to appear in -# the documentation. If the initializer consists of more lines than specified -# here it will be hidden. Use a value of 0 to hide initializers completely. -# The appearance of the initializer of individual variables and defines in the -# documentation can be controlled using \showinitializer or \hideinitializer -# command in the documentation regardless of this setting. - -MAX_INITIALIZER_LINES = 30 - -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated -# at the bottom of the documentation of classes and structs. If set to YES the -# list will mention the files that were used to generate the documentation. - -SHOW_USED_FILES = YES - -# The FILE_VERSION_FILTER tag can be used to specify a program or script that -# doxygen should invoke to get the current version for each file (typically from the -# version control system). Doxygen will invoke the program by executing (via -# popen()) the command , where is the value of -# the FILE_VERSION_FILTER tag, and is the name of an input file -# provided by doxygen. Whatever the program writes to standard output -# is used as the file version. See the manual for examples. - -FILE_VERSION_FILTER = - -#--------------------------------------------------------------------------- -# configuration options related to warning and progress messages -#--------------------------------------------------------------------------- - -# The QUIET tag can be used to turn on/off the messages that are generated -# by doxygen. Possible values are YES and NO. If left blank NO is used. - -QUIET = NO - -# The WARNINGS tag can be used to turn on/off the warning messages that are -# generated by doxygen. Possible values are YES and NO. If left blank -# NO is used. - -WARNINGS = YES - -# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings -# for undocumented members. If EXTRACT_ALL is set to YES then this flag will -# automatically be disabled. - -WARN_IF_UNDOCUMENTED = YES - -# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some -# parameters in a documented function, or documenting parameters that -# don't exist or using markup commands wrongly. - -WARN_IF_DOC_ERROR = YES - -# This WARN_NO_PARAMDOC option can be abled to get warnings for -# functions that are documented, but have no documentation for their parameters -# or return value. If set to NO (the default) doxygen will only warn about -# wrong or incomplete parameter documentation, but not about the absence of -# documentation. - -WARN_NO_PARAMDOC = NO - -# The WARN_FORMAT tag determines the format of the warning messages that -# doxygen can produce. The string should contain the $file, $line, and $text -# tags, which will be replaced by the file and line number from which the -# warning originated and the warning text. Optionally the format may contain -# $version, which will be replaced by the version of the file (if it could -# be obtained via FILE_VERSION_FILTER) - -WARN_FORMAT = "$file:$line: $text" - -# The WARN_LOGFILE tag can be used to specify a file to which warning -# and error messages should be written. If left blank the output is written -# to stderr. - -WARN_LOGFILE = - -#--------------------------------------------------------------------------- -# configuration options related to the input files -#--------------------------------------------------------------------------- - -# The INPUT tag can be used to specify the files and/or directories that contain -# documented source files. You may enter file names like "myfile.cpp" or -# directories like "/usr/src/myproject". Separate the files or directories -# with spaces. - -INPUT = \ -../../../../libxsd/xsd/cxx/tree/buffer.hxx \ -../../../../libxsd/xsd/cxx/tree/types.hxx \ -../../../../libxsd/xsd/cxx/tree/date-time.hxx \ -../../../../libxsd/xsd/cxx/tree/elements.hxx \ -../../../../libxsd/xsd/cxx/tree/element-map.hxx \ -../../../../libxsd/xsd/cxx/tree/exceptions.hxx - -# This tag can be used to specify the character encoding of the source files that -# doxygen parses. Internally doxygen uses the UTF-8 encoding, which is also the default -# input encoding. Doxygen uses libiconv (or the iconv built into libc) for the transcoding. -# See http://www.gnu.org/software/libiconv for the list of possible encodings. - -INPUT_ENCODING = UTF-8 - -# If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank the following patterns are tested: -# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx -# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 - -FILE_PATTERNS = - -# The RECURSIVE tag can be used to turn specify whether or not subdirectories -# should be searched for input files as well. Possible values are YES and NO. -# If left blank NO is used. - -RECURSIVE = NO - -# The EXCLUDE tag can be used to specify files and/or directories that should -# excluded from the INPUT source files. This way you can easily exclude a -# subdirectory from a directory tree whose root is specified with the INPUT tag. - -EXCLUDE = - -# The EXCLUDE_SYMLINKS tag can be used select whether or not files or -# directories that are symbolic links (a Unix filesystem feature) are excluded -# from the input. - -EXCLUDE_SYMLINKS = NO - -# If the value of the INPUT tag contains directories, you can use the -# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude -# certain files from those directories. Note that the wildcards are matched -# against the file with absolute path, so to exclude all test directories -# for example use the pattern */test/* - -EXCLUDE_PATTERNS = - -# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names -# (namespaces, classes, functions, etc.) that should be excluded from the output. -# The symbol name can be a fully qualified name, a word, or if the wildcard * is used, -# a substring. Examples: ANamespace, AClass, AClass::ANamespace, ANamespace::*Test - -EXCLUDE_SYMBOLS = - -# The EXAMPLE_PATH tag can be used to specify one or more files or -# directories that contain example code fragments that are included (see -# the \include command). - -EXAMPLE_PATH = - -# If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank all files are included. - -EXAMPLE_PATTERNS = - -# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude -# commands irrespective of the value of the RECURSIVE tag. -# Possible values are YES and NO. If left blank NO is used. - -EXAMPLE_RECURSIVE = NO - -# The IMAGE_PATH tag can be used to specify one or more files or -# directories that contain image that are included in the documentation (see -# the \image command). - -IMAGE_PATH = - -# The INPUT_FILTER tag can be used to specify a program that doxygen should -# invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command , where -# is the value of the INPUT_FILTER tag, and is the name of an -# input file. Doxygen will then use the output that the filter program writes -# to standard output. If FILTER_PATTERNS is specified, this tag will be -# ignored. - -INPUT_FILTER = - -# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. The filters are a list of the form: -# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further -# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER -# is applied to all files. - -FILTER_PATTERNS = - -# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will be used to filter the input files when producing source -# files to browse (i.e. when SOURCE_BROWSER is set to YES). - -FILTER_SOURCE_FILES = NO - -#--------------------------------------------------------------------------- -# configuration options related to source browsing -#--------------------------------------------------------------------------- - -# If the SOURCE_BROWSER tag is set to YES then a list of source files will -# be generated. Documented entities will be cross-referenced with these sources. -# Note: To get rid of all source code in the generated output, make sure also -# VERBATIM_HEADERS is set to NO. If you have enabled CALL_GRAPH or CALLER_GRAPH -# then you must also enable this option. If you don't then doxygen will produce -# a warning and turn it on anyway - -SOURCE_BROWSER = NO - -# Setting the INLINE_SOURCES tag to YES will include the body -# of functions and classes directly in the documentation. - -INLINE_SOURCES = NO - -# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct -# doxygen to hide any special comment blocks from generated source code -# fragments. Normal C and C++ comments will always remain visible. - -STRIP_CODE_COMMENTS = YES - -# If the REFERENCED_BY_RELATION tag is set to YES (the default) -# then for each documented function all documented -# functions referencing it will be listed. - -REFERENCED_BY_RELATION = YES - -# If the REFERENCES_RELATION tag is set to YES (the default) -# then for each documented function all documented entities -# called/used by that function will be listed. - -REFERENCES_RELATION = YES - -# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) -# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from -# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will -# link to the source code. Otherwise they will link to the documentstion. - -REFERENCES_LINK_SOURCE = YES - -# If the USE_HTAGS tag is set to YES then the references to source code -# will point to the HTML generated by the htags(1) tool instead of doxygen -# built-in source browser. The htags tool is part of GNU's global source -# tagging system (see http://www.gnu.org/software/global/global.html). You -# will need version 4.8.6 or higher. - -USE_HTAGS = NO - -# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen -# will generate a verbatim copy of the header file for each class for -# which an include is specified. Set to NO to disable this. - -VERBATIM_HEADERS = YES - -#--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- - -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index -# of all compounds will be generated. Enable this if the project -# contains a lot of classes, structs, unions or interfaces. - -ALPHABETICAL_INDEX = NO - -# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then -# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns -# in which this list will be split (can be a number in the range [1..20]) - -COLS_IN_ALPHA_INDEX = 5 - -# In case all classes in a project start with a common prefix, all -# classes will be put under the same header in the alphabetical index. -# The IGNORE_PREFIX tag can be used to specify one or more prefixes that -# should be ignored while generating the index headers. - -IGNORE_PREFIX = - -#--------------------------------------------------------------------------- -# configuration options related to the HTML output -#--------------------------------------------------------------------------- - -# If the GENERATE_HTML tag is set to YES (the default) Doxygen will -# generate HTML output. - -GENERATE_HTML = YES - -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `html' will be used as the default path. - -HTML_OUTPUT = html - -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for -# each generated HTML page (for example: .htm,.php,.asp). If it is left blank -# doxygen will generate files with .html extension. - -HTML_FILE_EXTENSION = .html - -# The HTML_HEADER tag can be used to specify a personal HTML header for -# each generated HTML page. If it is left blank doxygen will generate a -# standard header. - -HTML_HEADER = - -# The HTML_FOOTER tag can be used to specify a personal HTML footer for -# each generated HTML page. If it is left blank doxygen will generate a -# standard footer. - -HTML_FOOTER = footer.html - -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading -# style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own -# stylesheet in the HTML output directory as well, or it will be erased! - -HTML_STYLESHEET = - -# If the GENERATE_HTMLHELP tag is set to YES, additional index files -# will be generated that can be used as input for tools like the -# Microsoft HTML help workshop to generate a compressed HTML help file (.chm) -# of the generated HTML documentation. - -GENERATE_HTMLHELP = NO - -# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML -# documentation will contain sections that can be hidden and shown after the -# page has loaded. For this to work a browser that supports -# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox -# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). - -HTML_DYNAMIC_SECTIONS = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can -# be used to specify the file name of the resulting .chm file. You -# can add a path in front of the file if the result should not be -# written to the html output directory. - -CHM_FILE = - -# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can -# be used to specify the location (absolute path including file name) of -# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run -# the HTML help compiler on the generated index.hhp. - -HHC_LOCATION = - -# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag -# controls if a separate .chi index file is generated (YES) or that -# it should be included in the master .chm file (NO). - -GENERATE_CHI = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag -# controls whether a binary table of contents is generated (YES) or a -# normal table of contents (NO) in the .chm file. - -BINARY_TOC = NO - -# The TOC_EXPAND flag can be set to YES to add extra items for group members -# to the contents of the HTML help documentation and to the tree view. - -TOC_EXPAND = NO - -# The DISABLE_INDEX tag can be used to turn on/off the condensed index at -# top of each HTML page. The value NO (the default) enables the index and -# the value YES disables it. - -DISABLE_INDEX = NO - -# This tag can be used to set the number of enum values (range [1..20]) -# that doxygen will group on one line in the generated HTML documentation. - -ENUM_VALUES_PER_LINE = 4 - -# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be -# generated containing a tree-like index structure (just like the one that -# is generated for HTML Help). For this to work a browser that supports -# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, -# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are -# probably better off using the HTML help feature. - -GENERATE_TREEVIEW = NO - -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be -# used to set the initial width (in pixels) of the frame in which the tree -# is shown. - -TREEVIEW_WIDTH = 250 - -#--------------------------------------------------------------------------- -# configuration options related to the LaTeX output -#--------------------------------------------------------------------------- - -# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will -# generate Latex output. - -GENERATE_LATEX = NO - -# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `latex' will be used as the default path. - -LATEX_OUTPUT = latex - -# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be -# invoked. If left blank `latex' will be used as the default command name. - -LATEX_CMD_NAME = latex - -# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to -# generate index for LaTeX. If left blank `makeindex' will be used as the -# default command name. - -MAKEINDEX_CMD_NAME = makeindex - -# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact -# LaTeX documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_LATEX = NO - -# The PAPER_TYPE tag can be used to set the paper type that is used -# by the printer. Possible values are: a4, a4wide, letter, legal and -# executive. If left blank a4wide will be used. - -PAPER_TYPE = a4wide - -# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX -# packages that should be included in the LaTeX output. - -EXTRA_PACKAGES = - -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for -# the generated latex document. The header should contain everything until -# the first chapter. If it is left blank doxygen will generate a -# standard header. Notice: only use this tag if you know what you are doing! - -LATEX_HEADER = - -# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated -# is prepared for conversion to pdf (using ps2pdf). The pdf file will -# contain links (just like the HTML output) instead of page references -# This makes the output suitable for online browsing using a pdf viewer. - -PDF_HYPERLINKS = NO - -# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of -# plain latex in the generated Makefile. Set this option to YES to get a -# higher quality PDF documentation. - -USE_PDFLATEX = NO - -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. -# command to the generated LaTeX files. This will instruct LaTeX to keep -# running if errors occur, instead of asking the user for help. -# This option is also used when generating formulas in HTML. - -LATEX_BATCHMODE = NO - -# If LATEX_HIDE_INDICES is set to YES then doxygen will not -# include the index chapters (such as File Index, Compound Index, etc.) -# in the output. - -LATEX_HIDE_INDICES = NO - -#--------------------------------------------------------------------------- -# configuration options related to the RTF output -#--------------------------------------------------------------------------- - -# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output -# The RTF output is optimized for Word 97 and may not look very pretty with -# other RTF readers or editors. - -GENERATE_RTF = NO - -# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `rtf' will be used as the default path. - -RTF_OUTPUT = rtf - -# If the COMPACT_RTF tag is set to YES Doxygen generates more compact -# RTF documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_RTF = NO - -# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated -# will contain hyperlink fields. The RTF file will -# contain links (just like the HTML output) instead of page references. -# This makes the output suitable for online browsing using WORD or other -# programs which support those fields. -# Note: wordpad (write) and others do not support links. - -RTF_HYPERLINKS = NO - -# Load stylesheet definitions from file. Syntax is similar to doxygen's -# config file, i.e. a series of assignments. You only have to provide -# replacements, missing definitions are set to their default value. - -RTF_STYLESHEET_FILE = - -# Set optional variables used in the generation of an rtf document. -# Syntax is similar to doxygen's config file. - -RTF_EXTENSIONS_FILE = - -#--------------------------------------------------------------------------- -# configuration options related to the man page output -#--------------------------------------------------------------------------- - -# If the GENERATE_MAN tag is set to YES (the default) Doxygen will -# generate man pages - -GENERATE_MAN = NO - -# The MAN_OUTPUT tag is used to specify where the man pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `man' will be used as the default path. - -MAN_OUTPUT = man - -# The MAN_EXTENSION tag determines the extension that is added to -# the generated man pages (default is the subroutine's section .3) - -MAN_EXTENSION = .3 - -# If the MAN_LINKS tag is set to YES and Doxygen generates man output, -# then it will generate one additional man file for each entity -# documented in the real man page(s). These additional files -# only source the real man page, but without them the man command -# would be unable to find the correct page. The default is NO. - -MAN_LINKS = NO - -#--------------------------------------------------------------------------- -# configuration options related to the XML output -#--------------------------------------------------------------------------- - -# If the GENERATE_XML tag is set to YES Doxygen will -# generate an XML file that captures the structure of -# the code including all documentation. - -GENERATE_XML = NO - -# The XML_OUTPUT tag is used to specify where the XML pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `xml' will be used as the default path. - -XML_OUTPUT = xml - -# If the XML_PROGRAMLISTING tag is set to YES Doxygen will -# dump the program listings (including syntax highlighting -# and cross-referencing information) to the XML output. Note that -# enabling this will significantly increase the size of the XML output. - -XML_PROGRAMLISTING = YES - -#--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output -#--------------------------------------------------------------------------- - -# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will -# generate an AutoGen Definitions (see autogen.sf.net) file -# that captures the structure of the code including all -# documentation. Note that this feature is still experimental -# and incomplete at the moment. - -GENERATE_AUTOGEN_DEF = NO - -#--------------------------------------------------------------------------- -# configuration options related to the Perl module output -#--------------------------------------------------------------------------- - -# If the GENERATE_PERLMOD tag is set to YES Doxygen will -# generate a Perl module file that captures the structure of -# the code including all documentation. Note that this -# feature is still experimental and incomplete at the -# moment. - -GENERATE_PERLMOD = NO - -# If the PERLMOD_LATEX tag is set to YES Doxygen will generate -# the necessary Makefile rules, Perl scripts and LaTeX code to be able -# to generate PDF and DVI output from the Perl module output. - -PERLMOD_LATEX = NO - -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be -# nicely formatted so it can be parsed by a human reader. This is useful -# if you want to understand what is going on. On the other hand, if this -# tag is set to NO the size of the Perl module output will be much smaller -# and Perl will parse it just the same. - -PERLMOD_PRETTY = YES - -# The names of the make variables in the generated doxyrules.make file -# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. -# This is useful so different doxyrules.make files included by the same -# Makefile don't overwrite each other's variables. - -PERLMOD_MAKEVAR_PREFIX = - -#--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- - -# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will -# evaluate all C-preprocessor directives found in the sources and include -# files. - -ENABLE_PREPROCESSING = YES - -# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro -# names in the source code. If set to NO (the default) only conditional -# compilation will be performed. Macro expansion can be done in a controlled -# way by setting EXPAND_ONLY_PREDEF to YES. - -MACRO_EXPANSION = YES - -# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES -# then the macro expansion is limited to the macros specified with the -# PREDEFINED and EXPAND_AS_DEFINED tags. - -EXPAND_ONLY_PREDEF = YES - -# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files -# in the INCLUDE_PATH (see below) will be search if a #include is found. - -SEARCH_INCLUDES = YES - -# The INCLUDE_PATH tag can be used to specify one or more directories that -# contain include files that are not input files but should be processed by -# the preprocessor. - -INCLUDE_PATH = - -# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard -# patterns (like *.h and *.hpp) to filter out the header-files in the -# directories. If left blank, the patterns specified with FILE_PATTERNS will -# be used. - -INCLUDE_FILE_PATTERNS = - -# The PREDEFINED tag can be used to specify one or more macro names that -# are defined before the preprocessor is started (similar to the -D option of -# gcc). The argument of the tag is a list of macros of the form: name -# or name=definition (no spaces). If the definition and the = are -# omitted =1 is assumed. To prevent a macro definition from being -# undefined via #undef or recursively expanded use the := operator -# instead of the = operator. - -# C++98 version. -# -PREDEFINED = XSD_AUTO_PTR=std::auto_ptr - -# C++11 version. -# -# PREDEFINED = XSD_AUTO_PTR=std::unique_ptr - -# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then -# this tag can be used to specify a list of macro names that should be expanded. -# The macro definition that is found in the sources will be used. -# Use the PREDEFINED tag if you want to use a different macro definition. - -EXPAND_AS_DEFINED = - -# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then -# doxygen's preprocessor will remove all function-like macros that are alone -# on a line, have an all uppercase name, and do not end with a semicolon. Such -# function macros are typically used for boiler-plate code, and will confuse -# the parser if not removed. - -SKIP_FUNCTION_MACROS = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to external references -#--------------------------------------------------------------------------- - -# The TAGFILES option can be used to specify one or more tagfiles. -# Optionally an initial location of the external documentation -# can be added for each tagfile. The format of a tag file without -# this location is as follows: -# TAGFILES = file1 file2 ... -# Adding location for the tag files is done as follows: -# TAGFILES = file1=loc1 "file2 = loc2" ... -# where "loc1" and "loc2" can be relative or absolute paths or -# URLs. If a location is present for each tag, the installdox tool -# does not have to be run to correct the links. -# Note that each tag file must have a unique name -# (where the name does NOT include the path) -# If a tag file is not located in the directory in which doxygen -# is run, you must also specify the path to the tagfile here. - -TAGFILES = - -# When a file name is specified after GENERATE_TAGFILE, doxygen will create -# a tag file that is based on the input files it reads. - -GENERATE_TAGFILE = libxsd.doxytag - -# If the ALLEXTERNALS tag is set to YES all external classes will be listed -# in the class index. If set to NO only the inherited external classes -# will be listed. - -ALLEXTERNALS = NO - -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will -# be listed. - -EXTERNAL_GROUPS = YES - -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of `which perl'). - -PERL_PATH = /usr/bin/perl - -#--------------------------------------------------------------------------- -# Configuration options related to the dot tool -#--------------------------------------------------------------------------- - -# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will -# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base -# or super classes. Setting the tag to NO turns the diagrams off. Note that -# this option is superseded by the HAVE_DOT option below. This is only a -# fallback. It is recommended to install and use dot, since it yields more -# powerful graphs. - -CLASS_DIAGRAMS = YES - -# You can define message sequence charts within doxygen comments using the \msc -# command. Doxygen will then run the mscgen tool (see http://www.mcternan.me.uk/mscgen/) to -# produce the chart and insert it in the documentation. The MSCGEN_PATH tag allows you to -# specify the directory where the mscgen tool resides. If left empty the tool is assumed to -# be found in the default search path. - -MSCGEN_PATH = - -# If set to YES, the inheritance and collaboration graphs will hide -# inheritance and usage relations if the target is undocumented -# or is not a class. - -HIDE_UNDOC_RELATIONS = YES - -# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is -# available from the path. This tool is part of Graphviz, a graph visualization -# toolkit from AT&T and Lucent Bell Labs. The other options in this section -# have no effect if this option is set to NO (the default) - -HAVE_DOT = NO - -# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect inheritance relations. Setting this tag to YES will force the -# the CLASS_DIAGRAMS tag to NO. - -CLASS_GRAPH = YES - -# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect implementation dependencies (inheritance, containment, and -# class references variables) of the class with other documented classes. - -COLLABORATION_GRAPH = YES - -# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for groups, showing the direct groups dependencies - -GROUP_GRAPHS = YES - -# If the UML_LOOK tag is set to YES doxygen will generate inheritance and -# collaboration diagrams in a style similar to the OMG's Unified Modeling -# Language. - -UML_LOOK = NO - -# If set to YES, the inheritance and collaboration graphs will show the -# relations between templates and their instances. - -TEMPLATE_RELATIONS = NO - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT -# tags are set to YES then doxygen will generate a graph for each documented -# file showing the direct and indirect include dependencies of the file with -# other documented files. - -INCLUDE_GRAPH = YES - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and -# HAVE_DOT tags are set to YES then doxygen will generate a graph for each -# documented header file showing the documented files that directly or -# indirectly include this file. - -INCLUDED_BY_GRAPH = YES - -# If the CALL_GRAPH, SOURCE_BROWSER and HAVE_DOT tags are set to YES then doxygen will -# generate a call dependency graph for every global function or class method. -# Note that enabling this option will significantly increase the time of a run. -# So in most cases it will be better to enable call graphs for selected -# functions only using the \callgraph command. - -CALL_GRAPH = NO - -# If the CALLER_GRAPH, SOURCE_BROWSER and HAVE_DOT tags are set to YES then doxygen will -# generate a caller dependency graph for every global function or class method. -# Note that enabling this option will significantly increase the time of a run. -# So in most cases it will be better to enable caller graphs for selected -# functions only using the \callergraph command. - -CALLER_GRAPH = NO - -# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen -# will graphical hierarchy of all classes instead of a textual one. - -GRAPHICAL_HIERARCHY = YES - -# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES -# then doxygen will show the dependencies a directory has on other directories -# in a graphical way. The dependency relations are determined by the #include -# relations between the files in the directories. - -DIRECTORY_GRAPH = YES - -# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. Possible values are png, jpg, or gif -# If left blank png will be used. - -DOT_IMAGE_FORMAT = png - -# The tag DOT_PATH can be used to specify the path where the dot tool can be -# found. If left blank, it is assumed the dot tool can be found in the path. - -DOT_PATH = - -# The DOTFILE_DIRS tag can be used to specify one or more directories that -# contain dot files that are included in the documentation (see the -# \dotfile command). - -DOTFILE_DIRS = - -# The MAX_DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of -# nodes that will be shown in the graph. If the number of nodes in a graph -# becomes larger than this value, doxygen will truncate the graph, which is -# visualized by representing a node as a red box. Note that doxygen if the number -# of direct children of the root node in a graph is already larger than -# MAX_DOT_GRAPH_NOTES then the graph will not be shown at all. Also note -# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. - -DOT_GRAPH_MAX_NODES = 50 - -# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the -# graphs generated by dot. A depth value of 3 means that only nodes reachable -# from the root by following a path via at most 3 edges will be shown. Nodes -# that lay further from the root node will be omitted. Note that setting this -# option to 1 or 2 may greatly reduce the computation time needed for large -# code bases. Also note that the size of a graph can be further restricted by -# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. - -MAX_DOT_GRAPH_DEPTH = 0 - -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, which results in a white background. -# Warning: Depending on the platform used, enabling this option may lead to -# badly anti-aliased labels on the edges of a graph (i.e. they become hard to -# read). - -DOT_TRANSPARENT = YES - -# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output -# files in one run (i.e. multiple -o and -T options on the command line). This -# makes dot run faster, but since only newer versions of dot (>1.8.10) -# support this, this feature is disabled by default. - -DOT_MULTI_TARGETS = NO - -# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will -# generate a legend page explaining the meaning of the various boxes and -# arrows in the dot generated graphs. - -GENERATE_LEGEND = YES - -# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will -# remove the intermediate dot files that are used to generate -# the various graphs. - -DOT_CLEANUP = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to the search engine -#--------------------------------------------------------------------------- - -# The SEARCHENGINE tag specifies whether or not a search engine should be -# used. If set to NO the values of all tags below this one will be ignored. - -SEARCHENGINE = NO diff --git a/doc/cxx/tree/reference/makefile b/doc/cxx/tree/reference/makefile deleted file mode 100644 index 5df62c9..0000000 --- a/doc/cxx/tree/reference/makefile +++ /dev/null @@ -1,18 +0,0 @@ -.PHONY: all -all: libxsd.doxytag - -headers := \ -../../../../libxsd/xsd/cxx/tree/buffer.hxx \ -../../../../libxsd/xsd/cxx/tree/types.hxx \ -../../../../libxsd/xsd/cxx/tree/date-time.hxx \ -../../../../libxsd/xsd/cxx/tree/elements.hxx \ -../../../../libxsd/xsd/cxx/tree/exceptions.hxx - -libxsd.doxytag: libxsd.doxygen footer.html $(headers) - doxygen $< - -.PHONY: clean -clean: - rm -f libxsd.doxytag - rm -rf html - diff --git a/doc/default.css b/doc/default.css deleted file mode 100644 index bb3805b..0000000 --- a/doc/default.css +++ /dev/null @@ -1,319 +0,0 @@ -html { - margin : 0; - padding : 0; - background : white; -} - -body { - font-family : "Lucida Grande", Verdana, "Bitstream Vera Sans", sans-serif; - font-weight : normal; - font-size : 13px; - line-height : 19px; - - color : black; - - margin : 0 2em 0 2em; - padding : 0; -} - - -body { - min-width: 40em; -} - -#container { - max-width : 46em; - margin : 0 auto; - padding : 0 1em 0 1em; -} - - - -/* - * Footer - * - */ -#footer { - color : #3a84a7; - - padding : 1em 0 0.5em 0; - - font-size : 10px; - line-height : 15px; - - text-align: center; -} - -#footer a:link, #footer a:visited { - - color:#1d6699; - text-decoration: underline; -} - -#footer a { - margin-left: 0.7em; - margin-right: 0.7em; -} - -#footer p { - padding: 0; - margin: 0.3em 0 0 0; -} - -/* Distribution terms. */ -#footer #terms { - text-align: justify; - - font-size : 110%; - font-family : monospace; - - padding : 1em 0 0.5em 0; -} - - -/* - * Content - * - */ - -#content { - padding : 0em 0.1em 0 1.3em; - margin : 1.4em 0 0 0; -} - -#content p, -#content ol, -#content ul, -#content dl { - text-align: justify; -} - -#content h1 { - margin-left: -0.89em; -} - -a:link { - color:#0536d2; -} - - -/* - * Headings - * - */ - -h1, h2, h3, h4, h5, h6 { - font-weight : 500; -} - -h1 { font-size : 155%; } -h2 { font-size : 130%; } -h3 { font-size : 125%; } -h4 { font-size : 110%; } -h5 { font-size : 106%; } -h6 { font-size : 100%; } - -h1 { margin : 1.8em 0 0.8em 0;} -h2 { margin-top : 1.4em;} -h3 { margin-top : 1em;} - -p.indent { - margin-left : 1.5em; -} - - -/* - * Fix for IE 5.5 table font problem - * - */ - -table { - font-size : 13px; -} - - -/* - * table of content - * - */ - -ul.toc li { - padding : .4em 0em 0em 0em; -} - - -/* Toc links don't need to show when they are visited. */ -.toc a:visited { - color:#0536d2; -} - - -/* - * lists - * - */ - - -/* list of links */ -ul.menu { - list-style-type : none; -} - -ul.menu li { - padding-top : 0.3em; - padding-bottom : 0.3em; -} - - - -/* @@ I should probably use child selector here */ -/* list with multiline list-elements */ -ul.multiline li, ol.multiline li, dl.multiline dd { - padding-top : 0.16em; - padding-bottom : 0.16em; - - font-size : 11px; - line-height : 15px; -} - - - -/* C++ code snippet */ -pre.cxx { - margin-top : 0em; - margin-bottom : 2em; - - margin-left : 1em; -} - - - -/* make code snippet */ -pre.make { - margin-top : 0em; - margin-bottom : 2em; - - margin-left : 1em; -} - - - -/* terminal output */ -pre.term { - margin-top : 0em; - margin-bottom : 2em; - - margin-left : 1em; -} - - -/* Images */ -div.center { - text-align: center; -} - -/* Document info. */ -#docinfo { - margin-top: 4em; - border-top: 1px dashed #000000; - font-size: 70%; -} - - -/* Footnote */ - -#footnote { - margin-top : 2.5em; -} - -#footnote hr, hr.footnote { - margin-left: 0; - margin-bottom: 0.6em; - width: 8em; - border-top: 1px solid #000000; - border-right: none; - border-bottom: none; - border-left: none; - -} - -#footnote ol { - margin-left: 0; - padding-left: 1.45em; -} - -#footnote li { - text-align : left; - font-size : 11px; - line-height : 15px; - - padding : .4em 0 .4em 0; -} - - -/* Normal table with borders, etc. */ - -table.std { - margin: 2em 0 2em 0; - - border-collapse : collapse; - border : 1px solid; - border-color : #000000; - - font-size : 11px; - line-height : 14px; -} - -table.std th, table.std td { - border : 1px solid; - padding : 0.6em 0.8em 0.6em 0.8em; -} - -table.std th { - background : #cde8f6; -} - -table.std td { - text-align: left; -} - - -/* - * "item | description" table. - * - */ - -table.description { - border-style : none; - border-collapse : separate; - border-spacing : 0; - - font-size : 13px; - - margin : 0.6em 0 0.6em 0; - padding : 0 0 0 0; -} - -table.description tr { - padding : 0 0 0 0; - margin : 0 0 0 0; -} - -table.description * td, table.description * th { - border-style : none; - margin : 0 0 0 0; - vertical-align : top; -} - -table.description * th { - font-weight : normal; - padding : 0.4em 1em 0.4em 0; - text-align : left; - white-space : nowrap; - background : none; -} - -table.description * td { - padding : 0.4em 0 0.4em 1em; - text-align : justify; -} diff --git a/doc/doc.sh b/doc/doc.sh deleted file mode 100755 index 36528fd..0000000 --- a/doc/doc.sh +++ /dev/null @@ -1,105 +0,0 @@ -#! /usr/bin/env bash - -version=4.1.0.a11 - -trap 'exit 1' ERR -set -o errtrace # Trap in functions. - -function info () { echo "$*" 1>&2; } -function error () { info "$*"; exit 1; } - -date="$(date +"%B %Y")" -copyright="$(sed -n -re 's%^Copyright \(c\) (.+)\.$%\1%p' ../LICENSE)" - -while [ $# -gt 0 ]; do - case $1 in - --clean) - rm -f xsd.xhtml xsd.1 - rm -f cxx/parser/guide/cxx-parser-guide.{ps,pdf} - rm -f cxx/tree/guide/cxx-tree-guide.{ps,pdf} - rm -f cxx/tree/manual/cxx-tree-manual.{ps,pdf} - exit 0 - ;; - *) - error "unexpected $1" - ;; - esac -done - -ops=(\ --v project="xsd" \ --v version="$version" \ --v date="$date" \ --v copyright="$copyright" \ --I ../xsd \ ---stdout \ ---suppress-undocumented \ ---exclude-base) - -# XHTML -# -# Common options. -# -cli "${ops[@]}" --generate-html --class CXX::options --class options \ ---html-prologue-file xsd-prologue.xhtml \ -../xsd/cxx/options.cli >xsd.xhtml - -# C++/Tree options. -# -cli "${ops[@]}" --generate-html \ ---html-prologue-file xsd-tree-header.xhtml \ -../xsd/cxx/tree/options.cli >>xsd.xhtml - -# C++/Parser options. -# -cli "${ops[@]}" --generate-html \ ---html-prologue-file xsd-parser-header.xhtml \ ---html-epilogue-file xsd-epilogue.xhtml \ -../xsd/cxx/parser/options.cli >>xsd.xhtml - -# MAN -# -# Common options. -# -cli "${ops[@]}" --generate-man --class CXX::options --class options \ ---man-prologue-file xsd-prologue.1 \ -../xsd/cxx/options.cli >xsd.1 - -# C++/Tree options. -# -cli "${ops[@]}" --generate-man \ ---man-prologue-file xsd-tree-header.1 \ -../xsd/cxx/tree/options.cli >>xsd.1 - -# C++/Parser options. -# -cli "${ops[@]}" --generate-man \ ---man-prologue-file xsd-parser-header.1 \ ---man-epilogue-file xsd-epilogue.1 \ -../xsd/cxx/parser/options.cli >>xsd.1 - -# PS, PDF -# -# C++/Parser guide. -# -html2ps -f cxx/parser/guide/guide.html2ps \ --o cxx/parser/guide/cxx-parser-guide.ps cxx/parser/guide/index.xhtml - -ps2pdf14 -dOptimize=true -dEmbedAllFonts=true \ -cxx/parser/guide/cxx-parser-guide.ps cxx/parser/guide/cxx-parser-guide.pdf - -# C++/Tree guide. -# -html2ps -f cxx/tree/guide/guide.html2ps \ --o cxx/tree/guide/cxx-tree-guide.ps cxx/tree/guide/index.xhtml - -ps2pdf14 -dOptimize=true -dEmbedAllFonts=true \ -cxx/tree/guide/cxx-tree-guide.ps cxx/tree/guide/cxx-tree-guide.pdf - -# C++/Tree manual. -# -html2ps -f cxx/tree/manual/manual.html2ps \ --o cxx/tree/manual/cxx-tree-manual.ps cxx/tree/manual/index.xhtml - -ps2pdf14 -dOptimize=true -dEmbedAllFonts=true \ -cxx/tree/manual/cxx-tree-manual.ps cxx/tree/manual/cxx-tree-manual.pdf diff --git a/doc/makefile b/doc/makefile deleted file mode 100644 index fcce4f7..0000000 --- a/doc/makefile +++ /dev/null @@ -1,142 +0,0 @@ -# file : doc/makefile -# license : GNU GPL v2 + exceptions; see accompanying LICENSE file - -include $(dir $(lastword $(MAKEFILE_LIST)))../build/bootstrap.make - -default := $(out_base)/ -install := $(out_base)/.install -dist := $(out_base)/.dist -dist-win := $(out_base)/.dist-win -clean := $(out_base)/.clean - -# Import. -# -$(call import,\ - $(scf_root)/import/cli/stub.make,\ - cli: cli,cli-rules: cli_rules) - -# Build. -# -$(default): \ -$(out_base)/cxx/ \ -$(out_base)/xsd.xhtml \ -$(out_base)/xsd.1 - -# Man/html pages. -# -$(out_base)/xsd.xhtml $(out_base)/xsd.1: cli := $(cli) -$(out_base)/xsd.xhtml $(out_base)/xsd.1: cli_options += -I $(src_root)/xsd - -$(out_base)/xsd.xhtml $(out_base)/xsd.1: \ -$(src_root)/xsd/options.cli \ -$(src_root)/xsd/cxx/options.cli \ -$(src_root)/xsd/cxx/tree/options.cli \ -$(src_root)/xsd/cxx/parser/options.cli - -# Assemble the options from different files in a specific order. -# - -# XHTML -# -$(out_base)/xsd.xhtml: $(src_base)/xsd-prologue.xhtml \ - $(src_base)/xsd-epilogue.xhtml \ - $(src_base)/xsd-tree-header.xhtml \ - $(src_base)/xsd-parser-header.xhtml \ - | $(out_base)/. -# Common options. -# - $(call message,cli-html $$1,$(cli) $(cli_options) --generate-html \ ---stdout --suppress-undocumented --exclude-base --class CXX::options \ ---class options --html-prologue-file $(src_base)/xsd-prologue.xhtml \ -$$1 >$@, $(src_root)/xsd/cxx/options.cli) - -# C++/Tree options. -# - $(call message,cli-html $$1,$(cli) $(cli_options) --generate-html \ ---stdout --suppress-undocumented --exclude-base \ ---html-prologue-file $(src_base)/xsd-tree-header.xhtml \ -$$1 >>$@, $(src_root)/xsd/cxx/tree/options.cli) - -# C++/Parser options. -# - $(call message,cli-html $$1,$(cli) $(cli_options) --generate-html \ ---stdout --suppress-undocumented --exclude-base \ ---html-prologue-file $(src_base)/xsd-parser-header.xhtml \ ---html-epilogue-file $(src_base)/xsd-epilogue.xhtml \ -$$1 >>$@, $(src_root)/xsd/cxx/parser/options.cli) - -# MAN -# -$(out_base)/xsd.1: $(src_base)/xsd-prologue.1 \ - $(src_base)/xsd-epilogue.1 \ - $(src_base)/xsd-tree-header.1 \ - $(src_base)/xsd-parser-header.1 \ - | $(out_base)/. -# Common options. -# - $(call message,cli-man $$1,$(cli) $(cli_options) --generate-man \ ---stdout --suppress-undocumented --exclude-base --class CXX::options \ ---class options --man-prologue-file $(src_base)/xsd-prologue.1 \ -$$1 >$@, $(src_root)/xsd/cxx/options.cli) - -# C++/Tree options. -# - $(call message,cli-man $$1,$(cli) $(cli_options) --generate-man \ ---stdout --suppress-undocumented --exclude-base \ ---man-prologue-file $(src_base)/xsd-tree-header.1 \ -$$1 >>$@, $(src_root)/xsd/cxx/tree/options.cli) - -# C++/Parser options. -# - $(call message,cli-man $$1,$(cli) $(cli_options) --generate-man \ ---stdout --suppress-undocumented --exclude-base \ ---man-prologue-file $(src_base)/xsd-parser-header.1 \ ---man-epilogue-file $(src_base)/xsd-epilogue.1 \ -$$1 >>$@, $(src_root)/xsd/cxx/parser/options.cli) - - -# Install. -# -$(install): $(out_base)/cxx/.install \ - $(out_base)/xsd.xhtml \ - $(out_base)/xsd.1 - $(call install-data,$(src_base)/default.css,$(install_doc_dir)/xsd/default.css) - $(call install-data,$(out_base)/xsd.xhtml,$(install_doc_dir)/xsd/xsd.xhtml) - $(call install-data,$(src_base)/custom-literals.xsd,$(install_doc_dir)/xsd/custom-literals.xsd) - $(call install-data,$(out_base)/xsd.1,$(install_man_dir)/man1/xsd.1) - -# Dist. -# -dist-common := $(out_base)/.dist-common - -$(dist-common): $(out_base)/xsd.xhtml \ - $(out_base)/xsd.1 - $(call install-data,$(src_base)/default.css,$(dist_prefix)/doc/default.css) - $(call install-data,$(out_base)/xsd.xhtml,$(dist_prefix)/doc/xsd.xhtml) - $(call install-data,$(out_base)/xsd.1,$(dist_prefix)/doc/xsd.1) - $(call install-data,$(src_base)/custom-literals.xsd,$(dist_prefix)/doc/custom-literals.xsd) - -$(dist): $(dist-common) $(out_base)/cxx/.dist -$(dist-win): $(dist-common) $(out_base)/cxx/.dist-win - -# Clean. -# -$(clean): $(out_base)/cxx/.clean -ifneq ($(xsd_clean_gen),n) - $(call message,rm $$1,rm -f $$1,$(out_base)/xsd.1) - $(call message,rm $$1,rm -f $$1,$(out_base)/xsd.xhtml) -endif - -# Generated .gitignore. -# -ifeq ($(out_base),$(src_base)) -$(out_base)/xsd.xhtml $(out_base)/xsd.1: | $(out_base)/.gitignore - -$(out_base)/.gitignore: files := xsd.1 xsd.xhtml -$(clean): $(out_base)/.gitignore.clean - -$(call include,$(bld_root)/git/gitignore.make) -endif - -$(call include,$(bld_root)/install.make) -$(call import,$(src_base)/cxx/makefile) diff --git a/doc/xsd-epilogue.1 b/doc/xsd-epilogue.1 deleted file mode 100644 index 192880c..0000000 --- a/doc/xsd-epilogue.1 +++ /dev/null @@ -1,566 +0,0 @@ -\" -\" NAMING CONVENTION -\" - -.SH NAMING CONVENTION -The compiler can be instructed to use a particular naming convention in -the generated code. A number of widely-used conventions can be selected -using the -.B --type-naming -and -.B --function-naming -options. A custom naming convention can be achieved using the -.BR --type-regex , -.BR --accessor-regex , -.BR --one-accessor-regex , -.BR --opt-accessor-regex , -.BR --seq-accessor-regex , -.BR --modifier-regex , -.BR --one-modifier-regex , -.BR --opt-modifier-regex , -.BR --seq-modifier-regex , -.BR --parser-regex , -.BR --serializer-regex , -.BR --const-regex , -.BR --enumerator-regex , -and -.B --element-type-regex -options. - -The -.B --type-naming -option specifies the convention that should be used for naming C++ types. -Possible values for this option are -.B knr -(default), -.BR ucc , -and -.BR java . -The -.B knr -value (stands for K&R) signifies the standard, lower-case naming convention -with the underscore used as a word delimiter, for example: foo, foo_bar. -The -.B ucc -(stands for upper-camel-case) and -.B java -values a synonyms for the same naming convention where the first letter -of each word in the name is capitalized, for example: Foo, FooBar. - -Similarly, the -.B --function-naming -option specifies the convention that should be used for naming C++ functions. -Possible values for this option are -.B knr -(default), -.BR lcc , -and -.BR java . -The -.B knr -value (stands for K&R) signifies the standard, lower-case naming convention -with the underscore used as a word delimiter, for example: foo(), foo_bar(). -The -.B lcc -value (stands for lower-camel-case) signifies a naming convention where the -first letter of each word except the first is capitalized, for example: foo(), -fooBar(). The -.B java -naming convention is similar to the lower-camel-case one except that accessor -functions are prefixed with get, modifier functions are prefixed with set, -parsing functions are prefixed with parse, and serialization functions are -prefixed with serialize, for example: getFoo(), setFooBar(), parseRoot(), -serializeRoot(). - -Note that the naming conventions specified with the -.B --type-naming -and -.B --function-naming -options perform only limited transformations on the -names that come from the schema in the form of type, attribute, and element -names. In other words, to get consistent results, your schemas should follow -a similar naming convention as the one you would like to have in the generated -code. Alternatively, you can use the -.B --*-regex -options (discussed below) to perform further transformations on the names -that come from the schema. - -The -.BR --type-regex , -.BR --accessor-regex , -.BR --one-accessor-regex , -.BR --opt-accessor-regex , -.BR --seq-accessor-regex , -.BR --modifier-regex , -.BR --one-modifier-regex , -.BR --opt-modifier-regex , -.BR --seq-modifier-regex , -.BR --parser-regex , -.BR --serializer-regex , -.BR --const-regex , -.BR --enumerator-regex , -and -.B --element-type-regex -options allow you to specify extra regular expressions for each name -category in addition to the predefined set that is added depending on -the -.B --type-naming -and -.B --function-naming -options. Expressions that are provided with the -.B --*-regex -options are evaluated prior to any predefined expressions. This allows -you to selectively override some or all of the predefined transformations. -When debugging your own expressions, it is often useful to see which -expressions match which names. The -.B --name-regex-trace -option allows you to trace the process of applying -regular expressions to names. - -The value for the -.B --*-regex -options should be a perl-like regular expression in the form -.BI / pattern / replacement /\fR. -Any character can be used as a delimiter instead of -.BR / . -Escaping of the delimiter character in -.I pattern -or -.I replacement -is not supported. All the regular expressions for each category are pushed -into a category-specific stack with the last specified expression -considered first. The first match that succeeds is used. For the -.B --one-accessor-regex -(accessors with cardinality one), -.B --opt-accessor-regex -(accessors with cardinality optional), and -.B --seq-accessor-regex -(accessors with cardinality sequence) categories the -.B --accessor-regex -expressions are used as a fallback. For the -.BR --one-modifier-regex , -.BR --opt-modifier-regex , -and -.B --seq-modifier-regex -categories the -.B --modifier-regex -expressions are used as a fallback. For the -.B --element-type-regex -category the -.B --type-regex -expressions are used as a fallback. - -The type name expressions -.RB ( --type-regex ) -are evaluated on the name string that has the following format: - -[\fInamespace \fR]\fIname\fR[\fB,\fIname\fR][\fB,\fIname\fR][\fB,\fIname\fR] - -The element type name expressions -.RB ( --element-type-regex ), -effective only when the -.B --generate-element-type -option is specified, are evaluated on the name string that has the following -format: - -.I namespace name - -In the type name format the -.I namespace -part followed by a space is only present for global type names. For global -types and elements defined in schemas without a target namespace, the -.I namespace -part is empty but the space is still present. In the type name format after -the initial -.I name -component, up to three additional -.I name -components can be present, separated by commas. For example: - -.B http://example.com/hello type - -.B foo - -.B foo,iterator - -.B foo,const,iterator - -The following set of predefined regular expressions is used to transform -type names when the upper-camel-case naming convention is selected: - -.B /(?:[^ ]* )?([^,]+)/\\\\u$1/ - -.B /(?:[^ ]* )?([^,]+),([^,]+)/\\\\u$1\\\\u$2/ - -.B /(?:[^ ]* )?([^,]+),([^,]+),([^,]+)/\\\\u$1\\\\u$2\\\\u$3/ - -.B /(?:[^ ]* )?([^,]+),([^,]+),([^,]+),([^,]+)/\\\\u$1\\\\u$2\\\\u$3\\\\u$4/ - -The accessor and modifier expressions -.RB ( --*accessor-regex -and -.BR --*modifier-regex ) -are evaluated on the name string that has the following format: - -\fIname\fR[\fB,\fIname\fR][\fB,\fIname\fR] - -After the initial -.I name -component, up to two additional -.I name -components can be present, separated by commas. For example: - -.B foo - -.B dom,document - -.B foo,default,value - -The following set of predefined regular expressions is used to transform -accessor names when the -.B java -naming convention is selected: - -.B /([^,]+)/get\\\\u$1/ - -.B /([^,]+),([^,]+)/get\\\\u$1\\\\u$2/ - -.B /([^,]+),([^,]+),([^,]+)/get\\\\u$1\\\\u$2\\\\u$3/ - -For the parser, serializer, and enumerator categories, the corresponding -regular expressions are evaluated on local names of elements and on -enumeration values, respectively. For example, the following predefined -regular expression is used to transform parsing function names when the -.B java -naming convention is selected: - -.B /(.+)/parse\\\\u$1/ - -The const category is used to create C++ constant names for the -element/wildcard/text content ids in ordered types. - -See also the REGEX AND SHELL QUOTING section below. - -\" -\" TYPE MAP -\" -.SH TYPE MAP -Type map files are used in C++/Parser to define a mapping between XML -Schema and C++ types. The compiler uses this information to determine -the return types of -.B post_* -functions in parser skeletons corresponding to XML Schema types -as well as argument types for callbacks corresponding to elements -and attributes of these types. - -The compiler has a set of predefined mapping rules that map built-in -XML Schema types to suitable C++ types (discussed below) and all -other types to -.BR void . -By providing your own type maps you can override these predefined rules. -The format of the type map file is presented below: - -.RS -.B namespace -.I schema-namespace -[ -.I cxx-namespace -] -.br -.B { -.br - ( -.B include -.IB file-name ; -)* -.br - ([ -.B type -] -.I schema-type cxx-ret-type -[ -.I cxx-arg-type -.RB ] ; -)* -.br -.B } -.br -.RE - -Both -.I schema-namespace -and -.I schema-type -are regex patterns while -.IR cxx-namespace , -.IR cxx-ret-type , -and -.I cxx-arg-type -are regex pattern substitutions. All names can be optionally enclosed -in \fR" "\fR, for example, to include white-spaces. - -.I schema-namespace -determines XML Schema namespace. Optional -.I cxx-namespace -is prefixed to every C++ type name in this namespace declaration. -.I cxx-ret-type -is a C++ type name that is used as a return type for the -.B post_* -functions. Optional -.I cxx-arg-type -is an argument type for callback functions corresponding to elements and -attributes of this type. If -.I cxx-arg-type -is not specified, it defaults to -.I cxx-ret-type -if -.I cxx-ret-type -ends with -.B * -or -.B & -(that is, it is a pointer or a reference) and -.B const -\fIcxx-ret-type\fB&\fR otherwise. -.I file-name -is a file name either in the \fR" "\fR or < > format and is added with the -.B #include -directive to the generated code. - -The \fB#\fR character starts a comment that ends with a new line or end of -file. To specify a name that contains \fB#\fR enclose it in \fR" "\fR. For -example: - -.RS -namespace http://www.example.com/xmlns/my my -.br -{ -.br - include "my.hxx"; -.br - - # Pass apples by value. - # - apple apple; -.br - - # Pass oranges as pointers. - # - orange orange_t*; -.br -} -.br -.RE - -In the example above, for the -.B http://www.example.com/xmlns/my#orange -XML Schema type, the -.B my::orange_t* -C++ type will be used as both return and argument types. - -Several namespace declarations can be specified in a single file. -The namespace declaration can also be completely omitted to map -types in a schema without a namespace. For instance: - -.RS -include "my.hxx"; -.br -apple apple; -.br - -namespace http://www.example.com/xmlns/my -.br -{ -.br - orange "const orange_t*"; -.br -} -.br -.RE - - -The compiler has a number of predefined mapping rules that can be -presented as the following map files. The string-based XML Schema -built-in types are mapped to either -.B std::string -or -.B std::wstring -depending on the character type selected with the -.B --char-type -option -.RB ( char -by default). - -.RS -namespace http://www.w3.org/2001/XMLSchema -.br -{ -.br - boolean bool bool; -.br - - byte "signed char" "signed char"; -.br - unsignedByte "unsigned char" "unsigned char"; -.br - - short short short; -.br - unsignedShort "unsigned short" "unsigned short"; -.br - - int int int; -.br - unsignedInt "unsigned int" "unsigned int"; -.br - - long "long long" "long long"; -.br - unsignedLong "unsigned long long" "unsigned long long"; -.br - - integer "long long" "long long"; -.br - - negativeInteger "long long" "long long"; -.br - nonPositiveInteger "long long" "long long"; -.br - - positiveInteger "unsigned long long" "unsigned long long"; -.br - nonNegativeInteger "unsigned long long" "unsigned long long"; -.br - - float float float; -.br - double double double; -.br - decimal double double; -.br - - string std::string; -.br - normalizedString std::string; -.br - token std::string; -.br - Name std::string; -.br - NMTOKEN std::string; -.br - NCName std::string; -.br - ID std::string; -.br - IDREF std::string; -.br - language std::string; -.br - anyURI std::string; -.br - - NMTOKENS xml_schema::string_sequence; -.br - IDREFS xml_schema::string_sequence; -.br - - QName xml_schema::qname; -.br - - base64Binary std::auto_ptr -.br - std::auto_ptr; -.br - hexBinary std::auto_ptr -.br - std::auto_ptr; -.br - - date xml_schema::date; -.br - dateTime xml_schema::date_time; -.br - duration xml_schema::duration; -.br - gDay xml_schema::gday; -.br - gMonth xml_schema::gmonth; -.br - gMonthDay xml_schema::gmonth_day; -.br - gYear xml_schema::gyear; -.br - gYearMonth xml_schema::gyear_month; -.br - time xml_schema::time; -.br -} -.br -.RE - - -The last predefined rule maps anything that wasn't mapped by previous -rules to -.BR void : - -.RS -namespace .* -.br -{ -.br - .* void void; -.br -} -.br -.RE - -When you provide your own type maps with the -.B --type-map -option, they are evaluated first. This allows you to selectively override -predefined rules. - -.\" -.\" REGEX AND SHELL QUOTING -.\" -.SH REGEX AND SHELL QUOTING -When entering a regular expression argument in the shell command line -it is often necessary to use quoting (enclosing the argument in " " -or ' ') in order to prevent the shell from interpreting certain -characters, for example, spaces as argument separators and $ as -variable expansions. - -Unfortunately it is hard to achieve this in a manner that is portable -across POSIX shells, such as those found on GNU/Linux and UNIX, and -Windows shell. For example, if you use " " for quoting you will get -a wrong result with POSIX shells if your expression contains $. The -standard way of dealing with this on POSIX systems is to use ' ' -instead. Unfortunately, Windows shell does not remove ' ' from -arguments when they are passed to applications. As a result you may -have to use ' ' for POSIX and " " for Windows ($ is not treated as -a special character on Windows). - -Alternatively, you can save regular expression options into a file, -one option per line, and use this file with the -.B --options-file -option. With this approach you don't need to worry about shell quoting. - -.\" -.\" DIAGNOSTICS -.\" -.SH DIAGNOSTICS -If the input file is not a valid W3C XML Schema definition, -.B xsd -will issue diagnostic messages to -.B STDERR -and exit with non-zero exit code. -.SH BUGS -Send bug reports to the xsd-users@codesynthesis.com mailing list. -.SH COPYRIGHT -Copyright (c) $copyright$. - -Permission is granted to copy, distribute and/or modify this -document under the terms of the GNU Free Documentation License, -version 1.2; with no Invariant Sections, no Front-Cover Texts and -no Back-Cover Texts. Copy of the license can be obtained from -https://www.codesynthesis.com/licenses/fdl-1.2.txt diff --git a/doc/xsd-epilogue.xhtml b/doc/xsd-epilogue.xhtml deleted file mode 100644 index aef0418..0000000 --- a/doc/xsd-epilogue.xhtml +++ /dev/null @@ -1,422 +0,0 @@ -

NAMING CONVENTION

- -

The compiler can be instructed to use a particular naming - convention in the generated code. A number of widely-used - conventions can be selected using the --type-naming - and --function-naming options. A custom - naming convention can be achieved using the - --type-regex, - --accessor-regex, - --one-accessor-regex, - --opt-accessor-regex, - --seq-accessor-regex, - --modifier-regex, - --one-modifier-regex, - --opt-modifier-regex, - --seq-modifier-regex, - --parser-regex, - --serializer-regex, - --const-regex, - --enumerator-regex, and - --element-type-regex options. -

- -

The --type-naming option specifies the - convention that should be used for naming C++ types. Possible - values for this option are knr (default), - ucc, and java. The - knr value (stands for K&R) signifies - the standard, lower-case naming convention with the underscore - used as a word delimiter, for example: foo, - foo_bar. The ucc (stands - for upper-camel-case) and - java values a synonyms for the same - naming convention where the first letter of each word in the - name is capitalized, for example: Foo, - FooBar.

- -

Similarly, the --function-naming option - specifies the convention that should be used for naming C++ - functions. Possible values for this option are knr - (default), lcc, and java. The - knr value (stands for K&R) signifies - the standard, lower-case naming convention with the underscore - used as a word delimiter, for example: foo(), - foo_bar(). The lcc value - (stands for lower-camel-case) signifies a naming convention - where the first letter of each word except the first is - capitalized, for example: foo(), fooBar(). - The java naming convention is similar to - the lower-camel-case one except that accessor functions are prefixed - with get, modifier functions are prefixed - with set, parsing functions are prefixed - with parse, and serialization functions are - prefixed with serialize, for example: - getFoo(), setFooBar(), - parseRoot(), serializeRoot().

- -

Note that the naming conventions specified with the - --type-naming and - --function-naming options perform only limited - transformations on the names that come from the schema in the - form of type, attribute, and element names. In other words, to - get consistent results, your schemas should follow a similar - naming convention as the one you would like to have in the - generated code. Alternatively, you can use the - --*-regex options (discussed below) - to perform further transformations on the names that come from - the schema.

- -

The - --type-regex, - --accessor-regex, - --one-accessor-regex, - --opt-accessor-regex, - --seq-accessor-regex, - --modifier-regex, - --one-modifier-regex, - --opt-modifier-regex, - --seq-modifier-regex, - --parser-regex, - --serializer-regex, - --const-regex, - --enumerator-regex, and - --element-type-regex options allow you to - specify extra regular expressions for each name category in - addition to the predefined set that is added depending on - the --type-naming and - --function-naming options. Expressions - that are provided with the --*-regex - options are evaluated prior to any predefined expressions. - This allows you to selectively override some or all of the - predefined transformations. When debugging your own expressions, - it is often useful to see which expressions match which names. - The --name-regex-trace option allows you - to trace the process of applying regular expressions to - names.

- -

The value for the --*-regex options should be - a perl-like regular expression in the form - /pattern/replacement/. - Any character can be used as a delimiter instead of /. - Escaping of the delimiter character in pattern or - replacement is not supported. - All the regular expressions for each category are pushed into a - category-specific stack with the last specified expression - considered first. The first match that succeeds is used. For the - --one-accessor-regex (accessors with cardinality one), - --opt-accessor-regex (accessors with cardinality optional), and - --seq-accessor-regex (accessors with cardinality sequence) - categories the --accessor-regex expressions are - used as a fallback. For the - --one-modifier-regex, - --opt-modifier-regex, and - --seq-modifier-regex - categories the --modifier-regex expressions are - used as a fallback. For the --element-type-regex - category the --type-regex expressions are - used as a fallback.

- -

The type name expressions (--type-regex) - are evaluated on the name string that has the following - format:

- -

[namespace ]name[,name][,name][,name]

- -

The element type name expressions - (--element-type-regex), effective only when - the --generate-element-type option is specified, - are evaluated on the name string that has the following - format:

- -

namespace name

- -

In the type name format the namespace part - followed by a space is only present for global type names. For - global types and elements defined in schemas without a target - namespace, the namespace part is empty but - the space is still present. In the type name format after the - initial name component, up to three additional - name components can be present, separated - by commas. For example:

- -

http://example.com/hello type

-

foo

-

foo,iterator

-

foo,const,iterator

- -

The following set of predefined regular expressions is used to - transform type names when the upper-camel-case naming convention - is selected:

- -

/(?:[^ ]* )?([^,]+)/\u$1/

-

/(?:[^ ]* )?([^,]+),([^,]+)/\u$1\u$2/

-

/(?:[^ ]* )?([^,]+),([^,]+),([^,]+)/\u$1\u$2\u$3/

-

/(?:[^ ]* )?([^,]+),([^,]+),([^,]+),([^,]+)/\u$1\u$2\u$3\u$4/

- -

The accessor and modifier expressions - (--*accessor-regex and - --*modifier-regex) are evaluated on the name string - that has the following format:

- -

name[,name][,name]

- -

After the initial name component, up to two - additional name components can be present, - separated by commas. For example:

- -

foo

-

dom,document

-

foo,default,value

- -

The following set of predefined regular expressions is used to - transform accessor names when the java naming - convention is selected:

- -

/([^,]+)/get\u$1/

-

/([^,]+),([^,]+)/get\u$1\u$2/

-

/([^,]+),([^,]+),([^,]+)/get\u$1\u$2\u$3/

- -

For the parser, serializer, and enumerator categories, the - corresponding regular expressions are evaluated on local names of - elements and on enumeration values, respectively. For example, the - following predefined regular expression is used to transform parsing - function names when the java naming convention - is selected:

- -

/(.+)/parse\u$1/

- -

The const category is used to create C++ constant names for the - element/wildcard/text content ids in ordered types.

- -

See also the REGEX AND SHELL QUOTING section below.

- -

TYPE MAP

- -

Type map files are used in C++/Parser to define a mapping between - XML Schema and C++ types. The compiler uses this information - to determine the return types of post_* - functions in parser skeletons corresponding to XML Schema - types as well as argument types for callbacks corresponding - to elements and attributes of these types.

- -

The compiler has a set of predefined mapping rules that map - built-in XML Schema types to suitable C++ types (discussed - below) and all other types to void. - By providing your own type maps you can override these predefined - rules. The format of the type map file is presented below: -

- -
-namespace <schema-namespace> [<cxx-namespace>]
-{
-  (include <file-name>;)*
-  ([type] <schema-type> <cxx-ret-type> [<cxx-arg-type>];)*
-}
-  
- -

Both <schema-namespace> and - <schema-type> are regex patterns while - <cxx-namespace>, - <cxx-ret-type>, and - <cxx-arg-type> are regex pattern - substitutions. All names can be optionally enclosed in - " ", for example, to include white-spaces.

- -

<schema-namespace> determines XML - Schema namespace. Optional <cxx-namespace> - is prefixed to every C++ type name in this namespace declaration. - <cxx-ret-type> is a C++ type name that is - used as a return type for the post_* functions. - Optional <cxx-arg-type> is an argument - type for callback functions corresponding to elements and attributes - of this type. If - <cxx-arg-type> is not specified, it defaults - to <cxx-ret-type> if <cxx-ret-type> - ends with * or & (that is, - it is a pointer or a reference) and - const <cxx-ret-type>& - otherwise. - <file-name> is a file name either in the - " " or < > format - and is added with the #include directive to - the generated code.

- -

The # character starts a comment that ends - with a new line or end of file. To specify a name that contains - # enclose it in " ". - For example:

- -
-namespace http://www.example.com/xmlns/my my
-{
-  include "my.hxx";
-
-  # Pass apples by value.
-  #
-  apple apple;
-
-  # Pass oranges as pointers.
-  #
-  orange orange_t*;
-}
-  
- -

In the example above, for the - http://www.example.com/xmlns/my#orange - XML Schema type, the my::orange_t* C++ type will - be used as both return and argument types.

- -

Several namespace declarations can be specified in a single - file. The namespace declaration can also be completely - omitted to map types in a schema without a namespace. For - instance:

- -
-include "my.hxx";
-apple apple;
-
-namespace http://www.example.com/xmlns/my
-{
-  orange "const orange_t*";
-}
-  
- -

The compiler has a number of predefined mapping rules that can be - presented as the following map files. The string-based XML Schema - built-in types are mapped to either std::string - or std::wstring depending on the character type - selected with the --char-type option - (char by default).

- -
-namespace http://www.w3.org/2001/XMLSchema
-{
-  boolean bool bool;
-
-  byte "signed char" "signed char";
-  unsignedByte "unsigned char" "unsigned char";
-
-  short short short;
-  unsignedShort "unsigned short" "unsigned short";
-
-  int int int;
-  unsignedInt "unsigned int" "unsigned int";
-
-  long "long long" "long long";
-  unsignedLong "unsigned long long" "unsigned long long";
-
-  integer "long long" "long long";
-
-  negativeInteger "long long" "long long";
-  nonPositiveInteger "long long" "long long";
-
-  positiveInteger "unsigned long long" "unsigned long long";
-  nonNegativeInteger "unsigned long long" "unsigned long long";
-
-  float float float;
-  double double double;
-  decimal double double;
-
-  string std::string;
-  normalizedString std::string;
-  token std::string;
-  Name std::string;
-  NMTOKEN std::string;
-  NCName std::string;
-  ID std::string;
-  IDREF std::string;
-  language std::string;
-  anyURI std::string;
-
-  NMTOKENS xml_schema::string_sequence;
-  IDREFS xml_schema::string_sequence;
-
-  QName xml_schema::qname;
-
-  base64Binary std::auto_ptr<xml_schema::buffer>
-               std::auto_ptr<xml_schema::buffer>;
-  hexBinary std::auto_ptr<xml_schema::buffer>
-            std::auto_ptr<xml_schema::buffer>;
-
-  date xml_schema::date;
-  dateTime xml_schema::date_time;
-  duration xml_schema::duration;
-  gDay xml_schema::gday;
-  gMonth xml_schema::gmonth;
-  gMonthDay xml_schema::gmonth_day;
-  gYear xml_schema::gyear;
-  gYearMonth xml_schema::gyear_month;
-  time xml_schema::time;
-}
-  
- -

The last predefined rule maps anything that wasn't mapped by - previous rules to void:

- -
-namespace .*
-{
-  .* void void;
-}
-  
- - -

When you provide your own type maps with the - --type-map option, they are evaluated first. - This allows you to selectively override predefined rules.

- -

REGEX AND SHELL QUOTING

- -

When entering a regular expression argument in the shell - command line it is often necessary to use quoting (enclosing - the argument in " " or - ' ') in order to prevent the shell - from interpreting certain characters, for example, spaces as - argument separators and $ as variable - expansions.

- -

Unfortunately it is hard to achieve this in a manner that is - portable across POSIX shells, such as those found on - GNU/Linux and UNIX, and Windows shell. For example, if you - use " " for quoting you will get a - wrong result with POSIX shells if your expression contains - $. The standard way of dealing with this - on POSIX systems is to use ' ' instead. - Unfortunately, Windows shell does not remove ' ' - from arguments when they are passed to applications. As a result you - may have to use ' ' for POSIX and - " " for Windows ($ is - not treated as a special character on Windows).

- -

Alternatively, you can save regular expression options into - a file, one option per line, and use this file with the - --options-file option. With this approach - you don't need to worry about shell quoting.

- -

DIAGNOSTICS

- -

If the input file is not a valid W3C XML Schema definition, - xsd will issue diagnostic messages to STDERR - and exit with non-zero exit code.

- -

BUGS

- -

Send bug reports to the - xsd-users@codesynthesis.com mailing list.

- - - - - - diff --git a/doc/xsd-parser-header.1 b/doc/xsd-parser-header.1 deleted file mode 100644 index e0cf84e..0000000 --- a/doc/xsd-parser-header.1 +++ /dev/null @@ -1,4 +0,0 @@ -\" -\" C++/Parser -\" -.SS cxx-parser command options diff --git a/doc/xsd-parser-header.xhtml b/doc/xsd-parser-header.xhtml deleted file mode 100644 index 94fa2c1..0000000 --- a/doc/xsd-parser-header.xhtml +++ /dev/null @@ -1 +0,0 @@ -

CXX-PARSER COMMAND OPTIONS

diff --git a/doc/xsd-prologue.1 b/doc/xsd-prologue.1 deleted file mode 100644 index 50872b4..0000000 --- a/doc/xsd-prologue.1 +++ /dev/null @@ -1,119 +0,0 @@ -.\" Process this file with -.\" groff -man -Tascii xsd.1 -.\" -.TH XSD 1 "July 2014" "XSD 4.1.0" -.SH NAME -xsd \- W3C XML Schema to C++ Compiler -.\" -.\" -.\" -.\"-------------------------------------------------------------------- -.SH SYNOPSIS -.\"-------------------------------------------------------------------- -.B xsd -.I command -.B [ -.I options -.B ] -.I file -.B [ -.I file -.B ...] -.in -.B xsd help -.B [ -.I command -.B ] -.in -.B xsd version -.\" -.\" -.\" -.\"-------------------------------------------------------------------- -.SH DESCRIPTION -.\"-------------------------------------------------------------------- -.B xsd -generates vocabulary-specific, statically-typed C++ mapping from W3C XML -Schema definitions. Particular mapping to produce is selected by a -.IR command . -Each mapping has a number of mapping-specific -.I options -that should appear, if any, after the -.IR command . -Input files should be W3C XML Schema definitions. The exact set of the -generated files depends on the selected mapping and options. -.\" -.\" -.\" -.\"-------------------------------------------------------------------- -.SH COMMANDS -.\"-------------------------------------------------------------------- -.IP \fBcxx-tree\fR -Generate the C++/Tree mapping. For each input file in the form -.B name.xsd -the following C++ files are generated: -.B name.hxx -(header file), -.B name.ixx -(inline file, generated only if the -.B --generate-inline -option is specified), -.B name.cxx -(source file), and -.B name-fwd.hxx -(forward declaration file, generated only if the -.B --generate-forward -option is specified). - -.IP \fBcxx-parser\fR -Generate the C++/Parser mapping. For each input file in the form -.B name.xsd -the following C++ files are generated: -.B name-pskel.hxx -(parser skeleton header file), -.B name-pskel.ixx -(parser skeleton inline file, generated only if the -.B --generate-inline -option is specified), and -.B name-pskel.cxx -(parser skeleton source file). If the -.B --generate-noop-impl -or -.B --generate-print-impl -option is specified, the following additional sample implementation files -are generated: -.B name-pimpl.hxx -(parser implementation header file) and -.B name-pimpl.cxx -(parser implementation source file). If the -.B --generate-test-driver -option is specified, the additional -.B name-driver.cxx -test driver file is generated. - -.IP \fBhelp\fR -Print usage information and exit. Use -.PP -.RS -.RS 3 -.B xsd help -.I command -.RE -.PP -for command-specific help. -.RE -.IP \fBversion\fR -Print version and exit. -.\"-------------------------------------------------------------------- -.SH OPTIONS -.\"-------------------------------------------------------------------- -Command-specific -.IR options , -if any, should appear after the corresponding -.IR command . - -.\" -.\" Common options. -.\" -.SS common options -. diff --git a/doc/xsd-prologue.xhtml b/doc/xsd-prologue.xhtml deleted file mode 100644 index 6facbe8..0000000 --- a/doc/xsd-prologue.xhtml +++ /dev/null @@ -1,122 +0,0 @@ - - - - - - XSD 4.1.0 Compiler Command Line Manual - - - - - - - - - - - -
-
- -

NAME

- -

xsd - W3C XML Schema to C++ Compiler

- -

SYNOPSIS

- -
-
xsd command [options] file [file ...]
-
xsd help [command]
-
xsd version
-
- -

DESCRIPTION

- -

xsd generates vocabulary-specific, statically-typed - C++ mapping from W3C XML Schema definitions. Particular mapping to - produce is selected by a command. Each mapping has - a number of mapping-specific options that should - appear, if any, after the command. Input files should - be W3C XML Schema definitions. The exact set of the generated files depends - on the selected mapping and options.

- -

COMMANDS

- -
-
cxx-tree
-
Generate the C++/Tree mapping. For each input file in the form - name.xsd the following C++ files are generated: - name.hxx (header file), - name.ixx (inline file, generated only if the - --generate-inline option is specified), - name.cxx (source file), and - name-fwd.hxx (forward declaration file, generated - only if the --generate-forward option is - specified).
- -
cxx-parser
-
Generate the C++/Parser mapping. For each input file in the form - name.xsd the following C++ files are generated: - name-pskel.hxx (parser skeleton header file), - name-pskel.ixx (parser skeleton inline file, - generated only if the --generate-inline - option is specified), and - name-pskel.cxx (parser skeleton source file). - If the --generate-noop-impl or - --generate-print-impl option is specified, - the following additional sample implementation files are generated: - name-pimpl.hxx (parser implementation header - file) and - name-pimpl.cxx (parser implementation source - file). If the --generate-test-driver option - is specified, the additional name-driver.cxx - test driver file is generated.
- -
help
-
Print usage information and exit. Use -

xsd help command

- for command-specific help. -
- -
version
-
Print version and exit.
-
- -

OPTIONS

- -

Command-specific options, if any, should appear - after the corresponding command.

- -

COMMON OPTIONS

diff --git a/doc/xsd-tree-header.1 b/doc/xsd-tree-header.1 deleted file mode 100644 index b9146a7..0000000 --- a/doc/xsd-tree-header.1 +++ /dev/null @@ -1,4 +0,0 @@ -.\" -.\" C++/Tree options. -.\" -.SS cxx-tree command options diff --git a/doc/xsd-tree-header.xhtml b/doc/xsd-tree-header.xhtml deleted file mode 100644 index 73f9c99..0000000 --- a/doc/xsd-tree-header.xhtml +++ /dev/null @@ -1 +0,0 @@ -

CXX-TREE COMMAND OPTIONS

-- cgit v1.1