XML::S...mental(3pm)

💖 XML::S...mental — the manual page, but make it make sense 💖

okay bestie, so this is the manual page for XML::SAX::Expat::Incremental (the header abbreviates it as XML::S...mental, adorable, slay), living in the User Contributed Perl Documentation section, 3pm. Buckle up, it's giving parser lore. 🦋

---

✨ NAME ✨

XML::SAX::Expat::Incremental — it's an XML::SAX::Expat subclass for non-blocking (incremental) parsing, powered by XML::Parser::ExpatNB. basically it lets YOU drive the loop instead of the parser doing it behind your back. main character energy fr. 👑

---

🌸 SYNOPSIS 🌸

        use XML::SAX::Expat::Incremental;

        # don't do this, use XML::SAX::ParserFactory
        my $p = XML::SAX::Expat::Incremental->new( Handler => MyHandler->new );

        $p->parse_start;

        while (<DATA>){
                $p->parse_more($_); # or $p->parse_string($_);
        }

        $p->parse_done;

not me writing XML::SAX::Expat::Incremental->new directly 💀 the comment literally says don't do this, use XML::SAX::ParserFactory. respect the comment, bestie. 🙈

---

🎀 DESCRIPTION 🎀

okay so here's the tea. Most XML parsers hand you a callback interface tucked inside an encapsulated loop. meaning you call:

        $p->parse_whatever($whatever);

and then eventually, once the parser has chewed through $whatever, $p->parse returns. cute, but the parser is driving. not you. 🚗

and sometimes you do NOT want the parser controlling the loop for you. like, say you gotta pull your XML in chunks in some weird little way, you might end up doing something like:

        my $doc = '';
        while (defined(my $buffer = get_more_xml())) {
                $doc .= $buffer;
        }

        $p->parse_string($doc);

which is… not very convenient, or efficient. ngl it's giving struggle. 😭

you could use perltie to tie a filehandle that does this for you, but that only works some of the time — for example, say you have two inputs coming in simultaneously. yeah. exactly. the tie can't carry that.

XML::Parser::ExpatNB solves this by providing three methods:

• parse_start
• parse_more
• parse_done

this interface lets you move the loop to outside the parser, so you retain control. periodt. 💅

the callbacks are executed in the same manner, just that now, when there is no left to parse, instead of taking more data from a source on it's own, the parser returns control to you. (yes, the original says "no left to parse", we don't fix typos here, we honor them 🫶)

        $p->parse_start; # you can omit this - parse_start will
                         # be called automatically as needed

        while(defined(my $buffer = get_more_xml())) {
                $p->parse_more($buffer);
        }

        $p->parse_done;

and, iconic detail: this module is a subclass of XML::SAX::Expat which is to XML::Parser::ExpatXS as XML::SAX::Expat is to XML::Parser itself. iykyk. 🌈

---

💅 METHODS 💅

parse_string STRING

parse_more STRING

these two have the same effect, except that parse_more actually calls parse_string with @_. you might wanna use parse_string because in theory it's more efficient. ✨

this simply continues parsing with the new string, and sends SAX events for the data that is complete in the string.

parse_start

this calls parse_start on the underlying XML::Parser::ExpatNB object. it's called implicitly when you first call parse_string, though, so you don't have to worry about it. 🧚 lowkey it's already handled.

parse_done

this calls parse_done on the underlying XML::Parser::ExpatNB object. you use it to tell the parser you have no more data to give it. it's the "okay bestie we're done here" of methods. 🎀

parse

this is used internally as a sort of parse-anything method.

don't use it. instead use "parse_string", which invokes this method correctly, and takes simpler options. 🙅♀️

---

🦋 SEE ALSO 🦋

• XML::Parser
• XML::SAX
• XML::SAX::Expat
• XML::SAX::ExpatNB

go read those too, they're the friend group. 💜

---

🌈 VERSION CONTROL 🌈

this module is maintained using Darcs. you can get the latest version from <http://nothingmuch.woobling.org/XML-SAX-Expat-Incremental/>, and use "darcs send" to commit changes. old-school tool, new-school slay. ⭐

---

👑 AUTHOR 👑

Yuval Kogman <nothingmuch@woobling.org>

---

💖 COPYRIGHT & LICENSE 💖

        Copyright (c) 2005 Yuval Kogman. All rights reserved
        This program 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!! 🍓 this was perl v5.34.0, dated 2022-06-26, and that's a wrap — no cap, fr fr. go forth and parse incrementally. 💅✨🫶