Skip to main content

buffa_codegen/
idents.rs

1//! Rust identifier and path construction helpers.
2//!
3//! These are shared between buffa's codegen and downstream code generators
4//! (e.g. `connectrpc-codegen`) that emit Rust code alongside buffa's message
5//! types and need identical keyword-escaping and path-tokenization behavior.
6//!
7//! The guarantee is that if buffa generates `pub struct r#type::Foo { ... }`,
8//! downstream callers using [`rust_path_to_tokens`]`("type::Foo")` produce the
9//! matching `r#type::Foo` reference.
10
11use proc_macro2::{Ident, Span, TokenStream};
12use quote::{format_ident, quote};
13
14/// Parse a `::`-separated Rust path string into a [`TokenStream`], using raw
15/// identifiers (`r#type`) for segments that are Rust keywords.
16///
17/// Used instead of `syn::parse_str::<syn::Type>` because the latter cannot
18/// handle raw identifiers in path position: `"google::type::LatLng"` would
19/// fail to parse because `type` is a keyword, but this function correctly
20/// produces `google::r#type::LatLng`.
21///
22/// Path-position keywords (`self`, `super`, `Self`, `crate`) are emitted as
23/// plain idents (they're valid in paths) — this differs from
24/// [`make_field_ident`], which suffixes them with `_`.
25///
26/// Leading `::` (absolute path, e.g. `"::buffa::Message"`) is preserved.
27///
28/// # Panics
29///
30/// Panics (in debug) if `path` is empty.
31pub fn rust_path_to_tokens(path: &str) -> TokenStream {
32    debug_assert!(
33        !path.is_empty(),
34        "rust_path_to_tokens called with empty path"
35    );
36
37    // Handle absolute paths (starting with `::`, e.g. extern crate paths).
38    let (prefix, rest) = if let Some(stripped) = path.strip_prefix("::") {
39        (quote! { :: }, stripped)
40    } else {
41        (TokenStream::new(), path)
42    };
43
44    // For path segments, non-raw-able keywords (`self`, `super`, `Self`,
45    // `crate`) are emitted as plain idents because they are valid in path
46    // position. This differs from `make_field_ident`, which appends `_` for
47    // these keywords since they are invalid as struct field names.
48    let segments: Vec<Ident> = rest
49        .split("::")
50        .map(|seg| {
51            if is_rust_keyword(seg) && can_be_raw_ident(seg) {
52                Ident::new_raw(seg, Span::call_site())
53            } else {
54                Ident::new(seg, Span::call_site())
55            }
56        })
57        .collect();
58
59    quote! { #prefix #(#segments)::* }
60}
61
62/// Create a field identifier, escaping Rust keywords.
63///
64/// Most keywords use raw identifiers (`r#type`). The keywords `self`, `super`,
65/// `Self`, `crate` cannot be raw identifiers and are suffixed with `_` instead
66/// (e.g. `self_`), matching prost's convention.
67///
68/// This is the escaping step alone. The member that buffa generates for a
69/// field or oneof can have another name: `idiomatic_field_names` converts the
70/// name first, and a keyword member next to a member named `self_` is
71/// `self__`.
72pub fn make_field_ident(name: &str) -> Ident {
73    if is_rust_keyword(name) {
74        if can_be_raw_ident(name) {
75            Ident::new_raw(name, Span::call_site())
76        } else {
77            format_ident!("{}_", name)
78        }
79    } else {
80        format_ident!("{}", name)
81    }
82}
83
84/// Returns the Rust name of a generated message or enum type.
85///
86/// A Rust keyword (`type`, `Self`) and the name of a primitive type that
87/// generated code uses (`bool`, `u32`, `str`) get a trailing `_`. A struct
88/// named `bool` would otherwise replace the primitive for every item in its
89/// module, including the code that derive macros expand there. Unlike a
90/// field name, which [`make_field_ident`] makes a raw identifier, a keyword
91/// gets the suffix: a derive macro that builds an identifier from the
92/// type's name, as `derive(Arbitrary)` does, panics on `r#type`. Any other
93/// name is returned unchanged.
94pub(crate) fn escape_type_name(name: &str) -> std::borrow::Cow<'_, str> {
95    if is_generated_primitive(name) || is_rust_keyword(name) {
96        std::borrow::Cow::Owned(format!("{name}_"))
97    } else {
98        std::borrow::Cow::Borrowed(name)
99    }
100}
101
102/// Returns the Rust name of a locally generated message or enum type:
103/// [`CodeGenConfig::type_name_prefix`](crate::CodeGenConfig::type_name_prefix),
104/// then the proto simple name, with [`escape_type_name`] applied to the two
105/// joined. Prefix `Pb` and `bool` give `Pbbool`, with the suffix left off.
106pub(crate) fn local_type_name(type_name_prefix: &str, proto_name: &str) -> String {
107    escape_type_name(&format!("{type_name_prefix}{proto_name}")).into_owned()
108}
109
110/// Is `name` a primitive type that generated code names without a path?
111///
112/// These are the Rust types of the proto scalars, plus `u8` and `usize`.
113/// The other primitive type names (`char`, `i8`, `u16`) are left out:
114/// generated code does not name them, so a message with one of those names
115/// compiles as written.
116fn is_generated_primitive(name: &str) -> bool {
117    matches!(
118        name,
119        "bool" | "str" | "u8" | "usize" | "i32" | "i64" | "u32" | "u64" | "f32" | "f64"
120    )
121}
122
123/// Convert a protobuf enum value name to `UpperCamelCase`.
124///
125/// Word boundaries are underscores **and** case transitions, so the conversion
126/// works on the canonical `SHOUTY_SNAKE_CASE` (`RULE_LEVEL_HIGH` → `RuleLevelHigh`)
127/// as well as non-canonical mixed-case inputs: a lower→upper transition starts a
128/// word (`myValue` → `MyValue`) and an acronym ends a word at the upper→lower
129/// transition (`HTTPServer` → `HttpServer`). Each word's first character is
130/// upper-cased and the rest lower-cased.
131///
132/// The conversion is intentionally lossy: `FOO_BAR` and `FOO__BAR` both collapse
133/// to `FooBar`, and `HTTPServer` and `HTTP_SERVER` both produce `HttpServer`. The
134/// caller is responsible for detecting the resulting collisions.
135///
136/// A leading digit in the output is only reachable when the caller has stripped
137/// a prefix first (e.g. `VERSION_2` → `2`); it is preserved verbatim, so callers
138/// that need a valid Rust identifier must check for it themselves.
139#[must_use]
140pub fn to_upper_camel_case(s: &str) -> String {
141    let chars: Vec<char> = s.chars().collect();
142    let mut out = String::new();
143    let mut start_of_word = true;
144    for (i, &ch) in chars.iter().enumerate() {
145        if ch == '_' {
146            start_of_word = true;
147            continue;
148        }
149        // Within a run of non-underscore characters, detect a word boundary at
150        // case transitions so mixed-case input splits correctly.
151        if !start_of_word && i > 0 {
152            let prev = chars[i - 1];
153            let lower_to_upper = prev.is_lowercase() && ch.is_uppercase();
154            let acronym_end = prev.is_uppercase()
155                && ch.is_uppercase()
156                && chars.get(i + 1).is_some_and(|c| c.is_lowercase());
157            if lower_to_upper || acronym_end {
158                start_of_word = true;
159            }
160        }
161        if start_of_word {
162            out.extend(ch.to_uppercase());
163            start_of_word = false;
164        } else {
165            out.extend(ch.to_lowercase());
166        }
167    }
168    out
169}
170
171/// Convert a type name to `SHOUTY_SNAKE_CASE`.
172///
173/// Used to reconstruct the conventional enum-value prefix from an enum's proto
174/// name so it can be stripped: `RuleLevel` → `RULE_LEVEL` (then values like
175/// `RULE_LEVEL_HIGH` lose the `RULE_LEVEL_` prefix). An underscore is inserted
176/// at each lower→upper boundary and at acronym→word boundaries
177/// (`HTTPServer` → `HTTP_SERVER`); existing underscores are preserved without
178/// doubling.
179#[must_use]
180pub fn to_shouty_snake_case(s: &str) -> String {
181    let chars: Vec<char> = s.chars().collect();
182    let mut out = String::new();
183    for (i, &ch) in chars.iter().enumerate() {
184        if ch == '_' {
185            out.push('_');
186            continue;
187        }
188        if i > 0 && ch.is_uppercase() && chars[i - 1] != '_' {
189            let prev = chars[i - 1];
190            let prev_starts_word = prev.is_lowercase() || prev.is_ascii_digit();
191            let acronym_boundary =
192                prev.is_uppercase() && chars.get(i + 1).is_some_and(|c| c.is_lowercase());
193            if prev_starts_word || acronym_boundary {
194                out.push('_');
195            }
196        }
197        out.extend(ch.to_uppercase());
198    }
199    out
200}
201
202/// Escape a proto package segment for use as a Rust `mod` name.
203///
204/// Returns `r#` prefix for raw-able keywords, `_` suffix for path-position
205/// keywords (which can't be raw), and the name as-is otherwise.
206///
207/// This is a `String` (not `Ident`) because callers typically emit it into
208/// source text (e.g. `pub mod {name} { ... }` via `format!`), not via `quote!`.
209pub fn escape_mod_ident(name: &str) -> String {
210    if is_rust_keyword(name) {
211        if can_be_raw_ident(name) {
212            format!("r#{name}")
213        } else {
214            format!("{name}_")
215        }
216    } else {
217        name.to_string()
218    }
219}
220
221/// Is `name` a Rust keyword (strict, edition-2018+, edition-2024+, or reserved)?
222///
223/// Covers all editions up to 2024. See `scripts/check-keywords.py` for the
224/// maintenance script that diffs this list against the upstream rustc source.
225pub fn is_rust_keyword(name: &str) -> bool {
226    matches!(
227        name,
228        // Strict keywords — all editions
229        "as" | "break"
230            | "const"
231            | "continue"
232            | "crate"
233            | "else"
234            | "enum"
235            | "extern"
236            | "false"
237            | "fn"
238            | "for"
239            | "if"
240            | "impl"
241            | "in"
242            | "let"
243            | "loop"
244            | "match"
245            | "mod"
246            | "move"
247            | "mut"
248            | "pub"
249            | "ref"
250            | "return"
251            | "self"
252            | "Self"
253            | "static"
254            | "struct"
255            | "super"
256            | "trait"
257            | "true"
258            | "type"
259            | "unsafe"
260            | "use"
261            | "where"
262            | "while"
263            // Strict keywords — edition 2018+
264            | "async"
265            | "await"
266            | "dyn"
267            // Strict keywords — edition 2024+
268            | "gen"
269            // Reserved for future use (all editions)
270            | "abstract"
271            | "become"
272            | "box"
273            | "do"
274            | "final"
275            | "macro"
276            | "override"
277            | "priv"
278            | "try"
279            | "typeof"
280            | "unsized"
281            | "virtual"
282            | "yield"
283    )
284}
285
286/// The keywords that cannot be raw identifiers. They are valid path segments,
287/// so `r#self` is rejected; they get a `_` suffix in field/mod position
288/// instead.
289pub(crate) const SUFFIX_ESCAPED_KEYWORDS: [&str; 4] = ["self", "super", "Self", "crate"];
290
291/// Can `name` be used as a raw identifier (`r#name`)?
292fn can_be_raw_ident(name: &str) -> bool {
293    !SUFFIX_ESCAPED_KEYWORDS.contains(&name)
294}
295
296/// Whether [`make_field_ident`] escapes `name` with a `_` suffix: a keyword
297/// that cannot be a raw identifier.
298pub(crate) fn is_suffix_escaped(name: &str) -> bool {
299    is_rust_keyword(name) && !can_be_raw_ident(name)
300}
301
302#[cfg(test)]
303mod tests {
304    use super::*;
305
306    #[test]
307    fn rust_path_simple() {
308        assert_eq!(rust_path_to_tokens("Foo").to_string(), "Foo");
309    }
310
311    #[test]
312    fn rust_path_nested() {
313        assert_eq!(
314            rust_path_to_tokens("foo::bar::Baz").to_string(),
315            "foo :: bar :: Baz"
316        );
317    }
318
319    #[test]
320    fn rust_path_keyword_segment() {
321        // `type` is a keyword → raw identifier.
322        assert_eq!(
323            rust_path_to_tokens("google::type::LatLng").to_string(),
324            "google :: r#type :: LatLng"
325        );
326    }
327
328    #[test]
329    fn rust_path_absolute() {
330        assert_eq!(
331            rust_path_to_tokens("::buffa::Message").to_string(),
332            ":: buffa :: Message"
333        );
334    }
335
336    #[test]
337    fn rust_path_super_segment() {
338        // `super` is valid in path position → plain ident (no r# or _).
339        assert_eq!(
340            rust_path_to_tokens("super::super::Foo").to_string(),
341            "super :: super :: Foo"
342        );
343    }
344
345    #[test]
346    fn type_name_escape() {
347        for name in [
348            "bool", "str", "u8", "usize", "i32", "i64", "u32", "u64", "f32", "f64",
349        ] {
350            assert_eq!(escape_type_name(name), format!("{name}_"), "{name}");
351        }
352        for name in ["Self", "self", "super", "crate", "type", "match", "async"] {
353            assert_eq!(escape_type_name(name), format!("{name}_"), "{name}");
354        }
355        // Case-sensitive. Generated code does not name the last six, so they
356        // stay as written.
357        for name in [
358            "Bool", "U32", "Str", "Crate", "Type", "Foo", "char", "i8", "u16", "i128", "isize",
359            "f16",
360        ] {
361            assert_eq!(escape_type_name(name), name, "{name}");
362        }
363    }
364
365    #[test]
366    fn local_type_name_escapes_the_prefixed_name() {
367        assert_eq!(local_type_name("", "bool"), "bool_");
368        assert_eq!(local_type_name("", "type"), "type_");
369        assert_eq!(local_type_name("Pb", "bool"), "Pbbool");
370        assert_eq!(local_type_name("Pb", "type"), "Pbtype");
371        assert_eq!(local_type_name("Pb", "Foo"), "PbFoo");
372    }
373
374    #[test]
375    fn field_ident_normal() {
376        assert_eq!(make_field_ident("foo").to_string(), "foo");
377    }
378
379    #[test]
380    fn field_ident_keyword() {
381        assert_eq!(make_field_ident("type").to_string(), "r#type");
382    }
383
384    #[test]
385    fn field_ident_non_raw_keyword() {
386        // `self` can't be r#self → suffixed.
387        assert_eq!(make_field_ident("self").to_string(), "self_");
388        assert_eq!(make_field_ident("super").to_string(), "super_");
389        assert_eq!(make_field_ident("crate").to_string(), "crate_");
390        assert_eq!(make_field_ident("Self").to_string(), "Self_");
391    }
392
393    #[test]
394    fn escape_mod_normal() {
395        assert_eq!(escape_mod_ident("foo"), "foo");
396    }
397
398    #[test]
399    fn escape_mod_keyword() {
400        assert_eq!(escape_mod_ident("type"), "r#type");
401        assert_eq!(escape_mod_ident("async"), "r#async");
402    }
403
404    #[test]
405    fn escape_mod_non_raw_keyword() {
406        assert_eq!(escape_mod_ident("self"), "self_");
407        assert_eq!(escape_mod_ident("super"), "super_");
408    }
409
410    #[test]
411    fn upper_camel_basic() {
412        assert_eq!(to_upper_camel_case("RULE_LEVEL_HIGH"), "RuleLevelHigh");
413        assert_eq!(to_upper_camel_case("UNKNOWN"), "Unknown");
414        assert_eq!(to_upper_camel_case("low_priority"), "LowPriority");
415        assert_eq!(to_upper_camel_case("HTTP_SERVER"), "HttpServer");
416    }
417
418    #[test]
419    fn upper_camel_lossy_collisions() {
420        // Doubled and absent underscores collapse to the same identifier — the
421        // caller must detect this.
422        assert_eq!(to_upper_camel_case("FOO_BAR"), "FooBar");
423        assert_eq!(to_upper_camel_case("FOO__BAR"), "FooBar");
424        // Acronym vs snake also collapse — both must resolve to one identifier
425        // so the caller can detect the collision.
426        assert_eq!(to_upper_camel_case("HTTPServer"), "HttpServer");
427        assert_eq!(to_upper_camel_case("HTTP_SERVER"), "HttpServer");
428    }
429
430    #[test]
431    fn upper_camel_mixed_case_input() {
432        // Case transitions are word boundaries, so an already-CamelCase value
433        // round-trips (and is later skipped as a redundant alias).
434        assert_eq!(to_upper_camel_case("MyValue"), "MyValue");
435        assert_eq!(to_upper_camel_case("fooBar"), "FooBar");
436        assert_eq!(to_upper_camel_case("Active"), "Active");
437    }
438
439    #[test]
440    fn upper_camel_digit_and_empty() {
441        // Reachable only after a prefix strip; preserved verbatim for the
442        // caller's validity check.
443        assert_eq!(to_upper_camel_case("2"), "2");
444        assert_eq!(to_upper_camel_case(""), "");
445        assert_eq!(to_upper_camel_case("FOO_2"), "Foo2");
446    }
447
448    #[test]
449    fn upper_camel_keyword_source() {
450        // `SELF` folds to the keyword `Self`; identifier escaping is the
451        // caller's job (via `make_field_ident`).
452        assert_eq!(to_upper_camel_case("SELF"), "Self");
453    }
454
455    #[test]
456    fn shouty_snake_basic() {
457        assert_eq!(to_shouty_snake_case("RuleLevel"), "RULE_LEVEL");
458        assert_eq!(to_shouty_snake_case("NullValue"), "NULL_VALUE");
459        assert_eq!(to_shouty_snake_case("Type"), "TYPE");
460    }
461
462    #[test]
463    fn shouty_snake_acronym() {
464        assert_eq!(to_shouty_snake_case("HTTPServer"), "HTTP_SERVER");
465    }
466
467    #[test]
468    fn shouty_snake_already_snakey() {
469        // Idempotent on names that already carry underscores.
470        assert_eq!(to_shouty_snake_case("RULE_LEVEL"), "RULE_LEVEL");
471    }
472
473    #[test]
474    fn keyword_coverage() {
475        assert!(is_rust_keyword("type"));
476        assert!(is_rust_keyword("async"));
477        assert!(is_rust_keyword("gen")); // 2024
478        assert!(is_rust_keyword("yield")); // reserved
479        assert!(!is_rust_keyword("foo"));
480        assert!(!is_rust_keyword("Type")); // case-sensitive
481    }
482}