XMLRPC.pm

filter: Statementstmt 94.8% 129 / 136 Branchbran 87.5% 77 / 88 Conditioncond 86.6% 13 / 15 MC/DCmcdc 77.7% 7 / 9 Subroutinesub 100% 18 / 18 Podpod 100% 4 / 4 totaltotal 91.8% 248 / 270 CC 52 SCAR 25.8
CC
52
Cov
92%
_decode_element
21.2
_encode_item
16.8
to_xmlrpc
12.1
CRAP 13.2
↑ Summary XMLRPC/Base64.pm »
1 package Mojo::XMLRPC;
2  
3 3 ▶use Mojo::Base -strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 3 ▶use B ();
Subroutine BEGIN: called CC=1 SCAR=0.0
6 3 ▶use Mojo::ByteStream;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 3 ▶use Mojo::Date;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 3 ▶use Mojo::DOM;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 3 ▶use Mojo::JSON;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 3 ▶use Mojo::Template;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 3 ▶use Scalar::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 3 ▶use Mojo::XMLRPC::Base64;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 3 ▶use Mojo::XMLRPC::Message::Call;
Subroutine BEGIN: called CC=1 SCAR=0.0
15 3 ▶use Mojo::XMLRPC::Message::Response;
Subroutine BEGIN: called CC=1 SCAR=0.0
16  
17 3 ▶use Exporter 'import';
Subroutine BEGIN: called CC=1 SCAR=0.0
18  
19 3 our @EXPORT_OK = (qw[decode_xmlrpc encode_xmlrpc from_xmlrpc to_xmlrpc]);
20  
21 3 our $VERSION = '0.06';
22 3 $VERSION = eval $VERSION;
23  
24 3 my $message = Mojo::Template->new(
25 auto_escape => 1,
26 name => 'message',
27 namespace => __PACKAGE__,
28 )->parse(<<'TEMPLATE');
29 % my ($tag, $method, @args) = @_;
30 <?xml version="1.0" encoding="UTF-8"?>
31 <<%= $tag %>>
32 % if (defined $method) {
33 <methodName><%= $method %></methodName>
34 % }
35 % for my $arg (@args) {
36 %= $arg
37 % }
38 </<%= $tag %>>
39 TEMPLATE
40  
41 3 my $fault = Mojo::Template->new(
42 auto_escape => 1,
43 name => 'fault',
44 namespace => __PACKAGE__,
45 )->parse(<<'TEMPLATE');
46 % my ($code, $string) = @_;
47 <fault>
48 <value><struct>
49 <member>
50 <name>faultCode</name>
51 <value><int><%= $code // '' %></int></value>
52 </member>
53 <member>
54 <name>faultString</name>
55 <value><string><%= $string // '' %></string></value>
56 </member>
57 </struct></value>
58 </fault>
59 TEMPLATE
60  
61 3 my $params = Mojo::Template->new(
62 auto_escape => 1,
63 name => 'params',
64 namespace => __PACKAGE__,
65 )->parse(<<'TEMPLATE');
66 % my (@params) = @_;
67 <params>
68 % for my $param (@params) {
69 <param><value><%= $param %></value></param>
70 % }
71 </params>
72 TEMPLATE
73  
74 4 ▶sub decode_xmlrpc { from_xmlrpc(Mojo::Util::decode 'UTF-8', $_[0]) }
Subroutine decode_xmlrpc: called CC=1 SCAR=0.0
Pod documented
75  
76 4 ▶sub encode_xmlrpc { Mojo::Util::encode 'UTF-8', to_xmlrpc(@_) }
Subroutine encode_xmlrpc: called CC=1 SCAR=0.0
Pod documented
77  
78 17 ▶sub from_xmlrpc {
Subroutine from_xmlrpc: called CC=6 SCAR=18.1
Pod documented
79 17 my ($xml) = shift;
80  
81 # parse the XML document
82 17 my $dom = Mojo::DOM->new($xml);
83 17 my $msg;
84  
85 # detect the message type
86 17 my $top = $dom->children->first;
87 17 my $type = $top->tag;
88 17 ▶ if ($type eq 'methodCall') {
Branch: 2 branches
BranchTrueFalseTotal
if ($type eq 'methodCall') { } 4 13 17
elsif ($type eq 'methodResponse') { } 13 0 13
89 4 $msg = Mojo::XMLRPC::Message::Call->new;
90 4 ▶ if (defined(my $method = $top->children('methodName')->first)) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $method = $top->children("methodName")->first)) 4 0 4
91 4 $msg->method_name($method->text);
92 }
93  
94 } elsif ($type eq 'methodResponse') {
95 13 $msg = Mojo::XMLRPC::Message::Response->new;
96 13 ▶ if (defined(my $fault = $top->children('fault')->first)) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $fault = $top->children("fault")->first)) 2 11 13
97 2 return $msg->fault(_decode_element($fault));
98 }
99  
100 } else {
101 0 die 'unknown type of message';
102 }
103  
104 15 ▶ if (defined(my $params = $top->children('params')->first)) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $params = $top->children("params")->first)) 15 0 15
105 15 $msg->parameters([ map { _decode_element($_) } @{ $params->children('param') } ]);
106 }
107  
108 15 return $msg;
109 }
110  
111 41 ▶sub to_xmlrpc {
Subroutine to_xmlrpc: called CC=12 SCAR=24.9
Pod documented
112 41 my ($type, @args) = @_;
113  
114 41 ▶ if (Scalar::Util::blessed($type) && $type->isa('Mojo::XMLRPC::Message')) {
Branch: 1 branch
BranchTrueFalseTotal
if (builtin::blessed($type) and $type->isa("Mojo::XMLRPC::Message")) 3 38 41
Condition66%2/3
builtin::blessed($type) and $type->isa("Mojo::XMLRPC::Message")
!ll&&!rl&&r
3803
MC/DC50%1/2
builtin::blessed($type) and $type->isa("Mojo::XMLRPC::Message")
builtin::blessed($type) $type->isa("Mojo::XMLRPC::Message")
Truth table66%2/3
A and B
A= builtin::blessed($type)B= $type->isa("Mojo::XMLRPC::Message")
ABresult
0X0
100
111
115 3 my $obj = $type;
116 3 ▶ if ($obj->isa('Mojo::XMLRPC::Message::Call')) {
Branch: 2 branches
BranchTrueFalseTotal
if ($obj->isa('Mojo::XMLRPC::Message::Call')) { } 1 2 3
elsif ($obj->isa('Mojo::XMLRPC::Message::Response')) { } 2 0 2
117 1 $type = 'call';
118 1 @args = ($obj->method_name, @{ $obj->parameters });
119 } elsif ($obj->isa('Mojo::XMLRPC::Message::Response')) {
120 2 ▶ $type = $obj->is_fault ? 'fault' : 'response';
Branch: 1 branch
BranchTrueFalseTotal
$obj->is_fault ? : 1 1 2
121 2 ▶ @args = $obj->is_fault ? @{ $obj->fault }{qw/faultCode faultString/} : @{ $obj->parameters };
Branch: 1 branch
BranchTrueFalseTotal
$obj->is_fault ? : 1 1 2
122 } else {
123 0 die 'Message type not understood';
124 }
125 }
126  
127 41 ▶ my $tag = $type eq 'call' ? 'methodCall' : 'methodResponse';
Branch: 1 branch
BranchTrueFalseTotal
$type eq 'call' ? : 37 4 41
128 41 ▶ my $method = $type eq 'call' ? shift @args : undef;
Branch: 1 branch
BranchTrueFalseTotal
$type eq 'call' ? : 37 4 41
129  
130 my $xml =
131 $type eq 'fault' ? $fault->process(@args) :
132 41 ▶ @args ? $params->process(map { _encode_item($_) } @args) :
Branch: 2 branches
BranchTrueFalseTotal
$type eq 'fault' ? : 2 39 41
@args ? : 38 1 39
133 undef;
134  
135 41 ▶ return $message->process($tag, $method, defined($xml) ? Mojo::ByteStream->new($xml) : ());
Branch: 1 branch
BranchTrueFalseTotal
defined $xml ? : 40 1 41
136 }
137  
138 71 ▶sub _decode_element {
Subroutine _decode_element: called CC=21 SCAR=30.5
139 71 my $elem = shift;
140 71 my $tag = $elem->tag;
141  
142 71 ▶ if ($tag eq 'param' || $tag eq 'value' || $tag eq 'fault') {
Branch: 10 branches
BranchTrueFalseTotal
if ($tag eq 'param' or $tag eq 'value' or $tag eq 'fault') { } 45 26 71
elsif ($tag eq 'array') { } 1 25 26
elsif ($tag eq 'struct') { } 3 22 25
elsif ($tag eq 'int' or $tag eq 'i4') { } 9 13 22
elsif ($tag eq 'string' or $tag eq 'name') { } 5 8 13
elsif ($tag eq 'double') { } 0 8 8
elsif ($tag eq 'boolean') { } 3 5 8
elsif ($tag eq 'nil') { } 1 4 5
elsif ($tag eq 'dateTime.iso8601') { } 3 1 4
elsif ($tag eq 'base64') { } 1 0 1
Condition100%6/6
$tag eq "param" or $tag eq "value" or $tag eq "fault"
l!l&&r!l&&!r
43226
$tag eq "param" or $tag eq "value"
l!l&&r!l&&!r
152828
MC/DC100%3/3
$tag eq "param" or $tag eq "value" or $tag eq "fault"
$tag eq "param" $tag eq "value" $tag eq "fault"
Truth table100%4/4
A or B or C
A= $tag eq "param"B= $tag eq "value"C= $tag eq "fault"
ABCresult
1XX1
01X1
0011
0000
143 45 my $children = $elem->children;
144  
145 # elements with no children must be strings
146 45 ▶ return $elem->text unless @$children;
Branch: 1 branch
BranchTrueFalseTotal
unless @$children 2 43 45
147  
148 # otherwise they are another element
149 43 return _decode_element($children->first);
150  
151 } elsif ($tag eq 'array') {
152 1 my $data = $elem->children('data')->first;
153 1 return [ map { _decode_element($_) } @{ $data->children('value') } ];
154  
155 } elsif ($tag eq 'struct') {
156 return +{
157 map {;
158 6 $_->children('name')->first->text, # key
159 _decode_element($_->children('value')->first) # value
160 }
161 3 @{ $elem->children('member') } # pairs
162 };
163  
164 ▶ } elsif ($tag eq 'int' || $tag eq 'i4') {
Condition100%3/3
$tag eq "int" or $tag eq "i4"
l!l&&r!l&&!r
6313
MC/DC100%2/2
$tag eq "int" or $tag eq "i4"
$tag eq "int" $tag eq "i4"
Truth table100%3/3
A or B
A= $tag eq "int"B= $tag eq "i4"
ABresult
1X1
011
000
165 9 return $elem->text + 0;
166  
167 ▶ } elsif ($tag eq 'string' || $tag eq 'name') {
Condition66%2/3
$tag eq "string" or $tag eq "name"
l!l&&r!l&&!r
508
MC/DC50%1/2
$tag eq "string" or $tag eq "name"
$tag eq "string" $tag eq "name"
Truth table66%2/3
A or B
A= $tag eq "string"B= $tag eq "name"
ABresult
1X1
011
000
168 5 return $elem->text;
169  
170 } elsif ($tag eq 'double') {
171 0 return $elem->text / 1.0;
172  
173 } elsif ($tag eq 'boolean') {
174 3 ▶ return $elem->text ? Mojo::JSON::true : Mojo::JSON::false;
Branch: 1 branch
BranchTrueFalseTotal
$elem->text ? : 1 2 3
175  
176 } elsif ($tag eq 'nil') {
177 1 return undef;
178  
179 } elsif ($tag eq 'dateTime.iso8601') {
180 3 my $date = Mojo::Date->new($elem->text);
181 3 ▶ unless ($date->epoch) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($date->epoch) 2 1 3
182 2 require Time::Piece;
183 2 my $text = $elem->text;
184 2 PARSE: for my $time_format ('%H:%M:%S', '%H%M%S') {
185 3 for my $calendar_format ('%Y%m%d', '%Y-%m-%d') {
186 5 my $format = $calendar_format . 'T' . $time_format;
187 5 eval {
188 5 $date->epoch(Time::Piece->strptime($text, $format)->epoch);
189 };
190 5 ▶ last PARSE unless $@;
Branch: 1 branch
BranchTrueFalseTotal
unless $@ 2 3 5
191 }
192 }
193 }
194 3 return $date;
195 } elsif ($tag eq 'base64') {
196 1 return Mojo::XMLRPC::Base64->new(encoded => $elem->text);
197 }
198  
199 0 die "unknown tag: $tag";
200 }
201  
202 44 ▶sub _encode_item {
Subroutine _encode_item: called CC=16 SCAR=28.2
203 44 my $item = shift;
204 44 my $ret;
205  
206 44 ▶ if (ref $item) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $item) { } 9 35 44
207 9 ▶ if (Scalar::Util::blessed $item) {
Branch: 4 branches
BranchTrueFalseTotal
if (builtin::blessed($item)) { } 5 4 9
elsif (ref $item eq 'ARRAY') { } 1 3 4
elsif (ref $item eq 'HASH') { } 1 2 3
elsif (ref $item eq 'SCALAR') { } 2 0 2
208 5 ▶ if ($item->can('TO_XMLRPC')) {
Branch: 5 branches
BranchTrueFalseTotal
if ($item->can('TO_XMLRPC')) { } 0 5 5
elsif ($item->isa('JSON::PP::Boolean')) { } 2 3 5
elsif ($item->isa('Mojo::Date')) { } 1 2 3
elsif ($item->isa('Mojo::XMLRPC::Base64')) { } 2 0 2
elsif ($item->can('TO_JSON')) { } 0 0 0
209 0 return _encode_item($item->TO_XMLRPC);
210  
211 } elsif ($item->isa('JSON::PP::Boolean')) {
212 2 ▶ my $val = $item ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$item ? : 1 1 2
213 2 $ret = "<boolean>$val</boolean>";
214  
215 } elsif ($item->isa('Mojo::Date')) {
216 1 my $date = $item->to_datetime;
217 1 $ret = "<dateTime.iso8601>$date</dateTime.iso8601>";
218  
219 } elsif ($item->isa('Mojo::XMLRPC::Base64')) {
220 2 $ret = "<base64>$item</base64>";
221  
222 } elsif ($item->can('TO_JSON')) {
223 0 return _encode_item($item->TO_JSON);
224  
225 } else {
226 0 return _encode_item("$item");
227 }
228 } elsif (ref $item eq 'ARRAY') {
229 1 $ret = join '', map { '<value>' . _encode_item($_) . '</value>' } @$item;
230 1 $ret = "<array><data>$ret</data></array>";
231  
232 } elsif (ref $item eq 'HASH') {
233 $ret = join '', map {
234 1 my $name = Mojo::Util::xml_escape($_);
235 2 "<member><name>$name</name><value>" . _encode_item($item->{$_}) . '</value></member>';
236 } keys %$item;
237 1 $ret = "<struct>$ret</struct>";
238  
239 } elsif (ref $item eq 'SCALAR') {
240 2 ▶ my $val = $$item ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$$item ? : 1 1 2
241 2 $ret = "<boolean>$val</boolean>";
242 }
243 }
244 else {
245 35 my $sv = B::svref_2object(\$item);
246  
247 35 ▶ $ret =
Branch: 3 branches
BranchTrueFalseTotal
!defined($item) ? : 1 34 35
$sv->FLAGS & 512 ? : 4 30 34
$sv->FLAGS & 256 ? : 9 21 30
248 !defined $item ? '<nil/>' :
249 $sv->FLAGS & B::SVf_NOK ? "<double>$item</double>" :
250 $sv->FLAGS & B::SVf_IOK ? "<int>$item</int>" :
251 '<string>' . Mojo::Util::xml_escape($item) . '</string>';
252 }
253  
254 44 return Mojo::ByteStream->new($ret);
255 }
256  
257 3 1;
258  
259 =encoding utf8
260  
261 =head1 NAME
262  
263 Mojo::XMLRPC - An XMLRPC message parser/encoder using the Mojo stack
264  
265 =head1 SYNOPSIS
266  
267 use Mojo::UserAgent;
268 use Mojo::XMLRPC qw[to_xmlrpc from_xmlrpc];
269  
270 my $ua = Mojo::UserAgent->new;
271 my $url = ...;
272 my $tx = $ua->post($url, encode_xmlrpc(call => 'mymethod', 'myarg'));
273 my $res = decode_xmlrpc($tx->res->body)
274  
275 =head1 DESCRIPTION
276  
277 L<Mojo::XMLRPC> is a pure-perl XML-RPC message parser and encoder.
278 It uses tools from the L<Mojo> toolkit to do all of the work.
279  
280 This does not mean that it must only be used in conjunction with a L<Mojolicious> app, far from it.
281 Feel free to use it in any circumstance that needs XML-RPC messages.
282  
283 =head1 MAPPING
284  
285 The mapping between Perl types and XMLRPC types is not perfectly one-to-one, especially given Perl's scalar types.
286 The following is a description of the procedure used to encode and decode XMLRPC message from/to Perl.
287  
288 =head2 Perl to XMLRPC
289  
290 If the item is a blessed reference:
291  
292 =over
293  
294 =item *
295  
296 If the item/object implements a C<TO_XMLRPC> method, it is called and the result is encoded.
297  
298 =item *
299  
300 If the item is a L<JSON::PP::Boolean>, as the L<Mojo::JSON> booleans are, it is encoded as a C<boolean>.
301  
302 =item *
303  
304 If the item is a L<Mojo::Date> then it is encoded as a C<dateTime.iso8601>.
305  
306 =item *
307  
308 If the item is a L<Mojo::XMLRPC::Base64> then it is encode as a C<base64>.
309 This wrapper class is used to distinguish a string from a base64 and aid in encoding/decoding.
310  
311 =item
312  
313 If the item/object implements a C<TO_JSON> method, it is called and the result is encoded.
314  
315 =item
316  
317 If none of the above cases are true, the item is stringified and encoded as a C<string>.
318  
319 =back
320  
321 If the item is an unblessed reference:
322  
323 =over
324  
325 =item *
326  
327 An array reference is encoded as an C<array>.
328  
329 =item *
330  
331 A hash reference is encoded as a C<struct>.
332  
333 =item *
334  
335 A scalar reference is encoded as a C<boolean> depending on the truthiness of the referenced value.
336 This is the standard shortcut seen in JSON modules allowing C<\1> for true and C<\0> for false.
337  
338 =back
339  
340 If the item is a non-reference scalar:
341  
342 =over
343  
344 =item *
345  
346 If the item is undefined it is encoded as C<< <nil/> >>.
347  
348 =item *
349  
350 If the item has C<NOK> (it has been used as a floating point number) it is encoded as C<double>.
351  
352 =item *
353  
354 If the item has C<IOK> (it has been used as an integer (and not a float)) it is encoded as an C<int>.
355  
356 =item *
357  
358 All other values are encoded as C<string>.
359  
360 =back
361  
362 =head2 XMLRPC to Perl
363  
364 Most values decode back into Perl in a manner that would survive a round trip.
365 The exceptions are blessed objects that implement C<TO_XMLRPC> or C<TO_JSON> or are stringified.
366 The shortcuts for booleans will round-trip to being L<Mojo::JSON> booleans objects.
367  
368 Values encoded as integers will not be truncated via C<int> however no attempt is made to upgrade them to C<IOK> or C<NOK>.
369 Values encoded as floating point C<double> will be forcably upgraded to C<NOK> (by dividing by 1.0).
370 This is so that an integer value encoded as a floating point will round trip, the reverse case isn't as useful and thus isn't handled.
371  
372 =head1 FUNCTIONS
373  
374 =head2 decode_xmlrpc
375  
376 Like L</from_xmlrpc> but first decodes from UTF-8 encoded bytes.
377  
378 =head2 encode_xmlrpc
379  
380 Like L</to_xmlrpc> but encodes the result to UTF-8 encoded bytes.
381  
382 =head2 from_xmlrpc
383  
384 Takes a character string, interprets it, and returns a L<Mojo::XMLRPC::Message> containing the result.
385 If the input is UTF-8 encoded bytes, you can use L</decode_xmlrpc> instead.
386  
387 =head2 to_xmlrpc
388  
389 Generates an XMLRPC message from data passed to the function.
390 The input may be a L<Mojo::XMLRPC::Message> or it could be of the following form.
391  
392 =over
393  
394 =item *
395  
396 A message type, one of C<call>, C<response>, C<fault>.
397  
398 =item *
399  
400 If the message type is C<call>, then the method name.
401  
402 =item *
403  
404 If the message is not a C<fault>, then all remaining arguments are parameters.
405 If the message is a C<fault>, then the fault code followed by the fault string, all remaining arguments are ignored.
406  
407 =back
408  
409 The return value is a character string.
410 To generate UTF-8 encoded bytes, you can use L</encode_xmlrpc> instead.
411  
412 =head1 THANKS
413  
414 This module was inspired by L<XMLRPC::Fast> written by Sébastien Aperghis-Tramoni.
415  
416 L<Mojo::XMLRPC> was a port of that module initially to use the L<Mojo::DOM> module rather than L<XML::Parser>.
417 By the time port to the Mojo stack was complete, the module was entirely rewritten.
418 That said, the algorithm still owes a debt of gratitude to that one.
419  
420 =head1 SOURCE REPOSITORY
421  
422 L<http://github.com/jberger/Mojo-XMLRPC>
423  
424 =head1 AUTHOR
425  
426 Joel Berger, E<lt>joel.a.berger@gmail.comE<gt>
427  
428 =head1 CONTRIBUTORS
429  
430 Andreas Vögele (voegelas)
431  
432 =head1 COPYRIGHT AND LICENSE
433  
434 Copyright (C) 2017 by L</AUTHOR> and L</CONTRIBUTORS>
435 This library is free software; you can redistribute it and/or modify
436 it under the same terms as Perl itself.
↑ Summary XMLRPC/Base64.pm »