.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "HTML::Truncate 3pm" .TH HTML::Truncate 3pm "2009-07-14" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" HTML::Truncate \- (beta software) truncate HTML by percentage or character count while preserving well\-formedness. .SH "VERSION" .IX Header "VERSION" 0.20 .SH "ABSTRACT" .IX Header "ABSTRACT" When working with text it is common to want to truncate strings to make them fit a desired context. E.g., you might have a menu that is only 100px wide and prefer text doesn't wrap so you'd truncate it around 15\-30 characters, depending on preference and typeface size. This is trivial with plain text using substr but with \s-1HTML\s0 it is somewhat difficult because whitespace has fluid significance and open tags that are not properly closed destroy well-formedness and can wreck an entire layout. .PP HTML::Truncate attempts to account for those two problems by padding truncation for spacing and entities and closing any tags that remain open at the point of truncation. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use strict; \& use HTML::Truncate; \& \& my $html = \*(Aq

We have to test something.

\*(Aq; \& my $readmore = \*(Aq... [readmore]\*(Aq; \& \& my $html_truncate = HTML::Truncate\->new(); \& $html_truncate\->chars(20); \& $html_truncate\->ellipsis($readmore); \& print $html_truncate\->truncate($html); \& \& # or \& \& use Encode; \& my $ht = HTML::Truncate\->new( utf8_mode => 1, \& chars => 1_000, \& ); \& print Encode::encode_utf8( $ht\->truncate($html) ); .Ve .SH "XHTML" .IX Header "XHTML" This module is designed to work with XHTML-style nested tags. More below. .SH "WHITESPACE AND ENTITIES" .IX Header "WHITESPACE AND ENTITIES" Repeated natural whitespace (i.e., \*(L"\es+\*(R" and not \*(L"   \*(R") in \s-1HTML\s0 \&\*(-- 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. .PP .Vb 2 \& \en

\enthis is ‘text’\en\en

\& ^^^^^^^12345\-\-\-\-678\-\-9\-\-\-\-\-\-01234\-\-\-\-\-\-^^^^^^^^ .Ve .SH "METHODS" .IX Header "METHODS" .IP "\fBnew\fR" 4 .IX Item "new" Can take all the methods as hash style args. \*(L"percent\*(R" and \*(L"chars\*(R" are incompatible so don't use them both. Whichever is set most recently will erase the other. .Sp .Vb 3 \& my $ht = HTML::Truncate\->new(utf8_mode => 1, \& chars => 500, # default is 100 \& ); .Ve .IP "\fButf8_mode\fR" 4 .IX Item "utf8_mode" Set/get, true/false. If \f(CW\*(C`utf8_mode\*(C'\fR is set, \f(CWutf8_mode(1)\fR 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 \f(CW\*(C`…\*(C'\fR. .IP "\fBchars\fR" 4 .IX Item "chars" Set/get. The number of characters remaining after truncation, \&\fBexcluding\fR the \*(L"ellipsis\*(R". .Sp Entities are counted as single characters. E.g., \f(CW\*(C`©\*(C'\fR is one character for truncation counts. .Sp Default is \*(L"100.\*(R" Side-effect: clears any \*(L"percent\*(R" that has been set. .IP "\fBpercent\fR" 4 .IX Item "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 \s-1HTML\s0 is parsed. .Sp Side-effect: clears any \*(L"chars\*(R" that has been set. .IP "\fBellipsis\fR" 4 .IX Item "ellipsis" Set/get. Ellipsis in this case means \-\- .Sp .Vb 3 \& The omission of a word or phrase necessary for a complete \& syntactical construction but not necessary for understanding. \& http://www.answers.com/topic/ellipsis .Ve .Sp What it will probably mean in most real applications is \*(L"read more.\*(R" The default is \f(CW\*(C`…\*(C'\fR which if the utf8 flag is true will render as a literal ellipsis, \f(CW\*(C`chr(8230)\*(C'\fR. .Sp The reason the default is \f(CW\*(C`…\*(C'\fR and not \*(L"...\*(R" is this is meant for use in \s-1HTML\s0 environments, not plain text, and \*(L"...\*(R" (dot-dot-dot) is not typographically correct or equivalent to a real horizontal ellipsis character. .IP "\fBtruncate\fR" 4 .IX Item "truncate" It returns the truncated \s-1XHTML\s0 if asked for a return value. .Sp .Vb 1 \& my $truncated = $ht\->truncate($html); .Ve .Sp It will truncate the string in place if no return value is expected (wantarray is not defined). .Sp .Vb 2 \& $ht\->truncate($html); \& print $html; .Ve .Sp Also can be called with inline arguments\- .Sp .Vb 3 \& print $ht\->truncate( $html, \& $chars_or_percent, \& $ellipsis ); .Ve .Sp No arguments are strictly required. Without \s-1HTML\s0 to operate upon it returns undef. The two optional arguments may be preset with the methods \*(L"chars\*(R" (or \*(L"percent\*(R") and \*(L"ellipsis\*(R". .Sp Valid nesting of tags is required (alla \s-1XHTML\s0). Therefore some old \&\s-1HTML\s0 habits like

without a

are not supported and may cause a fatal error. See \*(L"repair\*(R" for help with badly formed \&\s-1HTML.\s0 .Sp Certain tags are omitted by default from the truncated output. .RS 4 .IP "\(bu" 4 Skipped tags .Sp These will not be included in truncated output by default. .Sp .Vb 3 \& ...
...
\& ... \& .Ve .IP "\(bu" 4 Tags allowed to self-close .Sp See emptyElement in HTML::Tagset. .RE .RS 4 .RE .IP "\fBadd_skip_tags( qw( tag list ) )\fR" 4 .IX Item "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 \f(CW\*(C`

title

\*(C'\fR 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\*(-- .Sp .Vb 1 \& $ht\->add_skip_tags( \*(Aqh1\*(Aq ); .Ve .IP "\fBdont_skip_tags( qw( tag list ) )\fR" 4 .IX Item "dont_skip_tags( qw( tag list ) )" Takes tags out of the current list to be omitted from truncated output. .IP "\fBrepair\fR" 4 .IX Item "repair" Set/get, true/false. If true, will attempt to repair unclosed \s-1HTML\s0 tags by adding close-tags as late as possible (eg. \f(CW\*(C`foobar\*(C'\fR becomes \f(CW\*(C`foobar\*(C'\fR). Unmatched close tags are dropped (\f(CW\*(C`foobar\*(C'\fR becomes \f(CW\*(C`foobar\*(C'\fR). .IP "\fBon_space\fR" 4 .IX Item "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. \*(L"on_space\*(R" runs before \*(L"cleanly\*(R" if both are set. .IP "\fBcleanly\fR" 4 .IX Item "cleanly" Set/get \*(-- a regular expression. This is on by default and the default cleaning regular expression is \f(CW\*(C`cleanly(qr/[\es[:punct:]]+\ez/)\*(C'\fR. It will make the truncation strip any trailing spacing and punctuation so you don't get things like \*(L"The End....\*(R" or \*(L"What? ...\*(R" You can cancel it with \f(CW\*(C`$ht\->cleanly(undef)\*(C'\fR or provide your own regular expression. .SH "COOKBOOK (well, a recipe)" .IX Header "COOKBOOK (well, a recipe)" .SS "Template Toolkit filter" .IX Subsection "Template Toolkit filter" For excerpting \s-1HTML\s0 in your Templates. Note the \*(L"add_skip_tags\*(R" which is set to drop any images from the truncated output. .PP .Vb 2 \& use Template; \& use HTML::Truncate; \& \& my %config = \& ( \& FILTERS => { \& truncate_html => [ \e&truncate_html_filter_factory, 1 ], \& }, \& ); \& \& my $tt = Template\->new(\e%config) or die $Template::ERROR; \& \& # ... etc ... \& \& sub truncate_html_filter_factory { \& my ( $context, $len, $ellipsis ) = @_; \& $len = 32 unless $len; \& $ellipsis = chr(8230) unless defined $ellipsis; \& my $ht = HTML::Truncate\->new(); \& $ht\->add_skip_tags(qw( img )); \& return sub { \& my $html = shift || return \*(Aq\*(Aq; \& return $ht\->truncate( $html, $len, $ellipsis ); \& } \& } .Ve .PP Then in your templates you can do things like this: .PP .Vb 6 \& [% FOR item IN search_results %] \&
\& [% item.title %]
\& [% item.body | truncate_html(200) %] \&
\& [% END %] .Ve .PP See also Template::Filters. .SH "AUTHOR" .IX Header "AUTHOR" Ashley Pond V, \f(CW\*(C`\*(C'\fR. .SH "LIMITATIONS" .IX Header "LIMITATIONS" There may be places where this will break down right now. I'll pad out possible edge cases as I find them or they are sent to me via the \s-1CPAN\s0 bug ticket system. .SS "This is not an \s-1HTML\s0 filter" .IX Subsection "This is not an HTML filter" Although this happens to do some crude \s-1HTML\s0 filtering to achieve its end, it is not a fully featured filter. If you are looking for one, check out HTML::Scrubber and HTML::Sanitizer. .SH "BUGS, FEEDBACK, PATCHES" .IX Header "BUGS, FEEDBACK, PATCHES" Please report any bugs or feature requests to \&\f(CW\*(C`bug\-html\-truncate@rt.cpan.org\*(C'\fR, or through the web interface at . I will get the ticket, and then you'll automatically be notified of progress as I make changes. .SS "\s-1TO DO\s0" .IX Subsection "TO DO" Write a couple more tests (percent and skip stuff) then take out beta notice. Try to make the 5.6 stuff work without decode...? Try a \f(CW\*(C`drop_tags\*(C'\fR method? .PP Write an XML::LibXML based version to load when possible...? Or make that part of XHTML::Util? .SH "THANKS TO" .IX Header "THANKS TO" Kevin Riggle for the \*(L"repair\*(R" functionality; patch, Pod, and tests. .PP Lorenzo Iannuzzi for the \*(L"on_space\*(R" functionality. .SH "SEE ALSO" .IX Header "SEE ALSO" HTML::Entities, HTML::TokeParser, the \*(L"truncate\*(R" filter in Template, and Text::Truncate. .PP HTML::Scrubber and HTML::Sanitizer. .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright (X) 2005\-2009 Ashley Pond V. .PP This program is free software; you can redistribute it or modify it or both under the same terms as Perl itself. .SH "DISCLAIMER OF WARRANTY" .IX Header "DISCLAIMER OF WARRANTY" Because this software is licensed free of charge, there is no warranty for the software, to the extent permitted by applicable law. Except when otherwise stated in writing the copyright holders or other parties provide the software \*(L"as is\*(R" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the software is with you. Should the software prove defective, you assume the cost of all necessary servicing, repair, or correction. .PP In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who may modify and/or redistribute the software as permitted by the above licence, be liable to you for damages, including any general, special, incidental, or consequential damages arising out of the use or inability to use the software (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the software to operate with any other software), even if such holder or other party has been advised of the possibility of such damages.