asciidoc_parser/parser/
docinfo_file_handler.rs

1use std::fmt::Debug;
2
3use crate::Parser;
4
5/// A `DocinfoFileHandler` is responsible for providing the text content of a
6/// [docinfo file] when one is requested while resolving a document's docinfo.
7///
8/// This crate is a parser, not a converter, and never reads from the
9/// filesystem itself. A client of [`Parser`] that wants docinfo files to be
10/// applied must provide a `DocinfoFileHandler` (analogous to
11/// [`IncludeFileHandler`]) that maps a computed docinfo file name to its
12/// content. If no handler is provided, no docinfo content is resolved.
13///
14/// [docinfo file]: https://docs.asciidoctor.org/asciidoc/latest/docinfo/
15/// [`Parser`]: crate::Parser
16/// [`IncludeFileHandler`]: crate::parser::IncludeFileHandler
17pub trait DocinfoFileHandler: Debug {
18    /// Provide the content of a docinfo file, if available.
19    ///
20    /// # Parameters
21    /// - `docinfodir`: The value of the `docinfodir` attribute, if set. When
22    ///   `Some`, docinfo files should be resolved relative to this directory
23    ///   only (a relative value is appended to the document directory; an
24    ///   absolute value is used as-is). When `None`, the implementation should
25    ///   resolve relative to the document directory.
26    /// - `file_name`: The computed docinfo file name to resolve, for example
27    ///   `docinfo-header.html` (shared) or `mydoc-docinfo.html` (private). The
28    ///   parser determines this name from the docinfo scope, location, the
29    ///   document name, and the `outfilesuffix` attribute.
30    /// - `parser`: An implementation may read document attribute values from
31    ///   the [`Parser`] state.
32    ///
33    /// Return the string content of the docinfo file if found. If no file is
34    /// found (or it is not readable), return `None`; the requested location's
35    /// content simply omits this file.
36    ///
37    /// # Encoding
38    /// If a `Some` result is provided, it is a typical Rust [`String`] and
39    /// therefore must be encoded as UTF-8.
40    ///
41    /// [`Parser`]: crate::Parser
42    fn resolve_docinfo(
43        &self,
44        docinfodir: Option<&str>,
45        file_name: &str,
46        parser: &Parser,
47    ) -> Option<String>;
48}
asciidoc_parser/parser/docinfo_file_handler.rs

asciidoc_parser/parser/
docinfo_file_handler.rs
