Commit | Line | Data |
e94260da |
1 | package Package::Stash; |
f10f6217 |
2 | use strict; |
3 | use warnings; |
988beb41 |
4 | # ABSTRACT: routines for manipulating stashes |
f10f6217 |
5 | |
59017825 |
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 | |
15c104e2 |
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 | |
f4979588 |
62 | =head1 SYNOPSIS |
63 | |
e94260da |
64 | my $stash = Package::Stash->new('Foo'); |
15c104e2 |
65 | $stash->add_symbol('%foo', {bar => 1}); |
683542f5 |
66 | # $Foo::foo{bar} == 1 |
15c104e2 |
67 | $stash->has_symbol('$foo') # false |
683542f5 |
68 | my $namespace = $stash->namespace; |
69 | *{ $namespace->{foo} }{HASH} # {bar => 1} |
f4979588 |
70 | |
71 | =head1 DESCRIPTION |
72 | |
683542f5 |
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 | |
56a29840 |
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 | |
988beb41 |
80 | =method new $package_name |
683542f5 |
81 | |
e94260da |
82 | Creates a new C<Package::Stash> object, for the package given as the only |
683542f5 |
83 | argument. |
f4979588 |
84 | |
988beb41 |
85 | =method name |
683542f5 |
86 | |
87 | Returns the name of the package that this object represents. |
88 | |
988beb41 |
89 | =method namespace |
683542f5 |
90 | |
91 | Returns the raw stash itself. |
92 | |
15c104e2 |
93 | =method add_symbol $variable $value %opts |
683542f5 |
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 | |
15c104e2 |
99 | Package::Stash->new('Foo')->add_symbol('%foo') |
683542f5 |
100 | |
101 | will create C<%Foo::foo>. |
102 | |
c61010aa |
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. |
4ada57e0 |
108 | Currently these values are only used if the symbol is a subroutine ('C<&>' |
c61010aa |
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. |
4ada57e0 |
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 | |
15c104e2 |
119 | =method remove_glob $name |
683542f5 |
120 | |
121 | Removes all package variables with the given name, regardless of sigil. |
122 | |
15c104e2 |
123 | =method has_symbol $variable |
683542f5 |
124 | |
125 | Returns whether or not the given package variable (including sigil) exists. |
126 | |
15c104e2 |
127 | =method get_symbol $variable |
683542f5 |
128 | |
129 | Returns the value of the given package variable (including sigil). |
130 | |
15c104e2 |
131 | =method get_or_add_symbol $variable |
e55803fc |
132 | |
15c104e2 |
133 | Like C<get_symbol>, except that it will return an empty hashref or |
e55803fc |
134 | arrayref if the variable doesn't exist. |
135 | |
15c104e2 |
136 | =method remove_symbol $variable |
683542f5 |
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 | |
15c104e2 |
142 | =method list_all_symbols $type_filter |
683542f5 |
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', |
d1f721b3 |
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). |
683542f5 |
150 | |
1156452d |
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 | |
c388e574 |
158 | =head1 BUGS / CAVEATS |
0992f4ec |
159 | |
c388e574 |
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 |
0992f4ec |
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 | |
f4979588 |
172 | =head1 SEE ALSO |
173 | |
f4979588 |
174 | =over 4 |
175 | |
988beb41 |
176 | =item * L<Class::MOP::Package> |
f4979588 |
177 | |
988beb41 |
178 | This module is a factoring out of code that used to live here |
f4979588 |
179 | |
180 | =back |
181 | |
0992f4ec |
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 | |
1355b868 |
214 | Based on code from L<Class::MOP::Package>, by Stevan Little and the Moose |
215 | Cabal. |
0992f4ec |
216 | |
8b16d807 |
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 | |
f4979588 |
229 | =cut |
230 | |
231 | 1; |