NAME

File::RoundRobin - Round Robin text files

VERSION

Version 0.04

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.

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');

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');

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

print

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 autoflush
        

Private methods

Don't call this methods manually, or you might get unexpected results!

open_file

Has two modes :

1. In append mode it opens an existing file

2. In new mode it creates a new file

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, <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::RoundRobin

You can also look for information at:

• RT: CPAN's request tracker (report bugs here)

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-RoundRobin

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/File-RoundRobin

• CPAN Ratings

  http://cpanratings.perl.org/d/File-RoundRobin

• Search CPAN

  http://search.cpan.org/dist/File-RoundRobin/

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.

cpanm File::RoundRobin

perl -MCPAN -e shell
install File::RoundRobin