File Coverage

lib/HTML/Object/DOM/NodeList.pm
Criterion Covered Total %
statement 19 21 90.4
branch n/a
condition n/a
subroutine 7 9 77.7
pod 2 2 100.0
total 28 32 87.5


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## HTML Object - ~/lib/HTML/Object/DOM/NodeList.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::NodeList;
15             BEGIN
16             {
17 1     1   1545 use strict;
  1         3  
  1         31  
18 1     1   8 use warnings;
  1         3  
  1         50  
19 1     1   6 use parent qw( Module::Generic::Array );
  1         2  
  1         7  
20 1     1   61 use vars qw( $VERSION );
  1         3  
  1         41  
21 1     1   32 our $VERSION = 'v0.2.0';
22             };
23              
24 1     1   6 use strict;
  1         2  
  1         19  
25 1     1   5 use warnings;
  1         2  
  1         98  
26              
27 0     0 1   sub forEach { return( shift->foreach( @_ ) ); }
28              
29 0     0 1   sub item { return( shift->index( @_ ) ); }
30              
31             1;
32             # NOTE: POD
33             __END__
34              
35             =encoding utf-8
36              
37             =head1 NAME
38              
39             HTML::Object::DOM::NodeList - HTML Object DOM NodeList Class
40              
41             =head1 SYNOPSIS
42              
43             use HTML::Object::DOM::NodeList;
44             my $list = HTML::Object::DOM::NodeList->new ||
45             die( HTML::Object::DOM::NodeList->error, "\n" );
46              
47             =head1 VERSION
48              
49             v0.2.0
50              
51             =head1 DESCRIPTION
52              
53             C<NodeList> objects are collections of L<nodes|HTML::Object::DOM::Node>, usually returned by properties such as L<HTML::Object::DOM::Node/childNodes> and methods such as L<HTML::Object::DOM::Document/querySelectorAll>.
54              
55             =head1 PROPERTIES
56              
57             =head2 length
58              
59             The number of nodes in the C<NodeList>.
60              
61             Example:
62              
63             # All the paragraphs in the document
64             my $items = $doc->getElementsByTagName("p");
65              
66             # For each item in the list,
67             # append the entire element as a string of HTML
68             my $gross = "";
69             for( my $i = 0; $i < $items->length; $i++ )
70             {
71             $gross += $items->[$i]->innerHTML;
72             }
73             # $gross is now all the HTML for the paragraphs
74              
75             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/NodeList/length>
76              
77             =head1 METHODS
78              
79             Inherits methods from its parent L<Module::Generic::Array>
80              
81             =head2 forEach
82              
83             Executes a provided code reference (reference to a subroutine or anonymous subroutine) once per C<NodeList> element, passing the element as an argument to the subroutine.
84              
85             Example:
86              
87             my $node = $doc->createElement("div");
88             my $kid1 = $doc->createElement("p");
89             my $kid2 = $doc->createTextNode("hey");
90             my $kid3 = $doc->createElement("span");
91              
92             $node->appendChild( $kid1 );
93             $node->appendChild( $kid2 );
94             $node->appendChild( $kid3 );
95              
96             my $list = $node->childNodes;
97             $list->forEach(sub(currentValue, currentIndex, listObj)
98             {
99             my( $currentValue, $currentIndex, $listObj ) = @_;
100             say( "$currentValue, $currentIndex, $_" );
101             });
102              
103             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/NodeList/forEach>
104              
105             =head2 item
106              
107             Returns an item in the list by its index, or C<undef> if the index is out-of-bounds.
108             An alternative to accessing nodeList[i] (which instead returns  undefined when i is out-of-bounds). This is mostly useful for non-JavaScript DOM implementations.
109              
110             Example:
111              
112             my $tables = $doc->getElementsByTagName( 'table' );
113             my $firstTable = $tables->item(1); # or $tables->[1] - returns the second table in the DOM
114              
115             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/NodeList/item>
116              
117             =head2 keys
118              
119             Returns an iterator, allowing code to go through all the keys of the key/value pairs contained in the collection. (In this case, the keys are numbers starting from 0.)
120              
121             Example:
122              
123             my $node = $doc->createElement("div");
124             my $kid1 = $doc->createElement("p");
125             my $kid2 = $doc->createTextNode("hey");
126             my $kid3 = $doc->createElement("span");
127              
128             $node->appendChild( $kid1 );
129             $node->appendChild( $kid2 );
130             $node->appendChild( $kid3 );
131              
132             my $list = $node->childNodes;
133              
134             # Using for..of
135             foreach my $key ( $list->keys->list )
136             {
137             say( $key );
138             }
139              
140             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/NodeList/keys>
141              
142             =head2 values
143              
144             Returns an iterator allowing code to go through all values (nodes) of the key/value pairs contained in the collection.
145              
146             Example:
147              
148             my $node = $doc->createElement("div");
149             my $kid1 = $doc->createElement("p");
150             my $kid2 = $doc->createTextNode("hey");
151             my $kid3 = $doc->createElement("span");
152              
153             $node->appendChild( $kid1 );
154             $node->appendChild( $kid2 );
155             $node->appendChild( $kid3 );
156              
157             my $list = $node->childNodes;
158              
159             # Using for..of
160             foreach my $value ( $list->values )
161             {
162             say( $value );
163             }
164              
165             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/NodeList/values>
166              
167             =head1 AUTHOR
168              
169             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
170              
171             =head1 SEE ALSO
172              
173             L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/NodeList>
174              
175             =head1 COPYRIGHT & LICENSE
176              
177             Copyright(c) 2022 DEGUEST Pte. Ltd.
178              
179             All rights reserved
180              
181             This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
182              
183             =cut