XML (Extensible Markup Language) document node. More...

#include <XmlDocument.h>

Inheritance diagram for PLCore::XmlDocument:

Public Member Functions
PLCORE_API	XmlDocument ()
	Default constructor.
PLCORE_API	XmlDocument (const String &sName)
	Constructor.
PLCORE_API	XmlDocument (const XmlDocument &cSource)
	Copy constructor.
virtual PLCORE_API	~XmlDocument ()
	Destructor.
PLCORE_API XmlDocument &	operator= (const XmlDocument &cSource)
	Copy operator.
bool	Load (EEncoding nEncoding=EncodingUnknown)
	Load a file using the current document value.
PLCORE_API bool	Load (const String &sFilename, EEncoding nEncoding=EncodingUnknown)
	Load a file using the given filename.
PLCORE_API bool	Load (File &cFile, EEncoding nEncoding=EncodingUnknown)
	Loads from a given file.
bool	Save ()
	Save a file using the current document value.
PLCORE_API bool	Save (const String &sFilename)
	Save a file using the given filename.
XmlElement *	GetRootElement ()
	Get the root element -- the only top level element -- of the document.
const XmlElement *	GetRootElement () const
bool	Error () const
	If an error occurs, error will be set to true.
PLCORE_API String	GetErrorDesc (bool bLocation=true) const
	Contains a textual (english) description of the error if one occurs.
int	GetErrorID () const
	Generally, you probably want the error string ('GetErrorDesc()') - but if you prefer the error ID, this function will fetch it.
int	GetErrorRow () const
	Returns the location (if known) of the error.
int	GetErrorColumn () const
	The column where the error occurred.
uint32	GetTabSize () const
	Returns the tab size.
void	SetTabSize (uint32 nTabSize=4)
	Sets the tab size.
PLCORE_API void	ClearError ()
	If you have handled the error, it can be reset with this call.
virtual PLCORE_API bool	Save (File &cFile, uint32 nDepth=0) override
	Save function.
virtual PLCORE_API String	ToString (uint32 nDepth=0) const override
	Output as string function.
virtual PLCORE_API const char *	Parse (const char pszData, XmlParsingData pData=nullptr, EEncoding nEncoding=EncodingUnknown) override
	Parse the given null terminated block of XML data.
virtual PLCORE_API XmlNode *	Clone () const override
	Create an exact duplicate of this node and return it.

Detailed Description

XML (Extensible Markup Language) document node.

Remarks:: Always the top level node. A document binds together all the XML pieces. It can be saved, loaded, and printed to the screen. The 'value' of a document node is the XML filename.

The XML DOM parser is basing on TinyXML (http://www.sourceforge.net/projects/tinyxml).

Constructor & Destructor Documentation

PLCORE_API PLCore::XmlDocument::XmlDocument ( )

Default constructor.

PLCORE_API PLCore::XmlDocument::XmlDocument ( const String & sName )

Constructor.

Parameters:

[in] sName Document name. The name of the document is also the filename of the XML.

PLCORE_API PLCore::XmlDocument::XmlDocument ( const XmlDocument & cSource )

Copy constructor.

Parameters:

[in] cSource Source to copy from

virtual PLCORE_API PLCore::XmlDocument::~XmlDocument ( ) [virtual]

Destructor.

Member Function Documentation

PLCORE_API XmlDocument& PLCore::XmlDocument::operator= ( const XmlDocument & cSource )

Copy operator.

Parameters:

[in] cSource Source to copy from

Returns:: Reference to this instance

bool PLCore::XmlDocument::Load ( EEncoding nEncoding = EncodingUnknown ) [inline]

Load a file using the current document value.

Parameters:

[in] nEncoding Encoding

Returns:: Returns 'true' if successful, else 'false'

Note:

Will delete any existing document data before loading

PLCORE_API bool PLCore::XmlDocument::Load	(	const String &	sFilename,
		EEncoding	nEncoding = `EncodingUnknown`
	)

Load a file using the given filename.

Parameters:

[in]	sFilename	Filename
[in]	nEncoding	Encoding

Returns:: Returns 'true' if successful, else 'false'

Note:

The document value is set to 'sFilename'

PLCORE_API bool PLCore::XmlDocument::Load	(	File &	cFile,
		EEncoding	nEncoding = `EncodingUnknown`
	)

Loads from a given file.

Parameters:

[in]	cFile	File to read from, must be opened and readable
[in]	nEncoding	Encoding

Returns:: 'true' if all went fine, else 'false'

bool PLCore::XmlDocument::Save ( ) [inline]

Save a file using the current document value.

Returns:: Returns 'true' if successful, else 'false'

PLCORE_API bool PLCore::XmlDocument::Save ( const String & sFilename )

Save a file using the given filename.

Parameters:

[in] sFilename Filename

Returns:: Returns 'true' if successful, else 'false'

Note:

The document value is set to 'sFilename'

XmlElement * PLCore::XmlDocument::GetRootElement ( ) [inline]

Get the root element -- the only top level element -- of the document.

Returns:: The root element, a null pointer on error

Note:

In well formed XML, there should only be one. This parser is tolerant of multiple elements at the document level

const XmlElement * PLCore::XmlDocument::GetRootElement ( ) const [inline]

bool PLCore::XmlDocument::Error ( ) const [inline]

If an error occurs, error will be set to true.

Returns:: 'true' if an error occurs, else 'false'

Note:

'GetErrorID()' will contain the integer identifier of the error (not generally useful)
'GetErrorDesc()' will return the name of the error. (very useful)
'GetErrorRow()' and 'GetErrorColumn()' will return the location of the error (if known)

PLCORE_API String PLCore::XmlDocument::GetErrorDesc ( bool bLocation = true ) const

Contains a textual (english) description of the error if one occurs.

Parameters:

[in] bLocation Do also add the location (if known) of the error?

Returns:: Error description

int PLCore::XmlDocument::GetErrorID ( ) const [inline]

Generally, you probably want the error string ('GetErrorDesc()') - but if you prefer the error ID, this function will fetch it.

Returns:: Error ID

int PLCore::XmlDocument::GetErrorRow ( ) const [inline]

Returns the location (if known) of the error.

Remarks:: The first column is column 1, and the first row is row 1. A value of 0 means the row and column wasn't applicable (memory errors, for example, have no row/column) or the parser lost the error. (An error in the error reporting, in that case.)

Returns:: Row the error occurred

See also:

SetTabSize(), GetRow() and GetColumn()

int PLCore::XmlDocument::GetErrorColumn ( ) const [inline]

The column where the error occurred.

Returns:: Column the error occurred

See also:

GetErrorRow()

uint32 PLCore::XmlDocument::GetTabSize ( ) const [inline]

Returns the tab size.

Returns:: Tab size

void PLCore::XmlDocument::SetTabSize ( uint32 nTabSize = 4 ) [inline]

Sets the tab size.

Parameters:

[in] nTabSize New tab size

Remarks:

By calling this method, with a tab size greater than 0, the row and column of each node and attribute is stored when the file is loaded. Very useful for tracking the DOM back in to the source file. The tab size is required for calculating the location of nodes. If not set, the default of 4 is used. The tab size is set per document. Setting the tab size to 0 disables row/column tracking. Note that row and column tracking is not supported when using operator '>>' The tab size needs to be enabled before the parse or load. Correct usage:

		*    XmlDocument cDocument;
		*    cDocument.SetTabSize(8);
		*    cDocument.Load("myfile.xml");
		*

See also:

GetRow() and GetColumn()

PLCORE_API void PLCore::XmlDocument::ClearError ( )

If you have handled the error, it can be reset with this call.

Note:

The error state is automatically cleared if you parse a new XML block

virtual PLCORE_API bool PLCore::XmlDocument::Save	(	File &	cFile,
		uint32	nDepth = `0`
	)		`[override, virtual]`

Save function.

Parameters:

[out]	cFile	File to write in, must be opened and writable
[in]	nDepth	Current depth

Returns:: 'true' if all went fine, else 'false'

Implements PLCore::XmlBase.

virtual PLCORE_API String PLCore::XmlDocument::ToString ( uint32 nDepth = 0 ) const [override, virtual]

Output as string function.

Parameters:

[in] nDepth Current depth

Returns:: String containing the XML

Implements PLCore::XmlBase.

virtual PLCORE_API const char* PLCore::XmlDocument::Parse	(	const char *	pszData,
		XmlParsingData *	pData = `nullptr`,
		EEncoding	nEncoding = `EncodingUnknown`
	)		`[override, virtual]`

Parse the given null terminated block of XML data.

Parameters:

[in]	pszData	Parsing data, if a null pointer, an error will be returned
[in]	pData	Parsing data, can be a null pointer
[in]	nEncoding	Encoding

Returns:: The pointer to the parameter 'pszData' if all went fine, else a null pointer

Remarks:: Passing in an encoding to this method (either 'EncodingLegacy' or 'EncodingUTF8' will force the parser to use that encoding, regardless of what the parser might otherwise try to detect.

Implements PLCore::XmlBase.

virtual PLCORE_API XmlNode* PLCore::XmlDocument::Clone ( ) const [override, virtual]

Create an exact duplicate of this node and return it.

Returns:: The clone, a null pointer on error

Note:

The memory must be deleted by the caller

Implements PLCore::XmlNode.

The documentation for this class was generated from the following files:

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation