Crate perl_parser_core 

Core parser engine for Perl source code.

perl-parser-core is the foundational crate that wires together the lexer, AST, error recovery, and position mapping into a single Parser entry point. Higher-level crates – semantic analysis, workspace indexing, and the LSP server – all build on top of this crate.

Key types

Type	Role
Parser	Recursive-descent parser; call Parser::parse to get an AST
Node / NodeKind	AST node and its discriminant (re-exported from perl-ast)
ParseError	Syntax error collected during parsing
ParseOutput	AST + diagnostics bundle for IDE workflows
Token / TokenKind	Lexer tokens consumed by the parser
SourceLocation	Byte-offset span for every node

Quick start

use perl_parser_core::{Parser, Node, NodeKind};

let mut parser = Parser::new("my $x = 42;");
let ast = parser.parse().expect("should parse");

// The root is always a Program node
assert!(matches!(ast.kind, NodeKind::Program { .. }));

// Non-fatal errors are collected, not returned as Err
assert!(parser.errors().is_empty());

For IDE workflows that need error-tolerant parsing, use Parser::parse_with_recovery:

use perl_parser_core::Parser;

let mut parser = Parser::new("if (");
let output = parser.parse_with_recovery();

// Always returns an AST (possibly with ERROR nodes)
assert!(!output.diagnostics.is_empty());

Re-exports

pub use engine::ast;

pub use engine::parser_context;

pub use engine::error;

pub use engine::parser;

pub use engine::position;

pub use engine::parser::Parser;

pub use tokens::token_stream;

pub use perl_builtins as builtins;

pub use engine::ast_v2;

pub use engine::pragma_tracker;

pub use engine::quote_parser;

pub use perl_edit as edit;

pub use perl_heredoc as heredoc_collector;

pub use builtins::builtin_signatures_phf;

Modules

builtin_signatures

Builtin function signature lookup tables. Comprehensive built-in function signatures for Perl scripting.

engine

Parser engine components and supporting utilities. Parser engine components and supporting utilities.

error_classifier

Error classification and recovery strategies for parse failures. Error types and result aliases used by the parser engine. Error classification and diagnostic generation for parsed Perl code. Error classification and diagnostic generation for Perl parsing workflows

error_recovery

Error recovery helpers and strategies. Error types and result aliases used by the parser engine. Error recovery strategies and traits for the Perl parser. Error recovery for the Perl parser

line_index

Line indexing and position mapping utilities.

token_wrapper

Lightweight token wrapper for AST integration. Token wrapper utilities for preserving original lexemes and trivia. Token wrapper with enhanced position tracking

tokens

Token stream and trivia utilities for the parser. Token stream and trivia utilities for parser workflows.

trivia

Trivia (whitespace and comments) representation. Trivia tokens (whitespace/comments) used for formatting and diagnostics. Trivia (comments and whitespace) handling for the Perl parser

trivia_parser

Trivia-preserving parser and formatting utilities. Trivia parser helpers for preserving formatting context. Trivia-preserving parser implementation

util

Parser utilities and helpers. Utility functions for the Perl parser

Structs

BudgetTracker

Parse error, budget, and output types. Error types and result aliases used by the parser engine. Tracks budget consumption during parsing.

Node

Core AST types re-exported for convenience. Re-exported AST node types used during Parse/Index/Analyze stages. Core AST node representing any Perl language construct within parsing workflows.

NodeWithTrivia

Trivia types attached to AST nodes for formatting preservation. A node with attached trivia

ParseBudget

Parse error, budget, and output types. Error types and result aliases used by the parser engine. Budget limits for parser operations to prevent runaway parsing.

ParseOutput

Parse error, budget, and output types. Error types and result aliases used by the parser engine. Structured output from parsing, combining AST with all diagnostics.

PositionMapper

Line ending detection for mixed-EOL source files. Centralized position mapper using rope for efficiency.

Token

Individual token, its classification, and the streaming iterator. Token stream types used during the Parse stage of the workflow. Token produced by the lexer and consumed by the parser.

TokenStream

Individual token, its classification, and the streaming iterator. Token stream types used during the Parse stage of the workflow. Token stream that wraps perl-lexer

TriviaPreservingParser

Trivia-preserving parser and source formatting helper. Parser that preserves trivia

TriviaToken

Trivia types attached to AST nodes for formatting preservation. A trivia token with position information

Enums

LineEnding

Line ending detection for mixed-EOL source files. Line ending style detected in a document

MissingKind

Index into the diagnostics array in ParseOutput (from ast_v2). Kinds of missing syntax elements for error recovery.

NodeKind

Core AST types re-exported for convenience. Re-exported AST node types used during Parse/Index/Analyze stages. Comprehensive enumeration of all Perl language constructs supported by the parser.

ParseError

Parse error, budget, and output types. Error types and result aliases used by the parser engine. Comprehensive error types that can occur during Perl parsing workflows

RecoveryResult

Result of an error recovery attempt. Result of a recovery operation.

TokenKind

Individual token, its classification, and the streaming iterator. Token stream types used during the Parse stage of the workflow. Token classification for Perl parsing.

Trivia

Trivia types attached to AST nodes for formatting preservation. Trivia represents non-semantic tokens like comments and whitespace

Functions

format_with_trivia

Trivia-preserving parser and source formatting helper. Format an AST with trivia back to source code

Type Aliases

DiagnosticId

Index into the diagnostics array in ParseOutput (from ast_v2). Index into the diagnostics array in ParseOutput.

ParseResult

Parse error, budget, and output types. Error types and result aliases used by the parser engine. Result type for parser operations in the Perl parsing workflow pipeline

SourceLocation

Core AST types re-exported for convenience. Re-exported AST node types used during Parse/Index/Analyze stages. Type alias for backward compatibility with SourceLocation.