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

3 files changed, 47 insertions, 1 deletions

diff --git a/pandoc-filter-diagram.md b/pandoc-filter-diagram.md
index 12520cb..30e3cf5 100644
--- a/pandoc-filter-diagram.md
+++ b/pandoc-filter-diagram.md
@@ -123,7 +123,7 @@ the HTML output, not referenced as an external image.
 ~~~scenario
 given an installed Rust program pandoc-filter-diagram
 given file plantuml.md
-when I run pandoc --filter subplot-filter plantuml.md -o plantuml.html
+when I run pandoc --filter pandoc-filter-diagram plantuml.md -o plantuml.html
 then file plantuml.html matches regex /img src="data:image/svg\+xml;base64,/
 ~~~
 
@@ -252,3 +252,29 @@ blocked:
   - next
 ~~~
 ~~~~~~~~
+
+
+# Command line tool
+
+The crate provides a command line tool `pandoc-filter-diagram`, for
+use with the `pandoc --filter` option. By default, it ignores any
+errors, but if the `PANDOC_FILTER_FAIL` environment variable is set
+to 1, it fails if there were any errors. This scenario verifies that
+this happens. The happy cases are already verified by other scenarios,
+so this one only verifies handling of bad input.
+
+~~~scenario
+given an installed Rust program pandoc-filter-diagram
+given file bad.md
+when I run pandoc --filter pandoc-filter-diagram bad.md -o bad.html
+then exit code is 0
+when I try to run env PANDOC_FILTER_FAIL=1 pandoc --filter pandoc-filter-diagram bad.md -o bad.html
+then command fails
+~~~
+
+~~~{#bad.md .file .markdown .numberLines}
+trigraph "example" {
+thing -> other
+}
+~~~
+
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: