Skip to main content

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}