The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
HTML-Object-v0.3.1
River stage zero No dependents
1 ++
/ HTML::Object::DOM::XPathResult

NAME

HTML::Object::DOM::XPathResult - HTML Object DOM XPath Result Class

SYNOPSIS

    use HTML::Object::DOM::XPathResult;
    my $result = HTML::Object::DOM::XPathResult->new ||
         die( HTML::Object::DOM::XPathResult->error, "\n" );

VERSION

    v0.2.0

DESCRIPTION

The XPathResult interface represents the results generated by evaluating an XPath expression within the context of a given node.

The method you can access vary depending on the type of results returned. The XPath evaluation can return a boolean, a number, a string, or a node set

PROPERTIES

All properties are read-only, but you can change their returned value by changing the value of "result", which contains the result from the XPath search.

booleanValue

A boolean representing the value of the result if resultType is BOOLEAN_TYPE, i.e. if the result is a boolean.

Example:

    <div>XPath example</div>
    <p>Text is 'XPath example': <output></output></p>

    my $xpath = "//div/text() = 'XPath example'";
    my $result = $doc->evaluate( $xpath, $doc );
    $doc->querySelector( 'output' )->textContent = $result->booleanValue;

See also Mozilla documentation

invalidIteratorState

This always return undef under perl, but you can change the value of this boolean to whatever boolean value you want.

Normally, under JavaScript, this signifies that the iterator has become invalid. It is true if resultType is UNORDERED_NODE_ITERATOR_TYPE or ORDERED_NODE_ITERATOR_TYPE and the document has been modified since this result was returned.

Example:

    <div>XPath example</div>
    <p>Iterator state: <output></output></p>

    my $xpath = '//div';
    my $result = $doc->evaluate( $xpath, $doc );
    # Invalidates the iterator state
    $doc->querySelector( 'div' )->remove();
    $doc->querySelector( 'output' )->textContent = $result->invalidIteratorState ? 'invalid' : 'valid';

See also Mozilla documentation

numberValue

A number representing the value of the result if resultType is NUMBER_TYPE, i.e. if the result is a number.

Example:

    <div>XPath example</div>
    <div>Number of &lt;div&gt;s: <output></output></div>

    my $xpath = 'count(//div)';
    my $result = $doc->evaluate( $xpath, $doc );
    $doc->querySelector( 'output' )->textContent = $result->numberValue;

See also Mozilla documentation

result

Sets or gets the resulting object from the XPath search. This could be a node, a boolean, a number, a string, or a set of nodes

resultType

A number code representing the type of the result, as defined by the type constants. See "CONSTANTS"

Example:

    <div>XPath example</div>
    <div>Is XPath result a node set: <output></output></div>

    use HTML::Object::DOM::XPathResult;
    # or
    use HTML::Object::DOM qw( :xpath );
    my $xpath = '//div';
    my $result = $doc->evaluate( $xpath, $doc );
    $doc->querySelector( 'output' )->textContent =
        $result->resultType >= UNORDERED_NODE_ITERATOR_TYPE &&
        $result->resultType <= FIRST_ORDERED_NODE_TYPE;

See also Mozilla documentation

singleNodeValue

A Node representing the value of the single node result, which may be undef. This is set when the result is a single node.

Example:

    <div>XPath example</div>
    <div>Tag name of the element having the text content 'XPath example': <output></output></div>

    my $xpath = q{//*[text()='XPath example']};
    my $result = $doc->evaluate( $xpath, $doc );
    $doc->querySelector( 'output' )->textContent = $result->singleNodeValue->localName;

See also Mozilla documentation

snapshotLength

The number of nodes in the result snapshot. As a divergence from the standard, this also applies to the number of elements in the NodeSet returned.

Example:

    <div>XPath example</div>
    <div>Number of matched nodes: <output></output></div>

    my $xpath = '//div';
    my $result = $doc->evaluate( $xpath, $doc );
    $doc->querySelector( 'output' )->textContent = $result->snapshotLength;

See also Mozilla documentation

stringValue

A string representing the value of the result if resultType is STRING_TYPE, i.e. when the result is a string.

Example:

    <div>XPath example</div>
    <div>Text content of the &lt;div&gt; above: <output></output></div>

    my $xpath = '//div/text()';
    my $result = $doc->evaluate( $xpath, $doc );
    $doc->querySelector( 'output' )->textContent = $result->stringValue;

See also Mozilla documentation

METHODS

iterateNext

If the result is a node set, this method iterates over it and returns the next node from it or undef if there are no more nodes.

Example:

    <div>XPath example</div>
    <div>Tag names of the matched nodes: <output></output></div>

    use Module::Generic::Array;
    my $xpath = '//div';
    my $result = $doc->evaluate( $xpath, $doc );
    my $node;
    my $tagNames = Module::Generic::Array->new;
    while( $node = $result->iterateNext() )
    {
        $tagNames->push( $node->localName );
    }
    $doc->querySelector( 'output' )->textContent = $tagNames->join( ', ' );

See also Mozilla documentation

snapshotItem

Returns an item of the snapshot collection or undef in case the index is not within the range of nodes.

Normally, under JavaScript, unlike the iterator result, the snapshot does not become invalid, but may not correspond to the current document if it is mutated.

Example:

    <div>XPath example</div>
    <div>Tag names of the matched nodes: <output></output></div>

    use Module::Generic::Array;
    my $xpath = '//div';
    my $result = $doc->evaluate( $xpath, $doc );
    my $node;
    my $tagNames = Module::Generic::Array->new;
    for( my $i = 0; $i < $result->snapshotLength; $i++ )
    {
        my $node = $result->snapshotItem( $i );
        $tagNames->push( $node->localName );
    }
    $doc->querySelector( 'output' )->textContent = $tagNames->join( ', ' );

See also Mozilla documentation

CONSTANTS

The following constants are exported by default:

ANY_TYPE (0)

A result set containing whatever type naturally results from evaluation of the expression. Note that if the result is a node-set then UNORDERED_NODE_ITERATOR_TYPE is always the resulting type.

NUMBER_TYPE (1)

A result containing a single number. This is useful for example, in an XPath expression using the count() function.

STRING_TYPE (2)

A result containing a single string.

BOOLEAN_TYPE (3)

A result containing a single boolean value. This is useful for example, in an XPath expression using the not() function.

UNORDERED_NODE_ITERATOR_TYPE (4)

A result node-set containing all the nodes matching the expression. The nodes may not necessarily be in the same order that they appear in the document.

ORDERED_NODE_ITERATOR_TYPE (5)

A result node-set containing all the nodes matching the expression. The nodes in the result set are in the same order that they appear in the document.

UNORDERED_NODE_SNAPSHOT_TYPE (6)

A result node-set containing snapshots of all the nodes matching the expression. The nodes may not necessarily be in the same order that they appear in the document.

ORDERED_NODE_SNAPSHOT_TYPE (7)

A result node-set containing snapshots of all the nodes matching the expression. The nodes in the result set are in the same order that they appear in the document.

ANY_UNORDERED_NODE_TYPE (8)

A result node-set containing any single node that matches the expression. The node is not necessarily the first node in the document that matches the expression.

FIRST_ORDERED_NODE_TYPE (9)

A result node-set containing the first node in the document that matches the expression.

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Mozilla documentation, W3C specifications

COPYRIGHT & LICENSE

Copyright(c) 2022 DEGUEST Pte. Ltd.

All rights reserved

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.