Enum DocumentError 

pub enum DocumentError {
    EmptyPath,
    EmptyValues,
    UnknownSegment {
        path: String,
        segment: String,
    },
    UnregisteredArray {
        path: String,
    },
    SlugNotFound {
        prefix: String,
        slug: String,
    },
    AmbiguousMatch {
        prefix: String,
        segment: String,
        indices: Vec<usize>,
    },
    SlugAlreadyExists {
        prefix: String,
        slug: String,
    },
    NotTraversable {
        path: String,
        got: String,
    },
    TypeMismatch {
        path: String,
        expected: String,
        got: String,
        hint: Option<String>,
    },
    PathNotFound {
        path: String,
    },
    IndexOutOfBounds {
        path: String,
        index: usize,
        len: usize,
    },
    ParseError {
        format: String,
        detail: String,
    },
    PathSyntax {
        detail: String,
    },
    SourceRefused {
        format: String,
        detail: String,
    },
    InvalidArgument {
        detail: String,
    },
    WriteWouldCorrupt {
        format: String,
        detail: String,
    },
    FormatUnknown {
        path: String,
    },
    IoError {
        detail: String,
    },
    UnsupportedOperation {
        format: String,
        operation: String,
        detail: String,
    },
}

Variants

EmptyPath

EmptyValues

UnknownSegment

Fields

path: String

segment: String

UnregisteredArray

A non-numeric segment addressed an array that nothing claims: no KeyedList registration covers it and its format states no rule of its own.

The message names the two ways out rather than the internal type that happens to be missing — a caller can supply a rule or use an index, and neither is discoverable from the name of a Rust struct.

Fields

path: String

SlugNotFound

Fields

prefix: String

slug: String

AmbiguousMatch

A non-numeric segment matched several elements of the array at prefix.

Substring matching can produce this, as can an explicit keyed-list field when an externally authored document contains duplicate identities. Naming several things at once is not an address, and picking the first would silently answer a different question than the one asked, so it is refused with structural candidate indices.

Candidate text is deliberately absent: an error must not become a route for document content to bypass normal output redaction.

Fields

prefix: String

segment: String

indices: Vec<usize>

SlugAlreadyExists

Fields

prefix: String

slug: String

NotTraversable

Fields

path: String

got: String

TypeMismatch

Fields

path: String

expected: String

got: String

hint: Option<String>

PathNotFound

Fields

path: String

IndexOutOfBounds

Fields

path: String

index: usize

len: usize

ParseError

A parser rejected the source. detail is the parser’s own text, which quotes the offending line — see Self::redacted_message.

Fields

format: String

detail: String

PathSyntax

A dot-path is malformed: a bad escape, a trailing \, a bare *, an index past the platform’s range.

Distinct from Self::ParseError because nothing here came from the document — the caller’s own address is what failed to parse, and detail is afdata’s own words about it. Sharing a code with a rejected file sent readers to inspect the wrong thing.

Fields

detail: String

SourceRefused

afdata declines to read a source its parser would accept, because it cannot answer honestly about it.

detail is authored here and names the way out; it holds no document text, so Self::redacted_message keeps it. Distinct from Self::ParseError because the file is not malformed — reporting it as a parse failure sends the reader hunting for a syntax error that is not there.

Fields

format: String

detail: String

InvalidArgument

A caller argument contradicts itself or the document. detail is afdata’s own words about the argument, never document content.

Fields

detail: String

WriteWouldCorrupt

A staged edit rendered source this format’s own parser rejects, caught by the read-back in save_atomic before any bytes reached disk.

detail is already redacted: it comes from Self::redacted_message of the rejection, not from its Display.

Fields

format: String

detail: String

FormatUnknown

No format could be inferred for path, so nothing was parsed at all.

Distinct from Self::ParseError because it is about the file’s name, never its contents: it carries no document text, and dropping its detail as a precaution would throw away the only actionable thing it says.

Fields

path: String

IoError

Fields

detail: String

UnsupportedOperation

Fields

format: String

operation: String

detail: String

Implementations

impl DocumentError

pub const fn code(&self) -> &'static str

Stable, program-decidable error code for this failure category.

Multiple variants share a code only when callers should handle them in the same way. An ordinary missing path is document_path_not_found; named array lookup distinguishes a missing slug from an ambiguous one.

pub fn location(&self) -> Option<String>

Best-effort, content-free source location for a parse failure.

Returns e.g. "line 5 column 12" (or "line 5") for a DocumentError::ParseError, and None for every other variant or when the underlying parser reported no position. The returned string is derived from the parser’s position only and never contains document content, so it is safe to surface even when the parsed file may hold secrets.

pub fn redacted_message(&self) -> String

A display message with any potentially content-bearing detail removed — safe to surface when the document may hold secrets.

Two variants can quote material that originates in the document and are rewritten here:

• DocumentError::ParseError renders as failed to parse {format} (with the location appended when known), dropping the parser detail, which echoes a snippet of the source.

DocumentError::PathSyntax, DocumentError::SourceRefused and DocumentError::InvalidArgument keep their detail in full. It is the reason they exist as separate variants: their text is written here, about the caller’s address, argument, or file encoding — never lifted from document content — and it is the only part that says what to do next. Dropping it as a precaution against a leak that cannot happen turned an actionable refusal into failed to parse Markdown.

• DocumentError::TypeMismatch drops got and hint. When built by Self::from_serde those carry serde’s rendering of the offending value, which is document content.

Every other variant renders the same as its [Display], carrying only structural context: paths, requested slugs, indices, and type or format names. In particular, Self::AmbiguousMatch carries candidate indices rather than matched field values. DocumentError::NotTraversable belongs to that group because got is a Value::kind_name, not a value.

pub fn from_serde(path: impl Into<String>, err: impl Display) -> Self

Wrap a serde deserialization failure as a TypeMismatch so callers that do a read-modify-write cycle (set_path → serde round-trip) surface a consistent error style rather than a raw serde message.

Trait Implementations

impl Clone for DocumentError

fn clone(&self) -> DocumentError

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DocumentError

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

Formats the value using the given formatter.

impl Display for DocumentError

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

Formats the value using the given formatter.

impl Error for DocumentError

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.

impl From<Error> for DocumentError

fn from(err: Error) -> Self

Converts to this type from the input type.