Struct syntax::diagnostics::plugin::DiagnosticBuilder

#[must_use]
pub struct DiagnosticBuilder<'a> {
    pub handler: &'a Handler,
    // some fields omitted
}

Used for emitting structured error messages and other diagnostic information.

If there is some state in a downstream crate you would like to access in the methods of DiagnosticBuilder here, consider extending HandlerFlags, accessed via self.handler.flags.

Fields

handler: &'a Handler

Methods

impl<'a> DiagnosticBuilder<'a>

pub fn emit(&mut self)

Emit the diagnostic.

pub fn buffer(self, buffered_diagnostics: &mut Vec<Diagnostic>)

Buffers the diagnostic for later emission, unless handler has disabled such buffering.

pub fn sub<S>(
    &mut self,
    level: Level,
    message: &str,
    span: Option<S>
) -> &mut DiagnosticBuilder<'a> where
    S: Into<MultiSpan>, 

Convenience function for internal use, clients should use one of the span_* methods instead.

pub fn delay_as_bug(&mut self)

Delay emission of this diagnostic as a bug.

This can be useful in contexts where an error indicates a bug but typically this only happens when other compilation errors have already happened. In those cases this can be used to defer emission of this diagnostic as a bug in the compiler only if no other errors have been emitted.

In the meantime, though, callsites are required to deal with the "bug" locally in whichever way makes the most sense.

pub fn span_label<T>(
    &mut self,
    span: Span,
    label: T
) -> &mut DiagnosticBuilder<'a> where
    T: Into<String>, 

Adds a span/label to be included in the resulting snippet. This is pushed onto the MultiSpan that was created when the diagnostic was first built. If you don't call this function at all, and you just supplied a Span to create the diagnostic, then the snippet will just include that Span, which is called the primary span.

pub fn note_expected_found(
    &mut self,
    label: &dyn Display,
    expected: DiagnosticStyledString,
    found: DiagnosticStyledString
) -> &mut DiagnosticBuilder<'a>

pub fn note_expected_found_extra(
    &mut self,
    label: &dyn Display,
    expected: DiagnosticStyledString,
    found: DiagnosticStyledString,
    expected_extra: &dyn Display,
    found_extra: &dyn Display
) -> &mut DiagnosticBuilder<'a>

pub fn note(&mut self, msg: &str) -> &mut DiagnosticBuilder<'a>

pub fn span_note<S>(&mut self, sp: S, msg: &str) -> &mut DiagnosticBuilder<'a> where
    S: Into<MultiSpan>, 

pub fn warn(&mut self, msg: &str) -> &mut DiagnosticBuilder<'a>

pub fn span_warn<S>(&mut self, sp: S, msg: &str) -> &mut DiagnosticBuilder<'a> where
    S: Into<MultiSpan>, 

pub fn help(&mut self, msg: &str) -> &mut DiagnosticBuilder<'a>

pub fn span_help<S>(&mut self, sp: S, msg: &str) -> &mut DiagnosticBuilder<'a> where
    S: Into<MultiSpan>, 

pub fn multipart_suggestion(
    &mut self,
    msg: &str,
    suggestion: Vec<(Span, String)>,
    applicability: Applicability
) -> &mut DiagnosticBuilder<'a>

pub fn tool_only_multipart_suggestion(
    &mut self,
    msg: &str,
    suggestion: Vec<(Span, String)>,
    applicability: Applicability
) -> &mut DiagnosticBuilder<'a>

pub fn span_suggestion(
    &mut self,
    sp: Span,
    msg: &str,
    suggestion: String,
    applicability: Applicability
) -> &mut DiagnosticBuilder<'a>

pub fn span_suggestions<impl Iterator>(
    &mut self,
    sp: Span,
    msg: &str,
    suggestions: impl Iterator,
    applicability: Applicability
) -> &mut DiagnosticBuilder<'a> where
    impl Iterator: Iterator<Item = String>, 

pub fn span_suggestion_short(
    &mut self,
    sp: Span,
    msg: &str,
    suggestion: String,
    applicability: Applicability
) -> &mut DiagnosticBuilder<'a>

pub fn span_suggestion_hidden(
    &mut self,
    sp: Span,
    msg: &str,
    suggestion: String,
    applicability: Applicability
) -> &mut DiagnosticBuilder<'a>

pub fn tool_only_span_suggestion(
    &mut self,
    sp: Span,
    msg: &str,
    suggestion: String,
    applicability: Applicability
) -> &mut DiagnosticBuilder<'a>

pub fn set_span<S>(&mut self, sp: S) -> &mut DiagnosticBuilder<'a> where
    S: Into<MultiSpan>, 

pub fn code(&mut self, s: DiagnosticId) -> &mut DiagnosticBuilder<'a>

pub fn allow_suggestions(&mut self, allow: bool) -> &mut DiagnosticBuilder<'a>

pub fn new(
    handler: &'a Handler,
    level: Level,
    message: &str
) -> DiagnosticBuilder<'a>

Convenience function for internal use, clients should use one of the struct_* methods on Handler.

pub fn new_with_code(
    handler: &'a Handler,
    level: Level,
    code: Option<DiagnosticId>,
    message: &str
) -> DiagnosticBuilder<'a>

Convenience function for internal use, clients should use one of the struct_* methods on Handler.

pub fn new_diagnostic(
    handler: &'a Handler,
    diagnostic: Diagnostic
) -> DiagnosticBuilder<'a>

Creates a new DiagnosticBuilder with an already constructed diagnostic.

Methods from Deref<Target = Diagnostic>

pub fn is_error(&self) -> bool

pub fn cancel(&mut self)

Cancel the diagnostic (a structured diagnostic must either be emitted or canceled or it will panic when dropped).

pub fn cancelled(&self) -> bool

pub fn span_label<T>(&mut self, span: Span, label: T) -> &mut Diagnostic where
    T: Into<String>, 

Adds a span/label to be included in the resulting snippet. This is pushed onto the MultiSpan that was created when the diagnostic was first built. If you don't call this function at all, and you just supplied a Span to create the diagnostic, then the snippet will just include that Span, which is called the primary span.

pub fn replace_span_with(&mut self, after: Span) -> &mut Diagnostic

pub fn note_expected_found(
    &mut self,
    label: &dyn Display,
    expected: DiagnosticStyledString,
    found: DiagnosticStyledString
) -> &mut Diagnostic

pub fn note_expected_found_extra(
    &mut self,
    label: &dyn Display,
    expected: DiagnosticStyledString,
    found: DiagnosticStyledString,
    expected_extra: &dyn Display,
    found_extra: &dyn Display
) -> &mut Diagnostic

pub fn note_trait_signature(
    &mut self,
    name: String,
    signature: String
) -> &mut Diagnostic

pub fn note(&mut self, msg: &str) -> &mut Diagnostic

pub fn highlighted_note(&mut self, msg: Vec<(String, Style)>) -> &mut Diagnostic

pub fn span_note<S>(&mut self, sp: S, msg: &str) -> &mut Diagnostic where
    S: Into<MultiSpan>, 

pub fn warn(&mut self, msg: &str) -> &mut Diagnostic

pub fn span_warn<S>(&mut self, sp: S, msg: &str) -> &mut Diagnostic where
    S: Into<MultiSpan>, 

pub fn help(&mut self, msg: &str) -> &mut Diagnostic

pub fn span_help<S>(&mut self, sp: S, msg: &str) -> &mut Diagnostic where
    S: Into<MultiSpan>, 

pub fn multipart_suggestion(
    &mut self,
    msg: &str,
    suggestion: Vec<(Span, String)>,
    applicability: Applicability
) -> &mut Diagnostic

pub fn tool_only_multipart_suggestion(
    &mut self,
    msg: &str,
    suggestion: Vec<(Span, String)>,
    applicability: Applicability
) -> &mut Diagnostic

Prints out a message with for a multipart suggestion without showing the suggested code.

This is intended to be used for suggestions that are obvious in what the changes need to be from the message, showing the span label inline would be visually unpleasant (marginally overlapping spans or multiline spans) and showing the snippet window wouldn't improve understandability.

pub fn span_suggestion(
    &mut self,
    sp: Span,
    msg: &str,
    suggestion: String,
    applicability: Applicability
) -> &mut Diagnostic

Prints out a message with a suggested edit of the code.

In case of short messages and a simple suggestion, rustc displays it as a label:

try adding parentheses: `(tup.0).1`

The message

• should not end in any punctuation (a : is added automatically)
• should not be a question (avoid language like "did you mean")
• should not contain any phrases like "the following", "as shown", etc.
• may look like "to do xyz, use" or "to do xyz, use abc"
• may contain a name of a function, variable, or type, but not whole expressions

See CodeSuggestion for more information.

pub fn span_suggestions<impl Iterator>(
    &mut self,
    sp: Span,
    msg: &str,
    suggestions: impl Iterator,
    applicability: Applicability
) -> &mut Diagnostic where
    impl Iterator: Iterator<Item = String>, 

Prints out a message with multiple suggested edits of the code.

pub fn span_suggestion_short(
    &mut self,
    sp: Span,
    msg: &str,
    suggestion: String,
    applicability: Applicability
) -> &mut Diagnostic

Prints out a message with a suggested edit of the code. If the suggestion is presented inline, it will only show the message and not the suggestion.

See CodeSuggestion for more information.

pub fn span_suggestion_hidden(
    &mut self,
    sp: Span,
    msg: &str,
    suggestion: String,
    applicability: Applicability
) -> &mut Diagnostic

Prints out a message with for a suggestion without showing the suggested code.

This is intended to be used for suggestions that are obvious in what the changes need to be from the message, showing the span label inline would be visually unpleasant (marginally overlapping spans or multiline spans) and showing the snippet window wouldn't improve understandability.

pub fn tool_only_span_suggestion(
    &mut self,
    sp: Span,
    msg: &str,
    suggestion: String,
    applicability: Applicability
) -> &mut Diagnostic

Adds a suggestion to the json output, but otherwise remains silent/undisplayed in the cli.

This is intended to be used for suggestions that are very obvious in what the changes need to be from the message, but we still want other tools to be able to apply them.

pub fn set_span<S>(&mut self, sp: S) -> &mut Diagnostic where
    S: Into<MultiSpan>, 

pub fn code(&mut self, s: DiagnosticId) -> &mut Diagnostic

pub fn get_code(&self) -> Option<DiagnosticId>

pub fn message(&self) -> String

pub fn styled_message(&self) -> &Vec<(String, Style)>

pub fn copy_details_not_message(&mut self, from: &Diagnostic)

Used by a lint. Copies over all details but the "main message".

pub fn sub(
    &mut self,
    level: Level,
    message: &str,
    span: MultiSpan,
    render_span: Option<MultiSpan>
)

Convenience function for internal use, clients should use one of the public methods above.

Trait Implementations

impl<'a> DerefMut for DiagnosticBuilder<'a>

fn deref_mut(&mut self) -> &mut Diagnostic

Mutably dereferences the value.

impl<'a> Deref for DiagnosticBuilder<'a>

type Target = Diagnostic

The resulting type after dereferencing.

fn deref(&self) -> &Diagnostic

Dereferences the value.

impl<'a> Drop for DiagnosticBuilder<'a>

Destructor bomb - a DiagnosticBuilder must be either emitted or canceled or we emit a bug.

fn drop(&mut self)

Executes the destructor for this type.

impl<'a> Clone for DiagnosticBuilder<'a>

fn clone(&self) -> DiagnosticBuilder<'a>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for DiagnosticBuilder<'a>

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

Formats the value using the given formatter.