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, JSON-RPC, CLI, and shape 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 cli_program;
13mod ext;
14mod extension;
15mod http_program;
16mod jsonrpc_program;
17mod lower;
18mod shape_program;
19mod syntax;
20
21use cli_program::cli_program_defunc_internal;
22use ext::ext_internal;
23use http_program::http_program_defunc_internal;
24use jsonrpc_program::jsonrpc_program_defunc_internal;
25use proc_macro::TokenStream;
26use shape_program::shape_program_defunc_internal;
27
28/// Declares extension methods and optionally gives each method a first-order operation type.
29///
30/// Plain `defunc` produces a hidden `*Operation<Context>` type implementing
31/// `OperationAlg` and `ApplyAlg`. When every method already builds first-order
32/// route syntax from `routes()`, plain `defunc` names those inferred programs
33/// directly. A backend such as `defunc(via = http)` or `defunc(via = jsonrpc)`
34/// additionally lifts convenient method references while producing named programs
35/// and their interpreter evidence.
36///
37/// Several backends are cumulative: `defunc(via = http, via = cli)` lowers the declarations each
38/// backend recognizes by its root call (`routes()`, `methods()`, `commands()`, `record()`) into that
39/// backend's programs, all in one extension. A bound on the block reaches every program in it, so
40/// a mixed block states each transport's algebra on the declarations of that transport, as in
41/// `fn status_api<Alg>(&self) where This: HttpRouteAlg`. A bound on `This` is what the program's
42/// interpreter answers, so it reaches the program's interpretation and not the method that names
43/// the program.
44///
45/// ```ignore
46/// use alux_ext::ext;
47///
48/// #[ext(name = CounterExt, defunc)]
49/// impl<This> This
50/// where
51/// This: CounterAlg,
52/// {
53/// async fn incremented(&self, by: u32) -> u32 {
54/// self.increment(by).await
55/// }
56/// }
57///
58/// // The expansion also defines `IncrementedOperation<This>`.
59/// ```
60///
61/// ```ignore
62/// use alux_ext::ext;
63/// use alux_http::http;
64///
65/// #[ext(name = StatusRoutesExt, defunc(via = http))]
66/// impl<This> This
67/// where
68/// This: HttpRouteAlg,
69/// {
70/// /// Declares the status surface.
71/// fn status_routes<Alg>(&self) {
72/// self.routes().get("/status", self.op(Alg::status_current).json())
73/// }
74/// }
75///
76/// // The expansion also defines `StatusRoutesProgram<Alg>`.
77/// ```
78#[proc_macro_attribute]
79pub fn ext(attr: TokenStream, item: TokenStream) -> TokenStream {
80 ext_internal(attr.into(), item.into()).unwrap_or_else(syn::Error::into_compile_error).into()
81}
82
83/// Lowers extension methods into named, composable HTTP programs.
84///
85/// This is the HTTP backend that `alux_ext::ext(..., defunc(via = http))` selects. `via = http`
86/// resolves the name in the authoring scope, so a declaration imports it as `use alux_http::http`.
87/// Applying the attribute directly means the same thing.
88///
89/// Each method becomes a first-order HTTP program. A route handler written with `op(...)` is replaced
90/// by the operation type generated by `alux_ext::ext(defunc)`, its declared input roles and output
91/// kind (`.json()`, `.out::<Kind>()`, and their wrappers) become one `HttpOperationAlg` bound on the
92/// interpreter, and a call to another method of the same extension becomes a nested program.
93///
94/// ```ignore
95/// use alux_ext::ext;
96/// use alux_http::{HttpRouteAlg, http};
97///
98/// #[ext(name = StatusApiExt, defunc(via = http))]
99/// impl<This> This
100/// where
101/// This: HttpRouteAlg,
102/// {
103/// /// Declares the status surface.
104/// fn status_api<Alg>(&self) {
105/// self.routes().get("/status", self.op(Alg::status_current).json())
106/// }
107/// }
108///
109/// // The expansion also defines `StatusApiProgram<Alg>`.
110/// ```
111#[proc_macro_attribute]
112pub fn http(attr: TokenStream, item: TokenStream) -> TokenStream {
113 http_program_defunc_internal(attr.into(), item.into()).unwrap_or_else(syn::Error::into_compile_error).into()
114}
115
116/// Lowers extension methods into named, composable JSON-RPC programs.
117///
118/// This is the JSON-RPC backend that `alux_ext::ext(..., defunc(via = jsonrpc))` selects. `via = jsonrpc`
119/// resolves the name in the authoring scope, so a declaration imports it as `use alux_jsonrpc::jsonrpc`.
120/// Applying the attribute directly means the same thing.
121///
122/// Each method becomes a first-order JSON-RPC program. A method handler written with `op(...)` is
123/// replaced by the operation type generated by `alux_ext::ext(defunc)`, the operation's argument
124/// product and output become bounds on the interpreter, `.named()` selects object decoding using the
125/// authored argument names, and a call to another method of the same extension becomes a nested
126/// program.
127///
128/// A `fallible` argument converts every declared method's error into a JSON-RPC protocol error, so
129/// each declaration that does not say otherwise is read as `.fallible()`. This argument belongs to
130/// the JSON-RPC backend; every other argument is read as `ext` reads it.
131///
132/// ```ignore
133/// use alux_ext::ext;
134/// use alux_jsonrpc::{JsonRpcApiAlg, jsonrpc};
135///
136/// #[ext(name = StatusRpcExt, defunc(via = jsonrpc))]
137/// impl<This> This
138/// where
139/// This: JsonRpcApiAlg,
140/// {
141/// /// Declares the status surface.
142/// fn status_rpc<Alg>(&self) {
143/// self.methods().method("status_current", self.op(Alg::status_current))
144/// }
145/// }
146///
147/// // The expansion also defines `StatusRpcProgram<Alg>`.
148/// ```
149#[proc_macro_attribute]
150pub fn jsonrpc(attr: TokenStream, item: TokenStream) -> TokenStream {
151 jsonrpc_program_defunc_internal(attr.into(), item.into()).unwrap_or_else(syn::Error::into_compile_error).into()
152}
153
154/// Lowers extension methods into named, composable shape programs.
155///
156/// This is the shape backend that `alux_ext::ext(..., defunc(via = shape))` selects. `via = shape`
157/// resolves the name in the authoring scope, so a declaration imports it as `use alux_shape::shape`.
158/// Applying the attribute directly means the same thing.
159///
160/// Each method becomes a first-order shape program named after the method, with a `_shape` suffix
161/// dropped. An identifier in name position states the words that name a member, splitting on `_`; a
162/// string literal there states a name no identifier spells. The record the declaration opens is named
163/// and closed by the expansion, so no declaration writes a name for it, a closing call, or a return
164/// type. A call to another method of the same extension becomes a nested program.
165///
166/// A shape body applies no handler — it reads the algebra through the same `self` the author wrote —
167/// so the bounds the impl states are the whole requirement, and no per-member evidence is generated.
168///
169/// The expansion adds no imports, because a declaration's `use` list is the author's. So everything a
170/// body reads must already be in scope: the algebra, and any extension the body derives its vocabulary
171/// from — `ShapeTaggedExt` for a tagged encoding, whatever ext states a leaf vocabulary of its own.
172/// `shape` itself must be in scope too, or `defunc(via = shape)` resolves to nothing: neither
173/// attribute expands, the authored block reaches the compiler as written, and the errors read
174/// `visibility qualifiers are not permitted here` on the `pub impl` followed by `cannot find value`
175/// for every member name. Nothing in that points at the missing import.
176///
177/// ```ignore
178/// use alux_ext::ext;
179/// use alux_shape::{FieldAlg, ShapeAlg, shape};
180///
181/// #[ext(name = UserShapeExt, defunc(via = shape))]
182/// pub impl<This> This
183/// where
184/// This: ShapeAlg + FieldAlg,
185/// {
186/// /// A user, as a surface answers one.
187/// fn user_shape(&self) {
188/// self.record().field(display_name, self.text()).field(email, self.opt(self.text()))
189/// }
190/// }
191///
192/// // The expansion also defines `UserShapeProgram`.
193/// ```
194#[proc_macro_attribute]
195pub fn shape(attr: TokenStream, item: TokenStream) -> TokenStream {
196 shape_program_defunc_internal(attr.into(), item.into()).unwrap_or_else(syn::Error::into_compile_error).into()
197}
198
199/// Lowers extension methods into named, composable CLI programs.
200///
201/// This is the CLI backend that `alux_ext::ext(..., defunc(via = cli))` selects. `via = cli`
202/// resolves the name in the authoring scope, so a declaration imports it as `use alux_cli::cli`.
203/// Applying the attribute directly means the same thing.
204///
205/// Each method becomes a first-order CLI program. A command handler written with `op(...)` is
206/// replaced by the operation type generated by `alux_ext::ext(defunc)`, its declared argument sources
207/// (`.arg(...)`) become one `CliOperationAlg` bound on the interpreter, `.nest(name, ...)`
208/// nests a program beneath a name, and a call to another method of the same extension becomes a
209/// nested program.
210///
211/// ```ignore
212/// use alux_cli::{CliCommandsAlg, cli};
213/// use alux_ext::ext;
214///
215/// #[ext(name = ReadingCliExt, defunc(via = cli))]
216/// impl<This> This
217/// where
218/// This: CliCommandsAlg,
219/// {
220/// /// Declares the reading commands.
221/// fn reading_cli<Machine, Name>(&self) {
222/// self.commands()
223/// .command("lookup", self.op(Machine::lookup).arg(self.positional("Requested name")))
224/// }
225/// }
226///
227/// // The expansion also defines `ReadingCliProgram<Machine, Name>`.
228/// ```
229#[proc_macro_attribute]
230pub fn cli(attr: TokenStream, item: TokenStream) -> TokenStream {
231 cli_program_defunc_internal(attr.into(), item.into()).unwrap_or_else(syn::Error::into_compile_error).into()
232}