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
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 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 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 eof
65 "eof" takes no arguments and it returns true when readline() has
66 iterated through the whole file.
67 close
69 "close" takes no arguments and it closes the handle
70 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 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
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
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 The record separator is a regular expression by default, which differs
105 from the behavior of $/.
106 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
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
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 @back_lines = reverse <FH>.
133 This module is only intended to read one line at a time from the end of
135 a file to the beginning.
136
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.
144perl v5.12.0 2005-05-05 ReadBackwards(3)