.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "File::ChangeNotify::Watcher 3pm"
.TH File::ChangeNotify::Watcher 3pm "2013-11-29" "perl v5.18.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
File::ChangeNotify::Watcher \- Base class for all watchers
.SH "VERSION"
.IX Header "VERSION"
version 0.24
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&    my $watcher =
\&        File::ChangeNotify\->instantiate_watcher
\&            ( directories => [ \*(Aq/my/path\*(Aq, \*(Aq/my/other\*(Aq ],
\&              filter      => qr/\e.(?:pm|conf|yml)$/,
\&              exclude     => [\*(Aqt\*(Aq, \*(Aqroot\*(Aq, qr(/(?!\e.)[^/]+$)],
\&            );
\&
\&    if ( my @events = $watcher\->new_events() ) { ... }
\&
\&    # blocking
\&    while ( my @events = $watcher\->wait_for_events() ) { ... }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A \f(CW\*(C`File::ChangeNotify::Watcher\*(C'\fR class monitors a directory for
changes made to any file. You can provide a regular expression to
filter out files you are not interested in. It handles the addition of
new subdirectories by adding them to the watch list.
.PP
Note that the actual granularity of what each watcher subclass reports
may vary across subclasses. Implementations that hook into some sort
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 subclass).
.PP
By default, events are returned in the form
File::ChangeNotify::Event objects, but this can be overridden by
providing an \*(L"event_class\*(R" attribute to the constructor.
.PP
The watcher can operate in a blocking/callback style, or you can
simply ask it for a list of new events as needed.
.SH "METHODS"
.IX Header "METHODS"
.SS "File::ChangeNotify::Watcher::Subclass\->new(...)"
.IX Subsection "File::ChangeNotify::Watcher::Subclass->new(...)"
This method creates a new watcher. It accepts the following arguments:
.IP "\(bu" 4
directories => \f(CW$path\fR
.IP "\(bu" 4
directories => \e@paths
.Sp
This argument is required. It can be either one or many paths which
should be watched for changes.
.IP "\(bu" 4
filter => qr/.../
.Sp
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.
.Sp
By default, all files are included.
.IP "\(bu" 4
exclude => [...]
.Sp
An optional list of paths to exclude. This list can contain either plain
strings or regular expressions. If you provide a string it should contain the
complete path to be excluded.
.Sp
The paths can be either directories or specific files. If the exclusion
matches a directory, all of its files and subdirectories are ignored.
.IP "\(bu" 4
follow_symlinks => \f(CW$bool\fR
.Sp
By default, symlinks are ignored. Set this to true to follow them.
.Sp
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.
.IP "\(bu" 4
sleep_interval => \f(CW$number\fR
.Sp
For watchers which call \f(CW\*(C`sleep\*(C'\fR to implement the \f(CW\*(C`$watcher\->wait_for_events()\*(C'\fR method, this argument controls how long
it sleeps for. The value is a number in seconds.
.Sp
The default is 2 seconds.
.IP "\(bu" 4
event_class => \f(CW$class\fR
.Sp
This can be used to change the class used to report events. By
default, this is File::ChangeNotify::Event.
.ie n .SS "$watcher\->\fIwait_for_events()\fP"
.el .SS "\f(CW$watcher\fP\->\fIwait_for_events()\fP"
.IX Subsection "$watcher->wait_for_events()"
This method causes the watcher to block until it sees interesting
events, and then return them as a list.
.PP
Some watcher subclasses may implement blocking as a sleep loop, while
others may actually block.
.ie n .SS "$watcher\->\fInew_events()\fP"
.el .SS "\f(CW$watcher\fP\->\fInew_events()\fP"
.IX Subsection "$watcher->new_events()"
This method returns a list of any interesting events seen since the
last time the watcher checked.
.ie n .SS "$watcher\->\fIsees_all_events()\fP"
.el .SS "\f(CW$watcher\fP\->\fIsees_all_events()\fP"
.IX Subsection "$watcher->sees_all_events()"
If this is true, the watcher will report on all events.
.PP
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.
.PP
Other watchers, like the Inotify subclass, see all events that happen
and report on them.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky <autarch@urth.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2013 by Dave Rolsky.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Artistic License 2.0 (GPL Compatible)
.Ve