Struct Parser

Source

pub struct Parser<'a> { /* private fields */ }

Expand description

Recursive descent Perl parser with error recovery and AST generation. Parser state for a single Perl source input.

Construct with Parser::new and call Parser::parse to obtain an AST. Non-fatal syntax errors are collected and can be accessed via Parser::errors.

Implementations§

Source §

impl<'a> Parser<'a>

Source

pub fn new(input: &'a str) -> Parser<'a>

Create a new parser for the provided Perl source.

§Arguments

input - Perl source code to be parsed

§Returns

A configured parser ready to parse the provided source.

§Examples

use perl_parser_core::Parser;

let script = "use strict; my $filter = qr/important/;";
let mut parser = Parser::new(script);
// Parser ready to parse the source

Source

pub fn new_with_cancellation( input: &'a str, cancellation_flag: Arc<Atomic<bool>>, ) -> Parser<'a>

Create a new parser with a cancellation flag for cooperative cancellation.

When the flag is set to true, the parser will return Err(ParseError::Cancelled) at the next cancellation check point (every 64 statements).

Source

pub fn from_tokens(tokens: Vec<Token>, source: &'a str) -> Parser<'a>

Create a parser from pre-lexed tokens, skipping the lexer pass.

This constructor is the integration point for the incremental parsing pipeline: when cached tokens are available for an unchanged region of source, they can be fed directly into the parser without re-lexing.

§Arguments

tokens — Pre-lexed Token values produced by a prior TokenStream pass. Trivia tokens (whitespace, comments) should already be filtered out, as TokenStream::from_vec does not apply trivia skipping. An Eof token does not need to be included; the stream synthesises one when the buffer is exhausted.
source — The original Perl source text. This is still required for heredoc content collection which operates directly on byte offsets in the source rather than on the token stream.

§Returns

A configured parser that will consume tokens in order without invoking the lexer. The resulting AST is structurally identical to one produced by Parser::new with the same source, provided the token list is complete and accurate.

§Context-sensitive token disambiguation

The standard parser uses relex_as_term to re-lex ambiguous tokens (e.g. / as division vs. regex) in context-sensitive positions. When using pre-lexed tokens the kind is fixed from the original lex pass, so the original parse context must have been correct. In practice this means from_tokens is safe to use when the token stream comes from a previous successful parse of the same source.

§Examples

use perl_parser_core::{Parser, Token, TokenKind, TokenStream};

let source = "my $x = 42;";

// Collect pre-lexed tokens (normally cached from a prior parse)
let mut stream = TokenStream::new(source);
let mut tokens = Vec::new();
loop {
    match stream.next() {
        Ok(t) if t.kind == TokenKind::Eof => break,
        Ok(t) => tokens.push(t),
        Err(_) => break,
    }
}

let mut parser = Parser::from_tokens(tokens, source);
let ast = parser.parse()?;
assert!(matches!(ast.kind, perl_parser_core::NodeKind::Program { .. }));

Source

pub fn new_with_recovery_config(input: &'a str, _config: ()) -> Parser<'a>

Create a new parser with custom enhanced recovery configuration.

This constructor exists for API compatibility while enhanced recovery configuration is being phased in.

§Arguments

input - Perl source text to tokenize and parse.
_config - Placeholder recovery configuration parameter.

§Returns

A parser instance initialized for the provided source text.

§Examples

use perl_parser_core::Parser;

let parser = Parser::new_with_recovery_config("my $x = 1;", ());
assert_eq!(parser.errors().len(), 0);

Source

pub fn parse(&mut self) -> Result<Node, ParseError>

Parse the source and return the AST for the Parse stage.

§Returns

Ok(Node) - Parsed AST with a Program root node.
Err(ParseError) - Non-recoverable parsing failure.

§Errors

Returns ParseError for non-recoverable conditions such as recursion limits.

§Examples

use perl_parser_core::Parser;

let mut parser = Parser::new("my $count = 1;");
let ast = parser.parse()?;
assert!(matches!(ast.kind, perl_parser_core::NodeKind::Program { .. }));

Source

pub fn errors(&self) -> &[ParseError]

Get all parse errors collected during parsing

When error recovery is enabled, the parser continues after syntax errors and collects them for later retrieval. This is useful for IDE integration where you want to show all errors at once.

§Returns

A slice of all ParseErrors encountered during parsing

§Examples

use perl_parser_core::Parser;

let mut parser = Parser::new("my $x = ; sub foo {");
let _ast = parser.parse(); // Parse with recovery
let errors = parser.errors();
// errors will contain details about syntax errors

Source

pub fn parse_with_recovery(&mut self) -> ParseOutput

Parse with error recovery and return comprehensive output.

This method is preferred for LSP Analyze workflows and always returns a ParseOutput containing the AST and any collected diagnostics.

§Returns

ParseOutput with the AST and diagnostics collected during parsing.

§Examples

use perl_parser_core::Parser;

let mut parser = Parser::new("my $x = ;");
let output = parser.parse_with_recovery();
assert!(!output.diagnostics.is_empty() || matches!(output.ast.kind, perl_parser_core::NodeKind::Program { .. }));

Source §