1Package::Stash(3) User Contributed Perl Documentation Package::Stash(3)
2
6 Package::Stash - Routines for manipulating stashes
7
9 version 0.40
10
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
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 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 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
40 new $package_name
41 Creates a new "Package::Stash" object, for the package given as the
42 only argument.
43 name
45 Returns the name of the package that this object represents.
46 namespace
48 Returns the raw stash itself.
49 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 Package::Stash->new('Foo')->add_symbol('%foo')
56 will create %Foo::foo.
58 Valid options (all optional) are "filename", "first_line_num", and
60 "last_line_num".
61 $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 remove_glob $name
72 Removes all package variables with the given name, regardless of sigil.
73 has_symbol $variable
75 Returns whether or not the given package variable (including sigil)
76 exists.
77 get_symbol $variable
79 Returns the value of the given package variable (including sigil).
80 get_or_add_symbol $variable
82 Like "get_symbol", except that it will return an empty hashref or
83 arrayref if the variable doesn't exist.
84 remove_symbol $variable
86 Removes the package variable described by $variable (which includes the
87 sigil); other variables with the same name but different sigils will be
88 untouched.
89 list_all_symbols $type_filter
91 Returns a list of package variable names in the package, without
92 sigils. If a "type_filter" is passed, it is used to select package
93 variables of a given type, where valid types are the slots of a
94 typeglob ('SCALAR', 'CODE', 'HASH', etc). Note that if the package
95 contained any "BEGIN" blocks, perl will leave an empty typeglob in the
96 "BEGIN" slot, so this will show up if no filter is used (and similarly
97 for "INIT", "END", etc).
98 get_all_symbols $type_filter
100 Returns a hashref, keyed by the variable names in the package. If
101 $type_filter is passed, the hash will contain every variable of that
102 type in the package as values, otherwise, it will contain the typeglobs
103 corresponding to the variable names (basically, a clone of the stash).
104 This is especially useful for debuggers and profilers, which use
106 %DB::sub to determine where the source code for a subroutine can be
107 found. See
108 <http://perldoc.perl.org/perldebguts.html#Debugger-Internals> for more
109 information about %DB::sub.
110
112 It is important to note, that when working with scalar variables, the
113 default behavior is to copy values.
114 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 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 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 If this behaviour is desired when working with Package::Stash, simply
135 pass Package::Stash a scalar ref:
136 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 This will be what you want as well if you're ever working with Readonly
145 variables:
146 use Readonly;
148 Readonly my $value, 'hello';
149 $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 $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
161 • Prior to perl 5.10, scalar slots are only considered to exist if
162 they are defined
163 This is due to a shortcoming within perl itself. See "Making
165 References" in perlref point 7 for more information.
166 • GLOB and FORMAT variables are not (yet) accessible through this
168 module.
169 • Also, see the BUGS section for the specific backends
171 (Package::Stash::XS and Package::Stash::PP)
172
174 • Class::MOP::Package
175 This module is a factoring out of code that used to live here
177
179 Based on code from Class::MOP::Package, by Stevan Little and the Moose
180 Cabal.
181
183 Bugs may be submitted through the RT bug tracker
184 <https://rt.cpan.org/Public/Dist/Display.html?Name=Package-Stash> (or
185 bug-Package-Stash@rt.cpan.org <mailto:bug-Package-Stash@rt.cpan.org>).
186
188 • Stevan Little <stevan.little@iinteractive.com>
189 • Jesse Luehrs <doy@tozt.net>
191
193 • Karen Etheridge <ether@cpan.org>
194 • Carlos Lima <carlos@multi>
196 • Christian Walde <walde.christian@googlemail.com>
198 • Dave Rolsky <autarch@urth.org>
200 • Justin Hunter <justin.d.hunter@gmail.com>
202 • Kent Fredric <kentfredric@gmail.com>
204 • Niko Tyni <ntyni@debian.org>
206 • Renee <reb@perl-services.de>
208 • Tim Bunce <Tim.Bunce@pobox.com>
210
212 This software is copyright (c) 2022 by Jesse Luehrs.
213 This is free software; you can redistribute it and/or modify it under
215 the same terms as the Perl 5 programming language system itself.
216perl v5.38.0 2023-07-21 Package::Stash(3)