HTML::O...okenList(3)

📦 version 0.6.0, in alpine 3.24

🎀 HTML::Object::TokenList — the perl pod page, but make it a vibe 🎀

okay bestie, so this is from the User Contributed Perl Documentation section of the manual (that's the (3) bit, iykyk), and it's literally the whole rundown on HTML::Object::TokenList. sit down, grab a strawberry drink 🍓, we're doing this.

✨ NAME ✨

HTML::Object::TokenList — the HTML Object Token List Class. that's it, that's the name, she's iconic 💅

✨ SYNOPSIS ✨

so first things first, you gotta pull her in:

use HTML::Object::TokenList;
# standalone, i.e. without connection to an element
my $list = HTML::Object::TokenList->new( 'some class to edit' ) ||
    die( HTML::Object::TokenList->error, "\n" );

or — and this is the main character route — you let an element spawn her:

use HTML::Object::Element;
my $e = HTML::Object::Element->new( tag => 'div' );
my $list = $e->classList;

$list->add( 'another-class' );
$list->remove( 'edit' );
$list->length;
$list->value;
$list->as_string;
$list->contains( 'some' );
$list->forEach(sub
{
    my $c = shift( @_ ); # also available as $_
    # do something
});
$list->item(3); # 'edit'
$list->replace( 'to' = 'other' );
$list->toggle( 'visible' ); # activate it
$list->toggle( 'visible' ); # now remove it

look at her go. no notes. 🔥

✨ VERSION ✨

v0.2.0

she's on v0.2.0, slay 💖

✨ DESCRIPTION ✨

okay so the TokenList interface represents a set of space-separated tokens. like, a bunch of words with spaces between them, living their best life together. and where do you get one of these? you get it from classList in HTML::Object::DOM::Element, or from relList in HTML::Object::DOM::AnchorElement. those are the two hookups. 🫶

a TokenList is indexed beginning with 0, exactly like a perl array — zero-based girlies rise. and TokenList is always case-sensitive, no cap, Foo and foo are not the same token, do not @ me.

this module can be used independently (solo, no element, living free 🦋) or be instantiated by an element — and in that case, any modification made will be reflected in the associated element's attribute. so like, they're linked. she's in a relationship with the element. 😭

✨ PROPERTIES ✨

length

Read-only. she returns an integer representing the number of objects stored in the object. count 'em. 🔢

value

a stringifier property that returns the value of the list as a string. see also "as_string" — same energy, different door. ✨

✨ METHODS ✨

add

adds the specified tokens to the list. returns the current object for chaining (so you can keep going, love that for us 💅).

the tokens can be provided either as a list of string, an array reference of strings, or a space-delimited string of tokens. three ways in, all valid, we love an inclusive queen. 🎀

as_string

a stringifier property that returns the value of the list as a string. see also "value". yes this is the same description as value, no i will not be explaining further, they're twins. 👯

attribute

set or get the element attribute to which TokenList is bound. for example a "class" attribute or a "rel" attribute.

this is optional if you want to use this class independently from any element, or if you want to set the element later. no pressure bestie, set it whenever. 🌸

contains

returns true if the list contains the given token, otherwise false. yes/no, in/out, that's the whole thing. ✅

element

set or get the element.

this is optional if you want to use this class independently from any element, or if you want to set the element later. same deal as attribute, she's flexible like that. 🧚

entries

this does nothing.

normally, under JavaScript, this would return an iterator, allowing you to go through all key/value pairs contained in this object. but we're in perl land, so... nothing. she simply does not. 💀

forEach

executes a provided callback function once for each DOMTokenList element. once. per. element. go off. 🔁

item

returns the item in the list by its index, or undefined if the index is greater than or equal to the list's length. so item(3) is fine, item(999) is giving void. 🕳️

items

sets or gets the list of token items. it returns the array object containing all the tokens. the whole squad, in array form. 🫶

keys

this does nothing.

normally, under JavaScript, this would return an iterator, allowing you to go through all keys of the key/value pairs contained in this object. perl said no keys for you. 🙈

remove

removes the specified tokens from the list. bye babes 👋

replace

replaces the token with another one.

it returns a boolean value, which is true if the old entry was successfully replaced, or false if not. so like, check your return, bestie, that's the vibe check.

see the Mozilla documentation <https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/replace> for more information. ✨

reset

reset the tokens list to an empty list and, of course, propagate that change to the associated element's attribute, if any was set. total clean slate, we're starting over, new era. 🌈

returns the current object.

supports

returns true if the given token is in the associated attribute's supported tokens.

for the purpose of the perl environment, this actually always returns true. like, unconditional support. ride or die. 💖

toggle

removes the token from the list if it exists, or adds it to the list if it does not. returns a boolean indicating whether the token is in the list after the operation. it's giving "on and off and on again". 🔥

tokens

sets or get the array object of tokens. (yes, the original says "sets or get", she's quirky, we keep her exactly as she is 💅)

update

this method is called by an internal callback in HTML::Object::Element when the value of an registered attribute has been changed. it does not propagate the change back to the element since it is triggered by the element itself. closed loop, no echo, no infinite feedback moment. 😭

if "undef" is provided as its sole argument, this will empty the tokens list, otherwise it will set the new tokens list with a space-delimited string of tokens, a list or array reference of tokens.

returns the current object.

values

this does nothing.

normally, under JavaScript, this would return an iterator, allowing you to go through all values of the key/value pairs contained in this object. once again: nothing. three for three on the do-nothing methods, a legend. 👑

✨ EXAMPLES ✨

in the following simple example, we retrieve the list of classes set on a <p> element as a HTML::Object::TokenList using "classList" in HTML::Object::Element, add a class using "add" in HTML::Object::TokenList, and then update the "textContent" of the <p> to equal the HTML::Object::TokenList.

<p class="a b c"></p>

my $para = $doc->querySelector("p");
my $classes = $para->classList;
$para->classList->add("d");
$para->textContent = qq{paragraph classList is "${classes}"};

would yield:

paragraph classList is "a b c d"

ate. no crumbs. 🍽️✨

✨ WHITESPACE AND DUPLICATES ✨

methods that modify the TokenList (such as "add" in HTML::Object::TokenList) automatically trim any excess whitespace and remove duplicate values from the list. she's tidy, she's got her life together, she does not tolerate a messy class attribute. 🧹

for example:

<span class="    d   d e f"></span>

my $span = $doc->querySelector("span");
my $classes = $span->classList;
$span->classList->add("x");
$span->textContent = qq{span classList is "${classes}"};

would yield:

span classList is "d e f x"

look at that. whitespace gone, d deduped, x added, perfection. 💅

✨ AUTHOR ✨

Jacques Deguest <jack@deguest.jp> — the icon, the legend, the one who wrote her. 👑

✨ SEE ALSO ✨

go read those, bestie, iykyk 📚✨

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. periodt. 🫶

and that's the whole page! footer girlies, this one's for you: it's perl v5.42.2, dated 2026-02-15, rendered off the HTML::O...okenList(3) page — mwah, take care of her, she's iconic 💖🎀🦋

📦 where this page comes from