AxioDL/tinyxml2
2
0
Fork 0
mirror of https://github.com/AxioDL/tinyxml2.git synced 2025-05-14 11:21:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

Moves example documentation from xmltest.h to xmltest.cpp

Browse Source
This commit is contained in:
Martinsh Shaiters 2013-01-16 02:08:19 +02:00
parent bbad12a922
commit c9c8b77d87
3 changed files with 116 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
dox
View File

@ -669,7 +669,7 @@ WARN_LOGFILE =
# with spaces. # with spaces.
INPUT = tinyxml2.h \ INPUT = tinyxml2.h \
xmltest.h \ xmltest.cpp \
readme.md readme.md
# This tag can be used to specify the character encoding of the source files # This tag can be used to specify the character encoding of the source files

118
xmltest.cpp
View File

@ -79,7 +79,6 @@ void NullLineEndings( char* p )
} }
// Comments in the header. (Don't know how to get Doxygen to read comments in this file.)
int example_1() int example_1()
{ {
XMLDocument doc; XMLDocument doc;
@ -87,9 +86,17 @@ int example_1()
return doc.ErrorID(); return doc.ErrorID();
} }
/** @page Example-1 Load an XML File
* @dontinclude ./xmltest.cpp
* Basic XML file loading.
* The basic syntax to load an XML file from
* disk and check for an error. (ErrorID()
* will return 0 for no error.)
* @skip example_1()
* @until }
*/
// Comments in the header. (Don't know how to get Doxygen to read comments in this file.)
int example_2() int example_2()
{ {
static const char* xml = "<element/>"; static const char* xml = "<element/>";
@ -98,6 +105,15 @@ int example_2()
return doc.ErrorID(); return doc.ErrorID();
} }
/** @page Example-2 Parse an XML from char buffer
* @dontinclude ./xmltest.cpp
* Basic XML string parsing.
* The basic syntax to parse an XML for
* a char* and check for an error. (ErrorID()
* will return 0 for no error.)
* @skip example_2()
* @until }
*/
int example_3() int example_3()
@ -122,6 +138,69 @@ int example_3()
return doc.ErrorID(); return doc.ErrorID();
} }
/** @page Example-3 Get information out of XML
@dontinclude ./xmltest.cpp
In this example, we navigate a simple XML
file, and read some interesting text. Note
that this is examlpe doesn't use error
checking; working code should check for null
pointers when walking an XML tree, or use
XMLHandle.
(The XML is an excerpt from "dream.xml").
@skip example_3()
@until </PLAY>";
The structure of the XML file is:
<ul>
<li>(declaration)</li>
<li>(dtd stuff)</li>
<li>Element "PLAY"</li>
<ul>
<li>Element "TITLE"</li>
<ul>
<li>Text "A Midsummer Night's Dream"</li>
</ul>
</ul>
</ul>
For this example, we want to print out the
title of the play. The text of the title (what
we want) is child of the "TITLE" element which
is a child of the "PLAY" element.
We want to skip the declaration and dtd, so the
method FirstChildElement() is a good choice. The
FirstChildElement() of the Document is the "PLAY"
Element, the FirstChildElement() of the "PLAY" Element
is the "TITLE" Element.
@until ( "TITLE" );
We can then use the convenience function GetText()
to get the title of the play.
@until title );
Text is just another Node in the XML DOM. And in
fact you should be a little cautious with it, as
text nodes can contain elements.
@verbatim
Consider: A Midsummer Night's <b>Dream</b>
@endverbatim
It is more correct to actually query the Text Node
if in doubt:
@until title );
Noting that here we use FirstChild() since we are
looking for XMLText, not an element, and ToText()
is a cast from a Node to a XMLText.
*/
bool example_4() bool example_4()
@ -150,6 +229,39 @@ bool example_4()
return !doc.Error() && ( v0 == v1 ); return !doc.Error() && ( v0 == v1 );
} }
/** @page Example-4 Read attributes and text information.
@dontinclude ./xmltest.cpp
There are fundamentally 2 ways of writing a key-value
pair into an XML file. (Something that's always annoyed
me about XML.) Either by using attributes, or by writing
the key name into an element and the value into
the text node wrapped by the element. Both approaches
are illustrated in this example, which shows two ways
to encode the value "2" into the key "v":
@skip example_4()
@until "</information>";
TinyXML-2 has accessors for both approaches.
When using an attribute, you navigate to the XMLElement
with that attribute and use the QueryIntAttribute()
group of methods. (Also QueryFloatAttribute(), etc.)
@skip XMLElement* attributeApproachElement
@until &v0 );
When using the text approach, you need to navigate
down one more step to the XMLElement that contains
the text. Note the extra FirstChildElement( "v" )
in the code below. The value of the text can then
be safely queried with the QueryIntText() group
of methods. (Also QueryFloatText(), etc.)
@skip XMLElement* textApproachElement
@until &v1 );
*/
int main( int /*argc*/, const char ** /*argv*/ ) int main( int /*argc*/, const char ** /*argv*/ )

129
xmltest.h
View File

@ -1,129 +0,0 @@
// Purely doxygen documentation
// What follows is the docs for the examples.
// I'd like the docs to be just before the
// actual examples in xmltest.cpp, but I
// can't seem to get doxygen to do that. It
// would be a wonderful patch if anyone figures
// it out.
/** @page Example-1 Load an XML File
* @dontinclude ./xmltest.cpp
* Basic XML file loading.
* The basic syntax to load an XML file from
* disk and check for an error. (ErrorID()
* will return 0 for no error.)
* @skip example_1()
* @until }
*/
/** @page Example-2 Parse an XML from char buffer
* @dontinclude ./xmltest.cpp
* Basic XML string parsing.
* The basic syntax to parse an XML for
* a char* and check for an error. (ErrorID()
* will return 0 for no error.)
* @skip example_2()
* @until }
*/
/** @page Example-3 Get information out of XML
@dontinclude ./xmltest.cpp
In this example, we navigate a simple XML
file, and read some interesting text. Note
that this is examlpe doesn't use error
checking; working code should check for null
pointers when walking an XML tree, or use
XMLHandle.
(The XML is an excerpt from "dream.xml").
@skip example_3
@until </PLAY>";
The structure of the XML file is:
<ul>
<li>(declaration)</li>
<li>(dtd stuff)</li>
<li>Element "PLAY"</li>
<ul>
<li>Element "TITLE"</li>
<ul>
<li>Text "A Midsummer Night's Dream"</li>
</ul>
</ul>
</ul>
For this example, we want to print out the
title of the play. The text of the title (what
we want) is child of the "TITLE" element which
is a child of the "PLAY" element.
We want to skip the declaration and dtd, so the
method FirstChildElement() is a good choice. The
FirstChildElement() of the Document is the "PLAY"
Element, the FirstChildElement() of the "PLAY" Element
is the "TITLE" Element.
@until ( "TITLE" );
We can then use the convenience function GetText()
to get the title of the play.
@until title );
Text is just another Node in the XML DOM. And in
fact you should be a little cautious with it, as
text nodes can contain elements.
@verbatim
Consider: A Midsummer Night's <b>Dream</b>
@endverbatim
It is more correct to actually query the Text Node
if in doubt:
@until title );
Noting that here we use FirstChild() since we are
looking for XMLText, not an element, and ToText()
is a cast from a Node to a XMLText.
*/
/** @page Example-4 Read attributes and text information.
@dontinclude ./xmltest.cpp
There are fundamentally 2 ways of writing a key-value
pair into an XML file. (Something that's always annoyed
me about XML.) Either by using attributes, or by writing
the key name into an element and the value into
the text node wrapped by the element. Both approaches
are illustrated in this example, which shows two ways
to encode the value "2" into the key "v":
@skip example_4
@until "</information>";
TinyXML-2 has accessors for both approaches.
When using an attribute, you navigate to the XMLElement
with that attribute and use the QueryIntAttribute()
group of methods. (Also QueryFloatAttribute(), etc.)
@skip XMLElement* attributeApproachElement
@until &v0 );
When using the text approach, you need to navigate
down one more step to the XMLElement that contains
the text. Note the extra FirstChildElement( "v" )
in the code below. The value of the text can then
be safely queried with the QueryIntText() group
of methods. (Also QueryFloatText(), etc.)
@skip XMLElement* textApproachElement
@until &v1 );
*/