filter_add#

Install a source filter for the current package. Called from the filter module’s import.

Synopsis#

filter_add($object);     # method filter: $object is blessed state
filter_add(sub { ... }); # closure filter: anonymous sub

What you get back#

Nothing. filter_add registers the filter as a side effect; the compiler now routes every subsequent read through it until the filter calls filter_del or compilation of the enclosing file finishes.

The shape of the argument picks the filter style:

A CODE reference - closure filter. The sub is called for every compiler read; state lives in lexicals captured by the closure.
Anything else - method filter. If the argument is a plain scalar or an unblessed ARRAY / HASH reference, filter_add blesses a reference to it into the caller’s package, so the caller’s filter method receives it as $self. An already-blessed reference is used as-is.

Examples#

A closure filter installed from import:

sub import {
    filter_add(sub {
        my $status = filter_read();
        tr/a-z/A-Z/ if $status > 0;
        $status;
    });
}

A method filter that carries a substitution count as its state:

sub import {
    my $count = 0;
    filter_add(bless \$count); # becomes $self in filter()
}
sub filter {
    my ($self) = @_;
    my $status = filter_read();
    $$self++ if s/Joe/Jim/g && $status > 0;
    $status;
}

Edge cases#

filter_add looks up the caller’s package through caller, so it must be called from code in the filter module’s package, normally its import. Invoking it from a helper in another package will bless the state object into that package.
Source filters only act during compilation. Calling filter_add at runtime (outside any use/BEGIN chain) has no effect.
Passing a plain scalar or an unblessed ARRAY / HASH reference is legal: filter_add wraps and blesses the value for you. Any other unblessed reference, such as a SCALAR reference, is installed unblessed, and the first read dies with Can't call method "filter" on unblessed reference.

Differences from upstream#

Fully compatible with upstream Filter::Util::Call 1.65.