feat(cli): write any errors to stderr, fail if requested

The command line program provided by the crate by default succeeds,
despite any errors. If PANDOC_FILTER_FAIL=1 is set in the environment,
it fails.

Sponsored-by: author

2 files changed, 20 insertions, 0 deletions

diff --git a/src/bin/pandoc-filter-diagram.rs b/src/bin/pandoc-filter-diagram.rs
index 80c8ba9..c2f808a 100644
--- a/src/bin/pandoc-filter-diagram.rs
+++ b/src/bin/pandoc-filter-diagram.rs
@@ -1,3 +1,5 @@
+//! A program that can be used with the pandoc --filter option.
+
 use pandoc_filter_diagram::DiagramFilter;
 use std::io::{Read, Write};
 
@@ -9,10 +11,25 @@ fn main() {
 }
 
 fn real_main() -> anyhow::Result<()> {
+    let fail_on_error = if let Ok(v) = std::env::var("PANDOC_FILTER_FAIL") {
+        v == "1"
+    } else {
+        false
+    };
+
     let mut df = DiagramFilter::new();
     let mut json = String::new();
     std::io::stdin().read_to_string(&mut json)?;
     let json = pandoc_ast::filter(json, |doc| df.filter(doc));
+    if !df.errors().is_empty() {
+        for e in df.errors().iter() {
+            eprintln!("ERROR: {}", e);
+        }
+        if fail_on_error {
+            eprintln!("Failing as requested");
+            std::process::exit(1);
+        }
+    }
     std::io::stdout().write_all(json.as_bytes())?;
     Ok(())
 }
diff --git a/src/lib.rs b/src/lib.rs
index d1b7bce..eb55090 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,5 +1,8 @@
 //! Render diagram markup in a Pandoc AST into SVG
 //!
+//! Provide a [Pandoc filter](https://pandoc.org/filters.html) filter
+//! to convert inline diagram markup into images.
+//!
 //! Process a Pandoc abstract syntax tree and convert fenced code
 //! blocks with diagram markup into embedded SVG images. Supported
 //! diagram markup languages: