.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "Strip 3pm"
.TH Strip 3pm "2011-11-15" "perl v5.14.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::Strip \- Perl extension for stripping HTML markup from text.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use HTML::Strip;
\&
\&  my $hs = HTML::Strip\->new();
\&
\&  my $clean_text = $hs\->parse( $raw_html );
\&  $hs\->eof;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module simply strips HTML-like markup from text in a very quick
and brutal manner. It could quite easily be used to strip \s-1XML\s0 or \s-1SGML\s0
from text as well; but removing \s-1HTML\s0 markup is a much more common
problem, hence this module lives in the \s-1HTML::\s0 namespace.
.PP
It is written in \s-1XS\s0, and thus about five times quicker than using
regular expressions for the same task.
.PP
It does \fInot\fR do any syntax checking (if you want that, use
HTML::Parser), instead it merely applies the following rules:
.IP "1." 4
Anything that looks like a tag, or group of tags will be replaced with
a single space character. Tags are considered to be anything that
starts with a \f(CW\*(C`<\*(C'\fR and ends with a \f(CW\*(C`>\*(C'\fR; with the caveat that a
\&\f(CW\*(C`>\*(C'\fR character may appear in either of the following without
ending the tag:
.RS 4
.IP "Quote" 4
.IX Item "Quote"
Quotes are considered to start with either a \f(CW\*(C`\*(Aq\*(C'\fR or a \f(CW\*(C`"\*(C'\fR character,
and end with a matching character \fInot\fR preceded by an even number or
escaping slashes (i.e. \f(CW\*(C`\e"\*(C'\fR does not end the quote but \f(CW\*(C`\e\e\e\e"\*(C'\fR does).
.IP "Comment" 4
.IX Item "Comment"
If the tag starts with an exclamation mark, it is assumed to be a
declaration or a comment. Within such tags, \f(CW\*(C`>\*(C'\fR characters do not
end the tag if they appear within pairs of double dashes (e.g. \f(CW\*(C`<!\-\-
<a href="old.htm">old page</a> \-\->\*(C'\fR would be
stripped completely).
.RE
.RS 4
.RE
.IP "2." 4
Anything the appears within so-called \fIstrip tags\fR is stripped as
well. By default, these tags are \f(CW\*(C`title\*(C'\fR, \f(CW\*(C`script\*(C'\fR, \f(CW\*(C`style\*(C'\fR and
\&\f(CW\*(C`applet\*(C'\fR.
.PP
HTML::Strip maintains state between calls, so you can parse a document
in chunks should you wish. If one chunk ends half-way through a tag,
quote, comment, or whatever; it will remember this, and expect the
next call to parse to start with the remains of said tag.
.PP
If this is not going to be the case, be sure to call \f(CW$hs\fR\->\fIeof()\fR
between calls to \f(CW$hs\fR\->\fIparse()\fR.
.SS "\s-1METHODS\s0"
.IX Subsection "METHODS"
.IP "\fInew()\fR" 4
.IX Item "new()"
Constructor. Can optionally take a hash of settings (with keys
corresponsing to the \f(CW\*(C`set_\*(C'\fR methods below).
.Sp
For example, the following is a valid constructor:
.Sp
.Vb 4
\& my $hs = HTML::Strip\->new(
\&                           striptags   => [ \*(Aqscript\*(Aq, \*(Aqiframe\*(Aq ],
\&                           emit_spaces => 0
\&                          );
.Ve
.IP "\fIparse()\fR" 4
.IX Item "parse()"
Takes a string as an argument, returns it stripped of \s-1HTML\s0.
.IP "\fIeof()\fR" 4
.IX Item "eof()"
Resets the current state information, ready to parse a new block of \s-1HTML\s0.
.IP "\fIclear_striptags()\fR" 4
.IX Item "clear_striptags()"
Clears the current set of strip tags.
.IP "\fIadd_striptag()\fR" 4
.IX Item "add_striptag()"
Adds the string passed as an argument to the current set of strip tags.
.IP "\fIset_striptags()\fR" 4
.IX Item "set_striptags()"
Takes a reference to an array of strings, which replace the current
set of strip tags.
.IP "\fIset_emit_spaces()\fR" 4
.IX Item "set_emit_spaces()"
Takes a boolean value. If set to false, HTML::Strip will not attempt
any conversion of tags into spaces. Set to true by default.
.IP "\fIset_decode_entities()\fR" 4
.IX Item "set_decode_entities()"
Takes a boolean value. If set to false, HTML::Strip will decode \s-1HTML\s0
entities. Set to true by default.
.SS "\s-1LIMITATIONS\s0"
.IX Subsection "LIMITATIONS"
.IP "Whitespace" 4
.IX Item "Whitespace"
Despite only outputting one space character per group of tags, and
avoiding doing so when tags are bordered by spaces or the start or
end of strings, HTML::Strip can often output more than desired; such
as with the following \s-1HTML:\s0
.Sp
.Vb 1
\& <h1> HTML::Strip </h1> <p> <em> <strong> fast, and brutal </strong> </em> </p>
.Ve
.Sp
Which gives the following output:
.Sp
\&\f(CW\*(C`\ HTML::Strip\ \ \ \ fast, and brutal\ \ \ \*(C'\fR
.Sp
Thus, you may want to post-filter the output of HTML::Strip to remove
excess whitespace (for example, using \f(CW\*(C`tr/ / /s;\*(C'\fR).
(This has been improved since previous releases, but is still an issue)
.IP "\s-1HTML\s0 Entities" 4
.IX Item "HTML Entities"
HTML::Strip will only attempt decoding of \s-1HTML\s0 entities if
HTML::Entities is installed.
.SS "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
None by default.
.SH "AUTHOR"
.IX Header "AUTHOR"
Alex Bowley <kilinrax@cpan.org>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perl, HTML::Parser, HTML::Entities