NAME

Data::LineBuffer - provide a line oriented data push back facility for input sources

SYNOPSIS

use Data::LineBuffer;

$fh = new IO::File $file;
$src = new Data::LineBuffer $fh;

$src = new Data::LineBuffer $scalar;

$src = new Data::LineBuffer \@array;

$src = new Data::LineBuffer \⊂

$next_line = $src->get;

$src->unget( @lines_i_wish_i_hadnt_gotten );

print "We just read line", $src->pos, "\n";

DESCRIPTION

Data::LineBuffer provides a very rudimentary input push back facility. It provides a layer between the input source and the calling routine which allows data to be pushed back onto the input source for retrieval, as a last in, first out, stack.

It is only concerned with line-oriented data, and can interface with a filehandle, a subroutine (which returns data), a string containing multiple lines to be parsed, or an array of lines. In order to provide a uniform interface, all returned input is chomp()'d.

As an example, consider the following code:

use Data::LineBuffer;

my $src = new Data::LineBuffer "Line 1\nLine 2\nLine 3\nLine 4\n";

print $src->get, "\n";
print $src->get, "\n";
$src->unget( "Oh Happy Day!" );
$src->unget( "I Sing with Joy!" );
print $src->get, "\n";
print $src->get, "\n";
print $src->get, "\n";

This produces the following output:

Line 1
Line 2
I Sing with Joy!
Oh Happy Day!
Line 3
Line 4

Constructors

new

$src = new Data::LineBuffer $fh;
$src = new Data::LineBuffer $scalar;
$src = new Data::LineBuffer \@array;
$src = new Data::LineBuffer \⊂
 

The constructor can take a filehandle, a subroutine, a scalar, or an array. It returns undefined if an error ocurred, which currently occurs only if it is passed a type not in the above list.

Each element of an array source is considered a single line, regardless of the number of actual lines in the element.

Scalar sources are chopped up (figuratively) into separate lines.

Subroutines should return the next line or undef if there are no more.

Methods

get

$line = $src->get;

This returns the next line from the input source. The line is chomp()'d before being returned. It returns the undefined value when input has been exhausted.

Do not test for end of input like this,

while ( $_ = $src->get() )  # WRONG! DON'T DO THIS!

as empty lines or lines which resolve to a numeric value of zero will fail this test. Instead, ensure that the result is defined:

while ( defined( $_ = $src->get()) )  # CORRECT! DO THIS!

unget

$src->unget( $line );
$src->unget( @lines );

This pushes one or more lines back onto the input source. Lines will be returned by get() in the reverse order in which they were pushed, i.e. Last In First out.

pos

my $pos

This returns the current line position in the source. This is the line number of the next line to be read.

EXPORT

None by default.

LIMITATIONS

All of the cached data is stored in memory.

The scalar's search position (see the pos Perl function) is used to keep track of the next line. Don't muck about with the scalar (or do any regexp's on it) or you'll confuse this poor module.

LICENSE

This software is released under the GNU General Public License. You may find a copy at

http://www.fsf.org/copyleft/gpl.html

AUTHOR

Diab Jerius (djerius@cpan.org)