facet_macros/lib.rs
1//! TeamDman-maintained fork of [facet-macros](https://github.com/facet-rs/facet/tree/65bae5c31a7ce401bc44630fb96250ea884cfd3e/facet-macros), published as
2//! [teamy-facet-macros](https://crates.io/crates/teamy-facet-macros).
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//! [](https://crates.io/crates/teamy-facet-macros)
8//! [](https://docs.rs/teamy-facet-macros)
9//! [](./LICENSE-MIT)
10//! [](https://discord.gg/JhD7CwCJ8F)
11//!
12//! Implements the `Facet` derive macro for facet. Uses [unsynn](https://crates.io/crates/unsynn) to provide fast compilation times.
13//!
14#![doc = include_str!("../readme-footer.md")]
15
16#[proc_macro_derive(Facet, attributes(facet))]
17pub fn facet_macros(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
18 facet_macros_impl::facet_macros(input.into()).into()
19}
20
21/// Internal proc macro for extension attribute resolution.
22///
23/// This is called by the `Facet` derive macro to forward extension attributes
24/// to their respective crate's dispatcher macro while preserving spans for
25/// better error messages.
26#[doc(hidden)]
27#[proc_macro]
28pub fn __ext(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
29 facet_macros_impl::ext_attr(input.into()).into()
30}
31
32// ============================================================================
33// ATTRIBUTE GRAMMAR PROC-MACROS
34// ============================================================================
35
36/// Internal proc macro for compiling attribute grammars.
37///
38/// This is called by `define_attr_grammar!` to generate type definitions
39/// and dispatcher macros from a grammar DSL.
40#[doc(hidden)]
41#[proc_macro]
42pub fn __make_parse_attr(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
43 facet_macros_impl::attr_grammar::make_parse_attr(input.into()).into()
44}
45
46/// Internal proc macro for unified attribute dispatch.
47///
48/// Routes parsed attribute names to the appropriate variant handlers
49/// (unit, newtype, or struct).
50#[doc(hidden)]
51#[proc_macro]
52pub fn __dispatch_attr(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
53 facet_macros_impl::attr_grammar::dispatch_attr(input.into()).into()
54}
55
56/// Internal proc macro for building struct field values.
57///
58/// Parses struct field assignments with type validation and helpful
59/// error messages.
60#[doc(hidden)]
61#[proc_macro]
62pub fn __build_struct_fields(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
63 facet_macros_impl::attr_grammar::build_struct_fields(input.into()).into()
64}
65
66/// Internal proc macro for attribute error messages.
67///
68/// Generates compile_error! with typo suggestions for unknown attributes.
69#[doc(hidden)]
70#[proc_macro]
71pub fn __attr_error(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
72 facet_macros_impl::attr_grammar::attr_error(input.into()).into()
73}
74
75/// Internal proc macro for field error messages.
76///
77/// Generates compile_error! with typo suggestions for unknown fields.
78#[doc(hidden)]
79#[proc_macro]
80pub fn __field_error(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
81 facet_macros_impl::attr_grammar::field_error(input.into()).into()
82}
83
84/// Internal proc macro for spanned error messages.
85///
86/// A generic helper for emitting errors with precise spans.
87#[doc(hidden)]
88#[proc_macro]
89pub fn __spanned_error(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
90 facet_macros_impl::attr_grammar::spanned_error(input.into()).into()
91}
92
93#[cfg(feature = "function")]
94#[proc_macro_attribute]
95pub fn facet_fn(
96 attr: proc_macro::TokenStream,
97 item: proc_macro::TokenStream,
98) -> proc_macro::TokenStream {
99 facet_macros_impl::function::facet_fn(attr.into(), item.into()).into()
100}
101
102#[cfg(feature = "function")]
103#[proc_macro]
104pub fn fn_shape(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
105 facet_macros_impl::function::fn_shape(input.into()).into()
106}
107
108/// Internal proc macro for unknown extension attribute errors.
109///
110/// This generates a compile_error! with the span pointing to the unknown identifier.
111#[doc(hidden)]
112#[proc_macro]
113pub fn __unknown_attr(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
114 facet_macros_impl::unknown_attr(input.into()).into()
115}
116
117// ============================================================================
118// PLUGIN SYSTEM PROC-MACROS
119// ============================================================================
120
121/// Internal proc macro for plugin chain finalization.
122///
123/// This is called at the end of a plugin chain to:
124/// 1. Parse the type definition ONCE
125/// 2. Generate the base Facet impl
126/// 3. Call each registered plugin's code generator
127///
128/// Input format:
129/// ```ignore
130/// __facet_finalize! {
131/// @tokens { struct Foo { ... } }
132/// @plugins { "Error", }
133/// @facet_crate { ::facet }
134/// }
135/// ```
136#[doc(hidden)]
137#[proc_macro]
138pub fn __facet_finalize(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
139 facet_macros_impl::facet_finalize(input.into()).into()
140}
141
142/// Internal proc macro for "does not accept arguments" errors.
143///
144/// Input: `"ns::attr", token`
145/// Generates compile_error! with span on the token.
146#[doc(hidden)]
147#[proc_macro]
148pub fn __no_args(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
149 facet_macros_impl::no_args(input.into()).into()
150}
151
152/// Attribute macro that runs cleanup code when a method returns an error.
153///
154/// # Usage
155///
156/// ```ignore
157/// #[on_error(self.cleanup())]
158/// pub fn do_something(&mut self) -> Result<(), Error> {
159/// self.inner_work()?;
160/// Ok(())
161/// }
162/// ```
163///
164/// For methods returning `Result<&mut Self, E>`, the macro properly handles
165/// the borrow by discarding the returned reference and returning a fresh `Ok(self)`:
166///
167/// ```ignore
168/// #[on_error(self.poison_and_cleanup())]
169/// pub fn begin_some(&mut self) -> Result<&mut Self, ReflectError> {
170/// self.require_active()?;
171/// // ... implementation
172/// Ok(self)
173/// }
174/// ```
175#[proc_macro_attribute]
176pub fn on_error(
177 attr: proc_macro::TokenStream,
178 item: proc_macro::TokenStream,
179) -> proc_macro::TokenStream {
180 facet_macros_impl::on_error(attr.into(), item.into()).into()
181}