Tracking issue for `proc_macro::Span` inspection APIs

[alexcrichton]

This issue is intended to track a number of unstable APIs which are used to inspect the contents of a Span for information like the file name, byte position, manufacturing new spans, combining them, etc.

This issue tracks the proc_macro_span unstable feature.

Public API

Already stabilized:

impl Span {
    // as `proc_macro_source_text`
    pub fn source_text(&self) -> Option<String>;

    // as `proc_macro_span_location`
    pub fn start(&self) -> Span;
    pub fn end(&self) -> Span;
    pub fn line(&self) -> usize;
    pub fn column(&self) -> usize;

    // as `proc_macro_span_file`
    pub fn file(&self) -> String; // Mapped file name, for display purposes.
    pub fn local_file(&self) -> Option<PathBuf>; // Real file name as it exists on disk.
}

impl Group {
    // as `proc_macro_group_span`
    pub fn span_open(&self) -> Span;
    pub fn span_close(&self) -> Span;
}

Close to stabilization, pending some bikeshedding:

impl Span {
    pub fn byte_range(&self) -> Range<usize>;
    // Open question: Do we want to use the old or new Range type?
}

Things that require more discussion:

impl Span {
    pub fn eq(&self, other: &Span) -> bool;
    pub fn join(&self, other: Span) -> Option<Span>;
    pub fn parent(&self) -> Option<Span>;
    pub fn source(&self) -> Span;
}

impl Literal {
    pub fn subspan<R: RangeBounds<usize>>(&self, range: R) -> Option<Span>;
}

History:

• Implementation
• Stabilization of proc_macro_source_text Stabilize proc_macro::Span::source_text #103197
• Stabilization of proc_macro_group_span Stabilize span_open() and span_close(). #86136
• Stabilization of proc_macro_span_location Stabilize proc_macro::Span::{start,end,line,column}. #139865
• Stabilization of proc_macro_span_file Stabilize proc_macro::Span::{file, local_file}. #140514

Unresolved questions

• API returning ranges should use the new Range type, or impl RangeBounds

[softprops]

I wanted to shed some pain this is causing with tarpaulin.

Tarpaulin has worked amazingly well for me and my company as a replacement for kcov which historically been a pain to get accurate, reliable and correct results. At the moment tarpaulin stands as the most promising goto option for codecoverage in rust and just feels more like the only first class tooling option.

Having one of those when choosing to invest in a technology is important for many company's adoption story for checking off code quantity checkmarks. When they see that rust doesn't have a reasonable code quality story that works on stable rust, that's can result in a "pass" rather than "I'll take it". There are currently some work arounds for making this work-ish on stable but it feels very much like the story serde was in a year or so ago when you wanted to show all your friends how amazing serde was but then was embarrassed to show what it took to make work on stable because of a macro stabilization blocker.

[JakeTherston]

With procedural macros having reached a point where they're very useful on stable, I expect many users will find themselves needing access to this information. Would it be reasonable to only stabilize parts of the Span API that are not too risky? Perhaps exposing a function that optionally returns the path of the file where a macro is invoked if such a file exists?