asciidoc_parser/parser/
include_file_handler.rs

1use std::fmt::Debug;
2
3use crate::{Parser, attributes::Attrlist};
4
5/// An `IncludeFileHandler` is responsible for providing the text content for an
6/// `include::` directive when encountered.
7///
8/// A client of [`Parser`] may provide an `IncludeFileHandler` to customize how
9/// include file resolution is handled.
10///
11/// [`Parser`]: crate::Parser
12pub trait IncludeFileHandler: Debug {
13    /// Provide the file content for an `include::` directive, if available.
14    ///
15    /// # Parameters
16    /// - `source`: The path to the document that is including the file. A root
17    ///   document may be signaled via `None` depending on how the parser was
18    ///   invoked. This path should be considered when resolving relative paths.
19    /// - `target`: The path to the document that was provided in the
20    ///   `include::` directive.
21    /// - `attrlist`: Any attributes specified on the include directive.
22    /// - `parser`: An implementation may read document attribute values from
23    ///   the [`Parser`] state.
24    ///
25    /// Return the string content of the include file if found. If no file is
26    /// found, return `None` and an appropriate warning message will be
27    /// generated.
28    ///
29    /// # Options
30    /// With the exception of `encoding` (see below), the implementation should
31    /// not attempt to interpret any of the built-in attributes (i.e.
32    /// `leveloffset`, `lines`, `tags`, or `indent`). Correct handling of these
33    /// attributes will be provided by the parser itself.
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. If the implementation is capable of
38    /// transcoding from other formats, it may use the `encoding` attribute as a
39    /// hint of the source format. If the implementation finds a file that is
40    /// not encoded in UTF-8 and is incapable of translating, it should return
41    /// `None`.
42    fn resolve_target<'src>(
43        &self,
44        source: Option<&str>,
45        target: &str,
46        attrlist: &Attrlist<'src>,
47        parser: &Parser,
48    ) -> Option<String>;
49}
asciidoc_parser/parser/include_file_handler.rs

asciidoc_parser/parser/
include_file_handler.rs
