1ReadBackwards(3)      User Contributed Perl Documentation     ReadBackwards(3)
2
3
4

NAME

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

SYNOPSIS

9           use File::ReadBackwards ;
10
11           # Object interface
12
13           $bw = File::ReadBackwards->new( 'log_file' ) or
14                               die "can't read 'log_file' $!" ;
15
16           while( defined( $log_line = $bw->readline ) ) {
17                   print $log_line ;
18           }
19
20           # ... or the alternative way of reading
21
22           until ( $bw->eof ) {
23                   print $bw->readline ;
24           }
25
26           # Tied Handle Interface
27
28           tie *BW, 'File::ReadBackwards', 'log_file' or
29                               die "can't read 'log_file' $!" ;
30
31           while( <BW> ) {
32                   print ;
33           }
34

DESCRIPTION

36       This module reads a file backwards line by line. It is simple to use,
37       memory efficient and fast. It supports both an object and a tied handle
38       interface.
39
40       It is intended for processing log and other similar text files which
41       typically have their newest entries appended to them. By default files
42       are assumed to be plain text and have a line ending appropriate to the
43       OS. But you can set the input record separator string on a per file
44       basis.
45

OBJECT INTERFACE

47       These are the methods in "File::ReadBackwards"' object interface:
48
49   new( $file, [$rec_sep], [$sep_is_regex] )
50       "new" takes as arguments a filename, an optional record separator and
51       an optional flag that marks the record separator as a regular
52       expression. It either returns the object on a successful open or undef
53       upon failure. $! is set to the error code if any.
54
55   readline
56       "readline" takes no arguments and it returns the previous line in the
57       file or undef when there are no more lines in the file. If the file is
58       a non-seekable file (e.g. a pipe), then undef is returned.
59
60   getline
61       "getline" is an alias for the readline method. It is here for
62       compatibilty with the IO::* classes which has a getline method.
63
64   eof
65       "eof" takes no arguments and it returns true when readline() has
66       iterated through the whole file.
67
68   close
69       "close" takes no arguments and it closes the handle
70
71   tell
72       "tell" takes no arguments and it returns the current filehandle
73       position.  This value may be used to seek() back to this position using
74       a normal file handle.
75
76   get_handle
77       "get_handle" takes no arguments and it returns the internal Perl
78       filehandle used by the File::ReadBackwards object.  This handle may be
79       used to read the file forward. Its seek position will be set to the
80       position that is returned by the tell() method.  Note that interleaving
81       forward and reverse reads may produce unpredictable results.  The only
82       use supported at present is to read a file backward to a certain point,
83       then use 'handle' to extract the handle, and read forward from that
84       point.
85

TIED HANDLE INTERFACE

87   tie( *HANDLE, 'File::ReadBackwards', $file, [$rec_sep], [$sep_is_regex] )
88       The TIEHANDLE, READLINE, EOF, CLOSE and TELL methods are aliased to the
89       new, readline, eof, close and tell methods respectively so refer to
90       them for their arguments and API.  Once you have tied a handle to
91       File::ReadBackwards the only I/O operation permissible is <> which will
92       read the previous line. You can call eof() and close() on the tied
93       handle as well. All other tied handle operations will generate an
94       unknown method error. Do not seek, write or perform any other
95       unsupported operations on the tied handle.
96

LINE AND RECORD ENDINGS

98       Since this module needs to use low level I/O for efficiency, it can't
99       portably seek and do block I/O without managing line ending
100       conversions.  This module supports the default record separators of
101       normal line ending strings used by the OS. You can also set the
102       separator on a per file basis.
103
104       The record separator is a regular expression by default, which differs
105       from the behavior of $/.
106
107       Only if the record separator is not specified and it defaults to CR/LF
108       (e.g, VMS, redmondware) will it will be converted to a single newline.
109       Unix and MacOS files systems use only a single character for line
110       endings and the lines are left unchanged.  This means that for native
111       text files, you should be able to process their lines backwards without
112       any problems with line endings. If you specify a record separator, no
113       conversions will be done and you will get the records as if you read
114       them in binary mode.
115

DESIGN

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

NOTES

128       There is no support for list context in either the object or tied
129       interfaces. If you want to slurp all of the lines into an array in
130       backwards order (and you don't care about memory usage) just do:
131
132               @back_lines = reverse <FH>.
133
134       This module is only intended to read one line at a time from the end of
135       a file to the beginning.
136

AUTHOR

138       Uri Guttman, uri@stemsystems.com
139
141       Copyright (C) 2003 by Uri Guttman. All rights reserved.  This program
142       is free software; you can redistribute it and/or modify it under the
143       same terms as Perl itself.
144
145
146
147perl v5.12.0                      2005-05-05                  ReadBackwards(3)
Impressum