Peter Karman > HTML-HiLiter > HTML::HiLiter

Download:
HTML-HiLiter-0.18.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.18   Source  

NAME ^

HTML::HiLiter - highlight words in an HTML document just like a felt-tip HiLiter

SYNOPSIS ^

 use HTML::HiLiter;
 
 my $hiliter = new HTML::HiLiter(
  word_characters   =>  '\w\-\.',
  ignore_first_char =>  '\-\.',
  ignore_last_char  =>  '\-\.',
  tag               =>  'span',
  colors            =>  [ qw(#FFFF33 yellow pink) ],
  tag_filter        =>  \&yourtagcode(),
  text_filter       =>  \&yourtextcode(),
  query             =>  'foo bar or "some phrase"',
 );
 
 $hiliter->run($some_file_or_URL);

DESCRIPTION ^

HTML::HiLiter is designed to make highlighting search queries in HTML easy and accurate. HTML::HiLiter was designed for CrayDoc 4, the Cray documentation server.

As of verison 0.14, HTML::HiLiter has been completely re-written with a new API, using Search::Tools.

REQUIREMENTS ^

The following are required:

Required to use the HTTP option in the run() method:

FEATURES ^

A cornucopia of features.

METHODS ^

new()

Create a HiLiter object.

Any parameter that can be passed to Search::Tools::HiLiter can be passed to HTML::HiLiter. In addition, the following HTML::HiLiter-specific parameters are supported:

fh

The filehandle to send output to. Defaults to STDOUT. If print_stream is false, will buffer instead of printing.

hiliter

Set a Search::Tools::HiLiter object for HTML::HiLiter to use. If you do not set one, one will be created based on the other parameters you pass.

tag_filter

A CODE reference of your choosing for filtering HTML tags as they pass through the HTML::Parser. See FILTERS.

text_filter

A CODE reference of your choosing for filtering HTML text as it passes through the HTML::Parser. See FILTERS.

buffer_limit

When the number of characters in the HTML buffer exceeds the value of buffer_limit, the buffer is printed without highlighting being attempted. The default is 2**16 characters. Make this higher at your peril. Most HTML will not exceed more than that n a <p> tagset, for example.

print_stream

Default value true (1). Print highlighted HTML as the HTML::Parser encounters it. If true, use a select() in your script to print somewhere besides the perl default of STDOUT.

NOTE: Set this to 0 (false) only if you are highlighting small chunks of HTML (i.e., smaller than buffer_limit). See run().

init

Called internally by new().

query

Get the Search::Tools::Query object created in new().

style_header( html )

If set, html will be applied just after the opening <head> tag while parsing. This is to allow insertion of CSS or other head-appropriate markup.

apply_hiliting( string )

Passes string through Search::Tools::HiLiter->light() and returns string highlighted.

Queries

This method is deprecated. See the query param to new() instead.

run( $file | $url | \$html )

run() takes either a file name, a URL (indicated by a leading 'http://'), or a scalar reference to a string of HTML text.

Run

For backwards compatability, Run() is an alias for run().

FILTERS ^

text_filter and tag_filter are two optional parameters that allow you to filter the contents of your HTML beyond normal highlighting. Each parameter takes a CODE reference.

text_filter should expect these parameters in this order:

parserobj, dtext, text, offset, length

tag_filter should expect these parameters in this order:

parserobj, tag, tagname, offset, length, offset_end, attr, text

Both should return a scalar string of text. tag_filter should return a set of attributes. text_filter may return whatever you want. See EXAMPLES and the HTML::Parser documentation for what these parameters mean and for more about writing filters.

EXAMPLES ^

See examples/ directory in source distribution.

HISTORY ^

Yet another highlighting module?

My goal was complete, exhaustive, tear-your-hair-out efforts to highlight HTML. No other modules I found on the web supported nested tags within words and phrases, or character entities. Cray uses the standard DocBook stylesheets from Norm Walsh et al, to generate HTML. These stylesheets produce valid HTML but often fool the other highlighters I found.

The problem became most evident when we started using Swish-e. Swish-e does such a good job at converting entities and doing phrase matching that we found ourselves in a dilemma: Swish-e often gave valid search results that mere mortal highlighters could not match in the source HTML -- not even the SWISH::*Highlight modules.

With the exception of the 'nohiliter' attribute, I think I follow the W3C HTML 4.01 specification. Please prove me wrong.

Prime Example of where this module overcomes other attempts by other modules.

The query 'bold in the middle' should match this HTML:

   <p>some phrase <b>with <i>b</i>old</b> in&nbsp;the middle</p>

GOOD highlighting:

   <p>some phrase <b>with <i><span>b</span></i><span>old</span></b><span>
   in&nbsp;the middle</span></p>

BAD highlighting:

   <p>some phrase <b>with <span><i>b</i>bold</b> in&nbsp;the middle</span></p>

No module I tried in my tests could even find that as a match (let alone perform bad highlighting on it), even though indexing programs like Swish-e would consider a document with that HTML a valid match.

Should you use this module?

I would suggest not using HTML::HiLiter if your HTML is fairly simple, since in HTML::HiLiter, speed has been sacrificed for accuracy and rich features. Check out HTML::Highlight instead.

Unlike other highlighting code I've found, HTML::HiLiter supports nested tags and character entities, such as might be found in technical documentation or HTML generated from some other source (like DocBook SGML or XML).

The goal is server-side highlighting that looks as if you used a felt-tip marker on the HTML page. You shouldn't need to know what the underlying tags and entities and encodings are: you just want to easily highlight some text as your browser presents it.

TODO ^

KNOWN BUGS AND LIMITATIONS ^

Will not highlight literal parentheses ().

Phrases that contain stopwords may not highlight correctly. It's more a problem of *which* stopword the original doc used and is not an intrinsic problem with the HiLiter, but noted here for completeness' sake.

AUTHOR ^

Peter Karman, karman@cray.com

Thanks to the Swish-e developers, in particular Bill Moseley for graciously sharing time, advice and code examples.

Comments and suggestions are welcome.

COPYRIGHT ^

 ###############################################################################
 #    CrayDoc 4
 #    Copyright (C) 2004 Cray Inc swpubs@cray.com
 #
 #    This program is free software; you can redistribute it and/or modify
 #    it under the terms of the GNU General Public License as published by
 #    the Free Software Foundation; either version 2 of the License, or
 #    (at your option) any later version.
 #
 #    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 the
 #    GNU General Public License for more details.
 #
 #    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.
 ###############################################################################

SUPPORT ^

Send email to swpubs@cray.com.

SEE ALSO ^

Search::Tools, HTML::Parser

syntax highlighting: