File::RoundRobin - Round Robin text files
Version 0.04
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',
);
$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.
This module implements the TIEHANDLE interface and the objects an be used as normal file handles.
local *FH;
tie *FH, 'File::RoundRobin', path => 'test.txt',size => '10M';
my $fh = *FH;
...
print $fh "foo bar";
...
close($fh);
local *FH;
tie *FH, 'File::RoundRobin', path => 'test.txt',mode => 'read';
$fh = *FH;
while ( my $line = readline($fh) ) {
print $line;
}
close($fh);
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)
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>
Returns a new File::RoundRobin object.
Files can be opened in three ways: new file, read, append
In new file mode any existing data will be lost and the file will be overwritten Arguments :
Example :
my $rrfile = File::RoundRobin->new(
path => '/tmp/sample.txt',
size => '100M',
);
Arguments :
readExample :
my $rrfile = File::RoundRobin->new(path => '/tmp/sample.txt', mode => 'read');
In append mode all existing data will preserved and we can continue writing the file from where we left off
Arguments :
appendExample :
my $rrfile = File::RoundRobin->new(path => '/tmp/sample.txt', mode => 'append');
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 :
Writes the given text into the file
Usage :
$rrfile->write("foo bar");
Arguments :
length($buffer))Writes the given text into the file
Usage :
$rrfile->print("foo bar");
Arguments :
Close the Round-Robin file
Usage :
$rrfile->close();
Return true if you reached the end of file, false otherwise
Usage :
my $bool = $rrfile->eof();
Turns on/off the autoflush feature
Usage : my $autoflush = $rrfile->autoflush();
or
$rrfile->autoflush(1); #enables autoflush
$rrfile->autoflush(0); #disables autoflush
Don't call this methods manually, or you might get unexpected results!
Has two modes :
Update the start point in the headers section after a write command
Re-reads the headers from the file. Useful for tail
Sets the write market to the same position as the read marker
Advance the read start position pointer by $offset bytes
Move the read/write start position to the given position
Arguments :
Usage :
$rrfile->seek(10,0);
Return the difference between the current read position and the last write position
Example :
my $pos = $rrfile->tell();
Converts the size from a human readable form into bytes
Example of acceptable formats :
This module implements the TIEHANDLE interface and the objects an be used as normal file handles.
See SYNOPSYS for more details on this
Gligan Calin Horea, <gliganh at gmail.com>
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.
You can find documentation for this module with the perldoc command.
perldoc File::RoundRobin
You can also look for information at:
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.
