proc_macro: Stabilize Span::resolved_at and Span::located_at

[petrochenkov]

Introduced in #47149.
Part of #54725.

Motivation: #68716 (comment).
Identifiers in proc macros may want to inherit span locations for diagnostics from one tokens (e.g. some tokens from the macro input), but resolve those identifiers from some different location (e.g. from the macro's definition site).
This becomes especially important when multiple resolution locations become available with stabilization of Span::mixed_site.

Why I think this is the right API for setting span's location and hygiene - #69041 (comment).

r? @dtolnay

[jhpratt]

@SergioBenitez & @jebrosen may be interested in this as well.

[jebrosen]

Yes, I suspect rocket could leverage these APIs for the same reason given in #68716 (comment) (mainly, diagnostic reporting).

[petrochenkov]

There are a few alternatives in terms of naming and the function signatures here.
I think the status quo hits a sweet spot between them.

The primary alternative is some API looking like,

impl Span {
	fn set_location(&mut self, location: ???);
	fn set_hygiene_context(&mut self, hygiene_context: ???);
}

, which has some issues.

• We don't have stable types representing the location alone and the hygienic context alone.
  All our API is in terms of spans and it seems reasonable to keep the API surface minimal as it is now for both simplicity (less types less issues) and faster stabilization.
  This means the API will combine locations and hygiene from spans.

   impl Span {
   	fn set_location_from(&mut self, location: Span);
   	fn set_hygiene_context_from(&mut self, hygiene_context: Span);
   }
  

• The setter interface is just inconvenient in practice. Built-in macros in the compiler use similar location and hygiene combining a lot, and they eventually evolved to a functional-style API returning a new span rather than modifying the old one for ergonomics.

   impl Span {
   	fn with_location_from(&self, location: Span) -> Span;
   	fn with_hygiene_context_from(&mut self, hygiene_context: Span) -> Span;
   }
  

This kind of promises that Span is cheaply copyable, but we already kind of promise it because Span is already Copy.

• "Hygiene context" is too abstract, nobody knows what it means, the name should preferably tell what the user-visible consequences the choice of context has, and the primary consequence is where the identifier with that context is resolved from.

So, fn located_at and fn resolved_at are basically better worded alternatives of the previous variant.

let span = input_subspan.resolved_at(Span::def_site()); // Nice

[petrochenkov]

ping @dtolnay, this is waiting on you.

[dtolnay]

@rust-lang/libs @rust-lang/lang: This PR stabilizes these two methods of proc_macro::Span:

impl Span {
    /// Creates a new span with the same line/column information as `self` but
    /// that resolves symbols as though it were at `other`.
    pub fn resolved_at(&self, other: Span) -> Span;

    /// Creates a new span with the same name resolution behavior as `self` but
    /// with the line/column information of `other`.
    pub fn located_at(&self, other: Span) -> Span;
}

These are for mixing and matching the two pieces of information held by Span, source location and hygiene (≈ name resolution) context.

We have experience with these methods in Serde, e.g. serde-rs/serde@6457331. To take a look at one of the diffs from that commit:

- quote!(try!(_serde::de::SeqAccess::next_element::<#field_ty>(&mut __seq)))
+ let span = Span::def_site().located_at(field.original.span());
+ let func = quote_spanned!(span=> _serde::de::SeqAccess::next_element::<#field_ty>);
+ quote!(try!(#func(&mut __seq)))

In this code:

• Name resolution needs to happen at def_site, because the symbol _serde is defined as extern crate serde as _serde by the generated code and is not necessarily in scope at the call site, or if it is, it may refer to something different at the call site.
• But if the relevant Deserialize trait impl is missing on #field_ty, we would really like for that error to appear pointing to the correct field inside the user's struct at the call site.

The green implementation uses Span::located_at to combine def_site's hygiene context with the caller's field's source location to get compilable code that produces good error messages.

@rfcbot fcp merge

[rfcbot]

Team member @dtolnay has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @Centril
• @KodrAus
• @SimonSapin
• @cramertj
• @dtolnay
• @joshtriplett
• @nikomatsakis
• @pnkfelix
• @scottmcm
• @sfackler
• @withoutboats

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[Centril]

Reviewed, but do we have relevant tests for these methods? (i.e. as exposed, and not via tests exercising the deeper internal mechanism)

[petrochenkov]

Reviewed, but do we have relevant tests for these methods? (i.e. as exposed, and not via tests exercising the deeper internal mechanism)

No, we don't. I'll add a test.

[nikomatsakis]

@rfcbot reviewed

My feelings here are similar to my comments from mixed_site. I am gratified to hear that serde has been using these APIs to get a good user experience.

[petrochenkov]

Test is added.

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

The RFC will be merged soon.

[Amanieu]

@bors r+

[bors]

📌 Commit 966a295 has been approved by Amanieu

[bors]

⌛ Testing commit 966a295 with merge 0862458...

[ZanderBrown]

So maybe I'm being stupid but since this was merged on the 25th April shouldn't this be since = "1.44.0" what with 1.43.0 being released on the 23rd April

[jplatte]

With 1.43 released before this was merged, it's actually going to be stabilized in 1.45 (the GitHub milestone this PR is assigned to is also the one for 1.45). I've already opened #71574 to fix the attribute.

[ZanderBrown]

So I'm not crazy? Good to know :-)