perl_parser_core/
lib.rs

1//! Core parser engine for Perl source code.
2//!
3//! `perl-parser-core` is the foundational crate that wires together the lexer,
4//! AST, error recovery, and position mapping into a single [`Parser`] entry
5//! point. Higher-level crates -- semantic analysis, workspace indexing, and the
6//! LSP server -- all build on top of this crate.
7//!
8//! # Key types
9//!
10//! | Type | Role |
11//! |------|------|
12//! | [`Parser`] | Recursive-descent parser; call [`Parser::parse`] to get an AST |
13//! | [`Node`] / [`NodeKind`] | AST node and its discriminant (re-exported from `perl-ast`) |
14//! | [`ParseError`] | Syntax error collected during parsing |
15//! | [`ParseOutput`] | AST + diagnostics bundle for IDE workflows |
16//! | [`Token`] / [`TokenKind`] | Lexer tokens consumed by the parser |
17//! | [`SourceLocation`] | Byte-offset span for every node |
18//!
19//! # Quick start
20//!
21//! ```rust
22//! use perl_parser_core::{Parser, Node, NodeKind};
23//!
24//! let mut parser = Parser::new("my $x = 42;");
25//! let ast = parser.parse().expect("should parse");
26//!
27//! // The root is always a Program node
28//! assert!(matches!(ast.kind, NodeKind::Program { .. }));
29//!
30//! // Non-fatal errors are collected, not returned as Err
31//! assert!(parser.errors().is_empty());
32//! ```
33//!
34//! For IDE workflows that need error-tolerant parsing, use
35//! [`Parser::parse_with_recovery`]:
36//!
37//! ```rust
38//! use perl_parser_core::Parser;
39//!
40//! let mut parser = Parser::new("if (");
41//! let output = parser.parse_with_recovery();
42//!
43//! // Always returns an AST (possibly with ERROR nodes)
44//! assert!(!output.diagnostics.is_empty());
45//! ```
46
47#![deny(unsafe_code)]
48#![deny(unreachable_pub)]
49#![warn(rust_2018_idioms)]
50#![warn(missing_docs)]
51#![cfg_attr(test, allow(clippy::panic, clippy::unwrap_used, clippy::expect_used))]
52#![warn(clippy::all)]
53#![allow(
54    clippy::too_many_lines,
55    clippy::module_name_repetitions,
56    clippy::cast_possible_truncation,
57    clippy::cast_sign_loss,
58    clippy::cast_precision_loss,
59    clippy::cast_possible_wrap,
60    clippy::must_use_candidate,
61    clippy::missing_errors_doc,
62    clippy::missing_panics_doc,
63    clippy::wildcard_imports,
64    clippy::enum_glob_use,
65    clippy::match_same_arms,
66    clippy::if_not_else,
67    clippy::struct_excessive_bools,
68    clippy::items_after_statements,
69    clippy::return_self_not_must_use,
70    clippy::unused_self,
71    clippy::collapsible_match,
72    clippy::collapsible_if,
73    clippy::only_used_in_recursion,
74    clippy::items_after_test_module,
75    clippy::while_let_loop,
76    clippy::single_range_in_vec_init,
77    clippy::arc_with_non_send_sync,
78    clippy::needless_range_loop,
79    clippy::result_large_err,
80    clippy::if_same_then_else,
81    clippy::should_implement_trait,
82    clippy::manual_flatten,
83    clippy::needless_raw_string_hashes,
84    clippy::single_char_pattern,
85    clippy::uninlined_format_args
86)]
87
88/// Builtin function signatures and metadata.
89pub use perl_lexer::builtins;
90/// Parser engine components and supporting utilities.
91pub mod engine;
92/// Syntax-level types absorbed from Wave D satellite crates.
93pub mod syntax;
94/// Token stream and trivia utilities for the parser.
95pub mod tokens;
96
97/// Index into the diagnostics array in [`ParseOutput`] (from `ast_v2`).
98pub use ast_v2::{DiagnosticId, MissingKind};
99/// Abstract Syntax Tree (AST) definitions for Perl parsing.
100pub use engine::ast;
101/// Experimental second-generation AST (work in progress).
102pub use engine::ast_v2;
103/// Parser context with error recovery support.
104pub use engine::parser_context;
105/// Pragma tracking for `use` and related directives.
106pub use engine::pragma_tracker;
107/// Parser for Perl quote and quote-like operators.
108pub use engine::quote_parser;
109/// Legacy module aliases for moved engine components.
110pub use engine::{error, parser, position};
111/// Parser utilities and helpers.
112pub use perl_lexer::tokenizer::util;
113/// Edit tracking for incremental parsing (internal module, previously `perl-edit`).
114pub use syntax::edit;
115/// Heredoc content collector with FIFO ordering and indent stripping (internal module, previously `perl-heredoc`).
116pub use syntax::heredoc as heredoc_collector;
117/// Secure workspace-relative path normalization (previously `perl-path-normalize`).
118pub use syntax::path_normalize;
119/// Workspace-bound path validation and traversal prevention (previously `perl-path-security`).
120pub use syntax::path_security;
121/// Percentile helpers for integer metric samples (previously `perl-percentile`).
122pub use syntax::percentile;
123/// Perl qualified-name parsing, splitting, and validation helpers (previously `perl-qualified-name`).
124pub use syntax::qualified_name;
125/// Perl source-file classification helpers (previously `perl-source-file`).
126pub use syntax::source_file;
127/// Text-line cursor and boundary helpers (previously `perl-text-line`).
128pub use syntax::text_line;
129
130/// Recursive-descent parser -- the main entry point for parsing Perl source.
131pub use engine::parser::Parser;
132
133/// Error classification and recovery strategies for parse failures.
134pub use error::classifier as error_classifier;
135/// Error recovery helpers and strategies.
136pub use error::recovery as error_recovery;
137/// Result of an error recovery attempt.
138pub use error_recovery::RecoveryResult;
139
140/// Line indexing and position mapping utilities.
141pub mod line_index {
142    /// Fast lookup from byte offset to line number.
143    pub use perl_position_tracking::LineIndex;
144}
145/// Line ending detection for mixed-EOL source files.
146pub use position::{LineEnding, PositionMapper};
147
148/// Core AST types re-exported for convenience.
149pub use ast::{Node, NodeKind, SourceLocation};
150/// Recovery-salvage metrics and classifier for accuracy closeout reporting.
151pub use error::classifier::{RecoverySalvageMetrics, classify_recovery_salvage};
152/// Parse error, budget, and output types.
153pub use error::{
154    BudgetTracker, ParseBudget, ParseError, ParseOutput, ParseResult, RecoverySalvageClass,
155    RecoverySalvageProfile,
156};
157
158/// Builtin function signature lookup tables.
159pub use builtins::builtin_signatures;
160/// Perfect hash function (PHF) based builtin signature lookup.
161pub use builtins::builtin_signatures_phf;
162
163/// Token stream module for lexer-to-parser bridge.
164pub use tokens::token_stream;
165/// Lightweight token wrapper for AST integration.
166pub use tokens::token_wrapper;
167/// Trivia (whitespace and comments) representation.
168pub use tokens::trivia;
169/// Trivia-preserving parser and formatting utilities.
170pub use tokens::trivia_parser;
171
172/// Individual token, its classification, and the streaming iterator.
173pub use token_stream::{Token, TokenKind, TokenStream};
174/// Trivia types attached to AST nodes for formatting preservation.
175pub use trivia::{NodeWithTrivia, Trivia, TriviaToken};
176/// Trivia-preserving parser and source formatting helper.
177pub use trivia_parser::{TriviaPreservingParser, format_with_trivia};
perl_parser_core/lib.rs

perl_parser_core/
lib.rs
