MezzanineEngine 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Classes | Typedefs | Enumerations | Functions | Variables
Mezzanine::XML Namespace Reference

All tools for working with XML are located in this namespace. More...

Classes

class  Attribute
 A light-weight handle for manipulating attributes in DOM tree. More...
 
class  AttributeIterator
 Attribute iterator (a bidirectional iterator over a collection of Attribute). More...
 
class  Document
 The root node of any xml hierarchy is a Document. More...
 
class  NamedNodeIterator
 Child node iterator (a forward iterator over a collection of Node) only iterates over nodes with a given name. More...
 
class  Node
 A light-weight handle for manipulating nodes in DOM tree. More...
 
class  NodeIterator
 Child node iterator (a bidirectional iterator over a collection of Node) More...
 
class  NodeText
 A helper for working with text inside PCDATA nodes. More...
 
class  ObjectRange
 Used by the xml system to pass around iterable ranges. More...
 
struct  ParseResult
 Troubleshooting data intended to help troublshoot XML parsing errors. More...
 
class  TreeWalker
 Used to call a function OnEachNode member of the subtree of nodes descended from a specific node. More...
 
class  Writer
 Interface for node printing (see Node::Print) More...
 
class  WriterFile
 An implementation of Writer intended for writing to FILEs as defined in stdio. More...
 
class  WriterStream
 An implementation of Writer intended for writing std::ostreams. More...
 
class  XMLStreamWrapper
 This represents a simple wrapper that makes data streams compatible with the XML API. More...
 
class  XPathNode
 An XPath node which can store handles to a XML::Node or an XML::Attribute. More...
 
class  XPathNodeSet
 A fixed sized collection of nodes that an XPathQuery can work on. More...
 
struct  XPathParseResult
 XPath parsing result. More...
 
class  XPathQuery
 A compiled XPath query object. More...
 
class  XPathVariable
 A single XPath variable. More...
 
class  XPathVariableSet
 A set of XPath variables. More...
 

Typedefs

typedef void *(* AllocationFunction )(size_t size)
 Memory allocation function interface; returns pointer to allocated memory or NULL on failure.
 
typedef void(* DeAllocationFunction )(void *ptr)
 Function pointer type for a memory deallocation function interface.
 

Enumerations

enum  Encoding {
  EncodingAuto, EncodingUTF8, EncodingUTF16LE, EncodingUTF16BE,
  EncodingUTF16, EncodingUTF32LE, EncodingUTF32BE, EncodingUTF32,
  Encodingwchar_t, EncodingLatin1
}
 These flags determine the encoding of input data for an XML document. More...
 
enum  NodeType {
  NodeNull, NodeDocument, NodeElement, NodePcdata,
  NodeCdata, NodeComment, NodePi, NodeDeclaration,
  NodeDocType
}
 The types of nodes that could be in the XML Tree. More...
 
enum  ParseStatus {
  StatusOk = 0, StatusFileNotFound, StatusIOError, StatusOutOfMemory,
  StatusInternalError, StatusUnrecognizedTag, StatusBadProcessingInstruction, StatusBadComment,
  StatusBadCdata, StatusBadDocType, StatusBadPcdata, StatusBadStartElement,
  StatusBadAttribute, StatusBadEndElement, StatusEndElementMismatch
}
 These statuses are used to help determine what issues, if any the parser had. Returned by Mezzanine::XML::ParseResult instances. More...
 
enum  XPathValueType {
  XPathTypeNone, XPathTypeNodeSet, XPathTypeNumber, XPathTypeString,
  XPathTypeBoolean
}
 XPathQuery return type. More...
 

Functions

std::basic_string< char,
std::char_traits< char >
, std::allocator< char >
> MEZZ_LIB 
AsUtf8 (const wchar_t *str)
 Convert a c-style string of wchar_t to std::string containing UTF8. More...
 
std::basic_string< char,
std::char_traits< char >
, std::allocator< char >
> MEZZ_LIB 
AsUtf8 (const std::basic_string< wchar_t, std::char_traits< wchar_t >, std::allocator< wchar_t > > &str)
 Convert a std::wstring to a UTF8 std::string. More...
 
std::basic_string< wchar_t,
std::char_traits< wchar_t >
, std::allocator< wchar_t >
> MEZZ_LIB 
AsWide (const char *str)
 Convert a Convert a c-style string to std::wstring containing native encoding (Usually UCS2 on windows and UTF32 on Linux/Mac). More...
 
std::basic_string< wchar_t,
std::char_traits< wchar_t >
, std::allocator< wchar_t >
> MEZZ_LIB 
AsWide (const std::basic_string< char, std::char_traits< char >, std::allocator< char > > &str)
 Convert a Convert a std::string to std::wstring containing native encoding (Usually UCS2 on windows and UTF32 on Linux/Mac). More...
 
String EscapeXML (const String &XMLText)
 Convert < > & and " in text to &lt;, &gt;, &amp; and &quote so text can safely be stored in XML. More...
 
AllocationFunction MEZZ_LIB GetMemoryAllocationFunction ()
 Get the current allocation funciton. More...
 
DeAllocationFunction MEZZ_LIB GetMemoryDeallocationFunction ()
 Get the current allocation funciton. More...
 
String GetOneTag (std::istream &stream)
 Gets the first tag out of the Stream and returns it as a String. More...
 
DocumentPreParseClassFromSingleTag (const String &NameSpace, const String &ClassName, const String &OneTag)
 Perform a basic series of checks for extracting meaning from a single xml tag. More...
 
DocumentPreParseClassFromSingleTag (const String &ClassName, const String &OneTag)
 Calls PreParseClassFromSingleTag passing a "" as the Namespace. More...
 
void MEZZ_LIB SetMemoryManagementFunctions (AllocationFunction allocate, DeAllocationFunction deallocate)
 Override default memory management functions. All subsequent allocations/deallocations will be performed via supplied functions. More...
 

Variables

const unsigned int FormatDefault = FormatRaw
 The default set of formatting flags. Only FormatRaw is enabled. More...
 
const unsigned int FormatIndent = 0x01
 Indent the nodes that are written to output stream with as many indentation strings as deep the node is in DOM tree. This flag is off by default.
 
const unsigned int FormatNoDeclaration = 0x08
 Omit default XML declaration even if there is no declaration in the document. This flag is off by default.
 
const unsigned int FormatNoEscapes = 0x10
 Don't escape GetAttribute Values and PCDATA contents. This flag is off by default.
 
const unsigned int FormatRaw = 0x04
 Use raw output mode (no indentation and no line breaks are written). This flag is on by default.
 
const unsigned int FormatSaveFileText = 0x20
 Open file using text mode in XML::Document::SaveFile. This enables special character (i.e. new-line) conversions on some systems. This flag is off by default.
 
const unsigned int FormatWriteBom = 0x02
 Write encoding-specific Byte Order Mark (BOM) to the output stream. This flag is off by default.
 
const unsigned int ParseCdata = 0x0004
 This flag determines if CDATA sections (NodeCdata) are added to the DOM tree. This flag is on by default.
 
const unsigned int ParseComments = 0x0002
 This flag determines if comments (NodeComment) are added to the DOM tree. This flag is off by default.
 
const unsigned int ParseDeclaration = 0x0100
 This flag determines if document declaration (NodeDeclaration) is added to the DOM tree. This flag is off by default.
 
const unsigned int ParseDefault = ParseCdata | ParseEscapes | ParseWconvAttribute | ParseEol
 The default parsing mode. More...
 
const unsigned int ParseDocType = 0x0200
 This flag determines if document type declaration (NodeDoctype) is added to the DOM tree. This flag is off by default.
 
const unsigned int ParseEol = 0x0020
 This flag determines if EOL characters are normalized (converted to #xA) during parsing. This flag is on by default.
 
const unsigned int ParseEscapes = 0x0010
 This flag determines if character and entity references are expanded during parsing. This flag is on by default.
 
const unsigned int ParseFull = ParseDefault | ParsePi | ParseComments | ParseDeclaration | ParseDocType
 The full parsing mode. More...
 
const unsigned int ParseMinimal = 0x0000
 Minimal parsing mode (equivalent to turning all other flags off). More...
 
const unsigned int ParsePi = 0x0001
 This flag determines if processing instructions (NodePi) are added to the DOM tree. This flag is off by default.
 
const unsigned int ParseWconvAttribute = 0x0040
 This flag determines if attribute values are normalized using CDATA normalization rules during parsing. This flag is on by default.
 
const unsigned int ParseWnormAttribute = 0x0080
 This flag determines if attribute values are normalized using NMTOKENS normalization rules during parsing. This flag is off by default.
 
const unsigned int ParseWsPcdata = 0x0008
 This flag determines if plain character data (NodePcdata) that consist only of whitespace are added to the DOM tree. More...
 
const unsigned int ParseWsPcdata_single = 0x0400
 This flag determines if plain character data (NodePcdata) that is the only child of the parent node and that consists only of whitespace is added to the DOM tree. More...
 

Detailed Description

All tools for working with XML are located in this namespace.

The contents of this namespace has many details covered in the Mezzanine::xml Manual

Enumeration Type Documentation

These flags determine the encoding of input data for an XML document.

Enumerator
EncodingAuto 

Auto-detect input DocumentEncoding using BOM or < / <? detection; use UTF8 if BOM is not found.

EncodingUTF8 

UTF8 DocumentEncoding.

EncodingUTF16LE 

Little-endian UTF16.

EncodingUTF16BE 

Big-endian UTF16n.

EncodingUTF16 

UTF16 with native endianness.

EncodingUTF32LE 

Little-endian UTF32.

EncodingUTF32BE 

Big-endian UTF32.

EncodingUTF32 

UTF32 with native endianness.

Encodingwchar_t 

The same document encoding wchar_t has (usually either UTF16 or UTF32)

EncodingLatin1 

Also called IEC_8859-1 a common encoding on windows, see http://en.wikipedia.org/wiki/ISO/IEC_8859-1 for furhter.

Definition at line 111 of file xmlenumerations.h.

The types of nodes that could be in the XML Tree.

Enumerator
NodeNull 

Empty (null) node handle.

NodeDocument 

A document tree's absolute GetRoot.

NodeElement 

Element tag, i.e. '<node/>'.

NodePcdata 

Plain character data, i.e. 'text'.

NodeCdata 

Character data, i.e. '<![CDATA[text]]>'.

NodeComment 

Comment tag, i.e. '<!– text –>'.

NodePi 

Processing instruction, i.e. '<?Name?>'.

NodeDeclaration 

Document declaration, i.e. '<?xml version="1.0"?>'.

NodeDocType 

Document Type declaration, i.e. '<!DOCTYPE doc>'.

Definition at line 144 of file xmlenumerations.h.

These statuses are used to help determine what issues, if any the parser had. Returned by Mezzanine::XML::ParseResult instances.

Enumerator
StatusOk 

This is returned to indicated there where no issues parsing the XML document.

StatusFileNotFound 

File was not found during a loading from filename attempt.

StatusIOError 

Error reading from file or stream.

StatusOutOfMemory 

Could not allocate memory.

StatusInternalError 

An unkown error, currently nothing should be able to return this status.

StatusUnrecognizedTag 

The parser could not determine type of tag.

StatusBadProcessingInstruction 

Parsing error occurred while parsing document declaration/processing instruction.

StatusBadComment 

Parsing error occurred while parsing comment.

StatusBadCdata 

Parsing error occurred while parsing CDATA section.

StatusBadDocType 

Parsing error occurred while parsing document type declaration.

StatusBadPcdata 

Parsing error occurred while parsing PCDATA section.

StatusBadStartElement 

Parsing error occurred while parsing start element tag.

StatusBadAttribute 

Parsing error occurred while parsing element attribute.

StatusBadEndElement 

Parsing error occurred while parsing end element tag.

StatusEndElementMismatch 

There was a mismatch of start-end tags (closing tag had incorrect name, some tag was not closed or there was an excessive closing tag).

Definition at line 158 of file xmlenumerations.h.

XPathQuery return type.

Enumerator
XPathTypeNone 

Unknown Type (query failed to compile)

XPathTypeNodeSet 

Node set (XPathNodeSet)

XPathTypeNumber 

Number This corresponds to a double or Real.

XPathTypeString 

Corresponds to the String type.

XPathTypeBoolean 

Boolean.

Definition at line 182 of file xmlenumerations.h.

Function Documentation

std::basic_string<char, std::char_traits<char>, std::allocator<char> > MEZZ_LIB Mezzanine::XML::AsUtf8 ( const wchar_t *  str)

Convert a c-style string of wchar_t to std::string containing UTF8.

Parameters
strThe wide string to convert
Returns
A std::basic_string<char, std::char_traits<char>, std::allocator<char> > containing the converted data
std::basic_string<char, std::char_traits<char>, std::allocator<char> > MEZZ_LIB Mezzanine::XML::AsUtf8 ( const std::basic_string< wchar_t, std::char_traits< wchar_t >, std::allocator< wchar_t > > &  str)

Convert a std::wstring to a UTF8 std::string.

Parameters
strThe wide string to convert.
Returns
A std::basic_string<char, std::char_traits<char>, std::allocator<char> > containing the converted data
std::basic_string<wchar_t, std::char_traits<wchar_t>, std::allocator<wchar_t> > MEZZ_LIB Mezzanine::XML::AsWide ( const char *  str)

Convert a Convert a c-style string to std::wstring containing native encoding (Usually UCS2 on windows and UTF32 on Linux/Mac).

Parameters
strThe string to convert.
Returns
A std::basic_string<wchar_t, std::char_traits<wchar_t>, std::allocator<wchar_t> > containing the converted data
std::basic_string<wchar_t, std::char_traits<wchar_t>, std::allocator<wchar_t> > MEZZ_LIB Mezzanine::XML::AsWide ( const std::basic_string< char, std::char_traits< char >, std::allocator< char > > &  str)

Convert a Convert a std::string to std::wstring containing native encoding (Usually UCS2 on windows and UTF32 on Linux/Mac).

Parameters
strThe string to convert.
Returns
A std::basic_string<wchar_t, std::char_traits<wchar_t>, std::allocator<wchar_t> > containing the converted data
String MEZZ_LIB Mezzanine::XML::EscapeXML ( const String &  XMLText)

Convert < > & and " in text to &lt;, &gt;, &amp; and &quote so text can safely be stored in XML.

Usually this is not required. Entering text into an XML::Attribute or and XML::Node will correctly escape it. Use this when you will be creating raw xml want to safely escape these characters.

Parameters
XMLTextThe Text to convert to xml safe text
Returns
a String containing the escaped version of XMLText

Definition at line 144 of file xmlstring.cpp.

AllocationFunction MEZZ_LIB Mezzanine::XML::GetMemoryAllocationFunction ( )

Get the current allocation funciton.

Returns
A function pointer of type AllocationFunction to the current allocation function
DeAllocationFunction MEZZ_LIB Mezzanine::XML::GetMemoryDeallocationFunction ( )

Get the current allocation funciton.

Returns
A function pointer of the type DeAllocationFunction to the current allocation function
String MEZZ_LIB Mezzanine::XML::GetOneTag ( std::istream &  stream)

Gets the first tag out of the Stream and returns it as a String.

Parameters
streamAn std::ostream that contains atleast one xml tag
Returns
This gets one XML tag, its closing tage, and all subtags.

Definition at line 72 of file xmlstring.cpp.

Document *MEZZ_LIB Mezzanine::XML::PreParseClassFromSingleTag ( const String &  NameSpace,
const String &  ClassName,
const String &  OneTag 
)

Perform a basic series of checks for extracting meaning from a single xml tag.

Parameters
NameSpaceUsed when throwing exceptions, this is a string containing the namespace and colons of a class to be deserialized for example "Mezzanine::"
ClassNameThis will be used to identify the main xml element/tag you are attempting to deserialize. This will also be used in error messages.
OneTagOne XML tag/elements worth of text to deserialize.
Returns
A pointer to XML::Document that you are now the owner of and must delete, that has the data parse and ready to access.
Exceptions
Thiscan throw a Mezzanine::exception in the event that the xml cannot be parsed.

Definition at line 116 of file xmlstring.cpp.

Document *MEZZ_LIB Mezzanine::XML::PreParseClassFromSingleTag ( const String &  ClassName,
const String &  OneTag 
)

Calls PreParseClassFromSingleTag passing a "" as the Namespace.

Parameters
ClassNameThis will be used to identify the main xml element/tag you are attempting to deserialize. This will also be used in error messages.
OneTagOne XML tag/elements worth of text to deserialize.
Returns
A pointer to XML::Document that you are now the owner of and must delete, that has the data parse and ready to access.
Exceptions
Thiscan throw a Mezzanine::exception in the event that the xml cannot be parsed.

Definition at line 141 of file xmlstring.cpp.

void MEZZ_LIB Mezzanine::XML::SetMemoryManagementFunctions ( AllocationFunction  allocate,
DeAllocationFunction  deallocate 
)

Override default memory management functions. All subsequent allocations/deallocations will be performed via supplied functions.

Parameters
allocateThe new memory allocator
deallocateThe new memory deallocator

Variable Documentation

const unsigned int Mezzanine::XML::FormatDefault = FormatRaw

The default set of formatting flags. Only FormatRaw is enabled.

Note
PugiXML defaults to FormatIndent which is not well suited to computer to computer transmission as games commonly do

Definition at line 141 of file xmlenumerations.h.

const unsigned int Mezzanine::XML::ParseDefault = ParseCdata | ParseEscapes | ParseWconvAttribute | ParseEol

The default parsing mode.

Elements, PCDATA and CDATA sections are added to the DOM tree, character/reference entities are expanded, End-of-Line characters are normalized, attribute values are normalized using CDATA normalization rules.

Definition at line 104 of file xmlenumerations.h.

const unsigned int Mezzanine::XML::ParseFull = ParseDefault | ParsePi | ParseComments | ParseDeclaration | ParseDocType

The full parsing mode.

Nodes of all types are added to the DOM tree, character/reference entities are expanded, End-of-Line characters are normalized, attribute values are normalized using CDATA normalization rules.

Definition at line 108 of file xmlenumerations.h.

const unsigned int Mezzanine::XML::ParseMinimal = 0x0000

Minimal parsing mode (equivalent to turning all other flags off).

Only elements and PCDATA sections are added to the DOM tree, no text conversions are performed.

Definition at line 75 of file xmlenumerations.h.

const unsigned int Mezzanine::XML::ParseWsPcdata = 0x0008

This flag determines if plain character data (NodePcdata) that consist only of whitespace are added to the DOM tree.

This flag is off by default; turning it on usually results in slower parsing and more memory consumption.

Definition at line 84 of file xmlenumerations.h.

const unsigned int Mezzanine::XML::ParseWsPcdata_single = 0x0400

This flag determines if plain character data (NodePcdata) that is the only child of the parent node and that consists only of whitespace is added to the DOM tree.

This flag is off by default; turning it on may Result in slower parsing and more memory consumption.

Definition at line 99 of file xmlenumerations.h.