paganel_plugin_sdk_macros/lib.rs
1extern crate proc_macro;
2
3mod abi;
4mod common;
5mod filter;
6mod sink;
7mod source;
8mod transform;
9
10use crate::common::AttrArgs;
11use proc_macro::TokenStream;
12use syn::parse_macro_input;
13
14/// Attribute macro for transform plugins.
15///
16/// Wraps a function of the shape `fn(PluginInput) -> PluginResult<T>` (where
17/// `T: Into<Value>`) and emits the full transform ABI: shared exports plus
18/// `__paganel_transform`.
19///
20/// ## Required attributes
21///
22/// - `name` - plugin name (string).
23/// - `version` - plugin version (string).
24/// - `output` - output type tag, e.g. `"f64"`, `"string"` (string).
25/// - `input` - schema array, e.g. `[{ name = "x", type = "f64", nullable = false }, ...]`.
26#[proc_macro_attribute]
27pub fn paganel_transform(attr: TokenStream, item: TokenStream) -> TokenStream {
28 let attr = parse_macro_input!(attr as AttrArgs);
29 let user_fn = parse_macro_input!(item as syn::ItemFn);
30 transform::expand(attr, user_fn)
31 .unwrap_or_else(syn::Error::into_compile_error)
32 .into()
33}
34
35/// Attribute macro for filter plugins.
36///
37/// Wraps a function of the shape `fn(PluginInput) -> PluginResult<FilterDecision>`
38/// and emits the filter ABI: shared exports plus `__paganel_evaluate`.
39///
40/// ## Required attributes
41///
42/// - `name`, `version`, `input` (same shape as transform).
43///
44/// Filters do **not** accept `output` - they always return a `FilterDecision`.
45#[proc_macro_attribute]
46pub fn paganel_filter(attr: TokenStream, item: TokenStream) -> TokenStream {
47 let attr = parse_macro_input!(attr as AttrArgs);
48 let user_fn = parse_macro_input!(item as syn::ItemFn);
49 filter::expand(attr, user_fn)
50 .unwrap_or_else(syn::Error::into_compile_error)
51 .into()
52}
53
54/// Attribute macro for source plugins.
55///
56/// Wraps a function of the shape `fn(Option<String>) -> PluginResult<SourcePage>`
57/// - the argument is the cursor handed by the host. Emits the source ABI:
58/// shared exports plus `__paganel_read_page` and a default
59/// `__paganel_estimated_count` that returns `-1` (unknown).
60///
61/// ## Required attributes
62///
63/// - `name`, `version`.
64/// - `output_schema` - array of fields the source emits.
65///
66/// Sources do **not** accept `input` (they don't consume rows) or `output`.
67/// The generated `__paganel_initialize` parses the config JSON the host
68/// delivers and stashes it in the SDK's `OnceLock`; the user reads it via
69/// `paganel_plugin_sdk::source_config()`.
70#[proc_macro_attribute]
71pub fn paganel_source(attr: TokenStream, item: TokenStream) -> TokenStream {
72 let attr = parse_macro_input!(attr as AttrArgs);
73 let user_fn = parse_macro_input!(item as syn::ItemFn);
74 source::expand(attr, user_fn)
75 .unwrap_or_else(syn::Error::into_compile_error)
76 .into()
77}
78
79/// Attribute macro for sink plugins.
80///
81/// Wraps a function of the shape `fn(PluginBatch) -> PluginResult<WriteResult>`
82/// and emits the sink ABI: shared exports plus `__paganel_prepare`,
83/// `__paganel_write_batch`, and `__paganel_finalize` (the prepare/finalize
84/// pair are default no-op stubs in Phase 2).
85///
86/// ## Required attributes
87///
88/// - `name`, `version`, `input`.
89///
90/// Sinks do **not** accept `output` or `output_schema`. As with sources, the
91/// generated init parses config into the SDK's `OnceLock`, readable via
92/// `paganel_plugin_sdk::sink_config()`.
93#[proc_macro_attribute]
94pub fn paganel_sink(attr: TokenStream, item: TokenStream) -> TokenStream {
95 let attr = parse_macro_input!(attr as AttrArgs);
96 let user_fn = parse_macro_input!(item as syn::ItemFn);
97 sink::expand(attr, user_fn)
98 .unwrap_or_else(syn::Error::into_compile_error)
99 .into()
100}