local-lib5/man/man3/File::ChangeNotify::Watcher.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "File::ChangeNotify::Watcher 3"
 132 .TH File::ChangeNotify::Watcher 3 "2009-12-07" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 File::ChangeNotify::Watcher \- Base class for all watchers
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 6
 138 \&    my $watcher =
 139 \&        File::ChangeNotify\->instantiate_watcher
 140 \&            ( directories => [ '/my/path', '/my/other' ],
 141 \&              filter      => qr/\e.(?:pm|conf|yml)$/,
 142 \&              exclude     => ['t', 'root', qr(/(?!\e.)[^/]+$)],
 143 \&            );
 144 .Ve
 145 .PP
 146 .Vb 1
 147 \&    if ( my @events = $watcher\->new_events() ) { ... }
 148 .Ve
 149 .PP
 150 .Vb 2
 151 \&    # blocking
 152 \&    while ( my @events = $watcher\->wait_for_events() ) { ... }
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 A \f(CW\*(C`File::ChangeNotify::Watcher\*(C'\fR class monitors a directory for
 157 changes made to any file. You can provide a regular expression to
 158 filter out files you are not interested in. It handles the addition of
 159 new subdirectories by adding them to the watch list.
 160 .PP
 161 Note that the actual granularity of what each watcher subclass reports
 162 may vary across subclasses. Implementations that hook into some sort
 163 of kernel event interface (Inotify, for example) have much better
 164 knowledge of exactly what changes are happening than one implemented
 165 purely in userspace code (like the Default subclass).
 166 .PP
 167 By default, events are returned in the form
 168 File::ChangeNotify::Event objects, but this can be overridden by
 169 providing an \*(L"event_class\*(R" attribute to the constructor.
 170 .PP
 171 The watcher can operate in a blocking/callback style, or you can
 172 simply ask it for a list of new events as needed.
 173 .SH "METHODS"
 174 .IX Header "METHODS"
 175 .Sh "File::ChangeNotify::Watcher::Subclass\->new(...)"
 176 .IX Subsection "File::ChangeNotify::Watcher::Subclass->new(...)"
 177 This method creates a new watcher. It accepts the following arguments:
 178 .ie n .IP "* directories => $path" 4
 179 .el .IP "* directories => \f(CW$path\fR" 4
 180 .IX Item "directories => $path"
 181 .PD 0
 182 .IP "* directories => \e@paths" 4
 183 .IX Item "directories => @paths"
 184 .PD
 185 This argument is required. It can be either one or many paths which
 186 should be watched for changes.
 187 .IP "* filter => qr/.../" 4
 188 .IX Item "filter => qr/.../"
 189 This is an optional regular expression that will be used to check if a
 190 file is of interest. This filter is only applied to files.
 191 .Sp
 192 By default, all files are included.
 193 .IP "* exclude => [...]" 4
 194 .IX Item "exclude => [...]"
 195 An optional list of paths to exclude. This list can contain either plain
 196 strings or regular expressions. If you provide a string it should contain the
 197 complete path to be excluded.
 198 .Sp
 199 The paths can be either directories or specific files. If the exclusion
 200 matches a directory, all of its files and subdirectories are ignored.
 201 .ie n .IP "* follow_symlinks => $bool" 4
 202 .el .IP "* follow_symlinks => \f(CW$bool\fR" 4
 203 .IX Item "follow_symlinks => $bool"
 204 By default, symlinks are ignored. Set this to true to follow them.
 205 .Sp
 206 If this symlinks are being followed, symlinks to files and directories
 207 will be followed. Directories will be watched, and changes for
 208 directories and files reported.
 209 .ie n .IP "* sleep_interval => $number" 4
 210 .el .IP "* sleep_interval => \f(CW$number\fR" 4
 211 .IX Item "sleep_interval => $number"
 212 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
 213 it sleeps for. The value is a number in seconds.
 214 .Sp
 215 The default is 2 seconds.
 216 .ie n .IP "* event_class => $class" 4
 217 .el .IP "* event_class => \f(CW$class\fR" 4
 218 .IX Item "event_class => $class"
 219 This can be used to change the class used to report events. By
 220 default, this is File::ChangeNotify::Event.
 221 .Sh "$watcher\->\fIwait_for_events()\fP"
 222 .IX Subsection "$watcher->wait_for_events()"
 223 This method causes the watcher to block until it sees interesting
 224 events, and then return them as a list.
 225 .PP
 226 Some watcher subclasses may implement blocking as a sleep loop, while
 227 others may actually block.
 228 .Sh "$watcher\->\fInew_events()\fP"
 229 .IX Subsection "$watcher->new_events()"
 230 This method returns a list of any interesting events seen since the
 231 last time the watcher checked.
 232 .Sh "$watcher\->\fIsees_all_events()\fP"
 233 .IX Subsection "$watcher->sees_all_events()"
 234 If this is true, the watcher will report on all events.
 235 .PP
 236 Some watchers, like the Default subclass, are not smart enough to
 237 track things like a file being created and then immediately deleted,
 238 and can only detect changes between snapshots of the file system.
 239 .PP
 240 Other watchers, like the Inotify subclass, see all events that happen
 241 and report on them.
 242 .SH "AUTHOR"
 243 .IX Header "AUTHOR"
 244 Dave Rolsky, <autarch@urth.org>
 245 .SH "COPYRIGHT & LICENSE"
 246 .IX Header "COPYRIGHT & LICENSE"
 247 Copyright 2009 Dave Rolsky, All Rights Reserved.
 248 .PP
 249 This program is free software; you can redistribute it and/or modify
 250 it under the same terms as Perl itself.