Struct Parser 

pub struct Parser<'a> {
    line_no: i64,
    state: State,
    extension_parser: ExtensionParser,
    extension_registry: ExtensionRegistry,
    relation_parser: RelationParser<'a>,
}

A parser for Substrait query plans in text format.

The Parser converts human-readable Substrait text format into Substrait protobuf plans. It handles both the extensions section (which defines functions, types, etc.) and the plan section (which defines the actual query structure).

Usage

The simplest entry point is the static parse() method:

use substrait_explain::parser::Parser;

let plan_text = r#"
=== Plan
Root[c, d]
  Project[$1, 42]
    Read[schema.table => a:i64, b:string?]
"#;

let plan = Parser::parse(plan_text).unwrap();

Input Format

The parser expects input in the following format:

=== Extensions
URNs:
  @  1: https://github.com/substrait-io/substrait/blob/main/extensions/functions_arithmetic.yaml
Functions:
  # 10 @  1: add
=== Plan
Root[columns]
  Relation[arguments => columns]
    ChildRelation[arguments => columns]

• Extensions section (optional): Defines URNs and function/type declarations
• Plan section (required): Defines the query structure with indented relations

Error Handling

The parser provides detailed error information including:

• Line number where the error occurred
• The actual line content that failed to parse
• Specific error type and description

use substrait_explain::parser::Parser;

let invalid_plan = r#"
=== Plan
InvalidRelation[invalid syntax]
"#;

match Parser::parse(invalid_plan) {
    Ok(plan) => println!("Successfully parsed"),
    Err(e) => eprintln!("Parse error: {}", e),
}

Supported Relations

The parser supports all standard Substrait relations:

• Read[table => columns] - Read from a table
• Project[expressions] - Project columns/expressions
• Filter[condition => columns] - Filter rows
• Root[columns] - Root relation with output columns
• And more…

Extensions Support

The parser fully supports Substrait Simple Extensions, allowing you to:

• Define custom functions with URNs and anchors
• Reference functions by name in expressions
• Use custom types and type variations

use substrait_explain::parser::Parser;

let plan_with_extensions = r#"
=== Extensions
URNs:
  @  1: https://example.com/functions.yaml
Functions:
  # 10 @  1: my_custom_function
=== Plan
Root[result]
  Project[my_custom_function($0, $1)]
    Read[table => col1:i32, col2:i32]
"#;

let plan = Parser::parse(plan_with_extensions).unwrap();

Performance

The parser is designed for efficiency:

• Single-pass parsing with minimal allocations
• Early error detection and reporting
• Memory-efficient tree building

Thread Safety

Parser instances are not thread-safe and should not be shared between threads. However, the static parse() method is safe to call from multiple threads.

Fields

line_no: i64

state: State

extension_parser: ExtensionParser

extension_registry: ExtensionRegistry

relation_parser: RelationParser<'a>

Implementations

impl<'a> Parser<'a>

pub fn parse(input: &str) -> ParseResult

Parse a Substrait plan from text format.

This is the main entry point for parsing.

The input should be in the Substrait text format, which consists of:

• An optional extensions section starting with “=== Extensions”
• A plan section starting with “=== Plan”
• Indented relation definitions

Examples

Simple parsing:

use substrait_explain::parser::Parser;

let plan_text = r#"
=== Plan
Root[result]
  Read[table => col:i32]
"#;

let plan = Parser::parse(plan_text).unwrap();
assert_eq!(plan.relations.len(), 1);

Errors

Returns a ParseError if the input cannot be parsed.

pub fn new() -> Self

Create a new parser with default configuration.

pub fn with_extension_registry(self, registry: ExtensionRegistry) -> Self

Configure the parser to use the specified extension registry.

pub fn parse_plan(self, input: &'a str) -> ParseResult

Parse a Substrait plan with the current parser configuration.

fn parse_line(&mut self, line: &'a str) -> Result<(), ParseError>

Parse a single line of input.

fn parse_initial(&mut self, line: IndentedLine<'_>) -> Result<(), ParseError>

Parse the initial line(s) of the input, which is either a blank line or the extensions or plan header.

fn parse_extensions( &mut self, line: IndentedLine<'_>, ) -> Result<(), ExtensionParseError>

Parse a single line from the extensions section of the input, updating the parser state.

fn build_plan(self) -> Result<Plan, ParseError>

Build the plan from the parser state with warning collection.

Trait Implementations

impl<'a> Debug for Parser<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for Parser<'a>

fn default() -> Self

Returns the “default value” for a type.