.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. 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 >0, 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
.\" ========================================================================
.\"
.IX Title "Strip 3"
.TH Strip 3 2023-07-25 "perl v5.38.0" "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 rapidly and
brutally. It could easily be used to strip XML or SGML markup
instead \- but as removing HTML is a much more common problem, this
module lives in the HTML:: namespace.
.PP
It is written in XS, 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`old page \-\->\*(C'\fR
would be stripped completely). No parsing for quotes is performed
within comments, so for instance
\&\f(CW\*(C`\*(C'\fR
would be entirely stripped.
.RE
.RS 4
.RE
.IP 2. 4
Anything that appears between tags which we term \fIstrip tags\fR is removed.
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 a call to \f(CWparse()\fR ends half-way through
a tag, quote or comment; the next call to \f(CWparse()\fR expects its input to
carry on from that point.
.PP
If this is not the behaviour you want, you can either call \f(CWeof()\fR
between calls to \f(CWparse()\fR, or set \f(CW\*(C`auto_reset\*(C'\fR to true (either
on the constructor or with \f(CW\*(C`set_auto_reset\*(C'\fR) so that the parser will
reset after each call.
.SS METHODS
.IX Subsection "METHODS"
.IP \fBnew()\fR 4
.IX Item "new()"
Constructor. Can optionally take a hash of settings (with keys
corresponding to the \f(CW\*(C`set_\*(C'\fR methods below).
.Sp
Example:
.Sp
.Vb 4
\& my $hs = HTML::Strip\->new(
\& striptags => [ \*(Aqscript\*(Aq, \*(Aqiframe\*(Aq ],
\& emit_spaces => 0
\& );
.Ve
.IP \fBparse()\fR 4
.IX Item "parse()"
Takes a string as an argument, returns it stripped of HTML.
.IP \fBeof()\fR 4
.IX Item "eof()"
Resets the current state information, ready to parse a new block of HTML.
.IP \fBclear_striptags()\fR 4
.IX Item "clear_striptags()"
Clears the current set of strip tags.
.IP \fBadd_striptag()\fR 4
.IX Item "add_striptag()"
Adds the string passed as an argument to the current set of strip tags.
.IP \fBset_striptags()\fR 4
.IX Item "set_striptags()"
Takes a reference to an array of strings, which replace the current
set of strip tags.
.IP \fBset_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 \fBset_emit_newlines()\fR 4
.IX Item "set_emit_newlines()"
Takes a boolean value. If set to true, HTML::Strip will output newlines
after \f(CW\*(C`
\*(C'\fR and \f(CW\*(C`
\*(C'\fR tags. Set to false by default. .IP \fBset_decode_entities()\fR 4 .IX Item "set_decode_entities()" Takes a boolean value. If set to false, HTML::Strip will not decode HTML entities. Set to true by default. .IP \fBfilter_entities()\fR 4 .IX Item "filter_entities()" If HTML::Entities is available, this method behaves just like invoking HTML::Entities::decode_entities, except that it respects the current setting of 'decode_entities'. .IP \fBset_filter()\fR 4 .IX Item "set_filter()" Sets a filter to be applied after tags were stripped. It may accept the name of a method (like 'filter_entities') or a code ref. By default, its value is 'filter_entities' if HTML::Entities is available or \f(CW\*(C`undef\*(C'\fR otherwise. .IP \fBset_auto_reset()\fR 4 .IX Item "set_auto_reset()" Takes a boolean value. If set to true, \f(CW\*(C`parse\*(C'\fR resets after each call (equivalent to calling \f(CW\*(C`eof\*(C'\fR). Otherwise, the parser remembers its state from one call to \f(CW\*(C`parse\*(C'\fR to another, until you call \f(CW\*(C`eof\*(C'\fR explicitly. Set to false by default. .IP \fBset_debug()\fR 4 .IX Item "set_debug()" Outputs extensive debugging information on internal state during the parse. Not intended to be used by anyone except the module maintainer. .IP \fBdecode_entities()\fR 4 .IX Item "decode_entities()" .PD 0 .IP \fBfilter()\fR 4 .IX Item "filter()" .IP \fBauto_reset()\fR 4 .IX Item "auto_reset()" .IP \fBdebug()\fR 4 .IX Item "debug()" .PD Readonly accessors for their respective settings. .SS LIMITATIONS .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 HTML: .Sp .Vb 1 \&
fast, and brutal
.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 "HTML Entities" 4 .IX Item "HTML Entities" HTML::Strip will only attempt decoding of HTML entities if HTML::Entities is installed. .SS EXPORT .IX Subsection "EXPORT" None by default. .SH AUTHOR .IX Header "AUTHOR" Alex Bowley