The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Array-LineReader-1.01
River stage zero No dependents
++
/ Array::LineReader

NAME

Array::LineReader - Access lines of a file via an array

SYNOPSIS

  use Array::LineReader;
  my @lines;
  
  # Get the content of every line as an element of @lines:
  tie @lines, 'Array::LineReader', 'filename';
  print scalar(@lines);         # number of lines in the file
  print $lines[0];              # content of the first line
  print $lines[-1];             # content of the last line
  ...
  
  # Get the offset and content of every line as array reference via the elements of @lines:
  tie @lines, 'Array::LineReader', 'filename', result=>[];
  print scalar(@lines);         # number of lines in the file
  print $lines[5]->[0],":",$lines[5]->[1];      # offset and content of the 5th line
  print $lines[-1]->[0],":",$lines[-1]->[1];    # offset and content of the last line
  ...
  
  # Get the offset and content of every line as hash reference via the elements of @lines:
  tie @lines, 'Array::LineReader', 'filename', result=>{};
  print scalar(@lines);         # number of lines in the file
  print $lines[4]->{OFFSET},":",$lines[4]->{CONTENT};   # offset and content of the 4th line
  print $lines[-1]->{OFFSET},":",$lines[-1]->{CONTENT}; # offset and content of the last line
  ...

VERSION and VOLATILITY

        $Revision: 1.1 $
        $Date: 2004/06/10 18:17:23 $

DESCRIPTION

Array::LineReader gives you the possibility to access lines of some file by the elements of an array. This modul inherites methods from Tie::Array (see Tie::Array). You save a lot of memory, because the file's content is read only on demand, i.e. in the case you access an element of the array. The offset and length of all the lines is hold in memory as long as you tie your array.

The underlying file is opened for reading in binary mode. (Yes, there are some OSs, that make a difference in interpreting the EOL-sequence, i.e. End-Of-Line and the EOF-character, i.e. End-Of-File what is the character "\x1A"). The bytes read are neigther translated nor suppressed.

Lines are build up to and including the EOL-sequence. The EOL-sequence is assumed to be "\x0D\x0A" or "\x0A\x0D" or "\x0D" or "\x0A".

The file is not closed until you untie the array.

It's up to you to define the kind of access:

Access content by element

        tie @lines, 'Array::LineReader', 'filename';

You get the content of every line of the file by the elements of the array @lines:

        print "@lines";

Access offset and content by array references

        tie @lines, 'Array::LineReader', 'filename', result=>[];

You get offset and content of every line of the file via the elements of the array @lines:

        foreach (@lines){
                print $_->[0],":";      # offset
                print $_->[1];          # content
        }

Access offset and content by hash references

        tie @lines, 'Array::LineReader', 'filename', result=>{};

You get offset and content of every line of the file via the elements of the array @lines:

        foreach (@lines){
                print $_->{OFFSET},":"; # offset
                print $_->{CONTENT};    # content
        }

METHODS

TIEARRAY

TIEARRAY Create this class

Overwrites the method TIEARRAY of Tie::Array (see Tie::Array). You never should have to call it. It is used to create this class.

This method croaks if the filename is missing. It croaks too if the additional parameters do not have the form of a hash, i.e. have an odd number.

The file is opened in binary mode for reading only. If the file does not exist or can not be opened you will get an emtpy array without a warning.

The offset of every line and its length is hold in arrays corresponding to the lines of the file. The content of a given line is read only if you access the corresponding element of the tied array.

FETCHSIZE

FETCHSIZE Define the size of the tied array.

Overwrites the method FETCHSIZE of Tie::Array (see Tie::Array). You never should have to call it. This method is called any time the size of the underlying array has to be defined.

The size of the tied array is defined to be the number of lines read so far.

Lets have an example:

        tie @lines, 'Array::LineReader', 'filename';
        $line5 = $lines[4];     # access the 5th line.
        print scalar(@lines);   # prints: 5
        $lastline = $lines[-1]; # access the last line of the file
        print scalar(@lines);   # prints: number of lines in the file

FETCH

FETCH access a specified element of the tied array

Overwrites the method FETCH of Tie::Array (see Tie::Array). You never should have to call it. This method is called any time you want to access a given element of the tied array.

If you access an already known element, the offset of the line to read is sought and the line is read with the already known length. If you access a not yet known element, the file is read up to the corresponding line.

Lets have an example:

        tie @lines, 'Array::LineReader', 'filename';
        foreach (@lines){
                print $_;       # access one line after the other
        }
        ...
        print $lines[5];        # seeks the offset of the 6th line and reads it

You should use the tie command with additional parameter defining the type of the result, if you want to have access not only to the content of a line but also to its offset.

        tie @lines, 'Array::LinesReader', 'filename', result=>{};
        print $lines[8]->{OFFSET};      # Offset of the 9th line.
        print $lines[8]->{CONTENT};     # Content of the 9th line.

or to get the offset and content by reference to an array:

        tie @lines, 'Array::LinesReader', 'filename', result=>[];
        print $lines[8]->[0];   # Offset of the 9th line.
        print $lines[8]->[1];   # Content of the 9th line.

DESTROY

DESTROY

Overwrites the method DESTROY of Tie:Array (see Tie::Array). Closes the file to free some memory.

EXISTS

EXISTS

Overwrites the method EXISTS of Tie::Array (see Tie::Array). Returns true if the array's element was already read.

EXPORT

None by default.

SEE ALSO

Array::FileReader, Tie::Array, Tie::File

HISTORY

 * $Log: LineReader.pm,v $
 * Revision 1.1  2004/06/10 15:07:37  Bjoern_Holsten
 * First stable (as seems) version
 *

AUTHOR

Bjoern Holsten <bholsten + At + cpan + DoT + org>

COPYRIGHT AND LICENSE

Copyright (C) 2004 by Bjoern Holsten

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6.0 or, at your option, any later version of Perl 5 you may have available.