NAME

File::Tail::App - Perl extension for making apps that tail files

SYNOPSIS

   use File::Tail::App;

   tail_app({
       'new'          => ['logfile.log'],
       'line_handler' => \&_wag_tail,
   });

   sub _wag_tail {
       my($line) = @_;
       # do what you want with the $line
   }

DESCRIPTION

Adds two methods for a File::Tail object and one function.

tail_app()

As in the SYNOPSIS, creates an app that processes a file's tail line by line.

Its only arg is a hashref with these keys:

new

Required. This is an array ref of the array you give to File::Tail's new method.

line_handler

This is a code ref that takes the current line in a string as its only argument. if you do not specify this the line is simply printed out.

seek_to

Before you start processing the file you can sysseek to this part of the file.

Like sysseek(), its value is in bytes.

seek_on_zero

If this is false and seek_to is 0, then don't $tail->seek_to() it, Default is 1.

lastrun_file

This is a file that is used to track the current position. It is recommended to use this so that if the program is terminated unexpectedly it can resume exactly where it left off so you will avoid duplicated or missing data.

If you'd rather do this your self the you'll need to get the current position before the call to app and send it via the seek_to key and log the new length at the end of your line processing function. You'll also need to be able to tell if the file you're tailing changes drastically because say you are currently at 12345 and the script is killed and then the log file is truncated before it is restarted. You don't want to start at 12345 in that case, you want to start at 0.

The lastrun_file parameter handles all of that and more for you. Feel free to take a look at how it works if you need to write your own for some reason, like you want to use SQL DB instead of a file, etc etc...

do_md5_check

If using lastrun_file also do a check on the MD5 sum of a small part of data in the beginning of the file to see if its been truncated and handle appropriately. (Thanks to Ben Thomas for the MD5 idea!!)

$tail->app()

Same args as tail_app except for the "new" key since you've already create the File::Tail object.

$tail->seek_to()

Given a digit, it will move to that position in the $tail object's handle. Useful for resuming where you left off.

Like sysseek(), its argument is in bytes.

EXPORT

None by default.

tail_app can be exported.

EXAMPLE

This example will process x.log as its updated. To avoid double logging it only allows one instance of itself to be run (See Unix::PID). To avoid missing or double processing data if a problem arises it uses a lastrun file. So this is a pretty sturdy, reliable, and easy to code log processor:

    #!/usr/bin/perl

    use strict;
    use warnings;

    use Unix::PID '/var/run/xlogr.pid';
    use File::Tail::App qw(tail_app);

    tail_app({
        'new'          => ['x.log'],
        'line_handler' => \&_wag_tail,
        'lastrun_file' => 'x.lastrun',
    });

    sub _wag_tail {
        my($line) = @_;
        # do what you want with the $line
    }

BUGS

This was stress tested pretty vigorously for various circumstances so it should be pretty solid. If you do come across a problem please contact me with the code and steps neccessary to reproduce the bug so I can release a fix ASAP.

SEE ALSO

File::Tail

AUTHOR

Daniel Muey, http://drmuey.com/cpan_contact.pl

COPYRIGHT AND LICENSE

Copyright 2005 by Daniel Muey

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.