Rust: Match lex return type with other signatures (#783)

This pull request refactors the `lex` return type in the public Rust
API. Additionally, the `LexResult` and `ParseResult` types now implement
`Display` for easier printing.

```rust
use herb::{lex, parse};

fn main() {
  let template = "<h1><%= title %></h1>";

  match lex(template) {
    Ok(result) => { println!("{}", result); }
    Err(error) => { eprintln!("Lex error: {}", error); }
  }

  match parse(template) {
    Ok(result) => { println!("{}", result); }
    Err(error) => { eprintln!("Parse error: {}", error); }
  }
}
```

Author: marcoroth

docs/docs/bindings/rust/index.md

@@ -75,10 +75,18 @@ use herb::lex;
 
 fn main() {
   let source = "<h1><%= user.name %></h1>";
-  let result = lex(source);
 
-  for token in result.tokens() {
-    println!("{}", token.inspect());
+  match lex(source) {
+    Ok(result) => {
+      println!("{}", result);
+
+      for token in result.tokens() {
+        // do something with each token
+      }
+    }
+    Err(e) => {
+      eprintln!("Lex error: {}", e);
+    }
   }
 }
 ```

docs/docs/bindings/rust/reference.md

@@ -20,19 +20,27 @@ The `herb` crate exposes functions for lexing, parsing, and extracting Ruby and
 
 ## Lexing
 
-The `herb::lex` function tokenizes an HTML document with embedded Ruby and returns a `LexResult` containing all tokens.
+The `herb::lex` function tokenizes an HTML document with embedded Ruby and returns a `Result<LexResult, String>` containing all tokens.
 
-### `herb::lex(source: &str) -> LexResult`
+### `herb::lex(source: &str) -> Result<LexResult, String>`
 
 :::code-group
 ```rust
 use herb::lex;
 
 let source = "<p>Hello <%= user.name %></p>";
-let result = lex(source);
 
-for token in result.tokens() {
-  println!("{}", token.inspect());
+match lex(source) {
+  Ok(result) => {
+    println!("{}", result);
+
+    for token in result.tokens() {
+      // do something with each token
+    }
+  }
+  Err(e) => {
+    eprintln!("Lex error: {}", e);
+  }
 }
 // Output:
 // #<Herb::Token type="TOKEN_HTML_TAG_START" value="<" range=[0, 1] start=(1:0) end=(1:1)>

rust/README.md

@@ -32,14 +32,19 @@ make all          # Generate templates and build
 ### As a Library
 
 ```rust
-use herb::{lex, Token};
+use herb::{lex, parse};
 
 fn main() {
-  let source = r#"<div><%= name %></div>"#;
-  let result = lex(source);
+  let template = "<h1><%= title %></h1>";
 
-  for token in result.tokens() {
-    println!("{}", token.inspect());
+  match lex(template) {
+    Ok(result) => { println!("{}", result); }
+    Err(error) => { eprintln!("Lex error: {}", error); }
+  }
+
+  match parse(template) {
+    Ok(result) => { println!("{}", result); }
+    Err(error) => { eprintln!("Parse error: {}", error); }
   }
 }
 ```

rust/src/herb.rs

@@ -3,13 +3,13 @@ use crate::convert::token_from_c;
 use crate::{LexResult, ParseResult};
 use std::ffi::CString;
 
-pub fn lex(source: &str) -> LexResult {
+pub fn lex(source: &str) -> Result<LexResult, String> {
   unsafe {
-    let c_source = CString::new(source).expect("Failed to create CString");
+    let c_source = CString::new(source).map_err(|e| e.to_string())?;
     let c_tokens = crate::ffi::herb_lex(c_source.as_ptr());
 
     if c_tokens.is_null() {
-      return LexResult::new(Vec::new());
+      return Err("Failed to lex source".to_string());
     }
 
     let array_size = crate::ffi::hb_array_size(c_tokens);
@@ -26,7 +26,7 @@ pub fn lex(source: &str) -> LexResult {
     let mut c_tokens_ptr = c_tokens;
     crate::ffi::herb_free_tokens(&mut c_tokens_ptr as *mut *mut hb_array_T);
 
-    LexResult::new(tokens)
+    Ok(LexResult::new(tokens))
   }
 }
 

rust/src/lex_result.rs

@@ -1,4 +1,5 @@
 use crate::Token;
+use std::fmt;
 
 pub struct LexResult {
   pub tokens: Vec<Token>,
@@ -12,4 +13,19 @@ impl LexResult {
   pub fn tokens(&self) -> &[Token] {
     &self.tokens
   }
+
+  pub fn inspect(&self) -> String {
+    self
+      .tokens
+      .iter()
+      .map(|token| token.inspect())
+      .collect::<Vec<_>>()
+      .join("\n")
+  }
+}
+
+impl fmt::Display for LexResult {
+  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+    write!(f, "{}", self.inspect())
+  }
 }

rust/src/lib.rs

@@ -23,35 +23,3 @@ pub use range::Range;
 pub use token::Token;
 
 pub const VERSION: &str = "0.7.5";
-
-#[cfg(test)]
-mod tests {
-  use super::*;
-  use crate::nodes::{DocumentNode, HTMLTextNode};
-
-  #[test]
-  fn test_tree_inspect() {
-    let loc = Location::new(Position::new(1, 0), Position::new(1, 5));
-
-    let text_node = HTMLTextNode {
-      node_type: "HTMLTextNode".to_string(),
-      location: loc,
-      errors: vec![],
-      content: "Hello".to_string(),
-    };
-
-    let doc_node = DocumentNode {
-      node_type: "DocumentNode".to_string(),
-      location: Location::new(Position::new(1, 0), Position::new(2, 0)),
-      errors: vec![],
-      children: vec![AnyNode::HTMLTextNode(text_node)],
-    };
-
-    let output = doc_node.tree_inspect();
-
-    assert!(output.contains("@ DocumentNode"));
-    assert!(output.contains("children: (1 item)"));
-    assert!(output.contains("@ HTMLTextNode"));
-    assert!(output.contains("Hello"));
-  }
-}

rust/src/main.rs

@@ -65,9 +65,14 @@ fn lex_command(file_path: &str) {
     }
   };
 
-  let result = herb::lex(&source);
-  for token in result.tokens() {
-    println!("{}", token.inspect());
+  match herb::lex(&source) {
+    Ok(result) => {
+      println!("{}", result);
+    }
+    Err(e) => {
+      eprintln!("Lex error: {}", e);
+      std::process::exit(1);
+    }
   }
 }
 
@@ -82,7 +87,7 @@ fn parse_command(file_path: &str) {
 
   match herb::parse(&source) {
     Ok(result) => {
-      println!("{}", result.tree_inspect());
+      println!("{}", result.inspect());
     }
     Err(e) => {
       eprintln!("Parse error: {}", e);

rust/src/parse_result.rs

@@ -1,5 +1,6 @@
 use crate::errors::{AnyError, ErrorNode};
 use crate::nodes::{DocumentNode, Node};
+use std::fmt;
 
 pub struct ParseResult {
   pub value: DocumentNode,
@@ -16,7 +17,7 @@ impl ParseResult {
     }
   }
 
-  pub fn tree_inspect(&self) -> String {
+  pub fn inspect(&self) -> String {
     self.value.tree_inspect()
   }
 
@@ -39,3 +40,9 @@ impl ParseResult {
     self.recursive_errors().is_empty()
   }
 }
+
+impl fmt::Display for ParseResult {
+  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+    write!(f, "{}", self.inspect())
+  }
+}

rust/tests/common/mod.rs

@@ -0,0 +1,5 @@
+// Common test utilities
+
+pub fn no_color() {
+  colored::control::set_override(false);
+}

rust/tests/error_handling_test.rs

@@ -1,11 +1,15 @@
+mod common;
+
 use herb::parse;
 
 #[test]
 fn test_unclosed_element_error() {
+  common::no_color();
+
   let source = "<div class=\"test\">";
   let result = parse(source).unwrap();
 
-  let tree_inspect = result.tree_inspect();
+  let tree_inspect = result.inspect();
   assert!(tree_inspect.contains("UnclosedElementError"));
   assert!(tree_inspect.contains("Tag `<div>` opened at (1:1) was never closed"));
   assert!(tree_inspect.contains("MissingClosingTagError"));
@@ -14,20 +18,24 @@ fn test_unclosed_element_error() {
 
 #[test]
 fn test_tag_names_mismatch_error() {
+  common::no_color();
+
   let source = "<div></span>";
   let result = parse(source).unwrap();
 
-  let tree_inspect = result.tree_inspect();
+  let tree_inspect = result.inspect();
   assert!(tree_inspect.contains("TagNamesMismatchError"));
   assert!(tree_inspect.contains("Opening tag `<div>` at (1:1) closed with `</span>`"));
 }
 
 #[test]
 fn test_no_errors_with_valid_html() {
+  common::no_color();
+
   let source = "<div>Hello</div>";
   let result = parse(source).unwrap();
 
-  let tree_inspect = result.tree_inspect();
+  let tree_inspect = result.inspect();
   assert!(!tree_inspect.contains("error"));
   assert!(!tree_inspect.contains("ERROR"));
 }