filter_read#

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

Σύνοψη#

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

Τι επιστρέφεται#

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.

Παραδείγματα#

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;
}

Οριακές περιπτώσεις#

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.

Διαφορές από το upstream#

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

Δείτε επίσης#

filter_read_exact - same, but insists on a full block.
filter_add - installs the filter that filter_read reads under.
filter_del - stops the current filter so subsequent reads go straight to the chain below.