Stabilize proc_macro Span::source_text

[jam1garner]

In the interest of improving error/diagnostic quality for macros I'd like to try and get some of the proc_macro_span feature stabilized.

While some of these APIs don't seem to have consensus on their effect on IDE/language server support, the source_text API seems both well-tested and to have consensus that its result only being invalidated by edits to the contents of the macro makes it a non-issue for IDE support (as noted by niko in #54725).

API

impl Span {
    pub fn source_text(&self) -> Option<String>;
}

@rustbot label +T-libs-api +A-macros +A-proc-macros

[joshtriplett]

Nominating to consider for partial stabilization.

I remember we had a lot of conversation about some of the proc_macro APIs in the past. I don't remember this one in particular being of concern.

Does anyone on @rust-lang/libs-api know of any blockers for stabilizing this?

[jhpratt]

Most of the discussion was related to either user-defined diagnostics or the line/column information being exposed. I see no reason this can't be stabilized.

[joshtriplett]

@rfcbot merge

[rfcbot]

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

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se
• @yaahc

Concerns:

• a question of line-endings resolved by Stabilize proc_macro Span::source_text #101991 (comment)
• span which escapes the macro resolved by Stabilize proc_macro Span::source_text #101991 (comment)

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.

[BurntSushi]

While some of these APIs don't seem to have consensus on their effect on IDE/language server support, the source_text API seems both well-tested and to have consensus that its result only being invalidated by edits to the contents of the macro makes it a non-issue for IDE support (as noted by niko in #54725).

@matklad Do you have thoughts here?

[BurntSushi]

It would be nice to have an example in the docs for this API, if possible.

One other thing that pops out at me is the return type of Option<String>. My guess is that perf isn't generally a huge concern in this context, and therefore it's okay. But I don't know that for sure. Otherwise, this return type is going to force a clone/allocation on every call. I don't know enough about proc macro internals to judge whether that's reasonable or not.

[matklad]

Yeah, I think getting the text of what's passed into a macro shouldn't be problematic. What could problematic is the macro somehow getting a span which "escapes" the macro (so, eg, the span for the whole file containing the macro) and querying the source of that, but I assume that's not possible.

There's also a question of line-endings. Does the returned text preserve original line-endings, or is it allowed to normalize to \n? I'd prefer to not expose original line endings.