lib/Package/Stash.pm

   1 package Package::Stash;
   2 use strict;
   3 use warnings;
   4 # ABSTRACT: routines for manipulating stashes
   5
   6 use XSLoader;
   7 XSLoader::load(
   8     __PACKAGE__,
   9     # we need to be careful not to touch $VERSION at compile time, otherwise
  10     # DynaLoader will assume it's set and check against it, which will cause
  11     # fail when being run in the checkout without dzil having set the actual
  12     # $VERSION
  13     exists $Package::Stash::{VERSION}
  14         ? ${ $Package::Stash::{VERSION} } : (),
  15 );
  16
  17 use Package::DeprecationManager -deprecations => {
  18     'Package::Stash::add_package_symbol'        => 0.14,
  19     'Package::Stash::remove_package_glob'       => 0.14,
  20     'Package::Stash::has_package_symbol'        => 0.14,
  21     'Package::Stash::get_package_symbol'        => 0.14,
  22     'Package::Stash::get_or_add_package_symbol' => 0.14,
  23     'Package::Stash::remove_package_symbol'     => 0.14,
  24     'Package::Stash::list_all_package_symbols'  => 0.14,
  25 };
  26
  27 sub add_package_symbol {
  28     deprecated('add_package_symbol is deprecated, please use add_symbol');
  29     shift->add_symbol(@_);
  30 }
  31
  32 sub remove_package_glob {
  33     deprecated('remove_package_glob is deprecated, please use remove_glob');
  34     shift->remove_glob(@_);
  35 }
  36
  37 sub has_package_symbol {
  38     deprecated('has_package_symbol is deprecated, please use has_symbol');
  39     shift->has_symbol(@_);
  40 }
  41
  42 sub get_package_symbol {
  43     deprecated('get_package_symbol is deprecated, please use get_symbol');
  44     shift->get_symbol(@_);
  45 }
  46
  47 sub get_or_add_package_symbol {
  48     deprecated('get_or_add_package_symbol is deprecated, please use get_or_add_symbol');
  49     shift->get_or_add_symbol(@_);
  50 }
  51
  52 sub remove_package_symbol {
  53     deprecated('remove_package_symbol is deprecated, please use remove_symbol');
  54     shift->remove_symbol(@_);
  55 }
  56
  57 sub list_all_package_symbols {
  58     deprecated('list_all_package_symbols is deprecated, please use list_all_symbols');
  59     shift->list_all_symbols(@_);
  60 }
  61
  62 =head1 SYNOPSIS
  63
  64   my $stash = Package::Stash->new('Foo');
  65   $stash->add_symbol('%foo', {bar => 1});
  66   # $Foo::foo{bar} == 1
  67   $stash->has_symbol('$foo') # false
  68   my $namespace = $stash->namespace;
  69   *{ $namespace->{foo} }{HASH} # {bar => 1}
  70
  71 =head1 DESCRIPTION
  72
  73 Manipulating stashes (Perl's symbol tables) is occasionally necessary, but
  74 incredibly messy, and easy to get wrong. This module hides all of that behind a
  75 simple API.
  76
  77 NOTE: Most methods in this class require a variable specification that includes
  78 a sigil. If this sigil is absent, it is assumed to represent the IO slot.
  79
  80 =method new $package_name
  81
  82 Creates a new C<Package::Stash> object, for the package given as the only
  83 argument.
  84
  85 =method name
  86
  87 Returns the name of the package that this object represents.
  88
  89 =method namespace
  90
  91 Returns the raw stash itself.
  92
  93 =method add_symbol $variable $value %opts
  94
  95 Adds a new package symbol, for the symbol given as C<$variable>, and optionally
  96 gives it an initial value of C<$value>. C<$variable> should be the name of
  97 variable including the sigil, so
  98
  99   Package::Stash->new('Foo')->add_symbol('%foo')
 100
 101 will create C<%Foo::foo>.
 102
 103 Valid options (all optional) are C<filename>, C<first_line_num>, and
 104 C<last_line_num>.
 105
 106 C<$opts{filename}>, C<$opts{first_line_num}>, and C<$opts{last_line_num}> can
 107 be used to indicate where the symbol should be regarded as having been defined.
 108 Currently these values are only used if the symbol is a subroutine ('C<&>'
 109 sigil) and only if C<$^P & 0x10> is true, in which case the special C<%DB::sub>
 110 hash is updated to record the values of C<filename>, C<first_line_num>, and
 111 C<last_line_num> for the subroutine. If these are not passed, their values are
 112 inferred (as much as possible) from C<caller> information.
 113
 114 This is especially useful for debuggers and profilers, which use C<%DB::sub> to
 115 determine where the source code for a subroutine can be found.  See
 116 L<http://perldoc.perl.org/perldebguts.html#Debugger-Internals> for more
 117 information about C<%DB::sub>.
 118
 119 =method remove_glob $name
 120
 121 Removes all package variables with the given name, regardless of sigil.
 122
 123 =method has_symbol $variable
 124
 125 Returns whether or not the given package variable (including sigil) exists.
 126
 127 =method get_symbol $variable
 128
 129 Returns the value of the given package variable (including sigil).
 130
 131 =method get_or_add_symbol $variable
 132
 133 Like C<get_symbol>, except that it will return an empty hashref or
 134 arrayref if the variable doesn't exist.
 135
 136 =method remove_symbol $variable
 137
 138 Removes the package variable described by C<$variable> (which includes the
 139 sigil); other variables with the same name but different sigils will be
 140 untouched.
 141
 142 =method list_all_symbols $type_filter
 143
 144 Returns a list of package variable names in the package, without sigils. If a
 145 C<type_filter> is passed, it is used to select package variables of a given
 146 type, where valid types are the slots of a typeglob ('SCALAR', 'CODE', 'HASH',
 147 etc). Note that if the package contained any C<BEGIN> blocks, perl will leave
 148 an empty typeglob in the C<BEGIN> slot, so this will show up if no filter is
 149 used (and similarly for C<INIT>, C<END>, etc).
 150
 151 =method get_all_symbols $type_filter
 152
 153 Returns a hashref, keyed by the variable names in the package. If
 154 C<$type_filter> is passed, the hash will contain every variable of that type in
 155 the package as values, otherwise, it will contain the typeglobs corresponding
 156 to the variable names (basically, a clone of the stash).
 157
 158 =head1 BUGS / CAVEATS
 159
 160 =over 4
 161
 162 =item * On perl versions prior to 5.10, undefined package scalars will not show up as existing, due to shortcomings within perl.
 163
 164 =item * GLOB and FORMAT variables are not (yet) accessible through this module.
 165
 166 =back
 167
 168 Please report any bugs through RT: email
 169 C<bug-package-stash at rt.cpan.org>, or browse to
 170 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Package-Stash>.
 171
 172 =head1 SEE ALSO
 173
 174 =over 4
 175
 176 =item * L<Class::MOP::Package>
 177
 178 This module is a factoring out of code that used to live here
 179
 180 =back
 181
 182 =head1 SUPPORT
 183
 184 You can find this documentation for this module with the perldoc command.
 185
 186     perldoc Package::Stash
 187
 188 You can also look for information at:
 189
 190 =over 4
 191
 192 =item * AnnoCPAN: Annotated CPAN documentation
 193
 194 L<http://annocpan.org/dist/Package-Stash>
 195
 196 =item * CPAN Ratings
 197
 198 L<http://cpanratings.perl.org/d/Package-Stash>
 199
 200 =item * RT: CPAN's request tracker
 201
 202 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Package-Stash>
 203
 204 =item * Search CPAN
 205
 206 L<http://search.cpan.org/dist/Package-Stash>
 207
 208 =back
 209
 210 =head1 AUTHOR
 211
 212 Jesse Luehrs <doy at tozt dot net>
 213
 214 Based on code from L<Class::MOP::Package>, by Stevan Little and the Moose
 215 Cabal.
 216
 217 =begin Pod::Coverage
 218
 219 add_package_symbol
 220 remove_package_glob
 221 has_package_symbol
 222 get_package_symbol
 223 get_or_add_package_symbol
 224 remove_package_symbol
 225 list_all_package_symbols
 226
 227 =end Pod::Coverage
 228
 229 =cut
 230
 231 1;