Trait IncludeFileHandler 

pub trait IncludeFileHandler: Debug {
    // Required method
    fn resolve_target<'src>(
        &self,
        source: Option<&str>,
        target: &str,
        attrlist: &Attrlist<'src>,
        parser: &Parser,
    ) -> IncludeResolution;
}

An IncludeFileHandler is responsible for providing the text content for an include:: directive when encountered.

A client of Parser may provide an IncludeFileHandler to customize how include file resolution is handled.

Required Methods

fn resolve_target<'src>( &self, source: Option<&str>, target: &str, attrlist: &Attrlist<'src>, parser: &Parser, ) -> IncludeResolution

Provide the file content for an include:: directive, if available.

Parameters

• source: The path to the document that is including the file. A root document may be signaled via None depending on how the parser was invoked. This path should be considered when resolving relative paths.
• target: The path to the document that was provided in the include:: directive.
• attrlist: Any attributes specified on the include directive.
• parser: An implementation may read document attribute values from the Parser state.

Return the outcome as an IncludeResolution:

• IncludeResolution::Found carries the content of the include file (wrapped in IncludeContent).
• IncludeResolution::NotFound signals that no such file exists; the parser records a WarningType::IncludeFileNotFound warning.
• IncludeResolution::NotReadable signals that the file exists but could not be read (for example a permission or other IO error); the parser records a WarningType::IncludeFileNotReadable warning.
• IncludeResolution::NotDecodable signals that the file exists and was read but is not valid UTF-8 and the handler could not transcode it (see the # Encoding section); the parser records a WarningType::IncludeFileNotDecodable warning.

The rendered replacement (Unresolved directive …) is identical for the three failure reasons; only the warning differs, mirroring Asciidoctor’s separate include file not found, include file not readable, and invalid byte sequence in UTF-8 messages.

Options

With the exception of encoding (see below), the implementation should not attempt to interpret any of the built-in attributes (i.e. leveloffset, lines, tags, or indent). Correct handling of these attributes will be provided by the parser itself.

Encoding

The content returned in IncludeContent is a typical Rust String and therefore must be encoded as UTF-8.

If the implementation is capable of transcoding from other formats, it may use the encoding attribute as a hint of the source format. When it transcodes the content to UTF-8, it should return the result via IncludeContent::transcoded so that the parser knows the requested encoding was honored and suppresses the non-UTF-8 include-encoding warning.

An implementation that only deals in UTF-8 should return its content via IncludeContent::new (or the From conversions). If the directive requested a non-UTF-8 encoding, the parser will emit a non-UTF-8 include-encoding warning in that case.

If the implementation finds a file that is not encoded in UTF-8 and is incapable of transcoding it (no encoding attribute, or one it does not support), it should return IncludeResolution::NotDecodable so the parser can name the real cause. Asciidoctor treats this condition as fatal (invalid byte sequence in UTF-8); this crate favors recoverable warnings, so it instead drops the include and records a WarningType::IncludeFileNotDecodable warning.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors