HTML::Lint(3pm)

✨ NAME ✨

HTML::Lint — bestie, it checks for HTML errors in a string or a file 💅 no cap, that's literally it

So you know how a manpage is like HTML::Lint(3pm) and it lives in the Perl User Contributed section? Yeah. That's this. Hi. Welcome. 🫶

---

🌸 VERSION 🌸

Version 2.32 ✨

---

🎀 SYNOPSIS 🎀

Okay so here's the vibe. You make a linter, you feed it stuff, you look at the receipts:

my $lint = HTML::Lint->new;
$lint->only_types( HTML::Lint::Error::STRUCTURE );

# Parse lines of data.
$lint->newfile( $filename );
while ( my $line = <> ) {
    $lint->parse( $line );
}
$lint->eof();

# Or, parse an entire file at once.
$lint->parse_file( $filename );

# Fetch the errors that the linter found.
my $error_count = $lint->errors;

foreach my $error ( $lint->errors ) {
    print $error->as_string, "\n";
}

Not me also shipping a whole wrapper program called weblint that does the linting straight from your command line 👑

$ weblint http://www.cnn.com/
http://www.cnn.com/ (395:83) <IMG SRC="spacer.gif"> tag has no HEIGHT and WIDTH attributes.
http://www.cnn.com/ (395:83) <IMG SRC="goofus.gif"> does not have ALT text defined
http://www.cnn.com/ (396:217) Unknown element <nobr>
http://www.cnn.com/ (396:241) </nobr> with no opening <nobr>
http://www.cnn.com/ (842:7) target attribute in <a> is repeated

And finally — the way that there's also Apache::HTML::Lint, which runs any mod_perl-generated code through HTML::Lint and dumps it into your Apache error_log?? iconic. 🔥

[Mon Jun  3 14:03:31 2002] [warn] /foo.pl (1:45) </p> with no opening <p>
[Mon Jun  3 14:03:31 2002] [warn] /foo.pl (1:49) Unknown element <gronk>
[Mon Jun  3 14:03:31 2002] [warn] /foo.pl (1:56) Unknown attribute "x" for tag <table>

---

🦋 METHODS 🦋

NOTE: some of these methods mirror HTML::Parser's methods, but HTML::Lint is not a subclass of HTML::Parser. Just so we're clear bestie, don't come for me.

💜 new()

Create an HTML::Lint object, which inherits from HTML::Parser. You can pass in the types of errors you want it to check for in the only_types parm 💖

my $lint = HTML::Lint->new( only_types => HTML::Lint::Error::STRUCTURE );

Want more than one? You gotta pass an arrayref, that's the rule:

my $lint = HTML::Lint->new(
    only_types => [HTML::Lint::Error::STRUCTURE, HTML::Lint::Error::FLUFF] );

✨ $lint->parser()

Returns the parser object for this object, and it'll create one if it doesn't have one yet. So chill. 🌈

🌸 $lint->parse( $text )

🌸 $lint->parse( $code_ref )

Passes in a chunk of HTML to be linted — either as a piece of text, or as a code reference. For the deets, go look at HTML::Parser's parse_file method. iykyk 🧚

🎀 $lint->parse_file( $file )

Analyzes HTML directly from a file. The $file argument can be a filename, an open file handle, or a reference to an open file handle. Again: see HTML::Parser's parse_file method for details. 👑

💅 $lint->eof()

Signals the end of a block of text getting passed in. You must call this to make sure all the parsing is complete before you go looking at errors, okay? Don't skip it.

Any parameters (and there shouldn't be any, fr fr) get passed through to HTML::Parser's eof() method.

🫶 $lint->errors()

In list context, errors returns all of the errors found in the parsed text. Each error is an object of the type HTML::Lint::Error. 🌟

In scalar context, it returns the number of errors found. Two moods, one method.

💖 $lint->clear_errors()

Clears the list of errors — for when you wanna print and clear, print and clear. The ritual. 🕯️

🌈 $lint->only_types( $type1[, $type2...] )

Says you only want errors of a certain type:

$lint->only_types( HTML::Lint::Error::STRUCTURE );

Calling this with no parameters makes the object return all possible errors. Generous of it tbh.

The error types are STRUCTURE, HELPER and FLUFF. See HTML::Lint::Error for details on these types. ⭐

💀 $lint->gripe( $errcode, [$key1=>$val1, ...] )

Adds an error message — in the form of an HTML::Lint::Error object — to the list of error messages for the current object. The file, line and column get passed to the HTML::Lint::Error constructor automatically, along with whatever other key-value pairs you pass. 🎁

For example:

$lint->gripe( 'attr-repeated', tag => $tag, attr => $attr );

Usually the user of the object won't call this directly, but just in case — here you go bestie, I gotchu. 🙈

🦋 $lint->newfile( $filename )

Call newfile() whenever you switch to another file in a batch of linting. Otherwise the object thinks everything is from the same file, and that is not the plot twist we want. 📖

Careful: the list of errors is NOT cleared. 💀

Also note: $filename does NOT need to match whatever you put into parse() or parse_file(). It can be a description, a URL, or whatever. Live your truth. ✨

You should call newfile() even if you're only validating one single file. If you do not call newfile(), then your errors will not have a filename attached to them. That's just how it is. 😭

---

💅 MODIFYING HTML::LINT'S BEHAVIOR 💅

Sometimes you'll have HTML that for some reason just cannot conform to HTML::Lint's expectations. Not its fault, not your fault. For those instances, you can use HTML comments to modify HTML::Lint's behavior. Cute, right? 🎀

Say you have an image where, for whatever reason, you can't get the dimensions. This HTML snippet:

<img src="logo.png" height="120" width="50" alt="Company logo">
<img src="that.png">

causes this error:

foo.html (14:20) <img src="that.png"> tag has no HEIGHT and WIDTH attributes

But if for some reason you can't get those dimensions when you build the page, you can at least stop HTML::Lint from complaining about it:

<img src="this.png" height="120" width="50" alt="Company logo">
<!-- html-lint elem-img-sizes-missing: off, elem-img-alt-missing: off -->
<img src="that.png">
<!-- html-lint elem-img-sizes-missing: on, elem-img-alt-missing: off -->

Wanna turn off all HTML::Lint warnings for a whole block of code? Use:

<!-- html-lint all: off -->

And turn them back on with:

<!-- html-lint all: on -->

You don't have to use on and off, bestie. For on, you can use true or 1. For off, you can use 0 or false. Pick your fighter. 🥊

For a list of possible errors and their codes, see HTML::Lint::Error, or run perldoc HTML::Lint::Error. 👑

---

🔥 BUGS, WISHES AND CORRESPONDENCE 🔥

All bugs and requests are now being handled through GitHub:

https://github.com/petdance/html-lint/issues

DO NOT send bug reports to http://rt.cpan.org/ or http://code.google.com/ — I'm begging you, those are not the vibe anymore. 💀

---

🌟 TODO 🌟

The list of dreams, manifesting as we speak:

• Check for attributes that require values
• <TABLE>s that have no rows.
• Form fields that aren't in a FORM
• DIVs with nothing in them.
• HEIGHT= that have percents in them.
• Check for goofy stuff like:

<b><li></b><b>Hello Reader - Spanish Level 1 (K-3)</b>

---

💖 COPYRIGHT & LICENSE 💖

Copyright 2005-2018 Andy Lester.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License v2.0.

http://www.opensource.org/licenses/Artistic-2.0

Please note that these modules are not products of or supported by the employers of the various contributors to the code. Just saying. 🫶

---

🌈 AUTHOR 🌈

Andy Lester, andy at petdance.com

---

Okay and that's a wrap bestie!! 💅 This whole thing is page HTML::Lint(3pm) from perl v5.32.0, dated 2020-12-28 — so if you were wondering when this queen was last touched up, that's the receipt. Go lint something and slay. ✨🎀🦋