POE::F...::Node(3pm)

💖 POE::F...::Node — the manual, but make it make sense 💖

okay bestie, so this is the POE::Filter::XML::Node page from the User Contributed Perl Documentation section (3pm, she's a Perl module, she's iconic, she's giving). Let's get into it ✨

---

✨ NAME ✨

POE::Filter::XML::Node — it's a XML::LibXML::Element subclass that adds streaming semantics on top. like, the Element you know and love, but she streams now 🦋

---

🎀 VERSION 🎀

version 1.140700

---

🌸 SYNOPSIS 🌸

bestie here's the whole vibe in code, no notes:

use POE::Filter::XML::Node;

my $node = POE::Filter::XML::Node->new('iq');

$node->setAttributes(
    ['to', 'foo@other',
    'from', 'bar@other',
    'type', 'get']
);

my $query = $node->addNewChild('jabber:iq:foo', 'query');

$query->appendTextChild('foo_tag', 'bar');

say $node->toString();

--

(newlines and tabs for example only)

<iq to='foo@other' from='bar@other' type='get'>
    <query xmlns='jabber:iq:foo'>
        <foo_tag>bar</foo_tag>
    </query>
</iq>

ok so quick heads up: the newlines and tabs up there are for example only, don't come for me 🙈

---

💅 DESCRIPTION 💅

POE::Filter::XML::Node is a XML::LibXML::Element subclass whose whole thing is that she provides a few extra convenience methods AND some light integration into a streaming context. lowkey a glow-up of an Element.

and like — the way this module can be used to create arbitrarily complex XML data structures that know how to stringify themselves?? main character energy fr fr. she doesn't need you to hold her hand, she just toStrings herself 💁‍♀️

---

👑 PUBLIC_ATTRIBUTES 👑

🌈 stream_[start|end] 🌈

is: ro, isa: Bool, default: false

these two attributes define behaviors for toString() on the node. no cap:

• stream_start — drops all the children and just leaves the tag unterminated. like eg. <start>. she's open-ended, she's mysterious 💫
• stream_end — drops any children and treats the tag like a terminator. like eg. </end>. closing the chapter, periodt.

each attribute also has a private writer — '_set_stream_[start|end]' — in case it's necessary to manipulate these attributes post construction. iykyk 🔥

---

⭐ PUBLIC_METHODS ⭐

🦋 override cloneNode 🦋

(Bool $deep)

cloneNode is overridden so that it carries forward the stream_[end|start] attributes. she clones and she remembers who she is, we love a self-aware queen 👑

🍓 override toString 🍓

(Bool $formatted)

toString was overridden to provide special stringification semantics for when stream_start or stream_end are boolean true. that's it, that's the override ✨

💜 setAttributes 💜

(ArrayRef $array_of_tuples)

setAttributes() accepts a single argument: an array reference. basically you pair up all the attributes you want to be into the node (ie. [attrib, value]) and this method will process them using setAttribute(). it's just a convenience method, she's doing you a solid 🫶

and here's the lil special case — if one of the attributes is 'xmlns', then setNamespace() will be called with the value used as the $nsURI argument, with no prefix, and not activated. so:

 eg.
 ['xmlns', 'http://foo']
        |
        V
 setNamespace($value, '', 0)
        |
        V
 <node xmlns="http://foo"/>

like. she just handles it. iconic 🎀

🧚 getAttributes 🧚

returns (HashRef)

this method returns all of the attribute nodes on the Element — filtering out namespace declarations — as a HashRef. clean, filtered, no clutter 💅

🌟 getFirstChildByTagName(Str $name) 🌟

returns (Maybe[POE::Filter::XML::Node])

this is a convenience method that basically does:

(getChildrenByTagName($name))[0]

first one, no scrolling. we love efficiency 🔥

💖 getChildrenHash 💖

returns (HashRef)

getChildrenHash() returns a hash reference to all the children of that node. each key in the hash is a node name, and each value is an array reference with all of the children with that name. organized. grouped. slay 🧚‍♀️

---

🌈 AUTHOR 🌈

Nicholas R. Perez <nperez@cpan.org>

---

🎀 COPYRIGHT AND LICENSE 🎀

this software is copyright (c) 2014 by Nicholas R. Perez <nperez@cpan.org>.

it's free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. free as in bestie, go off 💖

---

and that's the whole page, babe. no skips, no cuts, every detail intact ✨

okay so that's it — page brought to you by perl v5.34.0, dated 2022-06-17, filed under POE::F...::Node(3pm). go forth and stream your XML, queen 👑💅🌸