HTML-Truncate
view release on metacpan or search on metacpan
WHITESPACE AND ENTITIES
Repeated natural whitespace (i.e., "\s+" and not " ") in HTML --
with rare exception (pre tags or user defined styles) -- is not
meaningful. Therefore it is normalized when truncating. Entities are
also normalized. The following is only counted 14 chars long.
\n<p>\nthis is ‘text’\n\n</p>
^^^^^^^12345----678--9------01234------^^^^^^^^
METHODS
new Can take all the methods as hash style args. "percent" and "chars"
are incompatible so don't use them both. Whichever is set most
recently will erase the other.
my $ht = HTML::Truncate->new(utf8_mode => 1,
chars => 500, # default is 100
);
utf8_mode
Set/get, true/false. If "utf8_mode" is set, utf8_mode(1) is also set
in the underlying HTML::Parser, entities will be transformed with
decode and the default ellipsis will be a literal ellipsis and not
the default of "…".
chars
Set/get. The number of characters remaining after truncation,
excluding the "ellipsis".
Entities are counted as single characters. E.g., "©" is one
character for truncation counts.
Default is "100." Side-effect: clears any "percent" that has been
set.
percent
Set/get. A percentage to keep while truncating the rest. For a
document of 1,000 chars, percent('15%') and chars(150) would be
equivalent. The actual amount of character that the percent
represents cannot be known until the given HTML is parsed.
Side-effect: clears any "chars" that has been set.
ellipsis
Set/get. Ellipsis in this case means --
The omission of a word or phrase necessary for a complete
syntactical construction but not necessary for understanding.
http://www.answers.com/topic/ellipsis
What it will probably mean in most real applications is "read more."
The default is "…" which if the utf8 flag is true will render
as a literal ellipsis, "chr(8230)".
The reason the default is "…" and not "..." is this is meant
for use in HTML environments, not plain text, and "..."
(dot-dot-dot) is not typographically correct or equivalent to a real
horizontal ellipsis character.
truncate
It returns the truncated XHTML if asked for a return value.
my $truncated = $ht->truncate($html);
It will truncate the string in place if no return value is expected
(wantarray is not defined).
$ht->truncate($html);
print $html;
Also can be called with inline arguments-
print $ht->truncate( $html,
$chars_or_percent,
$ellipsis );
No arguments are strictly required. Without HTML to operate upon it
returns undef. The two optional arguments may be preset with the
methods "chars" (or "percent") and "ellipsis".
Valid nesting of tags is required (alla XHTML). Therefore some old
HTML habits like <p> without a </p> are not supported and may cause
a fatal error. See "repair" for help with badly formed HTML.
Certain tags are omitted by default from the truncated output.
* Skipped tags
These will not be included in truncated output by default.
<head>...</head> <script>...</script> <form>...</form>
<iframe></iframe> <title>...</title> <style>...</style>
<base/> <link/> <meta/>
* Tags allowed to self-close
See emptyElement in HTML::Tagset.
add_skip_tags( qw( tag list ) )
Put one or more new tags into the list of those to be omitted from
truncated output. An example of when you might like to use this is
if you're thumb-nailing articles and they start with
"<h1>title</h1>" or such before the article body. The heading level
would be absurd with a list of excerpts so you could drop it
completely this way--
$ht->add_skip_tags( 'h1' );
dont_skip_tags( qw( tag list ) )
Takes tags out of the current list to be omitted from truncated
output.
repair
Set/get, true/false. If true, will attempt to repair unclosed HTML
tags by adding close-tags as late as possible (eg.
"<i><b>foobar</i>" becomes "<i><b>foobar</b></i>"). Unmatched close
tags are dropped ("foobar</b>" becomes "foobar").
on_space
This will make the truncation back up to the first space it finds so
it doesn't truncate in the the middle of a word. "on_space" runs
( run in 1.529 second using v1.01-cache-2.11-cpan-f0fbb3f571b )