1ReadBackwards(3) User Contributed Perl Documentation ReadBackwards(3)
2
6 File::ReadBackwards.pm -- Read a file backwards by lines.
7
9 use File::ReadBackwards ;
10 # Object interface
12 $bw = File::ReadBackwards->new( 'log_file' ) or
14 die "can't read 'log_file' $!" ;
15 while( defined( $log_line = $bw->readline ) ) {
17 print $log_line ;
18 }
19 # ... or the alternative way of reading
21 until ( $bw->eof ) {
23 print $bw->readline ;
24 }
25 # Tied Handle Interface
27 tie *BW, 'File::ReadBackwards', 'log_file' or
29 die "can't read 'log_file' $!" ;
30 while( <BW> ) {
32 print ;
33 }
34
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 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
47 These are the methods in "File::ReadBackwards"' object interface:
48 new( $file, [$rec_sep], [$sep_is_regex] )
50 "new" takes as arguments a filename, an optional record separator and
52 an optional flag that marks the record separator as a regular expres‐
53 sion. It either returns the object on a successful open or undef upon
54 failure. $! is set to the error code if any.
55 readline
57 "readline" takes no arguments and it returns the previous line in the
59 file or undef when there are no more lines in the file. If the file is
60 a non-seekable file (e.g. a pipe), then undef is returned.
61 getline
63 "getline" is an alias for the readline method. It is here for compati‐
65 bilty with the IO::* classes which has a getline method.
66 eof
68 "eof" takes no arguments and it returns true when readline() has iter‐
70 ated through the whole file.
71 close
73 "close" takes no arguments and it closes the handle
75 tell
77 "tell" takes no arguments and it returns the current filehandle posi‐
79 tion. This value may be used to seek() back to this position using a
80 normal file handle.
81 get_handle
83 "get_handle" takes no arguments and it returns the internal Perl file‐
85 handle used by the File::ReadBackwards object. This handle may be used
86 to read the file forward. Its seek position will be set to the position
87 that is returned by the tell() method. Note that interleaving forward
88 and reverse reads may produce unpredictable results. The only use sup‐
89 ported at present is to read a file backward to a certain point, then
90 use 'handle' to extract the handle, and read forward from that point.
91
93 tie( *HANDLE, 'File::ReadBackwards', $file, [$rec_sep], [$sep_is_regex]
94 )
95 The TIEHANDLE, READLINE, EOF, CLOSE and TELL methods are aliased to the
97 new, readline, eof, close and tell methods respectively so refer to
98 them for their arguments and API. Once you have tied a handle to
99 File::ReadBackwards the only I/O operation permissible is <> which will
100 read the previous line. You can call eof() and close() on the tied han‐
101 dle as well. All other tied handle operations will generate an unknown
102 method error. Do not seek, write or perform any other unsupported oper‐
103 ations on the tied handle.
104
106 Since this module needs to use low level I/O for efficiency, it can't
107 portably seek and do block I/O without managing line ending conver‐
108 sions. This module supports the default record separators of normal
109 line ending strings used by the OS. You can also set the separator on a
110 per file basis.
111 The record separator is a regular expression by default, which differs
113 from the behavior of $/.
114 Only if the record separator is not specified and it defaults to CR/LF
116 (e.g, VMS, redmondware) will it will be converted to a single newline.
117 Unix and MacOS files systems use only a single character for line end‐
118 ings and the lines are left unchanged. This means that for native text
119 files, you should be able to process their lines backwards without any
120 problems with line endings. If you specify a record separator, no con‐
121 versions will be done and you will get the records as if you read them
122 in binary mode.
123
125 It works by reading a large (8kb) block of data from the end of the
126 file. It then splits them on the record separator and stores a list of
127 records in the object. Each call to readline returns the top record of
128 the list and if the list is empty it refills it by reading the previous
129 block from the file and splitting it. When the beginning of the file
130 is reached and there are no more lines, undef is returned. All bound‐
131 ary conditions are handled correctly i.e. if there is a trailing par‐
132 tial line (no newline) it will be the first line returned and lines
133 larger than the read buffer size are handled properly.
134
136 There is no support for list context in either the object or tied
137 interfaces. If you want to slurp all of the lines into an array in
138 backwards order (and you don't care about memory usage) just do:
139 @back_lines = reverse <FH>.
141 This module is only intended to read one line at a time from the end of
143 a file to the beginning.
144
146 Uri Guttman, uri@stemsystems.com
147
149 Copyright (C) 2003 by Uri Guttman. All rights reserved. This program
150 is free software; you can redistribute it and/or modify it under the
151 same terms as Perl itself.
152perl v5.8.8 2005-05-05 ReadBackwards(3)