Skip to main content

raf_source/
verbatim.rs

1// SPDX-FileCopyrightText: 2026 Blackcat InformaticsĀ® Inc. <paudley@blackcatinformatics.ca>
2// SPDX-License-Identifier: MIT OR Apache-2.0 OR MulanPSL-2.0
3
4//! The items that rustc parses and syn has no node for, returned as tokens.
5//!
6//! syn gives `Item::Verbatim` or `ImplItem::Verbatim` for an item it parses
7//! but has no node for. Three such shapes are read here, from the tokens syn
8//! kept, so each token keeps the span it has in the file:
9//!
10//! * a `use` whose tree is a braced group with a member that starts with `::`
11//!   (`pub use { ::std::fmt::Debug as D, crate::a::f };`), which is read as one
12//!   `use` per member, each with the attributes and visibility of the whole;
13//! * a function with no body (`#[ref_cast_custom] pub fn f(x: &T) -> &Self;`),
14//!   the input of an attribute macro, at item level or in an impl block;
15//! * a type with no definition (`#[ty] type bool;`), likewise.
16//!
17//! Other shapes can supply a disabled-syntax observation when an outer
18//! `cfg(any())` proves they have no active declaration.
19//!
20//! The tokens of one item are parsed again after the parse of its file, which
21//! built and dropped the same nodes before it kept the tokens, so what the
22//! second parse holds at once stays within what the first held. The facts
23//! it gives are charged as those of the plain items they stand for.
24
25use proc_macro2::TokenStream;
26use syn::parse::{ParseStream, Parser as _};
27use syn::{
28    Attribute, ForeignItemFn, ForeignItemType, MacroDelimiter, Meta, Token, UseTree, Visibility,
29    braced, token,
30};
31
32/// A verbatim item of a module that the index reads.
33pub(crate) enum Verbatim {
34    /// A braced `use` group, each member read as its own declaration.
35    UseGroup(UseGroup),
36    /// An item with no body.
37    Bodiless(Bodiless),
38}
39
40/// `#[attrs] vis use { member, ... };`.
41pub(crate) struct UseGroup {
42    /// The attributes of the whole declaration.
43    pub(crate) attrs: Vec<Attribute>,
44    /// The visibility of the whole declaration.
45    pub(crate) vis: Visibility,
46    /// The members, in order.
47    pub(crate) members: Vec<UseMember>,
48}
49
50/// One member of a `use` group.
51pub(crate) struct UseMember {
52    /// True when the member starts with `::`.
53    pub(crate) leading_colon: bool,
54    /// The tree after any leading `::`.
55    pub(crate) tree: UseTree,
56}
57
58/// An item with no body, of a module or an impl block.
59pub(crate) enum Bodiless {
60    /// A function with no body.
61    Fn(Box<ForeignItemFn>),
62    /// A type with no definition.
63    Type(Box<ForeignItemType>),
64}
65
66/// Read the tokens of a verbatim item of a module, or `None` for a shape that
67/// is not read.
68pub(crate) fn item(tokens: &TokenStream) -> Option<Verbatim> {
69    match split_use_group.parse2(tokens.clone()) {
70        Ok(group) => Some(Verbatim::UseGroup(group)),
71        Err(_) => member(tokens).map(Verbatim::Bodiless),
72    }
73}
74
75/// Read the members of a grouped import represented by syn as verbatim tokens.
76/// The visitor receives the original attributes and spans, with an independent
77/// leading-colon flag for every member. Other token shapes return `false`.
78pub fn visit_grouped_import(
79    tokens: &TokenStream,
80    mut visitor: impl FnMut(&[Attribute], bool, &UseTree),
81) -> bool {
82    let Ok(group) = split_use_group.parse2(tokens.clone()) else {
83        return false;
84    };
85    for member in &group.members {
86        visitor(&group.attrs, member.leading_colon, &member.tree);
87    }
88    true
89}
90
91/// Read the tokens of a verbatim member of an impl block, which holds no
92/// `use`, or `None` for a shape that is not read.
93pub(crate) fn member(tokens: &TokenStream) -> Option<Bodiless> {
94    if let Ok(f) = syn::parse2::<ForeignItemFn>(tokens.clone()) {
95        return Some(Bodiless::Fn(Box::new(f)));
96    }
97    syn::parse2::<ForeignItemType>(tokens.clone())
98        .ok()
99        .map(|t| Bodiless::Type(Box::new(t)))
100}
101
102/// Read only the outer configuration proof of an opaque declaration.
103pub(crate) fn definitely_disabled(tokens: &TokenStream) -> bool {
104    let parse = |input: ParseStream<'_>| {
105        let attributes = input.call(Attribute::parse_outer)?;
106        let _: TokenStream = input.parse()?;
107        Ok(attributes.iter().any(|attribute| {
108            matches!(
109                &attribute.meta,
110                Meta::List(cfg) if cfg.path.is_ident("cfg")
111                    && matches!(cfg.delimiter, MacroDelimiter::Paren(_))
112            ) && matches!(
113                attribute.parse_args::<Meta>(),
114                Ok(Meta::List(any)) if any.path.is_ident("any")
115                    && matches!(any.delimiter, MacroDelimiter::Paren(_))
116                    && any.tokens.is_empty()
117            )
118        }))
119    };
120    parse.parse2(tokens.clone()).unwrap_or(false)
121}
122
123/// `#[attrs] vis use { member, ... };`, each member an optional leading `::`
124/// and a use tree, or a braced group of such members, which binds what its
125/// members bind. A group under a path is read by syn as usual, so a leading
126/// `::` inside it is not accepted, as rustc does not accept it either.
127fn split_use_group(input: ParseStream<'_>) -> syn::Result<UseGroup> {
128    let attrs = input.call(Attribute::parse_outer)?;
129    let vis: Visibility = input.parse()?;
130    input.parse::<Token![use]>()?;
131    let content;
132    braced!(content in input);
133    input.parse::<Token![;]>()?;
134    let mut members = Vec::new();
135    split_members(&content, &mut members)?;
136    Ok(UseGroup {
137        attrs,
138        vis,
139        members,
140    })
141}
142
143/// The members of the braced group `content`, with those of every bare
144/// group in it, in order. The recursion is as deep as the nesting of the
145/// braces, which the pre-scan bounds and syn has already parsed.
146fn split_members(content: ParseStream<'_>, members: &mut Vec<UseMember>) -> syn::Result<()> {
147    while !content.is_empty() {
148        if content.peek(token::Brace) {
149            let inner;
150            braced!(inner in content);
151            split_members(&inner, members)?;
152        } else {
153            let leading_colon = content.parse::<Option<Token![::]>>()?.is_some();
154            let tree: UseTree = content.parse()?;
155            members.push(UseMember {
156                leading_colon,
157                tree,
158            });
159        }
160        if content.is_empty() {
161            break;
162        }
163        content.parse::<Token![,]>()?;
164    }
165    Ok(())
166}
167
168#[cfg(test)]
169mod tests {
170    use super::{Bodiless, Verbatim, item, member};
171
172    fn tokens(text: &str) -> proc_macro2::TokenStream {
173        text.parse().expect("tokens")
174    }
175
176    #[test]
177    fn a_use_group_splits_into_one_use_per_member() {
178        let Some(Verbatim::UseGroup(group)) = item(&tokens(
179            "#[cfg(x)] pub use { ::std::fmt::Debug as D, crate::a::{f, g}, };",
180        )) else {
181            panic!("not a use group");
182        };
183        assert_eq!(group.members.len(), 2);
184        assert!(group.members[0].leading_colon);
185        assert!(!group.members[1].leading_colon);
186        assert_eq!(group.attrs.len(), 1);
187        assert!(matches!(group.vis, syn::Visibility::Public(_)));
188    }
189
190    #[test]
191    fn a_bare_group_in_a_use_group_contributes_its_members() {
192        let Some(Verbatim::UseGroup(group)) =
193            item(&tokens("use { a::f, { ::b::c, { ::d::e } }, {} };"))
194        else {
195            panic!("not a use group");
196        };
197        let colons: Vec<bool> = group.members.iter().map(|m| m.leading_colon).collect();
198        assert_eq!(colons, [false, true, true]);
199    }
200
201    #[test]
202    fn a_use_group_is_not_read_in_an_impl_block() {
203        assert!(member(&tokens("use { ::a::b };")).is_none());
204    }
205
206    #[test]
207    fn bodiless_functions_and_types_are_read() {
208        assert!(matches!(
209            item(&tokens("#[m] pub(crate) const fn f(x: &str) -> &Self;")),
210            Some(Verbatim::Bodiless(Bodiless::Fn(_)))
211        ));
212        assert!(matches!(
213            member(&tokens("#[ty(cast)] type bool;")),
214            Some(Bodiless::Type(_))
215        ));
216    }
217
218    #[test]
219    fn other_shapes_are_not_read() {
220        for text in [
221            "trait Alias = Send;",
222            "use { a::{::b} };",
223            "use { ::a::b } extra;",
224            "use ::{ ::a::b };",
225            "const X: u8;",
226            "type T: Bound;",
227            "impl Tr for T;",
228        ] {
229            assert!(item(&tokens(text)).is_none(), "{text}");
230        }
231    }
232}