NAME
File::RoundRobin - Round Robin text files
VERSION
Version 0.01
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'
);
$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.
TIE INTERFACE
This module implements the TIEHANDLE interface and the objects an be used as normal file handles.
Write example:
local *FH;
tie *FH, 'File::RoundRobin', path => 'test.txt',size => '10M';
my $fh = *FH;
...
print $fh "foo bar";
...
close($fh);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
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)
SUBROUTINES/METHODS
new
Returns a new File::RoundRobin object.
Files can be opened in three ways: new file, read, append
New file mode
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 mode
Arguments :
path = path where to create the file
mode = must be
read
Example :
my $rrfile = File::RoundRobin->new(path => '/tmp/sample.txt', mode => 'read');Append mode
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');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
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();Private methods
Don't call this methods manually, or you might get unexpected results!
open_file
Has two modes :
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, <gliganh at gmail.com>
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)
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
LIMITATIONS
The module does not support tailing of files as they are written to.
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.