local-lib5/lib/perl5/File/ChangeNotify.pm

   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