NAME
Search::Tools::HiLiter - highlight terms in text
SYNOPSIS
use Search::Tools::HiLiter;
my $hiliter = Search::Tools::HiLiter->new(
query => 'the quick brown fox'
);
for my $text (@texts) {
print $hiliter->light( $text );
}
DESCRIPTION
Search::Tools::HiLiter uses HTML tags to highlight text just like a felt-tip HiLiter. The HiLiter can handle both plain (no HTML markup) and marked up text (HTML and XML). Nested entities and tags within terms are supported.
You create a HiLiter object with either a string or a Search::Tools::Query object, and then feed the HiLiter text to highlight. You can control the style and color of the highlight tags.
Some caveats if you are highlighting HTML or XML: Unlike its more powerful cousin HTML::HiLiter, Search::Tools::HiLiter knows nothing about context. This can give unexpected results when your terms appear in the HTML <head
> or across block tag boundaries. Use HTML::HiLiter if you need a real HTML parser. It uses the same regular expressions as this class but is designed for full HTML documents rather than smaller fragments.
METHODS
new( query => query )
query must be either a scalar string or a Search::Tools::Query object. You might use the last if you are also using Search::Tools::Snipper, since you only need to compile your Search::Tools::Query object once and then pass it to both new() instances.
The following params are also supported. Each is available as an accessor method as well:
- class
- colors
- no_html
- style
- tag
- text_color
- tty
- ttycolors
BUILD
Called internally by new().
terms
Calls through to query->terms(). Returns array ref.
keywords
Like terms() but returns array not array ref.
open_tag( term )
Get the opening hilite tag for term.
close_tag( term )
Get the closing hilite tag for term.
light( text )
Add hiliting tags to text. Calls plain(), plain_stemmer() or html() based on whether text contains markup (checked with Search::Tools::XML->looks_like_html()).
light() will return text as a UTF-8 encoded string.
hilite( text )
An alias for light().
plain( text )
Add hiliting tags to plain text.
Called internally by light().
plain_stemmer( text )
Add hiliting tags to plain text, when query has had stemming applied. See stemmer option to Search::Tools::QueryParser.
Called internally by light().
Note that stemming support for HTML text is not yet fully supported, and plain_stemmer() is applied to both HTML and non-HTML when the query has been stemmed.
html_stemmer( text )
Currently calls plain_stemmer().
html( text )
Add hiliting tags to marked up text.
Called internally by light().
Note that stemming support for HTML text is not yet supported.
class
The name of the class attribute to be used on the tag().
style
The value to use in the style
attribute of tag.
tag
The name of the highlighting tag. Default is span
.
tty
Pass a true value to use Term::ANSIColor highlighting. This is useful when using a terminal for debugging or for displaying results. Default is off.
ttycolors
Set the colors used if tty() is true. See the Term::ANSIColor documentation for options.
debug
Set to a value >= 1 to get debugging output. If used in conjuction with tty(), both tty colors and HTML tags are used for highlighting.
no_html
Set to a true value (1) to avoid HTML highlighting tags regardless of test for whether text is HTML.
colors( array_ref_of_html_colors )
Get/set the HTML color values to use inside tag(). These are used if class() is not set. The defaults are:
[ '#ffff99', '#99ffff', '#ffccff', '#ccccff' ]
text_color( html_color )
Get/set the HTML color to set on the style attribute in tag(). This setting can be useful if the background color of the page clashes with one or more of the colors() (as with a black body color).
AUTHOR
Peter Karman <karman at cpan dot org>
ACKNOWLEDGEMENTS
Based on the HTML::HiLiter regular expression building code, originally by the same author, copyright 2004 by Cray Inc.
Thanks to Atomic Learning www.atomiclearning.com
for sponsoring the development of this module.
BUGS
Please report any bugs or feature requests to bug-search-tools at rt.cpan.org
, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Search-Tools. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Search::Tools
You can also look for information at:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
COPYRIGHT
Copyright 2009 by Peter Karman.
This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO
Search::QueryParser