cXML/Object.pm

filter: Statementstmt 100% 78 / 78 Branchbran 100% 24 / 24 Conditioncond 100% 3 / 3 MC/DCmcdc 100% 2 / 2 Subroutinesub 100% 15 / 15 Podpod 100% 4 / 4 totaltotal 100% 126 / 126 CC 18 SCAR 12.7
CC
18
Cov
100%
_getset
7.0
new
5.0
copy
3.0
CRAP 3.6
« cXML/Address/Postal.pm ↑ Summary cXML/Contact.pm »
1 =encoding utf-8
2  
3 =head1 NAME
4  
5 Business::cXML::Object - Generic cXML object
6  
7 =head1 SYNOPSIS
8  
9 package Business::cXML::YourPackage;
10 use base qw(Business::cXML::Object);
11  
12 use constant NODENAME => 'XMLNodeName';
13  
14 use constant PROPERTIES => (
15 first_name => '',
16 last_name => undef,
17 emails => [],
18 phone => undef,
19 );
20 # new(), first_name(), last_name() and emails() get/set methods will be provided automatically
21  
22 # Optionally: an e-mail is actually a Something::Email object
23 # Even more optional: a phone is actually a Something::Number with "Phone" argument
24 use constant OBJ_PROPERTIES => (
25 emails => 'Something::Email',
26 phone => [ 'Something::Number', 'Phone' ],
27 );
28  
29 =head1 DESCRIPTION
30  
31 Base class for cXML objects which represent useful data (pretty much every
32 module except L<Business::cXML> and L<Business::cXML::Transmission>).
33  
34 Declarations in I<C<PROPERTIES>> represent property names to create in new
35 instances along with their default value. A default value of C<undef> is
36 acceptable: every possible property must be explicitly declared. A default
37 value of C<[]> indicates that the property is a list instead of a single
38 value. C<can()> will behave as expected, recognizing your methods and
39 automatic property methods.
40  
41 Declare those properties which should be objects (or lists of objects) of a
42 specific class in optional I<C<OBJ_PROPERTIES>> (in addition to
43 I<C<PROPERTIES>>) to specify which class (see example in L</SYNOPSIS>). If
44 the class is actually an arrayref, the first element will be considered the
45 class name and all other elements will be passed as arguments to the class'
46 C<new()> after the value hashref argument.
47  
48 I<C<NODENAME>> will be used in cases where C<_nodeName> cannot be
49 inferred from context.
50  
51 =cut
52  
53 13 ▶use 5.014;
Subroutine BEGIN: called CC=1 SCAR=0.0
54 13 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
55  
56 package Business::cXML::Object;
57  
58 13 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
59 13 ▶use Clone qw(clone);
Subroutine BEGIN: called CC=1 SCAR=0.0
60  
61 13 ▶use constant PROPERTIES => ();
Subroutine BEGIN: called CC=1 SCAR=0.0
62 13 ▶use constant OBJ_PROPERTIES => ();
Subroutine BEGIN: called CC=1 SCAR=0.0
63 13 ▶use constant NODENAME => 'GenericNode';
Subroutine BEGIN: called CC=1 SCAR=0.0
64  
65 =head1 COMMON METHODS
66  
67 The following methods are automatically available in all objects which inherit
68 from this one.
69  
70 =over
71  
72 =item C<B<new>( [I<$nodename>], [I<$node>], [I<$properties>] )>
73  
74 In some cases, specifying I<$nodename> is necessary, such as when creating a
75 new multi-name object like L<Business::cXML::Amount> without a source
76 I<$node>. This sets property C<_nodeName>. Alternatively, I<C<$properties>>
77 can also contain a C<_nodeName>, which is writeable during object creation.
78  
79 L<XML::LibXML::Element> I<C<$node>> is passed to L</from_node()>.
80  
81 Hashref I<C<$properties>> is passed to L</set()>.
82  
83 =cut
84  
85 87 ▶sub new {
Subroutine new: called CC=5 SCAR=16.1
Pod documented
86 87 my $class = shift;
87  
88 # Create instance
89 87 my $self = {
90 _nodeName => undef,
91 };
92 87 bless $self, $class; # $self->isa() true for 'Business::cXML::Object' and your own class, magically
93  
94 # Populate with declared default values
95 87 $self->{_nodeName} = clone($self->NODENAME); # First in case PROPERTIES overrides it
96 87 my %fields = $self->PROPERTIES;
97 87 $self->{$_} = clone($fields{$_}) foreach keys %fields;
98  
99 # Process arguments
100 87 foreach (@_) {
101 84 ▶ if (ref($_) eq 'HASH') {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $_ eq 'HASH') { } 24 60 84
elsif (ref $_) { } 52 8 60
102 24 $self->set(%{ $_ });
103 } elsif (ref($_)) {
104 52 $self->{_nodeName} = $_->nodeName;
105 52 $self->from_node($_);
106 } else {
107 8 $self->{_nodeName} = $_;
108 };
109 };
110  
111 87 return $self;
112 }
113  
114 =item C<B<set>( I<%properties> )>
115  
116 Batch sets all known read-write properties, safely ignoring any unknown keys.
117  
118 =cut
119  
120 29 ▶sub set {
Subroutine set: called CC=2 SCAR=6.9
Pod documented
121 29 my ($self, %props) = @_;
122 29 $self->_getset($_, $props{$_}) foreach keys %props;
123 }
124  
125 =item C<B<copy>( I<$object> )>
126  
127 Copy data from another cXML object into our own, only considering known
128 properties. It is thus theoretically safe to copy from an object of a
129 different class. Deep structures (hashes, arrays, other objects) are cloned
130 into new copies.
131  
132 =cut
133  
134 1 ▶sub copy {
Subroutine copy: called CC=3 SCAR=11.0
Pod documented
135 1 my ($self, $other) = @_;
136 1 my %fields = $self->PROPERTIES;
137 1 foreach (keys %fields) {
138 4 ▶ $self->{$_} = clone($other->{$_}) if exists $other->{$_};
Branch: 1 branch
BranchTrueFalseTotal
if exists $other->{$_} 2 2 4
139 };
140 }
141  
142 =back
143  
144 The following methods are required to be provided by classes which inherit
145 from this one.
146  
147 =over
148  
149 =item C<B<from_node>( I<$node> )>
150  
151 Overwrite our internal data from what is found by traversing I<C<$node>>, a
152 L<XML::LibXML::Element>.
153  
154 =item C<B<to_node>( I<$doc> )>
155  
156 Returns an L<XML::LibXML::Element> constructed from our internal data.
157 I<C<$doc>> can be any existing L<XML::LibXML::Element> so that this method can
158 return a new detached element within the same existing document.
159  
160 =item C<B<can>( I<$methodname> )>
161  
162 L<UNIVERSAL::can()> is properly overloaded according to L</PROPERTIES> so it
163 can still safely be used.
164  
165 =cut
166  
167 752 ▶sub can {
Subroutine can: called CC=3 SCAR=11.0
Pod documented
168 752 my ($self, $method) = @_;
169 752 my $universal = UNIVERSAL::can($self, $method);
170 752 ▶ unless (defined $universal) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $universal) 751 1 752
171 751 my %fields = $self->PROPERTIES;
172 751 ▶ $universal = \&AUTOLOAD if exists $self->{$method};
Branch: 1 branch
BranchTrueFalseTotal
if exists $self->{$method} 380 371 751
173 };
174 752 return $universal;
175 }
176  
177 =back
178  
179 =head1 PROPERTY METHODS
180  
181 Each property declared in I<C<PROPERTIES>> of classes which inherit from this
182 one, can be read from and written to by invoking a method of the same name.
183  
184 Calling with no arguments (perhaps not even parenthesis) returns the current
185 value.
186  
187 Calling with an argument overwrites the property and returns the new value.
188 For arrayref properties (documented with a C<[]> suffix), setting a new value
189 actually pushes a new one into the list. For properties which are objects of
190 a specific class, passing a hashref argument automatically creates a new
191 object of that class with that hashref.
192  
193 B<Example:>
194  
195 my $addr = new Business::cXML::Contact;
196  
197 $addr->name('John Smith');
198 print $addr->name; # Prints: John Smith
199  
200 $addr->emails('john1@');
201 $addr->emails('john2@');
202 print join(' ', @{ $addr->emails }); # Prints: john1@ john2@
203  
204 The following properties are automatically available in all objects which
205 inherit from this one:
206  
207 =over
208  
209 =item C<B<_nodeName>>
210  
211 Read-only name of the current cXML node.
212  
213 =back
214  
215 =cut
216  
217 3 ▶sub _nodeName { shift->{_nodeName} }
Subroutine _nodeName: called CC=1 SCAR=0.0
218  
219 295 ▶sub _getset {
Subroutine _getset: called CC=7 SCAR=19.5
220 295 my ($self, $name, $val) = @_;
221  
222 295 ▶ return unless exists $self->{$name};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->{$name} 1 294 295
223 294 my %obj_fields = $self->OBJ_PROPERTIES;
224  
225 294 ▶ if (exists($obj_fields{$name}) && ref($val) eq 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $obj_fields{$name} and ref $val eq "HASH") 15 279 294
Condition100%3/3
exists $obj_fields{$name} and ref $val eq "HASH"
!ll&&!rl&&r
2344515
MC/DC100%2/2
exists $obj_fields{$name} and ref $val eq "HASH"
exists $obj_fields{$name} ref $val eq "HASH"
Truth table100%3/3
A and B
A= exists $obj_fields{$name}B= ref $val eq "HASH"
ABresult
0X0
100
111
226 15 my @args;
227 my $class;
228 15 ▶ if (ref($obj_fields{$name}) eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $obj_fields{$name} eq 'ARRAY') { } 5 10 15
229 5 @args = @{ $obj_fields{$name} };
230 5 $class = shift(@args);
231 } else {
232 10 $class = $obj_fields{$name};
233 };
234  
235 15 unshift(@args, $val);
236 15 my $file = $class;
237 15 $file =~ s|::|/|g;
238 15 require "$file.pm";
239 15 $val = $class->new(@args);
240 };
241  
242 294 ▶ if (@_ > 2) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_ > 2) 274 20 294
243 274 ▶ if (ref($self->{$name}) eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $self->{$name} eq 'ARRAY') { } 30 244 274
244 30 push @{ $self->{$name} }, $val;
245 } else {
246 244 $self->{$name} = $val;
247 };
248 };
249  
250 294 return $self->{$name};
251 }
252  
253 219 ▶sub AUTOLOAD {
Subroutine AUTOLOAD: called CC=3 SCAR=11.0
254 219 my $self = shift; # We need a clean @_ to be passed to _getset() later
255  
256 219 our $AUTOLOAD;
257 219 my $field = $AUTOLOAD;
258 219 $field =~ s/.*:://;
259 219 ▶ croak "Unknown method $field" unless ref $self;
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 1 218 219
260  
261 218 ▶ if (exists $self->{$field}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $self->{$field}) { } 217 1 218
262 217 return $self->_getset($field, @_);
263 } else {
264 1 croak qq'Can\'t locate object method "$field" via package "@{[ ref $self ]}"';
265 };
266 }
267 1 ▶sub DESTROY { } # Having AUTOLOAD requires us also having an explicit DESTROY.
Subroutine DESTROY: called CC=1 SCAR=0.0
268  
269 =head1 AUTHOR
270  
271 Stéphane Lavergne L<https://github.com/vphantom>
272  
273 =head1 ACKNOWLEDGEMENTS
274  
275 Graph X Design Inc. L<https://www.gxd.ca/> sponsored this project.
276  
277 =head1 COPYRIGHT & LICENSE
278  
279 Copyright (c) 2017-2018 Stéphane Lavergne L<https://github.com/vphantom>
280  
281 Permission is hereby granted, free of charge, to any person obtaining a copy
282 of this software and associated documentation files (the "Software"), to deal
283 in the Software without restriction, including without limitation the rights
284 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
285 copies of the Software, and to permit persons to whom the Software is
286 furnished to do so, subject to the following conditions:
287  
288 The above copyright notice and this permission notice shall be included in all
289 copies or substantial portions of the Software.
290  
291 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
292 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
293 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
294 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
295 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
296 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
297 SOFTWARE.
298 =cut
299  
300 13 1;
« cXML/Address/Postal.pm ↑ Summary cXML/Contact.pm »