Encapsulate parser and parse state. (#135)

Author: jpschorr

partiql-conformance-test-generator/src/generator.rs

@@ -45,7 +45,7 @@ fn test_case_to_function(test_case: &TestCase) -> Function {
     match &test_case.test_kind {
         Parse(ParseTestCase { parse_assertions }) => {
             test_fn.line(format!("let query = r#\"{}\"#;", &test_case.statement));
-            test_fn.line("let res = partiql_parser::parse_partiql(query);");
+            test_fn.line("let res = partiql_parser::Parser::default().parse(query);");
             match parse_assertions {
                 ParseAssertions::ParsePass => test_fn
                     .line(r#"assert!(res.is_ok(), "For `{}`, expected `Ok(_)`, but was `{:#?}`", query, res);"#),

partiql-parser/src/result.rs renamed to partiql-parser/src/error.rs

@@ -5,18 +5,14 @@
 use std::borrow::Cow;
 use std::fmt::{Debug, Display};
 
-use partiql_ast::ast;
 use partiql_source_map::location::{LineAndColumn, Located};
 use thiserror::Error;
 
 /// [`Error`] type for errors in the lexical structure for the PartiQL parser.
-pub type LexicalError<'input> = crate::result::LexError<'input>;
+pub type LexicalError<'input> = crate::error::LexError<'input>;
 
 /// [`Error`] type for errors in the syntactic structure for the PartiQL parser.
-pub type ParserError<'input> = crate::result::ParseError<'input, LineAndColumn>;
-
-/// General [`Result`] type for the PartiQL parser.
-pub type ParserResult<'input> = Result<Box<ast::Expr>, Vec<ParserError<'input>>>;
+pub type ParserError<'input> = crate::error::ParseError<'input, LineAndColumn>;
 
 /// Errors in the lexical structure of a PartiQL query.
 ///

partiql-parser/src/lexer.rs

@@ -8,7 +8,7 @@ use std::cmp::max;
 use std::fmt;
 use std::fmt::Formatter;
 
-use crate::result::{LexError, ParseError};
+use crate::error::{LexError, ParseError};
 use partiql_source_map::line_offset_tracker::LineOffsetTracker;
 
 /// A 3-tuple of (start, `Tok`, end) denoting a token and it start and end offsets.

partiql-parser/src/lib.rs

@@ -5,30 +5,64 @@
 //! # Usage
 //!
 //! ```
-//! use partiql_parser::{parse_partiql, ParserError, ParserResult};
+//! use partiql_parser::{Parser, ParserError, ParserResult};
 //!
-//! let ast = parse_partiql("SELECT g FROM data GROUP BY a").expect("successful parse");
+//! let parser = Parser::default();
 //!
-//! let errs: Vec<ParserError> = parse_partiql("SELECT").expect_err("expected error");
-//! assert_eq!(errs[0].to_string(), "Unexpected end of input");
+//! let parsed = parser.parse("SELECT g FROM data GROUP BY a").expect("successful parse");
+//!
+//! let errs: Vec<ParserError> = parser.parse("SELECT").expect_err("expected error");
 //!
 //! let errs_at: Vec<ParserError> =
-//!     parse_partiql("SELECT * FROM a AY a CROSS JOIN c AS c AT q").unwrap_err();
+//!     parser.parse("SELECT * FROM a AY a CROSS JOIN c AS c AT q").unwrap_err();
 //! assert_eq!(errs_at[0].to_string(), "Unexpected token `<a:UNQUOTED_IDENT>` at `(1:20..1:21)`");
 //! ```
 //!
 //! [partiql]: https://partiql.org
 
+mod error;
 mod lexer;
 mod parse;
 mod preprocessor;
-mod result;
 mod token_parser;
 
-pub use result::LexError;
-pub use result::LexicalError;
-pub use result::ParseError;
-pub use result::ParserError;
-pub use result::ParserResult;
+use parse::parse_partiql;
+use partiql_ast::ast;
+use partiql_source_map::line_offset_tracker::LineOffsetTracker;
+
+pub use error::LexError;
+pub use error::LexicalError;
+pub use error::ParseError;
+pub use error::ParserError;
+
+/// General [`Result`] type for the PartiQL [`Parser`].
+pub type ParserResult<'input> = Result<Parsed<'input>, Vec<ParserError<'input>>>;
+
+/// A PartiQL parser from statement strings to AST.
+#[non_exhaustive]
+#[derive(Debug)]
+pub struct Parser {}
+
+impl Default for Parser {
+    fn default() -> Self {
+        Parser {}
+    }
+}
+
+impl Parser {
+    /// Parse a PartiQL statement into an AST.
+    pub fn parse<'input>(&self, text: &'input str) -> ParserResult<'input> {
+        let mut offsets = LineOffsetTracker::default();
+        let ast = parse_partiql(text, &mut offsets)?;
+        Ok(Parsed { text, offsets, ast })
+    }
+}
 
-pub use parse::parse_partiql;
+/// The output of parsing PartiQL statement strings: an AST and auxiliary data.
+#[non_exhaustive]
+#[derive(Debug)]
+pub struct Parsed<'input> {
+    text: &'input str,
+    offsets: LineOffsetTracker,
+    ast: Box<ast::Expr>,
+}

partiql-parser/src/parse/mod.rs

@@ -2,9 +2,9 @@
 
 //! Provides the [`parse_partiql`] function to parse a PartiQL query.
 
-use crate::lexer;
+use crate::error::{ParseError, UnexpectedTokenData};
 use crate::preprocessor::{built_ins, FnExprSet, PreprocessingPartiqlLexer};
-use crate::result::{ParseError, ParserResult, UnexpectedTokenData};
+use crate::{lexer, ParserError};
 use lalrpop_util as lpop;
 use lazy_static::lazy_static;
 use partiql_ast::ast;
@@ -30,19 +30,20 @@ type LalrpopResult<'input> = Result<Box<ast::Expr>, LalrpopError<'input>>;
 type LalrpopErrorRecovery<'input> =
     lpop::ErrorRecovery<ByteOffset, lexer::Token<'input>, ParseError<'input, BytePosition>>;
 
+pub(crate) type AstResult<'input> = Result<Box<ast::Expr>, Vec<ParserError<'input>>>;
+
 lazy_static! {
     static ref BUILT_INS: FnExprSet<'static> = built_ins();
 }
 
 /// Parse PartiQL query text.
-pub fn parse_partiql(s: &str) -> ParserResult {
-    let mut offsets = LineOffsetTracker::default();
+pub fn parse_partiql<'input>(s: &'input str, offsets: &mut LineOffsetTracker) -> AstResult<'input> {
     let mut errors: Vec<LalrpopErrorRecovery> = vec![];
-    let lexer = PreprocessingPartiqlLexer::new(s, &mut offsets, &*BUILT_INS);
+    let lexer = PreprocessingPartiqlLexer::new(s, offsets, &*BUILT_INS);
 
     let parsed: LalrpopResult = grammar::QueryParser::new().parse(s, &mut errors, lexer);
 
-    process_errors(s, &offsets, parsed, errors)
+    process_errors(s, offsets, parsed, errors)
 }
 
 fn process_errors<'input, T>(
@@ -124,6 +125,10 @@ impl<'input> From<LalrpopError<'input>> for ParseError<'input, BytePosition> {
 #[cfg(test)]
 mod tests {
     use super::*;
+    pub fn parse_partiql(s: &str) -> AstResult {
+        let mut offsets = LineOffsetTracker::default();
+        super::parse_partiql(s, &mut offsets)
+    }
 
     macro_rules! parse {
         ($q:expr) => {{
@@ -578,7 +583,7 @@ mod tests {
 
     mod errors {
         use super::*;
-        use crate::result::{LexicalError, UnexpectedToken, UnexpectedTokenData};
+        use crate::error::{LexicalError, UnexpectedToken, UnexpectedTokenData};
         use partiql_source_map::location::{
             CharOffset, LineAndCharPosition, LineOffset, Located, Location,
         };

partiql-parser/src/parse/partiql.lalrpop

@@ -1,5 +1,5 @@
 use crate::parse::lexer;
-use crate::result::ParseError;
+use crate::error::ParseError;
 
 use lalrpop_util as lpop;
 

partiql-parser/src/preprocessor.rs

@@ -5,7 +5,7 @@ use std::collections::VecDeque;
 
 use std::ops::Range;
 
-use crate::result::LexError;
+use crate::error::LexError;
 
 use crate::lexer::{InternalLexResult, LexResult, PartiqlLexer, Spanned, Token};
 

partiql-source-map/src/line_offset_tracker.rs

@@ -27,6 +27,7 @@ use std::ops::Range;
 /// assert_eq!(tracker.at(source, ByteOffset(30).into()), Ok(LineAndCharPosition::new(3,4)));
 /// assert_eq!(tracker.at(source, ByteOffset(300).into()), Err(LineOffsetError::EndOfInput));
 /// ```
+#[derive(Debug)]
 pub struct LineOffsetTracker {
     line_starts: SmallVec<[ByteOffset; 16]>,
 }