view release on metacpan or  search on metacpan

lib/Dist/Zilla/Role/FileWatcher.pm  view on Meta::CPAN

=pod

=encoding UTF-8

=head1 NAME

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

=head1 VERSION

version 0.006

=head1 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 ...
            },
        );
    }

=head1 DESCRIPTION

This is a role for L<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.

=head1 METHODS

This role adds the following methods to your plugin class:

=head2 C<watch_file($file, $subref)>

This method takes two arguments: the C<$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 C<$file>
object that changed.

=head2 C<lock_file($file, $message?)>

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

=head1 SUPPORT

=for stopwords irc

Bugs may be submitted through L<the RT bug tracker|https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Role-FileWatcher>
(or L<bug-Dist-Zilla-Role-FileWatcher@rt.cpan.org|mailto:bug-Dist-Zilla-Role-FileWatcher@rt.cpan.org>).
I am also usually active on irc, as 'ether' at C<irc.perl.org>.

=head1 SEE ALSO

=over 4

=item *

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

=item *

L<Dist::Zilla::File::OnDisk>

=item *

L<Dist::Zilla::File::InMemory>

=back

=head1 AUTHOR

Karen Etheridge <ether@cpan.org>

=head1 CONTRIBUTOR

=for stopwords Yanick Champoux

Yanick Champoux <yanick@babyl.dyndns.org>

=head1 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.

=cut