---
name: PadWalker
runtime: pp
source: src/native/PadWalker/pp.rs
---
```{index} single: PadWalker; Perl module (pp runtime)
```

# PadWalker

Native implementation of PadWalker

PadWalker provides introspective access to lexical variables in Perl subroutine
pads (scratchpads). It is widely used by debugging tools, test frameworks,
and REPL implementations.

# Implemented Functions

- `peek_my(N)`          — hashref of `my` vars at call depth N
- `peek_our(N)`         — hashref of `our` (package) vars visible at call depth N
- `peek_sub(\\&sub)`     — hashref of all pad vars in a CV
- `closed_over(\\&sub)`  — hashref of only the captured (closed-over) vars
- `set_closed_over(\\&sub, \\%h)` — replace closed-over vars from a hashref
- `var_name(N, \\$ref)`  — find the name of a variable by reference identity

# Semantics

`peek_my(0)` returns variables in the *calling* scope (the Perl sub that
called peek_my). `interp.hot.pad` is the current frame (level 0), and
`call_stack[len - N].saved_pad` gives level N's pad.

Values in the returned hashref are **live references** so that mutations
like `${$h->{'$x'}} = 42` update the actual variable in the target scope.

For array slots (`@arr`), the value is an ARRAY ref pointing to the actual Av.
For hash slots (`%hash`), the value is a HASH ref pointing to the actual Hv.
For scalar slots (`$x`), the value is a SCALAR ref via the live cell.

# Reference

See perl5-modules/PadWalker-2.5/PadWalker.xs for the original XS algorithm.