Xml.h

Go to the documentation of this file.

#ifndef SimTK_SimTKCOMMON_XML_H_
#define SimTK_SimTKCOMMON_XML_H_

/* -------------------------------------------------------------------------- *
 *                          SimTK Core: SimTKcommon                           *
 * -------------------------------------------------------------------------- *
 * This is part of the SimTK Core biosimulation toolkit originating from      *
 * Simbios, the NIH National Center for Physics-Based Simulation of           *
 * Biological Structures at Stanford, funded under the NIH Roadmap for        *
 * Medical Research, grant U54 GM072970. See https://simtk.org.               *
 *                                                                            *
 * Portions copyright (c) 2010 Stanford University and the Authors.           *
 * Authors: Michael Sherman                                                   *
 * Contributors:                                                              *
 *                                                                            *
 * Permission is hereby granted, free of charge, to any person obtaining a    *
 * copy of this software and associated documentation files (the "Software"), *
 * to deal in the Software without restriction, including without limitation  *
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,   *
 * and/or sell copies of the Software, and to permit persons to whom the      *
 * Software is furnished to do so, subject to the following conditions:       *
 *                                                                            *
 * The above copyright notice and this permission notice shall be included in *
 * all copies or substantial portions of the Software.                        *
 *                                                                            *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR *
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,   *
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL    *
 * THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,    *
 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR      *
 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE  *
 * USE OR OTHER DEALINGS IN THE SOFTWARE.                                     *
 * -------------------------------------------------------------------------- */

#include "SimTKcommon/internal/common.h"
#include "SimTKcommon/internal/Array.h"
#include "SimTKcommon/internal/String.h"

#include <iterator>
#include <iostream>

namespace SimTK {

// These are declared but never defined; all TinyXML code is hidden.
class TiXmlNode; 
class TiXmlElement; 
class TiXmlAttribute;

//------------------------------------------------------------------------------
//                                   XML
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT Xml {
public:

// These local classes are used to describe the contents of an XML document.
class Attribute;
class Node;         // This is the abstract handle type for any node.
class Comment;      // These are the concrete node types.
class Unknown;      //                  "
class Text;         //                  "
class Element;      //                  "

// This provides iteration over all the attributes found in a given element.
class attribute_iterator;

// This provides iteration over all the nodes, or nodes of a certain type,
// at either the Xml document level or over the child nodes of an element.
class node_iterator;

// This provides iteration over all the element nodes that are children
// of a given element, or over the subset of those child elements that has
// a particular tag word.
class element_iterator;

enum NodeType {
    NoNode      = 0x00, 
    ElementNode = 0x01, 
    TextNode    = 0x02, 
    CommentNode = 0x04, 
    UnknownNode = 0x08, 

    NoJunkNodes = ElementNode|TextNode,    
    JunkNodes   = CommentNode|UnknownNode, 
    AnyNodes    = NoJunkNodes|JunkNodes    
};

static String getNodeTypeAsString(NodeType type);


Xml();

explicit Xml(const String& pathname);

void clear();
void readFromFile(const String& pathname);
void writeToFile(const String& pathname) const;

void readFromString(const String& xmlDocument);
void readFromString(const char* xmlDocument);
void writeToString(String& xmlDocument, bool compact = false) const;
String getPathname() const;

Element getRootElement();

const String& getRootTag() const;
void setRootTag(const String& tag);

void insertTopLevelNodeAfter (const node_iterator& afterThis, 
                              Node                 insertThis);
void insertTopLevelNodeBefore(const node_iterator& beforeThis, 
                              Node                 insertThis);
void eraseTopLevelNode(const node_iterator& deleteThis);
node_iterator       node_begin(NodeType allowed=AnyNodes);

node_iterator       node_end() const;
String getXmlVersion() const;
String getXmlEncoding() const;
bool getXmlIsStandalone() const;

void setXmlVersion(const String& version);
void setXmlEncoding(const String& encoding);
void setXmlIsStandalone(bool isStandalone);
//------------------------------------------------------------------------------
                                  private:
friend class Node;

class Impl; // a private, local class Xml::Impl
const Impl& getImpl() const {assert(impl); return *impl;}
Impl&       updImpl()       {assert(impl); return *impl;}

Xml& unconst() const {return *const_cast<Xml*>(this);}

Impl*       impl; // This is the lone data member.
};

// Do this inline so we don't have to pass the ostream through the API.
inline std::ostream& operator<<(std::ostream& o, const Xml& xmlDocument) {
    String output;
    xmlDocument.writeToString(output);
    return o << output;
}



//------------------------------------------------------------------------------
//                              XML ATTRIBUTE
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT Xml::Attribute {
public:
Attribute() : tiAttr(0) {}
Attribute(const String& name, const String& value);
Attribute(const Attribute& src) : tiAttr(src.tiAttr) {} 
Attribute& operator=(const Attribute& src) 
{   if (&src!=this) {clear(); tiAttr=src.tiAttr;} return *this; }
~Attribute() {clear();}
bool isValid() const {return tiAttr!=0;}
const String& getName() const;
const String& getValue() const;
Attribute& setName(const String& name);
Attribute& setValue(const String& value);

void clear();

void writeToString(String& out) const;

bool operator==(const Attribute& attr) const {return tiAttr==attr.tiAttr;}
bool operator!=(const Attribute& attr) const {return tiAttr!=attr.tiAttr;}

//------------------------------------------------------------------------------
                                  private:
friend class Xml::attribute_iterator;
friend class Xml::Element;

explicit Attribute(TiXmlAttribute* attr) {tiAttr=attr;}
const TiXmlAttribute& getTiAttr() const {assert(tiAttr);return *tiAttr;}
TiXmlAttribute&       updTiAttr()       {assert(tiAttr);return *tiAttr;}

// Careful; this does not clear the handle before replacing the pointer
// so must not be used if this could be the owner handle of an attribute
// that hasn't ever been added to a document. It is intended for use by
// iterators, whose contained Attributes can never be owners.
void                  setTiAttrPtr(TiXmlAttribute* attr) {tiAttr=attr;}
const TiXmlAttribute* getTiAttrPtr() const {return tiAttr;}
TiXmlAttribute*       updTiAttrPtr()       {return tiAttr;}

Attribute& unconst() const {return *const_cast<Attribute*>(this);}

TiXmlAttribute* tiAttr; // this is the lone data member
};

// Do this inline so we don't have to pass the ostream through the API.
inline std::ostream& operator<<(std::ostream& o, const Xml::Attribute& attr) {
    String output;
    attr.writeToString(output);
    return o << output;
}



//------------------------------------------------------------------------------
//                          XML ATTRIBUTE ITERATOR
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT Xml::attribute_iterator 
:   public std::iterator<std::bidirectional_iterator_tag, Xml::Attribute> {
public:
attribute_iterator() {}
explicit attribute_iterator(Attribute& attr) : attr(attr) {}
attribute_iterator(const attribute_iterator& src) 
:   attr(src->updTiAttrPtr()) {}
~attribute_iterator() {attr.setTiAttrPtr(0);}
attribute_iterator& operator=(const attribute_iterator& src) 
{   attr.setTiAttrPtr(src->updTiAttrPtr()); return *this; }
attribute_iterator& operator++();   // prefix
attribute_iterator operator++(int); // postfix
attribute_iterator& operator--();   // prefix
attribute_iterator operator--(int); // postfix

// It's the iterator that's const in these next two methods; it still points
// to a non-const object just like a char* const p.

Attribute& operator*() const {return const_cast<Attribute&>(attr);}
Attribute* operator->() const {return const_cast<Attribute*>(&attr);}
bool operator==(const attribute_iterator& other) const 
{   return other.attr==attr; }
bool operator!=(const attribute_iterator& other) const 
{   return other.attr!=attr; }

//------------------------------------------------------------------------------
                                  private:
friend class Xml::Element;

explicit attribute_iterator(TiXmlAttribute* ap) : attr(ap) {}

Attribute       attr;   // the lone data member
};



//------------------------------------------------------------------------------
//                               XML NODE
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT Xml::Node {
public:


Node() : tiNode(0) {}
Node(const Node& src) : tiNode(src.tiNode) {} 
Node& operator=(const Node& src) 
{   if (&src!=this) {clear(); tiNode=src.tiNode;} return *this; }
~Node() {clear();}
void clear();

NodeType getNodeType() const;

String getNodeTypeAsString() const;

bool isValid() const {return tiNode != 0;}

bool isTopLevelNode() const;

bool isOrphan() const;

bool hasParentElement() const;

Element getParentElement();

const String& getNodeText() const;

void writeToString(String& out, bool compact=false) const;
bool operator==(const Node& other) const {return other.tiNode==tiNode;}
bool operator!=(const Node& other) const {return other.tiNode!=tiNode;}


//------------------------------------------------------------------------------
                                 protected: // don't let Doxygen see these
explicit Node(TiXmlNode* tiNode) : tiNode(tiNode) {}

const TiXmlNode& getTiNode() const {assert(tiNode);return *tiNode;}
TiXmlNode&       updTiNode()       {assert(tiNode);return *tiNode;}

// Careful: these "Ptr" methods provide raw access to the contained 
// pointer without any cleanup or error checking. In particular, 
// setTiNodePtr() does not attempt to delete the current contents.
void setTiNodePtr(TiXmlNode* node) {tiNode=node;}
const TiXmlNode* getTiNodePtr() const {return tiNode;}
TiXmlNode*       updTiNodePtr()       {return tiNode;}
//------------------------------------------------------------------------------
                                  private:
friend class Xml;
friend class Xml::Impl;
friend class Xml::node_iterator;
friend class Xml::Comment;
friend class Xml::Unknown;
friend class Xml::Text;
friend class Xml::Element;

Node& unconst() const {return *const_cast<Node*>(this);}

TiXmlNode*      tiNode; // the lone data member
};

// Do this inline so we don't have to pass the ostream through the API.
inline std::ostream& operator<<(std::ostream& o, const Xml::Node& xmlNode) {
    String output;
    xmlNode.writeToString(output);
    return o << output;
}



//------------------------------------------------------------------------------
//                          XML NODE ITERATOR
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT Xml::node_iterator 
:   public std::iterator<std::bidirectional_iterator_tag, Xml::Node> {
public:

explicit node_iterator(NodeType allowed=AnyNodes) 
:   allowed(allowed) {}
explicit node_iterator(Node& node, NodeType allowed=AnyNodes) 
:   node(node), allowed(allowed) {}

node_iterator(const node_iterator& src) 
:   node(*src), allowed(src.allowed) {}
~node_iterator() {node.setTiNodePtr(0);}
node_iterator& operator=(const node_iterator& src) 
{   node = *src; allowed = src.allowed; return *this; }

node_iterator& operator++();   // prefix
node_iterator operator++(int); // postfix
node_iterator& operator--();   // prefix
node_iterator operator--(int); // postfix
Node& operator*() {return node;}
Node* operator->() {return &node;}
// It's the iterator that's const; it still points to a non-const object
// just like a char* const p.
Node& operator*()  const {return const_cast<Node&>(node);}
Node* operator->() const {return const_cast<Node*>(&node);}
bool operator==(const node_iterator& other) const {return other.node==node;}
bool operator!=(const node_iterator& other) const {return other.node!=node;}

//------------------------------------------------------------------------------
                                 protected:
explicit node_iterator(TiXmlNode* tiNode, NodeType allowed=AnyNodes) 
:   node(tiNode), allowed(allowed) {}
void reassign(TiXmlNode* tiNode)
{   node.setTiNodePtr(tiNode); }

//------------------------------------------------------------------------------
                                  private:
friend class Xml;
friend class Xml::Node;
friend class Xml::Element;
friend class Xml::element_iterator;

Node            node;       // data members
NodeType        allowed;
};



//------------------------------------------------------------------------------
//                          XML ELEMENT ITERATOR
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT Xml::element_iterator
:   public Xml::node_iterator {
public:

explicit element_iterator(const String& tag="") 
:   node_iterator(ElementNode), tag(tag) {}
inline explicit element_iterator(Element& elt, const String& tag=""); // below

element_iterator(const element_iterator& src) 
:   node_iterator(src), tag(src.tag) {}

element_iterator& operator=(const element_iterator& src) 
{   upcast()=src; tag = src.tag; return *this; }

element_iterator& operator++();   // prefix
element_iterator operator++(int); // postfix
element_iterator& operator--();   // prefix
element_iterator operator--(int); // postfix
inline Element& operator*() const; // below
inline Element* operator->() const; // below

bool operator==(const element_iterator& other) const 
{   return other.upcast()==upcast();}
bool operator!=(const element_iterator& other) const 
{   return other.upcast()!=upcast();}

//------------------------------------------------------------------------------
                                   private:
friend class Xml;
friend class Xml::Element;

explicit element_iterator(TiXmlElement* tiElt, const String& tag="") 
:   node_iterator((TiXmlNode*)tiElt, ElementNode), tag(tag) {}
void reassign(TiXmlElement* tiElt)
{   upcast().reassign((TiXmlNode*)tiElt); }

const node_iterator& upcast() const 
{   return *static_cast<const node_iterator*>(this); }
node_iterator& upcast() 
{   return *static_cast<node_iterator*>(this); }

String          tag;    // lone data member
};




//------------------------------------------------------------------------------
//                               XML ELEMENT
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT Xml::Element : public Xml::Node {
public:


Element() : Node() {}

explicit Element(const String& tagWord, const String& value="");

template <class T>
Element(const String& tagWord, const T& value)
{   new(this) Element(tagWord, String(value)); }

const String& getElementTag() const;
void setElementTag(const String& tag);

void insertNodeBefore(const node_iterator& pos, Node node);
void insertNodeAfter(const node_iterator& pos, Node node);
void eraseNode(const node_iterator& deleteThis);

bool isValueElement() const;

const String& getValue() const;

String& updValue();

void setValue(const String& value);

template <class T>
void setValueAs(const T& value) 
{   setValue(String(value)); }

template <class T> T getValueAs() const 
{   T out; convertStringTo(getValue(),out); return out;}

template <class T> void getValueAs(T& out) const 
{   convertStringTo(getValue(),out); }

const String& 
getRequiredElementValue(const String& tag) const
{   return unconst().getRequiredElement(tag).getValue(); }

String 
getOptionalElementValue(const String& tag, const String& def="") const
{   const Element opt(unconst().getOptionalElement(tag));
    return opt.isValid() ? opt.getValue() : def; }

template <class T> T  
getRequiredElementValueAs(const String& tag) const
{   T out; convertStringTo(getRequiredElementValue(tag), out); return out; }

template <class T> T 
getOptionalElementValueAs(const String& tag, const T& def) const
{   const Element opt(getOptionalElement(tag));
    if (!opt.isValid()) return def;
    T out; convertStringTo(opt.getValue(), out); return out; }
bool hasAttribute(const String& name) const;

void setAttributeValue(const String& name, const String& value);

void removeAttribute(const String& name);

const String& 
getRequiredAttributeValue(const String& name) const
{   return unconst().getRequiredAttribute(name).getValue(); }

template <class T> T 
getRequiredAttributeValueAs(const String& name) const
{   T out; convertStringTo(getRequiredAttributeValue(name),out); return out; }

String 
getOptionalAttributeValue(const String& name, const String& def="") const
{   Attribute attr = unconst().getOptionalAttribute(name);
    if (!attr.isValid()) return def;
    return attr.getValue(); }

template <class T> T 
getOptionalAttributeValueAs(const String& name, const T& def) const
{   Attribute attr = unconst().getOptionalAttribute(name);
    if (!attr.isValid()) return def;
    T out; convertStringTo(attr.getValue(), out); return out; }

Attribute getRequiredAttribute(const String& name);

Attribute getOptionalAttribute(const String& name);

Array_<Attribute> getAllAttributes()
{   return Array_<Attribute>(attribute_begin(), attribute_end()); }


attribute_iterator attribute_begin();
attribute_iterator attribute_end() const;

bool hasElement(const String& tag) const;
bool hasNode(NodeType allowed=AnyNodes) const;

Element getRequiredElement(const String& tag);

Element getOptionalElement(const String& tag);

Array_<Element> getAllElements(const String& tag="")
{   return Array_<Element>(element_begin(tag), element_end()); }

Array_<Node> getAllNodes(NodeType allowed=AnyNodes)
{   return Array_<Node>(node_begin(allowed), node_end()); }

element_iterator element_begin(const String& tag="");
element_iterator element_end() const;

node_iterator node_begin(NodeType allowed=AnyNodes);
node_iterator node_end() const;
static bool isA(const Node&);
static const Element& getAs(const Node& node);
static Element& getAs(Node& node);
//------------------------------------------------------------------------------
                                  private:
friend class Xml::Node;
friend class Xml::element_iterator;

explicit Element(TiXmlElement* tiElt) 
:   Node(reinterpret_cast<TiXmlNode*>(tiElt)) {}

TiXmlElement& updTiElement() 
{   return reinterpret_cast<TiXmlElement&>(updTiNode()); } 
const TiXmlElement& getTiElement() const
{   return reinterpret_cast<const TiXmlElement&>(getTiNode()); }

// Careful: these "Ptr" methods provide raw access to the contained 
// pointer without any cleanup or error checking. In particular, 
// setTiElementPtr() does not attempt to delete the current contents.
const TiXmlElement* getTiElementPtr() const 
{   return reinterpret_cast<const TiXmlElement*>(getTiNodePtr()); }
TiXmlElement*       updTiElementPtr()
{   return reinterpret_cast<TiXmlElement*>(updTiNodePtr()); }
void                setTiElementPtr(TiXmlElement* elt)
{   setTiNodePtr(reinterpret_cast<TiXmlNode*>(elt)); }

Element& unconst() const {return *const_cast<Element*>(this);}


// no data members; see Node
};



// A few element_iterator inline definitions had to wait for Element to be
// defined.
inline Xml::element_iterator::element_iterator
   (Xml::Element& elt, const String& tag) 
:   Xml::node_iterator(elt, Xml::ElementNode), tag(tag) {}
inline Xml::Element& Xml::element_iterator::operator*() const 
{   return Element::getAs(*upcast());}
inline Xml::Element* Xml::element_iterator::operator->() const 
{   return &Element::getAs(*upcast());}




//------------------------------------------------------------------------------
//                               XML TEXT NODE
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT Xml::Text : public Xml::Node {
public:
Text() : Node() {}

explicit Text(const String& text);

const String& getText() const;
String& updText();

static bool isA(const Node&);
static const Text& getAs(const Node& node);
static Text& getAs(Node& node);
//------------------------------------------------------------------------------
                                   private:
// no data members; see Node
};



//------------------------------------------------------------------------------
//                             XML COMMENT NODE
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT Xml::Comment : public Xml::Node {
public:
Comment() : Node() {}

explicit Comment(const String& text);


static bool isA(const Node&);
static const Comment& getAs(const Node& node);
static Comment& getAs(Node& node);
//------------------------------------------------------------------------------
                                   private:
// no data members; see Node
};



//------------------------------------------------------------------------------
//                             XML UNKNOWN NODE
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT Xml::Unknown : public Xml::Node {
public:
Unknown() : Node() {}

explicit Unknown(const String& contents);

Unknown(Element& element, const String& contents)
{   new(this) Unknown(contents); 
    element.insertNodeBefore(element.node_end(), *this); }

const String& getContents() const;
void setContents(const String& contents);

static bool isA(const Node&);
static const Unknown& getAs(const Node& node);
static Unknown& getAs(Node& node);
//------------------------------------------------------------------------------
                                   private:
// no data members; see Node
};

} // namespace SimTK

#endif // SimTK_SimTKCOMMON_XML_H_