ARC SDK
|
Wrapper for LibXML library Tree interface. More...
#include <arc/XMLNode.h>
Public Member Functions | |
XMLNode (void) | |
Constructor of invalid node. More... | |
XMLNode (const XMLNode &node) | |
Copies existing instance. More... | |
XMLNode (const std::string &xml) | |
Creates XML document structure from textual representation of XML document. More... | |
XMLNode (const char *xml, int len=-1) | |
Creates XML document structure from textual representation of XML document. More... | |
XMLNode (long ptr_addr) | |
Copy constructor. Used by language bindings. More... | |
XMLNode (const NS &ns, const char *name) | |
Creates empty XML document structure with specified namespaces. More... | |
~XMLNode (void) | |
Destructor. More... | |
void | New (XMLNode &node) const |
Creates a copy of XML (sub)tree. More... | |
void | Exchange (XMLNode &node) |
Exchanges XML (sub)trees. More... | |
void | Move (XMLNode &node) |
Moves content of this XML (sub)tree to node. More... | |
void | Swap (XMLNode &node) |
Swaps XML (sub)trees to which this and node refer. More... | |
operator bool (void) const | |
Returns true if instance points to XML element - valid instance. More... | |
bool | operator! (void) const |
Returns true if instance does not point to XML element - invalid instance. More... | |
bool | operator== (const XMLNode &node) |
Returns true if 'node' represents same XML element. More... | |
bool | operator!= (const XMLNode &node) |
Returns false if 'node' represents same XML element. More... | |
bool | Same (const XMLNode &node) |
Returns true if 'node' represents same XML element - for bindings. More... | |
bool | operator== (bool val) |
This operator is needed to avoid ambiguity. More... | |
bool | operator!= (bool val) |
This operator is needed to avoid ambiguity. More... | |
bool | operator== (const std::string &str) |
This operator is needed to avoid ambiguity. More... | |
bool | operator!= (const std::string &str) |
This operator is needed to avoid ambiguity. More... | |
bool | operator== (const char *str) |
This operator is needed to avoid ambiguity. More... | |
bool | operator!= (const char *str) |
This operator is needed to avoid ambiguity. More... | |
XMLNode | Child (int n=0) |
Returns XMLNode instance representing n-th child of XML element. More... | |
XMLNode | operator[] (const char *name) const |
Returns XMLNode instance representing first child element with specified name. More... | |
XMLNode | operator[] (const std::string &name) const |
Returns XMLNode instance representing first child element with specified name. More... | |
XMLNode | operator[] (int n) const |
Returns XMLNode instance representing n-th node in sequence of siblings of same name. More... | |
void | operator++ (void) |
Convenience operator to switch to next element of same name. More... | |
void | operator-- (void) |
Convenience operator to switch to previous element of same name. More... | |
int | Size (void) const |
Returns number of children nodes. More... | |
XMLNode | Get (const std::string &name) const |
Same as operator[](). More... | |
std::string | Name (void) const |
Returns name of XML node. More... | |
std::string | Prefix (void) const |
Returns namespace prefix of XML node. More... | |
std::string | FullName (void) const |
Returns prefix:name of XML node. More... | |
std::string | Namespace (void) const |
Returns namespace URI of XML node. More... | |
void | Prefix (const std::string &prefix, int recursion=0) |
Assigns namespace prefix to XML node(s). More... | |
void | StripNamespace (int recursion=0) |
Removes namespace prefix from XML node(s). More... | |
void | Name (const char *name) |
Assigns new name to XML node. More... | |
void | Name (const std::string &name) |
Assigns new name to XML node. More... | |
void | GetXML (std::string &out_xml_str, bool user_friendly=false) const |
Fills argument with this instance XML subtree textual representation. More... | |
void | GetXML (std::string &out_xml_str, const std::string &encoding, bool user_friendly=false) const |
Get string representation of XML subtree. More... | |
void | GetDoc (std::string &out_xml_str, bool user_friendly=false) const |
Fills out_xml_str with whole XML document textual representation. More... | |
operator std::string (void) const | |
Returns textual content of node excluding content of children nodes. More... | |
XMLNode & | operator= (const char *content) |
Sets textual content of node. All existing children nodes are discarded. More... | |
XMLNode & | operator= (const std::string &content) |
Sets textual content of node. All existing children nodes are discarded. More... | |
void | Set (const std::string &content) |
Same as operator=. Used for bindings. More... | |
XMLNode & | operator= (const XMLNode &node) |
Make instance refer to another XML node. Ownership is not inherited. More... | |
XMLNode | Attribute (int n=0) |
Returns XMLNode instance reresenting n-th attribute of node. More... | |
XMLNode | Attribute (const char *name) |
Returns XMLNode instance representing first attribute of node with specified by name. More... | |
XMLNode | Attribute (const std::string &name) |
Returns XMLNode instance representing first attribute of node with specified by name. More... | |
XMLNode | NewAttribute (const char *name) |
Creates new attribute with specified name. More... | |
XMLNode | NewAttribute (const std::string &name) |
Creates new attribute with specified name. More... | |
int | AttributesSize (void) const |
Returns number of attributes of node. More... | |
void | Namespaces (const NS &namespaces, bool keep=false, int recursion=-1) |
Assigns namespaces of XML document at point specified by this instance. More... | |
NS | Namespaces (void) |
Returns namespaces known at this node. More... | |
std::string | NamespacePrefix (const char *urn) |
Returns prefix of specified namespace or empty string if no such namespace. More... | |
XMLNode | NewChild (const char *name, int n=-1, bool global_order=false) |
Creates new child XML element at specified position with specified name. More... | |
XMLNode | NewChild (const std::string &name, int n=-1, bool global_order=false) |
Same as NewChild(const char*,int,bool). More... | |
XMLNode | NewChild (const char *name, const NS &namespaces, int n=-1, bool global_order=false) |
Creates new child XML element at specified position with specified name and namespaces. More... | |
XMLNode | NewChild (const std::string &name, const NS &namespaces, int n=-1, bool global_order=false) |
Same as NewChild(const char*,const NS&,int,bool). More... | |
XMLNode | NewChild (const XMLNode &node, int n=-1, bool global_order=false) |
Link a copy of supplied XML node as child. More... | |
void | Replace (const XMLNode &node) |
Makes a copy of supplied XML node and makes this instance refer to it. More... | |
void | Destroy (void) |
Destroys underlying XML element. More... | |
XMLNodeList | Path (const std::string &path) |
Collects nodes corresponding to specified path. More... | |
XMLNodeList | XPathLookup (const std::string &xpathExpr, const NS &nsList) |
Uses XPath to look up XML tree. More... | |
XMLNode | GetRoot (void) |
Get the root node from any child node of the tree. More... | |
XMLNode | Parent (void) |
Get the parent node from any child node of the tree. More... | |
bool | SaveToFile (const std::string &file_name) const |
Save string representation of node to file. More... | |
bool | SaveToStream (std::ostream &out) const |
Save string representation of node to stream. More... | |
bool | ReadFromFile (const std::string &file_name) |
Read XML document from file and associate it with this node. More... | |
bool | ReadFromStream (std::istream &in) |
Read XML document from stream and associate it with this node. More... | |
bool | Validate (const std::string &schema_file, std::string &err_msg) |
XML schema validation against the schema file defined as argument. More... | |
bool | Validate (XMLNode schema_doc, std::string &err_msg) |
Protected Member Functions | |
XMLNode (xmlNodePtr node) | |
Protected constructor for inherited classes. More... | |
bool | Validate (xmlSchemaPtr schema, std::string &err_msg) |
Static Protected Member Functions | |
static void | LogError (void *ctx, const char *msg,...) |
Protected Attributes | |
xmlNodePtr | node_ |
bool | is_owner_ |
If true node is owned by this instance - hence released in destructor. More... | |
bool | is_temporary_ |
This variable is reserved for future use. More... | |
Friends | |
class | XMLNodeContainer |
bool | MatchXMLName (const XMLNode &node1, const XMLNode &node2) |
Returns true if underlying XML elements have same names. More... | |
bool | MatchXMLName (const XMLNode &node, const char *name) |
Returns true if 'name' matches name of 'node'. If name contains prefix it's checked too. More... | |
bool | MatchXMLName (const XMLNode &node, const std::string &name) |
Returns true if 'name' matches name of 'node'. If name contains prefix it's checked too. More... | |
bool | MatchXMLNamespace (const XMLNode &node1, const XMLNode &node2) |
Returns true if underlying XML elements belong to same namespaces. More... | |
bool | MatchXMLNamespace (const XMLNode &node, const char *uri) |
Returns true if 'namespace' matches 'node's namespace.. More... | |
bool | MatchXMLNamespace (const XMLNode &node, const std::string &uri) |
Returns true if 'namespace' matches 'node's namespace.. More... | |
Wrapper for LibXML library Tree interface.
This class wraps XML Node, Document and Property/Attribute structures. Each instance serves as pointer to actual LibXML element and provides convenient (for chosen purpose) methods for manipulating it. This class has no special ties to LibXML library and may be easily rewritten for any XML parser which provides interface similar to LibXML Tree. It implements only small subset of XML capabilities, which is probably enough for performing most of useful actions. This class also filters out (usually) useless textual nodes which are often used to make XML documents human-readable.
|
inlineprotected |
Protected constructor for inherited classes.
Creates instance and links to existing LibXML structure. Acquired structure is not owned by class instance. If there is need to completely pass control of LibXML document to then instance's is_owner_ variable has to be set to true.
|
inline |
Constructor of invalid node.
Created instance does not point to XML element. All methods are still allowed for such instance but produce no results.
|
inline |
Copies existing instance.
Underlying XML element is NOT copied. Ownership is NOT inherited. Strictly speaking there should be no const here - but that conflicts with C++.
Arc::XMLNode::XMLNode | ( | const std::string & | xml | ) |
Creates XML document structure from textual representation of XML document.
Created structure is pointed and owned by constructed instance.
Arc::XMLNode::XMLNode | ( | const char * | xml, |
int | len = -1 |
||
) |
Creates XML document structure from textual representation of XML document.
Created structure is pointed and owned by constructed instance.
Arc::XMLNode::XMLNode | ( | long | ptr_addr | ) |
Copy constructor. Used by language bindings.
Arc::XMLNode::XMLNode | ( | const NS & | ns, |
const char * | name | ||
) |
Creates empty XML document structure with specified namespaces.
Created XML contains only root element named 'name'. Created structure is pointed and owned by constructed instance.
Arc::XMLNode::~XMLNode | ( | void | ) |
Destructor.
Also destroys underlying XML document if owned by this instance
XMLNode Arc::XMLNode::Attribute | ( | int | n = 0 | ) |
Returns XMLNode instance reresenting n-th attribute of node.
XMLNode Arc::XMLNode::Attribute | ( | const char * | name | ) |
Returns XMLNode instance representing first attribute of node with specified by name.
|
inline |
Returns XMLNode instance representing first attribute of node with specified by name.
int Arc::XMLNode::AttributesSize | ( | void | ) | const |
Returns number of attributes of node.
XMLNode Arc::XMLNode::Child | ( | int | n = 0 | ) |
void Arc::XMLNode::Destroy | ( | void | ) |
Destroys underlying XML element.
XML element is unlinked from XML tree and destroyed. After this operation XMLNode instance becomes invalid
void Arc::XMLNode::Exchange | ( | XMLNode & | node | ) |
Exchanges XML (sub)trees.
The following combinations are possible:
The main reason for this method is to provide an effective way to insert one XML document inside another. One should take into account that if any of the exchanged nodes is top level it must be also the owner of the document. Otherwise this method will fail. If both nodes are top level owners and/or invalid nodes then this method is identical to Swap().
|
inline |
Returns prefix:name of XML node.
|
inline |
Same as operator[]().
void Arc::XMLNode::GetDoc | ( | std::string & | out_xml_str, |
bool | user_friendly = false |
||
) | const |
Fills out_xml_str with whole XML document textual representation.
XMLNode Arc::XMLNode::GetRoot | ( | void | ) |
Get the root node from any child node of the tree.
void Arc::XMLNode::GetXML | ( | std::string & | out_xml_str, |
bool | user_friendly = false |
||
) | const |
Fills argument with this instance XML subtree textual representation.
void Arc::XMLNode::GetXML | ( | std::string & | out_xml_str, |
const std::string & | encoding, | ||
bool | user_friendly = false |
||
) | const |
Get string representation of XML subtree.
Fills out_xml_str with this instance XML subtree textual representation if the XML subtree corresponds to the encoding format specified in the argument, e.g. utf-8.
|
staticprotected |
printf-like callback for libxml
void Arc::XMLNode::Move | ( | XMLNode & | node | ) |
Moves content of this XML (sub)tree to node.
This operation is similar to New() except that XML (sub)tree to referred by this is destroyed. This method is more effective than combination of New() and Destroy() because internally it is optimized not to copy data if not needed. The main purpose of this is to effectively extract part of XML document.
std::string Arc::XMLNode::Name | ( | void | ) | const |
Returns name of XML node.
void Arc::XMLNode::Name | ( | const char * | name | ) |
Assigns new name to XML node.
|
inline |
Assigns new name to XML node.
std::string Arc::XMLNode::Namespace | ( | void | ) | const |
Returns namespace URI of XML node.
std::string Arc::XMLNode::NamespacePrefix | ( | const char * | urn | ) |
Returns prefix of specified namespace or empty string if no such namespace.
void Arc::XMLNode::Namespaces | ( | const NS & | namespaces, |
bool | keep = false , |
||
int | recursion = -1 |
||
) |
Assigns namespaces of XML document at point specified by this instance.
If namespace already exists it gets new prefix. New namespaces are added. It is useful to apply this method to XML being processed in order to refer to it's elements by known prefix. If keep is set to false existing namespace definition residing at this instance and below are removed (default behavior). If recursion is set to positive number then depth of prefix replacement is limited by this number (0 limits it to this node only). For unlimited recursion use -1. If recursion is limited then value of keep is ignored and existing namespaces are always kept.
NS Arc::XMLNode::Namespaces | ( | void | ) |
Returns namespaces known at this node.
void Arc::XMLNode::New | ( | XMLNode & | node | ) | const |
Creates a copy of XML (sub)tree.
If object does not represent whole document - top level document is created. 'node' becomes a pointer owning new XML document.
XMLNode Arc::XMLNode::NewAttribute | ( | const char * | name | ) |
Creates new attribute with specified name.
|
inline |
Creates new attribute with specified name.
XMLNode Arc::XMLNode::NewChild | ( | const char * | name, |
int | n = -1 , |
||
bool | global_order = false |
||
) |
Creates new child XML element at specified position with specified name.
Default is to put it at end of list. If global_order is true position applies to whole set of children, otherwise only to children of same name. Returns created node.
|
inline |
Same as NewChild(const char*,int,bool).
XMLNode Arc::XMLNode::NewChild | ( | const char * | name, |
const NS & | namespaces, | ||
int | n = -1 , |
||
bool | global_order = false |
||
) |
Creates new child XML element at specified position with specified name and namespaces.
For more information look at NewChild(const char*,int,bool)
Link a copy of supplied XML node as child.
Returns instance referring to new child. XML element is a copy of supplied one but not owned by returned instance
|
inline |
Returns true if instance points to XML element - valid instance.
Arc::XMLNode::operator std::string | ( | void | ) | const |
Returns textual content of node excluding content of children nodes.
|
inline |
Returns true if instance does not point to XML element - invalid instance.
|
inline |
Returns false if 'node' represents same XML element.
|
inline |
This operator is needed to avoid ambiguity.
|
inline |
This operator is needed to avoid ambiguity.
|
inline |
This operator is needed to avoid ambiguity.
void Arc::XMLNode::operator++ | ( | void | ) |
Convenience operator to switch to next element of same name.
If there is no such node this object becomes invalid.
void Arc::XMLNode::operator-- | ( | void | ) |
Convenience operator to switch to previous element of same name.
If there is no such node this object becomes invalid.
XMLNode& Arc::XMLNode::operator= | ( | const char * | content | ) |
Sets textual content of node. All existing children nodes are discarded.
|
inline |
Sets textual content of node. All existing children nodes are discarded.
Make instance refer to another XML node. Ownership is not inherited.
Due to nature of XMLNode there should be no const here, but that does not fit into C++.
|
inline |
Returns true if 'node' represents same XML element.
|
inline |
This operator is needed to avoid ambiguity.
|
inline |
This operator is needed to avoid ambiguity.
|
inline |
This operator is needed to avoid ambiguity.
XMLNode Arc::XMLNode::operator[] | ( | const char * | name | ) | const |
Returns XMLNode instance representing first child element with specified name.
Name may be "namespace_prefix:name", "namespace_uri:name" or simply "name". In last case namespace is ignored. If such node does not exist invalid XMLNode instance is returned. This method should not be marked const because obtaining unrestricted XMLNode of child element allows modification of underlying XML tree. But in order to keep const in other places non-const-handling is passed to programmer. Otherwise C++ compiler goes nuts.
|
inline |
Returns XMLNode instance representing first child element with specified name.
Similar to operator[](const char *name) const.
XMLNode Arc::XMLNode::operator[] | ( | int | n | ) | const |
Returns XMLNode instance representing n-th node in sequence of siblings of same name.
Its main purpose is to be used to retrieve an element in an array of children of the same name like node["name"][5].
This method should not be marked const because obtaining unrestricted XMLNode of child element allows modification of underlying XML tree. But in order to keep const in other places non-const-handling is passed to programmer. Otherwise C++ compiler goes nuts.
XMLNode Arc::XMLNode::Parent | ( | void | ) |
Get the parent node from any child node of the tree.
XMLNodeList Arc::XMLNode::Path | ( | const std::string & | path | ) |
Collects nodes corresponding to specified path.
This is a convenience function to cover common use of XPath but without performance hit. Path is made of node_name[/node_name[...]] and is relative to current node. node_names are treated in same way as in operator[].
std::string Arc::XMLNode::Prefix | ( | void | ) | const |
Returns namespace prefix of XML node.
void Arc::XMLNode::Prefix | ( | const std::string & | prefix, |
int | recursion = 0 |
||
) |
Assigns namespace prefix to XML node(s).
The 'recursion' allows to assign prefixes recursively. Setting it to -1 allows for unlimited recursion. And 0 limits it to this node.
bool Arc::XMLNode::ReadFromFile | ( | const std::string & | file_name | ) |
Read XML document from file and associate it with this node.
bool Arc::XMLNode::ReadFromStream | ( | std::istream & | in | ) |
Read XML document from stream and associate it with this node.
void Arc::XMLNode::Replace | ( | const XMLNode & | node | ) |
Makes a copy of supplied XML node and makes this instance refer to it.
|
inline |
Returns true if 'node' represents same XML element - for bindings.
bool Arc::XMLNode::SaveToFile | ( | const std::string & | file_name | ) | const |
Save string representation of node to file.
bool Arc::XMLNode::SaveToStream | ( | std::ostream & | out | ) | const |
Save string representation of node to stream.
|
inline |
Same as operator=. Used for bindings.
int Arc::XMLNode::Size | ( | void | ) | const |
Returns number of children nodes.
void Arc::XMLNode::StripNamespace | ( | int | recursion = 0 | ) |
Removes namespace prefix from XML node(s).
void Arc::XMLNode::Swap | ( | XMLNode & | node | ) |
Swaps XML (sub)trees to which this and node refer.
For XML subtrees this method is not anyhow different then using the combination
But in case of either this or node owning XML document ownership is swapped too. And this is the main purpose of this method.
|
protected |
Convenience method for XML validation
bool Arc::XMLNode::Validate | ( | const std::string & | schema_file, |
std::string & | err_msg | ||
) |
XML schema validation against the schema file defined as argument.
bool Arc::XMLNode::Validate | ( | XMLNode | schema_doc, |
std::string & | err_msg | ||
) |
XML schema validation against the schema XML document defined as argument
XMLNodeList Arc::XMLNode::XPathLookup | ( | const std::string & | xpathExpr, |
const NS & | nsList | ||
) |
Uses XPath to look up XML tree.
Returns a list of XMLNode points. The xpathExpr should be like "//xx:child1/" which indicates the namespace and node that you would like to find. The nsList contains namespaces used by the xpathExpr. Query is run on whole XML document but only the elements belonging to this XML subtree are returned. Please note, that default namespaces - without prefix - are not fully supported. So xpathExpr without properly defined namespace prefixes will only work for XML documents without namespaces.
Returns true if underlying XML elements have same names.
|
friend |
Returns true if 'name' matches name of 'node'. If name contains prefix it's checked too.
|
friend |
Returns true if 'name' matches name of 'node'. If name contains prefix it's checked too.
Returns true if underlying XML elements belong to same namespaces.
|
friend |
Returns true if 'namespace' matches 'node's namespace..
|
friend |
Returns true if 'namespace' matches 'node's namespace..
|
protected |
If true node is owned by this instance - hence released in destructor.
Normally that may be true only for top level node of XML document.
|
protected |
This variable is reserved for future use.