Module pir 

Perl Intermediate Representation (PIR) for static analysis and tooling. PIR v0: a source-anchored tooling intermediate representation.

PIR is lowered from HirFile. It models data access, calls, and control flow for editor tooling and static analysis without executing Perl. PIR v0 is a compiler-substrate data layer only: it does not replace HIR, does not promote provider behavior, does not claim determinism, and does not run real Perl.

See PLSP-SPEC-0025 for the authoritative contract.

Quick start

use perl_parser_core::Parser;
use perl_parser_core::hir::lower_ast;
use perl_parser_core::pir::lower_hir;

let mut parser = Parser::new("my $x = foo();");
let output = parser.parse_with_recovery();
let hir = lower_ast(&output.ast);
let pir = lower_hir(&hir);

// Every source-derived node preserves a source anchor.
assert!(pir.nodes.iter().all(|n| n.source_anchor.is_anchored()));
// Provider behavior never changes from lowering alone.
assert!(!pir.receipt.provider_behavior_changed);

Structs

BodyExtractionResult

Extraction results for a single body.

LexicalBindingFact

A single lexical variable binding fact extracted from PIR.

LexicalExtractorReceipt

Receipt from the lexical extractor, summarizing all bindings extracted from a file.

LexicalName

A lexical (my/state) variable named by a PIR operation.

PirAnchorCoverage

Source-anchor coverage summary for a lowering receipt.

PirEdge

One control-flow edge between PIR nodes.

PirGraph

A lowered PIR graph plus its receipt.

PirId

Stable identifier for a PIR node within one lowering receipt.

PirNode

One PIR node.

PirReceipt

A PIR lowering receipt.

PirSourceAnchor

Source anchor for a PIR node.

SymbolName

A package/stash symbol named by a PIR operation.

Enums

LexicalRole

Role of a lexical binding fact (read or write).

PirAnchorKind

Provenance class for a PIR node’s source anchor.

PirCallee

Callee of a PIR call operation.

PirContext

Expression context modeled by PIR v0.

PirDynamicBoundaryKind

Dynamic-boundary category preserved by PIR instead of guessing behavior.

PirEdgeKind

Control-flow edge category.

PirLoweringMode

Lowering pass that produced a PIR graph.

PirMethod

Method named by a PIR method-call operation.

PirOperation

A modeled PIR operation.

PirReceiver

Receiver of a PIR method-call operation.

Constants

LEXICAL_EXTRACTOR_RECEIPT_VERSION

Current schema version for lexical extractor receipts.

PIR_RECEIPT_VERSION

Current PIR lowering-receipt schema version.

Functions

extract_lexical_facts

Extract lexical binding facts from a HirFile.

lower_hir

Lower a HirFile into a PIR v0 graph with no caller-supplied identity.

lower_hir_bodies

Lower a HirFile’s canonical body arenas into a PIR-A graph.

lower_hir_bodies_with_identity

Lower a HirFile’s canonical body arenas into a PIR-A graph, tagging the receipt with an optional caller-supplied source or fixture identity.

lower_hir_with_identity

Lower a HirFile into a PIR v0 graph, tagging the receipt with an optional caller-supplied source or fixture identity.

lower_single_body

Lower a single HirBody to PIR nodes, preserving body identity.