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.

The rendered replacement (Unresolved directive …) is identical for the two failure reasons; only the warning differs, mirroring Asciidoctor’s separate include file not found and include file not readable 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, it should return IncludeResolution::NotFound.

Dyn Compatibility

This trait is dyn compatible.

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

Implementors