File::...Watcher(3pm)

💖 File::ChangeNotify::Watcher — the role every watcher wears 💖

okay bestie, so this is File::ChangeNotify::Watcher, and it's a role — meaning all the watcher classes consume it. It's giving "shared destiny", it's giving "we all signed the same contract". 🫶

---

✨ VERSION ✨

version 0.31 — that's the vibe, that's the era, we're on it. 💅

---

🌸 SYNOPSIS 🌸

here's the whole mood, copy-paste ready:

my $watcher =
    File::ChangeNotify->instantiate_watcher
        ( directories => [ '/my/path', '/my/other' ],
          filter      => qr/\.(?:pm|conf|yml)$/,
          exclude     => ['t', 'root', qr(/(?!\.)[^/]+$),
                          sub { -e && ! -r }],
        );

if ( my @events = $watcher->new_events ) { ... }

# blocking
while ( my @events = $watcher->wait_for_events ) { ... }

not me reading that and being like "okay this is lowkey elegant". 🦋

---

🎀 DESCRIPTION 🎀

so a File::ChangeNotify::Watcher watches a directory and clocks any changes made to any file in it. You can hand it a regular expression to filter out the files you don't care about — no thoughts, no energy for those. ✨ And it handles new subdirectories for you, adding them to the watch list as they show up. main character behaviour honestly.

heads up bestie: the actual granularity of what each watcher class reports may vary. Implementations that hook into some kind of kernel event interface (Inotify, for example) have much better knowledge of exactly what changes are happening than one implemented purely in userspace code (like the Default class). iykyk — kernel girlies know more. 💀

by default, events come back as File::ChangeNotify::Event objects, but you can override that by handing an event_class attribute to the constructor. customizable queen.

you can either block while waiting for events, or do a non-blocking call asking for any new events since the last call (or since the watcher was instantiated). Different watchers implement blocking in different ways — and the Default watcher? it just does a sleep loop. iconic but simple. 😴

---

👑 METHODS 👑

🍓 File::ChangeNotify::Watcher::Subclass->new(...)

this method creates a new watcher. it accepts the following arguments:

• directories => $path
• directories => \@paths

This argument is required. It can be either one or many paths which should be watched for changes. no paths, no party. 🎉

• filter => qr/.../

This is an optional regular expression that will be used to check if a file is of interest. This filter is only applied to files.

By default, all files are included. everybody's welcome. 🌈

• exclude => [...]

An optional arrayref of paths to exclude. This arrayref can contain plain strings, regular expressions, or subroutine references. If you provide a string it should contain the complete path to be excluded.

If you provide a sub, it should return a true value for paths to be excluded, e.g. exclude => [ sub { -e && ! -r } ],. The path will be passed as the first argument to the subroutine as well as in a localized $_.

The paths can be either directories or specific files. If the exclusion matches a directory, all of its files and subdirectories are ignored. bye forever, bestie. 👋

• modify_includes_file_attributes

This can either be a boolean or an arrayref.

If it is an arrayref then it should contain paths for which you want information about changes to the file's attributes. This arrayref can contain plain strings, regular expressions, or subroutine references. If you provide a string it should contain the complete path to be excluded.

When this matches a file, then modify events for that file will include information about the file's before and after permissions and ownership when these change. glow-up tracking, fr fr. ✨

See the File::ChangeNotify::Event documentation for details on what this looks like.

• modify_includes_content

This can either be a boolean or an arrayref.

If it is an arrayref then it should contain paths for which you want to see past and current content for a file when it is modified. This arrayref can contain plain strings, regular expressions, or subroutine references. If you provide a string it should contain the complete path to be excluded.

When this matches a file, then modify events for that file will include information about the file's before and after content when it changes.

See the File::ChangeNotify::Event documentation for details on what this looks like.

• follow_symlinks => $bool

By default, symlinks are ignored. Set this to true to follow them. 🧚

If this symlinks are being followed, symlinks to files and directories will be followed. Directories will be watched, and changes for directories and files reported.

• sleep_interval => $number

For watchers which call sleep to implement the $watcher->wait_for_events method, this argument controls how long it sleeps for. The value is a number in seconds.

The default is 2 seconds. a little nap, as a treat. 😴

• event_class => $class

This can be used to change the class used to report events. By default, this is File::ChangeNotify::Event.

💅 $watcher->wait_for_events

this method causes the watcher to block until it sees interesting events, and then return them as a list.

Some watcher subclasses may implement blocking as a sleep loop, while others may actually block. either way she's waiting. ⏳

🦋 $watcher->new_events

this method returns a list of any interesting events seen since the last time the watcher checked.

⭐ $watcher->sees_all_events

if this is true, the watcher will report on all events.

Some watchers, like the Default subclass, are not smart enough to track things like a file being created and then immediately deleted, and can only detect changes between snapshots of the file system. 💀

Other watchers, like the Inotify subclass, see all events that happen and report on them. she sees everything, no cap. 👑

---

🫶 SUPPORT 🫶

Bugs may be submitted at <http://rt.cpan.org/Public/Dist/Display.html?Name=File-ChangeNotify> or via email to bug-file-changenotify@rt.cpan.org <mailto:bug-file-changenotify@rt.cpan.org>.

I am also usually active on IRC as 'autarch' on irc://irc.perl.org. come say hi bestie!! 💬

---

🌈 SOURCE 🌈

The source code repository for File-ChangeNotify can be found at <https://github.com/houseabsolute/File-ChangeNotify>.

---

💜 AUTHOR 💜

Dave Rolsky <autarch@urth.org>

---

🎀 COPYRIGHT AND LICENSE 🎀

This software is Copyright (c) 2009 - 2019 by Dave Rolsky.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

The full text of the license can be found in the LICENSE file included with this distribution.

---

and that's the whole page, bestie!! 🥳 this was perl v5.36.0, dated 2022-12-04, living under the manual name File::...Watcher(3pm) — mwah, slay, go watch some files. 💖✨🎀