new

    my $scrubber = HTML::Scrubber->new( allow => [ qw[ p b i u hr br ] ] );

Build a new HTML::Scrubber. The arguments are the initial values for the following directives:-

• default
• allow
• deny
• rules
• process
• comment

comment

    warn "comments are  ", $p->comment ? 'allowed' : 'not allowed';
    $p->comment(0);  # off by default

process

    warn "process instructions are  ", $p->process ? 'allowed' : 'not allowed';
    $p->process(0);  # off by default

script

    warn "script tags (and everything in between) are supressed"
        if $p->script;      # off by default
    $p->script( 0 || 1 );

** Please note that this is implemented using HTML::Parser's "ignore_elements" function, so if "script" is set to true, all script tags encountered will be validated like all other tags.

style

    warn "style tags (and everything in between) are supressed"
        if $p->style;       # off by default
    $p->style( 0 || 1 );

** Please note that this is implemented using HTML::Parser's "ignore_elements" function, so if "style" is set to true, all style tags encountered will be validated like all other tags.

allow

    $p->allow(qw[ t a g s ]);

deny

    $p->deny(qw[ t a g s ]);

rules

    $p->rules(
        img => {
            src => qr{^(?!http://)}i, # only relative image links allowed
            alt => 1,                 # alt attribute allowed
            '*' => 0,                 # deny all other attributes
        },
        a => {
            href => sub { ... },      # check or adjust with a callback
        },
        b => 1,
        ...
    );

Updates a set of attribute rules. Each rule can be 1/0, a regular expression or a callback. Values longer than 1 char are treated as regexps. The callback is called with the following arguments: the current object, tag name, attribute name, and attribute value; the callback should return an empty list to drop the attribute, "undef" to keep it without a value, or a new scalar value.

default

    print "default is ", $p->default();
    $p->default(1);      # allow tags by default
    $p->default(
        undef,           # don't change
        {                # default attribute rules
            '*' => 1,    # allow attributes by default
        }
    );

scrub_file

    $html = $scrubber->scrub_file('foo.html');   ## returns giant string
    die "Eeek $!" unless defined $html;  ## opening foo.html may have failed
    $scrubber->scrub_file('foo.html', 'new.html') or die "Eeek $!";
    $scrubber->scrub_file('foo.html', *STDOUT)
        or die "Eeek $!"
            if fileno STDOUT;

scrub

    print $scrubber->scrub($html);  ## returns giant string
    $scrubber->scrub($html, 'new.html') or die "Eeek $!";
    $scrubber->scrub($html', *STDOUT)
        or die "Eeek $!"
            if fileno STDOUT;

default handler, used by both "_scrub" and "_scrub_fh". Moved all the common code (basically all of it) into a single routine for ease of maintenance.

default handler, does the scrubbing if we're scrubbing out to a file. Now calls "_scrub_str" and pushes that out to a file.

default handler, does the scrubbing if we're returning a giant string. Now calls "_scrub_str" and appends that to the output string.

EXAMPLE

    #!/usr/bin/perl -w
    use HTML::Scrubber;
    use strict;

    my @allow = qw[ br hr b a ];

    my @rules = (
        script => 0,
        img    => {
            src => qr{^(?!http://)}i,    # only relative image links allowed
            alt => 1,                    # alt attribute allowed
            '*' => 0,                    # deny all other attributes
        },
    );

    my @default = (
        0 =>                             # default rule, deny all tags
            {
            '*'    => 1,                             # default rule, allow all attributes
            'href' => qr{^(?:http|https|ftp)://}i,
            'src'  => qr{^(?:http|https|ftp)://}i,

            #   If your perl doesn't have qr
            #   just use a string with length greater than 1
            'cite'        => '(?i-xsm:^(?:http|https|ftp):)',
            'language'    => 0,
            'name'        => 1,                                 # could be sneaky, but hey ;)
            'onblur'      => 0,
            'onchange'    => 0,
            'onclick'     => 0,
            'ondblclick'  => 0,
            'onerror'     => 0,
            'onfocus'     => 0,
            'onkeydown'   => 0,
            'onkeypress'  => 0,
            'onkeyup'     => 0,
            'onload'      => 0,
            'onmousedown' => 0,
            'onmousemove' => 0,
            'onmouseout'  => 0,
            'onmouseover' => 0,
            'onmouseup'   => 0,
            'onreset'     => 0,
            'onselect'    => 0,
            'onsubmit'    => 0,
            'onunload'    => 0,
            'src'         => 0,
            'type'        => 0,
            }
    );

    my $scrubber = HTML::Scrubber->new();
    $scrubber->allow(@allow);
    $scrubber->rules(@rules);    # key/value pairs
    $scrubber->default(@default);
    $scrubber->comment(1);       # 1 allow, 0 deny

    ## preferred way to create the same object
    $scrubber = HTML::Scrubber->new(
        allow   => \@allow,
        rules   => \@rules,
        default => \@default,
        comment => 1,
        process => 0,
    );

    require Data::Dumper, die Data::Dumper::Dumper($scrubber) if @ARGV;

    my $it = q[
        <?php   echo(" EVIL EVIL EVIL "); ?>    <!-- asdf -->
        <hr>
        <I FAKE="attribute" > IN ITALICS WITH FAKE="attribute" </I><br>
        <B> IN BOLD </B><br>
        <A NAME="evil">
            <A HREF="javascript:alert('die die die');">HREF=JAVA &lt;!&gt;</A>
            <br>
            <A HREF="image/bigone.jpg" ONMOUSEOVER="alert('die die die');">
                <IMG SRC="image/smallone.jpg" ALT="ONMOUSEOVER JAVASCRIPT">
            </A>
        </A> <br>
    ];

    print "#original text", $/, $it, $/;
    print
        "#scrubbed text (default ", $scrubber->default(),    # no arguments returns the current value
        " comment ", $scrubber->comment(), " process ", $scrubber->process(), " )", $/, $scrubber->scrub($it), $/;

    $scrubber->default(1);                                   # allow all tags by default
    $scrubber->comment(0);                                   # deny comments

    print
        "#scrubbed text (default ",
        $scrubber->default(),
        " comment ",
        $scrubber->comment(),
        " process ",
        $scrubber->process(),
        " )", $/,
        $scrubber->scrub($it),
        $/;

    $scrubber->process(1);    # allow process instructions (dangerous)
    $default[0] = 1;          # allow all tags by default
    $default[1]->{'*'} = 0;   # deny all attributes by default
    $scrubber->default(@default);    # set the default again

    print
        "#scrubbed text (default ",
        $scrubber->default(),
        " comment ",
        $scrubber->comment(),
        " process ",
        $scrubber->process(),
        " )", $/,
        $scrubber->scrub($it),
        $/;

FUN

    pod2test Scrubber.pm >scrubber.t
    perl scrubber.t

Perldoc

  perldoc HTML::Scrubber

Websites

• MetaCPAN

  A modern, open-source CPAN search engine, useful to view POD in HTML format.

  <https://metacpan.org/release/HTML-Scrubber>

• Search CPAN

  The default CPAN search engine, useful to view POD in HTML format.

  <http://search.cpan.org/dist/HTML-Scrubber>

• RT: CPAN's Bug Tracker

  The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.

  <https://rt.cpan.org/Public/Dist/Display.html?Name=HTML-Scrubber>

• AnnoCPAN

  The AnnoCPAN is a website that allows community annotations of Perl module documentation.

  <http://annocpan.org/dist/HTML-Scrubber>

• CPAN Ratings

  The CPAN Ratings is a website that allows community ratings and reviews of Perl modules.

  <http://cpanratings.perl.org/d/HTML-Scrubber>

• CPANTS

  The CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution.

  <http://cpants.cpanauthors.org/dist/HTML-Scrubber>

• CPAN Testers

  The CPAN Testers is a network of smoke testers who run automated tests on uploaded CPAN distributions.

  <http://www.cpantesters.org/distro/H/HTML-Scrubber>

• CPAN Testers Matrix

  The CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms.

  <http://matrix.cpantesters.org/?dist=HTML-Scrubber>

• CPAN Testers Dependencies

  The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution.

  <http://deps.cpantesters.org/?module=HTML::Scrubber>

Bugs / Feature Requests

Source Code

<https://github.com/nigelm/html-scrubber>

  git clone https://github.com/nigelm/html-scrubber.git