XML::LibXML provides an lightwight interface to
One also has to remember, that XML::LibXML is an
interface to libxml2 nodes which actually reside on
the C-Level of XML::LibXML. This means each node is a
reference to a structure different than a perl hash or
array. The only way to access these structure's values
is through the DOM interface provided by
XML::LibXML. This also means, that one
The DOM interface of XML::LibXML does not intend to implement a full DOM interface as it is done by XML::GDOME and used for full featured application. More it offers an simple way to build or modify documents that are created by XML::LibXML's parser.
Another target of the XML::LibXML interface is to make the interfaces of libxml2 available to the perl community. This includes also some workarounds to some features where libxml2 assumes more control over the C-Level that most perl users don't have.
One of the most important parts of the XML::LibXML DOM interface is, that the interfaces try do follow the DOM Level 3 specification rather strict. This means the interface functions are names as the DOM specification says and not what widespread Java interfaces claim to be standard. Although there are several functions that have only a singular interface that is conform to the DOM spec XML::LibXML provides an additional Java style alias interface.
Also there are some function interfaces left over from
early stages of XML::LibXML for compatibility
reasons. These interfaces are for compatibility
reasons
More recent versions of perl (e.g. 5.6.1 or higher) support special flags to disinguish between UTF8 and so called binary data. XML::LibXML provides for these versions functionality to make efficient use of these flags: If a document has set an encoding other than UTF8 all strings that are not already in UTF8 are implicitly encoded from the document encoding to UTF8. On output these strings are commonly returned as UTF8 unless a user does request explicitly the original (aka. document) encoding.
Older version of perl (such as 5.00503 or less) do not support these flags. If XML::LibXML is build for these versions, all strings have to get encoded to UTF8 manualy before they are passed to any DOM functions.
XML::LibXML's DOM implementation follows the DOM implementation of libxml2. This is important to know if namespaces are used. Namespaces cannot be declared on an document node. This is basicly because XPath doesn't know about document nodes. Therefore namespaces have to be declared on element nodes. This can happen explicitly by using XML::LibXML:Element's setNamespace() function or more or less implicitly by using XML::LibXML::Document's createElementNS() or createAttributeNS() function. If the a namespace is not declared on the documentElement, the namespace will be localy declared for the newly created node. In case of Attributes this may look a bit confusing, since these nodes cannot have namespace declarations itself. In this case the namespace in internally applied to the attribute and later declared on the node the attribute is appended to.
The following example may explain this a bit:
This piece of code will result the following document:
Note that the namespace is declared on the document element while the setAttributeNodeNS() call.
Here it is important to repeat the specification:
While working with namespaces you should use the
namespace aware functions instead of the simplified
versions. For example you should
XML::LibXML provides an interface to libxml2 direct SAX interface. Through this interface it is possible to generate SAX events directly while parsing a document. While using the SAX parser XML::LibXML will not create a DOM Document tree.
Such an interface is useful if very large XML documents have to be processed and no DOM functions are required. By using this interface it is possible to read data stored within a XML document directly into the application datastructures without loading the document into memory.
The SAX interface of XML::LibXML is based on the famous XML::SAX interface. It uses the generic interface as provided by XML::SAX::Base.
Additionaly to the generic functions, that are only
able to process entire documents, XML::LibXML::SAX
provides
The Document Class is in most cases the result of a parsing process. But sometimes it is necessary to create a Document from scratch. The DOM Document Class provides functions that are conform to the DOM Core naming style.
It inherits all functions from XML::LibXML::Node as specified in the DOM specification. This enables to access the nodes beside the root element on document level - a DTD for example. The support for these nodes is limited at the moment.
While generaly nodes are bound to a document in the DOM concept it is suggested that one should always create a node not bound to any document. There is no need of really including the node to the document, but once the node is bound to a document, it is quite safe that all strings have the correct encoding. If an unbound textnode with an iso encoded string is created (e.g. with $CLASS->new()), the toString function may not return the expected result.
All this seems like a limitation as long UTF8 encoding
is ashured. If iso encoded strings come into play it
is much safer to use the node creation functions of
alias for createDocument()
The constructor for the document class. As
Parameter it takes the version string and
(optionally) the ecoding string. Simply calling
Both parameter are optional. The default value for
The call of
Alternatively one can call this constructor directly from the XML::LibXML class level, to avoid some typing. This will not cause any effect to the class instance, which is alway XML::LibXML::Document.
returns the encoding string of the document.
Optionally this function can be accessed by
From time to time it is useful to change the effective encoding of a document. This method provides the interface to manipulate the encoding of a document.
Note that this function has to be used very careful, since you can't simply convert one encoding in any other, since some (or even all) characters may not exist in the new encoding. XML::LibXML will not test if the operation is allowed or possible for the given document. The only switching ashured to work is to UTF8.
returns the version string of the document
This function returns the Numerical value of a
documents XML declarations standalone attribute.
It returns
Through this method it is possible to alter the
value of a documents standalone attribute. Set it
to
libxml2 allows to read documents directly from
gziped files. In this case the compression
variable is set to the compression level of that
file (0-8). If XML::LibXML parsed a different
source or the file wasn't compressed, the returned
value will be
If one intends to write the document directly to a
file, it is possible to set the compression level
for a given document. This level can be in the
range from 0 to 8. If XML::LibXML should not try
to compress use
Note that this feature will
The optional
If $format is 0, than the document is dumped as it was originally parsed
If $format is 1, libxml2 will add ignoreable whitespaces, so the nodes content is easier to read. Existing text nodes will not be altered
If $format is 2 (or higher), libxml2 will act as $format == 1 but it add a leading and a trailing linebreak to each text node.
libxml2 uses a hardcoded indentation of 2 space characters per indentation level. This value can not be altered on runtime.
This function is similar to toString(), but it writes the document directly into a filesystem. This function is very usefull, if one needs to store large documents.
The format parameter has the same behaviour as in toString().
This function is similar to toString(), but it writes the document directly to a filehandler or a stream.
The format parameter has the same behaviour as in toString().
Returns either TRUE or FALSE depending on the DOM Tree is a valid Document or not.
You may also pass in a XML::LibXML::Dtd object, to validate against an external DTD:
This is an exception throwing equivalent of is_valid. If the document is not valid it will throw an exception containing the error. This allows you much better error reporting than simply is_valid or not.
Again, you may pass in a DTD object
Returns the root element of the Document. A document can have just one root element to contain the documents data.
Optionaly one can use
This function enables you to set the root element for a document. The function supports the import of a node from a different document tree.
This function creates a new Element Node bound to the DOM with the name $nodename.
This function creates a new Element Node bound to the DOM with the name $nodename and placed in the given namespace.
As an equivalent of
As an equivalent of
Creates a new Attribute node.
This function creates a DocumentFragment.
Creates an Attribute bound to a namespace.
Similar to createTextNode and createComment, this function creates a CDataSection bound to the current DOM.
create a processing instruction node.
Since this method is quite long one may use its
short form
If a docuemnt has a DTD specified, one can create entity refereferences by using this function. If one wants to add a entity reference to the document, this reference has to be created by this function.
An entity reference is unique to a document and cannot passed to other documents as other nodes can be passed.
If a node is not part of a document, it can be imported to another document. As specified in DOM Level 2 Specification the Node will not be altered or removed from its original document ($node->cloneNode(1) will get called implicitly).
If a node is not part of a document, it can be imported to another document. As specified in DOM Level 3 Specification the Node will not be altered but it will removed from its original document.
After a document adopted a node, the node, its attributes and all its descendants belong to the new document. Because the node does not belong to the old document, it will be unlinked from its old location first.
If a document has an external subset defined it will be returned by this function.
If a document has an internal subset defined it will be returned by this function.
This method sets a DTD node as an external subset of the given document.
This method sets a DTD node as an internal subset of the given document.
If a document has an external subset defined it can be removed from the document by using this function. The removed dtd node will be returned.
If a document has an internal subset defined it can be removed from the document by using this function. The removed dtd node will be returned.
LibXML::Node defines functions that are common to all Node Types. A LibXML::Node should never be created standalone, but as an instance of a high level class such as LibXML::Element or LibXML::Text. The class itself should provide only common functionality. In XML::LibXML each node is part either of a document or a document-fragment. Because of this there is no node without a parent. This may causes confusion with "unbound" nodes.
Returns the node's name. This Function is aware about namesaces and returns the full name of the current node (prefix:localname)
In very limited situation it is usefull to change a nodes name. In the DOM specification this should throw an error. This Function is aware about namespaces.
returns TRUE (1) if the given nodes refer to the same nodestructure, otherwise FALSE (0) is returned.
depraced version of isSameNode().
If the node has any content (such as stored in a text node) it can get requested through this function.
this function returns the content of all text nodes in the descendants of the given node as spacified in DOM.
Retrun the node's type. The possible types are
described in the libxml2
Unbinds the Node from its siblings and Parent, but not from the Document it belongs to. If the node is not inserted into the DOM afterwards it will be lost after the programm terminated. From a low level view, the unbound node is stripped from the context it is and inserted into a (hidden) document-fragment.
This will unbind the Child Node from its parent $node. The function returns the unbound node. If oldNode is not a child of the given Node the function will fail.
Replaces the $oldNode with the $newNode. The $oldNode will be unbound from the Node. This function differs from the DOM L2 specification, in the case, if the new node is not part of the document, the node will be imported first.
This function is very similar to replaceChild(), but it replaces the node itself rather than a childnode. This is useful if a node found by any XPath function, should be replaced.
The function will add the $childnode to the end of $node's children. The function should fail, if the new childnode is allready a child of $node. This function differs from the DOM L2 specification, in the case, if the new node is not part of the document, the node will be imported first.
addSibling() allows to add an additional node to the end of a nodelist, defined by the given node.
This function returns all attributes assigned to the given node. if this function is called in scalar context, it will return a XML::LibXML::NodeList.
Returns simply the Parent Node of the current node.
Returns the next sibling if any .
Analogous to
If the current node has Childnodes this function returns TRUE (1), otherwise it returns FALSE (0, not undef).
If a node has childnodes this function will return the first node in the childlist.
If the $node has childnodes this function returns the last child node.
Through this function it is allways possible to access the document the current node is bound to.
This function returns the node the current node is associated with. In the very most cases this will be a document node or a document fragment node.
This function binds a node to another DOM. This method unbinds the node first, if it is allready bound to another document.
This function is the oposite calling of XML::LibXML::Document's adoptNode() function. Because of this it has the same limitations with Entity References as adoptNode().
The method inserts $newNode before $refNode. If $refNode is undefined, the newNode will be set as the new first child of the parent node. This function differs from the DOM L2 specification, in the case, if the new node is not part of the document, the node will be imported first.
The method inserts $newNode after $refNode. If $refNode is undefined, the newNode will be set as the new last child of the parent node.
That is, it returns the literal value of the results. This enables you to ensure that you get a string back from your search, allowing certain shortcuts. This could be used as the equivalent of XSLT's <xsl:value-of select="some_xpath"/>.
This is the equivalent to XML::LibXML::Document::toString for a single node. This means a node and all its childnodes will be dumped into the result string.
Additionally to the $format flag of XML::LibXML::Document, this version accepts the optional $docencoding flag. If this flag is set this function returns the string in its original encoding (the encoding of the document) rather than UTF8.
Returns the local name of a tag. This is the part behind the colon.
Returns the prefix of a tag. This is the part before the colon.
returns the URI of the current namespace.
returns 1 (TRUE) if the current node has any attributes set, otherwise 0 (FALSE) is returned.
Returns all attributes of a given node.
If this function is called in array context the attribute nodes are returned as an array. In scalar context the function will return a XML::LibXML::NamedNodeMap object.
Find a namespace URI by its prefix starting at the current node.
Find a namespace prefix by its URI starting at the current node.
This function returns a new iterator object based with the current element as first element. This iterator can be used for linear tree walking.
The example will print all node names in the current subtree.
Check the XML::LibXML::Iterator man page for more details.
This function normalizes adjacent textnodes. This function is not as strict as libxml2's xmlTextMerge() function, since it will not free a node that is still refered by the perl layer.
If a node has any namespaces defined, this function will return these namespaces. Note, that this will not return all namespaces that are in scope, but only the ones declares explicitly for that node.
Although getNamespaces is available for all nodes, it makes only sense if used with element nodes.
This function is not specified for any DOM level: It removes all childnodes from a node in a single step. Other than the libxml2 function itself (xmlFreeNodeList), this function will not imediatly remove the nodes from the memory. This safes one from getting memory violations, if there are nodes still refered from the Perl level.
This function creates a new node unbound to any DOM.
This method sets or replaces the node's attribute $aname to the value $avalue
Namespaceversion of setAttribute.
If $node has an attribute with the name $aname, the value of this attribute will get returned.
Namespaceversion of getAttribute.
Returns the attribute as a node if the attribute exists. If the Attribute does not exists undef will be returned.
Namespaceversion of getAttributeNode.
The method removes the attribute $aname from the node's attribute list, if the attribute can be found.
Namespace version of removeAttribute
This funcion tests if the named attribute is set for the node. If the attribute is specified, TRUE (1) will be returned, otherwise the returnvalue is FALSE (0).
namespace version of hasAttribute
The function gives direct access to all childnodes of the current node with the same tagname. It makes things a lot easier if you need to handle big datasets.
If this function is called in SCALAR context, it returns the number of Elements found.
Namespace version of getChildrenByTagName.
If this function is called in SCALAR context, it returns the number of Elements found.
This function is part of the spec it fetches all descendants of a node with a given tagname. If one is as confused with tagname as I was, tagname is a qualified tagname which is in case of namespace useage prefix and local name
In SCALAR context this function returns a XML::LibXML::NodeList object.
Namespace version of getElementsByTagName as found in the DOM spec.
In SCALAR context this function returns a XML::LibXML::NodeList object.
This function is not found in the DOM specification. It is a mix of getElementsByTagName and getElementsByTagNameNS. It will fetch all tags matching the given local-name. This alows one to select tags with the same local name across namespace borders.
In SCALAR context this function returns a XML::LibXML::NodeList object.
Sometimes it is nessecary to append a string coded
XML Tree to a
node.
This form is more explicit and makes it easier to control the flow of a script.
alias for appendTextNode().
This wrapper function lets you add a string directly to an element node.
Somewhat similar with appendTextNode: It lets you set an Element, that contains only a text node directly by specifying the name and the text content.
setNamespace() allows one to apply a namespace to an element. The function takes three parameters: 1. the namespace URI, which is required and the two optional values prefix, which is the namespace prefix, as it should be used in child elements or attributes as well as the additionally activate parameter.
The activate parameter is most usefull: If this parameter is set to FALSE (0), the namespace is simply added to the namespacelist of the node, while the element's namespace itself is not altered. Nevertheless activate is set to TRUE (1) on default. In this case the namespace automaticly is used as the nodes effective namespace. This means the namespace prefix is added to the node name and if there was a namespace already active for the node, this will be replaced (but not removed from the global namespace list)
The following example may clarify this:
results
while
results only
By using $activate == 0 it is possible to apply multiple namepace declarations to a single element.
Alternativly you can call setAttribute() simply to declare a new namespace for a node, without activating it:
has the same result as
Different to the DOM specification XML::LibXML implements the text node as the base class of all character data node. Therefor there exists no CharacterData class. This allow one to use all methods that are available for textnodes as well for Comments or CDATA-sections.
The constuctor of the class. It creates an unbound text node.
Although there exists the nodeValue attribute in the Node class, the DOM specification defines data as a separate attribute. XML::LibXML implements these two attributes not as different attributes, but as aliases, such as libxml2 does. Therefore
and
will have the same result and are not different entities.
This function sets or replaces text content to a node. The node has to be of the type "text", "cdata" or "comment".
Extracts a range of data from the node. (DOM Spec) This function takes the two parameters $offset and $length and returns the substring if available.
If the node contains no data or $offset referes to
an nonexisting string index, this function will
return
Appends a string to the end of the existing data. If the current text node contains no data, this function has the same effect as setData.
Inserts the parameter $string at the given $offset of the existing data of the node. This operation will not remove existing data, but change the order of the existing data.
The $offset has to be a positive value. If $offset is out of range, insertData will have the same behaviour as appendData.
This method removes a chunk from the existing node data at the given offset. The $length parameter tells, how many characters should be removed from the string.
This method removes a chunk from the existing node data. Since the DOM spec is quite unhandy if you already know which string to remove from a text node, this method allows more perlish code :)
The functions takes two parameters:
The DOM style version to replace node data.
The more programmer friendly version of replaceData() :)
Instead of giving offsets and length one can
specify the exact string (
This method replaces the node's data by a simple regular expression. Optional, this function allows to pass some flags that will be added as flag to the replace statement.
This function can make things easier to read for simple replacements. For more complex variants it is recommented to use the code snippet above.
This class provides all functions of
The constructor is the only provided function for
this package. It is required, because
This class provides all functions of
The constructor is the only provided function for
this package. It is required, because
This is the interface to handle Attributes like ordinary nodes. The naming of the class relies on the W3C DOM documentation.
Class constructor. If you need to work with iso
encoded strings, you should
Returns the value stored for the attribute. If undef is returned, the attribute has no value, which is different of being not specified.
Alias for
This is needed to set a new attributevalue. If iso encoded strings are passed as parameter, the node has to be bound to a document, otherwise the encoding might be wrong done.
returns the node the attribute belongs to. If the
attribute is not bound to a node, undef will be
returned. Overwriting the underlaying
implementation, the
This function activates a namespace for the given attribute. If the attribute was not previously declared in the context of the attribute this function will be silently ignored. In this case you may wish to call setNamespace() on the ownerElement.
This class is a helper class as described in the DOM Level 2 Specification. It is implamented as a node without name. All adding, inserting or replacing functions are aware about document fragments now.
As well
Namespace nodes are returned by both $element->findnodes('namespace::foo') or by $node->getNamespaces().
The namespace node API is not part of any current DOM
API, and so it is quite minimal. It should be noted
that namespace nodes are
Creates a new Namespace node. Note that this is not a 'node' as an attribute or an element node. Therefore you can't do call all XML::LibXML::Node Functions. All functions available for this node are listed below.
optionally you can pass the prefix to the namespace constructor. If this second parameter is ommited you will create a so called default namespace. Note, the newly created namespace is not bound to any docuement or node, therefore you should not expect it to be available in an existing document.
Returns "xmlns:prefix", where prefix is the prefix for this namespace.
Alias for getName()
Returns the prefix bound to this namespace declaration.
Alias for prefix()
Returns the URI of the namespace.
Alias for getData()
Alias for getData()
Alias for getData()
Returns the string "http://www.w3.org/2000/xmlns/"
Returns the string "xmlns"
This class holds a DTD. You may parse a DTD from either a string, or from an external SYSTEM identifier.
No support is available as yet for parsing from a filehandle.
XML::LibXML::Dtd is a sub-class of Node, so all the methods available to nodes (particularly toString()) are available to Dtd objects.
Parse a DTD from the system identifier, and return a DTD object that you can pass to $doc->is_valid() or $doc->validate().
The same as new() above, except you can parse a DTD from a string.