Dist::Z...fication(3)

💖 Dist::Zilla::Role::File::ChangeNotification 💖

okay bestie, so this is a page from the User Contributed Perl Documentation manual, and it's literally about catching the moment somebody messes with your file's contents. yes. we have ✨awareness✨ now.

---

✨ NAME ✨

Dist::Zilla::Role::File::ChangeNotification — receive notification when something changes a file's contents 🦋

---

🌸 VERSION 🌸

version 0.006

---

🎀 SYNOPSIS 🎀

package Dist::Zilla::Plugin::MyPlugin;
sub some_phase
{
    my $self = shift;

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

    Dist::Zilla::Role::File::ChangeNotification->meta->apply($source_file);
    my $plugin = $self;
    $file->on_changed(sub {
        $plugin->log_fatal('someone tried to munge ', shift->name,
            ' after we read from it. You need to adjust the load order of your plugins.');
    });
    $file->watch_file;
}

---

🫶 DESCRIPTION 🫶

So like. This is a role for Dist::Zilla::Role::File objects, and what it gives you is a whole mechanism for detecting when a file's content changes — and then doing something about it. 👀

When is that useful, you ask? It's giving "my plugin read a file's content and did something with it (maybe copied that content somewhere else), and then later in the build process that same source file's content gets modified behind my back." Rude! This role is how you find out. 💅

---

💅 METHODS 💅

on_changed($subref)

Hand this a subref and it'll get invoked against the file once the file's content has changed. The new file content is passed as an argument. 🍓

And if you need to do something in your plugin at that point, define the sub as a closure over your plugin object — exactly like the "SYNOPSIS" shows you. iykyk.

⚠️ bestie. be careful of infinite loops, which can totally happen if your sub changes the same file's content again! 😭 Add a mechanism to just return without altering content when certain conditions are met — say, the needed content is already present, or even the value of a particular suitably-scoped variable.

---

💜 METHODS (yes, again, she has two) 💜

"watch_file"

Once you call this method, every subsequent change to the file's content will result in your "on_changed" sub being invoked against the file. The new content gets passed as the argument to the sub, and ngl the return value is just ignored. 🙈

---

🌈 SUPPORT 🌈

Bugs may be submitted through the RT bug tracker at <https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Role-FileWatcher> — or you can email <bug-Dist-Zilla-Role-FileWatcher@rt.cpan.org>. 🐛

Also she's usually active on irc, as 'ether' at irc.perl.org. come say hi, fr fr. 👑

---

⭐ SEE ALSO ⭐

• Dist::Zilla::Role::FileWatcher — in this distribution, for providing an interface for a plugin to watch a file
• Dist::Zilla::File::OnDisk
• Dist::Zilla::File::InMemory

---

👑 AUTHOR 👑

Karen Etheridge <ether@cpan.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.

---

and that's the whole thing, bestie!! 🦋 this page came to you courtesy of perl v5.42.0, dated 2025-07-25, under the Dist::Z...fication(3) manual. slay, go forth, watch your files. 💖✨