event_driven_macros/
lib.rs

1use proc_macro::TokenStream;
2
3mod expand;
4mod parse;
5use proc_macro_error::{abort_call_site, proc_macro_error};
6use syn::parse2;
7
8/// Provides a DSL that conveniently implements the FSM trait.
9/// States, Commands and Events are all required to be implemented
10/// both as structs and enums.
11///
12/// An example:
13///
14/// ```compile_fail
15/// #[impl_fsm]
16/// impl Fsm<State, Command, Event, EffectHandlers> for MyFsm {
17///     state!(Running / entry);
18///
19///     command!(Idle    => Start => Started => Running);
20///     command!(Running => Stop  => Stopped => Idle);
21///
22///     ignore_command!(Idle    => Stop);
23///     ignore_command!(Running => Start);
24/// }
25/// ```
26///
27/// The `state!` macro declares state-related attributes. At this time, only entry
28/// handlers can be declared. In our example, the macro will ensure that an `on_entry_running`
29/// method will be called for `MyFsm`. The developer is then
30/// required to implement a method e.g.:
31///
32/// ```compile_fail
33/// fn on_entry_running(_s: &Running, _se: &mut EffectHandlers) {
34///     // Do something
35/// }
36/// ```
37///
38/// The `command!` macro declares an entire transition using the form:
39///
40/// ```compile_fail
41/// <from-state> => <given-command> [=> <yields-event> []=> <to-state>]]
42/// ```
43///
44/// In our example, for the first transition, multiple methods will be called that the developer must provide e.g.:
45///
46/// ```compile_fail
47/// fn for_idle_start(_s: &Idle, _c: Start, _se: &mut EffectHandlers) -> Option<Started> {
48///     // Perform some effect here if required. Effects are performed via the EffectHandler
49///     Some(Started)
50/// }
51///
52/// fn on_idle_started(_s: &Idle, _e: &Started) -> Option<Running> {
53///     Some(Running)
54/// }
55/// ```
56///
57/// The `ignore_command!` macro describes those states and commands that should be ignored given:
58///
59/// ```compile_fail
60/// <from-state> => <given-command>
61/// ```
62///
63/// It is possible to use a wildcard i.e. `_` in place of `<from-state>` and `<to-state>`.
64///
65/// There are similar macros for events e.g. `event!` and `ignore_event`. For `event!`, the declaration
66/// becomes:
67///
68/// ```compile_fail
69/// <from-state> => <given-event> [=> <to-state> [ / action]]
70/// ```
71///
72/// The `/ action` is optional and is used to declare that a side-effect is to be performed.
73
74#[proc_macro_attribute]
75#[proc_macro_error]
76pub fn impl_fsm(input: TokenStream, annotated_item: TokenStream) -> TokenStream {
77    if !input.is_empty() {
78        abort_call_site!("this attribute takes no arguments"; help = "use `#[impl-fsm]`")
79    }
80
81    match parse2::<parse::Fsm>(annotated_item.into()) {
82        Ok(mut fsm) => match expand::expand(&mut fsm) {
83            Ok(expanded) => expanded.into(),
84            Err(e) => e.to_compile_error().into(),
85        },
86        Err(e) => e.to_compile_error().into(),
87    }
88}
event_driven_macros/lib.rs

event_driven_macros/
lib.rs
