asciidoc_parser/parser/
image_file_handler.rs

1use std::fmt::Debug;
2
3use crate::Parser;
4
5/// An `ImageFileHandler` is responsible for providing the raw bytes of an image
6/// file when a referenced image must be embedded directly in the output as a
7/// `data:` URI (i.e. when the `data-uri` document attribute is set and the safe
8/// mode is below [`SafeMode::Secure`]).
9///
10/// This crate is a parser, not a converter, and never reads from the filesystem
11/// itself. A client of [`Parser`] that wants images embedded as `data:` URIs
12/// must provide an `ImageFileHandler` (analogous to [`SvgFileHandler`],
13/// [`IncludeFileHandler`], and [`DocinfoFileHandler`]) that maps a resolved
14/// image path to its bytes. If no handler is provided (or the handler cannot
15/// find the file), the image degrades to an ordinary web path – the same output
16/// as when `data-uri` is not set – matching this crate's convention that a
17/// missing I/O handler is a silent, graceful degradation.
18///
19/// [`Parser`]: crate::Parser
20/// [`SafeMode::Secure`]: crate::SafeMode::Secure
21/// [`SvgFileHandler`]: crate::parser::SvgFileHandler
22/// [`IncludeFileHandler`]: crate::parser::IncludeFileHandler
23/// [`DocinfoFileHandler`]: crate::parser::DocinfoFileHandler
24pub trait ImageFileHandler: Debug {
25    /// Provide the raw bytes of an image file, if available.
26    ///
27    /// # Parameters
28    /// - `target`: The resolved path to the image file, already prefixed with
29    ///   the value of the relevant asset-directory attribute (`imagesdir` or
30    ///   `iconsdir`, as appropriate). This is the same value that would appear
31    ///   in the `src` attribute of the image were it *not* embedded.
32    /// - `parser`: An implementation may read document attribute values from
33    ///   the [`Parser`] state.
34    ///
35    /// Return the bytes of the image file if found. If no file is found (or it
36    /// is not readable), return `None`; the image will then fall back to
37    /// rendering an ordinary web path.
38    ///
39    /// [`Parser`]: crate::Parser
40    fn resolve_image(&self, target: &str, parser: &Parser) -> Option<Vec<u8>>;
41}
asciidoc_parser/parser/image_file_handler.rs

asciidoc_parser/parser/
image_file_handler.rs
