PadWalker

Native Rust implementation built into the interpreter. Runtime: PP. See original documentation for the full Perl reference.

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.