View on
MetaCPAN
Gligan Calin Horea > File-RoundRobin > File::RoundRobin

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

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.06   Source  

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

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') || die $@;

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

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