Struct rustc_errors::diagnostic::Diag

source ·
pub struct Diag<'a, G: EmissionGuarantee = ErrorGuaranteed> {
    pub dcx: &'a DiagCtxt,
    diag: Option<Box<DiagInner>>,
    _marker: PhantomData<G>,
}
Expand description

Used for emitting structured error messages and other diagnostic information. Wraps a DiagInner, adding some useful things.

  • The dcx field, allowing it to (a) emit itself, and (b) do a drop check that it has been emitted or cancelled.
  • The EmissionGuarantee, which determines the type returned from emit.

Each constructed Diag must be consumed by a function such as emit, cancel, delay_as_bug, or into_diag. A panic occurrs if a Diag is dropped without being consumed by one of these functions.

If there is some state in a downstream crate you would like to access in the methods of Diag here, consider extending DiagCtxtFlags.

Fields§

§dcx: &'a DiagCtxt§diag: Option<Box<DiagInner>>

Why the Option? It is always Some until the Diag is consumed via emit, cancel, etc. At that point it is consumed and replaced with None. Then drop checks that it is None; if not, it panics because a diagnostic was built but not used.

Why the Box? DiagInner is a large type, and Diag is often used as a return value, especially within the frequently-used PResult type. In theory, return value optimization (RVO) should avoid unnecessary copying. In practice, it does not (at the time of writing).

§_marker: PhantomData<G>

Implementations§

source§

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

source

pub fn new( dcx: &'a DiagCtxt, level: Level, message: impl Into<DiagMessage> ) -> Self

source

pub(crate) fn new_diagnostic(dcx: &'a DiagCtxt, diag: DiagInner) -> Self

Creates a new Diag with an already constructed diagnostic.

source

pub fn downgrade_to_delayed_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.

source

pub fn span_label( &mut self, span: Span, label: impl Into<SubdiagMessage> ) -> &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 Diag::span_label().

source

pub fn with_span_label( self, span: Span, label: impl Into<SubdiagMessage> ) -> 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 Diag::span_label().

source

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

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

source

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

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

source

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

source

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

source

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

source

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

source

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

Add a note attached to this diagnostic. See Diag::note().

source

pub fn with_note(self, msg: impl Into<SubdiagMessage>) -> Self

Add a note attached to this diagnostic. See Diag::note().

source

fn highlighted_note(&mut self, msg: Vec<StringPart>) -> &mut Self

source

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

This is like Diag::note(), but it’s only printed once.

source

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

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

source

pub fn with_span_note( self, sp: impl Into<MultiSpan>, msg: impl Into<SubdiagMessage> ) -> Self

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

source

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

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

source

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

Add a warning attached to this diagnostic. See Diag::warn().

source

pub fn with_warn(self, msg: impl Into<SubdiagMessage>) -> Self

Add a warning attached to this diagnostic. See Diag::warn().

source

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

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

source

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

Add a help message attached to this diagnostic. See Diag::help().

source

pub fn with_help(self, msg: impl Into<SubdiagMessage>) -> Self

Add a help message attached to this diagnostic. See Diag::help().

source

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

This is like Diag::help(), but it’s only printed once.

source

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

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

source

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

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

source

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.

source

fn push_suggestion(&mut self, suggestion: CodeSuggestion)

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

source

pub fn multipart_suggestion( &mut self, msg: impl Into<SubdiagMessage>, 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. See Diag::multipart_suggestion().

source

pub fn with_multipart_suggestion( self, msg: impl Into<SubdiagMessage>, suggestion: Vec<(Span, String)>, applicability: Applicability ) -> Self

Show a suggestion that has multiple parts to it. In other words, multiple changes need to be applied as part of this suggestion. See Diag::multipart_suggestion().

source

pub fn multipart_suggestion_verbose( &mut self, msg: impl Into<SubdiagMessage>, 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.

source

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

source

pub fn tool_only_multipart_suggestion( &mut self, msg: impl Into<SubdiagMessage>, 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.

source

pub fn span_suggestion( &mut self, sp: Span, msg: impl Into<SubdiagMessage>, 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. See Diag::span_suggestion().

source

pub fn with_span_suggestion( self, sp: Span, msg: impl Into<SubdiagMessage>, suggestion: impl ToString, applicability: Applicability ) -> 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. See Diag::span_suggestion().

source

pub fn span_suggestion_with_style( &mut self, sp: Span, msg: impl Into<SubdiagMessage>, suggestion: impl ToString, applicability: Applicability, style: SuggestionStyle ) -> &mut Self

source

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

Always show the suggested change. See Diag::span_suggestion_verbose().

source

pub fn with_span_suggestion_verbose( self, sp: Span, msg: impl Into<SubdiagMessage>, suggestion: impl ToString, applicability: Applicability ) -> Self

Always show the suggested change. See Diag::span_suggestion_verbose().

source

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

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

source

pub fn with_span_suggestions( self, sp: Span, msg: impl Into<SubdiagMessage>, suggestions: impl IntoIterator<Item = String>, applicability: Applicability ) -> Self

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

source

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

source

pub fn multipart_suggestions( &mut self, msg: impl Into<SubdiagMessage>, 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 Diag::multipart_suggestion().

source

pub fn span_suggestion_short( &mut self, sp: Span, msg: impl Into<SubdiagMessage>, 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. See Diag::span_suggestion_short().

source

pub fn with_span_suggestion_short( self, sp: Span, msg: impl Into<SubdiagMessage>, suggestion: impl ToString, applicability: Applicability ) -> 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. See Diag::span_suggestion_short().

source

pub fn span_suggestion_hidden( &mut self, sp: Span, msg: impl Into<SubdiagMessage>, 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.

source

pub fn tool_only_span_suggestion( &mut self, sp: Span, msg: impl Into<SubdiagMessage>, 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. See Diag::tool_only_span_suggestion().

source

pub fn with_tool_only_span_suggestion( self, sp: Span, msg: impl Into<SubdiagMessage>, suggestion: impl ToString, applicability: Applicability ) -> 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. See Diag::tool_only_span_suggestion().

source

pub fn subdiagnostic( &mut self, dcx: &DiagCtxt, subdiagnostic: impl Subdiagnostic ) -> &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).

source

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

Add a span. See Diag::span().

source

pub fn with_span(self, sp: impl Into<MultiSpan>) -> Self

Add a span. See Diag::span().

source

pub fn is_lint(&mut self, name: String, has_future_breakage: bool) -> &mut Self

source

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

Add an error code. See Diag::code().

source

pub fn with_code(self, code: ErrCode) -> Self

Add an error code. See Diag::code().

source

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

Add a primary message. See Diag::primary_message().

source

pub fn with_primary_message(self, msg: impl Into<DiagMessage>) -> Self

Add a primary message. See Diag::primary_message().

source

pub fn arg( &mut self, name: impl Into<DiagArgName>, arg: impl IntoDiagArg ) -> &mut Self

Add an argument. See Diag::arg().

source

pub fn with_arg( self, name: impl Into<DiagArgName>, arg: impl IntoDiagArg ) -> Self

Add an argument. See Diag::arg().

source

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

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

source

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

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

Used by proc_macro_server for implementing server::Diagnostic.

source

fn sub_with_highlights( &mut self, level: Level, messages: Vec<StringPart>, span: MultiSpan )

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

source

fn take_diag(&mut self) -> DiagInner

Takes the diagnostic. For use by methods that consume the Diag: emit, cancel, etc. Afterwards, drop is the only code that will be run on self.

source

fn emit_producing_nothing(self)

Most emit_producing_guarantee functions use this as a starting point.

source

fn emit_producing_error_guaranteed(self) -> ErrorGuaranteed

ErrorGuaranteed::emit_producing_guarantee uses this.

source

pub fn emit(self) -> G::EmitResult

Emit and consume the diagnostic.

source

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

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.

source

pub fn cancel(self)

Cancel and consume the diagnostic. (A diagnostic must either be emitted or cancelled or it will panic when dropped).

source

pub fn stash(self, span: Span, key: StashKey) -> Option<ErrorGuaranteed>

See DiagCtxt::stash_diagnostic for details.

source

pub fn delay_as_bug(self) -> G::EmitResult

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.

Methods from Deref<Target = DiagInner>§

source

pub fn level(&self) -> Level

source

pub fn is_error(&self) -> bool

source

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

source

pub(crate) fn has_future_breakage(&self) -> bool

Indicates whether this diagnostic should show up in cargo’s future breakage report.

source

pub(crate) fn is_force_warn(&self) -> bool

source

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

source

pub(crate) fn sub( &mut self, level: Level, message: impl Into<SubdiagMessage>, span: MultiSpan )

source

pub(crate) fn arg( &mut self, name: impl Into<DiagArgName>, arg: impl IntoDiagArg )

source

fn keys( &self ) -> (&Level, &[(DiagMessage, Style)], &Option<ErrCode>, &MultiSpan, &[Subdiag], &Result<Vec<CodeSuggestion>, SuggestionsDisabled>, Vec<(&DiagArgName, &DiagArgValue)>, &Option<IsLint>)

Fields used for Hash, and PartialEq trait.

Trait Implementations§

source§

impl<G> !Clone for Diag<'_, G>

1.0.0 · source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

§

type Target = DiagInner

The resulting type after dereferencing.
source§

fn deref(&self) -> &DiagInner

Dereferences the value.
source§

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

source§

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

Mutably dereferences the value.
source§

impl<G: EmissionGuarantee> Drop for Diag<'_, G>

Destructor bomb: every Diag must be consumed (emitted, cancelled, etc.) or we emit a bug.

source§

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

§

impl<'a, G> DynSend for Diag<'a, G>
where G: DynSend,

§

impl<'a, G> DynSync for Diag<'a, G>
where G: DynSync,

§

impl<'a, G> Freeze for Diag<'a, G>

§

impl<'a, G = ErrorGuaranteed> !RefUnwindSafe for Diag<'a, G>

§

impl<'a, G = ErrorGuaranteed> !Send for Diag<'a, G>

§

impl<'a, G = ErrorGuaranteed> !Sync for Diag<'a, G>

§

impl<'a, G> Unpin for Diag<'a, G>
where G: Unpin,

§

impl<'a, G = ErrorGuaranteed> !UnwindSafe for Diag<'a, G>

Blanket Implementations§

source§

impl<T> Aligned for T

source§

const ALIGN: Alignment = _

Alignment of Self.
source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T, R> CollectAndApply<T, R> for T

source§

fn collect_and_apply<I, F>(iter: I, f: F) -> R
where I: Iterator<Item = T>, F: FnOnce(&[T]) -> R,

Equivalent to f(&iter.collect::<Vec<_>>()).

§

type Output = R

source§

impl<T> Filterable for T

source§

fn filterable( self, filter_name: &'static str ) -> RequestFilterDataProvider<T, fn(_: DataRequest<'_>) -> bool>

Creates a filterable data provider with the given name for debugging. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Pointable for T

source§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

impl<'a, T> Captures<'a> for T
where T: ?Sized,

source§

impl<T> ErasedDestructor for T
where T: 'static,

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