- SEE ALSO
- COPYRIGHT AND LICENSE
IO::Slice - restrict reads to a range in a file
use IO::Slice; # Define a slice based on a file my $sfh = IO::Slice->new( filename => '/path/to/file', offset => 13, length => 16, ); # Ditto, based on a previously available filehandle $fh. The # filehandle MUST be seekable. my $sfh = IO::Slice->new( fh => $fh, offset => 13, length => 16, ); # Both the filehandle and the filename can be provided. The # filehandle will win. my $sfh = IO::Slice->new( fh => $fh, filename => '/path/to/file', offset => 13, length => 16, ); # Whatever, you can use $sfh as any other filehandle, mostly.
This module allows the definition of a filehandle that only works on a slice of an input file. The
new method provides back a GLOB that can be used as any other filehandle, mostly, with the notable exception of some methods like
fileno and the tracking of the input lines.
my $sfh = IO::Slice->new( filename => '/path/to/file', offset => 13, length => 16, );
The provided handle works only for reading, not for writing.
The parameters that you can pass to the constructor are:
the source of data. This can be provided by either a filename (through the
filenamekey) or a filehandle (through the
fhkey). If both are provided, the filehandle will take precedence for getting the data.
offset, specifying an offset where the slice starts.
0means the start of the file
length, specifying the number of bytes in the slice
create a new IO::Slice object.
Parameters can be passed either as an hash reference or key-value pairs. Useful parameters are:
set the offset of the slice from the start of file. This is mandatory
set the length of the slice. This is mandatory.
length are tested for correctness against the file.
You have to provide at least one of
filename so that the data source can be reached. If you provide both,
fh will used for taking the data.
Returns the object. Throws an exception in case of errors.
open a slice. Parameters are the same as the "new" method.
close the tied handle and the associated object.
assess whether the object is associated to an opened file
support the binmode method... but in a fake way, does not accept anything actually.
get one byte from the input stream.
release one byte back into the input stream
test whether there are still bytes to read or we are at the end of the file
accessor for the position. It allows you to set the position by passing an input parameter, and to retrieve the current position.
set current position in the stream. Two positional parameters are accepted:
specifies the offset to use
specifies the reference point for applying the offset
Both are consistent with what you find in CORE::seek documentation.
get current position in the stream.
convenience function around
read. Takes as input the count of needed bytes and outputs a string that is the result of the underlying
read, without requiring you to provide a buffer.
get a line from the input. Returns a single scalar with one line.
$INPUT_RECORD_SEPARATOR), so line might not be what you generally consider a line.
list-version for getting lines, propedeutic to READLINE
read bytes from the stream. The interface is the same as the CORE::read function, with the following positional parameters:
optional parameter, used for putting data into the buffer
Returns undef if errors arise or end of file. Returns number of read characters otherwise (0 if end of file).
alias of "seek"
alias for "read"
The following functions are defined but don't actually do anything.
This module is heavily inspired (and in some places based) on code from "IO::String" 1.08 by Gisle Aas.
Flavio Poletti <email@example.com>
Copyright (C) 2014 by Flavio Poletti <firstname.lastname@example.org>
This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.