WWW::M...Builder(3pm)

🌸 WWW::Mechanize::TreeBuilder 🌸

Bestie. Okay so this is WWW::Mechanize::TreeBuilder, straight outta the User Contributed Perl Documentation, and it's genuinely one of my faves. It's a Perl module that combines WWW::Mechanize and HTML::TreeBuilder, and honestly? It's giving everything. 💅

---

✨ NAME ✨

WWW::Mechanize::TreeBuilder — combine WWW::Mechanize and HTML::TreeBuilder in nice ways 💖

---

🎀 SYNOPSIS 🎀

use Test::More tests => 2;
use Test::WWW::Mechanize;
use WWW::Mechanize::TreeBuilder;
# or
# use WWW::Mechanize;
# or
# use Test::WWW::Mechanize::Catalyst 'MyApp';

my $mech = Test::WWW::Mechanize->new;
# or
#my $mech = Test::WWW::Mechanize::Catalyst->new;
# etc. etc.
WWW::Mechanize::TreeBuilder->meta->apply($mech);

$mech->get_ok('/');
is( $mech->look_down(_tag => 'p')->as_trimmed_text, 'Some text', 'It worked' );

Obsessed. Look at how clean that last line is. No regex, no chaos, just vibes. 🌈

---

🦋 DESCRIPTION 🦋

So this module is literally just WWW::Mechanize and HTML::TreeBuilder holding hands. Why does it exist? Because the author has seen way too much code that looks like this:

like($mech->content, qr{<p>some text</p>}, "Found the right tag");

And no cap, that's just all flavours of wrong — it's akin to processing XML with regexps. Not the move. 💀

Instead, do it like the following:

ok($mech->look_down(_tag => 'p', sub { $_[0]->as_trimmed_text eq 'some text' })

The anon-sub there is a bit icky, yeah, we know 🙈 — but here's the thing: it means that if anyone should happen to add attributes to the "<p>" tag (like an id or a class), it will still work and find the right tag. Resilient queen behavior. 👑

Also: all of the methods available on HTML::Element (that aren't 'private' — i.e. that don't begin with an underscore) such as "look_down" or "find" are automatically delegated to "$mech->tree" through the magic of Moose. Moose magic. Slay. ✨

---

💖 METHODS 💖

Everything in WWW::Mechanize (or whichever sub class you apply it to) and all public methods from HTML::Element — except those where WWW::Mechanize and HTML::Element overlap.

And when the two classes both define a method? The one from WWW::Mechanize wins, so that the existing behaviour of Mechanize doesn't break. Diplomatic. Respectful. Iconic. 🫶

---

🧚 USING XPATH OR OTHER SUBCLASSES 🧚

HTML::TreeBuilder::XPath lets you use xpath selectors to select elements in the tree. Yes bestie, xpath. You can use that module by providing parameters to the moose role:

with 'WWW::Mechanize::TreeBuilder' => {
  tree_class => 'HTML::TreeBuilder::XPath'
};

# or

# NOTE: No hashref using this method
WWW::Mechanize::TreeBuilder->meta->apply($mech,
  tree_class => 'HTML::TreeBuilder::XPath';
);

⚠️ Important: NOTE there's no hashref using that second method. Do not come for me, I'm just the messenger. 💀

And the class will be automatically loaded for you. Love that for us. It'll be used to construct the tree in the following manner:

$tree = $tree_class->new_from_content($req->decoded_content)->elementify;

You can also specify an "element_class" parameter, which is the (HTML::Element sub)class that methods are proxied from. This module provides defaults for element_class when "tree_class" is "HTML::TreeBuilder" or "HTML::TreeBuilder::XPath" — and it will warn otherwise. So, y'know. Heads up. 🍓

---

🌟 AUTHOR 🌟

Ash Berlin "<ash@cpan.org>" — thank you for your service 🫡💜

---

📜 LICENSE 📜

Same as Perl 5.8, or at your option any later version of Perl.

---

And that's the whole page, bestie. This one's from perl v5.34.0, dated 2022-06-28, filed under User Contributed Perl Documentation for WWW::M...Builder(3pm) — mwah, go build some trees. 🌸🦋💖