asciidoc_parser/parser/
svg_file_handler.rs

1use std::fmt::Debug;
2
3use crate::Parser;
4
5/// An `SvgFileHandler` is responsible for providing the raw contents of an SVG
6/// file when an inline image macro requests that the SVG be embedded directly
7/// in the output (`image:target.svg[opts=inline]`).
8///
9/// This crate is a parser, not a converter, and never reads from the
10/// filesystem itself. A client of [`Parser`] that wants inline SVG images to be
11/// embedded must provide an `SvgFileHandler` (analogous to
12/// [`IncludeFileHandler`] and [`DocinfoFileHandler`]) that maps a resolved
13/// image path to its content. If no handler is provided (or the handler cannot
14/// find the file), the inline SVG image degrades to a `<span class="alt">`
15/// element containing the alt text, matching Ruby Asciidoctor's behavior when
16/// the SVG contents can't be read.
17///
18/// [`Parser`]: crate::Parser
19/// [`IncludeFileHandler`]: crate::parser::IncludeFileHandler
20/// [`DocinfoFileHandler`]: crate::parser::DocinfoFileHandler
21pub trait SvgFileHandler: Debug {
22    /// Provide the raw contents of an SVG file, if available.
23    ///
24    /// # Parameters
25    /// - `target`: The resolved path to the SVG file, already prefixed with the
26    ///   value of the `imagesdir` attribute (if any). This is the same value
27    ///   that would appear in the `src` attribute of a non-inline image.
28    /// - `parser`: An implementation may read document attribute values from
29    ///   the [`Parser`] state.
30    ///
31    /// Return the string content of the SVG file if found. If no file is found
32    /// (or it is not readable), return `None`; the inline image will then fall
33    /// back to rendering its alt text.
34    ///
35    /// # Encoding
36    /// If a `Some` result is provided, it is a typical Rust [`String`] and
37    /// therefore must be encoded as UTF-8.
38    ///
39    /// [`Parser`]: crate::Parser
40    fn resolve_svg(&self, target: &str, parser: &Parser) -> Option<String>;
41}
asciidoc_parser/parser/svg_file_handler.rs

asciidoc_parser/parser/
svg_file_handler.rs
