state-shift 2.0.0

Macros for implementing Type-State-Pattern on your structs and methods
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

//! state-shift is a procedural macro crate designed to:
//! - hide away the complexities come with type-state pattern,
//! - make your code more readable and maintainable,
//! - and still benefit from the power of type-state pattern.
//!
//! Type-state is a design pattern that leverages the type system to enforce valid states and transitions at compile time.
//! This crate provides attribute macros to transform structures and methods into type-safe stateful components,
//! ensuring that methods are only callable in valid states, and enforcing transitions between them.
//!
//! Macros:
//!
//! - `#[require]`: Enforces that a method can only be called when the provided state is active.
//! - `#[switch_to]`: Modifies the return type of methods to switch between states.
//! - `#[impl_state]`: Defines the valid states for a given type and generates corresponding marker structs and trait implementations.
//! - `#[type_state]`: Transforms the struct into type-state compatible form, using state slots and default states.

extern crate proc_macro;

mod helper;
mod impl_state;
mod require;
mod switch_to;
mod type_state;

use helper::{extract_idents_from_group, extract_macro_args, is_single_letter};
use impl_state::impl_state_inner;
use require::generate_impl_block_for_method_based_on_require_args;
use switch_to::switch_to_inner;
use type_state::type_state_inner;

use proc_macro::TokenStream;

/// Turns your struct into type-state compatible version.
///
/// Usage: `#[type_state(states = (State1, State2, ...), slots = (DefaultState, ...))]`
///
/// Arguments:
/// - `states` -> A list of the states that the struct can transition through, which will be generated as marker structs and traits.
/// - `slots` -> Specifies the default states for the struct's state slots. Each slot corresponds to a tracked state.
///
/// What it does:
/// - Defines the valid states that a struct can transition between using the `states` attribute,
/// - Configures multiple state slots if needed, allowing a struct to track multiple states concurrently,
/// - Protects against invalid struct initialization by sealing state transitions using traits and marker structs,
/// - Seals the trait implementations for each state to ensure safety and prevent external modification.
#[proc_macro_attribute]
pub fn type_state(args: TokenStream, input: TokenStream) -> TokenStream {
    type_state_inner(args, input)
}

/// Modifies the methods in an `impl` block to work with the type-state pattern.
///
/// Usage: `#[impl_state]`
///
/// What it does:
/// - Applies type-state-specific transformations to methods in an `impl` block,
/// - Enforces state requirements on methods with the `#[require]` macro,
/// - Transforms methods that transition between states using the `#[switch_to]` macro,
/// - Automatically adds the hidden `_state` field to the `Self {}` struct initialization, ensuring compliance with the type-state pattern.
///
/// Also:
/// - Consumes the `#[require]` and `#[switch_to]` macros and handles the necessary transformations for those macros,
/// - Ensures that the methods only execute in the correct state and can safely transition between valid states.
#[proc_macro_attribute]
pub fn impl_state(_attr: TokenStream, item: TokenStream) -> TokenStream {
    impl_state_inner(item)
}

/// Denotes which state is required for this method to be called.
///
/// Usage:
/// - `#[require(State1)]`
/// - or with multiple state slots: `#[require(State1, State2, ...)]`
///
/// This macro is consumed by the `#[impl_state]` macro, and it basically guides `#[impl_state]` macro to:
/// - generate a specific `impl` block for each method,
/// - add the required types and generics to the generated `impl` blocks,
/// - add the hidden `_state` field to the `Self { }` struct, so you don't have to worry about anything regarding type-state-pattern
///
/// hence, it is empty, because it delegates its job to `#[impl_state]` macro
/// the reason for that delegation is: `#[require]` macro needs the below from the encapsulating `impl` block for the methods
/// - name of the impl block (name of the struct)
/// - generics
/// - lifetimes
#[proc_macro_attribute]
pub fn require(_args: TokenStream, _input: TokenStream) -> TokenStream {
    unreachable!(
        "`#[require]` macro should not be imported. It is consumed by the `#[impl_state]` macro."
    );
}

/// Denotes to which state will the object transition into after this method
///
/// Usage:
/// - `#[switch_to(State1)]`
/// - or with multiple state slots: `#[switch_to(State1, State2, ...)]`
///
/// This macro is consumed by the `#[impl_state]` macro, and it basically guides `#[impl_state]` macro to:
/// - overwrite the return type of the methods generated by the `#[impl_state]` macro
///
/// hence, it is empty, because it delegates its job to `#[impl_state]` macro
/// the reason for that delegation is: `#[switch_to]` macro needs the below from the encapsulating `impl` block for the methods
/// - name of the impl block (name of the struct)
#[proc_macro_attribute]
pub fn switch_to(_args: TokenStream, _input: TokenStream) -> TokenStream {
    unreachable!(
        "`#[switch_to]` macro should not be imported. It is consumed by the `#[impl_state]` macro."
    );
}