/ 
Mojo-XMLRPC-0.06
River stage zero No dependents
/ Mojo::XMLRPC

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 <nil/>.

  • 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, <joel.a.berger@gmail.com>

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.