From f0e0fb5f3f2af8b695680e84572137660ffd835b Mon Sep 17 00:00:00 2001 From: Karen Arutyunov Date: Tue, 16 Feb 2021 21:27:12 +0300 Subject: Update documentation --- xsd/doc/cxx/tree/guide/index.xhtml.in | 150 ++++++++++++++++++---------------- 1 file changed, 78 insertions(+), 72 deletions(-) (limited to 'xsd/doc/cxx/tree/guide/index.xhtml.in') 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 @@
  • XSD Compiler Command Line Manual
    • -
  • The examples/cxx/tree/ directory in the XSD - distribution contains a collection of examples and a README - file with an overview of each example.
    • +
  • The cxx/tree/ directory in the + xsd-examples package + 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 README file in the + xsd-examples package + explains how to build the examples.
  • The xsd-users 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 hello example which can be found in - the examples/cxx/tree/ directory of the XSD - distribution.

    + the cxx/tree/ directory in the + xsd-examples package.

    2.1 Writing XML Document and Schema

    @@ -534,7 +536,7 @@ 

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

    The XSD compiler produces two C++ files: hello.hxx 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&); @@ -625,22 +627,22 @@ hello (std::istream&); 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. + C++ standard selected. For C++11 it is std::unique_ptr + as shown above. For C++98 it is std::auto_ptr. For example, if we modify our XSD compiler invocation to - select C++11:

    + select C++98:

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

    Then the parsing function signatures will become:

    -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&);
    @@ -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[]) 

    -$ 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!

    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.

    + libxsd 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.

    2.5 Adding Serialization

    @@ -724,7 +726,7 @@ Hello, world! it with the --generate-serialization options:

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

    If we now examine the generated hello.hxx 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:

    -$ xsd cxx-tree --type-naming ucc hello.xsd
+$ xsd cxx-tree --std c++11 --type-naming ucc hello.xsd

    The ucc argument to the --type-naming @@ -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&); @@ -976,7 +978,8 @@ hello (std::istream&); --type-regex option:

    -$ 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

    This results in the following changes to the generated code:

    @@ -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&); @@ -1111,7 +1114,8 @@ hello (std::istream&); our schema with the --generate-doxygen option:

    -$ xsd cxx-tree --generate-serialization --generate-doxygen hello.xsd
+$ xsd cxx-tree --std c++11 --generate-serialization --generate-doxygen \
+      hello.xsd

    Now the generated hello.hxx file contains comments @@ -1167,12 +1171,12 @@ $ doxygen hello.doxygen

    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 +

    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 --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.

    + C++11, the document explains the C++11/98 usage difference and so + they can easily be converted to C++98.

    3.2 Character Type and Encoding

    @@ -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:

    -// 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

    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:

    -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 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
+     the object model as either std::unique_ptr (C++11) or
+     std::auto_ptr (C++98), 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;
+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));
   
    
 
 
@@ -2331,7 +2335,7 @@ auto_ptr<people_t> p4 (people (iss));
      flag to the parsing functions, for example:
    
 
   
    -auto_ptr<people_t> p (
+unique_ptr<people_t> p (
   people ("people.xml", xml_schema::flags::dont_validate));
   
    
 
@@ -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));

    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));

    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 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.

    + cxx/tree/ directory in the + xsd-examples 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 embedded example in the cxx/tree/ + directory in the xsd-examples + package.

    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' 

     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&)
 {
-- 
cgit v1.1