diff options
Diffstat (limited to 'src/lib.rs')
| -rw-r--r-- | src/lib.rs | 140 |
1 files changed, 120 insertions, 20 deletions
@@ -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: @@ -10,13 +13,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,13 +57,27 @@ 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, roadmap_width: usize, java_path: PathBuf, plantuml_jar: PathBuf, + errors: Vec<DiagramError>, } /// Possible errors for diagram filtering. @@ -39,7 +85,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}")] @@ -50,7 +98,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 /// @@ -61,8 +117,19 @@ 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}")] - HelperFailed(String, PathBuf, String, String), + #[error("helper program failed: {0} (as {1}), exit status {2}:\n{3}")] + 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 /// @@ -75,21 +142,41 @@ pub enum DiagramError { type Svg = Vec<u8>; impl Default for DiagramFilter { + /// Create a filter with default settings. fn default() -> Self { Self { dot: PathBuf::from("dot"), roadmap_width: 50, java_path: PathBuf::from("java"), plantuml_jar: PathBuf::from("/usr/share/plantuml/plantuml.jar"), + errors: vec![], } } } 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<P>(&mut self, path: P) -> &mut Self where P: AsRef<Path>, @@ -98,6 +185,8 @@ impl DiagramFilter { self } + /// Set the name by which to invoke the Java runtime, for + /// PlantUML. The default is "`java`". pub fn java_path<P>(&mut self, path: P) -> &mut Self where P: AsRef<Path>, @@ -106,6 +195,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<P>(&mut self, path: P) -> &mut Self where P: AsRef<Path>, @@ -114,17 +205,14 @@ 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 { + 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 +316,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 +343,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()), |