NAME
Mojo::XMLRPC - An XMLRPC message parser/encoder using the Mojo stack
SYNOPSIS
use Mojo::UserAgent;
use Mojo::XMLRPC qw[to_xmlrpc from_xmlrpc];
my $ua = Mojo::UserAgent->new;
my $url = ...;
my $tx = $ua->post($url, encode_xmlrpc(call => 'mymethod', 'myarg'));
my $res = decode_xmlrpc($tx->res->body)
DESCRIPTION
Mojo::XMLRPC is a pure-perl XML-RPC message parser and encoder. It uses
tools from the Mojo toolkit to do all of the work.
This does not mean that it must only be used in conjunction with a
Mojolicious app, far from it. Feel free to use it in any circumstance
that needs XML-RPC messages.
MAPPING
The mapping between Perl types and XMLRPC types is not perfectly
one-to-one, especially given Perl's scalar types. The following is a
description of the procedure used to encode and decode XMLRPC message
from/to Perl.
Perl to XMLRPC
If the item is a blessed reference:
* If the item/object implements a TO_XMLRPC method, it is called and
the result is encoded.
* If the item is a JSON::PP::Boolean, as the Mojo::JSON booleans are,
it is encoded as a boolean.
* If the item is a Mojo::Date then it is encoded as a
dateTime.iso8601.
* If the item is a Mojo::XMLRPC::Base64 then it is encode as a
base64. This wrapper class is used to distinguish a string from a
base64 and aid in encoding/decoding.
* If the item/object implements a TO_JSON method, it is called and
the result is encoded.
* If none of the above cases are true, the item is stringified and
encoded as a string.
If the item is an unblessed reference:
* An array reference is encoded as an array.
* A hash reference is encoded as a struct.
* A scalar reference is encoded as a boolean depending on the
truthiness of the referenced value. This is the standard shortcut
seen in JSON modules allowing \1 for true and \0 for false.
If the item is a non-reference scalar:
* If the item is undefined it is encoded as .
* If the item has NOK (it has been used as a floating point number)
it is encoded as double.
* If the item has IOK (it has been used as an integer (and not a
float)) it is encoded as an int.
* All other values are encoded as string.
XMLRPC to Perl
Most values decode back into Perl in a manner that would survive a
round trip. The exceptions are blessed objects that implement TO_XMLRPC
or TO_JSON or are stringified. The shortcuts for booleans will
round-trip to being Mojo::JSON booleans objects.
Values encoded as integers will not be truncated via int however no
attempt is made to upgrade them to IOK or NOK. Values encoded as
floating point double will be forcably upgraded to NOK (by dividing by
1.0). 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.
FUNCTIONS
decode_xmlrpc
Like "from_xmlrpc" but first decodes from UTF-8 encoded bytes.
encode_xmlrpc
Like "to_xmlrpc" but encodes the result to UTF-8 encoded bytes.
from_xmlrpc
Takes a character string, interprets it, and returns a
Mojo::XMLRPC::Message containing the result. If the input is UTF-8
encoded bytes, you can use "decode_xmlrpc" instead.
to_xmlrpc
Generates an XMLRPC message from data passed to the function. The input
may be a Mojo::XMLRPC::Message or it could be of the following form.
* A message type, one of call, response, fault.
* If the message type is call, then the method name.
* If the message is not a fault, then all remaining arguments are
parameters. If the message is a fault, then the fault code followed
by the fault string, all remaining arguments are ignored.
The return value is a character string. To generate UTF-8 encoded
bytes, you can use "encode_xmlrpc" instead.
THANKS
This module was inspired by XMLRPC::Fast written by Sébastien
Aperghis-Tramoni.
Mojo::XMLRPC was a port of that module initially to use the Mojo::DOM
module rather than XML::Parser. By the time port to the Mojo stack was
complete, the module was entirely rewritten. That said, the algorithm
still owes a debt of gratitude to that one.
SOURCE REPOSITORY
http://github.com/jberger/Mojo-XMLRPC
AUTHOR
Joel Berger,
CONTRIBUTORS
Andreas Vögele (voegelas)
COPYRIGHT AND LICENSE
Copyright (C) 2017 by "AUTHOR" and "CONTRIBUTORS" This library is free
software; you can redistribute it and/or modify it under the same terms
as Perl itself.