Miette

https://docs.rs/miette/latest/
Admin
Miette is a diagnostic library for Rust that provides customizable error reporting with fancy...
Tokens:227,080
Snippets:1,887
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Create SyntectHighlighter with Default SyntaxSet

Source: https://docs.rs/miette/latest/miette/highlighters/struct.SyntectHighlighter.html

Initialize a SyntectHighlighter using the default SyntaxSet and a specified Theme. This is a convenient way to get started with highlighting.

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

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

### Example: Reading and Deserializing Configuration

Source: https://docs.rs/miette/latest/miette/type.Result.html

This example shows a typical use case for `miette::Result` in a `main` function, involving reading a configuration file and deserializing its content using `serde_json`. The `?` operator propagates errors.

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

fn main() -> Result<()> {
    let config = std::fs::read_to_string("cluster.json").into_diagnostic()?;
    let map: ClusterMap = serde_json::from_str(&config).into_diagnostic()?;
    println!("cluster info: {:#?}", map);
    Ok(())
}
```

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

### SourceSpan::new

Source: https://docs.rs/miette/latest/miette/struct.SourceSpan.html

Creates a new SourceSpan with a given start offset and length.

```APIDOC
## SourceSpan::new

### Description
Creates a new `SourceSpan`.

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

### Parameters
* `start`: The starting offset of the span.
* `length`: The length of the span in bytes.
```

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

### Example Usage of miette::Result

Source: https://docs.rs/miette/latest/miette/type.Result.html

An example demonstrating how to use `miette::Result` in a `main` function for handling file reading and JSON parsing errors.

```APIDOC
## Example

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

fn main() -> Result<()> {
    let config = std::fs::read_to_string("cluster.json").into_diagnostic()?;
    let map: ClusterMap = serde_json::from_str(&config).into_diagnostic()?;
    println!("cluster info: {:#?}", map);
    Ok(())
}
```
```

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

### Box::from_non_null Example (Nightly)

Source: https://docs.rs/miette/latest/miette/type.ErrorHook.html

Shows how to construct a Box from a NonNull pointer. This is an experimental API and requires the nightly toolchain.

```rust
#![feature(box_vec_non_null)]

let x = Box::new(5);
let non_null = Box::into_non_null(x);
let x = unsafe { Box::from_non_null(non_null) };
```

```rust
#![feature(box_vec_non_null)]

use std::alloc::{alloc, Layout};
use std::ptr::NonNull;

unsafe {
    let non_null = NonNull::new(alloc(Layout::new::<i32>()).cast::<i32>())
        .expect("allocation failed");
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `non_null`.
    non_null.write(5);
    let x = Box::from_non_null(non_null);
}
```

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

### Box::from_raw Example

Source: https://docs.rs/miette/latest/miette/type.ErrorHook.html

Demonstrates recreating a Box from a raw pointer. This is useful when managing memory manually or when interacting with FFI.

```rust
let x = Box::new(5);
let ptr = Box::into_raw(x);
let x = unsafe { Box::from_raw(ptr) };
```

```rust
use std::alloc::{alloc, Layout};

unsafe {
    let ptr = alloc(Layout::new::<i32>()) as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw(ptr);
}
```

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

### Start Syntect Highlighter State

Source: https://docs.rs/miette/latest/src/miette/highlighters/syntect.rs.html

Initializes and returns a new `SyntectHighlighterState` for processing lines of code. It attempts to detect the syntax for the given source content.

```rust
fn start_highlighter_state<'h>(
    &'h self,
    source: &dyn SpanContents<'_>,
) -> Box<dyn HighlighterState + 'h> {
    if let Some(syntax) = self.detect_syntax(source) {
        let highlighter = syntect::Highlighter::new(&self.theme);
        let parse_state = syntect::ParseState::new(syntax);
        let highlight_state =
            syntect::HighlightState::new(&highlighter, syntect::ScopeStack::new());
        Box::new(SyntectHighlighterState {
            syntax_set: &self.syntax_set,
            highlighter,
            parse_state,
            highlight_state,
            use_bg_color: self.use_bg_color,
        })
    } else {
        Box::new(BlankHighlighterState)
    }
}
```

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

### Start Highlighter State for SyntectHighlighter

Source: https://docs.rs/miette/latest/miette/highlighters/struct.SyntectHighlighter.html

Creates a new HighlighterState to begin parsing and highlighting SpanContents. This is the entry point for the highlighting process.

```rust
fn start_highlighter_state<'h>( &'h self, source: &dyn SpanContents<'_>, ) -> Box<dyn HighlighterState + 'h>
```

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

### Box::into_raw Example

Source: https://docs.rs/miette/latest/miette/type.ErrorHook.html

Demonstrates consuming a Box to obtain a raw pointer. The caller becomes responsible for memory management, typically by converting it back to a Box.

```rust
let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
let x = unsafe { Box::from_raw(ptr) };
```

```rust
use std::alloc::{dealloc, Layout};
use std::ptr;

let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
unsafe {
    ptr::drop_in_place(ptr);
    dealloc(ptr as *mut u8, Layout::new::<String>());
}
```

```rust
let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
unsafe {
    drop(Box::from_raw(ptr));
}
```

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

### Error Reporting Example

Source: https://docs.rs/miette/latest/miette/trait.Context.html

Illustrates how errors with context are displayed, showing the outermost error first followed by underlying causes.

```text
Error: Failed to read instrs from ./path/to/instrs.json

Caused by:
    No such file or directory (os error 2)
```

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

### Create Default GraphicalReportHandler

Source: https://docs.rs/miette/latest/src/miette/handlers/graphical.rs.html

Instantiates a new GraphicalReportHandler with the default theme, unicode characters, and colors. This is the standard way to get the default reporter.

```rust
pub fn new() -> Self {
        Self {
            links: LinkStyle::Link,
            termwidth: 200,
            theme: GraphicalTheme::default(),
            footer: None,
            context_lines: 1,
            tab_width: 4,
            with_cause_chain: true,
            wrap_lines: true,
            break_words: true,
            with_primary_span_start: true,
            word_separator: None,
            word_splitter: None,
            highlighter: MietteHighlighter::default(),
            link_display_text: None,
            show_related_as_nested: false,
        }
    }
```

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

### Get Span Offset

Source: https://docs.rs/miette/latest/src/miette/handlers/graphical.rs.html

Returns the starting offset of the associated span within the source text. This is a zero-based index.

```rust
fn offset(&self) -> usize {
        self.span.offset()
    }
```

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

### Create SyntectHighlighter with SyntaxSet and Theme

Source: https://docs.rs/miette/latest/miette/highlighters/struct.SyntectHighlighter.html

Initialize a SyntectHighlighter with a specific SyntaxSet and Theme. This allows for custom highlighting configurations.

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

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

### unsafe unwrap_err_unchecked Example

Source: https://docs.rs/miette/latest/miette/type.Result.html

Demonstrates using unwrap_err_unchecked to get the Err value without checking if it's an Ok. This is unsafe and calling it on an Ok is undefined behavior.

```rust
let x: Result<u32, &str> = Ok(2);
unsafe { x.unwrap_err_unchecked() }; // Undefined behavior!
```

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

### Initialize SyntectHighlighter with Default Theme

Source: https://docs.rs/miette/latest/src/miette/highlighters/syntect.rs.html

Creates a SyntectHighlighter using the default theme and syntax set. Use this for general-purpose highlighting.

```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)
    }
}
```

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

### Create SyntectHighlighter with Custom Theme

Source: https://docs.rs/miette/latest/src/miette/highlighters/syntect.rs.html

Initializes a SyntectHighlighter with a specific theme and the default syntax set. Useful when a particular color scheme is desired.

```rust
pub fn new_themed(theme: syntect::Theme, use_bg_color: bool) -> Self {
    Self::new(
        syntect::SyntaxSet::load_defaults_nonewlines(),
        theme,
        use_bg_color,
    )
}
```

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

### unsafe unwrap_unchecked Example

Source: https://docs.rs/miette/latest/miette/type.Result.html

Shows how to use unwrap_unchecked to get the Ok value without checking if it's an Err. This is unsafe and calling it on an Err is undefined behavior.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(unsafe { x.unwrap_unchecked() }, 2);
```

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

### SyntectHighlighter::new

Source: https://docs.rs/miette/latest/miette/highlighters/struct.SyntectHighlighter.html

Creates a new SyntectHighlighter with a specified syntax set, theme, and background color option.

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

### Description
Create a syntect highlighter with the given theme and syntax set.

### Parameters
- `syntax_set`: The `SyntaxSet` to use for parsing code.
- `theme`: The `Theme` to use for styling the highlighted code.
- `use_bg_color`: A boolean indicating whether to include background colors in the highlighting.
```

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

### Enable Primary Span Start in GraphicalReportHandler

Source: https://docs.rs/miette/latest/src/miette/handlers/graphical.rs.html

Enables the display of the line and column number for the start of the primary span, particularly when the snippet spans multiple lines. This aids in pinpointing the exact start of the issue.

```rust
pub fn with_primary_span_start(mut self) -> Self {
        self.with_primary_span_start = true;
        self
    }
```

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

### FromIterator Example: Collection with Underflow Error

Source: https://docs.rs/miette/latest/miette/type.Result.html

Demonstrates how FromIterator stops processing and returns the first Err encountered. This example shows an underflow error during subtraction.

```rust
let v = vec![1, 2, 0];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| 
    x.checked_sub(1).ok_or("Underflow!")
).collect();
assert_eq!(res, Err("Underflow!"));
```

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

### Get Ok Value or Default with `unwrap_or`

Source: https://docs.rs/miette/latest/miette/type.Result.html

Use `unwrap_or` to get the `Ok` value or a provided default if the `Result` is `Err`. The default value is eagerly evaluated.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

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

### SyntectHighlighter::new_themed

Source: https://docs.rs/miette/latest/miette/highlighters/struct.SyntectHighlighter.html

Creates a new SyntectHighlighter with a specified theme and the default syntax set.

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

### Description
Create a syntect highlighter with the given theme and the default syntax set.

### Parameters
- `theme`: The `Theme` to use for styling the highlighted code.
- `use_bg_color`: A boolean indicating whether to include background colors in the highlighting.
```

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

### Get Ok Value or Compute with `unwrap_or_else`

Source: https://docs.rs/miette/latest/miette/type.Result.html

Use `unwrap_or_else` to get the `Ok` value or compute a default from a closure if the `Result` is `Err`. This is useful for lazily evaluated defaults.

```rust
fn op(x: u32) -> u32 { x * 2 }
let x: Result<u32, u32> = Ok(9);
assert_eq!(x.unwrap_or_else(op), 9);

let x: Result<u32, u32> = Err(5);
assert_eq!(x.unwrap_or_else(op), 10);
```

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

### FromIterator Example: Early Termination

Source: https://docs.rs/miette/latest/miette/type.Result.html

Illustrates that FromIterator halts iteration upon encountering an Err. This example shows that a shared counter is not updated with values from elements after the first Err.

```rust
let v = vec![3, 2, 1, 10];
let mut shared = 0;
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {
    shared += x;
    x.checked_sub(2).ok_or("Underflow!")
}).collect();
assert_eq!(res, Err("Underflow!"));
assert_eq!(shared, 6);
```

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

### Disable Primary Span Start in GraphicalReportHandler

Source: https://docs.rs/miette/latest/src/miette/handlers/graphical.rs.html

Disables the display of the line and column number for the start of the primary span when the snippet extends multiple lines. This can simplify the output when such detail is not needed.

```rust
pub fn without_primary_span_start(mut self) -> Self {
        self.with_primary_span_start = false;
        self
    }
```

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

### OwoColorize Methods

Source: https://docs.rs/miette/latest/miette/struct.Report.html

Provides methods for setting foreground and background colors for display.

```APIDOC
## fg<C>(&self) -> FgColorDisplay<'_, C, Self>

### Description
Set the foreground color generically.

### Method
`fg`

### Parameters
- `C`: A generic type representing the color.

### Returns
`FgColorDisplay<'_, C, Self>`: A display struct for foreground color.

## bg<C>(&self) -> BgColorDisplay<'_, C, Self>

### Description
Set the background color generically.

### Method
`bg`

### Parameters
- `C`: A generic type representing the color.

### Returns
`BgColorDisplay<'_, C, Self>`: A display struct for background color.

## black(&self) -> FgColorDisplay<'_, Black, Self>

### Description
Change the foreground color to black.

### Method
`black`

### Returns
`FgColorDisplay<'_, Black, Self>`

## on_black(&self) -> BgColorDisplay<'_, Black, Self>

### Description
Change the background color to black.

### Method
`on_black`

### Returns
`BgColorDisplay<'_, Black, Self>`

## red(&self) -> FgColorDisplay<'_, Red, Self>

### Description
Change the foreground color to red.

### Method
`red`

### Returns
`FgColorDisplay<'_, Red, Self>`

## on_red(&self) -> BgColorDisplay<'_, Red, Self>

### Description
Change the background color to red.

### Method
`on_red`

### Returns
`BgColorDisplay<'_, Red, Self>`

## green(&self) -> FgColorDisplay<'_, Green, Self>

### Description
Change the foreground color to green.

### Method
`green`

### Returns
`FgColorDisplay<'_, Green, Self>`

## on_green(&self) -> BgColorDisplay<'_, Green, Self>

### Description
Change the background color to green.

### Method
`on_green`

### Returns
`BgColorDisplay<'_, Green, Self>`

## yellow(&self) -> FgColorDisplay<'_, Yellow, Self>

### Description
Change the foreground color to yellow.

### Method
`yellow`

### Returns
`FgColorDisplay<'_, Yellow, Self>`

## on_yellow(&self) -> BgColorDisplay<'_, Yellow, Self>

### Description
Change the background color to yellow.

### Method
`on_yellow`

### Returns
`BgColorDisplay<'_, Yellow, Self>`

## blue(&self) -> FgColorDisplay<'_, Blue, Self>

### Description
Change the foreground color to blue.

### Method
`blue`

### Returns
`FgColorDisplay<'_, Blue, Self>`

## on_blue(&self) -> BgColorDisplay<'_, Blue, Self>

### Description
Change the background color to blue.

### Method
`on_blue`

### Returns
`BgColorDisplay<'_, Blue, Self>`

## magenta(&self) -> FgColorDisplay<'_, Magenta, Self>

### Description
Change the foreground color to magenta.

### Method
`magenta`

### Returns
`FgColorDisplay<'_, Magenta, Self>`

## on_magenta(&self) -> BgColorDisplay<'_, Magenta, Self>

### Description
Change the background color to magenta.

### Method
`on_magenta`

### Returns
`BgColorDisplay<'_, Magenta, Self>`

## purple(&self) -> FgColorDisplay<'_, Magenta, Self>

### Description
Change the foreground color to purple.

### Method
`purple`

### Returns
`FgColorDisplay<'_, Magenta, Self>`

## on_purple(&self) -> BgColorDisplay<'_, Magenta, Self>

### Description
Change the background color to purple.

### Method
`on_purple`

### Returns
`BgColorDisplay<'_, Magenta, Self>`

## cyan(&self) -> FgColorDisplay<'_, Cyan, Self>

### Description
Change the foreground color to cyan.

### Method
`cyan`

### Returns
`FgColorDisplay<'_, Cyan, Self>`

## on_cyan(&self) -> BgColorDisplay<'_, Cyan, Self>

### Description
Change the background color to cyan.

### Method
`on_cyan`

### Returns
`BgColorDisplay<'_, Cyan, Self>`

## white(&self) -> FgColorDisplay<'_, White, Self>

### Description
Change the foreground color to white.

### Method
`white`

### Returns
`FgColorDisplay<'_, White, Self>`

## on_white(&self) -> BgColorDisplay<'_, White, Self>

### Description
Change the background color to white.

### Method
`on_white`

### Returns
`BgColorDisplay<'_, White, Self>`

## default_color(&self) -> FgColorDisplay<'_, Default, Self>

### Description
Change the foreground color to the terminal default.

### Method
`default_color`

### Returns
`FgColorDisplay<'_, Default, Self>`

## on_default_color(&self) -> BgColorDisplay<'_, Default, Self>

### Description
Change the background color to the terminal default.

### Method
`on_default_color`

### Returns
`BgColorDisplay<'_, Default, Self>`

## bright_black(&self) -> FgColorDisplay<'_, BrightBlack, Self>

### Description
Change the foreground color to bright black.

### Method
`bright_black`

### Returns
`FgColorDisplay<'_, BrightBlack, Self>`

## on_bright_black(&self) -> BgColorDisplay<'_, BrightBlack, Self>

### Description
Change the background color to bright black.

### Method
`on_bright_black`

### Returns
`BgColorDisplay<'_, BrightBlack, Self>`

## bright_red(&self) -> FgColorDisplay<'_, BrightRed, Self>

### Description
Change the foreground color to bright red.

### Method
`bright_red`

### Returns
`FgColorDisplay<'_, BrightRed, Self>`

## on_bright_red(&self) -> BgColorDisplay<'_, BrightRed, Self>

### Description
Change the background color to bright red.

### Method
`on_bright_red`

### Returns
`BgColorDisplay<'_, BrightRed, Self>`

## bright_green(&self) -> FgColorDisplay<'_, BrightGreen, Self>

### Description
Change the foreground color to bright green.

### Method
`bright_green`

### Returns
`FgColorDisplay<'_, BrightGreen, Self>`

## on_bright_green(&self) -> BgColorDisplay<'_, BrightGreen, Self>

### Description
Change the background color to bright green.

### Method
`on_bright_green`

### Returns
`BgColorDisplay<'_, BrightGreen, Self>`

## bright_yellow(&self) -> FgColorDisplay<'_, BrightYellow, Self>

### Description
Change the foreground color to bright yellow.

### Method
`bright_yellow`

### Returns
`FgColorDisplay<'_, BrightYellow, Self>`

## on_bright_yellow(&self) -> BgColorDisplay<'_, BrightYellow, Self>

### Description
Change the background color to bright yellow.

### Method
`on_bright_yellow`

### Returns
`BgColorDisplay<'_, BrightYellow, Self>`

## bright_blue(&self) -> FgColorDisplay<'_, BrightBlue, Self>

### Description
Change the foreground color to bright blue.

### Method
`bright_blue`

### Returns
`FgColorDisplay<'_, BrightBlue, Self>`

## on_bright_blue(&self) -> BgColorDisplay<'_, BrightBlue, Self>

### Description
Change the background color to bright blue.

### Method
`on_bright_blue`

### Returns
`BgColorDisplay<'_, BrightBlue, Self>`

## bright_magenta(&self) -> FgColorDisplay<'_, BrightMagenta, Self>

### Description
Change the foreground color to bright magenta.

### Method
`bright_magenta`

### Returns
`FgColorDisplay<'_, BrightMagenta, Self>`

## on_bright_magenta(&self) -> BgColorDisplay<'_, BrightMagenta, Self>

### Description
Change the background color to bright magenta.

### Method
`on_bright_magenta`

### Returns
`BgColorDisplay<'_, BrightMagenta, Self>`

## bright_purple(&self) -> FgColorDisplay<'_, BrightMagenta, Self>

### Description
Change the foreground color to bright purple.

### Method
`bright_purple`

### Returns
`FgColorDisplay<'_, Magenta, Self>`

## on_bright_purple(&self) -> BgColorDisplay<'_, Magenta, Self>

### Description
Change the background color to bright purple.

### Method
`on_bright_purple`

### Returns
`BgColorDisplay<'_, Magenta, Self>`

## bright_cyan(&self) -> FgColorDisplay<'_, BrightCyan, Self>

### Description
Change the foreground color to bright cyan.

### Method
`bright_cyan`

### Returns
`FgColorDisplay<'_, BrightCyan, Self>`

## on_bright_cyan(&self) -> BgColorDisplay<'_, BrightCyan, Self>

### Description
Change the background color to bright cyan.

### Method
`on_bright_cyan`

### Returns
`BgColorDisplay<'_, BrightCyan, Self>`

## bright_white(&self) -> FgColorDisplay<'_, BrightWhite, Self>

### Description
Change the foreground color to bright white.

### Method
`bright_white`

### Returns
`FgColorDisplay<'_, BrightWhite, Self>`

## on_bright_white(&self) -> BgColorDisplay<'_, BrightWhite, Self>

### Description
Change the background color to bright white.

### Method
`on_bright_white`

### Returns
`BgColorDisplay<'_, BrightWhite, Self>`
```

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

### type_id

Source: https://docs.rs/miette/latest/miette/struct.SourceOffset.html

Gets the TypeId of the object.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
`type_id`

### Parameters
None

### Returns
`TypeId`
```

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

### Determine Visual Offset on a Line

Source: https://docs.rs/miette/latest/src/miette/handlers/graphical.rs.html

Calculates the visual column position for a given byte offset within a line. It handles offsets that fall in the middle of a character, returning the start or end column based on the `start` flag.

```rust
fn visual_offset(&self, line: &Line, offset: usize, start: bool) -> usize {
        let line_range = line.offset..=(line.offset + line.length);
        assert!(line_range.contains(&offset));

        let mut text_index = offset - line.offset;
        while text_index <= line.text.len() && !line.text.is_char_boundary(text_index) {
            if start {
                text_index -= 1;
            } else {

```

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

### MietteHandlerOpts::new

Source: https://docs.rs/miette/latest/miette/struct.MietteHandlerOpts.html

Creates a new MietteHandlerOpts instance with default settings.

```APIDOC
## MietteHandlerOpts::new

### Description
Create a new `MietteHandlerOpts`.

### Method
`pub fn new() -> Self`
```

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

### handler

Source: https://docs.rs/miette/latest/miette/struct.Error.html

Gets a reference to the `ReportHandler` associated with this `Report`.

```APIDOC
## handler

### Description
Provides read-only access to the `ReportHandler` responsible for formatting and displaying this error report.

### Returns
- `&dyn ReportHandler` - A reference to the report handler.

### Source
`pub fn handler(&self) -> &dyn ReportHandler`
```

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

### SyntectHighlighter::start_highlighter_state

Source: https://docs.rs/miette/latest/miette/highlighters/struct.SyntectHighlighter.html

Initializes a new HighlighterState for processing and highlighting SpanContents.

```APIDOC
## fn start_highlighter_state<'h>( &'h self, source: &dyn SpanContents<'_>, ) -> Box<dyn HighlighterState + 'h>

### Description
Creates a new `HighlighterState` to begin parsing and highlighting a `SpanContents`.

### Parameters
- `source`: A reference to the `SpanContents` to be highlighted.
```

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

### Box::new_uninit_in

Source: https://docs.rs/miette/latest/miette/type.ErrorHook.html

Constructs a new box with uninitialized contents in the provided allocator. This is a nightly-only experimental API.

```APIDOC
## Box::new_uninit_in

### Description
Constructs a new box with uninitialized contents in the provided allocator. This is a nightly-only experimental API.

### Method
Associated function (call as `Box::new_uninit_in(alloc)`)

### Parameters
- **alloc** (A) - The allocator to use.

### Return Value
- **Box<MaybeUninit<T>, A>**

### Examples
```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut five = Box::<u32, _>::new_uninit_in(System);
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```
```

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

### Get the name of NamedSource

Source: https://docs.rs/miette/latest/miette/struct.NamedSource.html

Retrieves the name associated with this NamedSource.

```rust
pub fn name(&self) -> &str
```

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

### handler_mut

Source: https://docs.rs/miette/latest/miette/struct.Error.html

Gets a mutable reference to the `ReportHandler` associated with this `Report`.

```APIDOC
## handler_mut

### Description
Provides mutable access to the `ReportHandler` associated with this error report. This allows for modification of the handler's behavior or state.

### Returns
- `&mut dyn ReportHandler` - A mutable reference to the report handler.

### Source
`pub fn handler_mut(&mut self) -> &mut dyn ReportHandler`
```

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

### Box::new_uninit

Source: https://docs.rs/miette/latest/miette/type.ErrorHook.html

Constructs a new Box with uninitialized contents.

```APIDOC
## Box::new_uninit

### Description
Constructs a new box with uninitialized contents.

### Method
Associated function

### Returns
A `Box<MaybeUninit<T>>` with uninitialized contents.

### Examples
```rust
let mut five = Box::<u32>::new_uninit();
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```
```

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

### Initialize MietteHandlerOpts

Source: https://docs.rs/miette/latest/miette/struct.MietteHandlerOpts.html

Create a new instance of MietteHandlerOpts to begin configuring error report display settings.

```rust
miette::MietteHandlerOpts::new()
```

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

### LabeledSpan::offset

Source: https://docs.rs/miette/latest/miette/struct.LabeledSpan.html

Returns the 0-based starting byte offset of the LabeledSpan.

```APIDOC
## LabeledSpan::offset

### Description
Returns the 0-based starting byte offset.

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

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

### start_highlighter_state Method

Source: https://docs.rs/miette/latest/miette/highlighters/trait.Highlighter.html

Creates a new HighlighterState for parsing and highlighting source code. The SpanContents is used for language detection and initialization.

```rust
fn start_highlighter_state<'h>(
        &'h self,
        source: &dyn SpanContents<'_>,
    ) -> Box<dyn HighlighterState + 'h>
```

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

### Report Handler Management

Source: https://docs.rs/miette/latest/miette/struct.Report.html

Methods for getting and setting the handler associated with a `Report`.

```APIDOC
## pub fn handler(&self) -> &dyn ReportHandler

Get a reference to the Handler for this Report.

Source
```

```APIDOC
## pub fn handler_mut(&mut self) -> &mut dyn ReportHandler

Get a mutable reference to the Handler for this Report.

Source
```

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

### impl Highlighter for SyntectHighlighter

Source: https://docs.rs/miette/latest/src/miette/highlighters/syntect.rs.html

Implementation of the Highlighter trait for SyntectHighlighter, providing the `start_highlighter_state` method.

```APIDOC
## `impl Highlighter for SyntectHighlighter`

### Description
Provides the functionality to start a highlighter state for processing source code.

### Method
#### `start_highlighter_state`

##### Description
Initializes and returns a new highlighter state for the given source content.

##### Signature
```rust
fn start_highlighter_state<'h>(
    &'h self,
    source: &dyn SpanContents<'_>,
) -> Box<dyn HighlighterState + 'h>
```

##### Parameters
* `source` (&dyn SpanContents<'_>) - The content to be highlighted.
```

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

### Get actual byte offset

Source: https://docs.rs/miette/latest/miette/struct.SourceOffset.html

Retrieves the actual byte offset from a SourceOffset instance.

```rust
pub const fn offset(&self) -> ByteOffset
```

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

### Build Handler

Source: https://docs.rs/miette/latest/src/miette/handler.rs.html

Builds a `MietteHandler` from the configured options.

```APIDOC
## build

### Description
Builds a [`MietteHandler`] from this builder.

### Method
`build() -> MietteHandler`
```

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

### Get the inner SourceCode

Source: https://docs.rs/miette/latest/miette/struct.NamedSource.html

Provides a reference to the underlying SourceCode contained within the NamedSource.

```rust
pub fn inner(&self) -> &S
```

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

### SourceSpan Conversions

Source: https://docs.rs/miette/latest/miette/struct.SourceSpan.html

Demonstrates various ways to convert other types into a SourceSpan.

```APIDOC
## SourceSpan Conversions

### From `(SourceOffset, usize)`

#### Description
Converts a tuple of `(start, len)` into a `SourceSpan`.

#### Signature
```rust
impl From<(SourceOffset, usize)> for SourceSpan
fn from((start, len): (SourceOffset, usize)) -> Self
```

### From `(usize, usize)`

#### Description
Converts a tuple of `(start, len)` into a `SourceSpan`.

#### Signature
```rust
impl From<(usize, usize)> for SourceSpan
fn from((start, len): (ByteOffset, usize)) -> Self
```

### From `Range<usize>`

#### Description
Converts a `Range<ByteOffset>` into a `SourceSpan`.

#### Signature
```rust
impl From<Range<usize>> for SourceSpan
fn from(range: Range<ByteOffset>) -> Self
```

### From `RangeInclusive<usize>`

#### Description
Converts a `RangeInclusive<ByteOffset>` into a `SourceSpan`.

#### Panics
Panics if the total length of the inclusive range would overflow a `usize`. This will only occur with the range `0..=usize::MAX`.

#### Signature
```rust
impl From<RangeInclusive<usize>> for SourceSpan
fn from(range: RangeInclusive<ByteOffset>) -> Self
```

### From `SourceOffset`

#### Description
Converts a `SourceOffset` into a `SourceSpan` (representing a zero-length span at the offset).

#### Signature
```rust
impl From<SourceOffset> for SourceSpan
fn from(offset: SourceOffset) -> Self
```

### From `usize`

#### Description
Converts a `ByteOffset` into a `SourceSpan` (representing a zero-length span at the offset).

#### Signature
```rust
impl From<usize> for SourceSpan
fn from(offset: ByteOffset) -> Self
```
```

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

### enumerate

Source: https://docs.rs/miette/latest/miette/type.ErrorHook.html

Creates an iterator that yields pairs of the current iteration count (starting from 0) and the element.

```APIDOC
## enumerate

### Description
Creates an iterator which gives the current iteration count as well as the next value.

### Signature
`fn enumerate(self) -> Enumerate<Self>`

### Constraints
* `Self: Sized`
```

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

### Manually Create Box from Raw Pointer

Source: https://docs.rs/miette/latest/miette/type.ErrorHook.html

Manually create a `Box` from scratch using the system allocator. Ensure the memory was allocated with the correct layout and use `.write()` to initialize the memory before creating the `Box`.

```rust
#![feature(allocator_api, slice_ptr_get)]

use std::alloc::{Allocator, Layout, System};

unsafe {
    let ptr = System.allocate(Layout::new::<i32>())?.as_mut_ptr() as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw_in(ptr, System);
}
```

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

### OwoColorize Methods

Source: https://docs.rs/miette/latest/miette/struct.LabeledSpan.html

Methods for applying foreground and background colors to LabeledSpans.

```APIDOC
## OwoColorize Methods

### Description
Provides methods to set foreground and background colors for terminal output.

### Methods
- `fg<C>(&self) -> FgColorDisplay<'_, C, Self>`: Set the foreground color generically.
- `bg<C>(&self) -> BgColorDisplay<'_, C, Self>`: Set the background color generically.
- `black(&self) -> FgColorDisplay<'_, Black, Self>`: Change the foreground color to black.
- `on_black(&self) -> BgColorDisplay<'_, Black, Self>`: Change the background color to black.
- `red(&self) -> FgColorDisplay<'_, Red, Self>`: Change the foreground color to red.
- `on_red(&self) -> BgColorDisplay<'_, Red, Self>`: Change the background color to red.
- `green(&self) -> FgColorDisplay<'_, Green, Self>`: Change the foreground color to green.
- `on_green(&self) -> BgColorDisplay<'_, Green, Self>`: Change the background color to green.
- `yellow(&self) -> FgColorDisplay<'_, Yellow, Self>`: Change the foreground color to yellow.
- `on_yellow(&self) -> BgColorDisplay<'_, Yellow, Self>`: Change the background color to yellow.
- `blue(&self) -> FgColorDisplay<'_, Blue, Self>`: Change the foreground color to blue.
- `on_blue(&self) -> BgColorDisplay<'_, Blue, Self>`: Change the background color to blue.
- `magenta(&self) -> FgColorDisplay<'_, Magenta, Self>`: Change the foreground color to magenta.
- `on_magenta(&self) -> BgColorDisplay<'_, Magenta, Self>`: Change the background color to magenta.
- `purple(&self) -> FgColorDisplay<'_, Magenta, Self>`: Change the foreground color to purple.
- `on_purple(&self) -> BgColorDisplay<'_, Magenta, Self>`: Change the background color to purple.
- `cyan(&self) -> FgColorDisplay<'_, Cyan, Self>`: Change the foreground color to cyan.
- `on_cyan(&self) -> BgColorDisplay<'_, Cyan, Self>`: Change the background color to cyan.
- `white(&self) -> FgColorDisplay<'_, White, Self>`: Change the foreground color to white.
- `on_white(&self) -> BgColorDisplay<'_, White, Self>`: Change the background color to white.
- `default_color(&self) -> FgColorDisplay<'_, Default, Self>`: Change the foreground color to the terminal default.
- `on_default_color(&self) -> BgColorDisplay<'_, Default, Self>`: Change the background color to the terminal default.
- `bright_black(&self) -> FgColorDisplay<'_, BrightBlack, Self>`: Change the foreground color to bright black.
- `on_bright_black(&self) -> BgColorDisplay<'_, BrightBlack, Self>`: Change the background color to bright black.
- `bright_red(&self) -> FgColorDisplay<'_, BrightRed, Self>`: Change the foreground color to bright red.
- `on_bright_red(&self) -> BgColorDisplay<'_, BrightRed, Self>`: Change the background color to bright red.
- `bright_green(&self) -> FgColorDisplay<'_, BrightGreen, Self>`: Change the foreground color to bright green.
- `on_bright_green(&self) -> BgColorDisplay<'_, BrightGreen, Self>`: Change the background color to bright green.
- `bright_yellow(&self) -> FgColorDisplay<'_, BrightYellow, Self>`: Change the foreground color to bright yellow.
- `on_bright_yellow(&self) -> BgColorDisplay<'_, BrightYellow, Self>`: Change the background color to bright yellow.
- `bright_blue(&self) -> FgColorDisplay<'_, BrightBlue, Self>`: Change the foreground color to bright blue.
- `on_bright_blue(&self) -> BgColorDisplay<'_, BrightBlue, Self>`: Change the background color to bright blue.
- `bright_magenta(&self) -> FgColorDisplay<'_, BrightMagenta, Self>`: Change the foreground color to bright magenta.
- `on_bright_magenta(&self) -> BgColorDisplay<'_, BrightMagenta, Self>`: Change the background color to bright magenta.
- `bright_purple(&self) -> FgColorDisplay<'_, BrightMagenta, Self>`: Change the foreground color to bright purple.
- `on_bright_purple(&self) -> BgColorDisplay<'_, BrightMagenta, Self>`: Change the background color to bright purple.
- `bright_cyan(&self) -> FgColorDisplay<'_, BrightCyan, Self>`: Change the foreground color to bright cyan.
- `on_bright_cyan(&self) -> BgColorDisplay<'_, BrightCyan, Self>`: Change the background color to bright cyan.
- `bright_white(&self) -> FgColorDisplay<'_, BrightWhite, Self>`: Change the foreground color to bright white.
- `on_bright_white(&self) -> BgColorDisplay<'_, BrightWhite, Self>`: Change the background color to bright white.
```

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

### GraphicalReportHandler::without_primary_span_start

Source: https://docs.rs/miette/latest/miette/struct.GraphicalReportHandler.html

Excludes the line and column for the start of the primary span when the snippet spans multiple lines.

```APIDOC
## GraphicalReportHandler::without_primary_span_start

### Description
Do not include the line and column for the the start of the primary span when the snippet extends multiple lines

### Method

```rust
pub fn without_primary_span_start(self) -> Self
```
```

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

### GraphicalReportHandler::with_primary_span_start

Source: https://docs.rs/miette/latest/miette/struct.GraphicalReportHandler.html

Includes the line and column for the start of the primary span when the snippet spans multiple lines.

```APIDOC
## GraphicalReportHandler::with_primary_span_start

### Description
Include the line and column for the the start of the primary span when the snippet extends multiple lines

### Method

```rust
pub fn with_primary_span_start(self) -> Self
```
```

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

### GraphicalTheme::none()

Source: https://docs.rs/miette/latest/src/miette/handlers/theme.rs.html

Creates a basic, monochrome ASCII art theme with no colors.

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

### Description
A "basic" graphical theme that skips colors and unicode characters and just does monochrome ascii art. If you want a completely non-graphical rendering of your [`Diagnostic`](crate::Diagnostic)s, check out [`NarratableReportHandler`](crate::NarratableReportHandler), or write your own [`ReportHandler`](crate::ReportHandler).

### Returns
`GraphicalTheme` - A monochrome ASCII theme with no colors.
```

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

### Get Style Information

Source: https://docs.rs/miette/latest/src/miette/handlers/graphical.rs.html

Retrieves the style associated with the current element. This is useful for applying consistent formatting.

```rust
fn style(&self) -> Style {
        self.style
    }
```

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

### Try Creating Box with Uninitialized Contents (Nightly)

Source: https://docs.rs/miette/latest/miette/type.ErrorHook.html

Attempts to construct a new box with uninitialized contents using the provided allocator, returning an error if allocation fails. This is a nightly-only experimental API.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut five = Box::<u32, _>::try_new_uninit_in(System)?;
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5);
```

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

### Assert Highlighter Options

Source: https://docs.rs/miette/latest/src/miette/handler.rs.html

Macro for asserting highlighter options with different configurations for syntect and non-syntect builds.

```rust
assert_highlighter_opt!(
    opts = $opts,
    supports_color = $sup_color,
    expected_with_syntect = $expected_with,
    expected_without_syntect = $expected_without,
);
```

```rust
assert_highlighter_opt!(
    opts = $opts,
    supports_color = $sup_color,
    expected = $expected,
);
```

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

### impl AsRef<dyn Diagnostic> for Report

Source: https://docs.rs/miette/latest/miette/trait.Diagnostic.html

Provides a way to get a reference to the Diagnostic trait from a Report.

```rust
fn as_ref(&self) -> &(dyn Diagnostic + 'static) { ... }
```

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

### MietteHandlerOpts::with_syntax_highlighting

Source: https://docs.rs/miette/latest/miette/struct.MietteHandlerOpts.html

Sets a syntax highlighter for graphical rendering.

```APIDOC
## MietteHandlerOpts::with_syntax_highlighting

### Description
Set a syntax highlighter when rendering in graphical mode. Use `force_graphical()` to force graphical mode. Syntax highlighting is disabled by default unless the `syntect-highlighter` feature is enabled. Call this method to override the default and use a custom highlighter implementation instead. Use `without_syntax_highlighting()` To disable highlighting completely. Setting this option will not force color output. In all cases, the current color configuration via `color()` takes precedence over highlighter configuration. However, this option does take precedence over `rgb_colors()` (meaning syntax highlighting will be enabled regardless of the value of `MietteHandlerOpts::rgb_colors`).

### Method
`pub fn with_syntax_highlighting( self, highlighter: impl Highlighter + Send + Sync + 'static, ) -> Self`
```

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

### Get Span Length

Source: https://docs.rs/miette/latest/src/miette/handlers/graphical.rs.html

Returns the length of the associated span in characters. This indicates the size of the highlighted or relevant section.

```rust
fn len(&self) -> usize {
        self.span.len()
    }
```

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

### Implement Default for SyntectHighlighter

Source: https://docs.rs/miette/latest/miette/highlighters/struct.SyntectHighlighter.html

Provides a default value for SyntectHighlighter, allowing it to be created without explicit configuration.

```rust
fn default() -> Self
```

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

### MietteHandler::new

Source: https://docs.rs/miette/latest/miette/struct.MietteHandler.html

Creates a new MietteHandler with default settings.

```APIDOC
## MietteHandler::new

### Description
Creates a new `MietteHandler` with default settings.

### Method
`pub fn new() -> Self`
```

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

### Get Report Handler Reference

Source: https://docs.rs/miette/latest/src/miette/eyreish/error.rs.html

Retrieves an immutable reference to the `ReportHandler` for the current `Report`. This is used for displaying or processing the error.

```rust
pub fn handler(&self) -> &dyn ReportHandler {
        unsafe {
            self.inner
                .by_ref()
                .deref()
                .handler
                .as_ref()
                .unwrap()
                .as_ref()
        }
    }
```

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

### Implement Any Trait for T

Source: https://docs.rs/miette/latest/miette/highlighters/struct.BlankHighlighterState.html

Provides the `type_id` method, which gets the `TypeId` of the current type. This is part of the blanket implementations for any type `T` that is `'static`.

```rust
fn type_id(&self) -> TypeId;
```

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

### Implement Clone for SyntectHighlighter

Source: https://docs.rs/miette/latest/miette/highlighters/struct.SyntectHighlighter.html

Allows SyntectHighlighter instances to be duplicated. This is useful for scenarios where multiple independent highlighters are needed.

```rust
fn clone(&self) -> SyntectHighlighter
```

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

### Manually Create Box from NonNull Pointer

Source: https://docs.rs/miette/latest/miette/type.ErrorHook.html

Manually create a `Box` from scratch using the system allocator. Ensure the memory was allocated with the correct layout and use `.write()` to initialize the memory before creating the `Box`.

```rust
#![feature(allocator_api, box_vec_non_null, slice_ptr_get)]

use std::alloc::{Allocator, Layout, System};

unsafe {
    let non_null = System.allocate(Layout::new::<i32>())?.cast::<i32>();
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `non_null`.
    non_null.write(5);
    let x = Box::from_non_null_in(non_null, System);
}
```

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

### Test span reading in the middle of a line

Source: https://docs.rs/miette/latest/src/miette/source_impls.rs.html

Ensures `read_span` correctly identifies content and position when the span is within a line, not at its start.

```rust
let src = String::from("foo\nbarbar\nbaz\n");
let contents = src.read_span(&(7, 4).into(), 0, 0)?;
assert_eq!("bar\n", std::str::from_utf8(contents.data()).unwrap());
assert_eq!(1, contents.line());
assert_eq!(3, contents.column());
```

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

### Serialize SourceSpan

Source: https://docs.rs/miette/latest/src/miette/protocol.rs.html

Demonstrates serializing a SourceSpan to JSON. Requires the 'serde' feature.

```rust
#[cfg(feature = "serde")]
#[test]
fn test_serialize_source_span() {
    use serde_json::json;

    assert_eq!(
        json!(SourceSpan::from(0)),
        json!({ "offset": 0, "length": 0})
    );
}
```

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

### unsafe unwrap_unchecked on Err Example

Source: https://docs.rs/miette/latest/miette/type.Result.html

Illustrates the undefined behavior that occurs when calling unwrap_unchecked on an Err variant. This code should not be run in production.

```rust
let x: Result<u32, &str> = Err("emergency failure");
unsafe { x.unwrap_unchecked() }; // Undefined behavior!
```

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

### Create Box with Uninitialized Contents (Nightly)

Source: https://docs.rs/miette/latest/miette/type.ErrorHook.html

Constructs a new box with uninitialized contents using the provided allocator. Deferred initialization is required. This is a nightly-only experimental API.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut five = Box::<u32, _>::new_uninit_in(System);
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```

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

### Iterating over Result<T, E>

Source: https://docs.rs/miette/latest/miette/type.Result.html

Use `into_iter()` to get a consuming iterator. It yields one value if the result is `Ok`, otherwise none.

```rust
let x: Result<u32, &str> = Ok(5);
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, [5]);

let x: Result<u32, &str> = Err("nothing!");
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, []);
```
Tokens:
Raw