filter_read#

Pull the next line of source — or up to a given number of bytes — from the filter chain into $_.

Synopsis#

my $status = filter_read();        # line mode
my $status = filter_read($size);   # block mode, up to $size bytes

What you get back#

An integer status, three-valued:

> 0 — more source was appended to $_.
= 0 — EOF: no more source is available from anything below this filter in the chain.
< 0 — a read error occurred.

The data is appended to $_, not returned. The caller’s filter body then transforms $_ and hands it back to the compiler by returning the same status.

In block mode, filter_read($size) may return fewer than $size bytes — short reads are normal. Use filter_read_exact when the filter needs a guaranteed block size.

Examples#

A minimal filter that rewrites Joe to Jim line by line:

sub filter {
    my $status = filter_read();
    s/Joe/Jim/g if $status > 0;
    $status;
}

Block mode, processing a chunk at a time:

sub filter {
    my $status = filter_read(4096);
    s/secret/*****/g if $status > 0;
    $status;
}

Edge cases#

Calling filter_read from outside a filter’s body (for example at module top level) has no useful effect — no parser is active to read from.
On EOF, $_ may still contain buffered data from an earlier partial read; the caller decides whether to flush it.

Differences from upstream#

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