XML::RPC::Enc(3pm)

💖 XML::RPC::Enc 💖

okay bestie, gather round, because we're talking about XML::RPC::Enc(3pm) — a User Contributed Perl Documentation page, no cap. This is the base class for XML::RPC encoders. It's the blueprint, the template, the main character that the actual encoder modules (hi XML::RPC::Enc::LibXML) take after. It doesn't do the encoding itself, it just tells you what your encoder has to do. it's giving "abstract parent energy" and we respect it. 🫶

---

✨ SYNOPSIS ✨

Generic usage, bestie, look at this:

use XML::RPC::Fast;

my $server = XML::RPC::Fast->new( undef, encoder => XML::RPC::Enc::LibXML->new );
my $client = XML::RPC::Fast->new( $uri, encoder => XML::RPC::Enc::LibXML->new );

so you're spinning up a server with undef as the uri and a client with an actual $uri, and both of them get handed an encoder. iconic. 🌸

---

🛠️ METHODS 🛠️

The following methods should be implemented. yes bestie, should — this is the base class, she's delegating, that's her whole thing. 💅

🌟 new (%args)

Should support arguments:

• internal_encoding [ = undef ] — Internal encoding. undef means wide perl characters (perl-5.8.1+). so like, if you leave it undefined you're getting the wide characters treatment. 🦋
• external_encoding [ = utf-8 ] — External encoding. Which encoding to use in composed XML. default is utf-8, obviously, she stays consistent. ✨

📨 request ($method, @args) : xml byte-stream, [ new call url ]

Encode request into XML. you give it a method name and args, it hands you back an xml byte-stream, and it may also hand you back a new call url. multi-tasking queen. 👑

📬 response (@args) : xml byte-stream

Encode response into XML. that's it, that's the job. simple, clean, no drama. 💅

💀 fault ($faultcode, $faultstring) : xml byte-stream

Encode fault into XML. when things go wrong (and bestie, sometimes they do 😭), this is what packages up the $faultcode and $faultstring into a cute lil xml byte-stream.

🎀 registerClass ($class_name,$encoder_cb)

Register encoders for custom Perl types. okay so this is where it gets fun, you're teaching the encoder how to handle your weird little objects.

Encoders description:

# Generic:
$simple_encoder_cb = sub {
    my $object = shift;
    # ...
    return type => $string;
};

# Encoder-dependent (XML::RPC::Enc::LibXML)
$complex_encoder_cb = sub {
    my $object = shift;
    # ...
    return XML::LibXML::Node;
};

so the generic one returns type => $string, and the encoder-dependent one (looking at you, XML::RPC::Enc::LibXML) returns an XML::LibXML::Node. two different vibes, both valid. 🌈

Samples:

$enc->registerClass( DateTime => sub {
    return ( 'dateTime.iso8601' => $_[0]->strftime('%Y%m%dT%H%M%S.%3N%z') );
});

# Encoder-dependent (XML::RPC::Enc::LibXML)
$enc->registerClass( DateTime => sub {
    my $node = XML::LibXML::Element->new('dateTime.iso8601');
    $node->appendText($_[0]->strftime('%Y%m%dT%H%M%S.%3N%z'));
    return $node;
});

see how DateTime gets its own little custom handler both ways? obsessed. the second one literally builds the XML::LibXML::Element node and appendTexts the formatted string. that's the %Y%m%dT%H%M%S.%3N%z format btw, in case you were squinting. 🔥

🔍 decode ($xml) : $methodname, @args

Decode request xml. you feed it xml, it gives you back the method name and the args. reverse uno card. 🃏

🔍 decode ($xml) : @args

Decode response xml. feed it xml, get the args back. same method name, different return shape, iykyk. 💜

🔍 decode ($xml) : { fault => { faultCode => ..., faultString => ... } }

Decode fault xml. this time you get a hashref situation: a fault key wrapping faultCode and faultString. sad girl hours but make it structured. 😭

🧚 registerType ($xmlrpc_type,$decoder_cb)

Register decoders for XML-RPC types.

$decoder_cb is depends on encoder implementation. (yes bestie, the grammar is giving chaos, but the meaning is clear: your callback's shape depends on which encoder you're running. 💀)

Samples for XML::RPC::Enc::LibXML:

$enc->registerType( base64 => sub {
    my $node = shift;
    return MIME::Base64::decode($node->textContent);
});

$enc->registerType( 'dateTime.iso8601' => sub {
    my $node = shift;
    return DateTime::Format::ISO8601->parse_datetime($node->textContent);
});

base64 gets MIME::Base64::decoded, 'dateTime.iso8601' gets parsed into a real DateTime via DateTime::Format::ISO8601->parse_datetime. both of them just pulling $node->textContent and doing their lil transformation. slay. ⭐

---

📜 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.

so yeah, same terms as Perl itself, go wild (responsibly). 🌸

---

👑 AUTHOR 👑

Mons Anderson, "<mons@cpan.org>". legend behaviour, honestly. 💖

---

and that's the whole page bestie!! no notes, we ate. 🍓

this was perl v5.34.0, dated 2022-06-28, and the page is XML::RPC::Enc(3pm) — k byeeee 💅✨