facet_macro_types/lib.rs
1//! TeamDman-maintained fork of [facet-macro-types](https://github.com/facet-rs/facet/tree/65bae5c31a7ce401bc44630fb96250ea884cfd3e/facet-macro-types), published as
2//! [teamy-facet-macro-types](https://crates.io/crates/teamy-facet-macro-types).
3//! This fork uses its own Facet crate identities; use matching Teamy packages.
4//! Upstream MIT OR Apache-2.0 licensing and attribution are retained.
5//! See the [release notes](https://github.com/TeamDman/facet/blob/teamy-main/TEAMY_RELEASE.md).
6//!
7//! # Facet Macro Types
8//!
9//! Unsynn grammar and type definitions for the facet macro ecosystem.
10//!
11//! This crate provides the foundational parsing infrastructure used by facet's
12//! derive macros. It includes:
13//!
14//! - Unsynn grammar definitions for parsing Rust struct and enum definitions
15//! - RenameRule for field/variant name transformations
16//! - Helper types like LifetimeName for code generation
17
18// unsynn's Parser API intentionally returns its large Error by value.
19#![allow(clippy::result_large_err)]
20#![warn(missing_docs)]
21#![allow(uncommon_codepoints)]
22
23// ============================================================================
24// RE-EXPORTS FROM UNSYNN
25// ============================================================================
26
27pub use unsynn::*;
28
29use std::ops::Deref;
30
31// ============================================================================
32// KEYWORDS AND OPERATORS
33// ============================================================================
34
35keyword! {
36 /// The "pub" keyword.
37 pub KPub = "pub";
38 /// The "struct" keyword.
39 pub KStruct = "struct";
40 /// The "enum" keyword.
41 pub KEnum = "enum";
42 /// The "doc" keyword.
43 pub KDoc = "doc";
44 /// The "repr" keyword.
45 pub KRepr = "repr";
46 /// The "crate" keyword.
47 pub KCrate = "crate";
48 /// The "in" keyword.
49 pub KIn = "in";
50 /// The "const" keyword.
51 pub KConst = "const";
52 /// The "where" keyword.
53 pub KWhere = "where";
54 /// The "mut" keyword.
55 pub KMut = "mut";
56 /// The "facet" keyword.
57 pub KFacet = "facet";
58}
59
60impl KWhere {
61 /// Returns the span of this keyword
62 pub fn span(&self) -> proc_macro2::Span {
63 self.0.deref().span()
64 }
65}
66
67operator! {
68 /// Represents the '=' operator.
69 pub Eq = "=";
70 /// Represents the ';' operator.
71 pub Semi = ";";
72 /// Represents the apostrophe '\'' operator.
73 pub Apostrophe = "'";
74 /// Represents the double semicolon '::' operator.
75 pub DoubleSemicolon = "::";
76}
77
78// ============================================================================
79// HELPER TYPES
80// ============================================================================
81
82/// Parses tokens and groups until `C` is found on the current token tree level.
83pub type VerbatimUntil<C> = Many<Cons<Except<C>, AngleTokenTree>>;
84
85/// Represents a module path, consisting of an optional path separator followed by
86/// a path-separator-delimited sequence of identifiers.
87pub type ModPath = Cons<Option<PathSep>, PathSepDelimited<Ident>>;
88
89/// Represents type bounds, consisting of a colon followed by tokens until
90/// a comma, equals sign, or closing angle bracket is encountered.
91pub type Bounds = Cons<Colon, VerbatimUntil<Either<Comma, Eq, Gt>>>;
92
93// ============================================================================
94// UNSYNN GRAMMAR
95// ============================================================================
96
97unsynn! {
98 /// Parses either a `TokenTree` or `<...>` grouping (which is not a [`Group`] as far as proc-macros
99 /// are concerned).
100 #[derive(Clone)]
101 pub struct AngleTokenTree(
102 #[allow(clippy::type_complexity)] // look,
103 pub Either<Cons<Lt, Vec<Cons<Except<Gt>, AngleTokenTree>>, Gt>, TokenTree>,
104 );
105
106 /// Represents an algebraic data type (ADT) declaration, which can be either a struct or enum.
107 pub enum AdtDecl {
108 /// A struct ADT variant.
109 Struct(Struct),
110 /// An enum ADT variant.
111 Enum(Enum),
112 }
113
114 /// Represents visibility modifiers for items.
115 pub enum Vis {
116 /// `pub(in? crate::foo::bar)`/`pub(in? ::foo::bar)`
117 PubIn(Cons<KPub, ParenthesisGroupContaining<Cons<Option<KIn>, ModPath>>>),
118 /// Public visibility, indicated by the "pub" keyword.
119 Pub(KPub),
120 }
121
122 /// Represents an attribute annotation on a field, typically in the form `#[attr]`.
123 pub struct Attribute {
124 /// The pound sign preceding the attribute.
125 pub _pound: Pound,
126 /// The content of the attribute enclosed in square brackets.
127 pub body: BracketGroupContaining<AttributeInner>,
128 }
129
130 /// Represents the inner content of an attribute annotation.
131 pub enum AttributeInner {
132 /// A facet attribute that can contain specialized metadata.
133 Facet(FacetAttr),
134 /// A documentation attribute typically used for generating documentation.
135 Doc(DocInner),
136 /// A representation attribute that specifies how data should be laid out.
137 Repr(ReprInner),
138 /// Any other attribute represented as a sequence of token trees.
139 Any(Vec<TokenTree>),
140 }
141
142 /// Represents a facet attribute that can contain specialized metadata.
143 pub struct FacetAttr {
144 /// The keyword for the facet attribute.
145 pub _facet: KFacet,
146 /// The inner content of the facet attribute.
147 pub inner: ParenthesisGroupContaining<CommaDelimitedVec<FacetInner>>,
148 }
149
150 /// Represents the inner content of a facet attribute.
151 ///
152 /// All attributes are now parsed uniformly - either namespaced (`xml::element`)
153 /// or simple (`sensitive`, `rename = "foo"`). The grammar system determines
154 /// what's valid, not hardcoded keywords.
155 pub enum FacetInner {
156 /// A namespaced attribute like `xml::element` or `xml::ns = "http://example.com"`
157 Namespaced(NamespacedAttr),
158 /// A where clause attribute like `where T: Clone`
159 Where(WhereAttr),
160 /// A non-namespaced (builtin) attribute like `sensitive` or `rename = "foo"`
161 Simple(SimpleAttr),
162 }
163
164 /// A where clause attribute like `where T: Clone + Send`
165 pub struct WhereAttr {
166 /// The `where` keyword.
167 pub _kw_where: KWhere,
168 /// The bounds (everything after `where`)
169 pub bounds: VerbatimUntil<EndOfStream>,
170 }
171
172 /// A namespaced attribute like `xml::element` or `xml::ns = "http://example.com"`
173 pub struct NamespacedAttr {
174 /// The namespace (e.g., "xml", "args")
175 pub ns: Ident,
176 /// The path separator ::
177 pub _sep: PathSep,
178 /// The key (e.g., "element", "short")
179 pub key: Ident,
180 /// Optional arguments - either in parentheses like `(args)` or with equals like `= value`
181 pub args: Option<AttrArgs>,
182 }
183
184 /// A simple (builtin) attribute like `sensitive` or `rename = "foo"`
185 pub struct SimpleAttr {
186 /// The key (e.g., "sensitive", "rename")
187 pub key: Ident,
188 /// Optional arguments - either in parentheses like `(args)` or with equals like `= value`
189 pub args: Option<AttrArgs>,
190 }
191
192 /// Arguments for attributes - either parenthesized `(args)` or with equals `= value`
193 pub enum AttrArgs {
194 /// Parenthesized arguments like `(auto_increment)`
195 Parens(ParenthesisGroupContaining<Vec<TokenTree>>),
196 /// Equals-style arguments like `= 'v'`
197 Equals(AttrEqualsArgs),
198 }
199
200 /// Equals-style arguments like `= 'v'` or `= "value"`
201 pub struct AttrEqualsArgs {
202 /// The equals sign
203 pub _eq: Eq,
204 /// The value (tokens until comma or end)
205 pub value: VerbatimUntil<Comma>,
206 }
207
208 /// Represents documentation for an item.
209 pub struct DocInner {
210 /// The "doc" keyword.
211 pub _kw_doc: KDoc,
212 /// The equality operator.
213 pub _eq: Eq,
214 /// The documentation content as a literal string.
215 pub value: LiteralString,
216 }
217
218 /// Represents the inner content of a `repr` attribute, typically used for specifying
219 /// memory layout or representation hints.
220 pub struct ReprInner {
221 /// The "repr" keyword.
222 pub _kw_repr: KRepr,
223 /// The representation attributes enclosed in parentheses.
224 pub attr: ParenthesisGroupContaining<CommaDelimitedVec<Ident>>,
225 }
226
227 /// Represents a struct definition.
228 pub struct Struct {
229 /// Attributes applied to the struct.
230 pub attributes: Vec<Attribute>,
231 /// The visibility modifier of the struct (e.g., `pub`).
232 pub _vis: Option<Vis>,
233 /// The "struct" keyword.
234 pub _kw_struct: KStruct,
235 /// The name of the struct.
236 pub name: Ident,
237 /// Generic parameters for the struct, if any.
238 pub generics: Option<GenericParams>,
239 /// The variant of struct (unit, tuple, or regular struct with named fields).
240 pub kind: StructKind,
241 }
242
243 /// Represents the generic parameters of a struct or enum definition, enclosed in angle brackets.
244 /// e.g., `<'a, T: Trait, const N: usize>`.
245 pub struct GenericParams {
246 /// The opening angle bracket `<`.
247 pub _lt: Lt,
248 /// The comma-delimited list of generic parameters.
249 pub params: CommaDelimitedVec<GenericParam>,
250 /// The closing angle bracket `>`.
251 pub _gt: Gt,
252 }
253
254 /// Represents a single generic parameter within a `GenericParams` list.
255 pub enum GenericParam {
256 /// A lifetime parameter, e.g., `'a` or `'a: 'b + 'c`.
257 Lifetime {
258 /// The lifetime identifier (e.g., `'a`).
259 name: Lifetime,
260 /// Optional lifetime bounds (e.g., `: 'b + 'c`).
261 bounds: Option<Cons<Colon, VerbatimUntil<Either<Comma, Gt>>>>,
262 },
263 /// A const generic parameter, e.g., `const N: usize = 10`.
264 Const {
265 /// The `const` keyword.
266 _const: KConst,
267 /// The name of the const parameter (e.g., `N`).
268 name: Ident,
269 /// The colon separating the name and type.
270 _colon: Colon,
271 /// The type of the const parameter (e.g., `usize`).
272 typ: VerbatimUntil<Either<Comma, Gt, Eq>>,
273 /// An optional default value (e.g., `= 10`).
274 default: Option<Cons<Eq, VerbatimUntil<Either<Comma, Gt>>>>,
275 },
276 /// A type parameter, e.g., `T: Trait = DefaultType`.
277 Type {
278 /// The name of the type parameter (e.g., `T`).
279 name: Ident,
280 /// Optional type bounds (e.g., `: Trait`).
281 bounds: Option<Bounds>,
282 /// An optional default type (e.g., `= DefaultType`).
283 default: Option<Cons<Eq, VerbatimUntil<Either<Comma, Gt>>>>,
284 },
285 }
286
287 /// Represents a `where` clause attached to a definition.
288 /// e.g., `where T: Trait, 'a: 'b`.
289 #[derive(Clone)]
290 pub struct WhereClauses {
291 /// The `where` keyword.
292 pub _kw_where: KWhere,
293 /// The comma-delimited list of where clause predicates.
294 pub clauses: CommaDelimitedVec<WhereClause>,
295 }
296
297 /// Represents a single predicate within a `where` clause.
298 /// e.g., `T: Trait` or `'a: 'b`.
299 #[derive(Clone)]
300 pub struct WhereClause {
301 /// The type or lifetime being constrained (e.g., `T` or `'a`).
302 /// We specifically required a single colon, not 2 because of `<A as B>::Thingy`
303 pub _pred: VerbatimUntil<Cons<Colon, Except<Colon>>>,
304 /// The colon separating the constrained item and its bounds.
305 pub _colon: Colon,
306 /// The bounds applied to the type or lifetime (e.g., `Trait` or `'b`).
307 pub bounds: VerbatimUntil<Either<Comma, Semicolon, BraceGroup>>,
308 }
309
310 /// Represents the kind of a struct definition.
311 pub enum StructKind {
312 /// A regular struct with named fields, e.g., `struct Foo { bar: u32 }`.
313 Struct {
314 /// Optional where clauses.
315 clauses: Option<WhereClauses>,
316 /// The fields enclosed in braces `{}`.
317 fields: BraceGroupContaining<CommaDelimitedVec<StructField>>,
318 },
319 /// A tuple struct, e.g., `struct Foo(u32, String);`.
320 TupleStruct {
321 /// The fields enclosed in parentheses `()`.
322 fields: ParenthesisGroupContaining<CommaDelimitedVec<TupleField>>,
323 /// Optional where clauses.
324 clauses: Option<WhereClauses>,
325 /// The trailing semicolon `;`.
326 semi: Semi,
327 },
328 /// A unit struct, e.g., `struct Foo;`.
329 UnitStruct {
330 /// Optional where clauses.
331 clauses: Option<WhereClauses>,
332 /// The trailing semicolon `;`.
333 semi: Semi,
334 },
335 }
336
337 /// Represents a lifetime annotation, like `'a`.
338 pub struct Lifetime {
339 /// The apostrophe `'` starting the lifetime.
340 pub _apostrophe: PunctJoint<'\''>,
341 /// The identifier name of the lifetime (e.g., `a`).
342 pub name: Ident,
343 }
344
345 /// Represents a simple expression, currently only integer literals.
346 /// Used potentially for const generic default values.
347 pub enum Expr {
348 /// An integer literal expression.
349 Integer(LiteralInteger),
350 }
351
352 /// Represents either the `const` or `mut` keyword, often used with pointers.
353 pub enum ConstOrMut {
354 /// The `const` keyword.
355 Const(KConst),
356 /// The `mut` keyword.
357 Mut(KMut),
358 }
359
360 /// Represents a field within a regular struct definition.
361 /// e.g., `pub name: String`.
362 pub struct StructField {
363 /// Attributes applied to the field (e.g., `#[doc = "..."]`).
364 pub attributes: Vec<Attribute>,
365 /// Optional visibility modifier (e.g., `pub`).
366 pub _vis: Option<Vis>,
367 /// The name of the field.
368 pub name: Ident,
369 /// The colon separating the name and type.
370 pub _colon: Colon,
371 /// The type of the field.
372 pub typ: VerbatimUntil<Comma>,
373 }
374
375 /// Represents a field within a tuple struct definition.
376 /// e.g., `pub String`.
377 pub struct TupleField {
378 /// Attributes applied to the field (e.g., `#[doc = "..."]`).
379 pub attributes: Vec<Attribute>,
380 /// Optional visibility modifier (e.g., `pub`).
381 pub vis: Option<Vis>,
382 /// The type of the field.
383 pub typ: VerbatimUntil<Comma>,
384 }
385
386 /// Represents an enum definition.
387 /// e.g., `#[repr(u8)] pub enum MyEnum<T> where T: Clone { Variant1, Variant2(T) }`.
388 pub struct Enum {
389 /// Attributes applied to the enum (e.g., `#[repr(...)]`).
390 pub attributes: Vec<Attribute>,
391 /// Optional visibility modifier (e.g., `pub`, `pub(crate)`, etc.).
392 pub _vis: Option<Vis>,
393 /// The `enum` keyword.
394 pub _kw_enum: KEnum,
395 /// The name of the enum.
396 pub name: Ident,
397 /// Optional generic parameters.
398 pub generics: Option<GenericParams>,
399 /// Optional where clauses.
400 pub clauses: Option<WhereClauses>,
401 /// The enum variants enclosed in braces `{}`.
402 pub body: BraceGroupContaining<CommaDelimitedVec<EnumVariantLike>>,
403 }
404
405 /// Represents a variant of an enum, including the optional discriminant value
406 pub struct EnumVariantLike {
407 /// The actual variant
408 pub variant: EnumVariantData,
409 /// The optional discriminant value
410 pub discriminant: Option<Cons<Eq, VerbatimUntil<Comma>>>
411 }
412
413 /// Represents the different kinds of variants an enum can have.
414 pub enum EnumVariantData {
415 /// A tuple-like variant, e.g., `Variant(u32, String)`.
416 Tuple(TupleVariant),
417 /// A struct-like variant, e.g., `Variant { field1: u32, field2: String }`.
418 Struct(StructEnumVariant),
419 /// A unit-like variant, e.g., `Variant`.
420 Unit(UnitVariant),
421 }
422
423 /// Represents a unit-like enum variant.
424 /// e.g., `MyVariant`.
425 pub struct UnitVariant {
426 /// Attributes applied to the variant.
427 pub attributes: Vec<Attribute>,
428 /// The name of the variant.
429 pub name: Ident,
430 }
431
432 /// Represents a tuple-like enum variant.
433 /// e.g., `MyVariant(u32, String)`.
434 pub struct TupleVariant {
435 /// Attributes applied to the variant.
436 pub attributes: Vec<Attribute>,
437 /// The name of the variant.
438 pub name: Ident,
439 /// The fields enclosed in parentheses `()`.
440 pub fields: ParenthesisGroupContaining<CommaDelimitedVec<TupleField>>,
441 }
442
443 /// Represents a struct-like enum variant.
444 /// e.g., `MyVariant { field1: u32, field2: String }`.
445 pub struct StructEnumVariant {
446 /// Attributes applied to the variant.
447 pub attributes: Vec<Attribute>,
448 /// The name of the variant.
449 pub name: Ident,
450 /// The fields enclosed in braces `{}`.
451 pub fields: BraceGroupContaining<CommaDelimitedVec<StructField>>,
452 }
453
454 /// A lifetime or a tokentree, used to gather lifetimes in type definitions
455 pub enum LifetimeOrTt {
456 /// A lifetime annotation.
457 Lifetime(Lifetime),
458 /// A single token tree.
459 TokenTree(TokenTree),
460 }
461}
462
463// ============================================================================
464// DISPLAY IMPLEMENTATIONS
465// ============================================================================
466
467impl core::fmt::Display for AngleTokenTree {
468 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
469 match &self.0 {
470 Either::First(it) => {
471 write!(f, "<")?;
472 for it in it.second.iter() {
473 write!(f, "{}", it.second)?;
474 }
475 write!(f, ">")?;
476 }
477 Either::Second(it) => write!(f, "{it}")?,
478 Either::Third(Invalid) => unreachable!(),
479 Either::Fourth(Invalid) => unreachable!(),
480 };
481 Ok(())
482 }
483}
484
485/// Display the verbatim tokens until the given token.
486pub struct VerbatimDisplay<'a, C>(
487 /// The verbatim tokens to display
488 pub &'a VerbatimUntil<C>,
489);
490
491impl<C> core::fmt::Display for VerbatimDisplay<'_, C> {
492 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
493 for tt in self.0.iter() {
494 write!(f, "{}", tt.value.second)?;
495 }
496 Ok(())
497 }
498}
499
500impl core::fmt::Display for ConstOrMut {
501 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
502 match self {
503 ConstOrMut::Const(_) => write!(f, "const"),
504 ConstOrMut::Mut(_) => write!(f, "mut"),
505 }
506 }
507}
508
509impl core::fmt::Display for Lifetime {
510 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
511 write!(f, "'{}", self.name)
512 }
513}
514
515impl core::fmt::Display for WhereClauses {
516 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
517 write!(f, "where ")?;
518 for clause in self.clauses.iter() {
519 write!(f, "{},", clause.value)?;
520 }
521 Ok(())
522 }
523}
524
525impl core::fmt::Display for WhereClause {
526 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
527 write!(
528 f,
529 "{}: {}",
530 VerbatimDisplay(&self._pred),
531 VerbatimDisplay(&self.bounds)
532 )
533 }
534}
535
536impl core::fmt::Display for Expr {
537 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
538 match self {
539 Expr::Integer(int) => write!(f, "{}", int.value()),
540 }
541 }
542}
543
544impl Struct {
545 /// Returns an iterator over the `FacetInner` content of `#[facet(...)]` attributes
546 /// applied to this struct.
547 pub fn facet_attributes(&self) -> impl Iterator<Item = &FacetInner> {
548 self.attributes
549 .iter()
550 .filter_map(|attr| match &attr.body.content {
551 AttributeInner::Facet(f) => Some(f.inner.content.as_slice()),
552 _ => None,
553 })
554 .flatten()
555 .map(|d| &d.value)
556 }
557}
558
559// ============================================================================
560// HELPER TYPES FOR CODE GENERATION
561// ============================================================================
562
563/// Helper type for lifetime name formatting
564#[derive(Clone)]
565pub struct LifetimeName(
566 /// The identifier for the lifetime
567 pub Ident,
568);
569
570impl quote::ToTokens for LifetimeName {
571 fn to_tokens(&self, tokens: &mut TokenStream) {
572 use proc_macro2::{Punct, Spacing, TokenTree};
573 let punct = TokenTree::Punct(Punct::new('\'', Spacing::Joint));
574 let name = &self.0;
575 tokens.extend(quote::quote! {
576 #punct #name
577 });
578 }
579}
580
581// ============================================================================
582// RENAME RULE
583// ============================================================================
584
585mod renamerule;
586pub use renamerule::*;
587
588#[cfg(test)]
589mod tests {
590 use super::*;
591 use quote::quote;
592
593 #[test]
594 fn test_struct_with_field_doc_comments() {
595 let input = quote! {
596 #[derive(Facet)]
597 pub struct User {
598 #[doc = " The user's unique identifier"]
599 pub id: u64,
600 }
601 };
602
603 let mut it = input.to_token_iter();
604 let parsed = it.parse::<Struct>().expect("Failed to parse struct");
605
606 // Check that we parsed the struct correctly
607 assert_eq!(parsed.name.to_string(), "User");
608
609 // Extract fields from the struct
610 if let StructKind::Struct { fields, .. } = &parsed.kind {
611 assert_eq!(fields.content.len(), 1);
612
613 // Check first field (id)
614 let id_field = &fields.content[0].value;
615 assert_eq!(id_field.name.to_string(), "id");
616
617 // Extract doc comments from id field
618 let mut doc_found = false;
619 for attr in &id_field.attributes {
620 match &attr.body.content {
621 AttributeInner::Doc(doc_inner) => {
622 // This should work with LiteralString
623 assert_eq!(doc_inner.value, " The user's unique identifier");
624 doc_found = true;
625 }
626 _ => {
627 // Skip non-doc attributes
628 }
629 }
630 }
631 assert!(doc_found, "Should have found a doc comment");
632 } else {
633 panic!("Expected a regular struct with named fields");
634 }
635 }
636}