Highlight(3pm)

✨ Highlight(3pm) ✨

okay bestie, sit down, because this one's a Perl module and it's about to make your search results look 🔥. It's called HTML::Highlight and it lives in the User Contributed Perl Documentation corner of the manual, iykyk. Let's get into it 💅

---

🌸 NAME 🌸

HTML::Highlight — a whole module whose entire job is highlighting words or patterns in HTML documents. That's it. That's the gig. 👑

---

🦋 SYNOPSIS 🦋

use HTML::Highlight;

# create the highlighter object

my $hl = new HTML::Highlight (
        words => [
                'word',
                'any',
                'car',
                'some phrase'
        ],
        wildcards => [
                undef,
                '%',
                '*',
                undef
        ],
        colors => [
                '#FF0000',
                'red',
                'green',
                'rgb(255, 0, 0)'
        ],
        czech_language => 0,
        debug => 0
);

# Remember that you don't need to specify your own colors.
# The default colors should be optimal.

# Now you can use the object to highlight patterns in a document
# by passing content of the document to its highlight() method.
# The highlighter object "remembers" its configuration.

my $highlighted_document = $hl->highlight($document);

---

💖 MOTIVATION 💖

So this module was originally built to team up with DBIx::TextIndex, a fulltext indexing module, so it could highlight search results. Bestie duo behavior fr fr 🫶

The whole reason it exists: nobody had a highlighter that (a) respected wildcard matches, (b) actually noticed HTML tags, and (c) spoke Czech — or other Slavic languages. So someone made one. Iconic. ✨

---

🌈 DESCRIPTION 🌈

This module does Google-style highlighting of words or patterns inside HTML documents. Classic use case? Highlighting search results. Main character energy ⭐

🎀 The constructor 🎀

my $hl = new HTML::Highlight (
        words => [],
        wildcards => [],
        colors => [],
        czech_language => 0,
        debug => 0
);

This is the constructor of the highlighter object, and it takes an array with an even number of parameters. (Even. Don't be chaotic about it 🙈)

• words — a reference to an array of the words you want highlighted.
• wildcards — a reference to an array of wildcards, and each one gets applied to the corresponding word in the words array.

A wildcard can be either undef or one of '%' or '*'.

The "%" character means "match any characters":

"%" applied to 'car' ==> matches "car", "cars", "careful", ...

The "*" character means "match also plural form of the word":

"*" applied to 'car' ==> matches only "car" or "cars"

An undefined wildcard means "match exactly the corresponding word":

undefined wildcard applied to 'car' ==> matches only "car"

• colors — a reference to an array of CSS color identificators, used to highlight the corresponding words in the words array.

If you don't specify your own colors, the default Google-like colors get used, no cap. And here's the cute part: the number of colors can be lower than the number of words — in that case the colors rotate, so some words end up sharing the same color. Recycling queen ♻️💅

Also, heads up: the highlighter takes HTML tags into account, so it will not "highlight" a word or pattern sitting inside a tag. Respect the tags, bestie 🚫

A support for diacritics insenstive matching for ISO-8859-2 languages (for for example the czech language) can be activated using the czech_language option. This feature requires a module CzFast that is available on CPAN in a directory of author TRIPIE or at http://geocities.com/tripiecz/.

Your system's locales must be set correctly to use the czech_language feature. Like, actually correctly. Not vibes-based. 😭

💜 highlight 💜

my $hl_document = $hl->highlight($document);

The only parameter is a document in that you want to highlight the words that were passed to the constructor of the highlighter object. The method returns a version of the document in which the words are highlighted. Simple. Clean. Slay. ✨

🧚 preview_context 🧚

my $sections = $hl->preview_context($document, $num);

This method takes two parameters:

1. The document you want to scan for the words that were passed to the constructor of the highlighter object.
2. An optional integer that specifies maximum number of characters in each of the context sections (see below). This parameter defaults to 80 characters if it's not specified. Minimum allowed value of this parameter is 60.

The method returns a reference to an array of sections of the document in which the words that were passed to the constructor appear. HTML tags are removed before the document is proccessed and are not present in the output. This feature is typically used in search engines to preview a context in which words from a search query appear in the resulting documents. The words are always in the middle of each of the sections. The number of sections this method returns is equal to the number of words passed to the constructor of the highlighter object. That means only the first occurrence of each of the words is taken into account.

(Words always centered, first occurrence only — she's got a system, and the system is immaculate 💅)

---

🍓 SUPPORT 🍓

No official support is provided, but I welcome any comments, patches and suggestions on my email. So like… slide into the inbox if you've got thoughts 🫶

---

💀 BUGS 💀

I am aware of no bugs.

(Not one. Zero. The confidence is off the charts and honestly? We love that for him 👑)

---

🌟 AVAILABILITY 🌟

http://geocities.com/tripiecz/

---

🎀 AUTHOR 🎀

Tomas Styblo, tripie@cpan.org, CPAN-ID TRIPIE

Prague, the Czech republic 🇨🇿

---

📜 LICENSE 📜

HTML::Highlight — A module to highlight words or patterns in HTML documents

Copyright (C) 2000 Tomas Styblo (tripie@cpan.org)

This module is free software; you can redistribute it and/or modify it under the terms of either:

a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

b) the "Artistic License" which comes with this module.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this module, in the file Artistic. If not, I'll be glad to provide one.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

---

👀 SEE ALSO 👀

• perl(1).

---

and that's the whole page, bestie 🦋 this one's from perl v5.36.0, dated 2022-11-21, and it's the Highlight(3pm) page — go forth and highlight responsibly, mwah 💖✨🎀