[p5sagit/namespace-clean.git] / README

NAME
    namespace::clean - Keep imports out of your namespace

VERSION
    0.02

SYNOPSIS
      package Foo;
      use warnings;
      use strict;

      use Carp qw(croak);   # will be removed

      sub bar { 23 }        # will be removed

      use namespace::clean;

      sub baz { bar() }     # still defined, 'bar' still bound

      no namespace::clean;

      sub quux { baz() }    # will be removed again

      use namespace::clean;

      ### Will print:
      #   No
      #   No
      #   Yes
      #   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
    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.

    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.

METHODS
    You shouldn't need to call any of these. Just "use" the package at the
    appropriate place.

  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.

  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 your 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.

SEE ALSO
    Filter::EOF

AUTHOR AND COPYRIGHT
    Robert 'phaylon' Sedlacek "<rs@474.at>", 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.
Commit	Line	Data
40aef9d6	1	NAME
	2	namespace::clean - Keep imports out of your namespace
	3
	4	VERSION
9b680ffe	5	0.02
40aef9d6	6
	7	SYNOPSIS
	8	package Foo;
	9	use warnings;
	10	use strict;
	11
	12	use Carp qw(croak); # will be removed
	13
	14	sub bar { 23 } # will be removed
	15
	16	use namespace::clean;
	17
	18	sub baz { bar() } # still defined, 'bar' still bound
	19
9b680ffe	20	no namespace::clean;
	21
	22	sub quux { baz() } # will be removed again
	23
	24	use namespace::clean;
	25
40aef9d6	26	### Will print:
	27	# No
	28	# No
	29	# Yes
9b680ffe	30	# No
40aef9d6	31	print +(__PACKAGE__->can('croak') ? 'Yes' : 'No'), "\n";
	32	print +(__PACKAGE__->can('bar') ? 'Yes' : 'No'), "\n";
	33	print +(__PACKAGE__->can('baz') ? 'Yes' : 'No'), "\n";
9b680ffe	34	print +(__PACKAGE__->can('quux') ? 'Yes' : 'No'), "\n";
40aef9d6	35
	36	1;
	37
	38	DESCRIPTION
	39	When you define a function, or import one, into a Perl package, it will
	40	naturally also be available as a method. This does not per se cause
	41	problems, but it can complicate subclassing and, for example, plugin
	42	classes that are included by loading them as base classes.
	43
	44	The "namespace::clean" pragma will remove all previously declared or
	45	imported symbols at the end of the current package's compile cycle. This
	46	means that functions are already bound by their name, and calls to them
	47	still work. But they will not be available as methods on your class or
	48	instances.
	49
	50	METHODS
	51	You shouldn't need to call any of these. Just "use" the package at the
	52	appropriate place.
	53
	54	import
	55	Makes a snapshot of the current defined functions and registers a
	56	Filter::EOF cleanup routine to remove those symbols from the package at
	57	the end of the compile-time.
	58
9b680ffe	59	unimport
	60	This method will be called when you do a
	61
	62	no namespace::clean;
	63
	64	It will start a new section of code that defines functions to clean up.
	65
	66	get_class_store
	67	This returns a reference to a hash in your package containing
	68	information about function names included and excluded from removal.
	69
40aef9d6	70	get_functions
	71	Takes a class as argument and returns all currently defined functions in
	72	it as a hash reference with the function name as key and a typeglob
	73	reference to the symbol as value.
	74
	75	SEE ALSO
	76	Filter::EOF
	77
	78	AUTHOR AND COPYRIGHT
	79	Robert 'phaylon' Sedlacek "<rs@474.at>", with many thanks to Matt S
	80	Trout for the inspiration on the whole idea.
	81
	82	LICENSE
	83	This program is free software; you can redistribute it and/or modify it
	84	under the same terms as perl itself.
	85