Enum IncludeError 

pub enum IncludeError {
    Cycle {
        include_site: Range,
        path: PathBuf,
        chain: Vec<PathBuf>,
    },
    DepthExceeded {
        include_site: Range,
        limit: usize,
        chain: Vec<PathBuf>,
    },
    TotalIncludesExceeded {
        include_site: Range,
        limit: usize,
    },
    FileTooLarge {
        include_site: Range,
        path: PathBuf,
        size: u64,
        limit: u64,
    },
    RootEscape {
        path: PathBuf,
        root: PathBuf,
    },
    AbsolutePath {
        path: PathBuf,
    },
    NotFound {
        include_site: Range,
        path: PathBuf,
    },
    ParseFailed {
        path: PathBuf,
        message: String,
    },
    ContainerPolicy {
        include_site: Range,
        container: &'static str,
        file: PathBuf,
        violation: &'static str,
    },
    LoaderIo {
        path: PathBuf,
        message: String,
    },
    MissingSrc {
        include_site: Range,
    },
}

Errors the include resolver can produce.

Variants

Cycle

An include chain looped back on itself. chain is the resolution stack at the moment the duplicate path was about to be pushed, in source-order (entry first, deepest last). include_site is the range of the offending lex.include annotation in its host file — useful for diagnostics that highlight the exact line.

Fields

include_site: Range

path: PathBuf

chain: Vec<PathBuf>

DepthExceeded

The include depth exceeded ResolveConfig::max_depth. chain shows the resolution stack at the moment of failure, in source order. include_site is the range of the offending lex.include annotation in its host file.

Fields

include_site: Range

limit: usize

chain: Vec<PathBuf>

TotalIncludesExceeded

The total number of includes resolved across the document exceeded ResolveConfig::max_total_includes. Bounds adversarial fan-out (which max_depth alone does not). include_site is the lex.include annotation that pushed the count past the limit.

Fields

include_site: Range

limit: usize

FileTooLarge

The included file’s size exceeded the loader’s configured limit. Surfaced by loaders that read from a real filesystem (FsLoader) to bound memory allocation per include. include_site is the offending annotation; size and limit are in bytes.

Fields

include_site: Range

path: PathBuf

size: u64

limit: u64

RootEscape

A path resolved outside the configured ResolveConfig::root.

Fields

path: PathBuf

root: PathBuf

AbsolutePath

The include src was a platform-absolute filesystem path (e.g. Windows C:\foo, \\server\share, \foo). The spec forbids absolute filesystem paths from entering the resolution pipeline; the root-absolute form (leading / resolved against the includes root) is the only spec-allowed way to write a path that doesn’t start from the host’s directory. On Unix the only thing that’s Path::is_absolute() is a leading /, which is consumed by the root-absolute branch first; this variant therefore only fires in practice for Windows-shaped absolute paths.

Fields

path: PathBuf

NotFound

The loader could not find or read the included file. include_site is the range of the offending lex.include annotation in its host file, so editors can squiggle the line that asked for the missing file rather than the document head.

Fields

include_site: Range

path: PathBuf

ParseFailed

The loader returned text that the parser rejected.

Fields

path: PathBuf

message: String

ContainerPolicy

The included file’s content is not legal in the include site’s parent container.

Today this only occurs when an included file has top-level Sessions and the include site is inside a GeneralContainer (Definition, ListItem, or another Annotation’s body). The violation field names the offending content kind (e.g. "Sessions") so future container/policy combinations can reuse this variant without a breaking change.

Fields

include_site: Range

container: &'static str

file: PathBuf

violation: &'static str

LoaderIo

Loader propagated a non-NotFound I/O error.

Fields

path: PathBuf

message: String

MissingSrc

lex.include annotation was missing the mandatory src= parameter.

Fields

include_site: Range

Trait Implementations

impl Clone for IncludeError

fn clone(&self) -> IncludeError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for IncludeError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for IncludeError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for IncludeError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.