NAME

File::ReadBackwards.pm -- Read a file backwards by lines.

SYNOPSIS

    use File::ReadBackwards ;

    # Object interface

    $bw = File::ReadBackwards->new( 'log_file' ) or
			die "can't read 'log_file' $!" ;

    while( defined( $log_line = $bw->readline ) ) {
	    print $log_line ;
    }

    # Tied Handle Interface

    tie *BW, File::ReadBackwards, 'log_file' or
			die "can't read 'log_file' $!" ;

    while( <BW> ) {
	    print ;
    }

DESCRIPTION

This module reads a file backwards line by line. It is simple to use, memory efficient and fast. It supports both an object and a tied handle interface.

It is intended for processing log and other similar text files which typically have their newest entries appended to them. By default files are assumed to be plain text and have a line ending appropriate to the OS. But you can set the input record separator string on a per file basis.

OBJECT INTERFACE

There are only 2 methods in Backwards' object interface, new and readline.

new( $file, [$rec_sep] )

New takes as arguments a filename and an optional record separator. It either returns the object on a successful open or undef upon failure. $! is set to the error code if any.

readline

Readline takes no arguments and it returns the previous line in the file or undef when there are no more lines in the file.

TIED HANDLE INTERFACE

tie( *HANDLE, File::ReadBackwards, $file, [$rec_sep] )

The TIEHANDLE and READLINE methods are aliased to the new and readline methods respectively so refer to them for their arguments and API. Once you have tied a handle to File::ReadBackwards the only operation permissible is <> which will read the previous line. All other tied handle operations will generate an unknown method error. Do not seek, write or perform any other operation other than <> on the tied handle.

LINE AND RECORD ENDINGS

Since this module needs to use low level I/O for efficiency, it can't portably seek and do block I/O without managing line ending conversions. This module supports the default record separators of normal line ending strings used by the OS. You can also set the separator on a per file basis.

Only if the record separator is not specified and it defaults to CR/LF (e.g, VMS, redmondware) will it will be converted to a single newline. Unix and MacOS files systems use only a single character for line endings and the lines are left unchanged. This means that for native text files, you should be able to process their lines backwards without any problems with line endings. If you specify a record separator, no conversions will be done and you will get the records as if you read them in binary mode.

DESIGN

It works by reading a large (8kb) block of data from the end of the file. It then splits them on the record separator and stores a list of records in the object. Each call to readline returns the top record of the list and if the list is empty it refills it by reading the previous block from the file and splitting it. When the beginning of the file is reached and there are no more lines, undef is returned. All boundary conditions are handled correctly i.e. if there is a trailing partial line (no newline) it will be the first line returned and lines larger than the read buffer size are handled properly.

NOTES

There is no support for list context in either the object or tied interfaces. If you want to slurp all of the lines into an array in backwards order (and you don't care about memory usage) just do:

@back_lines = reverse <FH>.

This module is only intended to read one line at a time from the end of a file to the beginning.

AUTHOR

Uri Guttman, uri@sysarch.com

COPYRIGHT

Copyright (C) 2000 by Uri Guttman. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.