Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ReadBackwards(3)      User Contributed Perl Documentation     ReadBackwards(3)

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

SYNOPSIS
	   use File::ReadBackwards ;

	   # Object interface

	   $bw = File::ReadBackwards->new( 'log_file' )	or
			       die "can't read 'log_file' $!" ;

	   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, 'File::ReadBackwards', 'log_file' or
			       die "can't read 'log_file' $!" ;

	   while( <BW> ) {
		   print ;
	   }

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.

       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
       OS. But you can set the input record separator string on	a per file
       basis.

OBJECT INTERFACE
       These are the methods in	"File::ReadBackwards"' object interface:

   new(	$file, [$rec_sep], [$sep_is_regex] )
       "new" 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.

   readline
       "readline" 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.

   getline
       "getline" is an alias for the readline method. It is here for
       compatibilty with the IO::* classes which has a getline method.

   eof
       "eof" takes no arguments	and it returns true when readline() has
       iterated	through	the whole file.

   close
       "close" takes no	arguments and it closes	the handle

   tell
       "tell" takes no arguments and it	returns	the current filehandle
       position.  This value may be used to seek() back	to this	position using
       a normal	file handle.

   get_handle
       "get_handle" 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	tell() 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.

TIED HANDLE INTERFACE
   tie(	*HANDLE, 'File::ReadBackwards',	$file, [$rec_sep], [$sep_is_regex] )
       The TIEHANDLE, READLINE,	EOF, CLOSE and TELL methods are	aliased	to the
       new, readline, eof, close and tell methods respectively so refer	to
       them for	their arguments	and API.  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 eof() and close() 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.

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 OS. You can also set the
       separator on a per file basis.

       The record separator is a regular expression by default,	which differs
       from the	behavior of $/.

       Only if the record separator is not specified and it defaults to	CR/LF
       (e.g, VMS, 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.

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.

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:

	       @back_lines = reverse <FH>.

       This module is only intended to read one	line at	a time from the	end of
       a file to the beginning.

AUTHOR
       Uri Guttman, uri@stemsystems.com

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.

perl v5.32.0			  2011-06-04		      ReadBackwards(3)

NAME | SYNOPSIS | DESCRIPTION | OBJECT INTERFACE | TIED HANDLE INTERFACE | LINE AND RECORD ENDINGS | DESIGN | NOTES | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=File::ReadBackwards&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help