Package::Stash::XS#

📦 std

The compiled implementation of Package::Stash: reading and changing a package’s symbol table - its scalars, arrays, hashes, subs and IO handles - by name.

A variable is named with its sigil ('$foo', '@ISA', '%h', '&f'; no sigil means the IO handle) or given as { name => 'foo', type => 'SCALAR' }. add_symbol installs a value, get_symbol returns a reference to it, get_or_add_symbol vivifies it first, has_symbol and remove_symbol test and remove one slot, remove_glob the whole glob, and list_all_symbols / get_all_symbols list them, optionally of one type. The object may also wrap an anonymous stash (a hash ref).

This is a native implementation of Package::Stash::XS 0.32’s XS.xs; its Package/Stash/XS.pm is used unchanged, and Package::Stash, which picks it as its implementation, comes from CPAN.

Synopsis#

use Package::Stash;                      # uses this one when it can

my $stash = Package::Stash->new('Foo');
$stash->add_symbol('%foo', { bar => 1 });
$stash->add_symbol('&hello', sub { "Hello" });
print ${ $stash->get_symbol('%foo') }{bar}, "\n";
print join(' ', sort $stash->list_all_symbols('CODE')), "\n";
$stash->remove_symbol('&hello');

Differences from upstream#

None.

Functions#

Symbol tables#

new#

A stash object for the package named $package, or for the anonymous stash \%stash.

name#

The package’s name.

Edge cases

  • Called on the class dies “Can’t call name as a class method”.

  • An anonymous stash has none: dies “Can’t get the name of an anonymous package”.

namespace#

A reference to the stash itself: \%Foo::Bar::, created when there is none yet. The object keeps it as a weak reference.

Edge cases

  • Called on the class dies “Can’t call namespace as a class method”.

add_symbol#

Install $initial in a slot: a reference installs its referent, a plain value a copy of it, nothing an empty value. Under the debugger ($^P & 0x10) a sub also gets its %DB::sub entry, from filename, first_line_num and last_line_num options.

remove_glob#

Delete the whole glob $name (no sigil) from the stash.

has_symbol#

Whether the slot holds something: 1 or 0, undef when the stash has no such entry at all.

Edge cases

  • An entry that is not yet a glob (a sub stub or constant) counts as a sub and as nothing else.

get_symbol#

A reference to the slot’s value, or undef when it has none.

get_or_add_symbol#

A reference to the slot’s value, created empty when there is none.

Edge cases

  • &name dies “Don’t know how to vivify CODE variables” whenever the entry exists.

remove_symbol#

Empty one slot of the glob; for an entry that is not yet a glob, & deletes it.

list_all_symbols#

The names in the stash, or with a type the names whose slot of that type holds something.

Synopsis

my @all  = $stash->list_all_symbols;
my @subs = $stash->list_all_symbols('CODE');

Edge cases

  • A type that is not a string dies “vartype must be a string”.

get_all_symbols#

A hash of the stash: name => glob, or with a type name => a reference to that slot’s value, for the names whose slot holds something. Entries that are not yet globs are made globs first.

Synopsis

my $subs = $stash->get_all_symbols('CODE');   # { name => \&code }