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
• crate::TemplateError: Template-specific errors
• 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::Internal: Internal error
• RenderError::Other: Other errors
• RenderError::Template: Template error

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(count, diags) => {
                eprintln!("Compilation failed with {} errors:", count);
                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)
    .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

Enums

ParseError

Error type for parsing operations

RenderError

Main error type for rendering operations

Severity

Error severity levels

Constants

MAX_INPUT_SIZE

Maximum input size for markdown (10 MB)

MAX_NESTING_DEPTH

Maximum nesting depth for markdown structures (100 levels)

MAX_TEMPLATE_OUTPUT

Maximum template output size (50 MB)

MAX_YAML_SIZE

Maximum YAML size (1 MB)

Functions

print_errors

Helper to print structured errors