HTML::O...llection(3)

📦 version 0.6.0, in alpine 3.24

💅 HTML::Object::DOM::Collection(3) — the perl manpage, but make it make sense

okay so bestie, you found the HTML::Object::DOM::Collection page in the User Contributed Perl Documentation and honestly? it's kind of a slay once you get past the manpage voice. let me translate 💖

✨ NAME ✨

HTML::Object::DOM::Collection — HTML Object DOM Collection. that's it, that's the name, no cap 🎀

✨ SYNOPSIS ✨

here's the whole vibe in code, exactly as the manpage serves it:

use HTML::Object::DOM::Collection;
my $this = HTML::Object::DOM::Collection->new || die( HTML::Object::DOM::Collection->error, "\n" );

my $html = <<EOT;
<html>
    <head><title>Demo</title></head>
    <body>
        <form id="myForm">
            <input type="text" />
            <button>Ok</button>
        </form>
    </body>
</html>
EOT

my( $elem1, $elem2 );
my $p = HTML::Object::DOM->new;
my $doc = $p->parse_data( $html );
# $doc->forms is an HTML::Object::DOM::Collection

$elem1 = $doc->forms->[0];
$elem2 = $doc->forms->item(0);

say( $elem1 == $elem2 ); # returns: "1" (i.e. true)
# or, similarly
say( $elem1 eq $elem2 ); # returns: "1" (i.e. true)

$elem1 = $doc->forms->myForm;
$elem2 = $doc->forms->namedItem("myForm");

say( $elem1 == $elem2 ); # returns: "1" (i.e. true)
# or, similarly
say( $elem1 eq $elem2 ); # returns: "1" (i.e. true)

# This is possible under JavaScript, but not possible under perl
# $elem1 = $doc->forms->[ 'named.item.with.periods' ];

like, look at that — [0] and item(0) give you the same node, ->myForm and namedItem("myForm") give you the same node. iconic behavior honestly 👑

and yeah, that last commented line is real: in JavaScript you could do $doc->forms->[ 'named.item.with.periods' ], but not possible under perl. sad but true 💀

✨ VERSION ✨

v0.3.0

✨ DESCRIPTION ✨

so the "Collection" interface is basically a generic collection — an array-like object that inherits from Module::Generic::Array — holding a list of elements in document order, and it comes with methods and properties for picking stuff out of that list. 🦋

and here's the part where the manpage is like "don't get it twisted":

This is fundamentally different from HTML::Object::Collection, which is used by HTML::Object::XQuery. two different things, bestie, don't mix them up 🙈

✨ PROPERTIES ✨

🌸 length

returns the number of items in the collection. literally just the count, that's the whole job 💅

✨ METHODS ✨

🎀 item

you hand it an integer representing an index, and it gives you back the specific node at that given zero-based index in the list. if the index is out of range? you get undef back. 🫶

this is also an alternative to accessing "$collection-"[$i]> (which instead returns "undef" when $i is out-of-bounds).

example time:

my $c = $doc->images;   # This is an HTMLCollection
my $img0 = $c->item(0); # You can use the item() method this way
my $img1 = $c->[1];     # But this notation is easier and more common

see the Mozilla documentation: <https://developer.mozilla.org/en-US/docs/Web/API/HTMLCollection/item> ✨

🦋 namedItem

you pass in a name, and it returns the specific node whose "ID" — or, as a fallback, "name" — matches the string you specified as name. and listen, matching by "name"? that's only done as a last resort, only in HTML, and only if the referenced element actually supports the "name" attribute. if no node exists with the given name, you get undef. 😭

it's an alternative to accessing "$collection-"[ $name ]> (which is possible in JavaScript, but not under perl).

example:

<div id="personal">
    <span name="title">Dr.</span>
    <span name="firstname">John</span>
    <span name="lastname">Doe</span>
</div>
my $container = $doc->getElementById('personal');
# Returns the span element object with the name "title" if no such element exists undef is returned
my $titleSpan = $container->children->namedItem('title');
# The following variants return undefined instead of null if there's no element with a matching name or id
# Not possible in perl!
# my $firstnameSpan = $container->children->['firstname'];
my $firstnameSpan = $container->children->[1];
my $lastnameSpan = $container->children->lastname;

see the Mozilla documentation: <https://developer.mozilla.org/en-US/docs/Web/API/HTMLCollection/namedItem> 🧚

✨ AUTHOR ✨

Jacques Deguest <jack@deguest.jp> 💌

✨ SEE ALSO ✨

Copyright(c) 2021 DEGUEST Pte. Ltd.

All rights reserved

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

okay and that's the whole page, bestie — you ate that reading comprehension 🔥

🌈 cute sign-off: this was perl v5.42.2, dated 2026-02-15, and the page is HTML::O...llection(3) in case you need to cite it in your group chat. periodt 💜
📦 where this page comes from