potok/tinyxml2
1
0
Fork 0
mirror of https://github.com/leethomason/tinyxml2.git synced 2026-07-21 19:23:00 +04:00
Code Packages Releases Wiki Activity

Improve README formatting with highlighted blocks (#1055)

Browse Source 
Improve README
This commit is contained in:
Miko
2026-05-23 19:18:19 -04:00
committed by GitHub
parent 8d8472fe1a
commit beb16fbca0
1 changed files with 121 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files
readme.md
+105 -90
View File
@@ -1,12 +1,11 @@
TinyXML-2 # TinyXML-2
=========
[![Test](https://github.com/leethomason/tinyxml2/actions/workflows/test.yml/badge.svg)](https://github.com/leethomason/tinyxml2/actions/workflows/test.yml) [![Test](https://github.com/leethomason/tinyxml2/actions/workflows/test.yml/badge.svg)](https://github.com/leethomason/tinyxml2/actions/workflows/test.yml)
TinyXML-2 is a simple, small, efficient, C++ XML parser that can be TinyXML-2 is a simple, small, efficient, C++ XML parser that can be
easily integrated into other programs. easily integrated into other programs.
The master is hosted on github: The master is hosted on GitHub:
https://github.com/leethomason/tinyxml2 https://github.com/leethomason/tinyxml2
The online HTML version of these docs: The online HTML version of these docs:
@@ -14,8 +13,7 @@ http://leethomason.github.io/tinyxml2/
Examples are in the "related pages" tab of the HTML docs. Examples are in the "related pages" tab of the HTML docs.
What it does. ## What it does.
-------------
In brief, TinyXML-2 parses an XML document, and builds from that a In brief, TinyXML-2 parses an XML document, and builds from that a
Document Object Model (DOM) that can be read, modified, and saved. Document Object Model (DOM) that can be read, modified, and saved.
@@ -37,7 +35,7 @@ code without creating a document first.
TinyXML-2 is designed to be easy and fast to learn. It is one header and TinyXML-2 is designed to be easy and fast to learn. It is one header and
one cpp file. Simply add these to your project and off you go. one cpp file. Simply add these to your project and off you go.
There is an example file - xmltest.cpp - to get you started. There is an example file - `xmltest.cpp` - to get you started.
TinyXML-2 is released under the ZLib license, TinyXML-2 is released under the ZLib license,
so you can use it in open source or commercial code. The details so you can use it in open source or commercial code. The details
@@ -45,10 +43,10 @@ of the license are at the top of every source file.
TinyXML-2 attempts to be a flexible parser, but with truly correct and TinyXML-2 attempts to be a flexible parser, but with truly correct and
compliant XML output. TinyXML-2 should compile on any reasonably C++ compliant XML output. TinyXML-2 should compile on any reasonably C++
compliant system. It does not rely on exceptions, RTTI, or the STL. compliant system. It does not rely on exceptions, run-time type information,
or the C++ Standard Library.
What it doesn't do. ## What it doesn't do.
-------------------
TinyXML-2 doesn't parse or use DTDs (Document Type Definitions) or XSLs TinyXML-2 doesn't parse or use DTDs (Document Type Definitions) or XSLs
(eXtensible Stylesheet Language.) There are other parsers out there (eXtensible Stylesheet Language.) There are other parsers out there
@@ -56,8 +54,7 @@ that are much more fully featured. But they are generally bigger and
more difficult to use. If you are working with more difficult to use. If you are working with
browsers or have more complete XML needs, TinyXML-2 is not the parser for you. browsers or have more complete XML needs, TinyXML-2 is not the parser for you.
TinyXML-1 vs. TinyXML-2 ## TinyXML-1 vs. TinyXML-2
-----------------------
TinyXML-2 has long been the focus of all development. It is well tested TinyXML-2 has long been the focus of all development. It is well tested
and should be used instead of TinyXML-1. and should be used instead of TinyXML-1.
@@ -67,10 +64,10 @@ rich test cases. But the implementation of the parser is completely re-written
to make it more appropriate for use in a game. It uses less memory, is faster, to make it more appropriate for use in a game. It uses less memory, is faster,
and uses far fewer memory allocations. and uses far fewer memory allocations.
TinyXML-2 has no requirement or support for STL. TinyXML-2 has no dependency on the C++ Standard Library, and does not adapt or use any
of its collection types either.
Features ## Features
--------
### Code Page ### Code Page
@@ -81,17 +78,17 @@ Filenames for loading / saving are passed unchanged to the underlying OS.
### Memory Model ### Memory Model
An XMLDocument is a C++ object like any other, that can be on the stack, or An `XMLDocument` is a C++ object like any other, that can be on the stack, or
new'd and deleted on the heap. `new`'d and `delete`d on the heap.
However, any sub-node of the Document, XMLElement, XMLText, etc, can only However, any sub-node of the `XMLDocument`, `XMLElement`, `XMLText`, etc, can only
be created by calling the appropriate XMLDocument::NewElement, NewText, etc. be created by calling the appropriate `XMLDocument::NewElement`, `XMLDocument::NewText`, etc.
method. Although you have pointers to these objects, they are still owned method. Although you have pointers to these objects, they are still owned
by the Document. When the Document is deleted, so are all the nodes it contains. by the `XMLDocument`. When the `XMLDocument` is `delete`d, so are all the nodes it contains.
### White Space ### White Space
#### Whitespace Preservation (default, PRESERVE_WHITESPACE) #### Whitespace Preservation (default, `PRESERVE_WHITESPACE`)
Microsoft has an excellent article on white space: http://msdn.microsoft.com/en-us/library/ms256097.aspx Microsoft has an excellent article on white space: http://msdn.microsoft.com/en-us/library/ms256097.aspx
@@ -103,51 +100,57 @@ line-feed character, as required by the XML spec.
White space in text is preserved. For example: White space in text is preserved. For example:
<element> Hello, World</element> ```xml
<element> Hello, World</element>
```
The leading space before the "Hello" and the double space after the comma are The leading space before the `"Hello"` and the double space after the comma are
preserved. Line-feeds are preserved, as in this example: preserved. Line-feeds are preserved, as in this example:
<element> Hello again, ```xml
<element> Hello again,
World</element> World</element>
```
However, white space between elements is **not** preserved. Although not strictly However, white space between elements is **not** preserved. Although not strictly
compliant, tracking and reporting inter-element space is awkward, and not normally compliant, tracking and reporting inter-element space is awkward, and not normally
valuable. TinyXML-2 sees these as the same XML: valuable. TinyXML-2 sees these as the same XML:
<document> ```xml
<document>
<data>1</data> <data>1</data>
<data>2</data> <data>2</data>
<data>3</data> <data>3</data>
</document> </document>
<document><data>1</data><data>2</data><data>3</data></document> <document><data>1</data><data>2</data><data>3</data></document>
```
#### Whitespace Collapse (COLLAPSE_WHITESPACE) #### Whitespace Collapse (`COLLAPSE_WHITESPACE`)
For some applications, it is preferable to collapse whitespace. Collapsing For some applications, it is preferable to collapse whitespace. Collapsing
whitespace gives you "HTML-like" behavior, which is sometimes more suitable whitespace gives you "HTML-like" behavior, which is sometimes more suitable
for hand typed documents. for hand typed documents.
TinyXML-2 supports this with the 'whitespace' parameter to the XMLDocument constructor. TinyXML-2 supports this with the `whitespace` parameter to the `XMLDocument` constructor.
(The default is to preserve whitespace, as described above.) (The default is to preserve whitespace, as described above.)
However, you may also use COLLAPSE_WHITESPACE, which will: However, you may also use `COLLAPSE_WHITESPACE`, which will:
* Remove leading and trailing whitespace * Remove leading and trailing whitespace
* Convert newlines and line-feeds into a space character * Convert newlines and line-feeds into a space character
* Collapse a run of any number of space characters into a single space character * Collapse a run of any number of space characters into a single space character
Note that (currently) there is a performance impact for using COLLAPSE_WHITESPACE. Note that (currently) there is a performance impact for using `COLLAPSE_WHITESPACE`.
It essentially causes the XML to be parsed twice. It essentially causes the XML to be parsed twice.
#### Pedantic Whitespace (PEDANTIC_WHITESPACE) #### Pedantic Whitespace (`PEDANTIC_WHITESPACE`)
For applications that need to know about text nodes that are composed entirely of For applications that need to know about text nodes that are composed entirely of
whitespace, PEDANTIC_WHITESPACE is available. PEDANTIC_WHITESPACE maintains all the whitespace, `PEDANTIC_WHITESPACE` is available. `PEDANTIC_WHITESPACE` maintains all the
whitespace between elements. whitespace between elements.
PEDANTIC_WHITESPACE is a new mode and not as tested as the other whitespace modes. `PEDANTIC_WHITESPACE` is a new mode and not as tested as the other whitespace modes.
### Error Reporting ### Error Reporting
@@ -163,18 +166,22 @@ line number information for error messages.
TinyXML-2 recognizes the pre-defined "character entities", meaning special TinyXML-2 recognizes the pre-defined "character entities", meaning special
characters. Namely: characters. Namely:
&amp; & ```html
&lt; < &amp; &
&gt; > &lt; <
&quot; " &gt; >
&apos; ' &quot; "
&apos; '
```
These are recognized when the XML document is read, and translated to their These are recognized when the XML document is read, and translated to their
UTF-8 equivalents. For instance, text with the XML of: UTF-8 equivalents. For instance, text with the XML of:
Far &amp; Away ```xml
Far &amp; Away
```
will have the Value() of "Far & Away" when queried from the XMLText object, will have the `Value()` of `"Far & Away"` when queried from the `XMLText` object,
and will be written back to the XML stream/file as an ampersand. and will be written back to the XML stream/file as an ampersand.
Additionally, any character can be specified by its Unicode code point: Additionally, any character can be specified by its Unicode code point:
@@ -188,21 +195,27 @@ regular code point. The output is correct, but the entity syntax isn't preserved
#### Print to file #### Print to file
You can directly use the convenience function: You can directly use the convenience function:
XMLDocument doc; ```cpp
... XMLDocument doc;
doc.SaveFile( "foo.xml" ); // ...
doc.SaveFile("foo.xml");
```
Or the XMLPrinter class: Or the `XMLPrinter` class:
XMLPrinter printer( fp ); ```cpp
doc.Print( &printer ); XMLPrinter printer(fp);
doc.Print(&printer);
```
#### Print to memory #### Print to memory
Printing to memory is supported by the XMLPrinter. Printing to memory is supported by the `XMLPrinter`.
XMLPrinter printer; ```cpp
doc.Print( &printer ); XMLPrinter printer;
// printer.CStr() has a const char* to the XML doc.Print(&printer);
// printer.CStr() has a const char* to the XML
```
#### Print without an XMLDocument #### Print without an XMLDocument
@@ -210,32 +223,36 @@ When loading, an XML parser is very useful. However, sometimes
when saving, it just gets in the way. The code is often set up when saving, it just gets in the way. The code is often set up
for streaming, and constructing the DOM is just overhead. for streaming, and constructing the DOM is just overhead.
The Printer supports the streaming case. The following code The `XMLPrinter` supports the streaming case. The following code
prints out a trivially simple XML file without ever creating prints out a trivially simple XML file without ever creating
an XML document. an XML document.
XMLPrinter printer( fp ); ```cpp
printer.OpenElement( "foo" ); XMLPrinter printer(fp);
printer.PushAttribute( "foo", "bar" ); printer.OpenElement("foo");
printer.CloseElement(); printer.PushAttribute("foo", "bar");
printer.CloseElement();
```
Examples ### Examples
--------
#### Load and parse an XML file. #### Load and parse an XML file.
/* ------ Example 1: Load and parse an XML file. ---- */ ```cpp
{ /* ------ Example 1: Load and parse an XML file. ---- */
{
XMLDocument doc; XMLDocument doc;
doc.LoadFile( "dream.xml" ); doc.LoadFile("dream.xml");
} }
```
#### Lookup information. #### Lookup information.
/* ------ Example 2: Lookup information. ---- */ ```cpp
{ /* ------ Example 2: Lookup information. ---- */
{
XMLDocument doc; XMLDocument doc;
doc.LoadFile( "dream.xml" ); doc.LoadFile("dream.xml");
// Structure of the XML file: // Structure of the XML file:
// - Element "PLAY" the root Element, which is the // - Element "PLAY" the root Element, which is the
@@ -245,57 +262,56 @@ Examples
// Navigate to the title, using the convenience function, // Navigate to the title, using the convenience function,
// with a dangerous lack of error checking. // with a dangerous lack of error checking.
const char* title = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->GetText(); const char* title = doc.FirstChildElement("PLAY")->FirstChildElement("TITLE")->GetText();
printf( "Name of play (1): %s\n", title ); printf("Name of play (1): %s\n", title);
// Text is just another Node to TinyXML-2. The more // Text is just another Node to TinyXML-2. The more
// general way to get to the XMLText: // general way to get to the XMLText:
XMLText* textNode = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->FirstChild()->ToText(); XMLText* textNode = doc.FirstChildElement("PLAY")->FirstChildElement("TITLE")->FirstChild()->ToText();
title = textNode->Value(); title = textNode->Value();
printf( "Name of play (2): %s\n", title ); printf("Name of play (2): %s\n", title);
} }
```
Using and Installing ## Using and Installing
--------------------
There are 2 files in TinyXML-2: There are 2 files in TinyXML-2:
* tinyxml2.cpp * `tinyxml2.cpp`
* tinyxml2.h * `tinyxml2.h`
And additionally a test file: And additionally a test file:
* xmltest.cpp * `xmltest.cpp`
Generally speaking, the intent is that you simply include the tinyxml2.cpp and Generally speaking, the intent is that you simply include the `tinyxml2.cpp` and
tinyxml2.h files in your project and build with your other source code. `tinyxml2.h` files in your project and build with your other source code.
There is also a CMake build included. CMake is the general build for TinyXML-2. There is also a CMake build included. CMake is the general build for TinyXML-2.
(Additional build systems are costly to maintain, and tend to become outdated. They are (Additional build systems are costly to maintain, and tend to become outdated. They are
being removed over time.) being removed over time.)
Building TinyXML-2 - Using vcpkg ### Building TinyXML-2 - Using vcpkg
--------------------------------
You can download and install TinyXML-2 using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager: You can download and install TinyXML-2 using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
git clone https://github.com/Microsoft/vcpkg.git ```sh
cd vcpkg git clone https://github.com/Microsoft/vcpkg.git
./bootstrap-vcpkg.sh cd vcpkg
./vcpkg integrate install ./bootstrap-vcpkg.sh
./vcpkg install tinyxml2 ./vcpkg integrate install
./vcpkg install tinyxml2
```
The TinyXML-2 port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository. The TinyXML-2 port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
Versioning ## Versioning
----------
TinyXML-2 uses semantic versioning. http://semver.org/ Releases are now tagged in github. TinyXML-2 uses semantic versioning. http://semver.org/ Releases are now tagged in GitHub.
Note that the major version will (probably) change fairly rapidly. API changes are fairly Note that the major version will (probably) change fairly rapidly. API changes are fairly
common. common.
License ## License
-------
TinyXML-2 is released under the zlib license: TinyXML-2 is released under the zlib license:
@@ -316,8 +332,7 @@ must not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source 3. This notice may not be removed or altered from any source
distribution. distribution.
Contributors ## Contributors
------------
Thanks very much to everyone who sends suggestions, bugs, ideas, and Thanks very much to everyone who sends suggestions, bugs, ideas, and
encouragement. It all helps, and makes this project fun. encouragement. It all helps, and makes this project fun.