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 | |
f4979588 |
17 | =head1 SYNOPSIS |
18 | |
e94260da |
19 | my $stash = Package::Stash->new('Foo'); |
683542f5 |
20 | $stash->add_package_symbol('%foo', {bar => 1}); |
21 | # $Foo::foo{bar} == 1 |
22 | $stash->has_package_symbol('$foo') # false |
23 | my $namespace = $stash->namespace; |
24 | *{ $namespace->{foo} }{HASH} # {bar => 1} |
f4979588 |
25 | |
26 | =head1 DESCRIPTION |
27 | |
683542f5 |
28 | Manipulating stashes (Perl's symbol tables) is occasionally necessary, but |
29 | incredibly messy, and easy to get wrong. This module hides all of that behind a |
30 | simple API. |
31 | |
56a29840 |
32 | NOTE: Most methods in this class require a variable specification that includes |
33 | a sigil. If this sigil is absent, it is assumed to represent the IO slot. |
34 | |
988beb41 |
35 | =method new $package_name |
683542f5 |
36 | |
e94260da |
37 | Creates a new C<Package::Stash> object, for the package given as the only |
683542f5 |
38 | argument. |
f4979588 |
39 | |
988beb41 |
40 | =method name |
683542f5 |
41 | |
42 | Returns the name of the package that this object represents. |
43 | |
988beb41 |
44 | =method namespace |
683542f5 |
45 | |
46 | Returns the raw stash itself. |
47 | |
988beb41 |
48 | =method add_package_symbol $variable $value %opts |
683542f5 |
49 | |
50 | Adds a new package symbol, for the symbol given as C<$variable>, and optionally |
51 | gives it an initial value of C<$value>. C<$variable> should be the name of |
52 | variable including the sigil, so |
53 | |
e94260da |
54 | Package::Stash->new('Foo')->add_package_symbol('%foo') |
683542f5 |
55 | |
56 | will create C<%Foo::foo>. |
57 | |
c61010aa |
58 | Valid options (all optional) are C<filename>, C<first_line_num>, and |
59 | C<last_line_num>. |
60 | |
61 | C<$opts{filename}>, C<$opts{first_line_num}>, and C<$opts{last_line_num}> can |
62 | be used to indicate where the symbol should be regarded as having been defined. |
4ada57e0 |
63 | Currently these values are only used if the symbol is a subroutine ('C<&>' |
c61010aa |
64 | sigil) and only if C<$^P & 0x10> is true, in which case the special C<%DB::sub> |
65 | hash is updated to record the values of C<filename>, C<first_line_num>, and |
66 | C<last_line_num> for the subroutine. If these are not passed, their values are |
67 | inferred (as much as possible) from C<caller> information. |
4ada57e0 |
68 | |
69 | This is especially useful for debuggers and profilers, which use C<%DB::sub> to |
70 | determine where the source code for a subroutine can be found. See |
71 | L<http://perldoc.perl.org/perldebguts.html#Debugger-Internals> for more |
72 | information about C<%DB::sub>. |
73 | |
988beb41 |
74 | =method remove_package_glob $name |
683542f5 |
75 | |
76 | Removes all package variables with the given name, regardless of sigil. |
77 | |
988beb41 |
78 | =method has_package_symbol $variable |
683542f5 |
79 | |
80 | Returns whether or not the given package variable (including sigil) exists. |
81 | |
988beb41 |
82 | =method get_package_symbol $variable |
683542f5 |
83 | |
84 | Returns the value of the given package variable (including sigil). |
85 | |
988beb41 |
86 | =method get_or_add_package_symbol $variable |
e55803fc |
87 | |
88 | Like C<get_package_symbol>, except that it will return an empty hashref or |
89 | arrayref if the variable doesn't exist. |
90 | |
988beb41 |
91 | =method remove_package_symbol $variable |
683542f5 |
92 | |
93 | Removes the package variable described by C<$variable> (which includes the |
94 | sigil); other variables with the same name but different sigils will be |
95 | untouched. |
96 | |
988beb41 |
97 | =method list_all_package_symbols $type_filter |
683542f5 |
98 | |
99 | Returns a list of package variable names in the package, without sigils. If a |
100 | C<type_filter> is passed, it is used to select package variables of a given |
101 | type, where valid types are the slots of a typeglob ('SCALAR', 'CODE', 'HASH', |
d1f721b3 |
102 | etc). Note that if the package contained any C<BEGIN> blocks, perl will leave |
103 | an empty typeglob in the C<BEGIN> slot, so this will show up if no filter is |
104 | used (and similarly for C<INIT>, C<END>, etc). |
683542f5 |
105 | |
0992f4ec |
106 | =head1 BUGS |
107 | |
108 | No known bugs. |
109 | |
110 | Please report any bugs through RT: email |
111 | C<bug-package-stash at rt.cpan.org>, or browse to |
112 | L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Package-Stash>. |
113 | |
f4979588 |
114 | =head1 SEE ALSO |
115 | |
f4979588 |
116 | =over 4 |
117 | |
988beb41 |
118 | =item * L<Class::MOP::Package> |
f4979588 |
119 | |
988beb41 |
120 | This module is a factoring out of code that used to live here |
f4979588 |
121 | |
122 | =back |
123 | |
0992f4ec |
124 | =head1 SUPPORT |
125 | |
126 | You can find this documentation for this module with the perldoc command. |
127 | |
128 | perldoc Package::Stash |
129 | |
130 | You can also look for information at: |
131 | |
132 | =over 4 |
133 | |
134 | =item * AnnoCPAN: Annotated CPAN documentation |
135 | |
136 | L<http://annocpan.org/dist/Package-Stash> |
137 | |
138 | =item * CPAN Ratings |
139 | |
140 | L<http://cpanratings.perl.org/d/Package-Stash> |
141 | |
142 | =item * RT: CPAN's request tracker |
143 | |
144 | L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Package-Stash> |
145 | |
146 | =item * Search CPAN |
147 | |
148 | L<http://search.cpan.org/dist/Package-Stash> |
149 | |
150 | =back |
151 | |
152 | =head1 AUTHOR |
153 | |
154 | Jesse Luehrs <doy at tozt dot net> |
155 | |
156 | Mostly copied from code from L<Class::MOP::Package>, by Stevan Little and the |
157 | Moose Cabal. |
158 | |
f4979588 |
159 | =cut |
160 | |
161 | 1; |