README(3pm)

💖 NAME 💖

XML::RPC::Fast — a fast and modular implementation for an XML-RPC client and server. that's the whole vibe bestie, client AND server, one module, no cap. 🦋✨

---

✨ SYNOPSIS ✨

🫶 Generic usage

use XML::RPC::Fast;

my $server = XML::RPC::Fast->new( undef, %args );
my $client = XML::RPC::Fast->new( $uri,  %args );

okay so like — you hand it undef for the url and it's giving server, you hand it a real $uri and it's giving client. that's it. that's the whole personality test. 💅

🌸 Create a simple XML-RPC service

use XML::RPC::Fast;

my $rpc = XML::RPC::Fast->new(
    undef,                         # the url is not required by server
    external_encoding => 'koi8-r', # any encoding, accepted by Encode
    #internal_encoding => 'koi8-r', # not supported for now
);
my $xml = do { local $/; <STDIN> };
length($xml) == $ENV{CONTENT_LENGTH} or warn "Content-Length differs from actually received";

print "Content-type: text/xml; charset=$rpc->{external_encoding}\n\n";
print $rpc->receive( $xml, sub {
    my ( $methodname, @params ) = @_;
    return { you_called => $methodname, with_params => \@params };
} );

not the # the url is not required by server comment doing the most 💀 anyway — external_encoding => 'koi8-r' can be any encoding, accepted by Encode, and yeah #internal_encoding => 'koi8-r' is commented out because it's not supported for now, don't come for me.

🎀 Make a call to an XML-RPC service

use XML::RPC::Fast;

my $rpc = XML::RPC::Fast->new(
    'http://your.hostname/rpc/url'
);

# Syncronous call
my @result = $rpc->req(
    call => [ 'examples.getStateStruct', { state1 => 12, state2 => 28 } ],
    url => 'http://...',
);

# Syncronous call (compatibility method)
my @result = $rpc->call( 'examples.getStateStruct', { state1 => 12, state2 => 28 } );

# Syncronous or asyncronous call
$rpc->req(
    call => ['examples.getStateStruct', { state1 => 12, state2 => 28 }],
    cb   => sub {
        my @result = @_;
    },
);

# Syncronous or asyncronous call (compatibility method)
$rpc->call( sub {
    my @result = @_;

}, 'examples.getStateStruct', { state1 => 12, state2 => 28 } );

four ways to say the same thing, and honestly? each one ate. 🔥

---

💅 DESCRIPTION 💅

XML::RPC::Fast is format-compatible with XML::RPC, but lowkey it may use different encoders to parse/compose xml. the encoder that's included rn uses XML::LibXML, and it is 3 times faster than XML::RPC and 75% faster, than XML::Parser implementation. yes we're bragging, and yes it's earned. 👑

---

🌈 METHODS 🌈

new ($url, %args)

creates the XML::RPC::Fast object. it's a server if url is undef, and a client if url is defined. the url literally decides its whole main character energy.

req( %ARGS )

Clientside. makes a syncronous or asyncronous call — which one depends on the UA, not on you, so vibe check your UA first bestie.

• if you have cb, it will invoke $cb with results and should not croak. very chill of it.
• if you have no cb, it will return results and croak on error — but only for a syncronous UA. sorry not sorry.

the arguments are:

call => [ methodName => @args ]

array ref of call arguments. Required. no call, no call, periodt. 🫶

cb => $cb->(@results)

invocation callback. Optional for syncronous UA. behaviour is same as in call with $cb and without. iykyk.

url => $request_url

alternative invocation URL. Optional. by default will be used defined from constructor.

headers => { http-headers hashref }

additional http headers to request. bring your own ✨

external_encoding => '...,

specify the encoding, used inside XML container just for this request. passed to encoder.

call( 'method_name', @arguments ) : @results

Clientside. make a syncronous call and return results. croaks on error. just a simple wrapper around req. it's giving delegate. 💅

call( $cb->(@res), 'method_name', @arguments ): void

Clientside. make a syncronous or asyncronous call (depends on UA) and invoke $cb with results. should not croak. just a simple wrapper around req. same wrapper, different fit. 🎀

receive ( $xml, $handler->($methodName,@args) ) : xml byte-stream

Serverside.</pulse> — wait, Serverside. process received XML and invoke $handler with parameters $methodName and @args and returns response XML. it's the full circle moment. 🌸

on error conditions $handler could set $XML::RPC::Fast::faultCode and die, or return "rpcfault($faultCode,$faultString)".

->receive( $xml, sub {
    # ...
    return rpcfault( 3, "Some error" ) if $error_condition
    $XML::RPC::Fast::faultCode = 4 and die "Another error" if $another_error_condition;

    return { call => $methodname, params => \@params };
})

two ways to fail and both are valid. so real. 😭

registerType

proxy-method to encoder. see XML::RPC::Enc.

registerClass

proxy-method to encoder. see XML::RPC::Enc.

---

✨ OPTIONS ✨

below is the options, accepted by new() — yes, all of them, we're not skipping any, that would be rude to the options.

ua

Client only. useragent object, or package name.

->new( $url, ua => 'LWP' ) # same as XML::RPC::UA::LWP
# or
->new( $url, ua => 'XML::RPC::UA::LWP' )
# or
->new( $url, ua => XML::RPC::UA::LWP->new( ... ) )
# or
->new( $url, ua => XML::RPC::UA::Curl->new( ... ) )

timeout

Client only. timeout for calls. passed directly to UA.

->new( $url, ua => 'LWP', timeout => 10 )

useragent

Client only. useragent string. passed directly to UA.

->new( $url, ua => 'LWP', useragent => 'YourClient/1.11' )

encoder

Client and server. encoder object or package name.

->new( $url, encoder => 'LibXML' )
# or
->new( $url, encoder => 'XML::RPC::Enc::LibXML' )
# or
->new( $url, encoder => XML::RPC::Enc::LibXML->new( ... ) )

internal_encoding NOT IMPLEMENTED YET

specify the encoding you are using in your code. by default the option is undef, which means flagged utf-8. for translations is used Encode, so the list of accepted encodings is fully derived from it. so like — the menu is Encode's menu, we're just the waiter. 🙈

external_encoding

specify the encoding, used inside XML container. by default it's utf-8. passed directly to encoder.

->new( $url, encoder => 'LibXML', external_encoding => 'koi8-r' )

---

💜 ACCESSORS 💜

url

get or set client url.

encoder

direct access to encoder object.

ua

direct access to useragent object.

---

🦋 FUNCTIONS 🦋

rpcfault(faultCode, faultString)

returns hash structure, that may be returned by serverside handler, instead of die. not exported by default — you gotta ask for it, it doesn't just show up uninvited. 💅

---

🎀 CUSTOM TYPES 🎀

sub {{ 'base64' => encode_base64($data) }}

when passing a CODEREF as a value, encoder will simply use the returned hashref as a type => value pair.

bless( do{\(my $o = encode_base64('test') )}, 'base64' )

when passing SCALARREF as a value, package name will be taken as type and dereference as a value.

bless( do{\(my $o = { something =>'complex' } )}, 'base64' )

when passing REFREF as a value, package name will be taken as type and XML::Hash::LX"::hash2xml(deref)" would be used as value.

customtype( $type, $data )

easily compose SCALARREF based custom type. quick, easy, iconic. ✨

---

🌈 BUGS & SUPPORT 🌈

bugs reports and testcases are welcome. we love a contributor moment. 🫶

if you write your own Enc or UA, I may include it into distribution. fr fr.

if you have propositions for default custom types (see Enc), send me patches. 👑

see <http://rt.cpan.org> to report and view bugs.

---

👑 AUTHOR 👑

Mons Anderson, "<mons@cpan.org>"

---

💖 COPYRIGHT & LICENSE 💖

Copyright (c) 2008-2009 Mons Anderson.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page bestie 💅 this README(3pm) shipped as part of the User Contributed Perl Documentation for perl v5.20.2, dated 2012-01-25. a whole vintage icon and it still ate. mwah. 💋✨