Struct rustc_errors::DiagnosticBuilder

pub struct DiagnosticBuilder<'a, G: EmissionGuarantee> {
    inner: DiagnosticBuilderInner<'a>,
    _marker: PhantomData<G>,
}

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

inner: DiagnosticBuilderInner<'a>

_marker: PhantomData<G>

Implementations

impl<'a> DiagnosticBuilder<'a, ErrorGuaranteed>

pub(crate) fn new_guaranteeing_error<M: Into<DiagnosticMessage>, const L: Level>(
    handler: &'a Handler,
    message: M
) -> Selfwhere
    (): IsError<L>,

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

pub fn forget_guarantee(self) -> DiagnosticBuilder<'a, ()>

Discard the guarantee .emit() would return, in favor of having the type DiagnosticBuilder<'a, ()>. This may be necessary whenever there is a common codepath handling both errors and warnings.

impl<'a> DiagnosticBuilder<'a, ()>

pub(crate) fn new<M: Into<DiagnosticMessage>>(
    handler: &'a Handler,
    level: Level,
    message: M
) -> Self

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

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

Creates a new DiagnosticBuilder with an already constructed diagnostic.

impl<'a> DiagnosticBuilder<'a, Noted>

pub(crate) fn new_note(
    handler: &'a Handler,
    message: impl Into<DiagnosticMessage>
) -> Self

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

pub(crate) fn new_diagnostic_note(
    handler: &'a Handler,
    diagnostic: Diagnostic
) -> Self

Creates a new DiagnosticBuilder with an already constructed diagnostic.

impl<'a> DiagnosticBuilder<'a, !>

pub(crate) fn new_fatal(
    handler: &'a Handler,
    message: impl Into<DiagnosticMessage>
) -> Self

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

pub(crate) fn new_diagnostic_fatal(
    handler: &'a Handler,
    diagnostic: Diagnostic
) -> Self

Creates a new DiagnosticBuilder with an already constructed diagnostic.

impl<'a, G: EmissionGuarantee> DiagnosticBuilder<'a, G>

pub fn emit(&mut self) -> G

Emit the diagnostic.

pub fn emit_unless(&mut self, delay: bool) -> G

Emit the diagnostic unless delay is true, in which case the emission will be delayed as a bug.

See emit and delay_as_bug for details.

pub fn cancel(self)

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

This method takes self by-value to disallow calling .emit() on it, which may be expected to guarantee the emission of an error, either at the time of the call, or through a prior .emit() call.

pub fn stash(self, span: Span, key: StashKey)

Stashes diagnostic for possible later improvement in a different, later stage of the compiler. The diagnostic can be accessed with the provided span and key through Handler::steal_diagnostic().

As with buffer, this is unless the handler has disabled such buffering.

pub fn into_diagnostic(self) -> Option<(Diagnostic, &'a Handler)>

Converts the builder to a Diagnostic for later emission, unless handler has disabled such buffering, or .emit() was called.

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

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

pub fn delay_as_bug(&mut self) -> G

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 downgrade_to_delayed_bug(&mut self) -> &mut Self

See Diagnostic::downgrade_to_delayed_bug().

pub fn span_label(
    &mut self,
    span: Span,
    label: impl Into<SubdiagnosticMessage>
) -> &mut Self

Appends a labeled span to the diagnostic.

Labels are used to convey additional context for the diagnostic’s primary span. They will be shown together with the original diagnostic’s span, not with spans added by span_note, span_help, etc. Therefore, if the primary span is not displayable (because the span is DUMMY_SP or the source code isn’t found), labels will not be displayed either.

Implementation-wise, the label span is pushed onto the MultiSpan that was created when the diagnostic was constructed. However, the label span is not considered a “primary span”; only the Span supplied when creating the diagnostic is primary. See Diagnostic::span_label().

pub fn span_labels(
    &mut self,
    spans: impl IntoIterator<Item = Span>,
    label: impl AsRef<str>
) -> &mut Self

Labels all the given spans with the provided label. See Diagnostic::span_label() for more information. See Diagnostic::span_labels().

pub fn note_expected_found(
    &mut self,
    expected_label: &dyn Display,
    expected: DiagnosticStyledString,
    found_label: &dyn Display,
    found: DiagnosticStyledString
) -> &mut Self

See Diagnostic::note_expected_found().

pub fn note_expected_found_extra(
    &mut self,
    expected_label: &dyn Display,
    expected: DiagnosticStyledString,
    found_label: &dyn Display,
    found: DiagnosticStyledString,
    expected_extra: &dyn Display,
    found_extra: &dyn Display
) -> &mut Self

See Diagnostic::note_expected_found_extra().

pub fn note_unsuccessful_coercion(
    &mut self,
    expected: DiagnosticStyledString,
    found: DiagnosticStyledString
) -> &mut Self

See Diagnostic::note_unsuccessful_coercion().

pub fn note(&mut self, msg: impl Into<SubdiagnosticMessage>) -> &mut Self

See Diagnostic::note().

pub fn note_once(&mut self, msg: impl Into<SubdiagnosticMessage>) -> &mut Self

See Diagnostic::note_once().

pub fn span_note(
    &mut self,
    sp: impl Into<MultiSpan>,
    msg: impl Into<SubdiagnosticMessage>
) -> &mut Self

See Diagnostic::span_note().

pub fn span_note_once(
    &mut self,
    sp: impl Into<MultiSpan>,
    msg: impl Into<SubdiagnosticMessage>
) -> &mut Self

See Diagnostic::span_note_once().

pub fn warn(&mut self, msg: impl Into<SubdiagnosticMessage>) -> &mut Self

See Diagnostic::warn().

pub fn span_warn(
    &mut self,
    sp: impl Into<MultiSpan>,
    msg: impl Into<SubdiagnosticMessage>
) -> &mut Self

See Diagnostic::span_warn().

pub fn help(&mut self, msg: impl Into<SubdiagnosticMessage>) -> &mut Self

See Diagnostic::help().

pub fn span_help(
    &mut self,
    sp: impl Into<MultiSpan>,
    msg: impl Into<SubdiagnosticMessage>
) -> &mut Self

See Diagnostic::span_help().

pub fn help_use_latest_edition(&mut self) -> &mut Self

See Diagnostic::help_use_latest_edition().

pub fn set_is_lint(&mut self) -> &mut Self

See Diagnostic::set_is_lint().

pub fn disable_suggestions(&mut self) -> &mut Self

See Diagnostic::disable_suggestions().

pub fn clear_suggestions(&mut self) -> &mut Self

See Diagnostic::clear_suggestions().

pub fn multipart_suggestion(
    &mut self,
    msg: impl Into<SubdiagnosticMessage>,
    suggestion: Vec<(Span, String)>,
    applicability: Applicability
) -> &mut Self

See Diagnostic::multipart_suggestion().

pub fn multipart_suggestion_verbose(
    &mut self,
    msg: impl Into<SubdiagnosticMessage>,
    suggestion: Vec<(Span, String)>,
    applicability: Applicability
) -> &mut Self

See Diagnostic::multipart_suggestion_verbose().

pub fn tool_only_multipart_suggestion(
    &mut self,
    msg: impl Into<SubdiagnosticMessage>,
    suggestion: Vec<(Span, String)>,
    applicability: Applicability
) -> &mut Self

See Diagnostic::tool_only_multipart_suggestion().

pub fn span_suggestion(
    &mut self,
    sp: Span,
    msg: impl Into<SubdiagnosticMessage>,
    suggestion: impl ToString,
    applicability: Applicability
) -> &mut Self

See Diagnostic::span_suggestion().

pub fn span_suggestions(
    &mut self,
    sp: Span,
    msg: impl Into<SubdiagnosticMessage>,
    suggestions: impl IntoIterator<Item = String>,
    applicability: Applicability
) -> &mut Self

See Diagnostic::span_suggestions().

pub fn multipart_suggestions(
    &mut self,
    msg: impl Into<SubdiagnosticMessage>,
    suggestions: impl IntoIterator<Item = Vec<(Span, String)>>,
    applicability: Applicability
) -> &mut Self

See Diagnostic::multipart_suggestions().

pub fn span_suggestion_short(
    &mut self,
    sp: Span,
    msg: impl Into<SubdiagnosticMessage>,
    suggestion: impl ToString,
    applicability: Applicability
) -> &mut Self

See Diagnostic::span_suggestion_short().

pub fn span_suggestion_verbose(
    &mut self,
    sp: Span,
    msg: impl Into<SubdiagnosticMessage>,
    suggestion: impl ToString,
    applicability: Applicability
) -> &mut Self

See Diagnostic::span_suggestion_verbose().

pub fn span_suggestion_hidden(
    &mut self,
    sp: Span,
    msg: impl Into<SubdiagnosticMessage>,
    suggestion: impl ToString,
    applicability: Applicability
) -> &mut Self

See Diagnostic::span_suggestion_hidden().

pub fn tool_only_span_suggestion(
    &mut self,
    sp: Span,
    msg: impl Into<SubdiagnosticMessage>,
    suggestion: impl ToString,
    applicability: Applicability
) -> &mut Self

See Diagnostic::tool_only_span_suggestion().

pub fn set_primary_message(
    &mut self,
    msg: impl Into<DiagnosticMessage>
) -> &mut Self

See Diagnostic::set_primary_message().

pub fn set_span(&mut self, sp: impl Into<MultiSpan>) -> &mut Self

See Diagnostic::set_span().

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

See Diagnostic::code().

pub fn set_arg(
    &mut self,
    name: impl Into<Cow<'static, str>>,
    arg: impl IntoDiagnosticArg
) -> &mut Self

See Diagnostic::set_arg().

pub fn subdiagnostic(&mut self, subdiagnostic: impl AddToDiagnostic) -> &mut Self

See Diagnostic::subdiagnostic().

Methods from Deref<Target = Diagnostic>

pub fn level(&self) -> Level

pub fn is_error(&self) -> bool

pub fn update_unstable_expectation_id(
    &mut self,
    unstable_to_stable: &FxHashMap<LintExpectationId, LintExpectationId>
)

pub fn has_future_breakage(&self) -> bool

pub fn is_force_warn(&self) -> bool

pub fn downgrade_to_delayed_bug(&mut self) -> &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(
    &mut self,
    span: Span,
    label: impl Into<SubdiagnosticMessage>
) -> &mut Self

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. That means it will be shown together with the original span/label, not a span added by one of the span_{note,warn,help,suggestions} methods.

This span is not considered a “primary span”; only the Span supplied when creating the diagnostic is primary.

pub fn span_labels(
    &mut self,
    spans: impl IntoIterator<Item = Span>,
    label: impl AsRef<str>
) -> &mut Self

Labels all the given spans with the provided label. See Self::span_label() for more information.

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

pub fn note_expected_found(
    &mut self,
    expected_label: &dyn Display,
    expected: DiagnosticStyledString,
    found_label: &dyn Display,
    found: DiagnosticStyledString
) -> &mut Self

pub fn note_unsuccessful_coercion(
    &mut self,
    expected: DiagnosticStyledString,
    found: DiagnosticStyledString
) -> &mut Self

pub fn note_expected_found_extra(
    &mut self,
    expected_label: &dyn Display,
    expected: DiagnosticStyledString,
    found_label: &dyn Display,
    found: DiagnosticStyledString,
    expected_extra: &dyn Display,
    found_extra: &dyn Display
) -> &mut Self

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

pub fn note(&mut self, msg: impl Into<SubdiagnosticMessage>) -> &mut Self

Add a note attached to this diagnostic.

pub fn highlighted_note<M: Into<SubdiagnosticMessage>>(
    &mut self,
    msg: Vec<(M, Style)>
) -> &mut Self

pub fn note_once(&mut self, msg: impl Into<SubdiagnosticMessage>) -> &mut Self

Prints the span with a note above it. This is like Diagnostic::note(), but it gets its own span.

pub fn span_note<S: Into<MultiSpan>>(
    &mut self,
    sp: S,
    msg: impl Into<SubdiagnosticMessage>
) -> &mut Self

Prints the span with a note above it. This is like Diagnostic::note(), but it gets its own span.

pub fn span_note_once<S: Into<MultiSpan>>(
    &mut self,
    sp: S,
    msg: impl Into<SubdiagnosticMessage>
) -> &mut Self

Prints the span with a note above it. This is like Diagnostic::note(), but it gets its own span.

pub fn warn(&mut self, msg: impl Into<SubdiagnosticMessage>) -> &mut Self

Add a warning attached to this diagnostic.

pub fn span_warn<S: Into<MultiSpan>>(
    &mut self,
    sp: S,
    msg: impl Into<SubdiagnosticMessage>
) -> &mut Self

Prints the span with a warning above it. This is like Diagnostic::warn(), but it gets its own span.

pub fn help(&mut self, msg: impl Into<SubdiagnosticMessage>) -> &mut Self

Add a help message attached to this diagnostic.

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

Add a help message attached to this diagnostic with a customizable highlighted message.

pub fn span_help<S: Into<MultiSpan>>(
    &mut self,
    sp: S,
    msg: impl Into<SubdiagnosticMessage>
) -> &mut Self

Prints the span with some help above it. This is like Diagnostic::help(), but it gets its own span.

pub fn help_use_latest_edition(&mut self) -> &mut Self

Help the user upgrade to the latest edition. This is factored out to make sure it does the right thing with Cargo.toml.

pub fn disable_suggestions(&mut self) -> &mut Self

Disallow attaching suggestions this diagnostic. Any suggestions attached e.g. with the span_suggestion_* methods (before and after the call to disable_suggestions) will be ignored.

pub fn clear_suggestions(&mut self) -> &mut Self

Clear any existing suggestions.

fn push_suggestion(&mut self, suggestion: CodeSuggestion)

Helper for pushing to self.suggestions, if available (not disable).

pub fn multipart_suggestion(
    &mut self,
    msg: impl Into<SubdiagnosticMessage>,
    suggestion: Vec<(Span, String)>,
    applicability: Applicability
) -> &mut Self

Show a suggestion that has multiple parts to it. In other words, multiple changes need to be applied as part of this suggestion.

pub fn multipart_suggestion_verbose(
    &mut self,
    msg: impl Into<SubdiagnosticMessage>,
    suggestion: Vec<(Span, String)>,
    applicability: Applicability
) -> &mut Self

Show a suggestion that has multiple parts to it, always as it’s own subdiagnostic. In other words, multiple changes need to be applied as part of this suggestion.

pub fn multipart_suggestion_with_style(
    &mut self,
    msg: impl Into<SubdiagnosticMessage>,
    suggestion: Vec<(Span, String)>,
    applicability: Applicability,
    style: SuggestionStyle
) -> &mut Self

Diagnostic::multipart_suggestion() but you can set the SuggestionStyle.

pub fn tool_only_multipart_suggestion(
    &mut self,
    msg: impl Into<SubdiagnosticMessage>,
    suggestion: Vec<(Span, String)>,
    applicability: Applicability
) -> &mut Self

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: impl Into<SubdiagnosticMessage>,
    suggestion: impl ToString,
    applicability: Applicability
) -> &mut Self

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_suggestion_with_style(
    &mut self,
    sp: Span,
    msg: impl Into<SubdiagnosticMessage>,
    suggestion: impl ToString,
    applicability: Applicability,
    style: SuggestionStyle
) -> &mut Self

Diagnostic::span_suggestion() but you can set the SuggestionStyle.

pub fn span_suggestion_verbose(
    &mut self,
    sp: Span,
    msg: impl Into<SubdiagnosticMessage>,
    suggestion: impl ToString,
    applicability: Applicability
) -> &mut Self

Always show the suggested change.

pub fn span_suggestions(
    &mut self,
    sp: Span,
    msg: impl Into<SubdiagnosticMessage>,
    suggestions: impl IntoIterator<Item = String>,
    applicability: Applicability
) -> &mut Self

Prints out a message with multiple suggested edits of the code. See also Diagnostic::span_suggestion().

pub fn span_suggestions_with_style(
    &mut self,
    sp: Span,
    msg: impl Into<SubdiagnosticMessage>,
    suggestions: impl IntoIterator<Item = String>,
    applicability: Applicability,
    style: SuggestionStyle
) -> &mut Self

Diagnostic::span_suggestions() but you can set the SuggestionStyle.

pub fn multipart_suggestions(
    &mut self,
    msg: impl Into<SubdiagnosticMessage>,
    suggestions: impl IntoIterator<Item = Vec<(Span, String)>>,
    applicability: Applicability
) -> &mut Self

Prints out a message with multiple suggested edits of the code, where each edit consists of multiple parts. See also Diagnostic::multipart_suggestion().

pub fn span_suggestion_short(
    &mut self,
    sp: Span,
    msg: impl Into<SubdiagnosticMessage>,
    suggestion: impl ToString,
    applicability: Applicability
) -> &mut Self

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: impl Into<SubdiagnosticMessage>,
    suggestion: impl ToString,
    applicability: Applicability
) -> &mut Self

Prints out a message 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: impl Into<SubdiagnosticMessage>,
    suggestion: impl ToString,
    applicability: Applicability
) -> &mut Self

Adds a suggestion to the JSON output that will not be shown 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 subdiagnostic(&mut self, subdiagnostic: impl AddToDiagnostic) -> &mut Self

Add a subdiagnostic from a type that implements Subdiagnostic (see rustc_macros::Subdiagnostic).

pub fn eager_subdiagnostic(
    &mut self,
    handler: &Handler,
    subdiagnostic: impl AddToDiagnostic
) -> &mut Self

Add a subdiagnostic from a type that implements Subdiagnostic (see rustc_macros::Subdiagnostic). Performs eager translation of any translatable messages used in the subdiagnostic, so suitable for use with repeated messages (i.e. re-use of interpolated variables).

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

pub fn set_is_lint(&mut self) -> &mut Self

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

pub fn clear_code(&mut self) -> &mut Self

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

pub fn set_primary_message(
    &mut self,
    msg: impl Into<DiagnosticMessage>
) -> &mut Self

pub fn args<'a>(&'a self) -> impl Iterator<Item = DiagnosticArg<'a, 'static>>

pub fn set_arg(
    &mut self,
    name: impl Into<Cow<'static, str>>,
    arg: impl IntoDiagnosticArg
) -> &mut Self

pub fn replace_args(
    &mut self,
    args: FxHashMap<Cow<'static, str>, DiagnosticArgValue<'static>>
)

pub fn styled_message(&self) -> &[(DiagnosticMessage, Style)]

pub(crate) fn subdiagnostic_message_to_diagnostic_message(
    &self,
    attr: impl Into<SubdiagnosticMessage>
) -> DiagnosticMessage

Helper function that takes a SubdiagnosticMessage and returns a DiagnosticMessage by combining it with the primary message of the diagnostic (if translatable, otherwise it just passes the user’s string along).

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

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

Used by proc_macro_server for implementing server::Diagnostic.

fn sub_with_highlights<M: Into<SubdiagnosticMessage>>(
    &mut self,
    level: Level,
    message: Vec<(M, Style)>,
    span: MultiSpan,
    render_span: Option<MultiSpan>
)

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

fn keys(
    &self
) -> (&Level, &[(DiagnosticMessage, Style)], &Option<DiagnosticId>, &MultiSpan, &Result<Vec<CodeSuggestion>, SuggestionsDisabled>, Option<&[SubDiagnostic]>)

Fields used for Hash, and PartialEq trait

Trait Implementations

impl<'a, G: Clone + EmissionGuarantee> Clone for DiagnosticBuilder<'a, G>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<G: EmissionGuarantee> Debug for DiagnosticBuilder<'_, G>

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

Formats the value using the given formatter.

impl<G: EmissionGuarantee> Deref for DiagnosticBuilder<'_, G>

type Target = Diagnostic

The resulting type after dereferencing.

fn deref(&self) -> &Diagnostic

Dereferences the value.

impl<G: EmissionGuarantee> DerefMut for DiagnosticBuilder<'_, G>

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

Mutably dereferences the value.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference’s “Type Layout” chapter for details on type layout guarantees.

Size: 16 bytes