Skip to main content

jevrs_derive/
lib.rs

1//! Derive macros for strongly typed Jev criteria.
2
3use proc_macro::TokenStream;
4use syn::{DeriveInput, parse_macro_input};
5
6mod attrs;
7mod indexed;
8mod levels;
9mod options;
10mod questions;
11
12/// Derives `jevrs::Options` for a unit-variant enum.
13///
14/// Variant names become `snake_case` wire keys. Attributes customize the
15/// generated implementation:
16///
17/// | Location | Attribute | Purpose |
18/// | --- | --- | --- |
19/// | Enum | `#[jev(crate = "path")]` | Override the default `::jevrs` path. |
20/// | Variant | `#[jev(key = "name")]` | Override the wire key. |
21/// | Variant | `#[jev(desc = "text")]` | Override the option description. |
22///
23/// A variant's trimmed `///` lines supply its description when `desc` is
24/// absent. A variant without either has no description.
25///
26/// ```
27/// use jevrs::{Indexed, Options as OptionsTrait};
28/// use jevrs_derive::Options;
29///
30/// #[derive(Clone, Copy, Debug, Eq, Options, PartialEq)]
31/// enum Dept {
32///     /// Payments, invoicing, refunds
33///     Billing,
34///     #[jev(key = "tech", desc = "Bugs, outages, integrations")]
35///     Technical,
36///     Sales,
37/// }
38///
39/// assert_eq!(Dept::all(), &[Dept::Billing, Dept::Technical, Dept::Sales]);
40/// assert_eq!(Dept::Technical.key(), "tech");
41/// assert_eq!(Dept::Sales.description(), None);
42/// ```
43///
44/// Compilation fails for non-enums, empty enums, non-unit variants, empty or
45/// duplicate wire keys, unknown `jev` attributes, or more than 255 variants.
46#[proc_macro_derive(Options, attributes(jev))]
47pub fn derive_options(input: TokenStream) -> TokenStream {
48    options::expand(&parse_macro_input!(input as DeriveInput))
49        .unwrap_or_else(syn::Error::into_compile_error)
50        .into()
51}
52
53/// Derives `jevrs::Levels` for an ordered unit-variant enum.
54///
55/// Variant order defines level order. Attributes customize the generated
56/// implementation:
57///
58/// | Location | Attribute | Purpose |
59/// | --- | --- | --- |
60/// | Enum | `#[jev(crate = "path")]` | Override the default `::jevrs` path. |
61/// | Variant | `#[jev(desc = "text")]` | Override the level description. |
62///
63/// Every variant needs either `desc` or at least one `///` doc line. Trimmed
64/// doc lines are joined with one space.
65///
66/// ```
67/// use jevrs::{Indexed, Levels as LevelsTrait};
68/// use jevrs_derive::Levels;
69///
70/// #[derive(Clone, Copy, Debug, Eq, Levels, Ord, PartialEq, PartialOrd)]
71/// enum Frustration {
72///     /// Calm
73///     Calm,
74///     /// Frustrated
75///     Frustrated,
76///     #[jev(desc = "Very angry")]
77///     VeryAngry,
78/// }
79///
80/// assert_eq!(Frustration::all()[2], Frustration::VeryAngry);
81/// assert_eq!(Frustration::VeryAngry.description(), "Very angry");
82/// ```
83///
84/// Compilation fails for non-enums, non-unit variants, fewer than two or more
85/// than ten variants, missing descriptions, `key` attributes, or unknown
86/// `jev` attributes.
87#[proc_macro_derive(Levels, attributes(jev))]
88pub fn derive_levels(input: TokenStream) -> TokenStream {
89    levels::expand(&parse_macro_input!(input as DeriveInput))
90        .unwrap_or_else(syn::Error::into_compile_error)
91        .into()
92}
93
94/// Derives a reusable, statically typed Jev question set from named fields.
95///
96/// Each field has exactly one question-kind attribute. The field type is its
97/// question marker, and `id` defaults to the field name:
98///
99/// | Kind | Required attribute | Optional attributes |
100/// | --- | --- | --- |
101/// | Yes/no | `#[jev(noul = "instructions")]` | `id`, or both `yes` and `no` |
102/// | Choice | `#[jev(choice = "instructions")]` | `id` |
103/// | Score | `#[jev(score = "instructions")]` | `id` |
104///
105/// Set `#[jev(crate = "::jevrs_core")]` on the struct when using the core
106/// crate directly. The derive generates public `<Name>Handles` and
107/// `<Name>Answers` structs.
108///
109/// ```
110/// use jevrs::{Choice, Noul, QuestionSet, Score};
111/// use jevrs_derive::{Levels, Options, Questions};
112///
113/// #[derive(Clone, Copy, Debug, Eq, Options, PartialEq)]
114/// enum Dept {
115///     /// Payments and refunds
116///     Billing,
117///     Sales,
118/// }
119/// #[derive(Clone, Copy, Debug, Eq, Levels, Ord, PartialEq, PartialOrd)]
120/// enum Mood {
121///     /// Calm
122///     Calm,
123///     /// Frustrated
124///     Frustrated,
125/// }
126/// #[derive(Questions)]
127/// struct Triage {
128///     #[jev(noul = "Does this convey urgency?")]
129///     urgent: Noul,
130///     #[jev(choice = "Which team should handle this?")]
131///     department: Choice<Dept>,
132///     #[jev(score = "How frustrated is the customer?", id = "mood")]
133///     frustration: Score<Mood>,
134/// }
135///
136/// let (questions, handles) = Triage::questions()?;
137/// assert_eq!(questions.len(), 3);
138/// let _ = handles;
139/// # Ok::<(), jevrs::Error>(())
140/// ```
141///
142/// Compilation fails for non-structs, tuple or empty structs, missing or
143/// conflicting question kinds, incomplete yes/no criteria, unknown attributes,
144/// or duplicate wire IDs.
145#[proc_macro_derive(Questions, attributes(jev))]
146pub fn derive_questions(input: TokenStream) -> TokenStream {
147    questions::expand(&parse_macro_input!(input as DeriveInput))
148        .unwrap_or_else(syn::Error::into_compile_error)
149        .into()
150}