File Coverage

lib/HTML/Object/Collection.pm
Criterion Covered Total %
statement 52 53 98.1
branch 7 10 70.0
condition 2 5 40.0
subroutine 14 15 93.3
pod 4 4 100.0
total 79 87 90.8


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## HTML Object - ~/lib/HTML/Object/Collection.pm
3             ## Version v0.2.0
4             ## Copyright(c) 2021 DEGUEST Pte. Ltd.
5             ## Author: Jacques Deguest <jack@deguest.jp>
6             ## Created 2021/04/28
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::Collection;
15             BEGIN
16             {
17 3     3   1615 use strict;
  3         11  
  3         104  
18 3     3   22 use warnings;
  3         6  
  3         79  
19 3     3   27 use warnings::register;
  3         6  
  3         614  
20 3     3   26 use parent qw( HTML::Object::DOM::Element );
  3         5  
  3         15  
21 3     3   258 use vars qw( $VERSION );
  3         8  
  3         162  
22 3     3   55 our $VERSION = 'v0.2.0';
23             };
24              
25 3     3   21 use strict;
  3         10  
  3         67  
26 3     3   13 use warnings;
  3         7  
  3         328  
27              
28             # Purpose of this class is to serve as a distinctive class for search result from find()
29             sub init
30             {
31 16     16 1 1381 my $self = shift( @_ );
32 16         443 $self->{end} = '';
33 16         61 $self->{tag} = '_collection';
34 16         49 $self->{_init_strict_use_sub} = 1;
35 16         53 $self->{_exception_class} = 'HTML::Object::Exception';
36 16 50       105 $self->SUPER::init( @_ ) || return( $self->pass_error );
37 16         60 my $class = ref( $self );
38             # To make collection exception also available as $HTML::Object::ERROR
39             $self->{_error_handler} = sub
40             {
41 2     2   6111 my $ex = shift( @_ );
42             # ${"${class}\::ERROR"} = $ex;
43 3     3   29 no warnings 'once';
  3         6  
  3         959  
44 2         24 $HTML::Object::ERROR = $ex;
45 2 50       848 warnings::warn( $ex ) if( warnings::enabled( 'HTML::Object' ) );
46 16         103 };
47 16         51 return( $self );
48             }
49              
50             sub as_string
51             {
52 5     5 1 1055 my $self = shift( @_ );
53 5         30 my $opts = $self->_get_args_as_hash( @_ );
54 5 100       523 $opts->{all} = 0 if( !CORE::exists( $opts->{all} ) );
55 5   50     24 $opts->{all} //= 0;
56             # In conformity with jQuery, we return the stringified version of the first object in our set
57             # unless the 'all' option is provided and true. This is a divergence
58 5 100       25 if( $opts->{all} )
59             {
60 3         17 my $res = $self->new_array;
61             $self->children->foreach(sub
62             {
63 20     20   3429 my $child = shift( @_ );
64             # This will instruct the HTML::Object::Element to automatically close
65 20         143 my $str = $_->as_string( inside_collection => 1 );
66 20         594 $res->push( $str );
67 3         69 });
68 3         713 return( $res->join( '' ) );
69             }
70             else
71             {
72 2         10 my $first = $self->children->first;
73             # If there is no element object in our collection, we return an empty scalar object
74             # to avoid a potential perl error of "called on undefined value"
75             # The user can then easily check if anything was provided with:
76             # $e->as_string->length
77 2 50 33     314 return( $self->new_scalar ) if( !$first || !$self->_is_a( $first, 'HTML::Object::Element' ) );
78 2         77 return( $first->as_string( inside_collection => 1 ) );
79             }
80             }
81              
82 16     16 1 1475 sub end { return( shift->_set_get_object( 'end', 'HTML::Object::Element', @_ ) ); }
83              
84             # Note: Property
85 0     0 1   sub nodeValue { return; }
86              
87             1;
88             # NOTE: POD
89             __END__
90              
91             =encoding utf-8
92              
93             =head1 NAME
94              
95             HTML::Object::Collection - HTML Object XQuery Collection Class
96              
97             =head1 SYNOPSIS
98              
99             use HTML::Object::Collection;
100             my $col = HTML::Object::Collection->new ||
101             die( HTML::Object::Collection->error, "\n" );
102              
103             =head1 VERSION
104              
105             v0.2.0
106              
107             =head1 DESCRIPTION
108              
109             This module serves as a collection of L<HTML elements|HTML::Object::Element> and is used by L<XQuery|HTML::Object::XQuery> when a query is made with a selector or other criteria to group several L<HTML objects|HTML::Object::Element> just like jQuery does.
110              
111             It inherits from L<HTML::Object::Document> and does not do much except for a handful methods.
112              
113             =head1 INHERITANCE
114              
115             +-----------------------+ +------------------------+ +--------------------------+
116             | HTML::Object::Element | --> | HTML::Object::Document | --> | HTML::Object::Collection |
117             +-----------------------+ +------------------------+ +--------------------------+
118              
119             =head1 PROPERTIES
120              
121             =head2 nodeValue
122              
123             This returns or sets the value of the current node.
124              
125             For document, element or collection, this returns C<undef> and for attribute, text or comment, this returns the objct value.
126              
127             See L<for more information|https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeValue>
128              
129             =head1 METHODS
130              
131             =head2 as_string
132              
133             When called, this will return the string representation of the first L<HTML element object|HTML::Object::Element> it contains similar to the behaviour of jQuery. However, as an added feature, if this method is called with C<all> set to 1 or a positive value then, it will return the string representation for all the L<HTML element objects|HTML::Object::Element> it holds.
134              
135             =head2 end
136              
137             Set or get the end L<element|HTML::Object::Element>
138              
139             =head1 AUTHOR
140              
141             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
142              
143             =head1 SEE ALSO
144              
145             L<HTML::Object>, L<HTML::Object::Attribute>, L<HTML::Object::Boolean>, L<HTML::Object::Closing>, L<HTML::Object::Collection>, L<HTML::Object::Comment>, L<HTML::Object::Declaration>, L<HTML::Object::Document>, L<HTML::Object::Element>, L<HTML::Object::Exception>, L<HTML::Object::Literal>, L<HTML::Object::Number>, L<HTML::Object::Root>, L<HTML::Object::Space>, L<HTML::Object::Text>, L<HTML::Object::XQuery>
146              
147             =head1 COPYRIGHT & LICENSE
148              
149             Copyright (c) 2021 DEGUEST Pte. Ltd.
150              
151             All rights reserved
152              
153             This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
154              
155             =cut