NAME

Dist::Zilla::Role::FileWatcher - Receive notification when something changes a file's contents

VERSION

version 0.006

SYNOPSIS

    package Dist::Zilla::Plugin::MyPlugin;
    use Moose;
    with 'Dist::Zilla::Role::SomeRole', 'Dist::Zilla::Role::FileWatcher';

    sub some_phase
    {
        my $self = shift;

        my (file) = grep { $_->name eq 'some_name' } @{$self->zilla->files};
        # ... do something with this file ...

        $self->lock_file($file, 'KEEP OUT!');

        # or:

        $self->watch_file(
            $file,
            sub {
                my ($plugin, $file) = @_;
                ... do something with the file object ...
            },
        );
    }

DESCRIPTION

This is a role for Dist::Zilla plugins which gives you a mechanism for detecting and acting on files changing their content. This is useful if your plugin performs an action based on a file's content (perhaps copying that content to another file), and then later in the build process, that source file's content is later modified.

METHODS

This role adds the following methods to your plugin class:

watch_file($file, $subref)

This method takes two arguments: the $file object to watch, and a subroutine which is invoked when the file's contents change. It is called as a method on your plugin, and is passed one additional argument: the $file object that changed.

lock_file($file, $message?)

This method takes the $file object to watch, and an optional message string; when the file is modified after it is locked, the build dies.

SUPPORT

Bugs may be submitted through the RT bug tracker (or bug-Dist-Zilla-Role-FileWatcher@rt.cpan.org). I am also usually active on irc, as 'ether' at irc.perl.org.

SEE ALSO

• Dist::Zilla::Role::File::ChangeNotification - in this distribution, the underlying implementation for watching the file

• Dist::Zilla::File::OnDisk

• Dist::Zilla::File::InMemory

AUTHOR

Karen Etheridge <ether@cpan.org>

CONTRIBUTOR

Yanick Champoux <yanick@babyl.dyndns.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Karen Etheridge.

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