<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from Package/Stash/XS.rs. Do not edit. -->

```{index} single: Package::Stash::XS
```

# Package::Stash::XS

```{pperl-module-badges} Package::Stash::XS
```

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

```perl
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`](XS/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`](XS/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**

```perl
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**

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

```{toctree}
:hidden:
:maxdepth: 1

XS/new
XS/add_symbol
```