Plus

- Minimal XML for C++

(Version 0.9.2)

Giancarlo Niccolai

MXML::Node Class Reference

Implements an XML node. More...

#include <mxml_node.h>

Inheritance diagram for MXML::Node:

[legend]Collaboration diagram for MXML::Node:

[legend]List of all members.


Public Types
typedef __iterator< Node >	iterator
typedef __iterator< const Node >	const_iterator
typedef __deep_iterator< Node >	deep_iterator
typedef __deep_iterator< const Node >	const_deep_iterator
typedef __find_iterator< Node >	find_iterator
typedef __find_iterator< const Node >	const_find_iterator
typedef __path_iterator< Node >	path_iterator
typedef __path_iterator< const Node >	const_path_iterator
enum	type { typeTag = 0, typeXMLDecl, typeComment, typePI, typeDirective, typeData, typeDocument, typeFakeClosing }
	Node types. More...
Public Member Functions
	Node (std::istream &in, const int style=0, const int line=1, const int pos=0) throw ( MalformedError )
	Deserializes a node Reads a node from an XML file at current position.
	Node (const type tp, const std::string &name="", const std::string &data="")
	Node (Node &)
	Copy constructor.
	~Node ()
	Deletes the node.
const type	nodeType () const
	Returns the type of this node.
const std::string	name () const
	Returns current name of the node.
const std::string	data () const
	Returns the data element of the node.
void	name (const std::string &new_name)
	Change name of the node.
void	data (const std::string &new_value)
	Change data of the node.
void	addAttribute (Attribute *attrib)
	Adds a new attribute at the end of the attribute list.
const std::string	getAttribute (const std::string name) const throw ( NotFoundError )
	Gets the value of the given attribute.
void	setAttribute (const std::string name, const std::string value) throw ( NotFoundError )
	Sets the value of a given attribute.
bool	hasAttribute (const std::string name) const
	Returns true if the node has a given attribute.
void	unlink ()
	Detaches current node from its parent and brothers.
Node *	unlinkComplete ()
	Detaches current node from all the adiacents node.
void	Node::removeChild (Node *child) throw ( NotFoundError )
	Removes a child from the children list.
Node *	parent () const
Node *	child () const
Node *	next () const
Node *	prev () const
Node *	lastChild () const
void	addBelow (Node *)
void	insertBelow (Node *)
void	insertBefore (Node *)
void	insertAfter (Node *)
int	Node::depth () const
	Returns the depth of the path leading to this node.
std::string	Node::path () const
	Returns a symbolic path leading to the node.
Node *	clone ()
virtual void	write (std::ostream &out, const int style) const
	Writes the node on a stream.
iterator	begin ()
iterator	end ()
const_iterator	const_begin () const
const_iterator	const_end ()
deep_iterator	deep_begin ()
find_iterator	find (std::string name, std::string attrib="", std::string valatt="", std::string data="")
	Find one or more with specific characteristics.
path_iterator	find_path (std::string path)
	Recursive node path find iterator.
Protected Member Functions
void	nodeIndent (std::ostream &out, const int depth, const int style) const
void	readData (std::istream in, const int iStyle)
Private Attributes
type	m_type
std::string	m_name
std::string	m_data
AttribList	m_attrib
AttribList::iterator	m_lastFound
Node *	m_parent
Node *	m_child
Node *	m_last_child
Node *	m_next
Node *	m_prev

Detailed Description

Implements an XML node.

Todo:: Write serialization progress hooks

Member Typedef Documentation

typedef __deep_iterator<const Node> MXML::Node::const_deep_iterator

typedef __find_iterator<const Node> MXML::Node::const_find_iterator

typedef __iterator<const Node> MXML::Node::const_iterator

typedef __path_iterator<const Node> MXML::Node::const_path_iterator

typedef __deep_iterator<Node> MXML::Node::deep_iterator

typedef __find_iterator<Node> MXML::Node::find_iterator

typedef __iterator<Node> MXML::Node::iterator

typedef __path_iterator<Node> MXML::Node::path_iterator

Member Enumeration Documentation

enum MXML::Node::type

Node types.
This enum describes the kind of node that is held inside this object.
Enumeration values:

typeTag The node is a normal XML tag.
It has possibly attributes, data and surely a name and a path.

typeXMLDecl The XML document declaration.
This node store the content of the <?xml abc ... ?> decl in its name. Data is unused, and the node cannot have children.

typeComment A Comment.
Comments nodes has only data, representing the content of the comment, and has no name, path or attributes. The node cannot have children.

typePI An XML Processing instruction.
The tag is a processing instruction in the form <?NAME ...?>; all the content of the tag, except the name, is set in the data. The node has never children.

typeDirective An XML directive.
The directive in the form <!xxx ... > has a name and a content. The node has never children.

typeData A data node.
Tag nodes having more than one tag and data nodes below them may have the first content in their data, and rely on this kind of node for the other data slices right below them. Data nodes have only data; no name, path or attribute is meaningful for them.

typeDocument The root element of a XML document.
A root node is always empty, and it's kust holding the root level XML nodes. Apart from the root tag, it has the XML as child, and may have many comments and directives as well.

typeFakeClosing Temporary node used internally during deserialization.

Constructor & Destructor Documentation

MXML::Node::Node ( std::istream & in,

const int style = 0,

const int line = 1,

const int pos = 0

) throw ( MalformedError )

Deserializes a node Reads a node from an XML file at current position.
In case of error Throws an MXML::IOError or MXML::MalformedError.

Parameters:

in the input stream

style style bits; see MXML::Document::setStyle()

line the current line in the stream

pos the current position in line

Exceptions:

MXML::MalformedError if the node is invalid

MXML::IOError in case of hard errors on the stream

MXML::Node::Node ( const type tp,

const std::string & name = "",

const std::string & data = ""

) [inline]

MXML::Node::Node ( Node & )

Copy constructor.
See clone()

MXML::Node::~Node ( )

Deletes the node.
All the attributes in the attribute list are deleted also, as well as the children of the node. To avoid deleting the children do an unlinkComplete of the parent after having got the first child; then insert it below or after another node, or iterate through an addBelow():

// saving children nodes Node *child = dying->child(); dying->unlinkComplete(); //alternative 1: safe->insertBelow( child ); //alternative 2: Node *ch = child; while( ch != 0 ) { ch = child->next(); safe->addBelow( child ); child = ch; // addBelow destroys child->next; } // do the job delete dying;

Member Function Documentation

void MXML::Node::addAttribute ( Attribute * attrib ) [inline]

Adds a new attribute at the end of the attribute list.

void MXML::Node::addBelow ( Node * )

iterator MXML::Node::begin ( ) [inline]

Node* MXML::Node::child ( ) const [inline]

Node * MXML::Node::clone ( )

const_iterator MXML::Node::const_begin ( ) const [inline]

const_iterator MXML::Node::const_end ( ) [inline]

void MXML::Node::data ( const std::string & new_value ) [inline]

Change data of the node.
The user can also set the data for a node that should not have it (i.e. an XMLdecl type), but the data will be ignored by the system.

Todo:
check validity of the name and throw a malformed error if wrong.

const std::string MXML::Node::data ( ) const [inline]

Returns the data element of the node.
If the name is not defined, it returns an empty string.

deep_iterator MXML::Node::deep_begin ( ) [inline]

iterator MXML::Node::end ( ) [inline]

Node::find_iterator MXML::Node::find ( std::string name,

std::string attrib = "",

std::string valatt = "",

std::string data = ""

)

Find one or more with specific characteristics.
This function returns an iterator that iterates over all the nodes below this one that matches the given criteria:

Having node name equal to the name parameter.
Having an attribute named as attrib parameter
attrib attribute having value valattr
data being a substring of node data.

In case one or more of the elements is to be ignored, it just set the corresponding parameter to an empty string (""); if all the parameters are set to an empty string, the iterator will iterate over all the nodes below this one.
The search is done deeply: all the nodes below this one that matches the search criteria are returned, regardless of their level and distance from this node.
In example, to search for all the nodes named "mynode" having the word "good" in their data, perform the following scan:

MXML::find_iterator iter = currentNode->find( "mynode", "", "", "good" ); while( iter != currentNode->end() ) { std::out << "Data inside node MYNODE: " << endl; std::cout << (*iter)->data() << endl; iter++; }

Todo:
add a flat find iterator.
If the find is unsuccesful, MXML::Node::end() will be returned.

Parameters:

name Node name to search for or "" to ignore this parameter.

attrib attribute that the searched node must possess, or "" for none.

valatt value that attribute attrib must possess, or any value in the attribute list if attrib is ""; set to "" to ignore.

data a substring that must appare in the node data; set to "" to ignore.

Returns:
an iterator that will return all the nodes that match the critria in turn or end().

Node::path_iterator MXML::Node::find_path ( std::string path )

Recursive node path find iterator.

Note:
currently, it only supports complete path or path aliased with '*'; also, it supports only the FIRST branch that corresponds to the path and all its leaves.

const std::string MXML::Node::getAttribute ( const std::string name ) const throw ( NotFoundError )

Gets the value of the given attribute.
If the attribute is present, its value is returned. If it is not present, an MXML::NotFoundError error is thrown.
Parameters:

name the attribute name

Returns:
the attribute value, if it exists

Exceptions:

MXML::NotFoundError if the attribute name can't be found.

bool MXML::Node::hasAttribute ( const std::string name ) const

Returns true if the node has a given attribute.
The found attribute is cached, so if you make this method follow by a getAttribute, the whole operation is done efficiently:
... if ( node.hasAttribute( "position" ) ) pos = node.getAttribute( "position"); else { pos = "0"; node.addAttribute( new Attribute( "position", pos ) ); } ...
Parameters:

name attribute to be found

Returns:
true if attribute with given name has been found, false otherwise

void MXML::Node::insertAfter ( Node * )

void MXML::Node::insertBefore ( Node * )

void MXML::Node::insertBelow ( Node * )

Node* MXML::Node::lastChild ( ) const [inline]

void MXML::Node::name ( const std::string & new_name ) [inline]

Change name of the node.
If the node should not have a name (i.e. comments) this value will be ignored by the system.

Todo:
check validity of the name and throw a malformed error if wrong.

const std::string MXML::Node::name ( ) const [inline]

Returns current name of the node.
If the name is not defined, it returns an empty string.

Node* MXML::Node::next ( ) const [inline]

int MXML::Node::Node::depth ( ) const

Returns the depth of the path leading to this node.
...Or how many levels are above this node. Can be called also for nodes that have not a valid symbolic path.

std::string MXML::Node::Node::path ( ) const

Returns a symbolic path leading to the node.
A Node path is the the list of all the ancestor node names, plus the name of the current node, separated by a "/" sign. So, if you have a doucument like:
<root> <item>an item</item> </root>
the path to item will "/root/item".
Node paths have not to be unique (two nodes can have the same name and be brothers). A node can also have an empty path if it has not a name, or if it is a child of nodes that have not a name. I.e. data nodes and comments have not a path.
Returns:
the path leading to the node, or an empty string if the node has not a valid path.

void MXML::Node::Node::removeChild ( Node * child ) throw ( NotFoundError )

Removes a child from the children list.
The child is not deleted; an error is thrown if the parameter is not a child of this object.
Note:
is possible to check if the node is in the child list of this object by checking that its parent() points to this. This prevents uslesess try/catches.

Parameters:

child the node to be removed

Exceptions:

NotFoundError if the node is not in the child list

void MXML::Node::nodeIndent ( std::ostream & out,

const int depth,

const int style

) const [protected]

const type MXML::Node::nodeType ( ) const [inline]

Returns the type of this node.

Node* MXML::Node::parent ( ) const [inline]

Node* MXML::Node::prev ( ) const [inline]

void MXML::Node::readData ( std::istream in,

const int iStyle

) [protected]

void MXML::Node::setAttribute ( const std::string name,

const std::string value

) throw ( NotFoundError )

Sets the value of a given attribute.
This is a shortcut instead of searching for an attribute in the list returned by attributes() method and setting its value.
Parameters:

name the attribute name

Returns:
the attribute value, if it exists

Exceptions:

MXML::NotFoundError if the attribute name can't be found.

void MXML::Node::unlink ( )

Detaches current node from its parent and brothers.
The node still retain its children though.

Node * MXML::Node::unlinkComplete ( )

Detaches current node from all the adiacents node.
Be sure to have a reference to the children nodes, or the whole children hierarcy will be lost (causing a memory leak). The ideal is to use a Node list to save the old children; the list can then be added to other nodes children, like that:
... Node *kids; kids = myNode->unlinkComplete(); targetNode.insertBelow( kids ); ...
Returns:
a pointer to the first list where the children are saved.

void MXML::Node::write ( std::ostream & out,

const int style

) const [virtual]

Writes the node on a stream.
This function is usually called by MXML::Document::write(), or by the << operator (in class MXML::Element), use the latter only for debug.
Parameters:

stream the stream where the object will be written

style the style of the serialization

Implements MXML::Element.