From: Florian Ragwitz Date: Thu, 14 Jan 2010 02:19:44 +0000 (+0100) Subject: Remove auto-generated README. X-Git-Tag: 0.12~1 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=cccfea04f26525bb4c782e84aa9229dec1e1fe27;p=p5sagit%2Fnamespace-clean.git Remove auto-generated README. --- diff --git a/README b/README deleted file mode 100644 index 6f2aca5..0000000 --- a/README +++ /dev/null @@ -1,175 +0,0 @@ -NAME - namespace::clean - Keep imports and functions out of your namespace - -VERSION - 0.11 - -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; - -DESCRIPTION - 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 "namespace::clean" 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 "no" you can tell "namespace::clean" to start - collecting functions for the next "use namespace::clean;" specification. - - You can use the "-except" flag to tell "namespace::clean" that you don't - want it to remove a certain function or method. A common use would be a - module exporting an "import" method along with some functions: - - use ModuleExportingImport; - use namespace::clean -except => [qw( import )]; - - If you just want to "-except" a single sub, you can pass it directly. - For more than one value you have to use an array reference. - - Explicitely removing functions when your scope is compiled - It is also possible to explicitely tell "namespace::clean" 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 - - Moose - When using "namespace::clean" together with Moose you want to keep the - installed "meta" method. So your classes should look like: - - package Foo; - use Moose; - use namespace::clean -except => 'meta'; - ... - - Same goes for Moose::Role. - - Cleaning other packages - You can tell "namespace::clean" that you want to clean up another - package instead of the one importing. To do this you have to pass in the - "-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 "namespace::clean"s discover-and-"-except" - logic, and just want to remove subroutines, try "clean_subroutines". - -METHODS - You shouldn't need to call any of these. Just "use" the package at the - appropriate place. - - clean_subroutines - This exposes the actual subroutine-removal logic. - - namespace::clean->clean_subroutines($cleanee, qw( subA subB )); - - will remove "subA" and "subB" from $cleanee. Note that this will remove - the subroutines immediately and not wait for scope end. If you want to - have this effect at a specific time (e.g. "namespace::clean" acts on - scope compile end) it is your responsibility to make sure it runs at - that time. - - import - Makes a snapshot of the current defined functions and installs a - B::Hooks::EndOfScope hook in the current scope to invoke the cleanups. - - 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. - - get_class_store - This returns a reference to a hash in a passed package containing - information about function names included and excluded from removal. - - 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. - -IMPLEMENTATION DETAILS - This module works through the effect that a - - delete $SomePackage::{foo}; - - will remove the "foo" symbol from $SomePackage for run time lookups - (e.g., method calls) but will leave the entry alive to be called by - already resolved names in the package itself. "namespace::clean" will - restore and therefor in effect keep all glob slots that aren't "CODE". - - A test file has been added to the perl core to ensure that this - behaviour will be stable in future releases. - - Just for completeness sake, if you want to remove the symbol completely, - use "undef" instead. - -SEE ALSO - B::Hooks::EndOfScope - -AUTHOR AND COPYRIGHT - Robert 'phaylon' Sedlacek "", with many thanks to Matt S - Trout for the inspiration on the whole idea. - -LICENSE - This program is free software; you can redistribute it and/or modify it - under the same terms as perl itself. -