alux_ext_macros/

lib.rs

//! Procedural macros for declaring and defunctionalizing DD programs.
//!
//! This crate is the shared syntax layer for DD extension, HTTP, and JSON-RPC programs.
//! Its public surface stays small: parsing, validation, and code generation
//! live in private modules, while this facade contains only procedural-macro
//! entry points. Product crates re-export the macros they own.
//!
//! Every example below is illustrative rather than tested. Expansion names `::alux_ext`,
//! `::alux_http`, and `::alux_jsonrpc`, and a procedural-macro crate cannot depend on the crates its
//! own expansion targets. The executed examples live in those crates' documentation.

mod ext;
mod extension;
mod http_program;
mod jsonrpc_program;
mod lower;
mod shape_program;
mod syntax;

use ext::ext_internal;
use http_program::http_program_defunc_internal;
use jsonrpc_program::jsonrpc_program_defunc_internal;
use proc_macro::TokenStream;
use shape_program::shape_program_defunc_internal;

/// Declares extension methods and optionally gives each method a first-order operation type.
///
/// Arguments unrelated to defunctionalization are forwarded to `extend::ext`.
/// Plain `defunc` produces a hidden `*Operation<Context>` type implementing
/// `OperationAlg` and `ApplyAlg`. When every method already builds first-order
/// route syntax from `routes()`, plain `defunc` names those inferred programs
/// directly. A backend such as `defunc(via = http)` or `defunc(via = jsonrpc)`
/// additionally lifts convenient method references while producing named programs
/// and their interpreter evidence.
///
/// ```ignore
/// use alux_ext::ext;
///
/// #[ext(name = CounterExt, defunc)]
/// impl<This> This
/// where
///     This: CounterAlg,
/// {
///     async fn incremented(&self, by: u32) -> u32 {
///         self.increment(by).await
///     }
/// }
///
/// // The expansion also defines `IncrementedOperation<This>`.
/// ```
///
/// ```ignore
/// use alux_ext::ext;
/// use alux_http::http;
///
/// #[ext(name = StatusRoutesExt, defunc(via = http))]
/// impl<This> This
/// where
///     This: HttpApiAlg + JsonOutAlg,
/// {
///     /// Declares the status surface.
///     fn status_routes<Alg>(&self)
///     where
///         Alg: StatusAlg,
///     {
///         self.routes().get("/status", self.op(Alg::status_current).json())
///     }
/// }
///
/// // The expansion also defines `StatusRoutesProgram<Alg>`.
/// ```
#[proc_macro_attribute]
pub fn ext(attr: TokenStream, item: TokenStream) -> TokenStream {
    ext_internal(attr.into(), item.into()).unwrap_or_else(syn::Error::into_compile_error).into()
}

/// Lowers extension methods into named, composable HTTP programs.
///
/// This is the HTTP backend that `alux_ext::ext(..., defunc(via = http))` selects. `via = http`
/// resolves the name in the authoring scope, so a declaration imports it as `use alux_http::http`.
/// Applying the attribute directly means the same thing.
///
/// Each method becomes a first-order HTTP program. A route handler written with `op(...)` is replaced
/// by the operation type generated by `alux_ext::ext(defunc)`, the declared input roles and output
/// kind become bounds on the interpreter, and a call to another method of the same extension becomes
/// a nested program.
///
/// ```ignore
/// use alux_ext::ext;
/// use alux_http::{HttpApiAlg, JsonOutAlg, http};
///
/// #[ext(name = StatusApiExt, defunc(via = http))]
/// impl<This> This
/// where
///     This: HttpApiAlg + JsonOutAlg,
/// {
///     /// Declares the status surface.
///     fn status_api<Alg>(&self)
///     where
///         Alg: StatusAlg,
///     {
///         self.routes().get("/status", self.op(Alg::status_current).json())
///     }
/// }
///
/// // The expansion also defines `StatusApiProgram<Alg>`.
/// ```
#[proc_macro_attribute]
pub fn http(attr: TokenStream, item: TokenStream) -> TokenStream {
    http_program_defunc_internal(attr.into(), item.into()).unwrap_or_else(syn::Error::into_compile_error).into()
}

/// Lowers extension methods into named, composable JSON-RPC programs.
///
/// This is the JSON-RPC backend that `alux_ext::ext(..., defunc(via = jsonrpc))` selects. `via = jsonrpc`
/// resolves the name in the authoring scope, so a declaration imports it as `use alux_jsonrpc::jsonrpc`.
/// Applying the attribute directly means the same thing.
///
/// Each method becomes a first-order JSON-RPC program. A method handler written with `op(...)` is
/// replaced by the operation type generated by `alux_ext::ext(defunc)`, the operation's argument
/// product and output become bounds on the interpreter, `.named()` selects object decoding using the
/// authored argument names, and a call to another method of the same extension becomes a nested
/// program.
///
/// A `fallible` argument converts every declared method's error into a JSON-RPC protocol error, so
/// each declaration that does not say otherwise is read as `.fallible()`. This argument belongs to
/// the JSON-RPC backend; every other argument is forwarded to `extend::ext`.
///
/// ```ignore
/// use alux_ext::ext;
/// use alux_jsonrpc::{JsonRpcApiAlg, jsonrpc};
///
/// #[ext(name = StatusRpcExt, defunc(via = jsonrpc))]
/// impl<This> This
/// where
///     This: JsonRpcApiAlg,
/// {
///     /// Declares the status surface.
///     fn status_rpc<Alg>(&self)
///     where
///         Alg: StatusAlg,
///     {
///         self.methods().method("status_current", self.op(Alg::status_current))
///     }
/// }
///
/// // The expansion also defines `StatusRpcProgram<Alg>`.
/// ```
#[proc_macro_attribute]
pub fn jsonrpc(attr: TokenStream, item: TokenStream) -> TokenStream {
    jsonrpc_program_defunc_internal(attr.into(), item.into()).unwrap_or_else(syn::Error::into_compile_error).into()
}

/// Lowers extension methods into named, composable shape programs.
///
/// This is the shape backend that `alux_ext::ext(..., defunc(via = shape))` selects. `via = shape`
/// resolves the name in the authoring scope, so a declaration imports it as `use alux_shape::shape`.
/// Applying the attribute directly means the same thing.
///
/// Each method becomes a first-order shape program named after the method, with a `_shape` suffix
/// dropped. An identifier in name position states the words that name a member, splitting on `_`; a
/// string literal there states a name no identifier spells. The record the declaration opens is named
/// and closed by the expansion, so no declaration writes a name for it, a closing call, or a return
/// type. A call to another method of the same extension becomes a nested program.
///
/// A shape body applies no handler — it reads the algebra through the same `self` the author wrote —
/// so the bounds the impl states are the whole requirement, and no per-member evidence is generated.
///
/// The expansion adds no imports, because a declaration's `use` list is the author's. So everything a
/// body reads must already be in scope: the algebra, and any extension the body derives its vocabulary
/// from — `ShapeTaggedExt` for a tagged encoding, whatever ext states a leaf vocabulary of its own.
/// `shape` itself must be in scope too, or `defunc(via = shape)` resolves to nothing: neither
/// attribute expands, the authored block reaches the compiler as written, and the errors read
/// `visibility qualifiers are not permitted here` on the `pub impl` followed by `cannot find value`
/// for every member name. Nothing in that points at the missing import.
///
/// ```ignore
/// use alux_ext::ext;
/// use alux_shape::{FieldAlg, ShapeAlg, shape};
///
/// #[ext(name = UserShapeExt, defunc(via = shape))]
/// pub impl<This> This
/// where
///     This: ShapeAlg + FieldAlg,
/// {
///     /// A user, as a surface answers one.
///     fn user_shape(&self) {
///         self.record().field(display_name, self.text()).field(email, self.opt(self.text()))
///     }
/// }
///
/// // The expansion also defines `UserShapeProgram`.
/// ```
#[proc_macro_attribute]
pub fn shape(attr: TokenStream, item: TokenStream) -> TokenStream {
    shape_program_defunc_internal(attr.into(), item.into()).unwrap_or_else(syn::Error::into_compile_error).into()
}