1Package::Stash(3)     User Contributed Perl Documentation    Package::Stash(3)
2
3
4

NAME

6       Package::Stash - routines for manipulating stashes
7

VERSION

9       version 0.38
10

SYNOPSIS

12         my $stash = Package::Stash->new('Foo');
13         $stash->add_symbol('%foo', {bar => 1});
14         # $Foo::foo{bar} == 1
15         $stash->has_symbol('$foo') # false
16         my $namespace = $stash->namespace;
17         *{ $namespace->{foo} }{HASH} # {bar => 1}
18

DESCRIPTION

20       Manipulating stashes (Perl's symbol tables) is occasionally necessary,
21       but incredibly messy, and easy to get wrong. This module hides all of
22       that behind a simple API.
23
24       NOTE: Most methods in this class require a variable specification that
25       includes a sigil. If this sigil is absent, it is assumed to represent
26       the IO slot.
27
28       Due to limitations in the typeglob API available to perl code, and to
29       typeglob manipulation in perl being quite slow, this module provides
30       two implementations - one in pure perl, and one using XS. The XS
31       implementation is to be preferred for most usages; the pure perl one is
32       provided for cases where XS modules are not a possibility. The current
33       implementation in use can be set by setting
34       $ENV{PACKAGE_STASH_IMPLEMENTATION} or $Package::Stash::IMPLEMENTATION
35       before loading Package::Stash (with the environment variable taking
36       precedence), otherwise, it will use the XS implementation if possible,
37       falling back to the pure perl one.
38

METHODS

40   new $package_name
41       Creates a new "Package::Stash" object, for the package given as the
42       only argument.
43
44   name
45       Returns the name of the package that this object represents.
46
47   namespace
48       Returns the raw stash itself.
49
50   add_symbol $variable $value %opts
51       Adds a new package symbol, for the symbol given as $variable, and
52       optionally gives it an initial value of $value. $variable should be the
53       name of variable including the sigil, so
54
55         Package::Stash->new('Foo')->add_symbol('%foo')
56
57       will create %Foo::foo.
58
59       Valid options (all optional) are "filename", "first_line_num", and
60       "last_line_num".
61
62       $opts{filename}, $opts{first_line_num}, and $opts{last_line_num} can be
63       used to indicate where the symbol should be regarded as having been
64       defined.  Currently these values are only used if the symbol is a
65       subroutine ('"&"' sigil) and only if "$^P & 0x10" is true, in which
66       case the special %DB::sub hash is updated to record the values of
67       "filename", "first_line_num", and "last_line_num" for the subroutine.
68       If these are not passed, their values are inferred (as much as
69       possible) from "caller" information.
70
71       This is especially useful for debuggers and profilers, which use
72       %DB::sub to determine where the source code for a subroutine can be
73       found.  See
74       <http://perldoc.perl.org/perldebguts.html#Debugger-Internals> for more
75       information about %DB::sub.
76
77   remove_glob $name
78       Removes all package variables with the given name, regardless of sigil.
79
80   has_symbol $variable
81       Returns whether or not the given package variable (including sigil)
82       exists.
83
84   get_symbol $variable
85       Returns the value of the given package variable (including sigil).
86
87   get_or_add_symbol $variable
88       Like "get_symbol", except that it will return an empty hashref or
89       arrayref if the variable doesn't exist.
90
91   remove_symbol $variable
92       Removes the package variable described by $variable (which includes the
93       sigil); other variables with the same name but different sigils will be
94       untouched.
95
96   list_all_symbols $type_filter
97       Returns a list of package variable names in the package, without
98       sigils. If a "type_filter" is passed, it is used to select package
99       variables of a given type, where valid types are the slots of a
100       typeglob ('SCALAR', 'CODE', 'HASH', etc). Note that if the package
101       contained any "BEGIN" blocks, perl will leave an empty typeglob in the
102       "BEGIN" slot, so this will show up if no filter is used (and similarly
103       for "INIT", "END", etc).
104
105   get_all_symbols $type_filter
106       Returns a hashref, keyed by the variable names in the package. If
107       $type_filter is passed, the hash will contain every variable of that
108       type in the package as values, otherwise, it will contain the typeglobs
109       corresponding to the variable names (basically, a clone of the stash).
110

WORKING WITH VARIABLES

112       It is important to note, that when working with scalar variables, the
113       default behavior is to copy values.
114
115         my $stash = Package::Stash->new('Some::Namespace');
116         my $variable = 1;
117         # $Some::Namespace::name is a copy of $variable
118         $stash->add_symbol('$name', $variable);
119         $variable++
120         # $Some::Namespace::name == 1 , $variable == 2
121
122       This will likely confuse people who expect it to work the same as
123       typeglob assignment, which simply creates new references to existing
124       variables.
125
126         my $variable = 1;
127         {
128             no strict 'refs';
129             # assign $Package::Stash::name = $variable
130             *{'Package::Stash::name'} = \$variable;
131         }
132         $variable++ # affects both names
133
134       If this behaviour is desired when working with Package::Stash, simply
135       pass Package::Stash a scalar ref:
136
137         my $stash = Package::Stash->new('Some::Namespace');
138         my $variable = 1;
139         # $Some::Namespace::name is now $variable
140         $stash->add_symbol('$name', \$variable);
141         $variable++
142         # $Some::Namespace::name == 2 , $variable == 2
143
144       This will be what you want as well if you're ever working with Readonly
145       variables:
146
147         use Readonly;
148         Readonly my $value, 'hello';
149
150         $stash->add_symbol('$name', \$value); # reference
151         print $Some::Namespace::name; # hello
152         # Tries to modify the read-only 'hello' and dies.
153         $Some::Namespace::name .= " world";
154
155         $stash->add_symbol('$name', $value); # copy
156         print $Some::Namespace::name; # hello
157         # No problem, modifying a copy, not the original
158         $Some::Namespace::name .= " world";
159

SEE ALSO

161       ·   Class::MOP::Package
162
163           This module is a factoring out of code that used to live here
164

SUPPORT

166       You can find this documentation for this module with the perldoc
167       command.
168
169           perldoc Package::Stash
170
171       You can also look for information at:
172
173       ·   MetaCPAN
174
175           <https://metacpan.org/release/Package-Stash>
176
177       ·   Github
178
179           <https://github.com/moose/Package-Stash>
180
181       ·   RT: CPAN's request tracker
182
183           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Package-Stash>
184
185       ·   CPAN Ratings
186
187           <http://cpanratings.perl.org/d/Package-Stash>
188

HISTORY

190       Based on code from Class::MOP::Package, by Stevan Little and the Moose
191       Cabal.
192

BUGS / CAVEATS

194       ·   Prior to perl 5.10, scalar slots are only considered to exist if
195           they are defined
196
197           This is due to a shortcoming within perl itself. See "Making
198           References" in perlref point 7 for more information.
199
200       ·   GLOB and FORMAT variables are not (yet) accessible through this
201           module.
202
203       ·   Also, see the BUGS section for the specific backends
204           (Package::Stash::XS and Package::Stash::PP)
205
206       Bugs may be submitted through the RT bug tracker
207       <https://rt.cpan.org/Public/Dist/Display.html?Name=Package-Stash> (or
208       bug-Package-Stash@rt.cpan.org <mailto:bug-Package-Stash@rt.cpan.org>).
209

AUTHOR

211       Jesse Luehrs <doy@tozt.net>
212

CONTRIBUTORS

214       ·   Karen Etheridge <ether@cpan.org>
215
216       ·   Carlos Lima <carlos@multi>
217
218       ·   Kent Fredric <kentfredric@gmail.com>
219
220       ·   Justin Hunter <justin.d.hunter@gmail.com>
221
222       ·   Christian Walde <walde.christian@googlemail.com>
223
224       ·   Dave Rolsky <autarch@urth.org>
225
226       ·   Niko Tyni <ntyni@debian.org>
227
228       ·   Renee <reb@perl-services.de>
229
230       ·   Tim Bunce <Tim.Bunce@pobox.com>
231
233       This software is copyright (c) 2018 by Jesse Luehrs.
234
235       This is free software; you can redistribute it and/or modify it under
236       the same terms as the Perl 5 programming language system itself.
237
238
239
240perl v5.28.1                      2018-12-31                 Package::Stash(3)
Impressum