libSBML Perl API
libSBML 5.8.0 Perl API
|
Representation of a node in an XML document tree.
Beginning with version 3.0.0, libSBML implements an XML abstraction layer. This layer presents a uniform XML interface to calling programs regardless of which underlying XML parser libSBML has actually been configured to use. The basic data object in the XML abstraction is a node, represented by XMLNode.
An XMLNode can contain any number of children. Each child is another XMLNode, thereby forming a tree. The methods XMLNode::getNumChildren() and XMLNode::getChild() can be used to access the tree structure starting from a given node.
Each XMLNode is subclassed from XMLToken, and thus has the same methods available as XMLToken. These methods include XMLToken::getNamespaces(), XMLToken::getPrefix(), XMLToken::getName(), XMLToken::getURI(), and XMLToken::getAttributes().
LibSBML provides the following utility functions for converting an XML string (e.g., <annotation>...</annotation>
) to/from an XMLNode object.
XMLNode::toXMLString() returns a string representation of the XMLNode object.
XMLNode::convertXMLNodeToString() (static function) returns a string representation of the given XMLNode object.
The returned XMLNode object by XMLNode::convertStringToXMLNode() is a dummy root (container) XMLNode if the given XML string has two or more top-level elements (e.g., "<p>...</p><p>...</p>
"). In the dummy root node, each top-level element in the given XML string is contained as a child XMLNode. XMLToken::isEOF() can be used to identify if the returned XMLNode object is a dummy node or not. Here is an example:
Public Member Functions | |
int | addAttr (const std::string &name, const std::string &value, const std::string &namespaceURI="", const std::string &prefix="") |
Adds an attribute to the attribute set in this XMLToken optionally with a prefix and URI defining a namespace. More... | |
int | addAttr (const XMLTriple &triple, const std::string &value) |
Adds an attribute with the given XMLTriple/value pair to the attribute set in this XMLToken. More... | |
int | addChild (const XMLNode &node) |
Adds a copy of node as a child of this XMLNode. More... | |
int | addNamespace (const std::string &uri, const std::string &prefix="") |
Appends an XML namespace prefix and URI pair to this XMLToken. More... | |
int | append (const std::string &chars) |
Appends characters to this XML text content. More... | |
int | clearAttributes () |
Clears (deletes) all attributes in this XMLToken. More... | |
int | clearNamespaces () |
Clears (deletes) all XML namespace declarations in the XMLNamespaces of this XMLToken. More... | |
XMLNode * | clone () const |
Creates and returns a deep copy of this XMLNode. More... | |
bool | equals (const XMLNode &other, bool ignoreURI=false) const |
Compare this XMLNode against another XMLNode returning true if both nodes represent the same XML tree, or false otherwise. More... | |
const XMLAttributes & | getAttributes () const |
Returns the attributes of this element. More... | |
int | getAttributesLength () const |
Return the number of attributes in the attributes set. More... | |
int | getAttrIndex (const std::string &name, const std::string &uri="") const |
Return the index of an attribute with the given local name and namespace URI. More... | |
int | getAttrIndex (const XMLTriple &triple) const |
Return the index of an attribute with the given XMLTriple. More... | |
std::string | getAttrName (int index) const |
Return the local name of an attribute in the attributes set in this XMLToken (by position). More... | |
std::string | getAttrPrefix (int index) const |
Return the prefix of an attribute in the attribute set in this XMLToken (by position). More... | |
std::string | getAttrPrefixedName (int index) const |
Return the prefixed name of an attribute in the attribute set in this XMLToken (by position). More... | |
std::string | getAttrURI (int index) const |
Return the namespace URI of an attribute in the attribute set in this XMLToken (by position). More... | |
std::string | getAttrValue (int index) const |
Return the value of an attribute in the attribute set in this XMLToken (by position). More... | |
std::string | getAttrValue (const std::string name, const std::string uri="") const |
Return a value of an attribute with the given local name and namespace URI. More... | |
std::string | getAttrValue (const XMLTriple &triple) const |
Return a value of an attribute with the given XMLTriple. More... | |
const std::string & | getCharacters () const |
Returns the text of this element. More... | |
XMLNode & | getChild (unsigned int n) |
Returns the n th child of this XMLNode. More... | |
const XMLNode & | getChild (unsigned int n) const |
Returns the n th child of this XMLNode. More... | |
XMLNode & | getChild (const std::string &name) |
Returns the first child of this XMLNode with the corresponding name. More... | |
const XMLNode & | getChild (const std::string &name) const |
Returns the first child of this XMLNode with the corresponding name. More... | |
unsigned int | getColumn () const |
Returns the column at which this XMLToken occurred in the input document or data stream. More... | |
int | getIndex (const std::string &name) const |
Return the index of the first child of this XMLNode with the given name. More... | |
unsigned int | getLine () const |
Returns the line at which this XMLToken occurred in the input document or data stream. More... | |
const std::string & | getName () const |
Returns the (unqualified) name of this XML element. More... | |
int | getNamespaceIndex (const std::string &uri) const |
Look up the index of an XML namespace declaration by URI. More... | |
int | getNamespaceIndexByPrefix (const std::string &prefix) const |
Look up the index of an XML namespace declaration by prefix. More... | |
std::string | getNamespacePrefix (int index) const |
Look up the prefix of an XML namespace declaration by position. More... | |
std::string | getNamespacePrefix (const std::string &uri) const |
Look up the prefix of an XML namespace declaration by its URI. More... | |
const XMLNamespaces & | getNamespaces () const |
Returns the XML namespace declarations for this XML element. More... | |
int | getNamespacesLength () const |
Returns the number of XML namespaces stored in the XMLNamespaces of this XMLToken. More... | |
std::string | getNamespaceURI (int index) const |
Look up the URI of an XML namespace declaration by its position. More... | |
std::string | getNamespaceURI (const std::string &prefix="") const |
Look up the URI of an XML namespace declaration by its prefix. More... | |
unsigned int | getNumChildren () const |
Returns the number of children for this XMLNode. More... | |
const std::string & | getPrefix () const |
Returns the namespace prefix of this XML element. More... | |
const std::string & | getURI () const |
Returns the namespace URI of this XML element. More... | |
bool | hasAttr (int index) const |
Predicate returning true or false depending on whether an attribute with the given index exists in the attribute set in this XMLToken. More... | |
bool | hasAttr (const std::string name, const std::string uri="") const |
Predicate returning true or false depending on whether an attribute with the given local name and namespace URI exists in the attribute set in this XMLToken. More... | |
bool | hasAttr (const XMLTriple &triple) const |
Predicate returning true or false depending on whether an attribute with the given XML triple exists in the attribute set in this XMLToken. More... | |
bool | hasChild (const std::string &name) const |
Return a boolean indicating whether this XMLNode has a child with the given name. More... | |
bool | hasNamespaceNS (const std::string &uri, const std::string &prefix) const |
Predicate returning true or false depending on whether an XML Namespace with the given uri/prefix pair is contained in the XMLNamespaces ofthis XMLToken. More... | |
bool | hasNamespacePrefix (const std::string &prefix) const |
Predicate returning true or false depending on whether an XML Namespace with the given prefix is contained in the XMLNamespaces of this XMLToken. More... | |
bool | hasNamespaceURI (const std::string &uri) const |
Predicate returning true or false depending on whether an XML Namespace with the given URI is contained in the XMLNamespaces of this XMLToken. More... | |
XMLNode & | insertChild (unsigned int n, const XMLNode &node) |
Inserts a copy of the given node as the n th child of this XMLNode. More... | |
bool | isAttributesEmpty () const |
Predicate returning true or false depending on whether the attribute set in this XMLToken set is empty. More... | |
bool | isElement () const |
Predicate returning true or false depending on whether this XMLToken is an XML element. More... | |
bool | isEnd () const |
Predicate returning true or false depending on whether this XMLToken is an XML end element. More... | |
bool | isEndFor (const XMLToken &element) const |
Predicate returning true or false depending on whether this XMLToken is an XML end element for the given start element. More... | |
bool | isEOF () const |
Predicate returning true or false depending on whether this XMLToken is an end of file marker. More... | |
bool | isNamespacesEmpty () const |
Predicate returning true or false depending on whether the XMLNamespaces of this XMLToken is empty. More... | |
bool | isStart () const |
Predicate returning true or false depending on whether this XMLToken is an XML start element. More... | |
bool | isText () const |
Predicate returning true or false depending on whether this XMLToken is an XML text element. More... | |
XMLNode & | operator= (const XMLNode &rhs) |
Assignment operator for XMLNode. More... | |
int | removeAttr (int n) |
Removes an attribute with the given index from the attribute set in this XMLToken. More... | |
int | removeAttr (const std::string &name, const std::string &uri="") |
Removes an attribute with the given local name and namespace URI from the attribute set in this XMLToken. More... | |
int | removeAttr (const XMLTriple &triple) |
Removes an attribute with the given XMLTriple from the attribute set in this XMLToken. More... | |
XMLNode * | removeChild (unsigned int n) |
Removes the n th child of this XMLNode and returns the removed node. More... | |
int | removeChildren () |
Removes all children from this node. More... | |
int | removeNamespace (int index) |
Removes an XML Namespace stored in the given position of the XMLNamespaces of this XMLToken. More... | |
int | removeNamespace (const std::string &prefix) |
Removes an XML Namespace with the given prefix. More... | |
int | setAttributes (const XMLAttributes &attributes) |
Sets an XMLAttributes to this XMLToken. More... | |
int | setEnd () |
Declares this XML start element is also an end element. More... | |
int | setEOF () |
Declares this XMLToken is an end-of-file (input) marker. More... | |
int | setNamespaces (const XMLNamespaces &namespaces) |
Sets an XMLnamespaces to this XML element. More... | |
int | setTriple (const XMLTriple &triple) |
Sets the XMLTripe (name, uri and prefix) of this XML element. More... | |
std::string | toString () |
Prints a string representation of the underlying token stream, for debugging purposes. More... | |
std::string | toXMLString () const |
Returns a string representation of this XMLNode. More... | |
int | unsetEnd () |
Declares this XML start/end element is no longer an end element. More... | |
XMLNode () | |
Creates a new empty XMLNode with no children. More... | |
XMLNode (const XMLToken &token) | |
Creates a new XMLNode by copying token. More... | |
XMLNode (const XMLTriple &triple, const XMLAttributes &attributes, const XMLNamespaces &namespaces, const unsigned int line=0, const unsigned int column=0) | |
Creates a new start element XMLNode with the given set of attributes and namespace declarations. More... | |
XMLNode (const XMLTriple &triple, const XMLAttributes &attributes, const unsigned int line=0, const unsigned int column=0) | |
Creates a start element XMLNode with the given set of attributes. More... | |
XMLNode (const XMLTriple &triple, const unsigned int line=0, const unsigned int column=0) | |
Creates an end element XMLNode. More... | |
XMLNode (const std::string &chars, const unsigned int line=0, const unsigned int column=0) | |
Creates a text XMLNode. More... | |
XMLNode (const XMLNode &orig) | |
Copy constructor; creates a copy of this XMLNode. More... | |
virtual | ~XMLNode () |
Destroys this XMLNode. More... | |
Static Public Member Functions | |
static XMLNode * | convertStringToXMLNode (const std::string &xmlstr, const XMLNamespaces *xmlns=NULL) |
Returns an XMLNode which is derived from a string containing XML content. More... | |
static std::string | convertXMLNodeToString (const XMLNode *node) |
Returns a string representation of a given XMLNode. More... | |
XMLNode::XMLNode | ( | ) |
Creates a new empty XMLNode with no children.
XMLNode::XMLNode | ( | const XMLToken & | token | ) |
XMLNode::XMLNode | ( | const XMLTriple & | triple, |
const XMLAttributes & | attributes, | ||
const XMLNamespaces & | namespaces, | ||
const unsigned int | line = 0 , |
||
const unsigned int | column = 0 |
||
) |
Creates a new start element XMLNode with the given set of attributes and namespace declarations.
triple | XMLTriple. |
attributes | XMLAttributes, the attributes to set. |
namespaces | XMLNamespaces, the namespaces to set. |
line | an unsigned int, the line number (default = 0). |
column | an unsigned int, the column number (default = 0). |
XMLNode::XMLNode | ( | const XMLTriple & | triple, |
const XMLAttributes & | attributes, | ||
const unsigned int | line = 0 , |
||
const unsigned int | column = 0 |
||
) |
Creates a start element XMLNode with the given set of attributes.
triple | XMLTriple. |
attributes | XMLAttributes, the attributes to set. |
line | an unsigned int, the line number (default = 0). |
column | an unsigned int, the column number (default = 0). |
XMLNode::XMLNode | ( | const XMLTriple & | triple, |
const unsigned int | line = 0 , |
||
const unsigned int | column = 0 |
||
) |
Creates an end element XMLNode.
triple | XMLTriple. |
line | an unsigned int, the line number (default = 0). |
column | an unsigned int, the column number (default = 0). |
XMLNode::XMLNode | ( | const std::string & | chars, |
const unsigned int | line = 0 , |
||
const unsigned int | column = 0 |
||
) |
Creates a text XMLNode.
chars | a string, the text to be added to the XMLToken |
line | an unsigned int, the line number (default = 0). |
column | an unsigned int, the column number (default = 0). |
|
virtual |
Destroys this XMLNode.
XMLNode::XMLNode | ( | const XMLNode & | orig | ) |
Copy constructor; creates a copy of this XMLNode.
orig | the XMLNode instance to copy. |
XMLConstructorException | Thrown if the argument orig is NULL . |
|
inherited |
Adds an attribute to the attribute set in this XMLToken optionally with a prefix and URI defining a namespace.
Nothing will be done if this XMLToken is not a start element.
name | a string, the local name of the attribute. |
value | a string, the value of the attribute. |
namespaceURI | a string, the namespace URI of the attribute. |
prefix | a string, the prefix of the namespace |
|
inherited |
Adds an attribute with the given XMLTriple/value pair to the attribute set in this XMLToken.
Nothing will be done if this XMLToken is not a start element.
triple | an XMLTriple, the XML triple of the attribute. |
value | a string, the value of the attribute. |
int XMLNode::addChild | ( | const XMLNode & | node | ) |
Adds a copy of node
as a child of this XMLNode.
The given node
is added at the end of the list of children.
node | the XMLNode to be added as child. |
|
inherited |
Appends an XML namespace prefix and URI pair to this XMLToken.
If there is an XML namespace with the given prefix in this XMLToken, then the existing XML namespace will be overwritten by the new one.
Nothing will be done if this XMLToken is not a start element.
uri | a string, the uri for the namespace |
prefix | a string, the prefix for the namespace |
|
inherited |
Appends characters to this XML text content.
chars | string, characters to append |
|
inherited |
|
inherited |
Clears (deletes) all XML namespace declarations in the XMLNamespaces of this XMLToken.
Nothing will be done if this XMLToken is not a start element.
XMLNode * XMLNode::clone | ( | ) | const |
|
static |
Returns an XMLNode which is derived from a string containing XML content.
The XML namespace must be defined using argument xmlns
if the corresponding XML namespace attribute is not part of the string of the first argument.
xmlstr | string to be converted to a XML node. |
xmlns | XMLNamespaces the namespaces to set (default value is NULL ). |
<html>
, <body>
, <annotation>
, or <notes>
. In the dummy root node, each top-level element in the given XML string is contained as a child XMLNode. XMLToken::isEOF() can be used to identify if the returned XMLNode object is a dummy node.xmlstr
. If the conversion failed, this method returns NULL
.
|
static |
bool XMLNode::equals | ( | const XMLNode & | other, |
bool | ignoreURI = false |
||
) | const |
Compare this XMLNode against another XMLNode returning true if both nodes represent the same XML tree, or false otherwise.
other | another XMLNode to compare against. |
ignoreURI | whether to ignore the namespace URI when doing the comparison. |
other | another XMLNode to compare against |
|
inherited |
Returns the attributes of this element.
|
inherited |
Return the number of attributes in the attributes set.
|
inherited |
Return the index of an attribute with the given local name and namespace URI.
name | a string, the local name of the attribute. |
uri | a string, the namespace URI of the attribute. |
-1
if not present.
|
inherited |
|
inherited |
Return the local name of an attribute in the attributes set in this XMLToken (by position).
index | an integer, the position of the attribute whose local name is required. |
|
inherited |
Return the prefix of an attribute in the attribute set in this XMLToken (by position).
index | an integer, the position of the attribute whose prefix is required. |
|
inherited |
Return the prefixed name of an attribute in the attribute set in this XMLToken (by position).
index | an integer, the position of the attribute whose prefixed name is required. |
|
inherited |
Return the namespace URI of an attribute in the attribute set in this XMLToken (by position).
index | an integer, the position of the attribute whose namespace URI is required. |
|
inherited |
Return the value of an attribute in the attribute set in this XMLToken (by position).
index | an integer, the position of the attribute whose value is required. |
|
inherited |
Return a value of an attribute with the given local name and namespace URI.
name | a string, the local name of the attribute whose value is required. |
uri | a string, the namespace URI of the attribute. |
|
inherited |
Return a value of an attribute with the given XMLTriple.
triple | an XMLTriple, the XML triple of the attribute whose value is required. |
|
inherited |
Returns the text of this element.
XMLNode & XMLNode::getChild | ( | unsigned int | n | ) |
const XMLNode & XMLNode::getChild | ( | unsigned int | n | ) | const |
XMLNode & XMLNode::getChild | ( | const std::string & | name | ) |
const XMLNode & XMLNode::getChild | ( | const std::string & | name | ) | const |
|
inherited |
int XMLNode::getIndex | ( | const std::string & | name | ) | const |
|
inherited |
|
inherited |
Returns the (unqualified) name of this XML element.
|
inherited |
Look up the index of an XML namespace declaration by URI.
uri | a string, uri of the required namespace. |
-1
if not present.
|
inherited |
Look up the index of an XML namespace declaration by prefix.
prefix | a string, prefix of the required namespace. |
-1
if not present.
|
inherited |
Look up the prefix of an XML namespace declaration by position.
Callers should use getNamespacesLength() to find out how many namespaces are stored in the XMLNamespaces.
index | an integer, position of the required prefix. |
|
inherited |
Look up the prefix of an XML namespace declaration by its URI.
uri | a string, the URI of the prefix being sought |
uri
does not exist, an empty string will be returned.
|
inherited |
Returns the XML namespace declarations for this XML element.
|
inherited |
Returns the number of XML namespaces stored in the XMLNamespaces of this XMLToken.
|
inherited |
Look up the URI of an XML namespace declaration by its position.
index | an integer, position of the required URI. |
index
is out of range, an empty string will be returned.
|
inherited |
Look up the URI of an XML namespace declaration by its prefix.
prefix | a string, the prefix of the required URI |
prefix
does not exist, an empty string will be returned.unsigned int XMLNode::getNumChildren | ( | ) | const |
|
inherited |
Returns the namespace prefix of this XML element.
|
inherited |
Returns the namespace URI of this XML element.
|
inherited |
Predicate returning true
or false
depending on whether an attribute with the given index exists in the attribute set in this XMLToken.
index | an integer, the position of the attribute. |
true
if an attribute with the given index exists in the attribute set in this XMLToken, false
otherwise.
|
inherited |
Predicate returning true
or false
depending on whether an attribute with the given local name and namespace URI exists in the attribute set in this XMLToken.
name | a string, the local name of the attribute. |
uri | a string, the namespace URI of the attribute. |
true
if an attribute with the given local name and namespace URI exists in the attribute set in this XMLToken, false
otherwise.
|
inherited |
Predicate returning true
or false
depending on whether an attribute with the given XML triple exists in the attribute set in this XMLToken.
triple | an XMLTriple, the XML triple of the attribute |
true
if an attribute with the given XML triple exists in the attribute set in this XMLToken, false
otherwise. bool XMLNode::hasChild | ( | const std::string & | name | ) | const |
|
inherited |
Predicate returning true
or false
depending on whether an XML Namespace with the given uri/prefix pair is contained in the XMLNamespaces ofthis XMLToken.
uri | a string, the uri for the namespace |
prefix | a string, the prefix for the namespace |
true
if an XML Namespace with the given uri/prefix pair is contained in the XMLNamespaces of this XMLToken, false
otherwise.
|
inherited |
Predicate returning true
or false
depending on whether an XML Namespace with the given prefix is contained in the XMLNamespaces of this XMLToken.
prefix | a string, the prefix for the namespace |
true
if an XML Namespace with the given URI is contained in the XMLNamespaces of this XMLToken, false
otherwise.
|
inherited |
Predicate returning true
or false
depending on whether an XML Namespace with the given URI is contained in the XMLNamespaces of this XMLToken.
uri | a string, the uri for the namespace |
true
if an XML Namespace with the given URI is contained in the XMLNamespaces of this XMLToken, false
otherwise. Inserts a copy of the given node as the n
th child of this XMLNode.
If the given index n
is out of range for this XMLNode instance, the node
is added at the end of the list of children. Even in that situation, this method does not throw an error.
n | an integer, the index at which the given node is inserted |
node | an XMLNode to be inserted as n th child. |
node
|
inherited |
|
inherited |
|
inherited |
|
inherited |
|
inherited |
|
inherited |
Predicate returning true
or false
depending on whether the XMLNamespaces of this XMLToken is empty.
true
if the XMLNamespaces of this XMLToken is empty, false
otherwise.
|
inherited |
|
inherited |
Assignment operator for XMLNode.
rhs | The XMLNode object whose values are used as the basis of the assignment. |
XMLConstructorException | Thrown if the argument rhs is NULL . |
|
inherited |
Removes an attribute with the given index from the attribute set in this XMLToken.
Nothing will be done if this XMLToken is not a start element.
n | an integer the index of the resource to be deleted |
|
inherited |
Removes an attribute with the given local name and namespace URI from the attribute set in this XMLToken.
Nothing will be done if this XMLToken is not a start element.
name | a string, the local name of the attribute. |
uri | a string, the namespace URI of the attribute. |
|
inherited |
Removes an attribute with the given XMLTriple from the attribute set in this XMLToken.
Nothing will be done if this XMLToken is not a start element.
triple | an XMLTriple, the XML triple of the attribute. |
XMLNode * XMLNode::removeChild | ( | unsigned int | n | ) |
Removes the n
th child of this XMLNode and returns the removed node.
It is important to keep in mind that a given XMLNode may have more than one child. Calling this method erases all existing references to child nodes after the given position n
. If the index n
is greater than the number of child nodes in this XMLNode, this method takes no action (and returns NULL
).
n | an integer, the index of the node to be removed |
NULL
if n
is greater than the number of children in this nodeint XMLNode::removeChildren | ( | ) |
Removes all children from this node.
|
inherited |
Removes an XML Namespace stored in the given position of the XMLNamespaces of this XMLToken.
Nothing will be done if this XMLToken is not a start element.
index | an integer, position of the removed namespace. |
|
inherited |
Removes an XML Namespace with the given prefix.
Nothing will be done if this XMLToken is not a start element.
prefix | a string, prefix of the required namespace. |
|
inherited |
Sets an XMLAttributes to this XMLToken.
Nothing will be done if this XMLToken is not a start element.
attributes | XMLAttributes to be set to this XMLToken. |
|
inherited |
Declares this XML start element is also an end element.
|
inherited |
Declares this XMLToken is an end-of-file (input) marker.
|
inherited |
Sets an XMLnamespaces to this XML element.
Nothing will be done if this XMLToken is not a start element.
namespaces | XMLNamespaces to be set to this XMLToken. |
|
inherited |
Sets the XMLTripe (name, uri and prefix) of this XML element.
Nothing will be done if this XML element is a text node.
triple | XMLTriple to be added to this XML element. |
|
inherited |
Prints a string representation of the underlying token stream, for debugging purposes.
std::string XMLNode::toXMLString | ( | ) | const |
|
inherited |
Declares this XML start/end element is no longer an end element.