Gligan Calin Horea > File-RoundRobin > File::RoundRobin

Download:
File-RoundRobin/File-RoundRobin-0.04.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  2
Open  0
View/Report Bugs
Module Version: 0.04   Source  

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 :

Example :

        my $rrfile = File::RoundRobin->new(
                                    path => '/tmp/sample.txt',
                                    size => '100M',
                                          );

read

Arguments :

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 :

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 :

write

Writes the given text into the file

Usage :

        $rrfile->write("foo bar");

Arguments :

print

Writes the given text into the file

Usage :

        $rrfile->print("foo bar");

Arguments :

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 :

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 :

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:

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.

syntax highlighting: