Commit | Line | Data |
3fea05b9 |
1 | package File::ChangeNotify; |
2 | |
3 | use strict; |
4 | use warnings; |
5 | |
6 | our $VERSION = '0.11'; |
7 | |
8 | use Carp qw( confess ); |
9 | use Class::MOP; |
10 | use Module::Pluggable::Object; |
11 | |
12 | sub instantiate_watcher { |
13 | my $class = shift; |
14 | |
15 | for my $class ( $class->usable_classes() ) { |
16 | if ( _try_load($class) ) { |
17 | return $class->new(@_); |
18 | } |
19 | } |
20 | |
21 | die |
22 | "Could not load a File::ChangeNotify::Watcher subclass (this should not happen, something is badly broken)"; |
23 | } |
24 | |
25 | { |
26 | my @usable_classes = (); |
27 | |
28 | sub usable_classes { |
29 | my $class = shift; |
30 | |
31 | return @usable_classes if @usable_classes; |
32 | return @usable_classes = grep { _try_load($_) } $class->_all_classes(); |
33 | } |
34 | } |
35 | |
36 | sub _try_load { |
37 | my $class = shift; |
38 | |
39 | eval { Class::MOP::load_class($class) }; |
40 | |
41 | my $e = $@; |
42 | die $e if $e && $e !~ /Can\'t locate|did not return a true value/; |
43 | |
44 | return $e ? 0 : 1; |
45 | } |
46 | |
47 | my $finder = Module::Pluggable::Object->new( |
48 | search_path => 'File::ChangeNotify::Watcher' ); |
49 | |
50 | sub _all_classes { |
51 | return sort _sort_classes $finder->plugins(); |
52 | } |
53 | |
54 | sub _sort_classes { |
55 | $a eq 'File::ChangeNotify::Watcher::Default' ? 1 |
56 | : $b eq 'File::ChangeNotify::Watcher::Default' ? -1 |
57 | : $a cmp $b; |
58 | } |
59 | |
60 | 1; |
61 | |
62 | __END__ |
63 | |
64 | =pod |
65 | |
66 | =head1 NAME |
67 | |
68 | File::ChangeNotify - Watch for changes to files, cross-platform style |
69 | |
70 | =head1 SYNOPSIS |
71 | |
72 | use File::ChangeNotify; |
73 | |
74 | my $watcher = |
75 | File::ChangeNotify->instantiate_watcher |
76 | ( directories => [ '/my/path', '/my/other' ], |
77 | filter => qr/\.(?:pm|conf|yml)$/, |
78 | ); |
79 | |
80 | if ( my @events = $watcher->new_events() ) { ... } |
81 | |
82 | # blocking |
83 | while ( my @events = $watcher->wait_for_events() ) { ... } |
84 | |
85 | =head1 DESCRIPTION |
86 | |
87 | This module provides an API for creating a |
88 | L<File::ChangeNotify::Watcher> subclass that will work on your |
89 | platform. |
90 | |
91 | Most of the documentation for this distro is in |
92 | L<File::ChangeNotify::Watcher>. |
93 | |
94 | =head1 METHODS |
95 | |
96 | This class provides the following methods: |
97 | |
98 | =head2 File::ChangeNotify->instantiate_watcher(...) |
99 | |
100 | This method looks at each available subclass of |
101 | L<File::ChangeNotify::Watcher> and instantiates the first one it can |
102 | load, using the arguments you provided. |
103 | |
104 | It always tries to use the L<File::ChangeNotify::Watcher::Default> |
105 | class last, on the assumption that any other class that is available |
106 | is a better option. |
107 | |
108 | =head2 File::ChangeNotify->usable_classes() |
109 | |
110 | Returns a list of all the loadable L<File::ChangeNotify::Watcher> |
111 | subclasses. |
112 | |
113 | =head1 DONATIONS |
114 | |
115 | If you'd like to thank me for the work I've done on this module, |
116 | please consider making a "donation" to me via PayPal. I spend a lot of |
117 | free time creating free software, and would appreciate any support |
118 | you'd care to offer. |
119 | |
120 | Please note that B<I am not suggesting that you must do this> in order |
121 | for me to continue working on this particular software. I will |
122 | continue to do so, inasmuch as I have in the past, for as long as it |
123 | interests me. |
124 | |
125 | Similarly, a donation made in this way will probably not make me work |
126 | on this software much more, unless I get so many donations that I can |
127 | consider working on free software full time, which seems unlikely at |
128 | best. |
129 | |
130 | To donate, log into PayPal and send money to autarch@urth.org or use |
131 | the button on this page: |
132 | L<http://www.urth.org/~autarch/fs-donation.html> |
133 | |
134 | =head1 AUTHOR |
135 | |
136 | Dave Rolsky, E<lt>autarch@urth.orgE<gt> |
137 | |
138 | =head1 BUGS |
139 | |
140 | Please report any bugs or feature requests to |
141 | C<bug-file-changenotify@rt.cpan.org>, or through the web interface at |
142 | L<http://rt.cpan.org>. I will be notified, and then you'll |
143 | automatically be notified of progress on your bug as I make changes. |
144 | |
145 | =head1 COPYRIGHT & LICENSE |
146 | |
147 | Copyright 2009 Dave Rolsky, All Rights Reserved. |
148 | |
149 | This program is free software; you can redistribute it and/or modify |
150 | it under the same terms as Perl itself. |
151 | |
152 | =cut |