diff options
Diffstat (limited to 'xsd/doc/cxx/tree/guide/index.xhtml.in')
-rw-r--r-- | xsd/doc/cxx/tree/guide/index.xhtml.in | 150 |
1 files changed, 78 insertions, 72 deletions
diff --git a/xsd/doc/cxx/tree/guide/index.xhtml.in b/xsd/doc/cxx/tree/guide/index.xhtml.in index e1bb36e..b704e50 100644 --- a/xsd/doc/cxx/tree/guide/index.xhtml.in +++ b/xsd/doc/cxx/tree/guide/index.xhtml.in @@ -305,12 +305,14 @@ <li><a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD Compiler Command Line Manual</a></li> - <li>The <code>examples/cxx/tree/</code> directory in the XSD - distribution contains a collection of examples and a README - file with an overview of each example.</li> + <li>The <code>cxx/tree/</code> directory in the + <a href="https://cppget.org/xsd-examples">xsd-examples</a> package + contains a collection of examples and a README file with an overview + of each example.</li> - <li>The <code>README</code> file in the XSD distribution explains - how to compile the examples on various platforms.</li> + <li>The <code>README</code> file in the + <a href="https://cppget.org/xsd-examples">xsd-examples</a> package + explains how to build the examples.</li> <li>The <a href="https://www.codesynthesis.com/mailman/listinfo/xsd-users">xsd-users</a> mailing list is the place to ask technical questions about XSD and the C++/Parser mapping. @@ -446,8 +448,8 @@ serialize a very simple XML document using the XSD-generated C++/Tree object model. The code presented in this chapter is based on the <code>hello</code> example which can be found in - the <code>examples/cxx/tree/</code> directory of the XSD - distribution.</p> + the <code>cxx/tree/</code> directory in the + <a href="https://cppget.org/xsd-examples">xsd-examples</a> package.</p> <h2><a name="2.1">2.1 Writing XML Document and Schema</a></h2> @@ -534,7 +536,7 @@ </p> <pre class="terminal"> -$ xsd cxx-tree hello.xsd +$ xsd cxx-tree --std c++11 hello.xsd </pre> <p>The XSD compiler produces two C++ files: <code>hello.hxx</code> and @@ -584,10 +586,10 @@ public: }; -std::auto_ptr<hello_t> +std::unique_ptr<hello_t> hello (const std::string& uri); -std::auto_ptr<hello_t> +std::unique_ptr<hello_t> hello (std::istream&); </pre> @@ -625,22 +627,22 @@ hello (std::istream&); with the <code>--root-element-*</code> 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 <code>std::auto_ptr</code> - as shown above. For C++11 it is <code>std::unique_ptr</code>. + C++ standard selected. For C++11 it is <code>std::unique_ptr</code> + as shown above. For C++98 it is <code>std::auto_ptr</code>. For example, if we modify our XSD compiler invocation to - select C++11:</p> + select C++98:</p> <pre class="terminal"> -$ xsd cxx-tree --std c++11 hello.xsd +$ xsd cxx-tree hello.xsd </pre> <p>Then the parsing function signatures will become:</p> <pre class="c++"> -std::unique_ptr<hello_t> +std::auto_ptr<hello_t> hello (const std::string& uri); -std::unique_ptr<hello_t> +std::auto_ptr<hello_t> hello (std::istream&); </pre> @@ -664,7 +666,7 @@ main (int argc, char* argv[]) { try { - auto_ptr<hello_t> h (hello (argv[1])); + unique_ptr<hello_t> h (hello (argv[1])); for (hello_t::name_const_iterator i (h->name ().begin ()); i != h->name ().end (); @@ -701,8 +703,8 @@ main (int argc, char* argv[]) </p> <pre class="terminal"> -$ c++ -I.../libxsd -c driver.cxx hello.cxx -$ c++ -o driver driver.o hello.o -lxerces-c +$ c++ -std=c++11 -I.../libxsd -c driver.cxx hello.cxx +$ c++ -std=c++11 -o driver driver.o hello.o -lxerces-c $ ./driver hello.xml Hello, sun! Hello, moon! @@ -710,10 +712,10 @@ Hello, world! </pre> <p>Here <code>.../libxsd</code> represents the path to the - <code>libxsd</code> 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.</p> + <a href="https://cppget.org/libxsd">libxsd</a> package root + directory. 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.</p> <h2><a name="2.5">2.5 Adding Serialization</a></h2> @@ -724,7 +726,7 @@ Hello, world! it with the <code>--generate-serialization</code> options:</p> <pre class="terminal"> -$ xsd cxx-tree --generate-serialization hello.xsd +$ xsd cxx-tree --std c++11 --generate-serialization hello.xsd </pre> <p>If we now examine the generated <code>hello.hxx</code> file, @@ -760,7 +762,7 @@ main (int argc, char* argv[]) { try { - auto_ptr<hello_t> h (hello (argv[1])); + unique_ptr<hello_t> h (hello (argv[1])); // Change the greeting phrase. // @@ -909,7 +911,7 @@ main (int argc, char* argv[]) change the type naming scheme:</p> <pre class="terminal"> -$ xsd cxx-tree --type-naming ucc hello.xsd +$ xsd cxx-tree --std c++11 --type-naming ucc hello.xsd </pre> <p>The <code>ucc</code> argument to the <code>--type-naming</code> @@ -959,10 +961,10 @@ public: }; -std::auto_ptr<Hello_t> +std::unique_ptr<Hello_t> hello (const std::string& uri); -std::auto_ptr<Hello_t> +std::unique_ptr<Hello_t> hello (std::istream&); </pre> @@ -976,7 +978,8 @@ hello (std::istream&); <code>--type-regex</code> option:</p> <pre class="terminal"> -$ xsd cxx-tree --type-naming ucc --type-regex '/ (.+)_t/\u$1/' hello.xsd +$ xsd cxx-tree --std c++11 --type-naming ucc \ + --type-regex '/ (.+)_t/\u$1/' hello.xsd </pre> <p>This results in the following changes to the generated code:</p> @@ -1022,10 +1025,10 @@ public: }; -std::auto_ptr<Hello> +std::unique_ptr<Hello> hello (const std::string& uri); -std::auto_ptr<Hello> +std::unique_ptr<Hello> hello (std::istream&); </pre> @@ -1111,7 +1114,8 @@ hello (std::istream&); our schema with the <code>--generate-doxygen</code> option:</p> <pre class="terminal"> -$ xsd cxx-tree --generate-serialization --generate-doxygen hello.xsd +$ xsd cxx-tree --std c++11 --generate-serialization --generate-doxygen \ + hello.xsd </pre> <p>Now the generated <code>hello.hxx</code> file contains comments @@ -1167,12 +1171,12 @@ $ doxygen hello.doxygen <h2><a name="3.1">3.1 C++ Standard</a></h2> - <p>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 + <p>The C++/Tree mapping provides support for ISO/IEC C++ 2011 (C++11) + and ISO/IEC C++ 1998/2003 (C++98). To select the C++ standard for the generated code we use the <code>--std</code> 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.</p> + C++11, the document explains the C++11/98 usage difference and so + they can easily be converted to C++98.</p> <h2><a name="3.2">3.2 Character Type and Encoding</a></h2> @@ -1600,7 +1604,7 @@ using namespace std; int main () { - auto_ptr<people_t> ppl (people ("people.xml")); + unique_ptr<people_t> ppl (people ("people.xml")); // Iterate over individual person records. // @@ -1681,7 +1685,7 @@ using namespace std; int main () { - auto_ptr<people_t> ppl (people ("people.xml")); + unique_ptr<people_t> ppl (people ("people.xml")); // Iterate over individual person records and increment // the age. @@ -1873,16 +1877,6 @@ ps.push_back (jane); of the passed objects:</p> <pre class="c++"> -// 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 ( @@ -1892,6 +1886,16 @@ unique_ptr<person_t> jane_p ( 28, // age 2)); // id ps.push_back (std::move (jane_p)); // assumes ownership + +// 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 </pre> <p>For more information on the non-copying modifier functions refer to @@ -2265,17 +2269,17 @@ ps.push_back (std::move (jane_p)); // assumes ownership on the following three parsing functions:</p> <pre class="c++"> -std::[auto|unique]_ptr<people_t> +std::[unique|auto]_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> +std::[unique|auto]_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> +std::[unique|auto]_ptr<people_t> people (std::istream& is, const std::string& resource_id, xml_schema::flags f = 0, @@ -2296,29 +2300,29 @@ people (std::istream& is, to pass additional information to the parsing functions. We will use these two arguments in <a href="#5.1">Section 5.1, "XML Schema Validation and Searching"</a> below. All three functions return - the object model as either <code>std::auto_ptr</code> (C++98) or - <code>std::unique_ptr</code> (C++11), depending on the C++ standard + the object model as either <code>std::unique_ptr</code> (C++11) or + <code>std::auto_ptr</code> (C++98), depending on the C++ standard selected (<code>--std</code> XSD compiler option). The following example shows how we can use the above parsing functions:</p> <pre class="c++"> -using std::auto_ptr; +using std::unique_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")); +unique_ptr<people_t> p1 (people ("people.xml")); +unique_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")); +unique_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)); +unique_ptr<people_t> p4 (people (iss)); </pre> @@ -2331,7 +2335,7 @@ auto_ptr<people_t> p4 (people (iss)); flag to the parsing functions, for example:</p> <pre class="c++"> -auto_ptr<people_t> p ( +unique_ptr<people_t> p ( people ("people.xml", xml_schema::flags::dont_validate)); </pre> @@ -2373,7 +2377,7 @@ 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)); +unique_ptr<people_t> p (people ("people.xml", 0, props)); </pre> <p>The schema locations provided with this method overrides @@ -2405,7 +2409,7 @@ 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)); +unique_ptr<people_t> p (people ("people.xml", 0, props)); </pre> <p>A third method is the most useful if you are planning to parse @@ -2414,14 +2418,16 @@ auto_ptr<people_t> p (people ("people.xml", 0, props)); 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 <code>caching</code> example in the - <code>examples/cxx/tree/</code> 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 <code>embedded</code> example in the - <code>examples/cxx/tree/</code> directory of the XSD distribution.</p> + <code>cxx/tree/</code> directory in the + <a href="https://cppget.org/xsd-examples">xsd-examples</a> package. + 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 <code>embedded</code> example in the <code>cxx/tree/</code> + directory in the <a href="https://cppget.org/xsd-examples">xsd-examples</a> + package.</p> <p>When the XML parser cannot locate a schema for the XML document, the validation fails and XML document @@ -2457,7 +2463,7 @@ people.xml:9:10 error: no declaration found for element 'age' <pre class="c++"> try { - auto_ptr<people_t> p (people ("people.xml")); + unique_ptr<people_t> p (people ("people.xml")); } catch (const xml_schema::exception& e) { @@ -2492,7 +2498,7 @@ if (ifs.fail ()) return 1; } -auto_ptr<people_t> p (people (ifs, "people.xml")); +unique_ptr<people_t> p (people (ifs, "people.xml")); if (ifs.fail ()) { @@ -2511,7 +2517,7 @@ try ifs.exceptions (std::ifstream::badbit | std::ifstream::failbit); ifs.open ("people.xml"); - auto_ptr<people_t> p (people (ifs, "people.xml")); + unique_ptr<people_t> p (people (ifs, "people.xml")); } catch (const std::ifstream::failure&) { |