Version 0.11.

[p5sagit/namespace-clean.git] / README

diff --git a/README b/README
index ee8a034..6f2aca5 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     namespace::clean - Keep imports and functions out of your namespace
 
 VERSION
-    0.03
+    0.11
 
 SYNOPSIS
       package Foo;
@@ -35,6 +35,7 @@ SYNOPSIS
       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
@@ -49,14 +50,85 @@ DESCRIPTION
     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 registers a
-    Filter::EOF cleanup routine to remove those symbols at the end of the
-    compile-time.
+    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
@@ -81,7 +153,8 @@ IMPLEMENTATION DETAILS
 
     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.
+    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.
@@ -90,7 +163,7 @@ IMPLEMENTATION DETAILS
     use "undef" instead.
 
 SEE ALSO
-    Filter::EOF
+    B::Hooks::EndOfScope
 
 AUTHOR AND COPYRIGHT
     Robert 'phaylon' Sedlacek "<rs@474.at>", with many thanks to Matt S