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//! See the [examples](https://github.com/Crazytieguy/structural-typing-rs/tree/master/examples) directory for comprehensive usage including merge, extract, serde integration, and more.
48//!
49//! ## Constraints
50//!
51//! - Named structs only (not tuple structs or enums)
52//! - No generic parameters
53//! - At least one field required
54
55#![deny(missing_docs)]
56#![warn(clippy::pedantic)]
57
58/// Runtime field access trait for checking presence and getting values.
59pub mod access;
60/// Type-level presence markers and traits for field state tracking.
61pub mod presence;
62/// Traits for splitting structs into selected fields and remainder.
63pub mod extract;
64
65pub use structural_typing_macros::structural;
66
67/// Construct a `FieldSet` by selecting fields from a module.
68///
69/// # Syntax
70/// - `select!(module: field)` - field is Present
71/// - `select!(module: ?field)` - field is Optional
72/// - `select!(module: ?all)` - all fields Optional
73/// - Multiple fields compose: `select!(module: field1, ?field2)` expands to `module::with::field1::Present<module::with::field2::Optional>`
74///
75/// # Examples
76/// ```ignore
77/// type Create = select!(user: name, email);
78/// type Update = select!(user: ?name, ?email);
79/// fn create_user(user: User<Create>) {...}
80/// ```
81#[macro_export]
82macro_rules! select {
83    // Error: invalid + prefix
84    ($($module:ident)::+ : + $field:ident $($rest:tt)*) => {
85        compile_error!("Invalid prefix '+' in select!. Use 'field' for Present or '?field' for Optional")
86    };
87
88    // Error: invalid - prefix
89    ($($module:ident)::+ : - $field:ident $($rest:tt)*) => {
90        compile_error!("Invalid prefix '-' in select!. Use 'field' for Present or '?field' for Optional")
91    };
92
93    // Error: empty field list
94    ($($module:ident)::+ :) => {
95        compile_error!("select! requires at least one field")
96    };
97
98    // Single field: Present
99    ($($module:ident)::+ : $field:ident) => {
100        $($module)::+::with::$field::Present
101    };
102
103    // Single field: Present with trailing comma
104    ($($module:ident)::+ : $field:ident,) => {
105        $($module)::+::with::$field::Present
106    };
107
108    // Single field: Optional
109    ($($module:ident)::+ : ? $field:ident) => {
110        $($module)::+::with::$field::Optional
111    };
112
113    // Single field: Optional with trailing comma
114    ($($module:ident)::+ : ? $field:ident,) => {
115        $($module)::+::with::$field::Optional
116    };
117
118    // Multiple fields: Present + rest
119    ($($module:ident)::+ : $field:ident, $($rest:tt)+) => {
120        $($module)::+::with::$field::Present<select!($($module)::+ : $($rest)+)>
121    };
122
123    // Multiple fields: Optional + rest
124    ($($module:ident)::+ : ? $field:ident, $($rest:tt)+) => {
125        $($module)::+::with::$field::Optional<select!($($module)::+ : $($rest)+)>
126    };
127}
structural_typing/lib.rs

structural_typing/
lib.rs
