aura_derive/lib.rs
1//! Proc macros for AURA plugins.
2//!
3//! - [`#[derive(Params)`](macro@Params) generates the full
4//! `aura_params::Params` impl for a struct of `FloatParam` /
5//! `IntParam` / `BoolParam` / `EnumParam<E>` / `MeterSlot` fields,
6//! plus `#[nested]` sub-structs and `#[persist]` plain-data fields.
7//! It also emits a `<Struct>ParamId` companion enum (one variant per
8//! own param field) so editors can use `GainParamsParamId::Gain.id()`
9//! instead of scattering raw `u32` IDs.
10//! - [`#[derive(ParamEnum)`](macro@ParamEnum) generates the
11//! `aura_params::ParamEnum` impl for a field-less enum.
12//!
13//! AURA owns this derive. Param IDs are always explicit (`id = N`);
14//! nested structs keep their declared IDs (collisions panic in `new()`
15//! via `Params::assert_no_id_collisions`). There is no compile-time
16//! `plugin_info!`, no framework `#[derive(State)]`, and no silent
17//! auto-numbering.
18//!
19//! **Packaging:** generated code references `::aura::params::…`. Depend on
20//! the `aura` umbrella crate (normal author path), not `aura-derive` alone.
21//!
22//! Implementation split across modules ([`parse`] collects fields /
23//! attributes, [`codegen`] turns them into `TokenStream`s, [`params`] and
24//! [`param_enum`] assemble the two derives) - the functions actually
25//! tagged `#[proc_macro_derive]` stay here since that attribute is
26//! only accepted on functions defined at the crate root.
27
28#![forbid(unsafe_code)]
29
30use proc_macro::TokenStream;
31
32mod codegen;
33mod param_enum;
34mod params;
35mod parse;
36
37/// Derive the `Params` implementation for a parameter struct.
38///
39/// Field kinds:
40///
41/// - `FloatParam` / `IntParam` / `BoolParam` / `EnumParam<E>` with
42/// `#[param(...)]` - a real parameter.
43/// - `MeterSlot` with `#[meter]` - a meter slot, auto-assigned an ID
44/// from `METER_ID_BASE` upward, in declaration order.
45/// - any `Params` type with `#[nested]` - a sub-struct whose params
46/// merge into this one (IDs stay as declared in the child; a
47/// parent/child collision panics in `new()` via
48/// `Params::assert_no_id_collisions`).
49/// - plain data with `#[persist]` (or `#[persist = "key"]`) — saved in the
50/// host state blob via `encode_state` / `decode_state` (v2 envelope:
51/// params + persist). Field type must be `RwLock<T>` / `Mutex<T>` with
52/// `T` one of `bool`, `u8`..`u64`, `i8`..`i64`, `f32`, `f64`, `String`.
53///
54/// `#[param(...)]` keys:
55///
56/// | key | value | default |
57/// |-----|-------|---------|
58/// | `id` | integer literal `< METER_ID_BASE` | required |
59/// | `name` | string | `"Unnamed"` |
60/// | `short_name` | string | `name` |
61/// | `group` | string | `""` |
62/// | `range` | `"linear(min, max)"`, `"log(min, max)"`, `"skewed(min, max, factor)"`, `"sym_skewed(min, max, factor, center)"`, `"discrete(min, max)"`, `"enum(count)"`, `"reversed(<range>)"` | `linear(0, 1)`; `discrete(0, 1)` for bools; `enum(variant_count)` for enums |
63/// | `default` | numeric or bool literal | `0.0` |
64/// | `unit` | `"dB"`, `"Hz"`, `"ms"`, `"s"`, `"%"`, `"st"`, `"pan"`, `"deg"`, `"none"` | `"none"` |
65/// | `flags` | `"automatable \| hidden \| readonly \| bypass \| modulatable \| modulatable_per_note"` | `"automatable"` |
66/// | `smooth` | `"none"`, `"linear(<ms>)"`, `"exp(<ms>)"`, `"log(<ms>)"` (float params only) | `"none"` |
67/// | `chunk` | bool | `true` (`ParamFlags::CHUNKED` set) |
68/// | `midi_cc` | `0..=127` | unset (hint only; wrappers ignore) |
69/// | `midi_source` | `"pitchbend"` \| `"pressure"` \| `"program"` | unset (hint only) |
70/// | `midi_channel` | `1..=16` | any channel (hint only) |
71/// | `format` / `parse` | method name string - custom display hooks | unit-aware defaults |
72///
73/// The derive also emits `__private::Sealed`, a `new()` that
74/// collision-checks the whole tree, and `impl Default` calling it.
75///
76/// # Panics
77///
78/// Panics if `syn` fails to parse the input token stream. That only
79/// happens on syntactically broken input (rustc would already be
80/// rejecting the same file), so the panic surfaces a derive-internal
81/// regression rather than user error.
82#[proc_macro_derive(Params, attributes(param, nested, meter, persist, skip))]
83pub fn derive_params(input: TokenStream) -> TokenStream {
84 params::expand(input)
85}
86
87/// Derive `ParamEnum` for a C-like enum.
88///
89/// Generates `Clone`, `Copy`, `PartialEq`, `Eq`, the `Sealed` marker,
90/// and all 5 `ParamEnum` methods: `from_index`, `to_index`, `name`,
91/// `variant_count`, and `variant_names`.
92///
93/// Display names default to the variant identifier. Use
94/// `#[name = "..."]` on a variant to override:
95///
96/// ```ignore
97/// #[derive(ParamEnum)]
98/// pub enum ArpPattern {
99/// Up,
100/// Down,
101/// #[name = "Up/Down"]
102/// UpDown,
103/// Random,
104/// }
105/// ```
106///
107/// # Panics
108///
109/// Panics if `syn` fails to parse the input token stream - same
110/// "rustc-already-rejected" condition as [`derive_params`].
111#[proc_macro_derive(ParamEnum, attributes(name))]
112pub fn derive_param_enum(input: TokenStream) -> TokenStream {
113 param_enum::expand(input)
114}