Miette

https://github.com/zkat/miette
Admin
Miette is a fancy diagnostic reporting library and protocol for Rust, designed to help developers...
Tokens:109,059
Snippets:636
Trust Score:9.9
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Custom Highlighter Example

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/highlighters.md

Example implementation of a custom highlighter using the Highlighter and HighlighterState traits, and how to attach it to a GraphicalReportHandler.

```APIDOC
## Custom Highlighter Example

### Description
Shows how to implement a custom highlighter by defining a struct that implements Highlighter and HighlighterState, then attaching it to a GraphicalReportHandler.

### Code
```rust
use miette::highlighters::{Highlighter, HighlighterState};
use miette::{GraphicalReportHandler, SpanContents};
use owo_colors::{OwoColorize, Style};

struct UpperHighlighter;
struct UpperState;

impl Highlighter for UpperHighlighter {
    fn start_highlighter_state<'h>(
        &'h self,
        _source: &dyn SpanContents<'_>,
    ) -> Box<dyn HighlighterState + 'h> {
        Box::new(UpperState)
    }
}

impl HighlighterState for UpperState {
    fn highlight_line<'s>(&mut self, line: &'s str) -> Vec<owo_colors::Styled<&'s str>> {
        vec![Style::new().style(line)]  // no-op styling; real highlighters emit styled ranges
    }
}

let handler = GraphicalReportHandler::new()
    .with_syntax_highlighting(UpperHighlighter);
```
```

--------------------------------

### set_hook example with MietteHandlerOpts

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/report.md

Example of installing a custom `ReportHandler` via `miette::set_hook`. The closure configures `MietteHandlerOpts` with `terminal_links(true)`, `unicode(false)`, and `context_lines(3)`. The `?` operator propagates `InstallError` if a hook is already installed.

```rust
miette::set_hook(Box::new(|_| {
    Box::new(miette::MietteHandlerOpts::new()
        .terminal_links(true)
        .unicode(false)
        .context_lines(3)
        .build())
}))?;
# fn main() -> miette::Result<()> { Ok(()) }
```

--------------------------------

### ensure! usage example

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/macros.md

Shows how to use `ensure!` to return early with a warning if the divisor is too close to zero. The example imports `ensure`, `Result`, and `Severity` from `miette`.

```rust
use miette::{ensure, Result, Severity};

fn divide(x: f64, y: f64) -> Result<f64> {
    ensure!(
        y.abs() >= 1e-3,
        severity = Severity::Warning,
        "dividing by value ({y}) close to 0",
    );
    Ok(x / y)
}
```

--------------------------------

### Custom theme example

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/graphical-handler.md

Creates a custom theme using ASCII characters and ANSI styles, then constructs a graphical report handler with that theme. This example shows how to combine the theme components.

```rust
use miette::{GraphicalReportHandler, GraphicalTheme, ThemeCharacters, ThemeStyles};
use owo_colors::Style;

let theme = GraphicalTheme {
    characters: ThemeCharacters::ascii(),
    styles: ThemeStyles::ansi(),
};
let handler = GraphicalReportHandler::new_themed(theme);

```

--------------------------------

### Custom highlighter example

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/highlighters.md

Shows how to implement a custom highlighter by defining `Highlighter` and `HighlighterState` types. The example uses a no-op styling that returns the line unchanged; real highlighters emit styled ranges. The resulting handler is configured with `with_syntax_highlighting`.

```rust
use miette::highlighters::{Highlighter, HighlighterState};
use miette::{GraphicalReportHandler, SpanContents};
use owo_colors::{OwoColorize, Style};

struct UpperHighlighter;
struct UpperState;

impl Highlighter for UpperHighlighter {
    fn start_highlighter_state<'h>(
        &'h self,
        _source: &dyn SpanContents<'_>,
    ) -> Box<dyn HighlighterState + 'h> {
        Box::new(UpperState)
    }
}

impl HighlighterState for UpperState {
    fn highlight_line<'s>(&mut self, line: &'s str) -> Vec<owo_colors::Styled<&'s str>> {
        vec![Style::new().style(line)]  // no-op styling; real highlighters emit styled ranges
    }
}

let handler = GraphicalReportHandler::new()
    .with_syntax_highlighting(UpperHighlighter);
```

--------------------------------

### Install miette with cargo add

Source: https://github.com/zkat/miette/blob/main/README.md

Adds the miette crate as a dependency using Cargo. This is the basic installation command.

```sh
$ cargo add miette
```

--------------------------------

### Handle `miette::InstallError` when setting a hook

Source: https://github.com/zkat/miette/blob/main/_autodocs/errors.md

Use this to handle the case where `miette::set_hook` fails because a hook is already installed. The `Err` variant is `miette::InstallError`, which is returned when `OnceLock::set` fails. The example prints a message when the error occurs.

```rust
match miette::set_hook(Box::new(|_| Box::new(miette::MietteHandler::new()))) {
    Ok(()) => {}
    Err(miette::InstallError) => println!("hook already installed"),
}
```

--------------------------------

### set_hook

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/report.md

Installs the global ReportHandler factory. Fails with InstallError if a hook has already been installed.

```APIDOC
## set_hook

### Description
Installs the global `ReportHandler` factory. Fails with `InstallError` if a hook has already been installed (`OnceLock`).

### Signature
```rust
pub fn set_hook(hook: ErrorHook) -> Result<(), InstallError>
```

### Parameters
- **hook** (`ErrorHook`) - Required - The error hook to install.

### Returns
- `Result<(), InstallError>` - `Ok(())` on success, or `InstallError` if a hook is already installed.

### Example
```rust
miette::set_hook(Box::new(|_| {
    Box::new(miette::MietteHandlerOpts::new()
        .terminal_links(true)
        .unicode(false)
        .context_lines(3)
        .build())
}))?;
# fn main() -> miette::Result<()> { Ok(()) }
```
```

--------------------------------

### Example: global hook with MietteHandlerOpts

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/handler.md

Sets a global hook using MietteHandlerOpts with terminal_links, unicode, context_lines, tab_width, break_words, and color. The example includes a main function returning miette::Result.

```rust
miette::set_hook(Box::new(|_| {
    Box::new(
        miette::MietteHandlerOpts::new()
            .terminal_links(true)
            .unicode(false)
            .context_lines(3)
            .tab_width(4)
            .break_words(true)
            .color(true)
            .build(),
    )
}))?;
# fn main() -> miette::Result<()> { Ok(()) }
```

--------------------------------

### Using with_context as anyhow alias

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/traits.md

Example of using `with_context` as a drop-in alias for anyhow's `context` method. The example reads a binary file and attaches a context message.

```rust
use miette::{IntoDiagnostic, WrapErr};

let content = std::fs::read("data.bin")
    .into_diagnostic()
    .with_context(|| "reading data.bin".to_string())?;
# fn main() -> miette::Result<()> { let _ = content; Ok(()) }
```

--------------------------------

### LabeledSpan usage example

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/protocol.md

Example usage of LabeledSpan constructors. `at` creates a span with a label, and `at_offset` creates a zero-length span at a given offset; assertions verify equality, offset, and emptiness.

```rust
use miette::LabeledSpan;

let label = LabeledSpan::at(0..3, "should be Rust");
assert_eq!(LabeledSpan::new(Some("should be Rust".to_string()), 0, 3), label);

let ptr = LabeledSpan::at_offset(4, "expected a closing parenthesis");
assert_eq!(ptr.offset(), 4);
assert!(ptr.is_empty());
```

--------------------------------

### struct `SyntectHighlighter`

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/highlighters.md

Documentation for the SyntectHighlighter struct, including constructors, parameters, and usage example.

```APIDOC
## struct `SyntectHighlighter`

### Description
Highlights `SpanContents` using the syntect crate. Only 24-bit truecolor output is supported. It implements `Highlighter` and provides constructors for customization.

### Type
Rust struct

### Derives
- `Debug`
- `Clone`

### Fields
- `theme: syntect::Theme`
- `syntax_set: syntect::SyntaxSet`
- `use_bg_color: bool`

### Constructors

#### `default`
```rust
impl Default for SyntectHighlighter {
    fn default() -> Self {
        let theme_set = syntect::ThemeSet::load_defaults();
        let theme = theme_set.themes["base16-ocean.dark"].clone();
        Self::new_themed(theme, false)
    }
}
```

#### `new`
```rust
pub fn new(syntax_set: syntect::SyntaxSet, theme: syntect::Theme, use_bg_color: bool) -> Self
```

#### `new_themed`
```rust
pub fn new_themed(theme: syntect::Theme, use_bg_color: bool) -> Self
```

### Parameters
- `syntax_set` (syntect::SyntaxSet) - Required - The syntax set to use for highlighting.
- `theme` (syntect::Theme) - Required - The theme to apply.
- `use_bg_color` (bool) - Required - Whether to blend foreground alpha into the background.

### Syntax Detection Order
1. `SpanContents::language()` → `syntax_set.find_syntax_by_name(language)`
2. else `SpanContents::name()` file extension → `find_syntax_by_extension(ext)`
3. else first line of the data → `find_syntax_by_first_line(...)`

If nothing resolves, falls back to `BlankHighlighterState`.

### Example
```rust
# #[cfg(feature = "syntect-highlighter")]
# mod ex {
use miette::highlighters::SyntectHighlighter;
use miette::{GraphicalReportHandler, NamedSource};

let highlighter = SyntectHighlighter::default();
let handler = GraphicalReportHandler::new()
    .with_syntax_highlighting(highlighter);

// Language comes from NamedSource::with_language or the file name extension.
let _src = NamedSource::new("main.rs", "fn main() {}");
# }
```
```

--------------------------------

### Example: using GraphicalReportHandler

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/graphical-handler.md

Creates a themed handler with width 80, URLs enabled, and 2 context lines, then renders a diagnostic to a string and prints it.

```rust
use miette::{GraphicalReportHandler, GraphicalTheme, ReportHandler};

let handler = GraphicalReportHandler::new_themed(GraphicalTheme::unicode())
    .with_width(80)
    .with_urls(true)
    .with_context_lines(2);

let diag = miette::MietteDiagnostic::new("oops").with_code("my::err");
let mut out = String::new();
handler.debug(&diag, &mut out).unwrap();
print!("{out}");
```

--------------------------------

### SourceOffset and ByteOffset

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/protocol.md

Documentation for the `SourceOffset` and `ByteOffset` types, including their methods and usage examples.

```APIDOC
## SourceOffset and ByteOffset

### Description
`ByteOffset` is a type alias for `usize`. `SourceOffset` is a newtype wrapper around `ByteOffset` that provides methods to convert line/column locations to byte offsets.

### Type Alias
`pub type ByteOffset = usize;`

### Struct `SourceOffset`

#### Methods
- `pub const fn offset(&self) -> ByteOffset` - Returns the raw byte offset.
- `pub fn from_location(source: impl AsRef<str>, loc_line: usize, loc_col: usize) -> Self` - Converts 1-based line/column into a byte offset. **Infallible**: out-of-range locations return the offset of the last byte of the source. Line counting treats `\n` as line break (a lone `\r` is not a break; `\r\n` increments once via the `\n`).
- `#[track_caller] pub fn from_current_location() -> Result<(String, Self), MietteError>` - Returns `(file_name, offset)` of the caller's source location. Errors (`MietteError::IoError`) if the source file is unavailable at that path. Honor `#[track_caller]` chain to target a different caller.

#### From Implementation
`impl From<ByteOffset> for SourceOffset { ... }`

### Example
```rust
use miette::SourceOffset;

let off = SourceOffset::from_location("f\n\noo\r\nbar", 3, 3);
assert_eq!(off.offset(), 5);
// out-of-range → last byte
assert_eq!(SourceOffset::from_location("abc", 99, 99).offset(), 3);
```
```

--------------------------------

### Using SyntectHighlighter with GraphicalReportHandler

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/highlighters.md

Example of using SyntectHighlighter with GraphicalReportHandler. Requires the syntect-highlighter feature. Language is determined by NamedSource::with_language or the file name extension.

```rust
# #[cfg(feature = "syntect-highlighter")]
# mod ex {
use miette::highlighters::SyntectHighlighter;
use miette::{GraphicalReportHandler, NamedSource};

let highlighter = SyntectHighlighter::default();
let handler = GraphicalReportHandler::new()
    .with_syntax_highlighting(highlighter);

// Language comes from NamedSource::with_language or the file name extension.
let _src = NamedSource::new("main.rs", "fn main() {}");
# }
```

--------------------------------

### MietteDiagnostic with labels and Report

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/miette-diagnostic.md

Example showing how to add labels with and_label and convert the diagnostic into a Report with source code.

```rust
use miette::{Diagnostic, LabeledSpan, MietteDiagnostic, Report};

let diag = MietteDiagnostic::new("Wrong best language")
    .and_label(LabeledSpan::at_offset(3, "add 'l'"))
    .and_label(LabeledSpan::at_offset(6, "add 'r'"));

let report: Report = diag.into();
let report = report.with_source_code("helo wrld".to_string());
println!("{:?}", report);
```

--------------------------------

### miette! usage example with labels and help

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/macros.md

Constructs an ad-hoc `Report` with a label and help message, attaches a source string, and prints the report. Demonstrates the keyed-fields form of `miette!`.

```rust
use miette::{miette, LabeledSpan};

let source = "2 + 2 * 2 = 8".to_string();
let report = miette!(
    labels = vec![LabeledSpan::at(12..13, "this should be 6")],
    help = "'*' has greater precedence than '+'",
    "Wrong answer"
).with_source_code(source);
println!("{:?}", report);
```

--------------------------------

### set_hook function signature

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/report.md

Installs the global `ReportHandler` factory. Fails with `InstallError` if a hook has already been installed (`OnceLock`).

```rust
pub fn set_hook(hook: ErrorHook) -> Result<(), InstallError>
```

--------------------------------

### Using IntoDiagnostic to parse a version

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/traits.md

Example of using `into_diagnostic()` on a `Result` from `str::parse()` to convert it into a `miette::Result`. The example parses a semver version string and returns a `Result<Version>`.

```rust
use miette::{IntoDiagnostic, Result};
use semver::Version;

pub fn some_tool() -> Result<Version> {
    "1.2.x".parse().into_diagnostic()
}
```

--------------------------------

### Graphical Theme API

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/graphical-handler.md

Constructors and usage examples for the GraphicalTheme, ThemeStyles, and ThemeCharacters types.

```APIDOC
## `GraphicalTheme::ascii()`

### Description
Creates a `GraphicalTheme` with ASCII characters and ANSI styles.

### Method
`GraphicalTheme::ascii()`

### Parameters
None.

### Returns
`GraphicalTheme` - A theme with `ThemeCharacters::ascii()` and `ThemeStyles::ansi()`.

### Example
```rust
let theme = GraphicalTheme::ascii();
```
```

```APIDOC
## `GraphicalTheme::unicode()`

### Description
Creates a `GraphicalTheme` with Unicode characters and ANSI styles.

### Method
`GraphicalTheme::unicode()`

### Parameters
None.

### Returns
`GraphicalTheme` - A theme with `ThemeCharacters::unicode()` and `ThemeStyles::ansi()`.

### Example
```rust
let theme = GraphicalTheme::unicode();
```
```

```APIDOC
## `GraphicalTheme::unicode_nocolor()`

### Description
Creates a `GraphicalTheme` with Unicode characters and no colors.

### Method
`GraphicalTheme::unicode_nocolor()`

### Parameters
None.

### Returns
`GraphicalTheme` - A theme with `ThemeCharacters::unicode()` and `ThemeStyles::none()`.

### Example
```rust
let theme = GraphicalTheme::unicode_nocolor();
```
```

```APIDOC
## `GraphicalTheme::none()`

### Description
Creates a `GraphicalTheme` with ASCII characters and no colors.

### Method
`GraphicalTheme::none()`

### Parameters
None.

### Returns
`GraphicalTheme` - A theme with `ThemeCharacters::ascii()` and `ThemeStyles::none()`.

### Example
```rust
let theme = GraphicalTheme::none();
```
```

```APIDOC
## `Default for GraphicalTheme`

### Description
Provides a default theme based on the environment: if stdout or stderr is not a terminal, returns `none()`; else if `NO_COLOR` env var is set to a non-"0" value, returns `unicode_nocolor()`; otherwise returns `unicode()`.

### Method
`Default::default()`

### Parameters
None.

### Returns
`GraphicalTheme` - The default theme.

### Example
```rust
let theme = GraphicalTheme::default();
```
```

```APIDOC
## `ThemeStyles::rgb()`

### Description
Creates `ThemeStyles` with 24-bit colors: error `255,30,30`, warning `244,191,117`, advice `106,159,181`, link `92,157,255` underlined+bold, linum dimmed, highlights magenta/yellow/green.

### Method
`ThemeStyles::rgb()`

### Parameters
None.

### Returns
`ThemeStyles` - A styles object with RGB colors.

### Example
```rust
let styles = ThemeStyles::rgb();
```
```

```APIDOC
## `ThemeStyles::ansi()`

### Description
Creates `ThemeStyles` with ANSI colors: red/yellow/cyan/cyan-underlined-bold/dimmed/magenta-yellow-green bold.

### Method
`ThemeStyles::ansi()`

### Parameters
None.

### Returns
`ThemeStyles` - A styles object with ANSI colors.

### Example
```rust
let styles = ThemeStyles::ansi();
```
```

```APIDOC
## `ThemeStyles::none()`

### Description
Creates `ThemeStyles` with all styles unstyled and a single highlight style.

### Method
`ThemeStyles::none()`

### Parameters
None.

### Returns
`ThemeStyles` - A styles object with no colors.

### Example
```rust
let styles = ThemeStyles::none();
```
```

```APIDOC
## `ThemeCharacters::unicode()`

### Description
Creates `ThemeCharacters` with Unicode box-drawing characters and symbols: error `"×"`, warning `"⚠"`, advice `"☞"`.

### Method
`ThemeCharacters::unicode()`

### Parameters
None.

### Returns
`ThemeCharacters` - A characters object with Unicode symbols.

### Example
```rust
let chars = ThemeCharacters::unicode();
```
```

```APIDOC
## `ThemeCharacters::emoji()`

### Description
Creates `ThemeCharacters` with the same box characters as `unicode()` but with emoji symbols: error `"💥"`, warning `"⚠️"`, advice `"💡"`.

### Method
`ThemeCharacters::emoji()`

### Parameters
None.

### Returns
`ThemeCharacters` - A characters object with emoji symbols.

### Example
```rust
let chars = ThemeCharacters::emoji();
```
```

```APIDOC
## `ThemeCharacters::ascii()`

### Description
Creates `ThemeCharacters` with ASCII characters: error `"x"`, warning `"!"`, advice `">"`.

### Method
`ThemeCharacters::ascii()`

### Parameters
None.

### Returns
`ThemeCharacters` - A characters object with ASCII symbols.

### Example
```rust
let chars = ThemeCharacters::ascii();
```
```

```APIDOC
## Custom Theme Example

### Description
Shows how to construct a custom `GraphicalTheme` and use it with `GraphicalReportHandler::new_themed`.

### Example
```rust
use miette::{GraphicalReportHandler, GraphicalTheme, ThemeCharacters, ThemeStyles};
use owo_colors::Style;

let theme = GraphicalTheme {
    characters: ThemeCharacters::ascii(),
    styles: ThemeStyles::ansi(),
};
let handler = GraphicalReportHandler::new_themed(theme);
```
```

--------------------------------

### Create SourceSpan from tuple, range, or offset

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/protocol.md

Shows how to create a SourceSpan from a tuple, a range, or a single offset, and how to read its offset. The tuple form is (start, length); the range form is inclusive of the end; the offset-only form creates a zero-length span.

```rust
use miette::SourceSpan;

let span: SourceSpan = (9, 4).into();   // (offset, length)
let span2: SourceSpan = (7..11).into(); // range form
let point: SourceSpan = 4.into();       // offset only, len 0
assert_eq!(span.offset(), 9);
```

--------------------------------

### JSONReportHandler usage example

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/narratable-handler.md

Shows how to create a JSONReportHandler, create a MietteDiagnostic with code and help, and render it to a string. The output is a JSON object with fields like message, code, severity, causes, help, filename, labels, and related.

```rust
use miette::{JSONReportHandler, ReportHandler};

let handler = JSONReportHandler::new();
let diag = miette::MietteDiagnostic::new("bad thing")
    .with_code("my::bad")
    .with_help("do better");
let mut out = String::new();
handler.debug(&diag, &mut out).unwrap();
// {"message": "bad thing","code": "my::bad","severity": "error","causes": [],"help": "do better","filename": "","labels": [],"related": []}
println!("{out}");
```

--------------------------------

### Render diagnostic with MietteHandler

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/handler.md

Standalone example of rendering a diagnostic with `MietteHandler`. Requires importing `ReportHandler` to call the `debug` method. Creates a `MietteDiagnostic` with message "kaboom" and prints the rendered output.

```rust
use miette::{Diagnostic, MietteHandler, ReportHandler};
use std::fmt::Write;

let handler = MietteHandler::new();
let diag = miette::MietteDiagnostic::new("kaboom");
let mut out = String::new();
handler.debug(&diag, &mut out).unwrap();
println!("{out}");
```

--------------------------------

### Using WrapErr to read a config file

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/traits.md

Example of using `wrap_err_with` to attach a lazy error message when reading a file. The example uses `into_diagnostic()` to convert the `io::Error` and then wraps it with a formatted message.

```rust
use miette::{IntoDiagnostic, Result, WrapErr};
use std::fs;

pub fn read_config(path: &str) -> Result<String> {
    fs::read_to_string(path)
        .into_diagnostic()
        .wrap_err_with(|| format!("Failed to read config at {path}"))
}
```

--------------------------------

### Use the `diagnostic!` macro

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/macros.md

Example usage of the `diagnostic!` macro, showing how to set `severity`, `code`, `help`, `labels`, and `url` fields before the format literal. The macro returns a `MietteDiagnostic` value.

```rust
use miette::{diagnostic, LabeledSpan, Severity};

let diag = diagnostic!(
    severity = Severity::Warning,
    code = "expected::rparen",
    help = "always close your parens",
    labels = vec![LabeledSpan::at_offset(6, "here")],
    url = "https://example.com",
    "expected closing ')'",
);
```

--------------------------------

### Using with_source_code with a custom error

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/report.md

Shows how to use `with_source_code` with a custom error type that implements `Diagnostic` and provides a label. The example creates a `Report` from the error and attaches source code, then prints the report with `println!`.

```rust
use miette::{Diagnostic, Report, SourceSpan};
use thiserror::Error;

#[derive(Error, Debug)]
#[error("oops")]
struct MyError { #[label] err_span: SourceSpan }
impl Diagnostic for MyError {
    fn labels(&self) -> Option<Box<dyn Iterator<Item = miette::LabeledSpan> + '_>> {
        Some(Box::new(std::iter::once(miette::LabeledSpan::underline(self.err_span))))
    }
}

let report = Report::from(MyError { err_span: (7..11).into() })
    .with_source_code("source code".to_string());
println!("{:?}", report);
```

--------------------------------

### Install miette with fancy feature

Source: https://github.com/zkat/miette/blob/main/README.md

Adds the miette crate with the 'fancy' feature enabled, which is required for the fancy graphical diagnostic output shown in the documentation. This feature should only be enabled in the toplevel crate because it pulls in additional dependencies.

```sh
$ cargo add miette --features fancy
```

--------------------------------

### DebugReportHandler usage example

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/narratable-handler.md

Shows how to create a DebugReportHandler, create a MietteDiagnostic, and render it to a string using the debug method from the ReportHandler trait.

```rust
use miette::{DebugReportHandler, ReportHandler};

let handler = DebugReportHandler::new();
let diag = miette::MietteDiagnostic::new("plain");
let mut out = String::new();
handler.debug(&diag, &mut out).unwrap();
println!("{out}");
```

--------------------------------

### Custom ReportHandler implementation example

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/report.md

Shows a minimal custom ReportHandler that defers to Debug when alternate formatting is used, otherwise writes the error's Display output. This handler can be downcast at runtime via Report::handler.

```rust
use miette::{Diagnostic, ReportHandler};
use std::fmt;

pub struct Handler;

impl ReportHandler for Handler {
    fn debug(&self, error: &dyn Diagnostic, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if f.alternate() {
            return fmt::Debug::fmt(error, f);
        }
        write!(f, "{}", error)
    }
}
```

--------------------------------

### Create dynamic diagnostic with miette! macro

Source: https://github.com/zkat/miette/blob/main/README.md

Create a diagnostic on the fly using the `miette!` macro when you don't know all possible errors upfront or need to serialize/deserialize errors. The example attaches a label, help text, and source code to the diagnostic.

```rust
let source = "2 + 2 * 2 = 8".to_string();
let report = miette!(
  labels = vec![
      LabeledSpan::at(12..13, "this should be 6"),
  ],
  help = "'*' has greater precedence than '+'",
  "Wrong answer"
).with_source_code(source);
println!("{:?}", report)
```

--------------------------------

### Full application usage with miette::Result and WrapErr

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/report.md

Full application usage example showing how to use miette's IntoDiagnostic and WrapErr traits to add context to errors. The main function returns a miette::Result, and errors are printed via the default MietteHandler when the `fancy` feature is enabled.

```rust
use miette::{IntoDiagnostic, Result, WrapErr};

fn main() -> Result<()> {
    let config = std::fs::read_to_string("cluster.json")
        .into_diagnostic()
        .wrap_err("Failed to read config")?;
    println!("{}", config.len());
    Ok(())
}
// Errors print via the default MietteHandler (with the `fancy` feature).
```

--------------------------------

### Reading a span with context

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/named-source.md

Example of reading a span with context lines from a &str source. The span covers "bar" with one line of context on each side, and the returned contents include the context lines. The line and column are 0-indexed.

```rust
use miette::SourceCode;

let src = "xxx\nfoo\nbar\nbaz\n\nyyy\n";
let contents = src.read_span(&(8, 3).into(), 1, 1)?;   // span "bar" with 1 line each side
assert_eq!(
    std::str::from_utf8(contents.data())?,
    "foo\nbar\nbaz\n"
);
assert_eq!(contents.line(), 1);
assert_eq!(contents.column(), 0);
# fn main() -> miette::Result<()> { Ok(()) }
```

--------------------------------

### Use collection of SourceSpan for multiple labels

Source: https://github.com/zkat/miette/blob/main/README.md

Use a collection of SourceSpan (or types convertible into SourceSpan) for an unknown number of labels. Add the `collection` parameter to `label` and use an iterable type for the field. The example creates a `miette::Report` and prints it with source code.

```rust
#[derive(Debug, Diagnostic, Error)]
#[error("oops!")]
struct MyError {
    #[label("main issue")]
    primary_span: SourceSpan,

    #[label(collection, "related to this")]
    other_spans: Vec<Range<usize>>,
}

let report: miette::Report = MyError {
    primary_span: (6, 9).into(),
    other_spans: vec![19..26, 30..41],
}.into();

println!("{:?}", report.with_source_code("About something or another or yet another ...".to_string()));
```

--------------------------------

### Set up and test the project

Source: https://github.com/zkat/miette/blob/main/CONTRIBUTING.md

Commands to set up the project locally and run tests with the 'fancy' feature. The 'fancy' feature is required for one of the doc-tests to pass.

```bash
cd path/to/your/clone
```

```bash
cargo test --features fancy
```

--------------------------------

### Catching MietteError from read_span

Source: https://github.com/zkat/miette/blob/main/_autodocs/errors.md

Shows how to catch MietteError variants when calling read_span on a SourceCode. The example uses a span starting at offset 10 with length 2 on the string "abc", which is out of bounds.

```rust
use miette::{MietteError, SourceCode};

match "abc".read_span(&(10, 2).into(), 0, 0) {
    Err(MietteError::OutOfBounds) => {}   // span outside source
    Err(MietteError::IoError(e)) => {}    // io failure
    Ok(_) => {}
}
```

--------------------------------

### InstallError struct

Source: https://github.com/zkat/miette/blob/main/_autodocs/types.md

Unit struct used as an error when installing a hook fails. Its Display message is "cannot install provided ErrorHook, a hook has already been installed". Implements Diagnostic and std::error::Error.

```rust
pub struct InstallError;
```

--------------------------------

### NarratableReportHandler usage example

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/narratable-handler.md

Example usage of NarratableReportHandler with context lines disabled, rendering a diagnostic to a string.

```rust
use miette::{Diagnostic, NarratableReportHandler, ReportHandler};

let handler = NarratableReportHandler::new().with_context_lines(0);
let diag = miette::MietteDiagnostic::new("kaboom").with_code("my::err");
let mut out = String::new();
handler.debug(&diag, &mut out).unwrap();
println!("{out}");
```

--------------------------------

### Example: downcast_ref to handle io::Error

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/report.md

Example usage of `downcast_ref` to check for a specific error type and print a message accordingly.

```rust
use miette::Report;

fn handle(err: Report) {
    if let Some(e) = err.downcast_ref::<std::io::Error>() {
        println!("io error: {e}");
    } else {
        println!("other: {err:#?}");
    }
}
```

--------------------------------

### SyntectHighlighter constructors

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/highlighters.md

Constructors for SyntectHighlighter. Default uses theme base16-ocean.dark and use_bg_color = false. new provides full customization, new_themed uses SyntaxSet::load_defaults_nonewlines().

```rust
impl Default for SyntectHighlighter {
    fn default() -> Self {
        let theme_set = syntect::ThemeSet::load_defaults();
        let theme = theme_set.themes["base16-ocean.dark"].clone();
        Self::new_themed(theme, false)
    }
}

pub fn new(syntax_set: syntect::SyntaxSet, theme: syntect::Theme, use_bg_color: bool) -> Self
pub fn new_themed(theme: syntect::Theme, use_bg_color: bool) -> Self
```

--------------------------------

### Example: find underlying io::ErrorKind via chain

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/report.md

Example function that iterates over the cause chain and returns the `ErrorKind` of the first `std::io::Error` found, or `None` if none exists.

```rust
pub fn underlying_io_error_kind(error: &Report) -> Option<std::io::ErrorKind> {
    for cause in error.chain() {
        if let Some(io_error) = cause.downcast_ref::<std::io::Error>() {
            return Some(io_error.kind());
        }
    }
    None
}
```

--------------------------------

### SourceSpan

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/protocol.md

Documentation for the `SourceSpan` struct, including its constructor, methods, and From conversions.

```APIDOC
## SourceSpan

### Description
Represents a byte-offset and length into a `SourceCode`. It is used to identify a region of source text.

### Constructor
`pub const fn new(start: SourceOffset, length: usize) -> Self`

### Methods
- `pub const fn offset(&self) -> usize` - Returns the starting byte offset.
- `pub const fn len(&self) -> usize` - Returns the length of the span.
- `pub const fn is_empty(&self) -> bool` - Returns `true` if the span has zero length.

### From Conversions
| From | To | Notes |
|------|----|----|
| `(ByteOffset, usize)` | `SourceSpan` | `(start, len)` tuple |
| `(SourceOffset, usize)` | `SourceSpan` | |
| `std::ops::Range<ByteOffset>` | `SourceSpan` | |
| `std::ops::RangeInclusive<ByteOffset>` | `SourceSpan` | **Panics** if length overflows `usize` (`0..=usize::MAX` only) |
| `SourceOffset` | `SourceSpan` | zero-length span |
| `ByteOffset` | `SourceSpan` | zero-length span |

### Example
```rust
use miette::SourceSpan;

let span: SourceSpan = (9, 4).into();   // (offset, length)
let span2: SourceSpan = (7..11).into(); // range form
let point: SourceSpan = 4.into();       // offset only, len 0
assert_eq!(span.offset(), 9);
```
```

--------------------------------

### SourceCode read_span example

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/protocol.md

Example usage of SourceCode::read_span on a String. Reads the span (4,4) with one line of context before and after, asserting the line number and data. The trailing main function is a hidden line for doctest.

```rust
use miette::SourceCode;

let src = "foo\nbar\nbaz\n".to_string();
let contents = src.read_span(&(4, 4).into(), 1, 1)?; // reads "bar" with context
assert_eq!(contents.line(), 1);      // 0-indexed
assert_eq!(std::str::from_utf8(contents.data())?, "bar\n");
# fn main() -> miette::Result<()> { Ok(()) }
```

--------------------------------

### LabeledSpan::len

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/protocol.md

Method to get the byte length of the span.

```APIDOC
## `LabeledSpan::len`

### Description
Returns the byte length of the span.

### Signature
```rust
pub const fn len(&self) -> usize
```

### Returns
- `usize` - The byte length.

```

--------------------------------

### Provide help text programmatically with #[help] field

Source: https://github.com/zkat/miette/blob/main/README.md

Supplies help text programmatically by defining a field annotated with `#[help]`. The field can be `Option<String>` or `String`, and the value is set when constructing the error.

```rust
use miette::Diagnostic;
use thiserror::Error;

#[derive(Debug, Diagnostic, Error)]
#[error("welp")]
#[diagnostic()]
struct Foo {
    #[help]
    advice: Option<String>, // Can also just be `String`
}

let err = Foo {
    advice: Some("try doing this instead".to_string()),
};
```

--------------------------------

### MietteHandlerOpts

Source: https://github.com/zkat/miette/blob/main/_autodocs/configuration.md

Complete builder API for MietteHandlerOpts, listing all configuration methods, their option keys, types, defaults, and descriptions.

```APIDOC
## MietteHandlerOpts

### Description
Builder for configuring a `MietteHandler` that renders miette diagnostics. All builder methods consume `self` and return `Self`; unset options auto-detect from the environment.

### Methods

#### `new()`
- **Signature**: `pub fn new() -> Self`
- **Description**: Creates an empty builder (same as `Default`).

#### `terminal_links(bool)`
- **Signature**: `pub fn terminal_links(self, value: bool) -> Self`
- **Option key**: `linkify`
- **Type**: `Option<bool>`
- **Default**: auto-detect via `supports_hyperlinks`
- **Description**: Makes codes clickable links in supported terminals.

#### `graphical_theme(GraphicalTheme)`
- **Signature**: `pub fn graphical_theme(self, theme: GraphicalTheme) -> Self`
- **Option key**: `theme`
- **Type**: `Option<GraphicalTheme>`
- **Default**: `GraphicalTheme { characters, styles }` resolved from unicode/color support
- **Description**: Overrides the default theme; overrides `color()`.

#### `with_syntax_highlighting(impl Highlighter)`
- **Signature**: `pub fn with_syntax_highlighting(self, highlighter: impl Highlighter) -> Self`
- **Option key**: `highlighter`
- **Type**: `Option<MietteHighlighter>`
- **Default**: syntect (if feature) else disabled
- **Description**: Sets a custom syntax highlighter; takes precedence over `rgb_colors`.

#### `without_syntax_highlighting()`
- **Signature**: `pub fn without_syntax_highlighting(self) -> Self`
- **Option key**: `highlighter`
- **Type**: —
- **Default**: —
- **Description**: Force-disables syntax highlighting.

#### `width(usize)`
- **Signature**: `pub fn width(self, width: usize) -> Self`
- **Option key**: `width`
- **Type**: `Option<usize>`
- **Default**: `terminal_size()` width, `None`→80
- **Description**: Sets the wrap width.

#### `wrap_lines(bool)`
- **Signature**: `pub fn wrap_lines(self, value: bool) -> Self`
- **Option key**: `wrap_lines`
- **Type**: `Option<bool>`
- **Default**: `true`
- **Description**: Wraps long lines.

#### `break_words(bool)`
- **Signature**: `pub fn break_words(self, value: bool) -> Self`
- **Option key**: `break_words`
- **Type**: `Option<bool>`
- **Default**: `true`
- **Description**: Breaks long words when wrapping.

#### `word_separator(textwrap::WordSeparator)`
- **Signature**: `pub fn word_separator(self, separator: textwrap::WordSeparator) -> Self`
- **Option key**: `word_separator`
- **Type**: `Option<...>`
- **Default**: textwrap default
- **Description**: Sets the wrap-point separator.

#### `word_splitter(textwrap::WordSplitter)`
- **Signature**: `pub fn word_splitter(self, splitter: textwrap::WordSplitter) -> Self`
- **Option key**: `word_splitter`
- **Type**: `Option<...>`
- **Default**: textwrap default
- **Description**: Sets the wrap-point splitter.

#### `with_cause_chain()`
- **Signature**: `pub fn with_cause_chain(self) -> Self`
- **Option key**: `with_cause_chain`
- **Type**: `Option<bool>` → `true`
- **Default**: `true`
- **Description**: Prints the cause chain.

#### `without_cause_chain()`
- **Signature**: `pub fn without_cause_chain(self) -> Self`
- **Option key**: `with_cause_chain`
- **Type**: `Option<bool>` → `false`
- **Default**: `true`
- **Description**: Omits the cause chain.

#### `show_related_errors_as_siblings()`
- **Signature**: `pub fn show_related_errors_as_siblings(self) -> Self`
- **Option key**: `show_related_as_nested`
- **Type**: `false`
- **Default**: `false`
- **Description**: Shows related errors as siblings.

#### `show_related_errors_as_nested()`
- **Signature**: `pub fn show_related_errors_as_nested(self) -> Self`
- **Option key**: `show_related_as_nested`
- **Type**: `true`
- **Default**: `false`
- **Description**: Shows related errors nested.

#### `color(bool)`
- **Signature**: `pub fn color(self, value: bool) -> Self`
- **Option key**: `color`
- **Type**: `Option<bool>`
- **Default**: auto (`supports_color::on(Stderr)`)
- **Description**: Forces or disables colors.

#### `rgb_colors(RgbColors)`
- **Signature**: `pub fn rgb_colors(self, colors: RgbColors) -> Self`
- **Option key**: `rgb_colors` (non-`Option`)
- **Type**: `RgbColors`
- **Default**: `RgbColors::Never`
- **Description**: Sets ANSI vs 24-bit color format; ignored when a highlighter is active.

#### `unicode(bool)`
- **Signature**: `pub fn unicode(self, value: bool) -> Self`
- **Option key**: `unicode`
- **Type**: `Option<bool>`
- **Default**: auto (`supports_unicode`)
- **Description**: Uses Unicode vs ASCII drawing characters.

#### `force_graphical(bool)`
- **Signature**: `pub fn force_graphical(self, value: bool) -> Self`
- **Option key**: `force_graphical`
- **Type**: `Option<bool>`
- **Default**: auto (`true` unless `NO_GRAPHICS` non-`"0"`)
- **Description**: Forces graphical rendering.

#### `force_narrated(bool)`
- **Signature**: `pub fn force_narrated(self, value: bool) -> Self`
- **Option key**: `force_narrated`
- **Type**: `Option<bool>`
- **Default**: `false`
- **Description**: Forces narrated rendering (wins over `force_graphical`).

#### `footer(String)`
- **Signature**: `pub fn footer(self, footer: String) -> Self`
- **Option key**: `footer`
- **Type**: `Option<String>`
- **Default**: `None`
- **Description**: Sets footer text.

#### `context_lines(usize)`
- **Signature**: `pub fn context_lines(self, lines: usize) -> Self`
- **Option key**: `context_lines`
- **Type**: `Option<usize>`
- **Default**: passed to handler: graphical/narratable default `1`
- **Description**: Sets context lines per span.

#### `tab_width(usize)`
- **Signature**: `pub fn tab_width(self, width: usize) -> Self`
- **Option key**: `tab_width`
- **Type**: `Option<usize>`
- **Default**: graphical default `4`
- **Description**: Sets tab width in spaces.

#### `build()`
- **Signature**: `pub fn build(self) -> MietteHandler`
- **Description**: Produces a `MietteHandler` (narratable if `!is_graphical()`, else themed `GraphicalReportHandler`).

### Resolution Order for `is_graphical()`
1. `force_narrated` → `!force_narrated`
2. else `force_graphical`
3. else `NO_GRAPHICS` env == `"0"`
4. else `true`
```

--------------------------------

### LabeledSpan::offset

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/protocol.md

Method to get the byte offset of the span.

```APIDOC
## `LabeledSpan::offset`

### Description
Returns the 0-based byte offset of the span.

### Signature
```rust
pub const fn offset(&self) -> usize
```

### Returns
- `usize` - The byte offset.

```

--------------------------------

### LabeledSpan::inner

Source: https://github.com/zkat/miette/blob/main/_autodocs/api-reference/protocol.md

Method to get a reference to the inner SourceSpan.

```APIDOC
## `LabeledSpan::inner`

### Description
Returns a reference to the inner source span.

### Signature
```rust
pub const fn inner(&self) -> &SourceSpan
```

### Returns
- `&SourceSpan` - A reference to the inner span.

```
Tokens:
Raw