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

💖 XML::Filter::Sort::BufferMgr 💖

okay bestie, welcome to the implementation class of XML::Filter::Sort — this is XML::Filter::Sort::BufferMgr, section 3pm, and it's the backstage crew nobody claps for but literally nothing works without. ✨

---

🌸 DESCRIPTION 🌸

heads up, this doc is for developers who wanna extend or straight-up replace this class. if you're just a user trying to sort stuff, go read XML::Filter::Sort instead, bestie. 💅

so here's the tea: there are two classes doing the heavy lifting for buffering records and spooling them back out in sorted order as SAX events.

• One single instance of the XML::Filter::Sort::Buffer class buffers each record.
• One or more instances of the XML::Filter::Sort::BufferMgr class (that's us!! hi!!) manage all those buffers. 🫶

---

🎀 API METHODS 🎀

the API of this module, as used by XML::Filter::Sort::Buffer, is literally this exact sequence of method calls. no cap:

1. When the first 'record' in a sequence shows up, XML::Filter::Sort creates a XML::Filter::Sort::BufferMgr object using the new() method. main character entrance fr. 👑
2. XML::Filter::Sort calls the buffer manager's new_buffer() method to get a XML::Filter::Sort::Buffer object, and all SAX events get directed to this object until the end of the record is encountered. The following events are supported by the current buffer implementation:

start_element()
characters()
comment()
processing_instruction()
end_element()

3. When the end of the record is detected, XML::Filter::Sort calls the buffer manager's close_buffer() method, which in turn calls the buffer's close() method. The close() method returns a list of values for the sort keys, and the buffer manager uses these to store the buffer for later recall. Subsequent records are handled as per step 2. 🔁
4. When the last record has been buffered, XML::Filter::Sort calls the buffer manager's to_sax() method. The buffer manager retrieves each of the buffers in sorted order and calls the buffer's to_sax() method. and that's the finale, slay. 💅

Each buffer attempts to match the sort key paths as SAX events are received. Once a value has been found for a given key, that same path match is not attempted against subsequent events. For efficiency, the code to match each key is compiled into a closure. For even more efficiency, this compilation is done once when the XML::Filter::Sort object is created. The compile_matches() method in the buffer manager class calls the compile_matches() method in the buffer class to achieve this. so smart, honestly obsessed. 🧚

---

🦋 DATA STRUCTURES 🦋

in the current implementation, the XML::Filter::Sort::BufferMgr class simply uses a hash to store the buffer objects. If only one sort key was defined, only a single hash is required. The values in the hash are arrayrefs containing the list of buffers for records with identical keys.

If two or more sort keys are defined, the hash values will be XML::Filter::Sort::BufferMgr objects which in turn will contain the buffers. The following illustration may clarify the relationship (BM=buffer manager, B=buffer):

                                     BM
                     +----------------+---------------+
                     |                                |
                    BM                               BM
               +-----+--------+                 +-----+----------+
               |              |                 |                |
              BM             BM                BM               BM
         +-----+----+    +----+------+     +----+----+    +------+------+
         |     |    |    |    |      |     |    |    |    |      |      |
      [B,B,B] [B] [B,B] [B] [B,B] [B,B,B] [B] [B,B] [B] [B,B] [B,B,B] [B,B]

This layered storage structure is transparent to the XML::Filter::Sort object, which instantiates and interacts with only one buffer manager — the one at the top of the tree. it's giving organizational hierarchy, it's giving tree structure, it's giving iykyk. 🌈

---

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

---

okay that's the whole page bestie, hope it ate 💖 this was perl v5.26.1, dated 2018-03-30, and it lives at XML::F...ferMgr(3pm) — go forth and buffer responsibly, mwah 🎀✨