migrated README to README.md

master
Marc Wäckerlin 6 years ago
parent b7b5c2d3ff
commit e8d4a60511
  1. 27
      README
  2. 114
      README.md
  3. 2
      doc/makefile.am
  4. 8
      makefile.am
  5. 127
      src/xml-cxx/xml.hxx

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

@ -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 <xml-cxx/xml.hxx>
```
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: <root id="">
xml::Factory template(xml::Node("root").attr("id", xml::optional)
// <root> contains any number of <child>
<<xml::String("child")
// must contain exactly one <other>
<<(xml::Node("other").limits(1, 1)
// <other> contains min 2 max 4 <text>
<<xml::String("text").limits(2, 4)));
```
Using Macros Instead of Literal Text
------------------------------------
If you prefere using [constants](group_xmlConst.html) instead of literal texts, you can declare the node names before you use them:
```cpp
XML_NODE(root);
XML_STRING(child);
[...]
```
```cpp
xml::Factory template(xml::node::root.clone()->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<std::string> 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. `<p><p><p></p></p></p>`;)
- 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

@ -2,7 +2,7 @@
## ##
## This file has been added: ## This file has been added:
## - by bootstrap.sh ## - 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 ## Feel free to change it or even remove and rebuild it, up to your needs
## ##
## 1 2 3 4 5 6 7 8 ## 1 2 3 4 5 6 7 8

@ -2,7 +2,7 @@
## ##
## This file has been added: ## This file has been added:
## - by bootstrap.sh ## - 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 ## Feel free to change it or even remove and rebuild it, up to your needs
## ##
## 1 2 3 4 5 6 7 8 ## 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 \ mac-create-app-bundle.sh resolve-debbuilddeps.sh \
dependency-graph.sh template.sh \ dependency-graph.sh template.sh \
sql-to-dot.sed 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 MAINTAINERCLEANFILES = makefile.in

@ -52,127 +52,10 @@ namespace xml {
} \ } \
assert(Y); \ assert(Y); \
} }
//! @endcond
} }
//! @endcond
/*! @mainpage /*! @page rationale Rationale - Limitations of other libraries
@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 <xml-cxx/xml.hxx>
@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 <code>template.read(is)</code> to read XML from a
stream:
@code
// start with root element: <root id="">
xml::Factory template(xml::Node("root").attr("id", xml::optional)
// <root> contains any number of <child>
<<xml::String("child")
// must contain exactly one <other>
<<(xml::Node("other").limits(1, 1)
// <other> contains min 2 max 4 <text>
<<xml::String("text").limits(2, 4)));
@endcode
@section introMacro Using Macros Instead od Literal Text
If you prefere using constants instead of literal texts, you can
declare the node names before you use them (@ref xmlConst):
@code
XML_NODE(root);
XML_STRING(child);
[...]
@endcode
@code
xml::Factory template(xml::node::root.clone()->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<std::string> 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. &ltp&gt;&ltp&gt;&ltp&gt;&lt/p&gt;&lt/p&gt;&lt/p&gt;)
- 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
The initial idea was to map C++ data structures to XML files The initial idea was to map C++ data structures to XML files
(e.g. for configuration files) that can easily be edited by (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 The design is based on my experiance with gsoap
(http://gsoap.sf.net), boost serialization (http://boost.org) and (http://gsoap.sf.net), boost serialization (http://boost.org) and
Qt XML (http://qtsoftware.com). Qt XML (http://qtsoftware.com).
@section qtxml Qt XML, a typical DOM approach @section qtxml Qt XML, a typical DOM approach
One is the XML part of the Qt library. These classes can read XML 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"); _firmware = releases.at(i).firstChildElement("firmware");
if (_software.isNull() || _firmware.isNull() || if (_software.isNull() || _firmware.isNull() ||
releases.at(i).firstChildElement("notes").isNull()); // error releases.at(i).firstChildElement("notes").isNull()); // error
... ...
@endcode @endcode
This is a typical example of a DOM parser. The main disadvantage 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 @section gsoap Using gSOAP for Serialization of C++ Structures
When I was working at Siemens, we often used gSOAP 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 declaration than what's possible with @ref boostserialization. But
gSOAP has several problems: gSOAP has several problems:

Loading…
Cancel
Save