File Coverage

lib/HTML/Object/DOM/XPathEvaluator.pm
Criterion Covered Total %
statement 22 37 59.4
branch 0 6 0.0
condition 0 5 0.0
subroutine 8 12 66.6
pod 4 4 100.0
total 34 64 53.1


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## HTML Object - ~/lib/HTML/Object/DOM/XPathEvaluator.pm
3             ## Version v0.2.0
4             ## Copyright(c) 2022 DEGUEST Pte. Ltd.
5             ## Author: Jacques Deguest <jack@deguest.jp>
6             ## Created 2022/01/01
7             ## Modified 2022/09/18
8             ## All rights reserved
9             ##
10             ##
11             ## This program is free software; you can redistribute it and/or modify it
12             ## under the same terms as Perl itself.
13             ##----------------------------------------------------------------------------
14             package HTML::Object::DOM::XPathEvaluator;
15             BEGIN
16             {
17 1     1   947 use strict;
  1         4  
  1         29  
18 1     1   5 use warnings;
  1         2  
  1         30  
19 1     1   6 use parent qw( Module::Generic );
  1         2  
  1         5  
20 1     1   58 use vars qw( $VERSION );
  1         2  
  1         50  
21 1     1   590 use HTML::Object::XPath;
  1         4  
  1         13  
22 1     1   296 our $VERSION = 'v0.2.0';
23             };
24              
25 1     1   8 use strict;
  1         2  
  1         21  
26 1     1   5 use warnings;
  1         1  
  1         253  
27              
28             sub init
29             {
30 0     0 1   my $self = shift( @_ );
31 0           $self->{_init_strict_use_sub} = 1;
32 0 0         $self->SUPER::init( @_ ) || return( $self->pass_error );
33 0           $self->{_xp} = HTML::Object::XPath->new;
34 0           return( $self );
35             }
36              
37 0     0 1   sub createExpression { return( shift->{_xp}->parse( @_ ) ); }
38              
39 0     0 1   sub createNSResolver { return; }
40              
41             sub evaluate
42             {
43 0     0 1   my $self = shift( @_ );
44 0           my $expr = shift( @_ );
45 0 0 0       if( $self->_is_a( $expr => 'HTML::Object::XPath::Expr' ) )
    0          
46             {
47 0           return( $expr->evaluate( @_ ) );
48             }
49             elsif( !ref( $expr ) || overload::Method( $expr, '""' ) )
50             {
51 0   0       my $xpath = $self->{_xp}->parse( $expr ) || return( $self->pass_error( $self->{_xp}->error ) );
52 0           return( $xpath->evaluate( @_ ) );
53             }
54             else
55             {
56 0           return( $self->error({
57             message => 'Value provided (' . overload::StrVal( $expr ) . ' is not a HTML::Object::XPath::Expr object. You can create one using createExpression()',
58             class => 'HTML::Object::TypeError',
59             }) );
60             }
61 0           return( $self );
62             }
63              
64             1;
65             # NOTE: POD
66             __END__
67              
68             =encoding utf-8
69              
70             =head1 NAME
71              
72             HTML::Object::DOM::XPathEvaluator - HTML Object DOM XPathEvaluator Class
73              
74             =head1 SYNOPSIS
75              
76             use HTML::Object::DOM::XPathEvaluator;
77             my $this = HTML::Object::DOM::XPathEvaluator->new ||
78             die( HTML::Object::DOM::XPathEvaluator->error, "\n" );
79              
80             =head1 VERSION
81              
82             v0.2.0
83              
84             =head1 DESCRIPTION
85              
86             The C<XPathEvaluator> interface allows to compile and evaluate XPath expressions.
87              
88             =head1 PROPERTIES
89              
90             There are no properties.
91              
92             =head1 METHODS
93              
94             =head2 createExpression
95              
96             Creates a parsed XPath expression with resolved namespaces.
97              
98             Example:
99              
100             <div>XPath example</div>
101             <div>Number of &lt;div&gt;s: <output></output></div>
102              
103             use HTML::Object::DOM;
104             my $parser = HTML::Object::DOM->new;
105             my $doc = $parser->parse_data( $html ) || die( $parser->error );
106             my $evaluator = HTML::Object::DOM::XPathEvaluator->new;
107             my $expression = $evaluator->createExpression( '//div' );
108             my $result = $expression->evaluate( $document );
109             $doc->querySelector( 'output' )->textContent = $result->snapshotLength;
110              
111             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/XPathEvaluator/createExpression>
112              
113             =head2 createNSResolver
114              
115             This always returns C<undef>, since this L<HTML::Object> does not work on XML documents.
116              
117             Normally, this would adapt any L<DOM node|HTML::Object::DOM::Node> to resolve namespaces allowing the XPath expression to be evaluated relative to the context of the node where it appeared within the document.
118              
119             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/XPathEvaluator/createNSResolver>
120              
121             =head2 evaluate
122              
123             Evaluates an XPath expression string and returns a result of the specified type if possible.
124              
125             Parameters:
126              
127             =over 4
128              
129             =item expression
130              
131             A string representing the XPath expression to be parsed and evaluated, or an L<XPath expression object|HTML::Object::XPath::Expr> to be evaluated. The latter would be equivalent to:
132              
133             $xpath_expression->evaluate( $context );
134              
135             With C<$context> being a L<node object|HTML::Object::DOM::Node> provided, such as L<HTML::Object::DOM::Document>.
136              
137             =item contextNode
138              
139             A L<Node|HTML::Object::DOM::Node> representing the context to use for evaluating the expression.
140              
141             =back
142              
143             Example:
144              
145             <div>XPath example</div>
146             <div>Number of &lt;div&gt;s: <output></output></div>
147              
148             use HTML::Object::DOM;
149             my $parser = HTML::Object::DOM->new;
150             my $doc = $parser->parse_data( $html ) || die( $parser->error );
151             my $evaluator = HTML::Object::DOM::XPathEvaluator->new;
152             my $result = $evaluator->evaluate( '//div', $doc );
153             $doc->querySelector( 'output' )->textContent = $result->snapshotLength;
154              
155             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/XPathEvaluator/evaluate>
156              
157             =head1 AUTHOR
158              
159             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
160              
161             =head1 SEE ALSO
162              
163             L<HTML::Selector::XPath>, L<HTML::Object::XPath>, L<HTML::Object::XPath::Expr>
164              
165             =head1 COPYRIGHT & LICENSE
166              
167             Copyright(c) 2022 DEGUEST Pte. Ltd.
168              
169             All rights reserved
170              
171             This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
172              
173             =cut