1 #ifndef SimTK_SimTKCOMMON_XML_H_ 2 #define SimTK_SimTKCOMMON_XML_H_ 56 class attribute_iterator;
65 class element_iterator;
353 void readFromFile(
const String& pathname);
358 void writeToFile(
const String& pathname)
const;
362 void readFromString(
const String& xmlDocument);
366 void readFromString(
const char* xmlDocument);
372 void writeToString(
String& xmlDocument,
bool compact =
false)
const;
377 void setIndentString(
const String& indent);
380 const String& getIndentString()
const;
385 static void setXmlCondenseWhiteSpace(
bool shouldCondense);
388 static bool isXmlWhiteSpaceCondensed();
416 const String& getRootTag()
const;
419 void setRootTag(
const String& tag);
428 void insertTopLevelNodeAfter (
const node_iterator& afterThis,
432 void insertTopLevelNodeBefore(
const node_iterator& beforeThis,
489 String getXmlVersion()
const;
492 String getXmlEncoding()
const;
498 bool getXmlIsStandalone()
const;
502 void setXmlVersion(
const String& version);
505 void setXmlEncoding(
const String& encoding);
510 void setXmlIsStandalone(
bool isStandalone);
518 const Impl& getImpl()
const {assert(impl);
return *impl;}
519 Impl& updImpl() {assert(impl);
return *impl;}
521 Document& unconst()
const {
return *
const_cast<Document*
>(
this);}
563 {
if (&src!=
this) {clear(); tiAttr=src.tiAttr;}
return *
this; }
574 bool isOrphan()
const;
576 const String& getName()
const;
579 const String& getValue()
const;
601 void writeToString(
String& out)
const;
614 explicit Attribute(TiXmlAttribute* attr) {tiAttr=attr;}
615 const TiXmlAttribute& getTiAttr()
const {assert(tiAttr);
return *tiAttr;}
616 TiXmlAttribute& updTiAttr() {assert(tiAttr);
return *tiAttr;}
622 void setTiAttrPtr(TiXmlAttribute* attr) {tiAttr=attr;}
623 const TiXmlAttribute* getTiAttrPtr()
const {
return tiAttr;}
624 TiXmlAttribute* updTiAttrPtr() {
return tiAttr;}
626 Attribute& unconst()
const {
return *
const_cast<Attribute*
>(
this);}
628 TiXmlAttribute* tiAttr;
650 :
public std::iterator<std::bidirectional_iterator_tag, Attribute> {
661 : attr(src->updTiAttrPtr()) {}
667 { attr.setTiAttrPtr(src->updTiAttrPtr());
return *
this; }
700 {
return other.attr==attr; }
703 {
return other.attr!=attr; }
762 {
if (&src!=
this) {clear(); tiNode=src.tiNode;}
return *
this; }
801 bool isTopLevelNode()
const;
807 bool isOrphan()
const;
812 bool hasParentElement()
const;
835 const String& getNodeText()
const;
843 void writeToString(
String& out,
bool compact=
false)
const;
857 explicit Node(TiXmlNode* tiNode) : tiNode(tiNode) {}
859 const TiXmlNode& getTiNode()
const {assert(tiNode);
return *tiNode;}
860 TiXmlNode& updTiNode() {assert(tiNode);
return *tiNode;}
865 void setTiNodePtr(TiXmlNode* node) {tiNode=node;}
866 const TiXmlNode* getTiNodePtr()
const {
return tiNode;}
867 TiXmlNode* updTiNodePtr() {
return tiNode;}
879 Node& unconst()
const {
return *
const_cast<Node*
>(
this);}
905 :
public std::iterator<std::bidirectional_iterator_tag, Node> {
909 : allowed(allowed) {}
911 : node(node), allowed(allowed) {}
916 : node(*src), allowed(src.allowed) {}
922 { node = *src; allowed = src.allowed;
return *
this; }
940 : node(tiNode), allowed(allowed) {}
942 { node.setTiNodePtr(tiNode); }
983 { upcast()=src; tag = src.tag;
return *
this; }
990 inline Element* operator->()
const;
993 {
return other.upcast()==upcast();}
995 {
return other.upcast()!=upcast();}
1003 void reassign(TiXmlElement* tiElt)
1004 { upcast().
reassign((TiXmlNode*)tiElt); }
1006 const node_iterator& upcast()
const 1007 {
return *
static_cast<const node_iterator*
>(
this); }
1008 node_iterator& upcast()
1009 {
return *
static_cast<node_iterator*
>(
this); }
1078 const String& getElementTag()
const;
1080 void setElementTag(
const String& tag);
1129 bool isValueElement()
const;
1138 const String& getValue()
const;
1152 void setValue(
const String& value);
1159 { setValue(
String(value)); }
1168 { T out; convertStringTo(getValue(),out);
return out;}
1173 { convertStringTo(getValue(),out); }
1184 {
return unconst().getRequiredElement(tag).getValue(); }
1191 {
const Element opt(unconst().getOptionalElement(tag));
1202 template <
class T> T
1204 { T out; convertStringTo(unconst().getRequiredElementValue(tag), out);
1218 template <
class T> T
1220 {
const Element opt(unconst().getOptionalElement(tag));
1221 if (!opt.
isValid())
return def;
1222 T out; convertStringTo(opt.
getValue(), out);
return out; }
1232 bool hasAttribute(
const String& name)
const;
1236 void setAttributeValue(
const String& name,
const String& value);
1242 void eraseAttribute(
const String& name);
1248 {
return unconst().getRequiredAttribute(name).getValue(); }
1256 template <
class T> T
1258 { T out; convertStringTo(getRequiredAttributeValue(name),out);
return out; }
1268 {
Attribute attr = unconst().getOptionalAttribute(name);
1269 if (!attr.
isValid())
return def;
1282 template <
class T> T
1284 {
Attribute attr = unconst().getOptionalAttribute(name);
1285 if (!attr.
isValid())
return def;
1286 T out; convertStringTo(attr.
getValue(), out);
return out; }
1331 bool hasElement(
const String& tag)
const;
1364 {
return Array_<Node>(node_begin(allowed), node_end()); }
1390 static bool isA(
const Node&);
1404 explicit Element(TiXmlElement* tiElt)
1405 :
Node(reinterpret_cast<TiXmlNode*>(tiElt)) {}
1407 TiXmlElement& updTiElement()
1408 {
return reinterpret_cast<TiXmlElement&
>(updTiNode()); }
1409 const TiXmlElement& getTiElement()
const 1410 {
return reinterpret_cast<const TiXmlElement&
>(getTiNode()); }
1415 const TiXmlElement* getTiElementPtr()
const 1416 {
return reinterpret_cast<const TiXmlElement*
>(getTiNodePtr()); }
1417 TiXmlElement* updTiElementPtr()
1418 {
return reinterpret_cast<TiXmlElement*
>(updTiNodePtr()); }
1419 void setTiElementPtr(TiXmlElement* elt)
1420 { setTiNodePtr(reinterpret_cast<TiXmlNode*>(elt)); }
1422 Element& unconst()
const {
return *
const_cast<Element*
>(
this);}
1464 const String& getText()
const;
1474 static bool isA(
const Node&);
1477 static const Text& getAs(
const Node& node);
1487 explicit Text(TiXmlText* tiText)
1488 :
Node(reinterpret_cast<TiXmlNode*>(tiText)) {}
1519 static bool isA(
const Node&);
1532 explicit Comment(TiXmlComment* tiComment)
1533 :
Node(reinterpret_cast<TiXmlNode*>(tiComment)) {}
1559 {
new(
this)
Unknown(contents);
1569 const String& getContents()
const;
1572 void setContents(
const String& contents);
1579 static bool isA(
const Node&);
1592 explicit Unknown(TiXmlUnknown* tiUnknown)
1593 :
Node(reinterpret_cast<TiXmlNode*>(tiUnknown)) {}
1621 template <
class T>
inline Xml::Element
1623 std::ostringstream os;
1625 return Xml::Element(name.empty()?
"value":name, os.str());
1631 template <
class T>
inline 1633 -> decltype(std::declval<T>().toXmlElement(name)) {
1634 return thing.toXmlElement(name);
1640 template <
class T>
inline 1643 return toXmlElement(thing, name);
1667 template <
class T>
inline void 1669 const std::string& requiredName=
"") {
1670 if (!requiredName.empty()) {
1673 "Expected element name '%s' but got '%s'.", requiredName.c_str(),
1676 std::istringstream is(elt.
getValue());
1679 "Failed to read an object of type T='%s' from element value '%s' " 1680 "using readUnformatted<T>().",
1687 template <
class T>
inline 1689 const std::string& requiredTag,
bool)
1690 -> decltype(std::declval<T>().fromXmlElement(elt,requiredTag)) {
1691 return thing.fromXmlElement(elt,requiredTag);
1697 template <
class T>
inline 1699 const std::string& requiredTag,
int)
1701 fromXmlElement(thing, elt, requiredTag);
1719 template <
class T,
class X>
1721 const std::string& name=
"") {
1722 static const int version = 1;
1726 for (
const auto& v : thing)
1727 e.
appendNode(toXmlElementHelper(v,
"",
true));
1736 template <
class T,
class X>
1738 const std::string& name=
"") {
1747 template <
class T,
class X>
1749 const std::string& name=
"") {
1755 #endif // SimTK_SimTKCOMMON_XML_H_ void writeToString(String &xmlDocument, bool compact=false) const
Write the contents of this in-memory Xml::Document to the supplied string.
Unknown()
Create an empty Unknown node handle, suitable only for holding references to other Unknown nodes...
Definition: Xml.h:1546
Unknown node type and only-Unknowns filter.
Definition: Xml.h:77
bool operator==(const Node &other) const
Comparing Nodes for equality means asking if the two Node handles are referring to exactly the same o...
Definition: Xml.h:849
This Array_ helper class is the base class for Array_, extending ArrayViewConst_ to add the ability t...
Definition: Array.h:52
bool operator!=(const Node &other) const
Inequality test using same criteria as operator==().
Definition: Xml.h:851
Attribute(const Attribute &src)
Copy constructor is shallow; that is, this handle will refer to the same attribute as the source...
Definition: Xml.h:557
node_iterator(TiXmlNode *tiNode, NodeType allowed=AnyNodes)
Definition: Xml.h:939
#define SimTK_SimTKCOMMON_EXPORT
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:224
#define SimTK_ERRCHK2_ALWAYS(cond, whereChecked, fmt, a1, a2)
Definition: ExceptionMacros.h:289
Xml::Element toXmlElement(const T &thing, const std::string &name)
Default implementation of serialization to an XML element for objects whose class does not define a m...
Definition: Xml.h:1622
~Attribute()
The Attribute handle destructor does not recover heap space so if you create orphan attributes and th...
Definition: Xml.h:567
String getNodeTypeAsString(NodeType type)
Translate a NodeType to a human-readable string.
This is something we don't understand but can carry around.
Definition: Xml.h:1542
auto fromXmlElementHelper(T &thing, Xml::Element &elt, const std::string &requiredTag, int) -> void
Helper function for fromXmlElement() that selects the free function if no member function exists...
Definition: Xml.h:1698
Array_< Attribute > getAllAttributes()
Return an array containing Attribute handles referencing all the attributes of this element...
Definition: Xml.h:1305
Text()
Create an empty Text node handle, suitable only for holding references to other Text nodes...
Definition: Xml.h:1451
node_iterator & operator=(const node_iterator &src)
Copy assignment takes an node_iterator that can be const, but that still allows writing to the Node...
Definition: Xml.h:921
const String & getRequiredAttributeValue(const String &name) const
Get the value of an attribute as a string and throw an error if that attribute is not present...
Definition: Xml.h:1247
const String & getValue() const
If this is a valid attribute handle, get the value of the attribute as a String, not including the qu...
Attribute & operator*() const
Return a writable reference to the Attribute referenced by this iterator; the handle will be invalid ...
Definition: Xml.h:690
const String & getElementTag() const
Get the element tag word.
String getOptionalElementValue(const String &tag, const String &def="") const
Get the text value of a child value element that may be present in this element, otherwise return a d...
Definition: Xml.h:1190
bool operator!=(const node_iterator &other) const
Definition: Xml.h:935
Node & operator*() const
Definition: Xml.h:932
Element(const String &tagWord, const T &value)
Create a new value element and set its initial value to the text equivalent of any type T for which a...
Definition: Xml.h:1068
bool readUnformatted(std::istream &in, T &v)
The default implementation of readUnformatted<T> reads in the next whitespace-separated token and the...
Definition: Serialize.h:176
This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with o...
Definition: Assembler.h:37
Node()
Create an empty Node handle that can be used to hold a reference to any kind of Node.
Definition: Xml.h:752
auto toXmlElementHelper(const T &thing, const std::string &name, int) -> Xml::Element
Helper function for toXmlElement() that selects the free function if no member function exists...
Definition: Xml.h:1641
node_iterator(NodeType allowed=AnyNodes)
Definition: Xml.h:908
void reassign(TiXmlNode *tiNode)
Definition: Xml.h:941
NodeType
The Xml::NodeType enum serves as the actual type of a node and as a filter for allowable node types d...
Definition: Xml.h:72
node_iterator(const node_iterator &src)
Copy constructor takes a node_iterator that can be const, but that still allows writing to the Node...
Definition: Xml.h:915
~Node()
The Node handle destructor does not recover heap space so if you create orphan nodes and then don't p...
Definition: Xml.h:770
Text node type and only-Text nodes filter.
Definition: Xml.h:75
bool isValid() const
Is this handle currently holding an attribute?
Definition: Xml.h:569
Array_< Node > getAllNodes(NodeType allowed=AnyNodes)
Return an array containing Node handles referencing all the immediate child nodes contained in this e...
Definition: Xml.h:1363
Comment node type and only-Comments filter.
Definition: Xml.h:76
Node * operator->()
Definition: Xml.h:929
Element * operator->() const
Definition: Xml.h:1437
static const Element & getAs(const Node &node)
Recast a Node to a const Element, throwing an error if the Node is not actually an element node...
attribute_iterator()
Default constructor creates an iterator that compares equal to attribute_end().
Definition: Xml.h:654
element_iterator & operator=(const element_iterator &src)
Copy assignment takes an element_iterator that can be const, but that still allows writing to the Ele...
Definition: Xml.h:982
T getValueAs() const
Assuming this is a "value element", convert its text value to the type of the template argument T...
Definition: Xml.h:1167
void fromXmlElement(T &thing, Xml::Element &elt, const std::string &requiredName="")
Default implementation of deserialization from an XML element for objects whose class does not define...
Definition: Xml.h:1668
element_iterator(const String &tag="")
This is the default constructor which leaves the element_iterator empty, and you can optionally set t...
Definition: Xml.h:969
This file defines the Array_<T,X> class and related support classes including base classes ArrayViewC...
Type of empty Node handle, or null filter.
Definition: Xml.h:73
bool operator==(const node_iterator &other) const
Definition: Xml.h:934
bool operator!=(const attribute_iterator &other) const
Uses same criteria as operator==().
Definition: Xml.h:702
This is a bidirectional iterator suitable for moving forward or backward within a list of Attributes ...
Definition: Xml.h:649
Allow all nodes.
Definition: Xml.h:81
Element()
Create an empty Element handle; this is suitable only for holding references to other Elements...
Definition: Xml.h:1046
auto fromXmlElementHelper(T &thing, Xml::Element &elt, const std::string &requiredTag, bool) -> decltype(std::declval< T >().fromXmlElement(elt, requiredTag))
Helper function for fromXmlElement() that selects the member function if it exists.
Definition: Xml.h:1688
This is the "leaf" content of an element.
Definition: Xml.h:1447
bool operator==(const Attribute &attr) const
Comparison operators return true if the same attribute is being referenced or both handles are empty...
Definition: Xml.h:606
Element & operator*() const
Definition: Xml.h:1435
bool isValid() const
Return true if this Node handle is referencing some node, false if the Node handle is empty...
Definition: Xml.h:796
Node(const Node &src)
Copy constructor is shallow; that is, this handle will refer to the same node as the source...
Definition: Xml.h:756
std::ostream & operator<<(std::ostream &o, const Attribute &attr)
Output a textual representation of the given Xml::Attribute to an std::ostream.
Definition: Xml.h:636
Attribute & operator=(const Attribute &src)
Copy assignment is shallow; the handle is first cleared and then will refer to the same attribute as ...
Definition: Xml.h:562
An element has (1) a tagword, (2) a map of (name,value) pairs called attributes, and (3) a list of ch...
Definition: Xml.h:1033
std::ostream & operator<<(std::ostream &o, const Node &xmlNode)
Output a "pretty printed" textual representation of the given XML node (and all its contents) to an s...
Definition: Xml.h:890
std::ostream & operator<<(std::ostream &o, const Document &doc)
Output a "pretty printed" textual representation of the given Xml::Document to an std::ostream...
Definition: Xml.h:531
void appendNode(Node node)
This is an abbreviation for insertNodeAfter(node_end(), node);.
Definition: Xml.h:1096
Attribute()
Default constructor creates a null Attribute handle.
Definition: Xml.h:550
Matrix_< E > operator*(const MatrixBase< E > &l, const typename CNT< E >::StdNumber &r)
Definition: BigMatrix.h:605
The Array_<T> container class is a plug-compatible replacement for the C++ standard template library ...
Definition: Array.h:53
void writeToString(String &out, bool compact=false) const
Serialize this node (and everything it contains) to the given String.
Xml::Element toXmlElement(const Array_< T, X > &thing, const std::string &name="")
Partial specialization for XML serialization of Array_ objects.
Definition: Xml.h:1748
~node_iterator()
An iterator destructor never deletes the object to which it refers.
Definition: Xml.h:918
void setValueAs(const T &value)
Set the value of this value element to the text equivalent of any type T for which a conversion const...
Definition: Xml.h:1158
node_iterator node_end() const
This node_end() iterator indicates the end of any sequence of nodes regardless of the NodeType restri...
void setAttributeValue(const String &name, const String &value)
Set the value of an attribute of this element, creating a new one if this is a new attribute name oth...
auto toXmlElementHelper(const T &thing, const std::string &name, bool) -> decltype(std::declval< T >().toXmlElement(name))
Helper function for toXmlElement() that selects the member function if it exists. ...
Definition: Xml.h:1632
Xml::Element toXmlElement(const ArrayView_< T, X > &thing, const std::string &name="")
Partial specialization for XML serialization of ArrayView_ objects.
Definition: Xml.h:1737
bool operator==(const attribute_iterator &other) const
Comparison return true only if both iterators refer to the same in-memory attribute or both are at at...
Definition: Xml.h:699
void getValueAs(T &out) const
Alternate form of getValueAs() that avoids unnecessary copying and heap allocation for reading in lar...
Definition: Xml.h:1172
const String & getValue() const
Get the text value of this value element.
attribute_iterator & operator=(const attribute_iterator &src)
Copy assignment takes an attribute_iterator that can be const, but that still allows writing to the A...
Definition: Xml.h:666
Array_< Element > getAllElements(const String &tag="")
Return an array containing Element handles referencing all the immediate child elements contained in ...
Definition: Xml.h:1354
attribute_iterator(Attribute &attr)
Construct this iterator to point to the same attribute as does the supplied Attribute handle (or attr...
Definition: Xml.h:657
This Array_ helper class is the base class for ArrayView_ which is the base class for Array_; here we...
Definition: Array.h:51
element_iterator(const element_iterator &src)
Copy constructor takes an element_iterator that can be const, but that still allows writing to the El...
Definition: Xml.h:977
SimTK::String is a plug-compatible std::string replacement (plus some additional functionality) inten...
Definition: String.h:62
This is a bidirectional iterator suitable for moving forward or backward within a list of Nodes...
Definition: Xml.h:904
node_iterator(Node &node, NodeType allowed=AnyNodes)
Definition: Xml.h:910
Mandatory first inclusion for any Simbody source or header file.
Xml::Element toXmlElement(const ArrayViewConst_< T, X > &thing, const std::string &name="")
Partial specialization for XML serialization of ArrayViewConst_ objects.
Definition: Xml.h:1720
Element node type and only-Elements filter.
Definition: Xml.h:74
Node * operator->() const
Definition: Xml.h:933
Unknown(Element &element, const String &contents)
Create a new Unknown node and append it to the list of nodes that are children of the given Element...
Definition: Xml.h:1558
Obtain human-readable and XML-usable names for arbitrarily-complicated C++ types. ...
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:858
T getRequiredElementValueAs(const String &tag) const
Convert the text value of a required child value element to the type of the template argument T...
Definition: Xml.h:1203
Abstract handle for holding any kind of node in an XML tree.
Definition: Xml.h:742
bool operator==(const element_iterator &other) const
Definition: Xml.h:992
Attribute * operator->() const
Return a writable pointer to the Attribute referenced by this iterator; the pointer will never be nul...
Definition: Xml.h:694
String getOptionalAttributeValue(const String &name, const String &def="") const
Get the value of an attribute as a string if the attribute is present in this element, otherwise return a supplied default value.
Definition: Xml.h:1267
Filter out meaningless nodes.
Definition: Xml.h:79
Node & operator=(const Node &src)
Copy assignment is shallow; the handle is first cleared and then will refer to the same node as the s...
Definition: Xml.h:761
T getOptionalElementValueAs(const String &tag, const T &def) const
Convert the text value of an optional child value element, if present, to the type of the template ar...
Definition: Xml.h:1219
This is a bidirectional iterator suitable for moving forward or backward within a list of Element nod...
Definition: Xml.h:964
~attribute_iterator()
An iterator destructor never deletes the object to which it refers.
Definition: Xml.h:663
attribute_iterator(const attribute_iterator &src)
Copy constructor takes an attribute_iterator that can be const, but that still allows writing to the ...
Definition: Xml.h:660
Node & operator*()
Definition: Xml.h:928
Elements can have attributes, which are name="value" pairs that appear within the element start tag i...
Definition: Xml.h:547
Filter out meaningful nodes.
Definition: Xml.h:80
bool operator!=(const Attribute &attr) const
Definition: Xml.h:607
void insertNodeBefore(const node_iterator &pos, Node node)
Insert a node into the list of this Element's children, just before the node pointed to by the suppli...
void writeToString(String &out) const
Serialize this attribute to the given String.
bool operator!=(const element_iterator &other) const
Definition: Xml.h:994
const String & getRequiredElementValue(const String &tag) const
Get the text value of a child value element that must be present in this element. ...
Definition: Xml.h:1183
T getOptionalAttributeValueAs(const String &name, const T &def) const
Convert the value of an optional attribute, if present, from a string to the type of the template arg...
Definition: Xml.h:1283
This class provides a minimalist capability for reading and writing XML documents, as files or strings.
Definition: Xml.h:307
T getRequiredAttributeValueAs(const String &name) const
Convert the text value of a required attribute to the type of the template argument T...
Definition: Xml.h:1257