From c64ed7b006943365acdf78feb86ebcff63749fda Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 11 Dec 2021 10:52:54 +0200 Subject: fix: use the right command line tool in scenarios Sponsored-by: author --- pandoc-filter-diagram.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pandoc-filter-diagram.md b/pandoc-filter-diagram.md index 86081d4..12520cb 100644 --- a/pandoc-filter-diagram.md +++ b/pandoc-filter-diagram.md @@ -47,7 +47,7 @@ and is not referenced as an external image. ~~~scenario given an installed Rust program pandoc-filter-diagram given file pikchr.md -when I run pandoc --filter subplot-filter pikchr.md -o pikchr.html +when I run pandoc --filter pandoc-filter-diagram pikchr.md -o pikchr.html then file pikchr.html matches regex /img src="data:image/svg\+xml;base64,/ ~~~ @@ -84,7 +84,7 @@ HTML output, not referenced as an external image. ~~~scenario given an installed Rust program pandoc-filter-diagram given file dot.md -when I run pandoc --filter subplot-filter dot.md -o dot.html +when I run pandoc --filter pandoc-filter-diagram dot.md -o dot.html then file dot.html matches regex /img src="data:image/svg\+xml;base64,/ ~~~ @@ -202,7 +202,7 @@ HTML output, not referenced as an external image. ~~~scenario given an installed Rust program pandoc-filter-diagram given file roadmap.md -when I run pandoc --filter subplot-filter roadmap.md -o roadmap.html +when I run pandoc --filter pandoc-filter-diagram roadmap.md -o roadmap.html then file roadmap.html matches regex /img src="data:image/svg\+xml;base64,/ ~~~ -- cgit v1.2.1 From 1605867b8e6b37160e527c9439322fc40ac6cce9 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 11 Dec 2021 09:34:34 +0200 Subject: fix: include stderr in error message when helper fails Previously, the exit status code was shown, not stderr. Sponsored-by: author --- src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index 40ae760..c7c3bc5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -61,7 +61,7 @@ pub enum DiagramError { /// /// This probably implies there's something wrong in the filter. /// Please report this error. - #[error("helper program failed: {0} (as {1}): {2}")] + #[error("helper program failed: {0} (as {1}), exit status {2}:\n{3}")] HelperFailed(String, PathBuf, String, String), /// I/O error -- cgit v1.2.1 From d8df77a971d6bdd911d1d49cbd872e91427ae984 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 11 Dec 2021 09:35:19 +0200 Subject: feat! collect errors from diagram rendering The errors are always rendered into the document. The caller can get them with the DiagramFilter::errors method and can decide what to do if there are any. This also changes the function signature for DiagramFilter::error_block, which is SemVer incompatible. Sponsored-by: author --- src/lib.rs | 32 +++++++++++++++++++++++++------- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index c7c3bc5..0f7b2a1 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -32,6 +32,7 @@ pub struct DiagramFilter { roadmap_width: usize, java_path: PathBuf, plantuml_jar: PathBuf, + errors: Vec, } /// Possible errors for diagram filtering. @@ -81,6 +82,7 @@ impl Default for DiagramFilter { roadmap_width: 50, java_path: PathBuf::from("java"), plantuml_jar: PathBuf::from("/usr/share/plantuml/plantuml.jar"), + errors: vec![], } } } @@ -90,6 +92,10 @@ impl DiagramFilter { Self::default() } + pub fn errors(&self) -> &[DiagramError] { + &self.errors + } + pub fn dot_path

(&mut self, path: P) -> &mut Self where P: AsRef, @@ -124,7 +130,7 @@ impl DiagramFilter { doc } - fn error_block(&self, error: DiagramError) -> Block { + fn error_block(&self, error: &DiagramError) -> Block { let msg = Inline::Str(format!("ERROR: {}", error.to_string())); let msg = vec![Inline::Strong(vec![msg])]; Block::Para(msg) @@ -228,12 +234,12 @@ fn filter_via( } else { String::from("terminated by signal") }; - let stderr = String::from_utf8_lossy(&output.stderr); + let stderr = String::from_utf8_lossy(&output.stderr).into_owned(); Err(DiagramError::HelperFailed( name.to_string(), argv0.to_path_buf(), status, - stderr.into_owned(), + stderr, )) } } else { @@ -255,19 +261,31 @@ impl MutVisitor for DiagramFilter { match block { Block::CodeBlock((_id, classes, _kv), text) => match DiagramKind::from(classes) { DiagramKind::GraphvizDot => match self.dot_to_svg(text) { - Err(err) => *block = self.error_block(err), + Err(err) => { + *block = self.error_block(&err); + self.errors.push(err); + } Ok(svg) => *block = self.svg_block(&svg), }, DiagramKind::Roadmap => match self.roadmap_to_svg(text) { - Err(err) => *block = self.error_block(err), + Err(err) => { + *block = self.error_block(&err); + self.errors.push(err); + } Ok(svg) => *block = self.svg_block(&svg), }, DiagramKind::Plantuml => match self.plantuml_to_svg(text) { - Err(err) => *block = self.error_block(err), + Err(err) => { + *block = self.error_block(&err); + self.errors.push(err); + } Ok(svg) => *block = self.svg_block(&svg), }, DiagramKind::Pikchr => match self.pikchr_to_svg(text, None) { - Err(err) => *block = self.error_block(err), + Err(err) => { + *block = self.error_block(&err); + self.errors.push(err); + } Ok(svg) => *block = self.svg_block(&svg), }, DiagramKind::Svg => *block = self.svg_block(text.as_bytes()), -- cgit v1.2.1 From d4a3267c5486ffecada592d7e0889d6cfa5893a3 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 11 Dec 2021 10:06:39 +0200 Subject: docs: improve doc comments Sponsored-by: author --- src/lib.rs | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 91 insertions(+), 12 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 0f7b2a1..d1b7bce 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -10,13 +10,42 @@ //! - [roadmap](https://gitlab.com/larswirzenius/roadmap) //! - [raw SVG](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) //! +//! Example: +//! +//! ~~~~~~markdown +//! This is a sample Markdown file. +//! +//! ```dot +//! digraph "broken" { +//! foo -> bar; +//! } +//! ``` +//! ~~~~~~ +//! //! The Pandoc AST has represents input as `Block` and other types of //! nodes. This crate turns `Block::CodeBlock` nodes that carry a //! class attribute that specifies one of the supported diagram markup -//! languages into blocks with embedded SVG graphics. +//! languages (`dot`, `plantuml`, `pikchr`, `roadmap`, `svg`) into +//! blocks with embedded SVG graphics. +//! +//! Note that this library does not do any parsing of an input +//! document. Use the [`pandoc_ast`](https://crates.io/crates/pandoc_ast) +//! or [`pandoc`](https://crates.io/crates/pandoc) crates for that. +//! +//! # Example //! -//! Note that this library does not do any parsing. The -//! `pandoc_ast::filter` function does that. +//! ``` +//! # use pandoc_filter_diagram::DiagramFilter; +//! # let mut json = r#"{"blocks":[{"t":"CodeBlock","c":[["",["dot"],[]],"digraph \"broken\" {\n foo -> bar;\n}"]}],"pandoc-api-version":[1,20],"meta":{}}"#; +//! let mut df = DiagramFilter::new(); +//! let json = pandoc_ast::filter(json.to_string(), |doc| df.filter(doc)); +//! if !df.errors().is_empty() { +//! for e in df.errors().iter() { +//! eprintln!("ERROR: {}", e); +//! } +//! std::process::exit(1); +//! } +//! ``` use pandoc_ast::{Block, Inline, MutVisitor, Pandoc}; use std::env; @@ -25,7 +54,20 @@ use std::io::{Read, Write}; use std::path::{Path, PathBuf}; use std::process::{Command, Stdio}; -/// Represent the diagram filter. +/// Convert inline diagram markup as images for Pandoc. +/// +/// This acts a filter on the Pandoc Abstract Syntax Tree (AST), to +/// modify it so that any inline markup for diagrams are rendered as +/// SVG images. The library is meant to be used with the +/// `pandoc_ast::filter` function. +/// +/// Filtering may fail. Because of the API constrain imposed by +/// `pandoc_ast::filter`, this library doesn't return a `Result`. +/// Instead, it collects any errors and lets the caller query for them +/// after the filtering is done (see the +/// [`errors`](DiagramFilter::errors) method). All errors are always +/// rendered as text in the document as well, but that requires a +/// human to read the document to spot any errors. #[derive(Debug)] pub struct DiagramFilter { dot: PathBuf, @@ -40,7 +82,9 @@ pub struct DiagramFilter { pub enum DiagramError { /// When rendering a pikchr, something went wrong. #[error("failure rendering pikchr diagram: {0}")] - PikchrRenderError(String), + PikchrRenderError( + /// The error message from pikchr. + String), /// When rendering a roadmap, something went wrong. #[error("failure rendering roadmap diagram: {0}")] @@ -51,7 +95,15 @@ pub enum DiagramError { /// This Pandoc filter uses some helper programs to do some of its /// work. It failed to invoke such a helper program. #[error("failed to invoke helper program {0} (as {1}): {2}")] - InvokeFailed(String, PathBuf, String), + InvokeFailed( + /// Name of the program. + String, + + /// Path with which the program was invoked. + PathBuf, + + /// Standard error output of program. + String), /// A helper program failed /// @@ -63,7 +115,18 @@ pub enum DiagramError { /// This probably implies there's something wrong in the filter. /// Please report this error. #[error("helper program failed: {0} (as {1}), exit status {2}:\n{3}")] - HelperFailed(String, PathBuf, String, String), + HelperFailed( + /// Name of the program. + String, + + /// Path with which the program was invoked. + PathBuf, + + /// How did the program end? Status code or signal? + String, + + /// Standard error output of program. + String), /// I/O error /// @@ -76,6 +139,7 @@ pub enum DiagramError { type Svg = Vec; impl Default for DiagramFilter { + /// Create a filter with default settings. fn default() -> Self { Self { dot: PathBuf::from("dot"), @@ -88,14 +152,28 @@ impl Default for DiagramFilter { } impl DiagramFilter { + /// Create a new filter. pub fn new() -> Self { Self::default() } + /// Process a parsed document to convert inline diagram markup + /// into SVG. This method is suitable to be passed to + /// `pandoc_ast::filter` as the filter function argument. + pub fn filter(&mut self, mut doc: Pandoc) -> Pandoc { + self.walk_pandoc(&mut doc); + doc + } + + /// Return any errors that occurred during the filtering process. + /// The caller can decide how to report them to the user in a + /// suitable way. pub fn errors(&self) -> &[DiagramError] { &self.errors } + /// Set the name by which to invoke Graphviz `dot` program. The + /// default is "`dot`". pub fn dot_path

(&mut self, path: P) -> &mut Self where P: AsRef, @@ -104,6 +182,8 @@ impl DiagramFilter { self } + /// Set the name by which to invoke the Java runtime, for + /// PlantUML. The default is "`java`". pub fn java_path

(&mut self, path: P) -> &mut Self where P: AsRef, @@ -112,6 +192,8 @@ impl DiagramFilter { self } + /// Set the location of the PlantUML jar (Java bytecode archive). + /// The default is "`/usr/share/plantuml/plantuml.jar`". pub fn plantuml_jar

(&mut self, path: P) -> &mut Self where P: AsRef, @@ -120,16 +202,13 @@ impl DiagramFilter { self } + /// Set the maximum width, in characters, of the roadmap text + /// nodes. The default is 50. pub fn roadmap_width(&mut self, w: usize) -> &mut Self { self.roadmap_width = w; self } - pub fn filter(&mut self, mut doc: Pandoc) -> Pandoc { - self.walk_pandoc(&mut doc); - doc - } - fn error_block(&self, error: &DiagramError) -> Block { let msg = Inline::Str(format!("ERROR: {}", error.to_string())); let msg = vec![Inline::Strong(vec![msg])]; -- cgit v1.2.1 From 4413917ca5dfb53a6ca5f2c6fe78a2f948af0c36 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 11 Dec 2021 09:45:30 +0200 Subject: 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 --- pandoc-filter-diagram.md | 28 +++++++++++++++++++++++++++- src/bin/pandoc-filter-diagram.rs | 17 +++++++++++++++++ src/lib.rs | 3 +++ 3 files changed, 47 insertions(+), 1 deletion(-) 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: -- cgit v1.2.1