alux_ext_macros/
lib.rs

1//! Procedural macros for declaring and defunctionalizing DD programs.
2//!
3//! This crate is the shared syntax layer for DD extension, HTTP, and JSON-RPC programs.
4//! Its public surface stays small: parsing, validation, and code generation
5//! live in private modules, while this facade contains only procedural-macro
6//! entry points. Product crates re-export the macros they own.
7//!
8//! Every example below is illustrative rather than tested. Expansion names `::alux_ext`,
9//! `::alux_http`, and `::alux_jsonrpc`, and a procedural-macro crate cannot depend on the crates its
10//! own expansion targets. The executed examples live in those crates' documentation.
11
12mod ext;
13mod http_program;
14mod jsonrpc_program;
15mod lower;
16mod syntax;
17
18use ext::ext_internal;
19use http_program::http_program_defunc_internal;
20use jsonrpc_program::jsonrpc_program_defunc_internal;
21use proc_macro::TokenStream;
22
23/// Declares extension methods and optionally gives each method a first-order operation type.
24///
25/// Arguments unrelated to defunctionalization are forwarded to `extend::ext`.
26/// Plain `defunc` produces a hidden `*Operation<Context>` type implementing
27/// `OperationAlg` and `ApplyAlg`. When every method already builds first-order
28/// route syntax from `routes()`, plain `defunc` names those inferred programs
29/// directly. A backend such as `defunc(via = http)` or `defunc(via = jsonrpc)`
30/// additionally lifts convenient method references while producing named programs
31/// and their interpreter evidence.
32///
33/// ```ignore
34/// use alux_ext::ext;
35///
36/// #[ext(name = CounterExt, defunc)]
37/// impl<This> This
38/// where
39///     This: CounterAlg,
40/// {
41///     async fn incremented(&self, by: u32) -> u32 {
42///         self.increment(by).await
43///     }
44/// }
45///
46/// // The expansion also defines `IncrementedOperation<This>`.
47/// ```
48///
49/// ```ignore
50/// use alux_ext::ext;
51/// use alux_http::http;
52///
53/// #[ext(name = StatusRoutesExt, defunc(via = http))]
54/// impl<This> This
55/// where
56///     This: HttpApiAlg + JsonOutAlg,
57/// {
58///     fn status_routes<Alg>(&self)
59///     where
60///         Alg: StatusAlg,
61///     {
62///         self.routes().get("/status", self.op(Alg::status_current).json())
63///     }
64/// }
65///
66/// // The expansion also defines `StatusRoutesProgram<Alg>`.
67/// ```
68#[proc_macro_attribute]
69pub fn ext(attr: TokenStream, item: TokenStream) -> TokenStream {
70    ext_internal(attr.into(), item.into()).unwrap_or_else(syn::Error::into_compile_error).into()
71}
72
73/// Lowers extension methods into named, composable HTTP programs.
74///
75/// This is the HTTP backend that `alux_ext::ext(..., defunc(via = http))` selects. `via = http`
76/// resolves the name in the authoring scope, so a declaration imports it as `use alux_http::http`.
77/// Applying the attribute directly means the same thing.
78///
79/// Each method becomes a first-order HTTP program. A route handler written with `op(...)` is replaced
80/// by the operation type generated by `alux_ext::ext(defunc)`, the declared input roles and output
81/// kind become bounds on the interpreter, and a call to another method of the same extension becomes
82/// a nested program.
83///
84/// ```ignore
85/// use alux_ext::ext;
86/// use alux_http::{HttpApiAlg, JsonOutAlg, http};
87///
88/// #[ext(name = StatusApiExt, defunc(via = http))]
89/// impl<This> This
90/// where
91///     This: HttpApiAlg + JsonOutAlg,
92/// {
93///     fn status_api<Alg>(&self)
94///     where
95///         Alg: StatusAlg,
96///     {
97///         self.routes().get("/status", self.op(Alg::status_current).json())
98///     }
99/// }
100///
101/// // The expansion also defines `StatusApiProgram<Alg>`.
102/// ```
103#[proc_macro_attribute]
104pub fn http(attr: TokenStream, item: TokenStream) -> TokenStream {
105    http_program_defunc_internal(attr.into(), item.into()).unwrap_or_else(syn::Error::into_compile_error).into()
106}
107
108/// Lowers extension methods into named, composable JSON-RPC programs.
109///
110/// This is the JSON-RPC backend that `alux_ext::ext(..., defunc(via = jsonrpc))` selects. `via = jsonrpc`
111/// resolves the name in the authoring scope, so a declaration imports it as `use alux_jsonrpc::jsonrpc`.
112/// Applying the attribute directly means the same thing.
113///
114/// Each method becomes a first-order JSON-RPC program. A method handler written with `op(...)` is
115/// replaced by the operation type generated by `alux_ext::ext(defunc)`, the operation's argument
116/// product and output become bounds on the interpreter, `.named()` selects object decoding using the
117/// authored argument names, and a call to another method of the same extension becomes a nested
118/// program.
119///
120/// ```ignore
121/// use alux_ext::ext;
122/// use alux_jsonrpc::{JsonRpcApiAlg, jsonrpc};
123///
124/// #[ext(name = StatusRpcExt, defunc(via = jsonrpc))]
125/// impl<This> This
126/// where
127///     This: JsonRpcApiAlg,
128/// {
129///     fn status_rpc<Alg>(&self)
130///     where
131///         Alg: StatusAlg,
132///     {
133///         self.methods().method("status_current", self.op(Alg::status_current))
134///     }
135/// }
136///
137/// // The expansion also defines `StatusRpcProgram<Alg>`.
138/// ```
139#[proc_macro_attribute]
140pub fn jsonrpc(attr: TokenStream, item: TokenStream) -> TokenStream {
141    jsonrpc_program_defunc_internal(attr.into(), item.into()).unwrap_or_else(syn::Error::into_compile_error).into()
142}
alux_ext_macros/lib.rs

alux_ext_macros/
lib.rs
