.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "ReadBackwards 3pm"
.TH ReadBackwards 3pm "2018-03-30" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
File::ReadBackwards.pm \-\- Read a file backwards by lines.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use File::ReadBackwards ;
\&
\&    # Object interface
\&
\&    $bw = File::ReadBackwards\->new( \*(Aqlog_file\*(Aq ) or
\&                        die "can\*(Aqt read \*(Aqlog_file\*(Aq $!" ;
\&
\&    while( defined( $log_line = $bw\->readline ) ) {
\&            print $log_line ;
\&    }
\&
\&    # ... or the alternative way of reading
\&
\&    until ( $bw\->eof ) {
\&            print $bw\->readline ;
\&    }
\&
\&    # Tied Handle Interface
\&
\&    tie *BW, \*(AqFile::ReadBackwards\*(Aq, \*(Aqlog_file\*(Aq or
\&                        die "can\*(Aqt read \*(Aqlog_file\*(Aq $!" ;
\&
\&    while( <BW> ) {
\&            print ;
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
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
\&\s-1OS.\s0 But you can set the input record separator string on a per file
basis.
.SH "OBJECT INTERFACE"
.IX Header "OBJECT INTERFACE"
These are the methods in \f(CW\*(C`File::ReadBackwards\*(C'\fR' object interface:
.ie n .SS "new( $file, [$rec_sep], [$sep_is_regex] )"
.el .SS "new( \f(CW$file\fP, [$rec_sep], [$sep_is_regex] )"
.IX Subsection "new( $file, [$rec_sep], [$sep_is_regex] )"
\&\f(CW\*(C`new\*(C'\fR takes as arguments a filename, an optional record separator and
an optional flag that marks the record separator as a regular
expression. It either returns the object on a successful open or undef
upon failure. $! is set to the error code if any.
.SS "readline"
.IX Subsection "readline"
\&\f(CW\*(C`readline\*(C'\fR takes no arguments and it returns the previous line in the
file or undef when there are no more lines in the file. If the file is
a non-seekable file (e.g. a pipe), then undef is returned.
.SS "getline"
.IX Subsection "getline"
\&\f(CW\*(C`getline\*(C'\fR is an alias for the readline method. It is here for
compatibility with the IO::* classes which has a getline method.
.SS "eof"
.IX Subsection "eof"
\&\f(CW\*(C`eof\*(C'\fR takes no arguments and it returns true when \fIreadline()\fR has
iterated through the whole file.
.SS "close"
.IX Subsection "close"
\&\f(CW\*(C`close\*(C'\fR takes no arguments and it closes the handle
.SS "tell"
.IX Subsection "tell"
\&\f(CW\*(C`tell\*(C'\fR takes no arguments and it returns the current filehandle position.
This value may be used to \fIseek()\fR back to this position using a normal
file handle.
.SS "get_handle"
.IX Subsection "get_handle"
\&\f(CW\*(C`get_handle\*(C'\fR takes no arguments and it returns the internal Perl
filehandle used by the File::ReadBackwards object.  This handle may be
used to read the file forward. Its seek position will be set to the
position that is returned by the \fItell()\fR method.  Note that
interleaving forward and reverse reads may produce unpredictable
results.  The only use supported at present is to read a file backward
to a certain point, then use 'handle' to extract the handle, and read
forward from that point.
.SH "TIED HANDLE INTERFACE"
.IX Header "TIED HANDLE INTERFACE"
.ie n .SS "tie( *HANDLE, 'File::ReadBackwards', $file, [$rec_sep], [$sep_is_regex] )"
.el .SS "tie( *HANDLE, 'File::ReadBackwards', \f(CW$file\fP, [$rec_sep], [$sep_is_regex] )"
.IX Subsection "tie( *HANDLE, 'File::ReadBackwards', $file, [$rec_sep], [$sep_is_regex] )"
The \s-1TIEHANDLE, READLINE, EOF, CLOSE\s0 and \s-1TELL\s0 methods are aliased to
the new, readline, eof, close and tell methods respectively so refer
to them for their arguments and \s-1API.\s0  Once you have tied a handle to
File::ReadBackwards the only I/O operation permissible is <> which
will read the previous line. You can call \fIeof()\fR and \fIclose()\fR on the
tied handle as well. All other tied handle operations will generate an
unknown method error. Do not seek, write or perform any other
unsupported operations on the tied handle.
.SH "LINE AND RECORD ENDINGS"
.IX Header "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 \s-1OS.\s0 You can also set the separator on a per file
basis.
.PP
The record separator is a regular expression by default, which differs
from the behavior of $/.
.PP
Only if the record separator is \fBnot\fR specified and it defaults to
\&\s-1CR/LF\s0 (e.g, \s-1VMS,\s0 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.
.SH "DESIGN"
.IX Header "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.
.SH "NOTES"
.IX Header "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:
.PP
.Vb 1
\&        @back_lines = reverse <FH>.
.Ve
.PP
This module is only intended to read one line at a time from the end of
a file to the beginning.
.SH "AUTHOR"
.IX Header "AUTHOR"
Uri Guttman, uri@stemsystems.com
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2003 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.