Import namespace-clean-0.06.tar.gz.

[p5sagit/namespace-clean.git] / README

diff --git a/README b/README
index c9a67b9..53a90ff 100644 (file)
--- a/README
+++ b/README
@@ -1,29 +1,36 @@
 NAME
-    namespace::clean - Keep imports out of your namespace
+    namespace::clean - Keep imports and functions out of your namespace
 
 VERSION
-    0.01
+    0.06
 
 SYNOPSIS
       package Foo;
       use warnings;
       use strict;
 
-      use Carp qw(croak);   # will be removed
+      use Carp qw(croak);   # 'croak' will be removed
 
-      sub bar { 23 }        # will be removed
+      sub bar { 23 }        # 'bar' will be removed
 
+      # remove all previously defined functions
       use namespace::clean;
 
-      sub baz { bar() }     # still defined, 'bar' still bound
+      sub baz { bar() }     # 'baz' still defined, 'bar' still bound
 
-      ### Will print:
-      #   No
-      #   No
-      #   Yes
+      # 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;
 
@@ -31,13 +38,26 @@ DESCRIPTION
     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 by loading them as base classes.
+    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. This
-    means that functions are already bound by their name, and calls to them
-    still work. But they will not be available as methods on your class or
-    instances.
+    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.
 
 METHODS
     You shouldn't need to call any of these. Just "use" the package at the
@@ -45,14 +65,41 @@ METHODS
 
   import
     Makes a snapshot of the current defined functions and registers a
-    Filter::EOF cleanup routine to remove those symbols from the package at
-    the end of the compile-time.
+    Filter::EOF cleanup routine to remove those symbols at the end of the
+    compile-time.
+
+  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
     Filter::EOF