alux_shape/construct.rs
1//! How a value is made from the members its shape names, and taken apart into them.
2//!
3//! A shape describes a value; it never builds one. An interpretation that reads a value member by
4//! member, from command-line words, named parameters, or a form, needs the other direction too: a
5//! product is its fields taken together, and a sum is the one alternative it carries. A sum is an
6//! isomorphism with a `SumN`. A product is one with a tuple unless a member is skipped: that member is
7//! no field and is made with `Default`, so a product made from its fields answers those fields, and its members are named as identifiers, the way an
8//! operation's argument names are, so `words_of` reads them as the words a shape names them by.
9
10use alux_ext::{ext, for_tuples};
11
12/// States that a value is its fields taken together.
13///
14/// `#[derive(Shape)]` states it for every struct it reads.
15#[diagnostic::on_unimplemented(
16 message = "`{Self}` is not stated as a product of its fields",
17 note = "`#[derive(Shape)]` states `Product` for a struct with named members; a skipped member is made with `Default`, and a flattened one is one field"
18)]
19pub trait Product: Sized {
20 /// The fields, in order, as a tuple.
21 type Fields;
22 /// The fields' names, in order, as identifiers.
23 const FIELDS: &'static [&'static str];
24
25 /// Makes the value from its fields.
26 fn from_fields(fields: Self::Fields) -> Self;
27
28 /// Takes the value apart into its fields.
29 fn into_fields(self) -> Self::Fields;
30}
31
32/// States that a value is exactly one of its alternatives.
33///
34/// An alternative carrying no value is `()`.
35///
36/// `#[derive(Shape)]` states it for every enum it reads with two to sixteen alternatives.
37#[diagnostic::on_unimplemented(
38 message = "`{Self}` is not stated as a sum of its alternatives",
39 note = "`#[derive(Shape)]` states `Sum` for an enum of two to sixteen alternatives, each carrying one value or none"
40)]
41pub trait Sum: Sized {
42 /// The alternatives, in order, as a `Sum2` through `Sum16`.
43 type Alternatives;
44 /// The alternatives' names, in order, as identifiers.
45 const ALTERNATIVES: &'static [&'static str];
46
47 /// Makes the value from the alternative it carries.
48 fn from_alternative(alternative: Self::Alternatives) -> Self;
49
50 /// Answers the alternative the value carries.
51 fn into_alternative(self) -> Self::Alternatives;
52}
53
54/// States `SumN`, the alternatives of one width.
55macro_rules! sums {
56 ($sum:ident, $width:tt; $(($variant:ident, $index:tt)),+) => {
57 #[doc = concat!("Holds the one alternative of ", stringify!($width), " a value carries.")]
58 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
59 pub enum $sum<$($variant),+> {
60 $(
61 #[doc = concat!("The alternative at index ", stringify!($index), ".")]
62 $variant($variant),
63 )+
64 }
65 };
66}
67
68for_tuples!(sums, 2..=16, named = Sum, each = []);
69
70/// States that a product made from its fields answers those fields.
71///
72/// A skipped member is no field, so the product made again holds its `Default`, not its value.
73#[ext(name = ProductLawsExt)]
74pub impl<This, Fields> This
75where
76 This: Product<Fields = Fields> + Clone,
77 Fields: Clone + PartialEq,
78{
79 /// Taking apart a product made from this one's fields answers the same fields.
80 fn law_product_round_trip(&self) -> bool {
81 let fields = self.clone().into_fields();
82 This::from_fields(fields.clone()).into_fields() == fields
83 }
84}
85
86/// States that answering a sum's alternative and making it again changes nothing.
87#[ext(name = SumLawsExt)]
88pub impl<This> This
89where
90 This: Sum + Clone + PartialEq,
91{
92 /// Making a sum from the alternative it carries answers the same sum.
93 fn law_sum_round_trip(&self) -> bool {
94 This::from_alternative(self.clone().into_alternative()) == *self
95 }
96}