better errors

Author: alexhallam

Cargo.lock

@@ -1,7 +1,7 @@
 [package]
 description = "High-performance modern Wilkinson's formula parsing for statistical models. Parses R-style formulas into structured JSON metadata supporting linear models, mixed effects, and complex statistical specifications."
 name = "fiasto"
-version = "0.2.1"
+version = "0.2.2"
 edition = "2021"
 authors = ["Alex Hallam <alexhallam6.28@gmail.com>"]
 license = "MIT"
@@ -24,3 +24,4 @@ serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 thiserror = "1.0"
 logos = "0.15.1"
+owo-colors = "4.2.2"

Cargo.toml

@@ -0,0 +1,10 @@
+use fiasto::parse_formula;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let input = "y ~ x +++";
+
+    let result = parse_formula(input)?;
+    println!("{}", serde_json::to_string_pretty(&result)?);
+
+    Ok(())
+}

examples/e01.rs

@@ -0,0 +1,16 @@
+use fiasto::internal::parser::Parser;
+
+// This example intentionally uses a malformed formula so we can see the pretty error output.
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // trailing '+' will cause a parse error
+    let input = "y ~ x +";
+    let mut parser = Parser::new(input)?;
+    match parser.parse_formula() {
+        Ok(_) => println!("parsed ok (unexpected)"),
+        Err(e) => {
+            // Print the colored, pretty error to stderr
+            eprintln!("{}", parser.pretty_error(&e));
+        }
+    }
+    Ok(())
+}

examples/pretty_error.rs

@@ -0,0 +1,20 @@
+use fiasto::parse_formula;
+
+fn main() {
+    // Test different error scenarios
+    let test_cases = vec![
+        "y ~ x +",           // trailing plus
+        "y ~ + x",           // leading plus  
+        "~ x",               // missing response
+        "y ~ x (",           // unmatched paren
+        "y ~",               // incomplete formula
+    ];
+    
+    for (i, formula) in test_cases.iter().enumerate() {
+        println!("\n=== Test case {} ===", i + 1);
+        println!("Formula: {}", formula);
+        if let Err(_) = parse_formula(formula) {
+            // Error is already printed by parse_formula via eprintln!
+        }
+    }
+}

examples/test_pretty.rs

@@ -143,7 +143,7 @@ pub fn parse_term<'a>(tokens: &'a [(Token, &'a str)], pos: &mut usize) -> Result
                         | Token::FunctionStart
                 )
             },
-            "Function token or ColumnName",
+            "Function or ColumnName",
         )?;
         if crate::internal::matches::matches(tokens, pos, |t| matches!(t, Token::FunctionStart)) {
             let fname = match tok {

src/internal/parse_term.rs

@@ -51,6 +51,8 @@ use crate::internal::{
     lexer::Token,
 };
 
+use owo_colors::OwoColorize;
+
 /// Parser for statistical formulas
 ///
 /// The parser converts formula strings into Abstract Syntax Trees (ASTs).
@@ -113,22 +115,63 @@ impl<'a> Parser<'a> {
         crate::internal::new::new(input)
     }
 
+    /// Pretty-print a parse error with context (tokens, last-consumed lexeme, expected/found)
+    ///
+    /// This produces a colored, human-friendly message useful for CLI output.
+    pub fn pretty_error(&self, err: &ParseError) -> String {
+        match err {
+            ParseError::Lex(s) => {
+                format!("{}\n\n{}\n", "Lexing error".red().bold(), s)
+            }
+            ParseError::Eoi => {
+                format!("{}\n\n{}\n", "Unexpected end of input".red().bold(), "the formula ended earlier than expected")
+            }
+            ParseError::Unexpected { expected, found: _ } => {
+                let mut out = String::new();
+                
+                // Header
+                out.push_str(&format!("{}\n", "Syntax error- Unexpected Token".red().bold()));
+                
+                // Formula: just print the original formula uncolored
+                out.push_str(&format!("Formula: {}\n", self.input));
+                
+                // Show: previous successful lexemes in green then failed lexeme in red
+                out.push_str("Show: ");
+                for i in 0..self.pos {
+                    if let Some((_, lex)) = self.tokens.get(i) {
+                        out.push_str(&format!("{} ", lex.green()));
+                    }
+                }
+                let failed = self.tokens.get(self.pos).map(|(_, l)| *l).unwrap_or("<eoi>");
+                out.push_str(&format!("{}\n", failed.red()));
+                
+                // Expected Token: list expected tokens
+                out.push_str(&format!("Expected Token: {}\n", expected.to_string()));
+                
+                out
+            }
+            ParseError::Syntax(s) => {
+                format!("{}\n\n{}\n", "Syntax error".red().bold(), s)
+            }
+        }
+    }
+
     /// Parses the formula and returns the complete AST information
     ///
     /// This method performs the syntactic analysis of the tokenized formula
-    /// and returns the parsed components.
+    /// and returns the structured representation needed for statistical modeling.
     ///
     /// # Returns
-    ///
+    /// 
     /// A tuple containing:
-    /// * `String` - The response variable name
+    /// * `String` - The response variable (left side of ~)
     /// * `Vec<Term>` - All terms in the formula (fixed effects, random effects, etc.)
     /// * `bool` - Whether the model includes an intercept
     /// * `Option<Family>` - The distribution family (if specified)
     ///
     /// # Examples
-///
-/// ```rust
+    ///
+    /// ```rust
 /// use fiasto::internal::parser::Parser;
 ///
 /// let formula = "y ~ x + (1 | group), family = gaussian";
@@ -142,6 +185,12 @@ impl<'a> Parser<'a> {
     pub fn parse_formula(
         &mut self,
     ) -> Result<(String, Vec<Term>, bool, Option<Family>), ParseError> {
-        crate::internal::parse_formula::parse_formula(&self.tokens, &mut self.pos)
+        match crate::internal::parse_formula::parse_formula(&self.tokens, &mut self.pos) {
+            Ok(v) => Ok(v),
+            Err(e) => {
+                // Return the original error unchanged so pretty_error can handle it properly
+                Err(e)
+            }
+        }
     }
 }

src/internal/parser.rs

@@ -282,7 +282,14 @@ use serde_json::Value;
 /// - Fast pattern matching
 pub fn parse_formula(formula: &str) -> Result<Value, Box<dyn std::error::Error>> {
     let mut p = Parser::new(formula)?;
-    let (response, terms, has_intercept, family_opt) = p.parse_formula()?;
+    let (response, terms, has_intercept, family_opt) = match p.parse_formula() {
+        Ok(v) => v,
+        Err(e) => {
+            // Print pretty, colored error by default for CLI users
+            eprintln!("{}", p.pretty_error(&e));
+            return Err(Box::new(e));
+        }
+    };
 
     let mut mb = MetaBuilder::new();
     mb.push_response(&response);