pugixml 0.9

The distribution contains library source, documentation (the guide you're reading now and the manual) and some code examples. After downloading the distribution, install pugixml by extracting all files from the compressed - archive. + archive. The files have different line endings depending on the archive format + - .zip archive has Windows line endings, .tar.gz archive has Unix line endings. + Otherwise the files in both archives are identical.

- The complete pugixml source consists of four files - two source files, pugixml.cpp and - pugixpath.cpp, and two header files, pugixml.hpp and pugiconfig.hpp. pugixml.hpp is - the primary header which you need to include in order to use pugixml classes/functions. + The complete pugixml source consists of three files - one source file, pugixml.cpp, + and two header files, pugixml.hpp and pugiconfig.hpp. pugixml.hpp is the primary + header which you need to include in order to use pugixml classes/functions. The rest of this guide assumes that pugixml.hpp is either in the current directory or in one of include directories of your projects, so that #include "pugixml.hpp" can find the header; however you can also use relative path (i.e. #include "../libs/pugixml/src/pugixml.hpp") @@ -94,13 +97,14 @@ <xml/thirdparty/pugixml/src/pugixml.hpp>).

- The easiest way to build pugixml is to compile two source files, pugixml.cpp and - pugixpath.cpp, along with the existing library/executable. This process depends - on the method of building your application; for example, if you're using - Microsoft Visual Studio^[1], Apple Xcode, Code::Blocks or any other IDE, just add - pugixml.cpp and pugixpath.cpp to one of your projects. There are other building - methods available, including building pugixml as a standalone static/shared - library; read the manual for further information. + The easiest way to build pugixml is to compile the source file, pugixml.cpp, + along with the existing library/executable. This process depends on the method + of building your application; for example, if you're using Microsoft Visual + Studio^[1], + Apple Xcode, Code::Blocks or any other IDE, just add pugixml.cpp to one of + your projects. There are other building methods available, including building + pugixml as a standalone static/shared library; read + the manual for further information.

@@ -176,11 +180,10 @@ xml_document is the owner of the entire document structure; destroying the document destroys the whole tree. The interface of xml_document - consists of loading functions, saving functions and the interface of xml_node, which allows for document inspection - and/or modification. Note that while xml_document - is a sub-class of xml_node, - xml_node is not a polymorphic - type; the inheritance is only used to simplify usage. + consists of loading functions, saving functions and the entire interface + of xml_node, which allows + for document inspection and/or modification. Note that while xml_document is a sub-class of xml_node, xml_node + is not a polymorphic type; the inheritance is present only to simplify usage.

xml_node is the handle to @@ -208,8 +211,8 @@ xml_attribute is the handle to an XML attribute; it has the same semantics as xml_node, i.e. there can be several xml_attribute - handles pointing to the same underlying object, there is a special null attribute - value, which propagates to function results. + handles pointing to the same underlying object and there is a special null + attribute value, which propagates to function results.

There are two choices of interface and internal representation when configuring @@ -217,8 +220,8 @@ UTF-16/32 (also called wchar_t) one. The choice is controlled via PUGIXML_WCHAR_MODE define; you can set it via pugiconfig.hpp or via preprocessor options. All tree functions that work with strings work with either C-style null terminated strings or STL - strings of the selected character type. Read the manual for additional information - on Unicode interface. + strings of the selected character type. Read + the manual for additional information on Unicode interface.

@@ -601,13 +604,13 @@

- Nodes and attributes do not exist outside of document tree, so you can't - create them without adding them to some document. A node or attribute can - be created at the end of node/attribute list or before/after some other node. - All insertion functions return the handle to newly created object on success, - and null handle on failure. Even if the operation fails (for example, if - you're trying to add a child node to PCDATA node), the document remains in - consistent state, but the requested node/attribute is not added. + Nodes and attributes do not exist without a document tree, so you can't create + them without adding them to some document. A node or attribute can be created + at the end of node/attribute list or before/after some other node. All insertion + functions return the handle to newly created object on success, and null + handle on failure. Even if the operation fails (for example, if you're trying + to add a child node to PCDATA node), the document remains in consistent state, + but the requested node/attribute is not added.

@@ -628,17 +631,14 @@

// add node with some name
-pugi::xml_node node = doc.append_child();
-node.set_name("node");
+pugi::xml_node node = doc.append_child("node");
 
 // add description node with text child
-pugi::xml_node descr = node.append_child();
-descr.set_name("description");
+pugi::xml_node descr = node.append_child("description");
 descr.append_child(pugi::node_pcdata).set_value("Simple node");
 
 // add param node before the description
-pugi::xml_node param = node.insert_child_before(pugi::node_element, descr);
-param.set_name("param");
+pugi::xml_node param = node.insert_child_before("param", descr);
 
 // add attributes to param node
 param.append_attribute("name") = "version";
@@ -647,7 +647,7 @@

If you do not want your document to contain some node or attribute, you can remove it with remove_attribute and remove_child functions. @@ -693,12 +693,12 @@ encoding conversions.

- The node/attribute data is written to the destination properly formatted + Before writing to the destination the node/attribute data is properly formatted according to the node type; all special XML symbols, such as < and &, are properly escaped. In order to guard against forgotten node/attribute names, empty node/attribute names are printed as ":anonymous". - For proper output, make sure all node and attribute names are set to meaningful - values. + For well-formed output, make sure all node and attribute names are set to + meaningful values.

If you want to save the whole document to a file, you can use the save_file function, which returns true on success. This is a simple example @@ -713,11 +713,11 @@

- For additional interoperability pugixml provides functions for saving document - to any object which implements C++ std::ostream interface. This allows you - to save documents to any standard C++ stream (i.e. file stream) or any third-party - compliant implementation (i.e. Boost Iostreams). Most notably, this allows - for easy debug output, since you can use std::cout + To enhance interoperability pugixml provides functions for saving document + to any object which implements C++ std::ostream + interface. This allows you to save documents to any standard C++ stream (i.e. + file stream) or any third-party compliant implementation (i.e. Boost Iostreams). + Most notably, this allows for easy debug output, since you can use std::cout stream as saving target. There are two functions, one works with narrow character streams, another handles wide character ones.

@@ -763,11 +763,12 @@

- While the previously described functions saved the whole document to the - destination, it is easy to save a single subtree. Instead of calling xml_document::save, just call xml_node::print - function on the target node. You can save node contents to C++ IOstream object - or custom writer in this way. Saving a subtree slightly differs from saving - the whole document; read the manual for more information. + While the previously described functions save the whole document to the destination, + it is easy to save a single subtree. Instead of calling xml_document::save, + just call xml_node::print function on the target node. You + can save node contents to C++ IOstream object or custom writer in this way. + Saving a subtree slightly differs from saving the whole document; read the manual for + more information.

@@ -819,16 +820,25 @@ IN THE SOFTWARE.

+ This means that you can freely use pugixml in your applications, both open-source + and proprietary. If you use pugixml in a product, it is sufficient to add + an acknowledgment like this to the product distribution: +

+ This software is based on pugixml library (http://pugixml.org).
+pugixml + is Copyright (C) 2006-2010 Arseny Kapoulkine. +

^[1]All trademarks used are properties of their - respective owners.

^[1]All trademarks used are properties of their respective owners.

- +

Last revised: July 15, 2010 at 17:02:03 GMT

Last revised: October 31, 2010 at 07:44:52 GMT

-- cgit v1.2.3

- pugixml 0.9 quick start guide + pugixml 1.0 quick start guide