Skip to main content

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}