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