XML::F...:Buffer(3pm)

💖 XML::Filter::Sort::Buffer 💖

okay so bestie, welcome to the manual page for XML::Filter::Sort::Buffer — it's part of the User Contributed Perl Documentation, and yes it's giving "internal plumbing that you should absolutely not touch unless you're a specific kind of nerd." 🫶

---

✨ NAME ✨

XML::Filter::Sort::Buffer — the implementation class that XML::Filter::Sort is out here using behind the scenes. It's the little worker bee. 🐝

---

🌸 DESCRIPTION 🌸

ngl, this doc is for developers — specifically the ones who wanna extend this class or straight up replace it. If you're just a normal person trying to use this stuff, go read XML::Filter::Sort instead, that's your main character page. 💅

And if you want the big-picture tea on how the buffering classes and methods all fit together, that lives in XML::Filter::Sort::BufferMgr. 🦋

---

🎀 BUFFER LIFE CYCLE 🎀

okay so here's the whole arc of a buffer's life, it's honestly a whole coming-of-age story:

A XML::Filter::Sort::Buffer object gets created by a XML::Filter::Sort::BufferMgr object, using the new() method. Birth. ✨

Then the XML::Filter::Sort object propagates any SAX events it receives over to the buffer object, and it keeps doing that until the end of the record is reached. Every time an element gets added to the buffer, its contents get compared against the sort key paths, and boom — the sort key values get extracted. 🔍

When the end of the record hits, the close() method gets called. The return value from that method? It's the list of sort keys. That's the whole payoff. 👑

The buffer manager then holds onto that buffer until the end of the record sequence is reached. Then it retrieves each buffer in order of the sort key values, and calls the buffer's to_sax() method to send all the buffered events downstream to the handler. 📬

After the call to to_sax(), the buffer is discarded. And no, there is no destructor method — everything is handled by Perl's garbage collector. Let the GC cook. 🗑️✨

---

🦋 DATA STRUCTURES 🦋

So the buffer contains a 'tree' of SAX events. And "tree" here is lowkey just an array of 'nodes'. Text nodes? They're represented as scalars. Every other node? Represented as arrayrefs. The first element of a node array is a single character that identifies the node type:

e - element
c - comment
p - processing instruction

The second element is the node data — that's the hash from the original SAX event. And the child nodes of an element node are represented by the third element, as an arrayref. 💜

For example, this XML:

<person age="27">
  <lastname>smith</lastname>
</person>

Would be buffered as this data structure:

[
  [
    'e',
    {
      'Name' => 'person'
      'Prefix' => '',
      'LocalName' => 'person',
      'NamespaceURI' => '',
      'Attributes' => {
        '{}age' => {
          'LocalName' => 'age',
          'NamespaceURI' => '',
          'Value' => '27',
          'Prefix' => '',
          'Name' => 'age'
        }
      },
    },
    [
      "\n  ",
      [
        'e',
        {
          'Name' => 'lastname'
          'Prefix' => '',
          'LocalName' => 'lastname',
          'NamespaceURI' => '',
          'Attributes' => {},
        },
        [
          'smith'
        ]
      ],
      "\n  ",
    ]
  ]
]

Like… it's giving nested arrayrefs all the way down, and honestly? Iconic. 🌈

---

👑 COPYRIGHT 👑

Copyright 2002 Grant McLean <grantm@cpan.org>

This library 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, we ate and left no crumbs 💅 this was pulled from perl v5.26.1, dated 2018-03-30, under the XML::Filter::Sort::Buffer(3pm) name. mwah, go forth and buffer responsibly 🎀💖✨