Module error 

Error Handling

Structured error handling with diagnostics and source location tracking.

Overview

The error module provides error types and diagnostic types for actionable error reporting with source location tracking.

Key Types

• RenderError: Main error enum for rendering operations
• Diagnostic: Structured diagnostic information
• Location: Source file location (file, line, column)
• Severity: Error severity levels (Error, Warning, Note)
• RenderResult: Result type with artifacts and warnings

Error Hierarchy

RenderError Variants

• RenderError::EngineCreation: Failed to create rendering engine
• RenderError::InvalidFrontmatter: Malformed YAML frontmatter
• RenderError::TemplateFailed: Template rendering error
• RenderError::CompilationFailed: Backend compilation errors
• RenderError::FormatNotSupported: Requested format not supported
• RenderError::UnsupportedBackend: Backend not registered
• RenderError::DynamicAssetCollision: Asset filename collision
• RenderError::DynamicFontCollision: Font filename collision
• RenderError::InputTooLarge: Input size limits exceeded
• RenderError::YamlTooLarge: YAML size exceeded maximum
• RenderError::NestingTooDeep: Nesting depth exceeded maximum

Examples

Error Handling

use quillmark_core::{RenderError, error::print_errors};

match workflow.render(markdown, None) {
    Ok(result) => {
        // Process artifacts
        for artifact in result.artifacts {
            std::fs::write(
                format!("output.{:?}", artifact.output_format),
                &artifact.bytes
            )?;
        }
    }
    Err(e) => {
        // Print structured diagnostics
        print_errors(&e);
         
        // Match specific error types
        match e {
            RenderError::CompilationFailed { diags } => {
                eprintln!("Compilation failed with {} errors:", diags.len());
                for diag in diags {
                    eprintln!("{}", diag.fmt_pretty());
                }
            }
            RenderError::InvalidFrontmatter { diag } => {
                eprintln!("Frontmatter error: {}", diag.message);
            }
            _ => eprintln!("Error: {}", e),
        }
    }
}

Creating Diagnostics

use quillmark_core::{Diagnostic, Location, Severity};

let diag = Diagnostic::new(Severity::Error, "Undefined variable".to_string())
    .with_code("E001".to_string())
    .with_location(Location {
        file: "template.typ".to_string(),
        line: 10,
        col: 5,
    })
    .with_hint("Check variable spelling".to_string());

println!("{}", diag.fmt_pretty());

Example output:

[ERROR] Undefined variable (E001) at template.typ:10:5
  hint: Check variable spelling

Result with Warnings

let result = RenderResult::new(artifacts, OutputFormat::Pdf)
    .with_warning(Diagnostic::new(
        Severity::Warning,
        "Deprecated field used".to_string(),
    ));

Pretty Printing

The Diagnostic type provides Diagnostic::fmt_pretty() for human-readable output with error code, location, and hints.

Machine-Readable Output

All diagnostic types implement serde::Serialize for JSON export:

let json = serde_json::to_string(&diagnostic).unwrap();

Structs

Diagnostic

Structured diagnostic information

Location

Location information for diagnostics

RenderResult

Result type containing artifacts and warnings

SerializableDiagnostic

Serializable diagnostic for cross-language boundaries

Enums

ParseError

Error type for parsing operations

RenderError

Main error type for rendering operations

Severity

Error severity levels

Constants

MAX_CARD_COUNT

Maximum number of CARD blocks allowed per document Prevents memory exhaustion from documents with excessive card blocks

MAX_FIELD_COUNT

Maximum number of fields allowed per document Prevents memory exhaustion from documents with excessive fields

MAX_INPUT_SIZE

Maximum input size for markdown (10 MB)

MAX_NESTING_DEPTH

Maximum nesting depth for markdown structures (100 levels)

MAX_YAML_DEPTH

Maximum YAML nesting depth (100 levels) Prevents stack overflow from deeply nested YAML structures

MAX_YAML_SIZE

Maximum YAML size (1 MB)

Functions

print_errors

Helper to print structured errors