NAME

App::Wubot::Util::Tail - follow the tail of a growing file

VERSION

version 0.4.2

SYNOPSIS

use App::Wubot::Util::Tail;

# for a complete example, see App::Wubot::Plugin::FileTail

DESCRIPTION

This class helps build plugins that need to monitor a log file that is being continuously updated, and execute a bit of code for each new line.

Once initialized, it holds the filehandle open while wubot is running. The position in the file can be cached using the standard wubot caching mechanism.

Plugins that use this library can call get_lines() in the check() method to process all lines that showed up in the file since the last time check() was called. This will execute a callback for each new line. In addition, a callback can be defined to run if the filehandle was reset (i.e. the filehandle was reopened or the file was truncated).

SUBROUTINES/METHODS

$obj->get_lines();

Look for new lines in the file, and run the callback on each.

If no new lines are found in the file, then the filehandle is checked to see if the file was truncated or the filehandle was closed and then a new one was re-opened. In either case, the reset_callback is executed and is passed the appropriate text:

filehandle was truncated: {$path}

If the 'detect_rename' attribute is true (the default), then the filehandle will also be checked to see if it was renamed. This will detect if the date on the file has increased even though the filehandle has nothing available to read. In the event of a rename, the reset_callback will be executed.

file was renamed: {$path}

$obj->get_fh()

Use sysopen to open the filehandle in non-blocking read-only mode. If a position was defined on the object, seeks to that position.

$obj->_get_lines_nonblock( $fh )

Private method, code adapted from:

http://www.perlmonks.org/?node_id=55241

SIMILAR MODULES

I looked at a lot of other similar modules, but ended up having to roll my own due some some specific requirements of wubot.

File::Tail - I was unable to tweak the frequency at which this module checks for updates or filehandle resets to work the way I wanted. I wanted to do this reliably every time the check() method was executed.

POE::Wheel::FollowTail - I have used this module in the past and love it. While old versions of wubot were based on POE, the current version of wubot uses AnyEvent.

File::Tail - this module has great mechanisms for detecting if the file was replaced or the file was truncated, but unfortunately it does pass that information on to programs that use the module.