• About xsd2pp
• Running the xsd2cpp tool
• Building the generated source
• Using the build

• the C++ sources/headers for the supplied XML-Schema
• a main.cpp template, to demonstrate how generated sources can be consumed
• the automake/autoconf files for building the generated source

• C++ data-binding for XML-schema
• C++ validating-parser/writer for xml-files constrained by the supplied XML-schema

The main.cpp aims to demonstrate the multiple options available(parsing/writing/validating xml-files etc.) around the schema and xml files.

Further, in this document, in relation to xsd2cpp, the <name> token would signify the name(excluding extension like .xsd) of the supplied XML-Schema.
For instance, given a XML-Schema file simpleTypesDemo.xsd, the <name> would mean "simpleTypesDemo" token.

  $ xsd2cpp 
  Usage:

  1.  xsd2cpp xsd-file [outdir]
        outdir: directory to output the generated source to
        (if unspecified, defaults to xsd-file-name)

        -s :  do not terminate on error

  2.  xsd2cpp -v
        prints verion

  3.  xsd2cpp -h
        prints help

  $ xsd2cpp simpleTypesDemo.xsd .
  output path: .
  =>  Generating source files...
  =>  Generating automake/autoconf files ...
  =>  Generating README.build.txt file ...

• the -s option suppresses any error reported on xml schema by xsd2cpp tool.While processing the input XML Schema, if the xsd2cpp tool finds some invalidity with the schema, it aborts the code generation and reports the error. However, if you think that the error itself is invalid, and want to proceed with code generation, use this option. Please note that, the code generated with -s option, is not guranteed to compile or run in a sane manner. This is an experimental option and will be deprecated later.
  Whenever you suspect the xsd2cpp to be wrongly reporting an error on input XML Schema, you are requested to report it to us: Report Bugs
  
  
• If there is a main.cpp file already present in output directory, then it is not overridden on invocation of xsd2cpp, instead a file named main.cpp.template, is made available under the same output directory. This is so to preserve any user edits inside main.cpp over it's generated copy. The important thing to remember is that if an edit is made to the XML-Schema file, the main.cpp may need to get updated with changes like renamed classes, new includes, choice of documentElement etc. A "make" in this case may fail on main.cpp. So please make sure to do following in such cases:
  • apply user edits(if any) from current main.cpp to main.cpp.template
  • rename main.cpp.template to main.cpp
  • then run "make"

• the data-binding+parser+writer library
• header files to be used in user development sources consuming the abovestated library
• there is a binary built with name <name>run

• Look of the build
• Change needed prior to use of -s and -w options: choose the document element
• Run Options explained

The built library alongwith the generated headers for user supplied XML-Schema, can be consumed by user applications in their builds.
One example of how to consume the built library/headers, comes alongwith the generated sources viz. main.cpp. The main.cpp includes the generated headers and links to the built library, and makes a binary named <name>run. This <name>run binary demostrates all the use cases around the XML-Schema, that XmlPlus supports. So in that sense main.cpp serves as an example user application, showing how to consume the C++ library built for a XML-Schema file.

 $ ./build/bin/simpleTypesDemorun --help 
 Usage: ./build/bin/simpleTypesDemorun [options] [XMLfile] 
 Options:
  -s, --sample
    create a schema-driven sample xml-file
  -w, --write
    write a xml-file using populated Document
    Note: populateDocument() function in main.cpp template,
    must be used to populate the Document
  -v, --validate
    validate input xml-file(against compiled schema)
  -r, --roundtrip
    roundtrip (read->write) input xml-file
  -u, --row
    perform read->operate->write operations on input xml-file
  -h, --help
    print help
 

  void chooseDocumentElement(NoNS::Document* xsdDoc)
  {
    // uncomment one of folowing to choose root
    xsdDoc->set_root_mails();
    //xsdDoc->set_root_header();
    //xsdDoc->set_root_Date();
  }
  

1. write sample xml file(-s option)
   This option results in writing of a schema driven sample xml file namely sample.xml.
   Following points are noteworthy in this regard:
   
   • If XML Schema has more than one choice of document element, then choose the document element in the generated main.cpp file.
   • This sample.xml file is just one of many possible instance documents for the XML Schema in question, and not necessarily the only possible layout.
     
   • This sample.xml is not necessarily a valid instance document. Though, the order of elements and attributes in the sample.xml file is a valid order, the values of elements and attributes are not necessarily valid with respect to the XML Schema in question.
   
   
   
2. write a xml file using populated Document(-w option)
   This option shows the use case of writing xml file, by serializing the populated XML-Objects. The serialization is done through Document class.
   Following points are noteworthy in this regard:
   
   • If XML Schema has more than one choice of document element, then choose the document element in the generated main.cpp file.
   • The callback function populateDocument(...) should be filled with appropriate code to populate the XML Objects under Document.
   
   
   
3. validate input xml file(-v option)
   
   This option is used to validate the input xml-file(against compiled schema).
   For instance, for a XML-Schema named simpleTypesDemo.xsd, we would have a simpleTypesDemorun test utility built.
   Now, let us assume that you have one st.xml file which is a well-formed xml document, but is invalid against the XML-Schema.

   ---

     $ ./build/bin/simpleTypesDemorun -v st.xml
     validating file:st.xml
       => validation failed
   
     Error: {
       Expected:
         => Element '{http://www.example.com/STDemo} anIntMax5k'
       Got:
         => Element '{http://www.example.com/STDemo} anIntMax10'
     
       element: myComplexTypeElem
       file: st.xml
       line,column: 43, 2
     }

   ---

   
   On fixing the error in st.xml, when the validation is done again, it should look like this:

   ---

     $ ./build/bin/simpleTypesDemorun -v st.xml
     validating file:st.xml
        => validated successfully

   ---

   
   
   
4. roundtrip a xml file(-r option)
   This option shows the use case of roundtripping(read->write) an input xml file, ie. deserializing an input xml file into XML-Objects and then serializing them back to a xml file. This option can be used to test if the roundtrip causes any loss of xml entities or data. XmlPlus claims to retain comments and processing-instructions in addition to elements and attributes.
   
   
5. roundtrip with a callback(-u option)
   
   This option shows the use case where:
   • a xml file is read(deserialized) into Document(along with the XML Objects under the Document)
   • then the Document is updated using callback function named updateOrConsumeDocument(...). The callback function updateOrConsumeDocument(...) should be filled with appropriate code to update the Document. Alternatively, this callback function can be used to test the correctness of XML Objects' values.
   • then the Document is written(serialized) back to output xml file
   
   Note that, if the updateOrConsumeDocument(...) is left empty, the -u option is as good as -r option.