Node

Synopsis

use LibXML::Node;
        my LibXML::Node $node;

# -- Property Methods -- #
        my Str $name = $node.nodeName;
        $node.nodeName = $newName;
        my Bool $same = $node.isSameNode( $other-node );
        my Bool $blank = $node.isBlank;
        my Str $key = $node.unique-key;
        my Str $content = $node.nodeValue;
        $content = $node.textContent;
        my UInt $type = $node.nodeType;
        my Str $uri = $node.getBaseURI();
        $node.setBaseURI($uri);
        my Str $path = $node.nodePath();
        my UInt $lineno = $node.line-number();

# -- Navigation Methods -- #
        my LibXML::Node $parent = $node.parentNode;
        my LibXML::Node $next = $node.nextSibling();
        $next = $node.nextNonBlankSibling();
        my LibXML::Node $prev = $node.previousSibling();
        $prev = $node.previousNonBlankSibling();
        my Bool $is-parent = $node.hasChildNodes();
        $child = $node.firstChild;
        $child = $node.lastChild;
        $top-level-node = $node.getOwner;
        my LibXML::Node @kids = $node.childNodes();
        @kids = $node.nonBlankChildNodes();

# -- DOM Manipulation Methods -- #
        $node.unbindNode();
        $node.doc = $doc; # -OR- $node.setOwnerDoc($doc);
        my LibXML::Node $child = $node.removeChild( $node );
        $oldNode = $node.replaceChild( $newNode, $oldNode );
        $childNode = $node.appendChild( $childNode );
        $node = $parent.addNewChild( $nsURI, $name );
        $node.replaceNode($newNode);
        $node.addSibling($newNode);
        $newnode = $node.cloneNode( :deep );
        $node.insertBefore( $newNode, $refNode );
        $node.insertAfter( $newNode, $refNode );
        $node.removeChildNodes();
        $node.ownerDocument = $doc;

# -- Searching Methods -- #
        #    * XPath *
        my LibXML::Node @found = $node.findnodes( $xpath-expr, :%ns );
        my LibXML::Node::Set $results = $node.find( $xpath-expr, :%ns );
        print $node.findvalue( $xpath-expr, :%ns );
        my Bool $found = $node.exists( $xpath-expr, :%ns );
        $found = $xpath-expression ~~ $node;
        my LibXML::Node $item = $node.first( $xpath-expr, :%ns );
        $item = $node.last( $xpath-expr, :%ns );
        #    * CSS selectors *
        $node.query-handler = CSS::Selector::To::XPath.new; # setup a query selector handler
        $item = $node.querySelector($css-selector); # first match
        $results = $node.querySelectorAll($css-selector); # all matches

# -- Serialization Methods -- #
        my Str $xml = $node.Str(:format);
        my Str $xml-c14 = $node.Str: :C14N;
        $xml-c14 = $node.Str: :C14N, :comments, :xpath($expression), :exclusive;
        $xml-c14 = $node.Str :C14N, :v1_1, :xpath($expression);
        $xml = $doc.serialize(:format);
        # -- Binary serialization/encoding
        my blob8 $buf = $node.Blob(:format, :enc<UTF-8>);
        # -- Data  serialization -- #
        use LibXML::Item :ast-to-xml;
        my $node-data = $node.ast;
        my LibXML::Node $node2 = ast-to-xml($node-data);

# -- Namespace Methods -- #
        my LibXML::Namespace @ns = $node.getNamespaces;
        my Str $localname = $node.localname;
        my Str $prefix = $node.prefix;
        my Str $uri = $node.namespaceURI();
        $uri = $node.lookupNamespaceURI( $prefix );
        $prefix = $node.lookupNamespacePrefix( $URI );
        $node.normalize;

# -- Positional interface -- #
        $node.push: LibXML::Element.new: :name<A>;
        $node.push: LibXML::Element.new: :name<B>;
        say $node[1].Str; # <B/>
        $node[1] = LibXML::Element.new: :name<C>;
        say $node.values».Str.join(':');  # <A/>:<C/>
        $node.pop;  # remove last child

# -- Associative interface -- #
        say $node.keys; # A B text() ..
        for $node<A> { ... }; # all '<A>..</A>' child nodes
        for $node<text()> { ... }; # text nodes

Description

LibXML::Node defines functions that are common to all Node Types. An 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 LibXML each node is part either of a document or a document-fragment. Because of this there is no node without a parent.

Many methods listed here are documented in the DOM Level 3 specification (http://www.w3.org/TR/DOM-Level-3-Core/). Please refer to the specification for extensive documentation.

Property Methods

method setNodeName

method setNodeName(QName $new-name)
        # -Or-
        $.nodeName = $new-name

In very limited situations, it is useful to change a nodes name. In the DOM specification this should throw an error. This Function is aware of namespaces.

method unique-key

method unique-key() returns Str

This function is not specified for any DOM level. It returns a key guaranteed to be unique for this node, and to always be the same value for this node. In other words, two node objects return the same key if and only if isSameNode indicates that they are the same node.

The returned key value is useful as a key in hashes.

method nodePath

method nodePath() returns Str

This function is not specified for any DOM level: It returns a canonical structure based XPath for a given node. For example:

use LibXML::Document;
use LibXML::Element;
LibXML::Document:D $doc .= parse: :file<samples/dromeds.xml>;
my LibXML::Element @humps = $doc.find: "//humps";
say @humps[0].nodePath: # /dromedaries/species[1]/humps

method isBlank

method isBlank() returns Bool

True if this is a text node or processing instruction, and it contains only blank content

method isHTMLish

method isHTMLish() returns Bool

True if this is an HTML document (type `XML_HTML_DOCUMENT_NODE`) or is owned by an HTML document. Used internally to set `:$html` default value for the `Blob` and `Str` methods.

Navigation Methods

hasChildNodes

method hasChildNodes() returns Bool

method childNodes

method childNodes(Bool :$blank = True) returns LibXML::Node::List

childNodes implements a more intuitive interface to the childnodes of the current node. It enables you to pass all children directly to a map or grep.

Note that child nodes are iterable:

for $elem.childNodes { ... }

They also directly support a number of update operations, including 'push' (add an element), 'pop' (remove last element) and ASSIGN-POS, e.g.:

$elem.childNodes[3] = LibXML::TextNode.new('p', 'replacement text for 4th child');

method nonBlankChildNodes

method nonBlankChildNodes() returns LibXML::Node::List

Get non-blank child nodes of a node

This equivalent to childNodes(:!blank). It returns only non-blank nodes (where a node is blank if it is a Text or CDATA node consisting of whitespace only). This method is not defined by DOM.

DOM Manipulation Methods

method addNewChild

method addNewChild(
            Str $uri,
            QName $name
        ) returns LibXML::Element

Vivify and add a new child element.

Similar to addChild(), this function uses low level libxml2 functionality to provide faster interface for DOM building. addNewChild() uses xmlNewChild() to create a new node on a given parent element.

addNewChild() has two parameters $nsURI and $name, where $nsURI is an (optional) namespace URI. $name is the fully qualified element name; addNewChild() will determine the correct prefix if necessary.

The function returns the newly created node.

This function is very useful for DOM building, where a created node can be directly associated with its parent. NOTE this function is not part of the DOM specification and its use may limit your code to Raku or Perl.

method removeChildNodes

method removeChildNodes() returns LibXML::DocumentFragment

Remove all child nodes, which are returned as a LibXML::DocumentFragment This function is not specified for any DOM level: It removes all childnodes from a node in a single step.

Searching Methods

method findnodes

multi method findnodes(Str $xpath-expr,
                               LibXML::Node $ref-node?,
                               Bool :$deref, :%ns) returns LibXML::Node::Set
        multi method findnodes(LibXML::XPath::Expression:D $xpath-expr,
                               LibXML::Node $ref-node?,
                               Bool :$deref, :%ns) returns LibXML::Node::Set
        # Examples:
        my LibXML::Node @nodes = $node.findnodes( $xpath-expr );
        my LibXML::Node::Set $nodes = $node.findnodes( $xpath-expr, :deref );
        for $node.findnodes($xpath-expr) {...}

findnodes evaluates the XPath expression (XPath 1.0) on the current node and returns the resulting node set as an array; returning an LibXML::Node::Set object.

The XPath expression can be passed either as a string, or as a LibXML::XPath::Expression object.

The `:deref` option has an effect on associative indexing:

my $humps = $node.findnodes("dromedaries/species")<species/humps>;
        my $humps = $node.findnodes("dromedaries/species", :deref)<humps>;

It indexes element child nodes and attributes. This option is used by the `AT-KEY` method (see below).

NOTE ON NAMESPACES AND XPATH:

A common mistake about XPath is to assume that node tests consisting of an element name with no prefix match elements in the default namespace. This assumption is wrong - by XPath specification, such node tests can only match elements that are in no (i.e. null) namespace.

So, for example, one cannot match the root element of an XHTML document with $node.find('/html') since '/html' would only match if the root element `<html>` had no namespace, but all XHTML elements belong to the namespace http://www.w3.org/1999/xhtml. (Note that xmlns="..." namespace declarations can also be specified in a DTD, which makes the situation even worse, since the XML document looks as if there was no default namespace).

There are several possible ways to deal with namespaces in XPath:

• The recommended way is to define a document independent prefix-to-namespace mapping. For example:

  my %ns = 'x' => 'http://www.w3.org/1999/xhtml';
            $node.find('/x:html', :%ns);
  

  --OR--

  my $xpath-context = $node.xpath-context: :%ns;
             $xpath-context.find('/x:html');
  

• Another possibility is to use prefixes declared in the queried document (if known). If the document declares a prefix for the namespace in question (and the context node is in the scope of the declaration), LibXML allows you to use the prefix in the XPath expression, e.g.:

  $node.find('/xhtml:html');
  

method find

multi method find( Str $xpath, :%ns) returns Any
      multi method find( LibXML::XPath::Expression:D $xpath, :%ns) returns Any

find evaluates the XPath 1.0 expression using the current node as the context of the expression, and returns the result depending on what type of result the XPath expression had. For example, the XPath "1 * 3 + 52" results in a Numeric object being returned. Other expressions might return an Bool object, or a Str object.

The XPath expression can be passed either as a string, or as a LibXML::XPath::Expression object.

See also LibXML::XPathContext.find.

method findvalue

multi method findvalue( Str $xpath, :%ns) returns Str
      multi method findvalue( LibXML::XPath::Expression:D $xpath, :%ns) returns Str

findvalue is equivalent to:

$node.find( $xpath ).to-literal;

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"/>.

See also LibXML::XPathContext.findvalue.

The xpath expression can be passed either as a string, or as a LibXML::XPath::Expression object.

method first

multi method first(Bool :$blank=True, :%ns) returns LibXML::Node
        multi method first(Str $xpath-expr, :%ns) returns LibXML::Node
        multi method first(LibXML::XPath::Expression:D $xpath-expr, :%ns) returns LibXML::Node
        # Examples
        my $child = $node.first;          # first child
        my $child = $node.first: :!blank; # first non-blank child
        my $descendant = $node.first($xpath-expr);

This node returns the first child node, or descendant node that matches an optional XPath expression.

method last

multi method last(Bool :$blank=True, :%ns) returns LibXML::Node
        multi method last(Str $xpath-expr, :%ns) returns LibXML::Node
        multi method last(LibXML::XPath::Expression:D $xpath-expr) returns LibXML::Node
        # Examples
        my $child = $node.last;          # last child
        my $child = $node.last: :!blank; # last non-blank child
        my $descendant = $node.last($xpath-expr);

This node returns the last child node, or descendant node that matches an optional XPath expression.

method exists

multi method exists(Str $xpath-expr, :%ns) returns Bool
        multi method exist(LibXML::XPath::Expression:D $xpath-expr, :%ns) returns Bool

This method behaves like findnodes, except that it only returns a boolean value (True if the expression matches a node, False otherwise) and may be faster than findnodes, because the XPath evaluation may stop early on the first match.

For XPath expressions that do not return node-set, the method returns True if the returned value is a non-zero number or a non-empty string.

xpath-context

method xpath-context() returns LibXML::XPath::Context

Gets the LibXML::XPath::Context object that is used for xpath queries (including `find()`, `findvalue()`, `exists()` and some `AT-KEY` queries.

$node.xpath-context.set-options: :suppress-warnings, :suppress-errors;

methods query-handler, querySelector, querySelectorAll

These methods provide pluggable support for CSS (or other 3rd party) Query Selectors. See https://www.w3.org/TR/selectors-api/#DOM-LEVEL-2-STYLE. For example, to use CSS::Selector::To::XPath (module available separately).

use CSS::Selector::To::XPath;
        $doc.query-handler = CSS::Selector::To::XPath.new;
        my $result-query = "#score>tbody>tr>td:nth-of-type(2)"
        my $results = $doc.querySelectorAll($result-query);
        my $first-result = $doc.querySelector($result-query);

See LibXML::XPath::Context for more details.

Serialization Methods

If :$comments is False or not specified, the result-document will not contain any comments that exist in the original document. To include comments into the canonized document, :$comments has to be set to True.

The parameter :$xpath defines the nodeset of nodes that should be visible in the resulting document. This can be used to filter out some nodes. One has to note, that only the nodes that are part of the nodeset, will be included into the result-document. Their child-nodes will not exist in the resulting document, unless they are part of the nodeset defined by the xpath expression.

If :$xpath is omitted or empty, Str: :C14N will include all nodes in the given sub-tree, using the following XPath expressions: with comments

(. | .//node() | .//@* | .//namespace::*)

and without comments

(. | .//node() | .//@* | .//namespace::*)[not(self::comment())]

An optional parameter :$selector can be used to pass an L<LibXML::XPathContext> object defining the context for evaluation of $xpath-expression. This is useful
    for mapping namespace prefixes used in the XPath expression to namespace URIs.
    Note, however, that $node will be used as the context node for the evaluation,
    not the context node of :$selector.

:v(v1.1) can be passed to specify v1.1 of the C14N specification. The `:$eclusve` flag is not applicable to this level.

multi method Str :C14N

multi method Str(Bool :C14N!, *%opts) returns Str

`$node.Str( :C14N, |%opts)` is equivalent to `$node.canonicalize(|%opts)`

multi method Str() returns Str

method Str(
            Bool :$format, Bool :$tag-expansion,
            Bool :$skip-xml-declaration,
            Bool :$html = self.isHTMLish,
            LibXML::Config :$config, # defaults for :skip-xml-declaration and :tag-expansion
        ) returns Str;

This method is similar to the method Str of a LibXML::Document but for a single node. It returns a string consisting of XML serialization of the given node and all its descendants.

method serialize

method serialize(*%opts) returns Str

An alias for Str. This function name was added to be more consistent with libxml2.

method Blob() returns Blob

method Blob(
            xmlEncodingStr :$enc = 'UTF-8',
            Bool :$format,
            Bool :$tag-expansion,
            Bool :$html = self.isHTMLish,
        ) returns Blob;

Returns a binary representation  of the XML
   node and its descendants encoded as `:$enc`.

use LibXML::Item :ast-to-xml;
        my $ast = $node.ast;
        my LibXML::Node $copy = ast-to-xml($ast);

Namespace Methods

method getNamespaces

method getNamespaces returns LibXML::Node::List
        my LibXML::Namespace @ns = $node.getNamespaces;

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 declared explicitly for that node.

Although getNamespaces is available for all nodes, it only makes sense if used with element nodes.

method lookupNamespaceURI

method lookupNamespaceURI( NCName $prefix ) returns Str;

Find a namespace URI by its prefix starting at the current node.

method lookupNamespacePrefix

method lookupNamespacePrefix( Str $URI ) returns NCName;

Find a namespace prefix by its URI starting at the current node.

NOTE Only the namespace URIs are meant to be unique. The prefix is only document related. Also the document might have more than a single prefix defined for a namespace.

method normalize

method normalize() returns Str

This function normalizes adjacent text nodes. This function is not as strict as libxml2's xmlTextMerge() function, since it will not free a node that is still referenced by Raku.

Associative Interface

methods AT-KEY, keys

say $node.AT-KEY("species");
      #-OR-
      say $node<species>;

say $node<species>.keys; # (disposition text() @name humps)
      say $node<species/humps>;
      say $node<species><humps>;

This is a lightweight associative interface, based on xpath expressions. `$node.AT-KEY($foo)` is equivalent to `$node.findnodes($foo, :deref)`.

Copyright

2001-2007, AxKit.com Ltd.

2002-2006, Christian Glahn.

2006-2009, Petr Pajas.

License

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0 http://www.perlfoundation.org/artistic_license_2_0.