docs

2 files changed, 85 insertions, 2 deletions

diff --git a/dist.ini b/dist.ini
index f8a586b..50b42fa 100644
--- a/dist.ini
+++ b/dist.ini
@@ -3,8 +3,9 @@ version = 0.01
 author = Jesse Luehrs <doy at tozt dot net>
 license = Perl_5
 copyright_holder = Jesse Luehrs
-abstract =
+abstract = routines for manipulating stashes
 
 [@Classic]
 
 [Prereq]
+Scalar::Util = 0
diff --git a/lib/Stash/Manip.pm b/lib/Stash/Manip.pm
index b6e0061..be37e87 100644
--- a/lib/Stash/Manip.pm
+++ b/lib/Stash/Manip.pm
@@ -7,13 +7,31 @@ use Scalar::Util qw(reftype);
 
 =head1 NAME
 
-Stash::Manip -
+Stash::Manip - routines for manipulating stashes
 
 =head1 SYNOPSIS
 
+  my $stash = Stash::Manip->new('Foo');
+  $stash->add_package_symbol('%foo', {bar => 1});
+  # $Foo::foo{bar} == 1
+  $stash->has_package_symbol('$foo') # false
+  my $namespace = $stash->namespace;
+  *{ $namespace->{foo} }{HASH} # {bar => 1}
 
 =head1 DESCRIPTION
 
+Manipulating stashes (Perl's symbol tables) is occasionally necessary, but
+incredibly messy, and easy to get wrong. This module hides all of that behind a
+simple API.
+
+=head1 METHODS
+
+=cut
+
+=head2 new $package_name
+
+Creates a new C<Stash::Manip> object, for the package given as the only
+argument.
 
 =cut
 
@@ -23,10 +41,22 @@ sub new {
     return bless { package => $namespace }, $class;
 }
 
+=head2 name
+
+Returns the name of the package that this object represents.
+
+=cut
+
 sub name {
     return $_[0]->{package};
 }
 
+=head2 namespace
+
+Returns the raw stash itself.
+
+=cut
+
 sub namespace {
     # NOTE:
     # because of issues with the Perl API 
@@ -65,6 +95,18 @@ sub namespace {
     }
 }
 
+=head2 add_package_symbol $variable $value
+
+Adds a new package symbol, for the symbol given as C<$variable>, and optionally
+gives it an initial value of C<$value>. C<$variable> should be the name of
+variable including the sigil, so
+
+  Stash::Manip->new('Foo')->add_package_symbol('%foo')
+
+will create C<%Foo::foo>.
+
+=cut
+
 sub add_package_symbol {
     my ($self, $variable, $initial_value) = @_;
 
@@ -79,6 +121,12 @@ sub add_package_symbol {
     *{$pkg . '::' . $name} = ref $initial_value ? $initial_value : \$initial_value;
 }
 
+=head2 remove_package_glob $name
+
+Removes all package variables with the given name, regardless of sigil.
+
+=cut
+
 sub remove_package_glob {
     my ($self, $name) = @_;
     no strict 'refs';
@@ -87,6 +135,12 @@ sub remove_package_glob {
 
 # ... these functions deal with stuff on the namespace level
 
+=head2 has_package_symbol $variable
+
+Returns whether or not the given package variable (including sigil) exists.
+
+=cut
+
 sub has_package_symbol {
     my ($self, $variable) = @_;
 
@@ -114,6 +168,12 @@ sub has_package_symbol {
     }
 }
 
+=head2 get_package_symbol $variable
+
+Returns the value of the given package variable (including sigil).
+
+=cut
+
 sub get_package_symbol {
     my ($self, $variable) = @_;
 
@@ -143,6 +203,14 @@ sub get_package_symbol {
     }
 }
 
+=head2 remove_package_symbol $variable
+
+Removes the package variable described by C<$variable> (which includes the
+sigil); other variables with the same name but different sigils will be
+untouched.
+
+=cut
+
 sub remove_package_symbol {
     my ($self, $variable) = @_;
 
@@ -194,6 +262,15 @@ sub remove_package_symbol {
     $self->add_package_symbol($code_desc   => $code)   if defined $code;
 }
 
+=head2 list_all_package_symbols $type_filter
+
+Returns a list of package variable names in the package, without sigils. If a
+C<type_filter> is passed, it is used to select package variables of a given
+type, where valid types are the slots of a typeglob ('SCALAR', 'CODE', 'HASH',
+etc).
+
+=cut
+
 sub list_all_package_symbols {
     my ($self, $type_filter) = @_;
 
@@ -225,6 +302,8 @@ L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Stash-Manip>.
 
 =head1 SEE ALSO
 
+L<Class::MOP::Package> - this module is a factoring out of code that used to
+live here
 
 =head1 SUPPORT
 
@@ -258,6 +337,9 @@ L<http://search.cpan.org/dist/Stash-Manip>
 
   Jesse Luehrs <doy at tozt dot net>
 
+Mostly copied from code from L<Class::MOP::Package>, by Stevan Little and the
+Moose Cabal.
+
 =head1 COPYRIGHT AND LICENSE
 
 This software is copyright (c) 2010 by Jesse Luehrs.