Enum FigletError 

#[non_exhaustive]
pub enum FigletError {
    FontNotFound {
        name: String,
        searched: Vec<PathBuf>,
    },
    FontParse {
        reason: String,
        line: u32,
    },
    Io(Error),
    WidthTooNarrow {
        needed: u32,
        given: u32,
    },
    InvalidTlfHeader {
        found: Vec<u8>,
    },
    TlfParse {
        reason: String,
        line: u32,
    },
    UnknownFilter {
        name: String,
        available: Vec<String>,
    },
    UnsupportedExportFormat {
        requested: String,
        available: Vec<String>,
    },
    StrictCompatViolation {
        mode: StrictTarget,
        detail: String,
    },
    Internal(&'static str),
}

All fallible operations in rusty-figlet return Result<T, FigletError>.

The enum is #[non_exhaustive] (per AD-013) so additive variants in future minor releases do NOT constitute a breaking change. Downstream matches MUST include a wildcard _ arm:

use rusty_figlet::FigletError;
fn describe(err: &FigletError) -> &'static str {
    match err {
        FigletError::FontNotFound { .. } => "missing font",
        FigletError::FontParse { .. } => "bad font file",
        FigletError::Io(_) => "io error",
        FigletError::WidthTooNarrow { .. } => "width too narrow",
        FigletError::UnknownFilter { .. } => "unknown filter",
        FigletError::Internal(_) => "internal error",
        _ => "unknown",
    }
}

Error::source() returns Some(&io::Error) ONLY for the FigletError::Io variant; all other variants are leaf errors and return None from source(). FontParse { line } is 1-indexed and matches the convention used by upstream figlet(6) parse-error stderr messages.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

FontNotFound

The requested font name (or path) could not be located.

name is the user-supplied identifier; searched is the ordered list of paths the resolver consulted, suitable for displaying in a diagnostic message.

Fields

name: String

Font name or path the user supplied (e.g. "slant", "./my.flf").

searched: Vec<PathBuf>

Ordered list of paths inspected during font resolution.

FontParse

A .flf file failed to parse.

reason is a short human description (e.g. "bad signature", "missing endmark"); line is the 1-indexed line number at which the parser detected the problem.

Fields

reason: String

Short human-readable description of the parse failure.

line: u32

1-indexed line number where the parse error was detected.

Io(Error)

Underlying I/O failure (file read, stdin, stdout).

Error::source() returns the wrapped io::Error for this variant.

WidthTooNarrow

The requested width is too narrow to render the requested glyph(s).

needed is the minimum width a single glyph requires; given is the width the caller supplied.

Fields

needed: u32

Minimum width required by the widest glyph.

given: u32

Width supplied by the caller.

InvalidTlfHeader

The tlf2a magic header was missing or malformed.

found is the first up-to-32 bytes of the file (per spec Security Posture — capped to prevent log spam from adversarial inputs). Raised by crate::tlf::parse_tlf when the magic prefix mismatches or when the numeric header fields are structurally invalid.

Fields

found: Vec<u8>

Up to 32 bytes of observed header for diagnostic display.

TlfParse

A .tlf file’s glyph table failed to parse.

reason is a short human description; line is the 1-indexed line number at which the parser detected the problem. Distinct from FigletError::FontParse because TLF carries different semantics (UTF-8 multicolumn glyphs, multicolor cell markers) and downstream callers may want to recover differently from each.

Fields

reason: String

Short human-readable description of the parse failure.

line: u32

1-indexed line number where the parse error was detected.

UnknownFilter

A -F <chain> segment named a filter that is not in the supported set (or whose leaf is disabled at compile-time).

name is the offending segment as supplied; available enumerates the valid filter names (in declaration order) so the CLI can emit a helpful diagnostic per FR-016 and spec Edge Cases. Raised by crate::filter::FilterChain::parse.

Fields

name: String

Offending filter name from the -F chain.

available: Vec<String>

Valid filter names in declaration order.

UnsupportedExportFormat

A CLI or library caller requested an export format whose leaf is disabled at compile time (FR-016 + Phase 7 / T046).

requested is the user-supplied format name (e.g. "html"); available enumerates the format names whose leaves ARE enabled in this build so the CLI can produce a helpful diagnostic. Raised by crate::export::write_export.

Fields

requested: String

Offending export format name as supplied by the caller.

available: Vec<String>

Format names whose leaves ARE compiled into this build.

StrictCompatViolation

Strict-compat mode encountered input it cannot byte-equal-match against the documented target (toilet 0.3-1 or figlet 2.2.5).

mode identifies which strict-compat target was active; detail is a short human-readable description of the unmappable construct (e.g., "TLF multicolor glyph not representable in toilet 16-color floor").

Raised by crate::strict_toilet::strict_render (gated by the toilet-strict-compat leaf) and by future figlet-2.2.5 strict invariants when no upstream byte-equal mapping exists for a given input. The variant is feature-gated free — it is always compiled so library callers can match on it regardless of which strict-compat leaf is enabled at build time (per FR-016 + AD-005).

Fields

mode: StrictTarget

Which strict-compat target was active when the violation occurred.

detail: String

Short description of the unmappable construct.

Internal(&'static str)

An internal invariant was violated. Indicates a bug in the library; please file an issue.

Trait Implementations

impl Debug for FigletError

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

Formats the value using the given formatter.

impl Display for FigletError

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

Formats the value using the given formatter.

impl Error for FigletError

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 FigletError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<StrictError> for FigletError

Available on crate feature strict-compat only.

fn from(err: StrictError) -> Self

Converts to this type from the input type.