From: Peter Rabbitson Date: Sun, 27 Sep 2015 08:13:54 +0000 (+0200) Subject: Eject pod to the end of the file X-Git-Tag: 0.26~9 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit%2Fnamespace-clean.git;a=commitdiff_plain;h=b3b7a821aaaabd87986cddaf2a55c01c4076f862 Eject pod to the end of the file The current file structure is very chaotic, electing to move POD out out of the way before doing any further changes `git blame -M` is smart enough to preserve authorship etc in such cases --- diff --git a/lib/namespace/clean.pm b/lib/namespace/clean.pm index 209dd02..b47a68e 100644 --- a/lib/namespace/clean.pm +++ b/lib/namespace/clean.pm @@ -10,137 +10,6 @@ our $STORAGE_VAR = '__NAMESPACE_CLEAN_STORAGE'; use B::Hooks::EndOfScope 'on_scope_end'; -=head1 NAME - -namespace::clean - Keep imports and functions out of your namespace - -=head1 SYNOPSIS - - package Foo; - use warnings; - use strict; - - use Carp qw(croak); # 'croak' will be removed - - sub bar { 23 } # 'bar' will be removed - - # remove all previously defined functions - use namespace::clean; - - sub baz { bar() } # 'baz' still defined, 'bar' still bound - - # begin to collection function names from here again - no namespace::clean; - - sub quux { baz() } # 'quux' will be removed - - # remove all functions defined after the 'no' unimport - use namespace::clean; - - # Will print: 'No', 'No', 'Yes' and 'No' - print +(__PACKAGE__->can('croak') ? 'Yes' : 'No'), "\n"; - print +(__PACKAGE__->can('bar') ? 'Yes' : 'No'), "\n"; - print +(__PACKAGE__->can('baz') ? 'Yes' : 'No'), "\n"; - print +(__PACKAGE__->can('quux') ? 'Yes' : 'No'), "\n"; - - 1; - -=head1 DESCRIPTION - -=head2 Keeping packages clean - -When you define a function, or import one, into a Perl package, it will -naturally also be available as a method. This does not per se cause -problems, but it can complicate subclassing and, for example, plugin -classes that are included via multiple inheritance by loading them as -base classes. - -The C pragma will remove all previously declared or -imported symbols at the end of the current package's compile cycle. -Functions called in the package itself will still be bound by their -name, but they won't show up as methods on your class or instances. - -By unimporting via C you can tell C to start -collecting functions for the next C specification. - -You can use the C<-except> flag to tell C that you -don't want it to remove a certain function or method. A common use would -be a module exporting an C method along with some functions: - - use ModuleExportingImport; - use namespace::clean -except => [qw( import )]; - -If you just want to C<-except> a single sub, you can pass it directly. -For more than one value you have to use an array reference. - -=head2 Explicitly removing functions when your scope is compiled - -It is also possible to explicitly tell C what packages -to remove when the surrounding scope has finished compiling. Here is an -example: - - package Foo; - use strict; - - # blessed NOT available - - sub my_class { - use Scalar::Util qw( blessed ); - use namespace::clean qw( blessed ); - - # blessed available - return blessed shift; - } - - # blessed NOT available - -=head2 Moose - -When using C together with L you want to keep -the installed C method. So your classes should look like: - - package Foo; - use Moose; - use namespace::clean -except => 'meta'; - ... - -Same goes for L. - -=head2 Cleaning other packages - -You can tell C that you want to clean up another package -instead of the one importing. To do this you have to pass in the C<-cleanee> -option like this: - - package My::MooseX::namespace::clean; - use strict; - - use namespace::clean (); # no cleanup, just load - - sub import { - namespace::clean->import( - -cleanee => scalar(caller), - -except => 'meta', - ); - } - -If you don't care about Cs discover-and-C<-except> logic, and -just want to remove subroutines, try L. - -=head1 METHODS - -=head2 clean_subroutines - -This exposes the actual subroutine-removal logic. - - namespace::clean->clean_subroutines($cleanee, qw( subA subB )); - -will remove C and C from C<$cleanee>. Note that this will remove the -subroutines B and not wait for scope end. If you want to have this -effect at a specific time (e.g. C acts on scope compile end) -it is your responsibility to make sure it runs at that time. - -=cut # Constant to optimise away the unused code branches use constant FIXUP_NEEDED => $] < 5.015_005_1; @@ -256,13 +125,6 @@ sub clean_subroutines { $RemoveSubs->($cleanee, {}, @subs); } -=head2 import - -Makes a snapshot of the current defined functions and installs a -L hook in the current scope to invoke the cleanups. - -=cut - sub import { my ($pragma, @args) = @_; @@ -321,16 +183,6 @@ sub import { } } -=head2 unimport - -This method will be called when you do a - - no namespace::clean; - -It will start a new section of code that defines functions to clean up. - -=cut - sub unimport { my ($pragma, %args) = @_; @@ -349,13 +201,6 @@ sub unimport { return 1; } -=head2 get_class_store - -This returns a reference to a hash in a passed package containing -information about function names included and excluded from removal. - -=cut - sub get_class_store { my ($pragma, $class) = @_; my $stash = Package::Stash->new($class); @@ -365,14 +210,6 @@ sub get_class_store { return $stash->get_symbol($var); } -=head2 get_functions - -Takes a class as argument and returns all currently defined functions -in it as a hash reference with the function name as key and a typeglob -reference to the symbol as value. - -=cut - sub get_functions { my ($pragma, $class) = @_; @@ -383,6 +220,165 @@ sub get_functions { }; } +'Danger! Laws of Thermodynamics may not apply.' + +__END__ + +=head1 NAME + +namespace::clean - Keep imports and functions out of your namespace + +=head1 SYNOPSIS + + package Foo; + use warnings; + use strict; + + use Carp qw(croak); # 'croak' will be removed + + sub bar { 23 } # 'bar' will be removed + + # remove all previously defined functions + use namespace::clean; + + sub baz { bar() } # 'baz' still defined, 'bar' still bound + + # begin to collection function names from here again + no namespace::clean; + + sub quux { baz() } # 'quux' will be removed + + # remove all functions defined after the 'no' unimport + use namespace::clean; + + # Will print: 'No', 'No', 'Yes' and 'No' + print +(__PACKAGE__->can('croak') ? 'Yes' : 'No'), "\n"; + print +(__PACKAGE__->can('bar') ? 'Yes' : 'No'), "\n"; + print +(__PACKAGE__->can('baz') ? 'Yes' : 'No'), "\n"; + print +(__PACKAGE__->can('quux') ? 'Yes' : 'No'), "\n"; + + 1; + +=head1 DESCRIPTION + +=head2 Keeping packages clean + +When you define a function, or import one, into a Perl package, it will +naturally also be available as a method. This does not per se cause +problems, but it can complicate subclassing and, for example, plugin +classes that are included via multiple inheritance by loading them as +base classes. + +The C pragma will remove all previously declared or +imported symbols at the end of the current package's compile cycle. +Functions called in the package itself will still be bound by their +name, but they won't show up as methods on your class or instances. + +By unimporting via C you can tell C to start +collecting functions for the next C specification. + +You can use the C<-except> flag to tell C that you +don't want it to remove a certain function or method. A common use would +be a module exporting an C method along with some functions: + + use ModuleExportingImport; + use namespace::clean -except => [qw( import )]; + +If you just want to C<-except> a single sub, you can pass it directly. +For more than one value you have to use an array reference. + +=head2 Explicitly removing functions when your scope is compiled + +It is also possible to explicitly tell C what packages +to remove when the surrounding scope has finished compiling. Here is an +example: + + package Foo; + use strict; + + # blessed NOT available + + sub my_class { + use Scalar::Util qw( blessed ); + use namespace::clean qw( blessed ); + + # blessed available + return blessed shift; + } + + # blessed NOT available + +=head2 Moose + +When using C together with L you want to keep +the installed C method. So your classes should look like: + + package Foo; + use Moose; + use namespace::clean -except => 'meta'; + ... + +Same goes for L. + +=head2 Cleaning other packages + +You can tell C that you want to clean up another package +instead of the one importing. To do this you have to pass in the C<-cleanee> +option like this: + + package My::MooseX::namespace::clean; + use strict; + + use namespace::clean (); # no cleanup, just load + + sub import { + namespace::clean->import( + -cleanee => scalar(caller), + -except => 'meta', + ); + } + +If you don't care about Cs discover-and-C<-except> logic, and +just want to remove subroutines, try L. + +=head1 METHODS + +=head2 clean_subroutines + +This exposes the actual subroutine-removal logic. + + namespace::clean->clean_subroutines($cleanee, qw( subA subB )); + +will remove C and C from C<$cleanee>. Note that this will remove the +subroutines B and not wait for scope end. If you want to have this +effect at a specific time (e.g. C acts on scope compile end) +it is your responsibility to make sure it runs at that time. + +=head2 import + +Makes a snapshot of the current defined functions and installs a +L hook in the current scope to invoke the cleanups. + + +=head2 unimport + +This method will be called when you do a + + no namespace::clean; + +It will start a new section of code that defines functions to clean up. + +=head2 get_class_store + +This returns a reference to a hash in a passed package containing +information about function names included and excluded from removal. + +=head2 get_functions + +Takes a class as argument and returns all currently defined functions +in it as a hash reference with the function name as key and a typeglob +reference to the symbol as value. + =head1 IMPLEMENTATION DETAILS This module works through the effect that a @@ -439,8 +435,3 @@ Father Chrysostomos This software is copyright (c) 2011 by L This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. - -=cut - -no warnings; -'Danger! Laws of Thermodynamics may not apply.'