NAME

Stateful::Tailer - Tail multiple files and keep state between invocations.

VERSION

Version 0.01

SYNOPSIS

Tail multiple files and keep state between invocations. Calls to read will not block, so it may be integrated into other event loops.

For example, it may be used in conjunction with Linux::Inotify2, where inotify triggers the reading based on the tailed files' events (eg IN_MODIFY OR IN_ATTRIB events).

use Stateful::Tailer;

my $tailer = Stateful::Tailer->new(
    files            => [ '/path/to/file1' ],
    include_patterns => [ 'greyd\[\d+\]:' ],
    except_patterns  => [ '^greylogd.*' ],
    state_file       => "/tmp/tailer.state",
    read_callback    => (
        sub {
            my $lines = shift; # Array ref.
            ...
        }
    ),
);

$tailer->read; # Does not block.

This module is completely object-oriented, with minimal dependencies (eg only YAML at this stage).

SUBROUTINES/METHODS

new

Constructor for the Stateful::Tailer class. On construction, the state file is automatically loaded or created if it does not exist.

parameters

files (required): An ARRAY ref of file paths to tail.
state_file (required): The path to the state file in which the state of each tailed file is recorded in YAML. If the specified file does not exist, it will be created automatically.
include_patterns: An ARRAY ref of regular expressions to which all returned lines must match. If this parameter is specified, any lines that do not match an expression in the list will be silently ignored. Defaults to an empty ARRAY ref.
exclude_patterns: An ARRAY ref of regular expressions. Any line matching an expression in this list will be ignored, including those lines that match expressions in include_patterns (if specified). Defaults to an empty ARRAY ref.
read_callback: The callback to be invoked (once per file) on read with the filtered lines. This callback is invoked with an ARRAY ref as a single argument. The callback will not be invoked if there are no lines.
debug: Print diagnostic messages to STDERR.

read

Read all lines from the specified files starting from the last saved position. If the state file does not exist, start reading from the beginning. The state is then saved after all files are read.

The specified files are processed in sequence. Calls to this subroutine will not block.

close_files

Close all configured files. This is called automatically on destruction.

AUTHOR

Mikey Austin, <mikey at jackiemclean.net>

BUGS

Please report any bugs or feature requests to the author's email address.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Stateful::Tailer

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

mikey-austin/perl-Stateful-Tailer