Skip to main content

simpleplatform_sdk_macros/
lib.rs

1//! The derive that makes `#[simple(…)]` legal, and checks what is written in it.
2//!
3//! An action depends on `simpleplatform-sdk` and reaches this crate through it.
4//! `use simpleplatform_sdk::prelude::*;` brings [`Schema`] into scope, and the
5//! `simple` helper attribute comes with it.
6
7#![deny(missing_docs)]
8#![deny(unsafe_code)]
9#![deny(rustdoc::broken_intra_doc_links)]
10
11mod constraints;
12
13use proc_macro::TokenStream;
14use syn::{parse_macro_input, DeriveInput};
15
16/// Constraints on the members of an action's input or output type.
17///
18/// ```
19/// use simpleplatform_sdk_macros::Schema;
20///
21/// #[derive(Schema)]
22/// struct Payload {
23///     /// Doc comment becomes the description.
24///     #[simple(length(min = 1, max = 500))]
25///     ids: Vec<String>,
26///
27///     /// How many days back to look.
28///     #[simple(range(min = 1, max = 90))]
29///     days: u32,
30///
31///     /// Only keys starting here.
32///     #[simple(pattern = "^KNOW", length(max = 64))]
33///     prefix: String,
34/// }
35/// ```
36///
37/// # What this derive generates
38///
39/// Nothing. It expands to an empty token stream, so a member that carries
40/// constraints costs a built module exactly what a member without them costs.
41/// Its whole job is the two things a derive is uniquely able to do: register
42/// `simple` as an inert helper attribute, so writing one is legal Rust, and
43/// read what was written, so a mistake in one is a compile error at the span
44/// that holds it.
45///
46/// # The constraints
47///
48/// | written | applies to | becomes |
49/// |---|---|---|
50/// | `range(min = …, max = …)` | numbers | `minimum` / `maximum` |
51/// | `length(min = …, max = …)` | strings and collections | `minLength` / `maxLength` on a string, `minItems` / `maxItems` on a collection |
52/// | `pattern = "…"` | strings | `pattern` |
53/// | `format = "…"` | strings | `format` |
54/// | `default = …` | any member | `default` |
55/// | `example = …` | any member | `example` |
56/// | `deprecated` | any member | `deprecated` |
57///
58/// `length` is type-directed: the same two bounds mean characters on a
59/// `String` and elements on a `Vec<T>`, so there is one length to remember
60/// rather than two.
61///
62/// Several constraints go in one attribute, separated by commas, or in
63/// attributes of their own — `#[simple(pattern = "^KNOW", length(max = 64))]`
64/// and `#[simple(pattern = "^KNOW")] #[simple(length(max = 64))]` are the same
65/// thing. Either way each constraint is written once per member.
66///
67/// # What is *not* written here
68///
69/// - **The description** is the doc comment. `/// Collection identifiers.`
70///   above the member is the description, and there is one place to write it.
71/// - **Requiredness** is the type. A member is optional when it is `Option<T>`
72///   or carries `#[serde(default)]`, and required otherwise, so the signature
73///   and the schema cannot disagree.
74/// - **The property name** is what `serde` says it is. `#[serde(rename = "…")]`
75///   and `#[serde(rename_all = "…")]` name the property, so the name on the
76///   wire and the name serde reads are the same name.
77#[proc_macro_derive(Schema, attributes(simple))]
78pub fn schema(input: TokenStream) -> TokenStream {
79    let input = parse_macro_input!(input as DeriveInput);
80
81    match constraints::check(&input) {
82        Ok(()) => TokenStream::new(),
83        Err(error) => error.into_compile_error().into(),
84    }
85}