HTTP::...lparser(3pm)

💖 HTTP::Proxy::BodyFilter::htmlparser — the manual, but make it cute 💖

okay bestie, so this page lives in the User Contributed Perl Documentation corner of the man-page universe, and it's called HTTP::Proxy::BodyFilter::htmlparser (the header shortens it to HTTP::...lparser(3pm) because man pages are dramatic and love an ellipsis ✨). buckle up, we're filtering HTML with style 🎀

---

✨ NAME ✨

HTTP::Proxy::BodyFilter::htmlparser — a filter that uses HTML::Parser, no cap 💅

---

🌸 SYNOPSIS 🌸

use HTTP::Proxy::BodyFilter::htmlparser;

# $parser is a HTML::Parser object
$proxy->push_filter(
    mime     => 'text/html',
    response => HTTP::Proxy::BodyFilter::htmlparser->new( $parser );
);

---

🦋 DESCRIPTION 🦋

so basically, HTTP::Proxy::BodyFilter::htmlparser lets you build a filter around whatever HTML::Parser object your heart desires 💖

the filter takes a HTML::Parser object as the argument to its constructor. and here's the vibe check: the filter is either read-only or read-write. a read-only filter is like, hands off — it will not let you change the data on the fly. but if you ask for a read-write filter, bestie, you're signing up to rewrite the entire response body. completely. all of it. no shortcuts 😭

with a read-write filter you must recreate the whole body data. why?? because the HTML::Parser has its own buffering system going on, and there's literally no easy way to match up the data that triggered an HTML::Parser event with its original position in the chunk that the origin server sent. it's giving chaos. see below for the details 👇

ngl, if all you wanna do is modify the HTML text (not the tags), there's a way easier route: HTTP::Proxy::BodyFilter::htmltext. just saying 🫶

🧚 Creating a HTML::Parser that rewrites pages 🧚

to declare a read-write filter, you pass rw => 1 to the constructor, like so:

HTTP::Proxy::BodyFilter::htmlparser->new( $parser, rw => 1 );

to actually be able to modify the body of a message, a filter made with HTTP::Proxy::BodyFilter::htmlparser has to rewrite it completely — periodt. the HTML::Parser object can update a special attribute named output. to do that, the HTML::Parser handler has to request the self attribute (translation: it needs access to the parser itself 🪞) and then update its output key.

here are the attributes this filter adds to the HTML::Parser object:

• output — a string that will hold the data sent back by the proxy. 🌈 this string gets used as a replacement for the body data only if the filter is read-write, aka only if it was initialised with rw => 1. data should always be appended to $parser->{output}. always always. 💅
• message — a reference to the HTTP::Message that triggered the filter. 📨
• protocol — a reference to the HTTP::Protocol object. 🔌

---

👑 METHODS 👑

this filter defines three methods, and they're all called automatically — you don't have to poke them, they just show up like the main character ✨

• filter() — the filter() method handles all the interactions with the HTML::Parser object. it's the social butterfly of the trio 🦋
• init() — initialises the filter with the HTML::Parser object passed to the constructor. the setup era 🎀
• will_modify() — returns a boolean value that tells the system whether it's gonna modify the data passing through. and the value? it's literally just the value of the rw parameter you passed to the constructor. iconic, honestly 👑

---

🔥 SEE ALSO 🔥

HTTP::Proxy, HTTP::Proxy::Bodyfilter, HTTP::Proxy::BodyFilter::htmltext.

---

💜 AUTHOR 💜

Philippe "BooK" Bruhat, <book@cpan.org>.

---

⭐ COPYRIGHT ⭐

Copyright 2003-2015, Philippe Bruhat.

---

🌈 LICENSE 🌈

This module is free software; you can redistribute it or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie 🫶 this lil doc shipped as part of perl v5.36.0, dated 2022-12-04, so go forth and filter your HTML with main character energy 💖✨🎀🦋