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}