From e8d4a60511f96660f4c754703aff295e32223136 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20W=C3=A4ckerlin?= Date: Thu, 22 Nov 2018 00:13:50 +0000 Subject: [PATCH] migrated README to README.md --- README | 27 ---------- README.md | 114 +++++++++++++++++++++++++++++++++++++++ doc/makefile.am | 2 +- makefile.am | 8 ++- src/xml-cxx/xml.hxx | 127 ++------------------------------------------ 5 files changed, 126 insertions(+), 152 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index 1aef217..0000000 --- a/README +++ /dev/null @@ -1,27 +0,0 @@ -C++ class for reading and writing XML structures - -All informaton can be found in the generated doxygen project documentation. - -Rationale: The initial idea was to map C++ data structures to XML -files for configuration files that can easily be edited by hand. - -This library does not need any kind of C++ code parser or special pre -compiler. You can specify a schema entirly in native C++. The schema -is verified when XML is read and exceptions are thrown when the XML to -be parse is invalid. Exceptions specify exactly the location and -reason of the problem, so that the editor of the XML file can easily -find and correct the problem. - -C++ classes can inherit xml::Serialize and become serializable this -way. All you need to do is to overwrite one single method, where you -declare XML tag names for the class name and for all members. - -(More rationale: See also "Related Pages" in the doxygen project documentation) - -Structure of the files: - src: The source code of the library - doc/html: Doxygen documentation oft the library usage - doc/examples: Example code (included in doxygen documentation) - test: CppUnit test files - can also be taken as examples - -Project URL: https://dev.marc.waeckerlin.org/redmine/projects/libxml-cxx diff --git a/README.md b/README.md new file mode 100644 index 0000000..a878b87 --- /dev/null +++ b/README.md @@ -0,0 +1,114 @@ +C++ XML Class Library +===================== + +This is a C++ class for reading and writing XML structures. + + - Specify your XML schema in C++ using common C++ syntax, such as shift, dereference, etc. + - Verify the schema of XML files while they are read from a stream. + - Map and store your own C++ classes to XML and restore them back. + +Rationale +--------- + +The initial idea was to map C++ data structures to XML files for configuration files that can easily be edited by hand. + +This library does not need any kind of C++ code parser or special pre compiler. You can specify a schema entirly in native C++. The schema is verified when XML is read and exceptions are thrown when the XML to be parse is invalid. Exceptions specify exactly the location and reason of the problem, so that the editor of the XML file can easily find and correct the problem. + +C++ classes can inherit `xml::Serialize` and become serializable this way. All you need to do is to overwrite one single method, where you declare XML tag names for the class name and for all members. + +More rationale: See also [Related Pages](pages.html) in the doxygen project documentation. + + +Basics +------ + +Include file: + +```cpp +#include +``` + +Link option: +``` +-lxml-cxx +``` + + +Factory with Schema Declaration +------------------------------- + +Small example on how to [declare an XML schema](group_freexml.html), you may then use `template.read(is)` to read XML from a stream: + +```cpp +// start with root element: +xml::Factory template(xml::Node("root").attr("id", xml::optional) + // contains any number of + < + <<(xml::Node("other").limits(1, 1) + // contains min 2 max 4 + <attr("id", xml::optional) + <<*xml::string::child.clone() + [...] +``` + + +Serialize Classes, Join Classes with XML +---------------------------------------- + +When inheriting from `xml::Serialize`, your class inherits the methods `xml::Serialize::loadXml` and `xml::Serialize::saveXml`. Simply overwrite `xml::Serialize::initXmlMembers` to make your class [serializable](group_serialization.html): + +```cpp +class MyClass: public xml::Serialize { + [...] + protected: + void initXmlMembers() { + className("MyClass"); + persist(i, "i"); + persist(s, "s"); + persist(l, "l"); + } + private: + int i; + std::string s; + xml::List l; // same behaviour as std::list +}; +``` + + +Known Limitations +----------------- + + - XML-Comments are only ignored, not read, not stored. + - Mixed tags and text is not supported. Tags may either contain other tags only (type xml::Node) or text only (type `xml::String`). -> This is intended behaviour! + - Unlimited recursion is not possible (e.g. `

`;) + - Exceptions should be optional, best effort otherwise (option "strict") + + +### Limitations of Serialization + + - Only the following types are intended to be serialized: + (It is possible to use other techniques, but that's not recommended) + - basic C++ types (except pointer) + - `std::string` + - classes derieved from `xml::Serialize` + - most standard containers, but in their xml-form, e.g. `xml::List` instead of `std::list` (`xml::List` inherits `std::list`) + - Optional values are supported through `xml::Optional` + - `std::bitset`, `std::priority_queue`, `std::queue` and `std::stack` are not implemented + - Polymorfic serialisation is not yet implemented diff --git a/doc/makefile.am b/doc/makefile.am index 62c33d8..d65ff41 100644 --- a/doc/makefile.am +++ b/doc/makefile.am @@ -2,7 +2,7 @@ ## ## This file has been added: ## - by bootstrap.sh -## - on Wed, 21 November 2018 21:41:32 +0100 +## - on Thu, 22 November 2018 01:05:30 +0100 ## Feel free to change it or even remove and rebuild it, up to your needs ## ## 1 2 3 4 5 6 7 8 diff --git a/makefile.am b/makefile.am index 64ed403..6ce3178 100644 --- a/makefile.am +++ b/makefile.am @@ -2,7 +2,7 @@ ## ## This file has been added: ## - by bootstrap.sh -## - on Wed, 21 November 2018 16:27:35 +0100 +## - on Thu, 22 November 2018 01:05:30 +0100 ## Feel free to change it or even remove and rebuild it, up to your needs ## ## 1 2 3 4 5 6 7 8 @@ -21,6 +21,10 @@ dist_noinst_DATA = ax_check_qt.m4 bootstrap.sh \ mac-create-app-bundle.sh resolve-debbuilddeps.sh \ dependency-graph.sh template.sh \ sql-to-dot.sed -dist_doc_DATA = AUTHORS NEWS README COPYING INSTALL ChangeLog +dist_doc_DATA = AUTHORS NEWS README.md COPYING INSTALL ChangeLog +README: README.md + cp README.md README + +CLEANFILES = README MAINTAINERCLEANFILES = makefile.in diff --git a/src/xml-cxx/xml.hxx b/src/xml-cxx/xml.hxx index 37a4717..9020702 100644 --- a/src/xml-cxx/xml.hxx +++ b/src/xml-cxx/xml.hxx @@ -52,127 +52,10 @@ namespace xml { } \ assert(Y); \ } - //! @endcond } +//! @endcond -/*! @mainpage - - @section maintitle C++ XML Class Library - - - Specify your XML schema in C++ using common C++ syntax, - such as shift, dereference, etc. - - Verify the schema of XML files while they are read from a stream. - - Map and store your own C++ classes to XML and restore them back. - - @section basics Basics - - Include file: - @code - #include - @endcode - - Link option: - @code - -lxml-cxx - @endcode - - @section schemaFactory Factory with Schema Declaration - - Small example on how to declare an XML schema (@ref freexml), you - may then use template.read(is) to read XML from a - stream: - - @code - // start with root element: - xml::Factory template(xml::Node("root").attr("id", xml::optional) - // contains any number of - < - <<(xml::Node("other").limits(1, 1) - // contains min 2 max 4 - <attr("id", xml::optional) - <<*xml::string::child.clone() - [...] - @endcode - - @section introSer Serialize Classes, Join Classes with XML - - When inheriting from xml::Serialize, your class inherits the - methods xml::Serialize::loadXml and - xml::Serialize::saveXml. Simply overwrite - xml::Serialize::initXmlMembers to make your class serializable - (@ref serialization): - - @code - class MyClass: public xml::Serialize { - [...] - protected: - void initXmlMembers() { - className("MyClass"); - persist(i, "i"); - persist(s, "s"); - persist(l, "l"); - } - private: - int i; - std::string s; - xml::List l; // same behaviour as std::list - }; - @endcode - - @section readme The README File - - @include README - - @page license License is LGPL 3 - - File COPYING from http://www.gnu.org/licenses/lgpl-3.0.txt: - - @include COPYING - - @page limits Known Limitations - - - XML-Comments are only ignored, not read, not stored. - - Mixed tags and text is not supported. Tags may either contain - other tags only (type xml::Node) or text only (type - xml::String). -> This is intended behaviour! - - Unlimited recursion is not possible - (e.g. <p><p><p></p></p></p>) - - Exceptions should be optional, best effort otherwise (option "strict") - - @see serializationLimits - - @page serializationLimits Limitations of Serialization - - - Only the following types are intended to be serialized:\n - (It is possible to use other techniques, but that's not recommended) - - basic C++ types (except pointer) - - @c std::string - - classes derieved from xml::Serialize - - most standard containers, but in their xml-form, - e.g. xml::List instead of @c std::list - (xml::List inherits @c std::list) - - Optional values are supported through xml::Optional - - @c std::bitset, @c std::priority_queue, @c std::queue and - @c std::stack are not implemented - - Polymorfic serialisation is not yet implemented - - @page rationale Rationale - Limitations of other libraries +/*! @page rationale Rationale - Limitations of other libraries The initial idea was to map C++ data structures to XML files (e.g. for configuration files) that can easily be edited by @@ -195,7 +78,7 @@ namespace xml { The design is based on my experiance with gsoap (http://gsoap.sf.net), boost serialization (http://boost.org) and Qt XML (http://qtsoftware.com). - + @section qtxml Qt XML, a typical DOM approach One is the XML part of the Qt library. These classes can read XML @@ -213,7 +96,7 @@ namespace xml { _firmware = releases.at(i).firstChildElement("firmware"); if (_software.isNull() || _firmware.isNull() || releases.at(i).firstChildElement("notes").isNull()); // error - ... + ... @endcode This is a typical example of a DOM parser. The main disadvantage @@ -250,7 +133,7 @@ namespace xml { @section gsoap Using gSOAP for Serialization of C++ Structures When I was working at Siemens, we often used gSOAP - (http://gsoap.sf.net) when we needed mor flexibility in XML + (https://en.wikipedia.org/wiki/GSOAP) when we needed more flexibility in XML declaration than what's possible with @ref boostserialization. But gSOAP has several problems: