Package::Stash(3pm)

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.08
10

SYNOPSIS

12         my $stash = Package::Stash->new('Foo');
13         $stash->add_package_symbol('%foo', {bar => 1});
14         # $Foo::foo{bar} == 1
15         $stash->has_package_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

METHODS

29   new $package_name
30       Creates a new "Package::Stash" object, for the package given as the
31       only argument.
32
33   name
34       Returns the name of the package that this object represents.
35
36   namespace
37       Returns the raw stash itself.
38
39   add_package_symbol $variable $value %opts
40       Adds a new package symbol, for the symbol given as $variable, and
41       optionally gives it an initial value of $value. $variable should be the
42       name of variable including the sigil, so
43
44         Package::Stash->new('Foo')->add_package_symbol('%foo')
45
46       will create %Foo::foo.
47
48       Valid options (all optional) are "filename", "first_line_num", and
49       "last_line_num".
50
51       $opts{filename}, $opts{first_line_num}, and $opts{last_line_num} can be
52       used to indicate where the symbol should be regarded as having been
53       defined.  Currently these values are only used if the symbol is a
54       subroutine ('"&"' sigil) and only if "$^P & 0x10" is true, in which
55       case the special %DB::sub hash is updated to record the values of
56       "filename", "first_line_num", and "last_line_num" for the subroutine.
57       If these are not passed, their values are inferred (as much as
58       possible) from "caller" information.
59
60       This is especially useful for debuggers and profilers, which use
61       %DB::sub to determine where the source code for a subroutine can be
62       found.  See http://perldoc.perl.org/perldebguts.html#Debugger-Internals
63       <http://perldoc.perl.org/perldebguts.html#Debugger-Internals> for more
64       information about %DB::sub.
65
66   remove_package_glob $name
67       Removes all package variables with the given name, regardless of sigil.
68
69   has_package_symbol $variable
70       Returns whether or not the given package variable (including sigil)
71       exists.
72
73   get_package_symbol $variable
74       Returns the value of the given package variable (including sigil).
75
76   get_or_add_package_symbol $variable
77       Like "get_package_symbol", except that it will return an empty hashref
78       or arrayref if the variable doesn't exist.
79
80   remove_package_symbol $variable
81       Removes the package variable described by $variable (which includes the
82       sigil); other variables with the same name but different sigils will be
83       untouched.
84
85   list_all_package_symbols $type_filter
86       Returns a list of package variable names in the package, without
87       sigils. If a "type_filter" is passed, it is used to select package
88       variables of a given type, where valid types are the slots of a
89       typeglob ('SCALAR', 'CODE', 'HASH', etc).
90

BUGS

92       No known bugs.
93
94       Please report any bugs through RT: email "bug-package-stash at
95       rt.cpan.org", or browse to
96       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Package-Stash
97       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Package-Stash>.
98

SUPPORT

100       You can find this documentation for this module with the perldoc
101       command.
102
103           perldoc Package::Stash
104
105       You can also look for information at:
106
107       ·   AnnoCPAN: Annotated CPAN documentation
108
109           http://annocpan.org/dist/Package-Stash
110           <http://annocpan.org/dist/Package-Stash>
111
112       ·   CPAN Ratings
113
114           http://cpanratings.perl.org/d/Package-Stash
115           <http://cpanratings.perl.org/d/Package-Stash>
116
117       ·   RT: CPAN's request tracker
118
119           http://rt.cpan.org/NoAuth/Bugs.html?Dist=Package-Stash
120           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Package-Stash>
121
122       ·   Search CPAN
123
124           http://search.cpan.org/dist/Package-Stash
125           <http://search.cpan.org/dist/Package-Stash>
126

AUTHOR

128       Jesse Luehrs <doy at tozt dot net>
129
130       Mostly copied from code from Class::MOP::Package, by Stevan Little and
131       the Moose Cabal.
132

COPYRIGHT AND LICENSE

139       This software is copyright (c) 2010 by Jesse Luehrs.
140
141       This is free software; you can redistribute it and/or modify it under
142       the same terms as the Perl 5 programming language system itself.
143
144
145
146perl v5.12.1                      2010-09-19                 Package::Stash(3)