NAME
File::RoundRobin - Round Robin text files
VERSION
Version 0.06
SYNOPSIS
This module implements a Round-Robin text file.
The text file will not grow beyond the size we specify.
The benefit of using this module is that you can log a certain amount of information without having to care about filling your hard drive or setting up a log-rotate mechanism.
Example :
use File::RoundRobin;
my $rrfile = File::RoundRobin->new(
path => '/tmp/sample.txt',
size => '100M',
mode => 'new',
) // die $@;
$rrfile->print("foo bar");
or
my $rrfile = File::RoundRobin->new(path => '/tmp/sample.txt', mode => 'read');
while (my $line = $rrfile->readline() ) {
print $line;
}When you write into the Round-Robin file, if it filled the maximum allowed space it will write over the old data, while always preserving the most recent data.
ERROR HANDLING and DEBUGGING
In case an error occurs, the error will be stored in $@
Starting with version 0.5 the module no longer dies on errors, instead returns undef or 0 (c<new()> will return undef, c<write()> will return 0) and the actual error message is available in $@.
TIE INTERFACE
This module implements the TIEHANDLE interface and the objects an be used as normal file handles.
- 1. Write example :
-
local *FH; tie *FH, 'File::RoundRobin', path => 'test.txt',size => '10M'; my $fh = *FH; ... print $fh "foo bar"; ... close($fh); - 2. Read example :
-
local *FH; tie *FH, 'File::RoundRobin', path => 'test.txt',mode => 'read'; $fh = *FH; while ( my $line = readline($fh) ) { print $line; } close($fh);
UTILITIES
rrcat
The package comes with a simple utility rrcat that let's you create and read RoundRobin files from command line
Usage : To print the content of a file : $ rrcat <filename>
To write into a file (reads from stdin): $ rrcat <size> <filename>
Size can be specified in any of the forms accepted by File::RoundRobin (see new method)
rrtail
The package comes with a simple utility rrtail that let's you tail RoundRobin files from command line
Usage : To a file you can run :
Print the last 10 lines
$ rrtail <filename>Print the last 100 lines :
$ rrtail -n 100 <filename>Print the content as it's written :
$ rrtail -f <filename>SUBROUTINES/METHODS
new
Returns a new File::RoundRobin object.
Files can be opened in three ways: new file, read, append
write
In new file mode any existing data will be lost and the file will be overwritten Arguments :
path = path where to create the file
size = the maximum size the file is allowed to grow to. Example : 100K or 100Kb, 10M or 10Mb, 1G or 1Gb
Example :
my $rrfile = File::RoundRobin->new(
path => '/tmp/sample.txt',
size => '100M',
);read
Arguments :
path = path where to create the file
mode = must be
read
Example :
my $rrfile = File::RoundRobin->new(path => '/tmp/sample.txt', mode => 'read') || die $@;append
In append mode all existing data will preserved and we can continue writing the file from where we left off
Arguments :
path = path where to create the file
mode = must be
append
Example :
my $rrfile = File::RoundRobin->new(path => '/tmp/sample.txt', mode => 'append') || die $@;read
Reads the $length craracters form the file beginning with $offset and returns the result
Usage :
#reads the next 10 characted from the file
my $buffer = $rrfile->read(10);
or
#reads the first 10 characters starting with character 90 after the current position
my $buffer = $rrfile->read(10,90);Arguments :
length = how many bytes to read
offset = offset from which to start reading
write
Writes the given text into the file
Usage :
$rrfile->write("foo bar");Arguments :
buffer = the actual content we want to write
length = the length of the content we want to write (defaults to
length($buffer))offset = offset from which to start writing
Writes the given text into the file
Usage :
$rrfile->print("foo bar");Arguments :
buffer = the actual content we want to write
close
Close the Round-Robin file
Usage :
$rrfile->close();eof
Return true if you reached the end of file, false otherwise
Usage :
my $bool = $rrfile->eof();autoflush
Turns on/off the autoflush feature
Usage : my $autoflush = $rrfile->autoflush();
or
$rrfile->autoflush(1); #enables autoflush
$rrfile->autoflush(0); #disables autoflushPrivate methods
Don't call this methods manually, or you might get unexpected results!
open_file
Has two modes :
update_headers
Update the start point in the headers section after a write command
refresh
Re-reads the headers from the file. Useful for tail
sync_markers
Sets the write market to the same position as the read marker
jump
Advance the read start position pointer by $offset bytes
seek
Move the read/write start position to the given position
Arguments :
position = The position to which we want to move to offset
whence = From where should we start counting the position :
0 = from the beginning of the file
1 = from the current position
2 = from the end of the file (position must be negative)
Usage :
$rrfile->seek(10,0);tell
Return the difference between the current read position and the last write position
Example :
my $pos = $rrfile->tell();convert_size
Converts the size from a human readable form into bytes
Example of acceptable formats :
1000
120K or 120Kb
15M or 15Mb
1G or 1Gb
TIE INTERFACE IMPLEMENTATION
This module implements the TIEHANDLE interface and the objects an be used as normal file handles.
See SYNOPSYS for more details on this
AUTHOR
Gligan Calin Horea, <horea at gligan.ro>
BUGS
Please report any bugs or feature requests to bug-file-roundrobin at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-RoundRobin. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc File::RoundRobinYou can also look for information at:
RT: CPAN's request tracker (report bugs here)
LICENSE AND COPYRIGHT
Copyright 2012 Gligan Calin Horea.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.