XMLTraversal Class Reference

#include <xmltraversal.h>

List of all members.

Classes

class  iterator

Public Member Functions

 XMLTraversal (QString)
 XMLTraversal (QDomDocument)
 XMLTraversal (QByteArray)
 XMLTraversal (XMLTraversal &x)
bool isValid () const
bool exists (const QString &path) const
QString pwd () const
QDomNode currentNode (const QString &path=QString()) const
QDomElement currentElement ()
QString attribute (const QString &name) const
bool hasAttribute (const QString &attrname) const
const QDomDocument & document () const
QString dump () const
QStringList ls () const
iterator begin ()
iterator end ()
unsigned int size () const
virtual bool setDocument (QString doc)
virtual bool setDocument (QByteArray doc)
virtual bool setDocument (QDomDocument doc)
bool cd (const QString &path=QString())
bool cd (const QDomElement &)
bool cdToRoot ()
QDomElement mkdir (const QString &path)
bool rmdir (const QString &path)
bool mv (const QString &oldpath, const QString &newpath)
bool cp (const QString &source, const QString &target)
bool setAttribute (const QString &path, const QString &attrname, const QString &attrvalue)
bool setAttribute (const QString &attrname, const QString &attrvalue)
void push ()
void pop ()
void clearStack ()
void setText (QString s)
QString text (QString path)
QDomElement mkdirAndCd (QString s)
QDomElement mkdirSetText (QString s, QString text)
bool loadFromFile (QString s)
void XmlSet (QString s, QVariant v)
void XmlGet (QString s, QVariant &b)
void XmlSet (QString s, QHostAddress a)
void XmlGet (QString s, QHostAddress &b)
QVariant GetVar (QString s)
void initialise (QString s="Document")
QVariant elementToVariant (QDomElement e)
void VariantToElement (QVariant v, QDomElement e)
QDateTime getUpdateTime () const
void markUpdated ()

Private Member Functions

QDomNode cd_to_node (const QString &path)

Private Attributes

QStack< QDomNode > savePoints
QDomDocument doc_
QDomNode cur_path_node_
QDateTime updateTime

Detailed Description

Useful class to traverse an xml document. The key idea is that the xml document is compared to a tree structure of a drive. The document node has no name and is compared to the Unix like "/" folder. The separator used is the '/' character. Available Unix like commands are: cd, pwd, mkdir, rmdir, cp, mv, ls and exist.

QDomElement is the main node type used in this implementation, since it holds attributes, which was important for our requierements.

This class provides an iterator over dom elements of first sibling in a given folder. This iterator is STL conformant, and therefor, STL algorithms can be used.

Sorry but there's no name completion (like with the tab-tab under the unix-like bash shell), because it was too hard to implement ;-)

Example: 

   XMLTraversal xml ;
   xml.setDocument(...) ;
   assert(xml.is_valid()) ;

   xml.cd("constants/remote/s11") ;
   xml.cd("/config/user_path") ;
   xml.cd("..") ;
   xml.cd("...") ;

   xml.rmdir("/constants/halfspace/enable") ;
   std::cout << xml.pwd() << std::endl ;

   xml.cd("/config/user_path") ;
   QDomElement e = xml.currentNode().toElement() ;
   std::cout << e.attribute("value") << std::endl ;

   xml.cd("/constants/halfspace") ;
   if (!xml.exist("depth"))
     xml.mkdir("depth") ;
   xml.mv("depth", "profondeur") ;

   QStringList list = xml.ls() ;
   for (QStringList::iterator it = list.begin(); it != list.end(); ++it) {
     std::cerr << (*it) << std::endl ;
   }

   // Iterate over all chidren of the current directory
   xml.cd("/") ;
   XMLTraversal::iterator it = xml.begin() ;
   for (; it != xml.end(); it++) {
     std::cerr << (*it).tagName() << std::endl ;
   }

Todo:
Some checkings and bugs correction for sure
Author:
Frantz Maerten, frantz.maerten@igeoss.com (http://www.igeoss.com)
Version:
1.02
Date:
November 2004
Warning:
The 'rename' command was removed and is replaced by the more generic command 'mv'

Member Function Documentation

QString XMLTraversal::attribute ( const QString &  name  )  const [inline]

Get an attribute for the current node. This method assumes that the current node is a QDomElement. If not, a QString::null value is returned.

Returns:
the attribute value, or QString::null if no such attribute exists, or if the current node is not a QDomElement.

XMLTraversal::iterator XMLTraversal::begin (  )  [inline]

Iterate over the children (first sibling) of the current node of this XMLTraversal. Get the first child.

Example: 

 XMLTraversal xml(mydoc) ;
 xml.cd("/root/tag1") ;

 // Iterate over all chidren of "/root/tag1"
 XMLTraversal::iterator it = xml.begin() ;
 for (; it != xml.end(); it++) {
   std::cerr << (*it).tagName() << std::endl ;
 }
See also:
end() and size()

bool XMLTraversal::cd ( const QDomElement &  e  ) 

To cd to a specified directory given by a QDomElement. This can be useful, for example, while iterate over the children using begin() and end(). 

   XMLTraversal::iterator it = xml.begin() ;
   for (; it != xml.end(); it++) {
     xml.cd(*it) ;
     ...
     xml.cd("..") ;
   }

bool XMLTraversal::cd ( const QString &  path = QString()  ) 

To cd to a specific node. You can use:

  • a usual path. If a backslash is present at the beginning of the path, it starts from the root. Otherwise, it starts from the current path (see pwd()). Examples: 
       cd("/constants/remote/s11") ;
   cd("../..") ;
   // Jump to the root:
   cd() ;
   cd("../../tools/remote/../halfspace") ;
  • "..." to do a "cd ../.." (an alias)
  • no argument: to return to the root of the XMLTraversal.

Returns:
true if successful, false otherwise.

bool XMLTraversal::cp ( const QString &  source,
const QString &  target 
)

Copy a branch node into another node.

Parameters:
source the node to copy (with its children)
target the parent for the copy node
Returns:
true if successful, false otherwise
Example: 
   XMLTraversal xml ;
   ...// init
   // copy remote to halfspace
   xml.cp("/constants/remote", "/constants/halfspace") ;

QDomNode XMLTraversal::currentNode ( const QString &  path = QString()  )  const

Return the node at the current path or at a specified path of the document. If no path is provided, it return the node of the current path. Otherwise, it returns the node of the provided path, without changing the current path.

Parameters:
path the path to node or no argument.
Returns:
the node at the current path or at the specified path, or a null node if the current path or the provided path is invalid.
Example: 
   XMLTraversal xml ;
   ...// init
   xml.cd("constants/halfspace/depth") ;
   QDomNode node = xml.currentNode() ;
   if (node.isNull())
     std::cerr << "invalid current path" << std::endl ;

   node = xml.currentNode("/constants/remote/s11") ;
   if (node.isNull())
     std::cerr << "invalid path" << std::endl ;

const QDomDocument & XMLTraversal::document (  )  const [inline]

Return the document making this XMLTraversal

QString XMLTraversal::dump (  )  const [inline]

Convert to string for debugging purpose

XMLTraversal::iterator XMLTraversal::end (  )  [inline]

Iterate over the children (first sibling) of the current node of this XMLTraversal. Get the end child (i.e. the following is true: QDomElement::isNull()).

bool XMLTraversal::exists ( const QString &  path  )  const [inline]

Check if a path exists within the document

Returns:
true if the path exists, false otherwise

bool XMLTraversal::hasAttribute ( const QString &  attrname  )  const [inline]

Tells if the current node has the attribute attrname. This method assumes that the current node is a QDomElement. If not, a false value is returned.

Returns:
true if the attribute exists, or false if no such attribute exists, or if the current node is not a QDomElement.

bool XMLTraversal::isValid (  )  const [inline]

Check the validity of the XMLTraversal instance

Returns:
true if the internal document is valid, false otherwise

QStringList XMLTraversal::ls (  )  const

Return the list of the first child nodes of the current directory. Equivalent to the Unix command ls (but with no arguments).

Example: 

   XMLTraversal xml ;
   ...// init
   QStringList list = xml.ls() ;
   if (list.size()==0)
     std::cerr << "no child nodes." << std::endl ;
   else {
     std::cerr << "Printing all child nodes of the first sibling" 
               << std::endl ;
     for (QStringList::iterator it=list.begin(); it!=list.end(); ++it) {
       std::cerr << (*it).latin1() << std::endl ;
     }
   }

QDomElement XMLTraversal::mkdir ( const QString &  path  ) 

Create a new directory (a new node). The tail of the path is the name of the new node, and the remaining path have to be a valid path. You can only create one directory at a time.

Returns:
the created element. The return element is invalid (isNull()) if the operation failed.
Example: 
   XMLTraversal xml ;
   ...// init
   // Create the s23 node
   if (xml.mkdir("/constants/remote/s23"))
     std::cerr << "node successfuly created." << std::endl ;
   else
     std::cerr << "error while creating the node." << std::endl ;

bool XMLTraversal::mv ( const QString &  oldpath,
const QString &  newpath 
)

Move or rename a node. Several possible commands:

  • If newpath does exist, and oldpath is not a child of newpath, it moves oldpath to newpath.
  • If newpath doesn't exist (at least the last child of newpath), it renames oldpath to newpath

Parameters:
oldpath the node to move or rename
newpath the new parent or the new name
Returns:
true if successful, false otherwise
Example: 
   XMLTraversal xml ;
   ...// init
   // rename remote to limits
   xml.mv("remote", "limits") ;
   // move limits to another place
   xml.mv("limits", "../others") ;

QString XMLTraversal::pwd (  )  const

Gives the current path within the XMLTraversal from the root (the document)

Returns:
the current path.
Example: 
   XMLTraversal xml ;
   ...// init
   std::cerr << xml.pwd() << std::endl ;

  // print: /constants/halfspace/depth

bool XMLTraversal::rmdir ( const QString &  path  ) 

Remove an existing directory (a node)

Returns:
true if succeed, false otherwise
Example: 
   XMLTraversal xml ;
   ...// init
   if (xml.rmdir("/constants/remote"))
     std::cerr << "node successfuly removed." << std::endl ;
   else
     std::cerr << "error while removing the node." << std::endl ;

bool XMLTraversal::setAttribute ( const QString &  attrname,
const QString &  attrvalue 
)

Shortcut to set an attribute for the current element.

Parameters:
attrname the name of the attribute
attrvalue the value of the attribute.
Returns:
true if successful

bool XMLTraversal::setAttribute ( const QString &  path,
const QString &  attrname,
const QString &  attrvalue 
)

Shortcut to set an attribute for an element.

Parameters:
path the path to the element
attrname the name of the attribute
attrvalue the value of the attribute.
Returns:
true if successful

bool XMLTraversal::setDocument ( QDomDocument  doc  )  [virtual]

The the new content of the XMLTraversal

Parameters:
doc the document
Returns:
true if the internal document is valid, false otherwise

bool XMLTraversal::setDocument ( QString  doc  )  [virtual]

The the new content of the XMLTraversal

Parameters:
doc the stringified version of the document
Returns:
true if the internal document is valid, false otherwise

unsigned int XMLTraversal::size (  )  const [inline]

Return the number of first sibling children

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