Xml.h

Go to the documentation of this file.

#ifndef SimTK_SimTKCOMMON_XML_H_
#define SimTK_SimTKCOMMON_XML_H_

/* -------------------------------------------------------------------------- *
 *                       Simbody(tm): SimTKcommon                             *
 * -------------------------------------------------------------------------- *
 * This is part of the SimTK 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/home/simbody.  *
 *                                                                            *
 * Portions copyright (c) 2010-15 Stanford University and the Authors.        *
 * Authors: Michael Sherman                                                   *
 * Contributors: Peter Eastman                                                *
 *                                                                            *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may    *
 * not use this file except in compliance with the License. You may obtain a  *
 * copy of the License at http://www.apache.org/licenses/LICENSE-2.0.         *
 *                                                                            *
 * Unless required by applicable law or agreed to in writing, software        *
 * distributed under the License is distributed on an "AS IS" BASIS,          *
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.   *
 * See the License for the specific language governing permissions and        *
 * limitations under the License.                                             *
 * -------------------------------------------------------------------------- */

#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;
class TiXmlText;
class TiXmlComment;
class TiXmlUnknown;

namespace Xml {

// These classes are defined below.
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    
};

String getNodeTypeAsString(NodeType type);
    
//------------------------------------------------------------------------------
//                               XML :: DOCUMENT
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT Document {
public:

Document();

explicit Document(const String& pathname);

Document(const Document& source);

Document& operator=(const Document& souce);

~Document();

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;
void setIndentString(const String& indent);
const String& getIndentString() const;

static void setXmlCondenseWhiteSpace(bool shouldCondense);
static bool isXmlWhiteSpaceCondensed();

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 removeTopLevelNode(const node_iterator& removeThis);
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 Document::Impl
const Impl& getImpl() const {assert(impl); return *impl;}
Impl&       updImpl()       {assert(impl); return *impl;}

Document& unconst() const {return *const_cast<Document*>(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 Document& doc) {
    String output;
    doc.writeToString(output);
    return o << output;
}



//------------------------------------------------------------------------------
//                              XML ATTRIBUTE
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT 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;}
bool isOrphan() const;
const String& getName() const;
const String& getValue() const;
Attribute& setName(const String& name);
Attribute& setValue(const String& value);

void clear();
void clearOrphan();

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 attribute_iterator;
friend class 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 should 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  Attribute& attr) {
    String output;
    attr.writeToString(output);
    return o << output;
}



//------------------------------------------------------------------------------
//                          XML ATTRIBUTE ITERATOR
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT attribute_iterator 
:   public std::iterator<std::bidirectional_iterator_tag, 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 Element;

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

Attribute       attr;   // the lone data member
};



//------------------------------------------------------------------------------
//                               XML :: NODE
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT 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 clone() const;
~Node() {clear();}
void clear();
void clearOrphan();

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 Document;
friend class node_iterator;
friend class Comment;
friend class Unknown;
friend class Text;
friend class 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 Node& xmlNode) {
    String output;
    xmlNode.writeToString(output);
    return o << output;
}



//------------------------------------------------------------------------------
//                          XML :: NODE ITERATOR
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT node_iterator 
:   public std::iterator<std::bidirectional_iterator_tag, 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 Document;
friend class Node;
friend class Element;
friend class element_iterator;

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



//------------------------------------------------------------------------------
//                          XML :: ELEMENT ITERATOR
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT element_iterator: public 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 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 Element : public 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)); }

Element clone() const;

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 appendNode(Node node) {insertNodeAfter(node_end(), node);}

void eraseNode(const node_iterator& deleteThis);
Node removeNode(const node_iterator& removeThis);

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(unconst().getRequiredElementValue(tag), out); 
    return out; }

template <class T> T 
getOptionalElementValueAs(const String& tag, const T& def) const
{   const Element opt(unconst().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 eraseAttribute(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 Node;
friend class 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 element_iterator::element_iterator
   (Element& elt, const String& tag) 
:   node_iterator(elt, ElementNode), tag(tag) {}
inline Element& element_iterator::operator*() const 
{   return Element::getAs(*upcast());}
inline Element* element_iterator::operator->() const 
{   return &Element::getAs(*upcast());}




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

explicit Text(const String& text);

Text clone() const;

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

explicit Text(TiXmlText* tiText) 
:   Node(reinterpret_cast<TiXmlNode*>(tiText)) {}
};



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

explicit Comment(const String& text);

Comment clone() const;

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

explicit Comment(TiXmlComment* tiComment) 
:   Node(reinterpret_cast<TiXmlNode*>(tiComment)) {}
};



//------------------------------------------------------------------------------
//                             XML :: UNKNOWN NODE
//------------------------------------------------------------------------------
class SimTK_SimTKCOMMON_EXPORT Unknown : public 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); }

Unknown clone() const;

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

explicit Unknown(TiXmlUnknown* tiUnknown) 
:   Node(reinterpret_cast<TiXmlNode*>(tiUnknown)) {}
};

} // end of namespace Xml


template <class T> inline Xml::Element
toXmlElement(const T& thing, const std::string& name) {
    std::ostringstream os;
    writeUnformatted(os, thing);
    return Xml::Element(name.empty()?"value":name, os.str());
}

template <class T> inline
auto toXmlElementHelper(const T& thing, const std::string& name, bool)
    -> decltype(std::declval<T>().toXmlElement(name)) {
    return thing.toXmlElement(name); // call member function
}

template <class T> inline
auto toXmlElementHelper(const T& thing, const std::string& name, int) 
    -> Xml::Element  {
    return toXmlElement(thing, name); // call free function
}

template <class T> inline void
fromXmlElement(T& thing, Xml::Element& elt, 
               const std::string& requiredName="") {
    if (!requiredName.empty()) {
        const String& name = elt.getElementTag();
        SimTK_ERRCHK2_ALWAYS(name==requiredName, "fromXmlElement<T>",
        "Expected element name '%s' but got '%s'.", requiredName.c_str(), 
                                                    name.c_str());
    }
    std::istringstream is(elt.getValue());
    const bool readOK = readUnformatted(is, thing);
    SimTK_ERRCHK2_ALWAYS(readOK, "fromXmlElement<T>",
        "Failed to read an object of type T='%s' from element value '%s' "
        "using readUnformatted<T>().",
        NiceTypeName<T>::namestr().c_str(), elt.getValue().c_str());
}

template <class T> inline
auto fromXmlElementHelper(T& thing, Xml::Element& elt, 
                          const std::string& requiredTag, bool)
    -> decltype(std::declval<T>().fromXmlElement(elt,requiredTag)) {
    return thing.fromXmlElement(elt,requiredTag); // call member function
}

template <class T> inline
auto fromXmlElementHelper(T& thing, Xml::Element& elt, 
                          const std::string& requiredTag, int) 
    -> void {
    fromXmlElement(thing, elt, requiredTag); // call free function
}


// Definition of these functions (which should really be methods of 
// the Array_ classes) has to wait until Xml classes are declared because Xml 
// uses Array_.

template <class T, class X>
Xml::Element toXmlElement(const ArrayViewConst_<T,X>& thing,
                          const std::string& name="") {
    static const int version = 1;
    Xml::Element e("Array");
    if (!name.empty()) e.setAttributeValue("name", name);
    e.setAttributeValue("version", String(version));
    for (const auto& v : thing)
        e.appendNode(toXmlElementHelper(v, "", true));
    return e;
}

template <class T, class X>
Xml::Element toXmlElement(const ArrayView_<T,X>& thing,
                          const std::string& name="") {
    return toXmlElement(static_cast<const ArrayViewConst_<T,X>&>(thing),name);
}

template <class T, class X>
Xml::Element toXmlElement(const Array_<T,X>& thing,
                          const std::string& name="") {
    return toXmlElement(static_cast<const ArrayViewConst_<T,X>&>(thing),name);
}

} // namespace SimTK

#endif // SimTK_SimTKCOMMON_XML_H_