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.