NAME

File::Watch - Module for performing a filtered tail on a file

VERSION

version 2.0.1

SYNOPSIS

$watch = File::Watch->new;

# Set the directory pathname
$watch->filename( $filename );

$watch->filter( $regex )
    if $regex;

while( 1 )
{
    print $line
        if $line=$watch->get_line;
    sleep 1;
};

# or multi-line efficient
while( 1 )
{
    $lines=$watch->get_lines;
    print @$lines
        if @$lines;
    sleep 1;
};

# Perform action from beginning of file and then follow
$watch = File::Watch->new( {
    'filename'       => $filename,
    'filter'         => $regex,
    'from_beginning' => 1,
    } );

while( 1 )
{
    $lines=$watch->get_lines;
    print @$lines
        if @$lines;
    sleep 1;
};

DESCRIPTION

File::Watch is a module to provide a object/method mechanism to perform the equivalent of tail --follow=file | grep pattern.

PROPERTIES

• filename

  Get/Set the filename to be watched. Setting after the filename after the first line fetch is not supported.

• filter

  Get/Set a regular expression used to filter the output. Setting the filter after the first line fetch is not supported.

• from_beginning

  Boolean, if set will cause the requested file to be read from the beginning rather than starting at the end and then following. Only effective if set prior to first fetch of lines.

METHODS

Note that once any of the following methods are called modification of the previous properties will cause undefined behaviour.

• get_line / getline

  Get a single line from the file (after filtering) if present. Returns undef if no lines available at the time.

  = item get_lines / getlines

  Get an array reference to a number of lines. By default this will be all available unless a number is supplied.

• activity

  Returns a boolean indicating if there are lines available to be read.

EXAMPLE

#!/usr/bin/perl
use strict;
use Time::HiRes qw( usleep );
use File::Watch;

my ($beginning,$filter,@l);
if (@ARGV && $ARGV[0] eq '-b')
{
    $beginning = 1;
    shift @ARGV;
}

die "Usage: tailgrep pattern file [ file ... ]\n" if @ARGV < 2;
$filter = shift @ARGV;
@l = map{ File::Watch->new(
            'filename'      => $_,
            'filter'        => $filter,
            'from_beginning' => $beginning,
        ); } @ARGV;

# autoflush stdout
local $| = 1;
while(1) { map { print $_->get_lines; } @l; usleep 100000; };  

COMPATIBILITY

• File::Watch requires Class::Accessorize and IO::File.

AUTHOR

Bernard Quatermass toolsmith@quatermass.co.uk

COPYRIGHT AND LICENSE

This software is copyright (c) 2017,2022,2025 by Bernard Quatermass.

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