Struct DiagnosticMessageBuilder 

pub struct DiagnosticMessageBuilder { /* private fields */ }

Builder for creating diagnostic messages following tidyverse guidelines.

The builder API naturally encourages the tidyverse four-part error structure:

1. Title: Brief error message (via .error(), .warning(), etc.)
2. Problem: What went wrong - the “must” or “can’t” statement (via .problem())
3. Details: Specific information - max 5 bulleted items (via .add_detail(), .add_info())
4. Hints: Optional guidance (via .add_hint())

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let error = DiagnosticMessageBuilder::error("Incompatible types")
    .with_code("Q-1-2") // quarto-error-code-audit-ignore
    .problem("Cannot combine date and datetime types")
    .add_detail("`x`{.arg} has type `date`{.type}")
    .add_detail("`y`{.arg} has type `datetime`{.type}")
    .add_hint("Convert both to the same type?")
    .build();

assert_eq!(error.title, "Incompatible types");
assert_eq!(error.code, Some("Q-1-2".to_string())); // quarto-error-code-audit-ignore
assert!(error.problem.is_some());
assert_eq!(error.details.len(), 2);
assert_eq!(error.hints.len(), 1);

Implementations

impl DiagnosticMessageBuilder

pub fn new(kind: DiagnosticKind, title: impl Into<String>) -> Self

Create a new builder with the specified kind and title.

Most code should use the convenience methods .error(), .warning(), or .info() instead of calling this directly.

pub fn error(title: impl Into<String>) -> Self

Create an error diagnostic builder.

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let error = DiagnosticMessageBuilder::error("YAML Syntax Error")
    .build();

pub fn generic_error( message: impl Into<String>, file: &str, line: u32, ) -> DiagnosticMessage

Create a generic error for migration purposes.

This is a convenience method for the migration from ErrorCollector to DiagnosticMessage. It creates an error with code Q-0-99 (quarto-error-code-audit-ignore) and includes file/line information for tracking where the error originated in the code.

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let error = DiagnosticMessageBuilder::generic_error(
    "Found unexpected attribute",
    file!(),
    line!()
);
assert_eq!(error.code, Some("Q-0-99".to_string())); // quarto-error-code-audit-ignore
assert!(error.title.contains("Found unexpected attribute"));

pub fn generic_warning( message: impl Into<String>, file: &str, line: u32, ) -> DiagnosticMessage

Create a generic warning for migration purposes.

Similar to generic_error() but for warnings.

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let warning = DiagnosticMessageBuilder::generic_warning(
    "Caption found without table",
    file!(),
    line!()
);
assert_eq!(warning.code, Some("Q-0-99".to_string()));

pub fn warning(title: impl Into<String>) -> Self

Create a warning diagnostic builder.

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let warning = DiagnosticMessageBuilder::warning("Deprecated feature")
    .build();

pub fn info(title: impl Into<String>) -> Self

Create an info diagnostic builder.

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let info = DiagnosticMessageBuilder::info("Processing complete")
    .build();

pub fn with_code(self, code: impl Into<String>) -> Self

Set the error code.

Error codes follow the format Q-<subsystem>-<number> (e.g., “Q-1-1”). (quarto-error-code-audit-ignore)

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let error = DiagnosticMessageBuilder::error("YAML Syntax Error")
    .with_code("Q-1-1") // quarto-error-code-audit-ignore
    .build();

assert_eq!(error.code, Some("Q-1-1".to_string())); // quarto-error-code-audit-ignore

pub fn with_location(self, location: SourceInfo) -> Self

Attach a source location to this diagnostic.

The location identifies where in the source code the issue occurred. The location may track transformation history, allowing the error to be mapped back through multiple processing steps to the original source file.

Example

use quarto_error_reporting::DiagnosticMessageBuilder;
use quarto_source_map::{SourceInfo, SourceContext, FileId, Range, Location};

let mut ctx = SourceContext::new();
let file_id = ctx.add_file("test.qmd".into(), Some("content".into()));
let range = Range {
    start: Location { offset: 0, row: 0, column: 0 },
    end: Location { offset: 7, row: 0, column: 7 },
};
let source_info = SourceInfo::original(file_id, range);

let error = DiagnosticMessageBuilder::error("Parse error")
    .with_location(source_info)
    .build();

pub fn problem(self, stmt: impl Into<MessageContent>) -> Self

Set the problem statement.

Following tidyverse guidelines, the problem statement should:

• Start with a general, concise statement
• Use “must” for requirements or “can’t” for impossibilities
• Be specific about types/expectations

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let error = DiagnosticMessageBuilder::error("Invalid input")
    .problem("`n` must be a numeric vector, not a character vector")
    .build();

pub fn add_detail(self, detail: impl Into<MessageContent>) -> Self

Add an error detail (displayed with error/cross bullet).

Error details provide specific information about what went wrong. Following tidyverse guidelines:

• Keep sentences short and specific
• Reveal location, name, or content of problematic input
• Limit to 5 total details (error + info) to avoid overwhelming users

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let error = DiagnosticMessageBuilder::error("Incompatible lengths")
    .add_detail("`x` has length 3")
    .add_detail("`y` has length 5")
    .build();

assert_eq!(error.details.len(), 2);

pub fn add_detail_at( self, detail: impl Into<MessageContent>, location: SourceInfo, ) -> Self

Add an error detail with a source location.

This allows adding contextual information that points to specific locations in the source code, creating rich multi-location error messages.

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let error = DiagnosticMessageBuilder::error("Mismatched brackets")
    .add_detail_at("Opening bracket here", opening_location)
    .add_detail_at("But no closing bracket found", end_location)
    .build();

pub fn add_info(self, info: impl Into<MessageContent>) -> Self

Add an info detail (displayed with info bullet).

Info details provide additional context or explanatory information.

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let error = DiagnosticMessageBuilder::error("Missing file")
    .add_detail("Could not find `config.yaml`")
    .add_info("Default configuration will be used")
    .build();

pub fn add_info_at( self, info: impl Into<MessageContent>, location: SourceInfo, ) -> Self

Add an info detail with a source location.

pub fn add_note(self, note: impl Into<MessageContent>) -> Self

Add a note detail (displayed with plain bullet).

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let error = DiagnosticMessageBuilder::error("Parse error")
    .add_note("This is an experimental feature")
    .build();

pub fn add_note_at( self, note: impl Into<MessageContent>, location: SourceInfo, ) -> Self

Add a note detail with a source location.

pub fn add_faded_at( self, content: impl Into<MessageContent>, location: SourceInfo, ) -> Self

Add a faded detail with a source location.

Rendered with the same dim grey colour Ariadne uses for unlabelled source characters, so it visually “punches a hole” in any wider label that also covers the same column range. Useful for excluding block-quote prefixes or other prefix decorations from the highlight of a multi-line span.

pub fn add_hint(self, hint: impl Into<MessageContent>) -> Self

Add a hint for fixing the error.

Following tidyverse guidelines, hints should:

• Only be included when the problem source is clear and common
• Provide straightforward fix suggestions
• End with a question mark if suggesting action

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let error = DiagnosticMessageBuilder::error("Function not found")
    .problem("Could not find function `summarise()`")
    .add_hint("Did you mean `summarize()`?")
    .build();

assert_eq!(error.hints.len(), 1);

pub fn build(self) -> DiagnosticMessage

Build the diagnostic message.

This consumes the builder and returns the constructed DiagnosticMessage.

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let error = DiagnosticMessageBuilder::error("Parse error")
    .problem("Invalid syntax")
    .build();

assert_eq!(error.title, "Parse error");

pub fn build_with_validation(self) -> (DiagnosticMessage, Vec<String>)

Build with validation.

This validates the message structure according to tidyverse guidelines:

• Warns if there’s no problem statement (recommended but not required)
• Warns if there are more than 5 details (overwhelming for users)
• Future: Could check that hints end with ‘?’

Returns warnings as a Vec of strings. An empty Vec means validation passed.

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let (error, warnings) = DiagnosticMessageBuilder::error("Test error")
    .build_with_validation();

// Warns because there's no problem statement
assert!(!warnings.is_empty());

Trait Implementations

impl Clone for DiagnosticMessageBuilder

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DiagnosticMessageBuilder

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

Formats the value using the given formatter.