structural_typing/
lib.rs

1//! # Structural Typing for Rust
2//!
3//! Define a struct once and use it with different field combinations, tracked at compile time.
4//!
5//! ## Installation
6//!
7//! ```bash
8//! cargo add structural-typing
9//! ```
10//!
11//! If using derives on `#[structural]` structs, also add:
12//! ```bash
13//! cargo add derive-where
14//! ```
15//!
16//! ## Quick Example
17//!
18//! ```
19//! use structural_typing::{structural, presence::Present, select};
20//!
21//! #[structural]
22//! struct User { id: u32, name: String, email: String }
23//!
24//! type Create = select!(user: name, email);
25//!
26//! fn create_user(data: User<Create>) -> User {
27//!     data.id(generate_id())
28//! }
29//!
30//! fn update_user<F: user::Fields<id = Present>>(data: User<F>) {
31//!     if let Some(name) = data.get_name() {
32//!         update_in_db(data.id, name);
33//!     }
34//! }
35//! # fn generate_id() -> u32 { 42 }
36//! # fn update_in_db(_id: u32, _name: &String) {}
37//! ```
38//!
39//! ## Core Concepts
40//!
41//! - **Field States**: `Present`, `Optional`, `Absent`
42//! - **Builder API**: `.field(value)` infers presence from type
43//! - **Type Selection**: `select!` macro or type aliases
44//! - **Bounded Impls**: Require specific fields via trait bounds
45//! - **Merge and Extract**: Combine partial structs or extract field subsets
46//!
47//! For serde integration and other details, see the [`structural`] macro documentation.
48//!
49//! See the [examples](https://github.com/Crazytieguy/structural-typing-rs/tree/master/examples) directory for comprehensive usage.
50//!
51//! ## Constraints
52//!
53//! - Named structs only (not tuple structs or enums)
54//! - At least one field required
55
56#![deny(missing_docs)]
57#![warn(clippy::pedantic)]
58
59/// Runtime field access trait for checking presence and getting values.
60pub mod access;
61/// Type-level presence markers and traits for field state tracking.
62pub mod presence;
63/// Traits for splitting structs into selected fields and remainder.
64pub mod extract;
65
66pub use structural_typing_macros::structural;
67
68/// Construct a `FieldSet` by selecting fields from a module.
69///
70/// # Syntax
71/// - `select!(module: field)` - field is Present
72/// - `select!(module: ?field)` - field is Optional
73/// - `select!(module: ?all)` - all fields Optional
74/// - Multiple fields compose: `select!(module: field1, ?field2)` expands to `module::with::field1::Present<module::with::field2::Optional>`
75///
76/// # Examples
77/// ```ignore
78/// type Create = select!(user: name, email);
79/// type Update = select!(user: ?name, ?email);
80/// fn create_user(user: User<Create>) {...}
81/// ```
82#[macro_export]
83macro_rules! select {
84    // Error: invalid + prefix
85    ($($module:ident)::+ : + $field:ident $($rest:tt)*) => {
86        compile_error!("Invalid prefix '+' in select!. Use 'field' for Present or '?field' for Optional")
87    };
88
89    // Error: invalid - prefix
90    ($($module:ident)::+ : - $field:ident $($rest:tt)*) => {
91        compile_error!("Invalid prefix '-' in select!. Use 'field' for Present or '?field' for Optional")
92    };
93
94    // Error: empty field list
95    ($($module:ident)::+ :) => {
96        compile_error!("select! requires at least one field")
97    };
98
99    // Single field: Present
100    ($($module:ident)::+ : $field:ident) => {
101        $($module)::+::with::$field::Present
102    };
103
104    // Single field: Present with trailing comma
105    ($($module:ident)::+ : $field:ident,) => {
106        $($module)::+::with::$field::Present
107    };
108
109    // Single field: Optional
110    ($($module:ident)::+ : ? $field:ident) => {
111        $($module)::+::with::$field::Optional
112    };
113
114    // Single field: Optional with trailing comma
115    ($($module:ident)::+ : ? $field:ident,) => {
116        $($module)::+::with::$field::Optional
117    };
118
119    // Multiple fields: Present + rest
120    ($($module:ident)::+ : $field:ident, $($rest:tt)+) => {
121        $($module)::+::with::$field::Present<select!($($module)::+ : $($rest)+)>
122    };
123
124    // Multiple fields: Optional + rest
125    ($($module:ident)::+ : ? $field:ident, $($rest:tt)+) => {
126        $($module)::+::with::$field::Optional<select!($($module)::+ : $($rest)+)>
127    };
128}
structural_typing/lib.rs

structural_typing/
lib.rs
