whitespace/style cleanups
[gitmo/Moo.git] / lib / Sub / Defer.pm
1 package Sub::Defer;
2
3 use strictures 1;
4 use base qw(Exporter);
5 use Moo::_Utils;
6 use Scalar::Util qw(weaken);
7
8 our $VERSION = '1.003001';
9 $VERSION = eval $VERSION;
10
11 our @EXPORT = qw(defer_sub undefer_sub);
12
13 our %DEFERRED;
14
15 sub undefer_sub {
16   my ($deferred) = @_;
17   my ($target, $maker, $undeferred_ref) = @{
18     $DEFERRED{$deferred}||return $deferred
19   };
20   return ${$undeferred_ref}
21     if ${$undeferred_ref};
22   ${$undeferred_ref} = my $made = $maker->();
23
24   # make sure the method slot has not changed since deferral time
25   if (defined($target) && $deferred eq *{_getglob($target)}{CODE}||'') {
26     no warnings 'redefine';
27
28     # I believe $maker already evals with the right package/name, so that
29     # _install_coderef calls are not necessary --ribasushi
30     *{_getglob($target)} = $made;
31   }
32   weaken($DEFERRED{$made} = $DEFERRED{$deferred});
33
34   return $made;
35 }
36
37 sub defer_info {
38   my ($deferred) = @_;
39   $DEFERRED{$deferred||''};
40 }
41
42 sub defer_sub {
43   my ($target, $maker) = @_;
44   my $undeferred;
45   my $deferred_info;
46   my $deferred = sub {
47     $undeferred ||= undefer_sub($deferred_info->[3]);
48     goto &$undeferred;
49   };
50   $deferred_info = [ $target, $maker, \$undeferred, $deferred ];
51   weaken($DEFERRED{$deferred} = $deferred_info);
52   _install_coderef($target => $deferred) if defined $target;
53   return $deferred;
54 }
55
56 sub CLONE {
57   %DEFERRED = map { defined $_ ? ($_->[3] => $_) : () } values %DEFERRED;
58   weaken($_) for values %DEFERRED;
59 }
60
61 1;
62
63 =head1 NAME
64
65 Sub::Defer - defer generation of subroutines until they are first called
66
67 =head1 SYNOPSIS
68
69  use Sub::Defer;
70
71  my $deferred = defer_sub 'Logger::time_since_first_log' => sub {
72     my $t = time;
73     sub { time - $t };
74  };
75
76   Logger->time_since_first_log; # returns 0 and replaces itself
77   Logger->time_since_first_log; # returns time - $t
78
79 =head1 DESCRIPTION
80
81 These subroutines provide the user with a convenient way to defer creation of
82 subroutines and methods until they are first called.
83
84 =head1 SUBROUTINES
85
86 =head2 defer_sub
87
88  my $coderef = defer_sub $name => sub { ... };
89
90 This subroutine returns a coderef that encapsulates the provided sub - when
91 it is first called, the provided sub is called and is -itself- expected to
92 return a subroutine which will be goto'ed to on subsequent calls.
93
94 If a name is provided, this also installs the sub as that name - and when
95 the subroutine is undeferred will re-install the final version for speed.
96
97 =head2 undefer_sub
98
99  my $coderef = undefer_sub \&Foo::name;
100
101 If the passed coderef has been L<deferred|/defer_sub> this will "undefer" it.
102 If the passed coderef has not been deferred, this will just return it.
103
104 If this is confusing, take a look at the example in the L</SYNOPSIS>.
105
106 =head1 SUPPORT
107
108 See L<Moo> for support and contact information.
109
110 =head1 AUTHORS
111
112 See L<Moo> for authors.
113
114 =head1 COPYRIGHT AND LICENSE
115
116 See L<Moo> for the copyright and license.