DOM representation of XML document. More...

Inheritance diagram for MXmlDocument:

Public Types
enum	ParseEnum { ParsePi = 0x0001, ParseComments = 0x0002, ParseCdata = 0x0004, ParseWsPcdata = 0x0008, ParseEscapes = 0x0010, ParseEol = 0x0020, ParseWconvAttribute = 0x0040, ParseWnormAttribute = 0x0080, ParseDeclaration = 0x0100, ParseDoctype = 0x0200, ParseWsPcdataSingle = 0x0400, ParseTrimPcdata = 0x0800, ParseFragment = 0x1000, ParseMaskMinimal = 0x0000, ParseMaskDefault = ParseCdata \| ParseEscapes \| ParseWconvAttribute \| ParseEol, ParseMaskFull = ParseMaskDefault \| ParsePi \| ParseComments \| ParseDeclaration \| ParseDoctype }
	Document parsing mode. More...

enum	{ FormatIndent = 0x0001, FormatWriteBom = 0x0002, FormatRaw = 0x0004, FormatNoDeclaration = 0x0008, FormatNoEscapes = 0x0010, FormatSaveFileText = 0x20, FormatIndentAttributes = 0x40, FormatMaskDefault = FormatIndent }
	Formatting flags applied when the XML is written. More...

Public Types inherited from MXmlNode
enum	NodeTypeEnum { NodeDocument = 1, NodeElement = 2, NodePcdata = 3, NodeCdata = 4, NodeComment = 5, NodePi = 6, NodeDeclaration = 7, NodeDoctype = 8 }
	Type of the node. More...

typedef M_TEMPLATE_CLASS std::vector< MXmlNode * >	NodeVector
	Convenience type, vector of nodes.

Public Member Functions
	MXmlDocument ()
	Create an empty XML document, ready to be read or populated manually. More...

	MXmlDocument (const MVariant &streamFilenameOrString, unsigned parseMask=ParseMaskDefault)
	Create an XML document from generic parameter. More...

	MXmlDocument (const void *buffer, unsigned size, unsigned parseMask=ParseMaskDefault)
	Create an XML document from a buffer that contains XML text. More...

virtual	~MXmlDocument ()
	Destructor, claims all memory allocated for children.

void	Read (const MVariant &streamFilenameOrString)
	Read an XML document using a generic parameter. More...

void	ReadFromString (const MStdString &xmlString)
	Read an XML document from a given string. More...

void	ReadFromStream (MStream *stream)
	Read an XML document from an opened stream. More...

void	ReadFromFile (const MStdString &fileName)
	Read an XML document from a file given by its name. More...

void	ReadFromBuffer (const void *buffer, unsigned size)
	Read an XML document from a given string. More...

void	ReadFromChars (const char *buff)
	Read an XML document from a given string. More...

void	Clear ()
	Clear all contents of this document. More...

void	Write (const MVariant &streamOrFilename)
	Write the contents of the document using a generic parameter. More...

void	WriteToStream (MStream *stream)
	Write the contents of the document into a stream. More...

void	WriteToFile (const MStdString &fileName)
	Write the contents of the document into a file with a given name. More...


const MStdString &	GetFileName () const

void	SetFileName (const MStdString &name)


unsigned	GetParseMask () const

void	SetParseMask (unsigned mask)


unsigned	GetFormatMask () const

void	SetFormatMask (unsigned mask)


const MStdString &	GetIndentationSequence () const

void	SetIndentationSequence (const MStdString &sequence)


char	GetPathDelimiter () const

void	SetPathDelimiter (char delimiter)


virtual MXmlDocument *	GetRoot ()

const MXmlDocument *	GetRootConst () const


void	Assign (const MXmlDocument &other)

MXmlDocument &	operator= (const MXmlDocument &other)

Public Member Functions inherited from MXmlNode
NodeTypeEnum	GetNodeType () const
	Type of the node. More...

MStdString	AsString () const
	XML String representation of this element, and all its children. More...

MXmlNode *	GetParent () const
	Access parent of this node. More...

bool	HasChildren () const
	Whether the node has one or more children. More...

MXmlNode::NodeVector	GetChildren () const
	Get the read-only array of all children of the node. More...

MVariant	GetAllChildren () const
	Get the read-only array of all children of the node. More...

MXmlNode *	GetFirstChild () const
	Return the first child of the node, if present. More...

MXmlNode *	GetLastChild () const
	Return the last child of the node, if present. More...

MXmlNode *	GetPreviousSibling () const
	Return the sibling that is previous to this node. More...

MXmlNode *	GetNextSibling () const
	Return the sibling that is next to this node. More...

MXmlNode *	GetChild (const MStdString &name) const
	Access the first child by name, if it is present. More...

bool	IsChildPresent (const MStdString &name) const
	Is the child with such name present within the node. More...

MXmlNode *	GetExistingChild (const MStdString &name) const
	Access the first child by name, or throw an exception if there is no such child. More...

void	RemoveAllAttributes ()
	Remove all attributes of the item.

bool	IsAttributePresent (const MStdString &name) const
	Whether an attribute with such name is present in the node. More...

MStdStringVector	GetAllAttributeNames () const
	Access the collection of node attribute names. More...

bool	RemoveAttribute (const MStdString &name)
	Remove attribute by name or do nothing if there is no such attribute already. More...

void	RemoveExistingAttribute (const MStdString &name)
	Remove attribute by name. More...

MVariant	GetAttribute (const MStdString &name) const
	Get attribute value by name. More...

MStdString	GetAttributeAsString (const MStdString &name) const
	Get string attribute value by name, a C++ convenience call. More...

MConstChars	GetAttributeAsChars (const MStdString &name) const
	Get const char* attribute value, a C++ convenience call. More...

int	GetAttributeAsInt (const MStdString &name) const
	Get integer attribute value, a C++ convenience call. More...

double	GetAttributeAsDouble (const MStdString &name) const
	Get a double precision floating point attribute value, a C++ convenience call. More...

bool	SetAttribute (const MStdString &name, const MVariant &value)
	Set a value to attribute of a given name. More...

MXmlNode *	PrependAttribute (const MStdString &name, const MVariant &value)
	Create an attribute that will be the first in the list of node attributes. More...

MXmlNode *	AppendAttribute (const MStdString &name, const MVariant &value)
	Create an attribute that will be the last in the list of node attributes. More...

void	InsertAttributeBefore (const MStdString &targetName, const MStdString &name, const MVariant &value)
	Create an attribute and place it before another attribute. More...

MXmlNode *	AppendChild (NodeTypeEnum type)
	Append a child node of a given type and return a freshly created node. More...

MXmlNode *	PrependChild (NodeTypeEnum type)
	Prepend a child node of a given type and return a freshly created node. More...

MXmlNode *	InsertChildBefore (const MXmlNode *node, NodeTypeEnum type)
	Insert a child node before the given node. More...

MXmlNode *	AppendChildElement (const MStdString &name)
	Append element child node and return a freshly created element object. More...

MXmlNode *	PrependChildElement (const MStdString &name)
	Prepend element child node and return a freshly created element object. More...

MXmlNode *	InsertChildElementBefore (const MXmlNode *node, const MStdString &name)
	Insert element child node prior to a given child. More...

void	AppendFragment (const MStdString &contents)
	Parse the string buffer as an XML document fragment and append all nodes as children to the current node. More...

void	AppendFragmentFromBuffer (const char *buff, unsigned size)
	Parse the raw buffer as an XML document fragment and append all nodes as children to the current node. More...

void	AppendFragmentFromChars (const char *buff)
	Parse the raw buffer as an XML document fragment and append all nodes as children to the current node. More...

void	RemoveAllChildren ()
	Remove all children of the node. More...

bool	RemoveChild (const MVariant &nameOrNodeObject)
	Remove a child node, do nothing if there is no such node. More...

bool	RemoveChildByName (const MStdString &name)
	Remove a child node by name, do nothing if there is no such node. More...

bool	RemoveChildByObject (MXmlNode *node)
	Remove a child object, do nothing if there is no such node. More...

void	RemoveExistingChild (const MVariant &nameOrNodeObject)
	Remove an existing child node. More...

void	RemoveExistingChildByName (const MStdString &name)
	Remove an existing child node by name. More...

void	RemoveExistingChildByObject (MXmlNode *node)
	Remove an existing child object. More...

MStdString	GetPath () const
	Return the node path from the root of XML document. More...

MXmlNode *	GetFirstElementByPath (const MStdString &path) const
	Convenience function that returns elements by path. More...

MXmlNode *	GetDocumentElement () const
	Access the main element of the document from any child. More...

MStdString	GetName () const

void	SetName (const MStdString &)

MVariant	GetValue () const

void	SetValue (const MVariant &)

MStdString	GetStringValue () const

void	SetStringValue (const MStdString &)

MVariant	GetText () const

void	SetText (const MVariant &)

MStdString	GetStringText () const

void	SetStringText (const MStdString &)

MVariant	GetAllAttributes () const

void	SetAllAttributes (const MVariant &)

const MXmlDocument *	GetRootConst () const

Public Member Functions inherited from MObject
virtual	~MObject ()
	Object destructor.

virtual const MClass *	GetClass () const =0
	Get the final class of the object. More...

virtual unsigned	GetEmbeddedSizeof () const
	For embedded object types, return the size of the class. More...

bool	IsEmbeddedObject () const
	Tell if the object is of embedded kind. More...

SHOW_INTERNAL MVariant	Call (const MStdString &name, const MVariant &params)
	Call the object service with parameters, given as variant. More...

MVariant	Call0 (const MStdString &name)
	Call the object service with no parameters. More...

MVariant	Call1 (const MStdString &name, const MVariant &p1)
	Call the object service with one parameter. More...

MVariant	Call2 (const MStdString &name, const MVariant &p1, const MVariant &p2)
	Call the object service with two parameter. More...

MVariant	Call3 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3)
	Call the object service with three parameter. More...

MVariant	Call4 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4)
	Call the object service with four parameter. More...

MVariant	Call5 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4, const MVariant &p5)
	Call the object service with five parameter. More...

MVariant	Call6 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4, const MVariant &p5, const MVariant &p6)
	Call the object service with six parameter. More...

virtual MVariant	CallV (const MStdString &name, const MVariant::VariantVector &params)
	Call the object service with parameters, given as variant vector. More...

virtual bool	IsPropertyPresent (const MStdString &name) const
	Tell if the property with the given name exists.

virtual bool	IsServicePresent (const MStdString &name) const
	Tell if the service with the given name exists.

virtual MVariant	GetProperty (const MStdString &name) const
	Get the property value using name of the property. More...

virtual void	SetProperty (const MStdString &name, const MVariant &value)
	Set the property using name of the property, and value. More...

virtual MStdStringVector	GetAllPropertyNames () const
	Return the list of publicly available properties, persistent or not. More...

virtual MStdStringVector	GetAllPersistentPropertyNames () const
	Return the list of persistent properties. More...

virtual void	SetPersistentPropertiesToDefault ()
	Set the persistent properties of the object to their default values. More...

virtual MVariant	GetPersistentPropertyDefaultValue (const MStdString &name) const
	Get the default value of persistent property with the name given. More...

virtual void	SetPersistentPropertyToDefault (const MStdString &name)
	Set the persistent property with the name given to default value. More...

virtual const char *	GetType () const
	Get the name of the type for the object (could be the same as class name).

virtual void	SetType (const MStdString &)
	Intentionally, it will set the name of the type for the object, but the service will not allow setting the name to anything other than the current name. More...

virtual void	Validate ()
	Validate internal structures of the object. More...

Friends
class M_CLASS	MXmlNode

Additional Inherited Members
Static Public Member Functions inherited from MObject
static const MClass *	GetStaticClass ()
	Get the declared class of this particular object. More...

static bool	IsClassPresent (const MStdString &name)
	Tells if the given class name is available. More...

Static Public Attributes inherited from MObject
static const MClass	s_class
	Class of MObject.

Protected Member Functions inherited from MObject
	MObject ()
	Object constructor, protected as the class is abstract.

void	DoSetPersistentPropertiesToDefault (const MClass *staticClass)
	Set the persistent properties to their default values for one object provided the class for that object. More...

Detailed Description

DOM representation of XML document.

XML document object manages memory for all its children all by itself, no attempts should be made to delete any child nodes.

The implementation of DOM interface is based on one of the fastest libraries, pugixml, which is freeware. There is very little overhead above pugixml on memory, and no overhead on speed.

Member Enumeration Documentation

anonymous enum

Formatting flags applied when the XML is written.

Enumerator
FormatIndent	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 on by default.
FormatWriteBom	Write encoding-specific BOM (Byte Order Mark) to the output stream. This flag is off by default.
FormatRaw	Use raw output mode, no indentation and no line breaks. When this flag is set, FormatIndent is ignored. This flag is off by default.
FormatNoDeclaration	Omit default XML declaration even if there is no declaration in the document. This flag is off by default.
FormatNoEscapes	Do not escape attribute values and PCDATA contents. This flag is off by default.
FormatSaveFileText	Open file using text mode. This enables special character (i.e. new-line) conversions on some systems. This flag is off by default.
FormatIndentAttributes	Write every attribute on a new line with appropriate indentation. This flag is off by default.
FormatMaskDefault	The default format mask. Nodes are indented depending on their depth in the DOM tree.

enum MXmlDocument::ParseEnum

Document parsing mode.

Enumerator
ParsePi	If processing instructions are added to the DOM tree when parsed. This flag is off by default.
ParseComments	If comments are added to the DOM tree. This flag is off by default.
ParseCdata	If CDATA sections are added to the DOM tree. This flag is on by default.
ParseWsPcdata	If plain character data that consist only of whitespace are added to the DOM tree. This flag is off by default and turning it on usually results in slower parsing and more memory consumption.
ParseEscapes	If character and entity references are expanded during parsing. This flag is on by default.
ParseEol	If EOL (End Of Line) characters are normalized, converted to a single ' ' during parsing. This flag is on by default.
ParseWconvAttribute	If attribute values are normalized using CDATA normalization rules during parsing. This flag is on by default.
ParseWnormAttribute	If attribute values are normalized using NMTOKENS normalization rules during parsing. This flag is off by default.
ParseDeclaration	If document declaration is added to the DOM tree. This flag is off by default.
ParseDoctype	If document type declaration is added to the DOM tree. This flag is off by default.
ParseWsPcdataSingle	If character data that is the only child of the parent node and that only has blanks is added to the DOM tree. This flag is off by default, turning it on may result in slower parsing and more memory consumption.
ParseTrimPcdata	If leading and trailing whitespace is to be removed from plain character data. This flag is off by default.
ParseFragment	If plain character data that does not have a parent node is added to the DOM tree, and if an empty document is a valid document. This flag is off by default.
ParseMaskMinimal	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.
ParseMaskDefault	Default parsing mode, active when parsing mode is not set explicitly. 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.
ParseMaskFull	Full parsing mode, all information is gathered from XML. 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.

Constructor & Destructor Documentation

MXmlDocument::MXmlDocument ( )

Create an empty XML document, ready to be read or populated manually.

No child nodes are present.

MXmlDocument::MXmlDocument	(	const MVariant &	streamFilenameOrString,
		unsigned	parseMask = `ParseMaskDefault`
	)

explicit

Create an XML document from generic parameter.

An error can result from stream I/O, or if the document is malformed.

Parameters

streamFilenameOrString

The parameter can be one of the following types:

Instance of class MXmlDocument. If provided, this document will be a copy.
MStream object that is opened and ready to be read. The whole stream will be read, but there will be no attempt to close the stream.
An in-place XML document in a possibly long string. Whether this is an in-place XML is determined by having '<' at the beginning and '>' at the end of the string.
A file name.

parseMask Parse mask to use. If not given, use ParseMaskDefault. When the first parameter is an XML Document, this is ignored.

MXmlDocument::MXmlDocument	(	const void *	buffer,
		unsigned	size,
		unsigned	parseMask = `ParseMaskDefault`
	)

Create an XML document from a buffer that contains XML text.

An error can result from stream I/O, or if the document is malformed.

Parameters

buffer	Pointer to a buffer to parse.
size	Size of the buffer.
parseMask	Parse mask to use. If not given, use ParseMaskDefault.

Member Function Documentation

void MXmlDocument::Assign ( const MXmlDocument & other )

Copy the given document into self.

The result document has a copy of all nodes of the given document.

Parameters

other The document from which the value should be copied.

void MXmlDocument::Clear ( )

Clear all contents of this document.

Delete all children, reclaim memory. All node pointers of this document will become invalid.

const MStdString& MXmlDocument::GetFileName ( ) const

inline

File name of the document, if the document was loaded from file.

The file name is updated by Read services, or it can be set explicitly by the user of the class. Write services do not update this property.

unsigned MXmlDocument::GetFormatMask ( ) const

inline

Format mask used during writing of XML.

This is defined as a set of Format constants. Default value is FormatMaskDefault.

const MStdString& MXmlDocument::GetIndentationSequence ( ) const

inline

Access indentation sequence, whatever is used to indent elements.

By default, indentation sequence is three blanks.

unsigned MXmlDocument::GetParseMask ( ) const

inline

Parse mask used during reading of XML.

This is defined as a set of Parse constants. Default value is ParseMaskDefault.

char MXmlDocument::GetPathDelimiter ( ) const

inline

Delimited character used for path construction.

Typical values are slash, back slash, dot, or colon. Default value is '/'.

virtual MXmlDocument* MXmlDocument::GetRoot ( )

virtual

Access root document object.

In case of this call, document object, self is returned.

Reimplemented from MXmlNode.

const MXmlDocument* MXmlDocument::GetRootConst ( ) const

inline

Access root document object.

In case of this call, document object, self is returned.

MXmlDocument& MXmlDocument::operator= ( const MXmlDocument & other )

inline

Copy the given document into self.

The result document has a copy of all nodes of the given document.

Parameters

other The document from which the value should be copied.

void MXmlDocument::Read ( const MVariant & streamFilenameOrString )

Read an XML document using a generic parameter.

The previous contents of XML Document will be lost, pointers to nodes invalidated. An error can result from stream I/O, or in case the document is malformed. The property GetParseMask is used during parsing in order to determine which parts of the document are significant and should stay in memory.

Parameters

streamFilenameOrString

The parameter can be one of the following types:

Instance of class MXmlDocument. If provided, this document will be a copy.
MStream object that is opened and ready to be read. The whole stream will be read, but there will be no attempt to close the stream.
An in-place XML document in a possibly long string. Whether this is an in-place XML is determined by having '<' at the beginning and '>' at the end of the string.
A file name.

void MXmlDocument::ReadFromBuffer	(	const void *	buffer,
		unsigned	size
	)

Read an XML document from a given string.

Parameters

buffer	Buffer from which an XML document should be read.
size	Size of the buffer.

See also: ReadFromString

void MXmlDocument::ReadFromChars ( const char * buff )

inline

Read an XML document from a given string.

Parameters

buff	Zero terminated string from which an XML document should be read.

See also: ReadFromString

void MXmlDocument::ReadFromFile ( const MStdString & fileName )

Read an XML document from a file given by its name.

The previous contents of XML Document will be lost, pointers to nodes invalidated. An error can result from stream I/O, or if the document is malformed. The property GetParseMask is used during parsing in order to determine which parts of the document are significant and should stay in memory.

Parameters

fileName A file name from which to read the document.

void MXmlDocument::ReadFromStream ( MStream * stream )

Read an XML document from an opened stream.

The previous contents of XML Document will be lost, pointers to nodes invalidated. An error can result from stream I/O, or if the document is malformed. The property GetParseMask is used during parsing in order to determine which parts of the document are significant and should stay in memory.

Parameters

stream Stream object that is opened and ready to be read. The whole stream will be read, but there will be no attempt to close the stream.

void MXmlDocument::ReadFromString ( const MStdString & xmlString )

Read an XML document from a given string.

The previous contents of XML Document will be lost, pointers to nodes invalidated. An error can result from bad contents of the string parameter. The property GetParseMask is used during parsing in order to determine which parts of the document are significant and should stay in memory.

Parameters

xmlString An in-place XML document in a possibly long string.

void MXmlDocument::SetFileName ( const MStdString & name )

inline

File name of the document, if the document was loaded from file.

The file name is updated by Read services, or it can be set explicitly by the user of the class. Write services do not update this property.

void MXmlDocument::SetFormatMask ( unsigned mask )

inline

Format mask used during writing of XML.

This is defined as a set of Format constants. Default value is FormatMaskDefault.

void MXmlDocument::SetIndentationSequence ( const MStdString & sequence )

inline

Access indentation sequence, whatever is used to indent elements.

By default, indentation sequence is three blanks.

void MXmlDocument::SetParseMask ( unsigned mask )

inline

Parse mask used during reading of XML.

This is defined as a set of Parse constants. Default value is ParseMaskDefault.

void MXmlDocument::SetPathDelimiter ( char delimiter )

inline

Delimited character used for path construction.

Typical values are slash, back slash, dot, or colon. Default value is '/'.

void MXmlDocument::Write ( const MVariant & streamOrFilename )

Write the contents of the document using a generic parameter.

The properties GetFormatMask and GetIndentationSequence are used during the write.

Parameters

streamOrFilename

This can be:

A stream object into which the XML document should be written. The stream should be open outside, and there is no attempt made to close it inside the call.
File name into which to write this document.

See also: AsString - an easy way of creating an XML context as a string.

void MXmlDocument::WriteToFile ( const MStdString & fileName )

Write the contents of the document into a file with a given name.

The file will be created if it does not exist, or it will be truncated if there is already. The properties GetFormatMask and GetIndentationSequence are used during the write.

Parameters

fileName File name into which to write this document.

See also: AsString - an easy way of creating an XML context as a string.

void MXmlDocument::WriteToStream ( MStream * stream )

Write the contents of the document into a stream.

The stream should be open outside, and there is no attempt made to close it inside the call. The properties GetFormatMask and GetIndentationSequence are used during the write.

Parameters

stream Stream object into which the XML document should be written.

See also: AsString - an easy way of creating an XML context as a string.

Public Types

Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation