diff options
author | Jesse Luehrs <doy@tozt.net> | 2011-01-25 15:33:05 -0600 |
---|---|---|
committer | Jesse Luehrs <doy@tozt.net> | 2011-01-25 15:35:39 -0600 |
commit | 3ccc98d18c503cdf062776bcb874c7097f6d03eb (patch) | |
tree | 233444e34e394a1bee5707b087403c0133c81935 | |
parent | a010922759e895ca9eaec3c1187910f5622ced53 (diff) | |
download | circular-require-3ccc98d18c503cdf062776bcb874c7097f6d03eb.tar.gz circular-require-3ccc98d18c503cdf062776bcb874c7097f6d03eb.zip |
docs
-rw-r--r-- | lib/circular/require.pm | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/lib/circular/require.pm b/lib/circular/require.pm index 882b2b7..16660c2 100644 --- a/lib/circular/require.pm +++ b/lib/circular/require.pm @@ -1,8 +1,42 @@ package circular::require; use strict; use warnings; +# ABSTRACT: detect circularity in use/require statements + use Package::Stash; +=head1 SYNOPSIS + + package Foo; + use Bar; + + package Bar; + use Foo; + + package main; + no circular::require; + use Foo; # warns + +or + + perl -M-circular::require foo.pl + +=head1 DESCRIPTION + +Perl by default just ignores cycles in require statements - if Foo.pm does +C<use Bar> and Bar.pm does C<use Foo>, doing C<use Foo> elsewhere will start +loading Foo.pm, then hit the C<use> statement, start loading Bar.pm, hit the +C<use> statement, notice that Foo.pm has already started loading and ignore it, +and continue loading Bar.pm. But Foo.pm hasn't finished loading yet, so if +Bar.pm uses anything from Foo.pm (which it likely does, if it's loading it), +those won't be accessible while the body of Bar.pm is being executed. This can +lead to some very confusing errors, especially if introspection is happening at +load time (C<make_immutable> in L<Moose> classes, for example). This module +generates a warning whenever a module is skipped due to being loaded, if that +module has not finished executing. + +=cut + my %seen; my $saved; @@ -35,4 +69,48 @@ sub unimport { $stash->add_package_symbol('&require', \&_require); } +=head1 CAVEATS + +This module works by overriding C<CORE::GLOBAL::require>, and so other modules +which do this may cause issues if they aren't written properly. This also means +that the effect is global, but this is typically the most useful usage. + +=head1 BUGS + +No known bugs. + +Please report any bugs through RT: email +C<bug-circular-require at rt.cpan.org>, or browse to +L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=circular-require>. + +=head1 SUPPORT + +You can find this documentation for this module with the perldoc command. + + perldoc circular::require + +You can also look for information at: + +=over 4 + +=item * AnnoCPAN: Annotated CPAN documentation + +L<http://annocpan.org/dist/circular-require> + +=item * CPAN Ratings + +L<http://cpanratings.perl.org/d/circular-require> + +=item * RT: CPAN's request tracker + +L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=circular-require> + +=item * Search CPAN + +L<http://search.cpan.org/dist/circular-require> + +=back + +=cut + 1; |