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

✨ NAME ✨

okay so bestie, welcome to POE::Filter::XML::Handler — it's the default SAX Handler for POE::Filter::XML, and it lives in the User Contributed Perl Documentation section of the manual, page POE::F...Handler(3pm). yes the title is abbreviated, the man page author said "iykyk" 💅

🌸 VERSION 🌸

this one's rockin' version 1.140700 ✨

---

🦋 DESCRIPTION 🦋

POE::Filter::XML::Handler is, like, the default SAX handler for POE::Filter::XML. no cap. it extends XML::SAX::Base so it can serve up different semantics for streaming vs. non-streaming contexts — because those two situations are not the same vibe at all, bestie 😭

and by default? this handler builds POE::Filter::XML::Nodes. that's its whole thing. iconic behavior honestly 👑

---

💖 PUBLIC_ATTRIBUTES 💖

⭐ not_streaming ⭐

is: ro, isa: Bool, default: false

not_streaming is the little switch that decides how the opening tag gets treated when it's parsed, and it's giving very main character energy:

• if what you're parsing is not a stream, the whole document gets parsed in full, and then it's placed into the finished_nodes attribute.
• otherwise (so, streaming mode, the default), the opening tag gets placed immediately into the finished_nodes bucket. immediately immediately. no waiting 🫶

---

🎀 PRIVATE_ATTRIBUTES 🎀

💜 current_node 💜

is: rw, isa: POE::Filter::XML::Node

current_node is just, like, holding the node that's being immediately parsed right now. it's the one on deck, the one in the spotlight, the one going through it at this exact moment 🙈

🌈 finished_nodes 🌈

is: ro, isa: ArrayRef, traits: Array

finished_nodes holds all the nodes that have been completely parsed — the done ones, the graduated ones, the ones that ate and left no crumbs ✨

you get at this attribute through these methods:

handles =>
{
    all_finished_nodes => 'elements',
    has_finished_nodes => 'count',
    add_finished_node => 'push',
    get_finished_node => 'shift',
}

🧚 depth_stack 🧚

is: ro, isa: ArrayRef, traits: Array

depth_stack is holding the operating stack for the parsed nodes. as nodes get processed, the ancendants of the current node get stored in the stack (yes, the original says "ancendants", we're keeping it exactly as-is, bestie, that's the canon spelling here 💀). when they're done, they get popped right off the stack. bye!

you reach this attribute through these methods:

handles =>
{
    push_depth_stack => 'push',
    pop_depth_stack => 'pop',
    depth => 'count',
}

---

🔥 PUBLIC_METHODS 🔥

🍓 reset 🍓

reset will clear:

• the current node
• the finished nodes
• and the depth stack

that's it. full factory reset of the internal vibe check. so clean 💅

---

👑 PROTECTED_METHODS 👑

🌸 override start_element 🌸

(HashRef $data)

start_element is overridden from the XML::SAX::Base class so we can get our custom behavior for dealing with streaming vs. non-streaming data.

what it does, step by step:

• it builds Nodes, then attaches them either to the root node (that's the non-streaming case) or as stand-alone top level fragments (that's the streaming case)
• then it sets them to be the current node
• children nodes are appended to their parents before getting set as the current node — order matters, bestie, don't skip that part
• and then the base class method gets called via super()

periodt. 🫶

💀 override end_element 💀

(HashRef $data)

end_element is also overridden from XML::SAX::Base, again for that streaming vs. non-streaming custom behavior. mostly this method is in charge of stack management when the depth of the stack reaches certain points.

here's the tea:

• in streaming documents, this means top level fragments (not root!) get popped off the stack and added to the finished_nodes collection.
• otherwise, a Node is created with stream_end set, and added to the finished nodes.

and then the base class method is called via super() ✨

🦋 override characters 🦋

(HashRef $data)

characters merely applies the character data as text to the current node being processed. that's the whole job. then it calls the base class method via super(). lowkey the most chill method in the whole file 🌈

---

💖 AUTHOR 💖

Nicholas R. Perez <nperez@cpan.org>

---

🎀 COPYRIGHT AND LICENSE 🎀

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

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

---

okay and for the cute sign-off: this page was generated by perl v5.34.0 on 2022-06-17, filed under POE::F...Handler(3pm) in the User Contributed Perl Documentation. go forth and parse, bestie, you got this 💅✨🫶