NAME File::Bidirectional - Read a file line-by-line either forwards or backwards SYNOPSIS use File::Bidirectional; my $file = "/var/log/large_file"; # Object interface # start from the last line my $fh = File::Bidirectional->new($file, {origin => -1}) or die $!; # read backwards until point of interest while (my $line = $fh->readline()) { last if $line =~ /RECORD_START/; } # switch directions $fh->switch(); # read forwards until point of interest while (my $line = $fh->readline()) { last if $line =~ /RECORD_END/; } # Tied Handle Interface local *F; tie *F, "File::Bidirectional", $file, {origin => 1} or die $!; while (my $line = ) { ... } (tied *F)->switch(); DESCRIPTION File::Bidirectional reads a file line-by-line in either the forwards or backwards direction. It supports an object interface as well as a tied filehandle interface, and should be straight-forward to use. It is also memory efficient, since it is intended to be used on files too large to be efficiently slurped into an array and traversed backwards. The direction in which to traverse the file can be changed at anytime, but it is important to note that the last-read line will be repeated when this happens. See "line_num" to see why this is so. On non-Unix platforms, this module attempts to immitate native Perl in converting the line endings. Currently, this is limited and untested, so please see "LINE ENDINGS" for more information. MOTIVATION I had a "diff" file describing the changes in a large (> 200MB) file. Based on the line numbers in the "diff", I have to repeatedly read backwards and forwards in the large file to obtain the context lines before and after the "diff" changes. The number of context lines vary, thus it was a little more involved than regenerating the "diff" with an appropriate "--context" option. I decided to publish this module as I thought others might have similar needs. Reading large log files backwards is probably the most common of these, but if you have any other interesting uses, do let me know. CONSTRUCTOR (CLASS METHODS) new $file, \%option $fh = File::Bidirectional->new($file); $fh = File::Bidirectional->new($file, {mode => 'forward'}); $fh = File::Bidirectional->new($file, {mode => 'backward'}); $fh = File::Bidirectional->new($file, {origin => -1}); $fh = File::Bidirectional->new($file, \%option); Has the file name as the first parameter, and a hashref of options as an optional second parameter. Upon success, it will return the object. For invalid parameters, it will "Carp/croak". For "sysopen" in perlfunc errors, it returns undef and sets the error code in "$!" in perlvar. The list of valid options are: mode Can be either "bi" (bi-directional), "forward" or "backward". The "forward" and "backward" modes are restrictive: the file is read from the first and last line respectively, and switching directions is prohibited. The "bi" mode allows direction switching, and will start from the first line by default (use the "origin" option to change that.) The default is "bi". origin Can be either 1 or -1. These denote whether the first or last line of the file is considered as line 1 by "line_num". ("readline" will always start from line 1.) "origin" can only be set if the "mode" option is "bi". The default is 1. binmode Can be any true or false expression. It is analogous to the "binmode" in perlfunc built-in function. On systems that distinguish between binary and text files, notably DOS and Windows-based systems, this is important. A true value will preserve "\r\n" as is; a false value will convert "\r\n" to "\n". The default is false. separator Can be any scalar string. It is analogous to the "$/" in perlvar variable. "separator" determines "File::Bidirectional"'s notion of what a line is. The default is "$/" in perlvar, which in turn defaults to "\n". Caveat: The Perl-ish magic that occurs when "$/" in perlvar is "" does not happen yet. regex Can be any true or false expression. It determines whether the "separator" option is a regex or a string. The default is false. block_size Can be any positive integer. This is the size of a single block read by the underlying "sysread" in perlfunc. The default is 8192. INSTANCE METHODS readline while (my $line = $fh->readline()) { ... } Returns the subsequent line. This refers either to the next line when the direction is forwards, or to the previous line when the direction is backwards. The direction can be changed with "switch". "undef" is returned when there are no more lines to be read. getline An alias for "readline". It exists for compatability with the IO::* classes. eof Returns true when "readline" will return an "undef", false otherwise. switch $fh->switch(); Switches the current direction in which we are reading the file. It will "croak" in Carp if the "mode" option in the constructor is set to "forward" or "backward". Note that switching directions will cause the last-read line to be repeated by "readline". close $fh->close(); Closes the underlying filehandle and releases the memory allocated for its buffer. On success it returns true, otherwise it returns false with the error code found in "$!" in perlvar. All subsequent "readline" calls will return undef, and "line_num", its last value. direction $direction Takes an optional parameter: 1 for reading forwards, -1 for reading backwards, "croak" in Carp otherwise. If an argument for the parameter is provided, the direction will be switched if necessary. Either way, it returns the (new) direction. line_num my $fh=File::Bidirectional->new($file); n=$fh->line_num(); # n = 0 $fh->readline(); n=$fh->line_num(); # n = 1 $fh->readline(); n=$fh->line_num(); # n = 2 $fh->switch(); n=$fh->line_num(); # n = 2 $fh->readline(); n=$fh->line_num(); # n = 1 $fh->readline(); n=$fh->line_num(); # n = 0 Returns the current line number. It is analogous to "$." in perlvar. For a file with *n* logical lines, the line number ranges from 0 to *n*. When reading away from the origin (forwards if the first line is the origin), its behavior is always identical to that of "$." in perlvar - it refers to the number of lines that has been read. When reading towards the origin, it refers to the number of lines that can still be read. When "switch" is called, the direction is changed, but the line number remains the same. Therefore, the last-read line before changing directions will be repeated by "readline". tell Returns the current position of the filehandle. fh Returns the underlying filehandle. This is mainly useful for file-locking. Notice that this actually breaks the encapsulation of File::Bidirectional, therefore it becomes the user's responsibility to ensure that nothing bad happens to the underlying filehandle. For example, it should definitely not be closed. The underlying filehandle will be returned with its seek position set to what is returned by "tell". It should generally be okay for this seek position to be modified (the object remembers its own seek position and will always restore it). Any other operations on the filehandle, however, is very likely to void your warranty. =) TIED HANDLE INTERFACE local *F; tie *F, "File::Bidirectional", $file, {origin => 1} or die $!; while (my $line = ) { ... } (tied *F)->switch(); The "TIEHANDLE", "READLINE", "EOF", "CLOSE" and "TELL" are aliased to the constructor and the lower-case method names, respectively. All other tied operations, such as seeking and writing, are unsupported and will generate an unknown method area. To use the other methods, it is necessary to get at the reference to the object underlying the tied variable via "tied" in perlfunc. LINE ENDINGS Currently, File::Bidirectional attempts to imitate Perl by converting the platform-specific line separator into "\n". Currently, this only means converting "\r" on MacOS, and "\r\n" on DOS and Windows-type systems (when the "binmode" option is not set). So far, this module has only been tested on Unix where line endings do not need to be converted, thus it will be greatly appreciated if users can feedback whether the line endings conversion work on their respective platforms. BENCHMARKS As would be expected, File::Bidirectional is hardly as fast as native Perl I/O. To break the news gently, it can be up to an order of magnitude slower... Reading through a 250MB file with various methods yield the following numbers: Method | Time (s) -------------------------------------- Native Perl | 5 IO::File | 16 File::Bidirectional (OO) | 42 File::Bidirectional (tied) | 51 To be optimistic about it, in the best case File::Bidirectional takes 2.6 times the time taken for IO::File. For smaller files, the absolute time difference may be less noticeable, so you will have to decide if the tradeoff is worth it for your application. It is about as fast as I can make it without dropping down into C, but if anybody has a compelling need for speed or ideas on how to optimize things, please do drop me a line. The benchmarks were performed circa 2005, on a Pentium-4 machine with clockspeed 2.8GHz, a 7200rpm IDE harddisk, running Debian sarge and ext3. The programs tested were the respective variants of while (my $line = <$fh>) { chomp $line; } The record separator was simply "\n" and no newline translation took place. AUTHOR Kian Win Ong, cpan@bulk.squeakyblue.com COPYRIGHT Copyright (C) 2005 by Kian Win Ong. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This can be either the GNU General Public License or the Artistic License, as specified in the Perl README file. ACKNOWLEDGEMENTS Thanks goes out to Uri Guttman, the author of File::ReadBackwards, from which I stole a bunch of code and tests. =)