Skip to main content

class_warfare/
lib.rs

1#![no_std]
2#![forbid(unsafe_code)]
3#![doc = include_str!("../README.md")]
4
5/// A direct parent, as recorded by the Department of Ancestral Paperwork.
6///
7/// Derived classes implement this automatically. Base classes have no parent
8/// and therefore no paperwork. These operations address only the direct parent;
9/// call them again to reach a grandparent.
10pub trait HasParent: Sized {
11    /// The concrete type stored in this class's `super_class` field.
12    type Parent;
13
14    /// Borrow the direct parent.
15    fn parent(&self) -> &Self::Parent;
16
17    /// Mutably borrow the direct parent.
18    fn parent_mut(&mut self) -> &mut Self::Parent;
19
20    /// Consume the child and return its parent, dropping the child's own fields.
21    fn into_parent(self) -> Self::Parent;
22}
23
24/// Declare a struct with a constructor and optional parent delegation.
25///
26/// See the crate documentation for syntax, visibility, custom derives, and the
27/// legally significant difference between method shadowing and virtual dispatch.
28/// Each invocation declares one class. Class-level generic parameters are not
29/// supported; methods may have ordinary Rust generics and `where` clauses.
30///
31/// Generated names are `new`, and (for derived classes) `super_class`,
32/// `super_cast`, `super_cast_mut`, and `into_super`. Do not redeclare them.
33#[macro_export]
34macro_rules! class {
35    // The original syntax always made the class public. Keep that contract.
36    (plain $(#[$attr:meta])* class $name:ident $($rest:tt)*) => {
37        $crate::class! { plain $(#[$attr])* pub class $name $($rest)* }
38    };
39    ($(#[$attr:meta])* class $name:ident $($rest:tt)*) => {
40        $crate::class! { $(#[$attr])* pub class $name $($rest)* }
41    };
42
43    // `plain` opts out of the complimentary Debug + Clone personality package.
44    (plain $(#[$attr:meta])* $vis:vis class $name:ident extends $parent:ty {
45        $($(#[$field_attr:meta])* $field_vis:vis $field:ident : $field_ty:ty),* $(,)?
46    } $($item:item)*) => {
47        $crate::class! { @derived [$(#[$attr])*] $vis $name [$parent] {
48            $($(#[$field_attr])* $field_vis $field: $field_ty),*
49        } $($item)* }
50    };
51    (plain $(#[$attr:meta])* $vis:vis class $name:ident {
52        $($(#[$field_attr:meta])* $field_vis:vis $field:ident : $field_ty:ty),* $(,)?
53    } $($item:item)*) => {
54        $crate::class! { @base [$(#[$attr])*] $vis $name {
55            $($(#[$field_attr])* $field_vis $field: $field_ty),*
56        } $($item)* }
57    };
58    ($(#[$attr:meta])* $vis:vis class $name:ident extends $parent:ty {
59        $($(#[$field_attr:meta])* $field_vis:vis $field:ident : $field_ty:ty),* $(,)?
60    } $($item:item)*) => {
61        $crate::class! { @derived [#[derive(Debug, Clone)] $(#[$attr])*] $vis $name [$parent] {
62            $($(#[$field_attr])* $field_vis $field: $field_ty),*
63        } $($item)* }
64    };
65    ($(#[$attr:meta])* $vis:vis class $name:ident {
66        $($(#[$field_attr:meta])* $field_vis:vis $field:ident : $field_ty:ty),* $(,)?
67    } $($item:item)*) => {
68        $crate::class! { @base [#[derive(Debug, Clone)] $(#[$attr])*] $vis $name {
69            $($(#[$field_attr])* $field_vis $field: $field_ty),*
70        } $($item)* }
71    };
72
73    (@base [$($attr:tt)*] $vis:vis $name:ident {
74        $($(#[$field_attr:meta])* $field_vis:vis $field:ident : $field_ty:ty),* $(,)?
75    } $($item:item)*) => {
76        $($attr)*
77        $vis struct $name {
78            $($(#[$field_attr])* $field_vis $field: $field_ty),*
79        }
80
81        impl $name {
82            /// Construct a class from its fields, in declaration order.
83            /// No application form, reference check, or Java installation needed.
84            #[inline]
85            pub fn new($($field: $field_ty),*) -> Self {
86                Self { $($field),* }
87            }
88
89            $($item)*
90        }
91    };
92    (@derived [$($attr:tt)*] $vis:vis $name:ident [$parent:ty] {
93        $($(#[$field_attr:meta])* $field_vis:vis $field:ident : $field_ty:ty),* $(,)?
94    } $($item:item)*) => {
95        $($attr)*
96        $vis struct $name {
97            /// The direct parent. The family resemblance is literally stored here.
98            pub super_class: $parent,
99            $($(#[$field_attr])* $field_vis $field: $field_ty),*
100        }
101
102        impl $name {
103            /// Construct a child from its parent, then its fields in declaration order.
104            #[inline]
105            pub fn new(super_instance: $parent, $($field: $field_ty),*) -> Self {
106                Self { super_class: super_instance, $($field),* }
107            }
108
109            /// Borrow the direct parent, bypassing the child's method shadowing.
110            #[inline]
111            pub fn super_cast(&self) -> &$parent {
112                &self.super_class
113            }
114
115            /// Mutably borrow the direct parent. Family therapy sold separately.
116            #[inline]
117            pub fn super_cast_mut(&mut self) -> &mut $parent {
118                &mut self.super_class
119            }
120
121            /// Consume the child and recover its parent, dropping child-only fields.
122            #[inline]
123            pub fn into_super(self) -> $parent {
124                self.super_class
125            }
126
127            $($item)*
128        }
129
130        impl ::core::ops::Deref for $name {
131            type Target = $parent;
132
133            #[inline]
134            fn deref(&self) -> &Self::Target {
135                &self.super_class
136            }
137        }
138
139        impl ::core::ops::DerefMut for $name {
140            #[inline]
141            fn deref_mut(&mut self) -> &mut Self::Target {
142                &mut self.super_class
143            }
144        }
145
146        impl $crate::HasParent for $name {
147            type Parent = $parent;
148
149            #[inline]
150            fn parent(&self) -> &Self::Parent {
151                &self.super_class
152            }
153
154            #[inline]
155            fn parent_mut(&mut self) -> &mut Self::Parent {
156                &mut self.super_class
157            }
158
159            #[inline]
160            fn into_parent(self) -> Self::Parent {
161                self.super_class
162            }
163        }
164
165        impl ::core::convert::AsRef<$parent> for $name {
166            #[inline]
167            fn as_ref(&self) -> &$parent {
168                &self.super_class
169            }
170        }
171
172        impl ::core::convert::AsMut<$parent> for $name {
173            #[inline]
174            fn as_mut(&mut self) -> &mut $parent {
175                &mut self.super_class
176            }
177        }
178    };
179    ($($unsupported:tt)*) => {
180        ::core::compile_error!(
181            "The Architecture Committee rejected this class declaration. Expected: \
182             class Name { fields } methods, or class Child extends Parent { fields } methods. \
183             Put `plain` first to disable default derives; class-level generics are unsupported."
184        );
185    };
186}