duckfn_macro/lib.rs
1//! `duckfn-macro`:`duckfn` 的过程宏实现。
2//!
3//! 本 crate 提供属性宏、derive 宏和函数式宏,把一个普通的 Rust 函数/结构体包装成
4//! 可注册到 DuckDB 的扩展对象;运行时依赖在 `duckfn` crate 中。
5//!
6//! `duckfn-macro`: the procedural macros behind `duckfn`. This crate provides the attribute,
7//! derive and function-like macros that wrap an ordinary Rust function or struct into an object
8//! registerable with DuckDB; the runtime lives in the `duckfn` crate.
9
10/// 各属性宏共用的脚手架:入口调度、函数/参数包装、共用的类型与返回值解析。
11///
12/// Shared scaffolding for the attribute macros: entry dispatch, the function / argument wrappers
13/// and the shared types plus return-type parsing.
14mod common;
15/// `#[derive(DuckStruct)]` 的实现:把具名结构体映射为 DuckDB `STRUCT`。
16///
17/// Implementation of `#[derive(DuckStruct)]`: maps a named struct onto a DuckDB `STRUCT`.
18mod duck_struct_derive;
19/// `#[derive(DuckEnum)]` 的实现:把只有单元变体的枚举映射为 DuckDB `ENUM`。
20///
21/// Implementation of `#[derive(DuckEnum)]`: maps a unit-variant-only enum onto a DuckDB `ENUM`.
22mod duck_enum_derive;
23/// 过程宏内部的 token/类型解析工具。
24///
25/// Token and type parsing helpers used inside the procedural macros.
26pub(crate) mod macro_utils;
27/// `duckfn_entrypoint!` 的实现:生成扩展入口符号。
28///
29/// Implementation of `duckfn_entrypoint!`: generates the extension entry-point symbol.
30mod entrypoint;
31/// `duck_sql_macro_files!` 的实现:把若干 `.sql` 文件编译期内联并注册。
32///
33/// Implementation of `duck_sql_macro_files!`: inlines several `.sql` files at compile time and
34/// registers them.
35mod sql_macro_files;
36/// `#[duck_scalar_function]` 的实现(含它自己需要的参数)。
37///
38/// Implementation of `#[duck_scalar_function]` (with the arguments it needs).
39mod scalar_function;
40/// `#[duck_aggregate_function]` 的实现(含它自己需要的参数)。
41///
42/// Implementation of `#[duck_aggregate_function]` (with the arguments it needs).
43mod aggregate_function;
44/// `#[duck_table_function]` 的实现(含它自己需要的参数)。
45///
46/// Implementation of `#[duck_table_function]` (with the arguments it needs).
47mod table_function;
48/// `#[duck_copy_function]` 的实现(含它自己需要的参数)。
49///
50/// Implementation of `#[duck_copy_function]` (with the arguments it needs).
51mod copy_function;
52/// `#[duck_copy_from_function]` 的实现(含它自己需要的参数)。
53///
54/// Implementation of `#[duck_copy_from_function]` (with the arguments it needs).
55mod copy_from_function;
56/// `#[duck_cast_function]` 的实现(含它自己需要的参数)。
57///
58/// Implementation of `#[duck_cast_function]` (with the arguments it needs).
59mod cast_function;
60/// `#[duck_sql_macro]` 的实现(本宏不接受参数)。
61///
62/// Implementation of `#[duck_sql_macro]` (this macro takes no arguments).
63mod sql_macro;
64/// `#[duck_replacement_scan]` 的实现(含它自己需要的参数)。
65///
66/// Implementation of `#[duck_replacement_scan]` (with the arguments it needs).
67mod replacement_scan;
68/// `#[duck_custom_register]` 的实现(本宏不接受参数)。
69///
70/// Implementation of `#[duck_custom_register]` (this macro takes no arguments).
71mod custom_register;
72
73use crate::macro_utils::handle_token_stream2_result;
74use proc_macro::TokenStream;
75use syn::{DeriveInput, parse_macro_input};
76
77/// 把一个具名结构体映射成 DuckDB `STRUCT`(嵌套 LIST / MAP / ARRAY / STRUCT 均支持)。
78///
79/// 生成的实现同时让该结构体可用于:
80///
81/// - 标量函数的参数(作为一行多列);
82/// - 表函数的输出行;
83/// - 表函数的 bind 参数(用 `#[duck(named_param_from = "字段名")]` 指定命名参数起点);
84/// - 单独作为一个 STRUCT 列值读写。
85///
86/// 字段的可空性完全由字段类型表达:写 `Option<T>` 就是可空(NULL 取到 `None`),
87/// 写 `T` 就是 NOT NULL(NULL 会让整行/整个结构变成 NULL,bind 参数处则报错)。
88///
89/// 还可以用 `#[duck(sql_name = "ticket", create_type = true)]` 在加载期把这个结构体建成 catalog 里的
90/// 命名类型:`CREATE TYPE IF NOT EXISTS "ticket" AS STRUCT(...)`。字段类型不是宏写死的 —— 注册时把整
91/// 个结构体的 `LogicalType` 递归渲染成 SQL(走 DuckDB 的类型 introspection),因此枚举、嵌套结构体、
92/// LIST / ARRAY / MAP、DECIMAL 与手写的自定义字段类型都能自动带上;语句幂等,`LOAD` 多次不会报错。
93/// 把 `true` 换成 `"replace"` 则发 `CREATE OR REPLACE TYPE`,同名旧定义会被**覆盖**;
94/// 换成 `"print"` 则不建类型:DDL 被收进队列,等全部注册项跑完由入口点一次性打印出来,
95/// 方便先看看宏会生成什么。
96///
97/// Maps a named struct onto a DuckDB `STRUCT` (nested LIST / MAP / ARRAY / STRUCT are
98/// supported). The generated implementations let the struct be used as scalar-function
99/// arguments (a row of columns), as table-function output rows, as table-function bind
100/// parameters (use `#[duck(named_param_from = "field")]` to mark where named parameters start)
101/// and as a standalone STRUCT column value.
102///
103/// Field nullability is expressed purely by the field type: `Option<T>` is nullable (a NULL
104/// yields `None`) while `T` is NOT NULL (a NULL turns the whole row / struct into NULL, or, for
105/// a bind argument, into an error).
106///
107/// `#[duck(sql_name = "ticket", create_type = true)]` additionally creates a named type in the
108/// catalog at load time (`CREATE TYPE IF NOT EXISTS "ticket" AS STRUCT(...)`). The field types are
109/// not hard-coded: the struct's `LogicalType` is rendered recursively through DuckDB's own type
110/// introspection, so enums, nested structs, LIST / ARRAY / MAP, DECIMAL and hand-written custom
111/// field types all come along. The statement is idempotent. `"replace"` emits
112/// `CREATE OR REPLACE TYPE` instead and **overwrites** an existing type of that name. `"print"`
113/// does not create the type: the DDL is queued and the entry point prints the whole batch once every
114/// registration has run, which is handy for previewing what the macro would run.
115#[proc_macro_derive(DuckStruct, attributes(duck))]
116pub fn duck_struct_derive(input: TokenStream) -> TokenStream {
117 let derive_input = parse_macro_input!(input as DeriveInput);
118 let result = duck_struct_derive::duck_struct_derive(derive_input);
119 handle_token_stream2_result(result)
120}
121
122/// 把「只有单元变体的 Rust enum」映射成 DuckDB `ENUM`。
123///
124/// 生成的实现让该枚举可直接用于函数参数/返回值、`STRUCT` 字段与容器元素,逻辑类型是带字典的
125/// `ENUM('a', 'b', ...)`(字典就是变体的声明顺序)。ENUM 的规则很固定,所以这里生成完整实现,
126/// 而不是像 `#[derive(DuckStruct)]` 那样只生成 trait 实现再靠 blanket impl 兜底 ——
127/// `Option<T>` 与结构体已经各占一个 blanket impl,再加第三个会冲突(E0119)。
128///
129/// ```ignore
130/// #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, DuckEnum)]
131/// #[duck(rename_all = "lowercase", sql_name = "priority", create_type = true)]
132/// pub enum Priority {
133/// #[default]
134/// Low,
135/// Medium,
136/// High,
137/// }
138/// // SQL 侧:ENUM('low', 'medium', 'high'),并在加载时建好 `priority` 类型
139/// ```
140///
141/// `#[duck(...)]` 参数:
142///
143/// - `rename_all = "..."`:变体名 → SQL 标签的命名规则(`lowercase` / `UPPERCASE` /
144/// `snake_case` / `SCREAMING_SNAKE_CASE` / `camelCase` / `PascalCase` / `kebab-case` /
145/// `SCREAMING-KEBAB-CASE` / `verbatim`),默认原样使用变体名;
146/// - `sql_name = "..."`:SQL 侧类型名,默认是类型名的小写蛇形(`Priority` -> `priority`);
147/// - `create_type`:`true` 在加载期执行 `CREATE TYPE IF NOT EXISTS <sql_name> AS ENUM (...)`,
148/// `"replace"` 改发 `CREATE OR REPLACE TYPE`(覆盖同名旧定义),`"print"` 则不建类型、只把同一
149/// 条 DDL 收进队列,由入口点在全部注册跑完后一次性打印;默认 `false` 什么都不做。`true` 的语句
150/// 幂等(重复 `LOAD` 不报错),也不会覆盖已存在的同名类型,执行路径与 SQL 宏相同(`duckdb_query`);
151/// - 变体级 `#[duck(rename = "...")]`:单独覆盖某个变体的标签。
152///
153/// 约束:必须是 enum、不能带泛型、至少一个变体、变体不能带数据、标签不能重复。
154/// 作为**非可空**函数参数时还需要 `Default`(宏生成的参数结构体会 `derive(Default)`),
155/// 因此通常写成 `#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, DuckEnum)]` 并用
156/// `#[default]` 标一个变体;可空参数写 `Option<Priority>` 则不需要。
157///
158/// Maps a unit-variant-only Rust enum onto a DuckDB `ENUM`. The generated implementation lets the
159/// enum be used as a function argument/return value, as a `STRUCT` field and as a container
160/// element; its logical type is `ENUM('a', 'b', ...)` with the dictionary in declaration order.
161/// The ENUM rules are fixed, so this generates the whole implementation instead of leaning on a
162/// blanket impl — `Option<T>` and the struct derive already own one blanket impl each, and a third
163/// would conflict (E0119).
164///
165/// `#[duck(...)]` arguments: `rename_all = "..."` for the variant-name-to-label rule,
166/// `sql_name = "..."` for the SQL-side type name (defaults to the lowercase snake_case of the Rust
167/// name), and `create_type` — `true` runs `CREATE TYPE IF NOT EXISTS ...` at load time, `"replace"`
168/// runs `CREATE OR REPLACE TYPE ...` and overwrites an existing type of that name, while `"print"`
169/// creates nothing: it queues that same DDL for the entry point to print as one batch after every
170/// registration, and `false` (the default) does nothing (idempotent, leaves an existing
171/// type untouched, same execution path as the SQL macros). A single variant can override its label
172/// with `#[duck(rename = "...")]`. The input
173/// must be a non-generic enum with at least one data-free variant and distinct labels; a
174/// non-nullable function argument additionally needs `Default`.
175#[proc_macro_derive(DuckEnum, attributes(duck))]
176pub fn duck_enum_derive(input: TokenStream) -> TokenStream {
177 let derive_input = parse_macro_input!(input as DeriveInput);
178 let result = duck_enum_derive::duck_enum_derive(derive_input);
179 handle_token_stream2_result(result)
180}
181
182/// 把普通 Rust 函数注册成 DuckDB 标量函数。
183///
184/// 参数与返回值的映射规则(可空性完全由类型表达):
185///
186/// - 每个参数对应一个 SQL 参数,参数类型决定 DuckDB 逻辑类型与可空性:写 `T` 就是 NOT NULL,
187/// 写 `Option<T>` 就是可空 —— `Option<T>` 自己也实现了 `DuckValueType`,可空性由
188/// `DuckValueType::from_null` 承载;
189/// - 参数写成 `T` 时,输入为 NULL 会直接短路输出 NULL(函数体不执行);写成 `Option<T>`
190/// 时以 `None` 进入函数体,语义由函数自己决定;
191/// - 返回类型可以是 `T`、`Option<T>`(`None` -> SQL NULL)或 `DuckOptionResult<T>`
192/// (可失败、可为 NULL);`T` 与 `Option<T>` 都直接作为该列的值类型,只有
193/// `DuckOptionResult` 额外表示「可能失败」;
194/// - 函数体里的 panic 会被捕获并转成查询错误(仅原生;wasm/浏览器上 panic 接不住,会变成栈溢出);
195/// - `volatile = true` 把函数标记为 volatile:注册时调用
196/// `duckdb_scalar_function_set_volatile`,DuckDB 不缓存也不复用相同参数的调用结果,每一行
197/// 都重新求值(`random()` 这类函数需要它)。这是 DuckDB 1.2.0 起的稳定 C API,不需要
198/// `duckdb-1-5`;独立函数与 `overloads_name` 重载都支持;
199/// - `varargs = true` 开启可变参数:函数签名的最后一个参数必须是 `Vec<T>`(可变参数集合),
200/// `T` 的逻辑类型会交给 DuckDB 的 `duckdb_scalar_function_set_varargs`,调用时固定参数之后的
201/// 每一列都按 `T` 读出来、组成 `Vec<T>` 传给函数体。比如
202/// `fn my_sum(values: Vec<i64>) -> i64`。同样不需要 `duckdb-1-5`,独立函数与 `overloads_name`
203/// 重载都支持。
204/// - `batch = true` 开启批量模式:适配层本来就把整块数据读成一批行、再由默认实现逐行调用函数体,
205/// 这个开关把那层遍历也交给用户 —— 唯一的参数是整批行、返回值是整批结果。行类型由用户用
206/// `#[derive(DuckStruct)]` 定义并直接充当参数类型(宏不再生成 `DuckArgsImpl` 结构体):
207/// `fn f(rows: Vec<MyRow>) -> Vec<T>` 只收到非空行(结果按原位回填 NULL),
208/// `fn f(rows: Vec<Option<MyRow>>) -> DuckOptionResult<Vec<Option<T>>>` 则把空行以 `None`
209/// 交给函数体。返回形态还有 `Vec<T>` / `Vec<Option<T>>` / `DuckOptionResult<Vec<T>>`
210/// (`Ok(None)` 表示整批 NULL);返回行数必须与收到的行数一致,否则整条查询失败。
211/// 函数仍然按 chunk 调用,整表不会被拉进内存。不能与 `varargs = true` 同用。
212///
213/// 宏会生成一个同名模块,导出 `scalar_function_builder()` / `scalar_overload_builder()`(便于手动注册
214/// 重载或函数集),以及常量 `SQL_NAME` —— 该签名注册到 DuckDB 时真正使用的 SQL 名字(设了
215/// `overloads_name` 时是函数集名,否则是函数名)。
216///
217/// Registers an ordinary Rust function as a DuckDB scalar function. Each parameter maps to one
218/// SQL parameter whose type determines both the DuckDB logical type and nullability: `T` means
219/// NOT NULL while `Option<T>` means nullable — `Option<T>` implements `DuckValueType` itself,
220/// carrying nullability through `DuckValueType::from_null`. A `T` parameter short-circuits NULL
221/// input to NULL output without running the body, whereas an `Option<T>` parameter receives
222/// `None` and decides the semantics itself. The return type may be `T`, `Option<T>` (`None` maps
223/// to SQL NULL) or `DuckOptionResult<T>` (fallible and nullable): `T` and `Option<T>` are both
224/// used as the column's value type directly, and only `DuckOptionResult` adds a failure channel.
225/// Panics in the body are caught and turned into query errors (native only — on wasm a panic cannot
226/// unwind across the JS boundary and surfaces as a stack overflow). `volatile = true` marks the
227/// function volatile: registration then calls `duckdb_scalar_function_set_volatile`, so DuckDB
228/// neither caches nor reuses the result of a call with the same arguments and every row is
229/// re-evaluated (which is what functions like `random()` need). `varargs = true` enables variadic
230/// arguments: the last parameter must then be `Vec<T>` (the variadic collection) and `T`'s logical
231/// type goes to DuckDB's `duckdb_scalar_function_set_varargs`, so at call time every column after
232/// the fixed ones is read as a `T` and collected into the `Vec<T>` passed to the body — e.g.
233/// `fn my_sum(values: Vec<i64>) -> i64`. Both switches are part of the stable C API since DuckDB
234/// 1.2.0, so they need no `duckdb-1-5` feature, and both work on standalone functions and
235/// `overloads_name` overloads alike. `batch = true` enables batch
236/// mode: the adapter already reads a whole chunk as a batch of rows and its default implementation
237/// walks them one by one, and this switch hands that walk over to you — the single parameter is the
238/// whole batch of rows and the return value is the whole batch of results. The row type is a
239/// user-defined `#[derive(DuckStruct)]` struct used directly as the argument type (no `DuckArgsImpl`
240/// struct is generated): `fn f(rows: Vec<MyRow>) -> Vec<T>` receives only the non-NULL rows (their
241/// results are spliced back at the original positions), while
242/// `fn f(rows: Vec<Option<MyRow>>) -> DuckOptionResult<Vec<Option<T>>>` receives the NULL rows as
243/// `None`. The other return shapes are `Vec<T>`, `Vec<Option<T>>` and
244/// `DuckOptionResult<Vec<T>>` (`Ok(None)` nulls the whole batch); the returned row count must match
245/// the number of rows received or the query fails. The function is still called once per chunk, so
246/// a large table is never materialised. It cannot be combined with `varargs = true`. A module named
247/// after the
248/// function is generated, exporting `scalar_function_builder()` and `scalar_overload_builder()`
249/// for manual overload / function-set registration, plus the `SQL_NAME` constant holding the SQL
250/// name this signature is really registered under (the function-set name when `overloads_name` is
251/// set, the function name otherwise).
252#[proc_macro_attribute]
253pub fn duck_scalar_function(attr: TokenStream, item: TokenStream) -> TokenStream {
254 scalar_function::build(attr, item)
255}
256
257/// 把普通 Rust 函数注册成 DuckDB 聚合函数。
258///
259/// 函数需带一个 `&mut XxxState` 参数用于跨行累积状态(`XxxState` 需实现
260/// `duckfn::DuckAggregateState`,其 `Output` 即聚合的返回类型);其余参数是每行的输入。
261/// 返回值规则与标量函数一致,通常直接返回 `()`。
262///
263/// 宏生成同名模块并导出 `aggregate_function_builder()` / `aggregate_overload_builder()`,
264/// 以及常量 `SQL_NAME` —— 该签名注册到 DuckDB 时真正使用的 SQL 名字
265/// (设了 `overloads_name` 时是函数集名,否则是函数名);写错误信息前缀时读它,不必再手抄一遍属性
266/// 字面量。
267///
268/// Registers an ordinary Rust function as a DuckDB aggregate function. The function takes one
269/// `&mut XxxState` parameter that accumulates state across rows (`XxxState` must implement
270/// `duckfn::DuckAggregateState`, whose `Output` is the aggregate's return type); the remaining
271/// parameters are the per-row inputs. Return-type rules match scalar functions, though in
272/// practice `()` is returned. A module named after the function is generated, exporting
273/// `aggregate_function_builder()` and `aggregate_overload_builder()`, plus the `SQL_NAME` constant
274/// holding the SQL name this signature is really registered under (the function-set name when
275/// `overloads_name` is set, the function name otherwise) — read it for error-message prefixes
276/// instead of copying the attribute literal.
277///
278/// # `auto_collect = true`:先收集整列、再一次性计算
279///
280/// 「收集整列 → finalize 算一个值」是聚合里常见却又样板最多的形态(手写状态结构体 +
281/// `DuckAggregateState` + 逐行 `push`)。开启 `auto_collect` 后被标注函数**不再是逐行回调**,
282/// 而是聚合的**收尾函数**,宏把收集样板全部封装掉:
283///
284/// - `Vec<T>` 参数 = 要收集的列:宏逐行读 `T` 收进内部状态,finalize 时把 `Vec<T>` 交给本函数;
285/// - `DuckFirst<T>` 参数 = 逐行不变的标量常量:宏用 `DuckLazy<T>` + `DuckLazySlot<T>` 只解析一次,
286/// finalize 时把解析出的 `T` 交给本函数(`DuckFirst<T>` 是恒等别名,函数里拿到的就是 `T`);
287/// - 返回值即聚合结果,规则与标量函数一致(`-> T` / `-> Option<T>` / `-> DuckOptionResult<T>`)。
288///
289/// 空值传播与原写法完全一致:某行任一「非 `Option`」列为 NULL 时整行丢弃、不进收集,想保留
290/// NULL 就把该列写成 `Vec<Option<T>>`;标量常量同理,`DuckFirst<T>` 非可空、`DuckFirst<Option<T>>`
291/// 可空(整列为 NULL 得到 `None`)。一个非可空的 `DuckFirst<T>` 在空组时无从解析,此时结果为 NULL。
292/// 参数只能是这样两类之一,出现 `&mut State` 或普通标量会直接编译报错。该模式与 `overloads_name`、
293/// `auto_register` 等仍可组合。
294///
295/// ## `auto_collect = true`: collect the column, then compute once
296///
297/// "Collect a column, evaluate one value at finalize" is a common aggregate shape that otherwise
298/// costs the most boilerplate (a hand-written state struct + `DuckAggregateState` + a per-row
299/// `push`). With `auto_collect` the annotated function *is* the finalize handler rather than a row
300/// callback, and the macro hides the collection entirely:
301///
302/// - a `Vec<T>` parameter is a column to collect: rows are read as `T` into the generated state and
303/// the `Vec<T>` is handed to the function at finalize;
304/// - a `DuckFirst<T>` parameter is a per-query constant: it is resolved once through
305/// `DuckLazy<T>` + `DuckLazySlot<T>` and the `T` is passed in (`DuckFirst<T>` is an identity alias,
306/// so the function receives a plain `T`);
307/// - the return value is the aggregate result, following the same rules as scalar functions
308/// (`-> T`, `-> Option<T>` or `-> DuckOptionResult<T>`).
309///
310/// NULL propagation is unchanged: a NULL in any non-`Option` column drops the whole row from the
311/// collection — keep NULLs by writing `Vec<Option<T>>`. A scalar constant works the same way:
312/// `DuckFirst<T>` is non-nullable, `DuckFirst<Option<T>>` yields `None` when the whole column is
313/// NULL; a non-nullable `DuckFirst<T>` cannot resolve on an empty group, so the result is NULL. Only
314/// these two parameter kinds are allowed — a `&mut State` or a plain scalar is a compile error. The
315/// mode still combines with `overloads_name`, `auto_register` and the others.
316#[proc_macro_attribute]
317pub fn duck_aggregate_function(attr: TokenStream, item: TokenStream) -> TokenStream {
318 aggregate_function::build(attr, item)
319}
320
321/// 把返回迭代器的 Rust 函数注册成 DuckDB 表函数。
322///
323/// 函数参数即表函数的 bind 参数;返回类型支持三种形式:
324///
325/// - `impl Iterator<Item = Row>`:最简单,不支持出错;
326/// - `DuckResult<impl Iterator<Item = Row>>`:支持构建迭代器时出错;
327/// - `DuckFullIteratorResult<Row>`(即 `DuckResult<Box<dyn Iterator<Item = DuckOptionResult<Row>>>>`):
328/// 构建与逐行产出都可出错、行也可为 NULL。
329///
330/// `Row` 需实现 `DuckColumns`(一般用 `#[derive(DuckStruct)]`),其列即结果列。
331///
332/// Registers a Rust function returning an iterator as a DuckDB table function. The parameters
333/// are the bind parameters and three return shapes are supported: `impl Iterator<Item = Row>`
334/// (simplest, no error handling), `DuckResult<impl Iterator<Item = Row>>` (construction may
335/// fail), and `DuckFullIteratorResult<Row>` (both construction and per-row production may fail,
336/// and a row may be NULL). `Row` must implement `DuckColumns` (typically via
337/// `#[derive(DuckStruct)]`) and its columns become the result columns.
338#[proc_macro_attribute]
339pub fn duck_table_function(attr: TokenStream, item: TokenStream) -> TokenStream {
340 table_function::build(attr, item)
341}
342
343/// 把「按批写行」的 Rust 函数注册成 DuckDB 的 COPY 函数,为 `COPY ... TO` 提供自定义文件格式。
344///
345/// 需要 `duckfn` 打开 `duckdb-1-5` feature(DuckDB 1.5.0+ 的 C API 才提供 COPY 函数)。
346///
347/// 输出 schema 是**运行时**的:适配层在 bind 阶段把结果各列的类型反推成动态描述,sink 阶段再把每个
348/// 数据块读成动态行,因此 `LIST` / `STRUCT` / `MAP` 等嵌套列同样能写出。
349///
350/// 签名固定为「writer + 行批」两参,顺序可互换:
351///
352/// ```ignore
353/// use duckfn::{
354/// duck_copy_function, DuckCopyOptions, DuckCopyToWriter, DuckDynamicRow, DuckResult,
355/// DuckResultSchema,
356/// };
357/// use std::fs::File;
358/// use std::io::{BufWriter, Write};
359///
360/// /// writer 状态:持有已打开的输出文件与 bind 阶段定下的 schema。
361/// pub struct MyWriter {
362/// file: BufWriter<File>,
363/// schema: DuckResultSchema,
364/// }
365///
366/// impl DuckCopyToWriter for MyWriter {
367/// fn open(path: &str, schema: &DuckResultSchema, _options: &DuckCopyOptions)
368/// -> DuckResult<Self>
369/// {
370/// Ok(Self {
371/// file: BufWriter::new(File::create(path).map_err(/* … */)?),
372/// schema: schema.clone(),
373/// })
374/// }
375///
376/// fn write_rows(&mut self, rows: &[DuckDynamicRow]) -> DuckResult<()> {
377/// // 逐行逐列渲染;LIST / STRUCT / MAP 都能从 DuckDynamicValue 里取到
378/// Ok(())
379/// }
380///
381/// fn finish(&mut self) -> DuckResult<()> {
382/// self.file.flush().map_err(/* … */)?;
383/// Ok(())
384/// }
385/// }
386///
387/// /// 每个数据块调用一次;函数名即 `FORMAT <函数名>` 里的格式名。
388/// #[duck_copy_function]
389/// fn my_copy(writer: &mut MyWriter, rows: &[DuckDynamicRow]) -> DuckResult<()> {
390/// writer.write_rows(rows)
391/// }
392/// ```
393///
394/// - `&mut Writer`:COPY 的 writer 状态,需实现 `duckfn::DuckCopyToWriter`(`open` 在 global init
395/// 阶段拿到路径、动态 schema 与 COPY 选项,`finish` 在 finalize 阶段收尾);
396/// - `&[DuckDynamicRow]`:本批要写出的动态行(至多 `vector_size()` 行);行的列与 `open` 收到的
397/// schema 逐列对应,`None` 单元格就是 SQL NULL;
398/// - 返回 `DuckResult<()>`,入参或写出失败会让整条 `COPY` 失败,panic 也会被转成查询错误(仅原生;wasm 上会变成栈溢出)。
399///
400/// 四个生命周期阶段的回调由适配层生成:bind 把输出列反推成动态 schema 并读出 COPY 选项,global init
401/// 调用 `DuckCopyToWriter::open`,sink 把数据块读成动态行后调用被标注的函数,finalize 调用
402/// `DuckCopyToWriter::finish`。
403///
404/// 宏生成同名模块,导出 `copy_function_builder()` 与 `copy_function_register(connection)`;
405/// `auto_register = false` 时只生成它们、不自动注册。
406///
407/// Registers a batch-writing Rust function as a DuckDB copy function, providing a custom file format
408/// for `COPY ... TO`. Requires `duckfn`'s `duckdb-1-5` feature (only the DuckDB 1.5.0+ C API provides
409/// copy functions). The output schema is a **runtime** one: bind reconstructs every result column's
410/// type into a dynamic description and sink reads each data chunk into dynamic rows, so nested
411/// columns (`LIST` / `STRUCT` / `MAP`) can be written too. The signature is fixed to "writer + rows"
412/// (in either order): `&mut Writer` is the writer state implementing `duckfn::DuckCopyToWriter` (its
413/// `open` receives the path, the dynamic schema and the COPY options during global init; its
414/// `finish` wraps up during finalize), and `&[DuckDynamicRow]` is the batch to write, one column per
415/// schema column with `None` cells as SQL NULL. It returns `DuckResult<()>`: a failure fails the whole
416/// `COPY`, and a panic is turned into a query error as well (native only; on wasm it becomes a stack
417/// overflow). A module named after the function is
418/// generated, exporting `copy_function_builder()` and `copy_function_register(connection)`; with
419/// `auto_register = false` they are generated but nothing is registered.
420#[proc_macro_attribute]
421pub fn duck_copy_function(attr: TokenStream, item: TokenStream) -> TokenStream {
422 copy_function::build(attr, item)
423}
424
425/// 把「按批取行」的 Rust 函数注册成 DuckDB 的 COPY 读取格式,为 `COPY ... FROM` 提供自定义文件格式。
426///
427/// 需要 `duckfn` 打开 `duckdb-1-5` feature。
428///
429/// 目标表的 schema 由 DuckDB 给出,读取器**不能**声明结果列;装载时逐批取动态行写进目标表,因此
430/// `LIST` / `STRUCT` / `MAP` 等嵌套列同样能读入。
431///
432/// 签名固定为「reader + limit」两参,顺序可互换:
433///
434/// ```ignore
435/// use duckfn::{
436/// duck_copy_from_function, DuckCopyFromReader, DuckDynamicRow, DuckResult, DuckResultSchema,
437/// DuckStruct,
438/// };
439///
440/// /// bind 参数:字段 0 必须是文件路径(唯一的位置参数),其余字段是 COPY 的命名选项。
441/// #[derive(Default, Debug, Clone, DuckStruct)]
442/// #[duck(named_param_from = "skip_rows")]
443/// pub struct MyFromArgs {
444/// pub path: String,
445/// /// `COPY ... FROM 'f' (FORMAT my_from, SKIP_ROWS 2)`
446/// pub skip_rows: Option<i64>,
447/// }
448///
449/// pub struct MyReader { /* … */ }
450///
451/// impl DuckCopyFromReader for MyReader {
452/// type Args = MyFromArgs;
453///
454/// fn open(args: Self::Args, schema: &DuckResultSchema) -> DuckResult<Self> {
455/// // schema 就是目标表的列名与类型(含嵌套类型)
456/// /* … */
457/// }
458/// }
459///
460/// /// 每次取一批行;空 Vec 表示文件读完。函数名即 `FORMAT <函数名>` 里的格式名。
461/// #[duck_copy_from_function]
462/// fn my_from(reader: &mut MyReader, limit: usize) -> DuckResult<Vec<DuckDynamicRow>> {
463/// reader.next_batch(limit)
464/// }
465/// ```
466///
467/// - `&mut Reader`:读取器状态,需实现 `duckfn::DuckCopyFromReader`(`open` 在 bind 阶段拿到参数与
468/// 目标表 schema);
469/// - `limit: usize`:本批最多多少行(即一个 DuckDB 向量的行数);
470/// - 返回 `DuckResult<Vec<DuckDynamicRow>>`:空 `Vec` 表示流结束;行数与类型不匹配目标表时,错误由
471/// 适配层的按列校验给出。
472///
473/// 位置参数必须**恰好一个**(文件路径,`VARCHAR`),bind 阶段会校验;其余 `COPY ... FROM (...)` 选项
474/// 以命名参数到达(大小写不敏感),由 `Reader::Args` 声明 —— 未声明的选项 DuckDB 会在 bind 之前报错。
475///
476/// 宏生成同名模块,导出 `copy_from_register(connection)`;`auto_register = false` 时只生成、不注册。
477///
478/// Registers a batch-reading Rust function as a DuckDB copy-from format for `COPY ... FROM`.
479/// Requires `duckfn`'s `duckdb-1-5` feature. The target table's schema comes from DuckDB and the
480/// reader **must not** declare result columns; loading pulls dynamic rows batch by batch, so nested
481/// columns (`LIST` / `STRUCT` / `MAP`) load as well. The signature is fixed to "reader + limit" (in
482/// either order): `&mut Reader` is the reader state implementing `duckfn::DuckCopyFromReader` (its
483/// `open` receives the arguments and the target schema during bind) and `limit: usize` is the batch
484/// size (one DuckDB vector's row count). It returns `DuckResult<Vec<DuckDynamicRow>>`, where an empty
485/// `Vec` ends the stream; a row whose width or types disagree with the target table is reported by the
486/// adapter's per-column validation. Exactly **one** positional parameter (the file path, `VARCHAR`)
487/// is required and checked during bind; the remaining `COPY ... FROM (...)` options arrive as named
488/// parameters (case-insensitively) declared through `Reader::Args` — an undeclared option is rejected
489/// by DuckDB before bind. A module named after the function is generated, exporting
490/// `copy_from_register(connection)`; with `auto_register = false` it is generated but nothing is
491/// registered.
492#[proc_macro_attribute]
493pub fn duck_copy_from_function(attr: TokenStream, item: TokenStream) -> TokenStream {
494 copy_from_function::build(attr, item)
495}
496
497/// 手动注册入口:把 `fn(&Connection) -> DuckResult<()>` 交给扩展初始化时调用。
498///
499/// 用于 `auto_register = false` 的场景:宏生成的各种 `*_builder()` 需要自己注册,
500/// 这里是最方便的挂载点。
501///
502/// Manual registration entry point: makes a `fn(&Connection) -> DuckResult<()>` run during
503/// extension initialisation. It suits the `auto_register = false` case, where the generated
504/// `*_builder()` functions must be registered by hand.
505///
506/// # 示例 / Example
507///
508/// ```ignore
509/// #[duck_custom_register]
510/// fn register_my_stuff(c: &Connection) -> DuckResult<()> {
511/// unsafe { my_scalar::scalar_function_builder().register(c) }
512/// }
513/// ```
514#[proc_macro_attribute]
515pub fn duck_custom_register(attr: TokenStream, item: TokenStream) -> TokenStream {
516 custom_register::build(attr, item)
517}
518
519/// 把 `fn(源值) -> 目标值` 注册成 DuckDB 的 cast 函数,覆盖 `CAST(源 AS 目标)`。
520///
521/// 源类型来自唯一参数,目标类型来自返回类型;返回形式与 `duck_scalar_function` 一致:
522///
523/// ```ignore
524/// #[duck_cast_function]
525/// fn dfn_cast_str_to_int(s: String) -> DuckOptionResult<i32> {
526/// s.parse().map_err(|_| duck_error("not an integer"))
527/// }
528///
529/// // 允许把 NULL 带进函数体:入参写 Option<T>
530/// #[duck_cast_function]
531/// fn dfn_cast_bigint_to_double(v: Option<i64>) -> Option<f64> { ... }
532///
533/// // 允许 DuckDB 自动插入该转换
534/// #[duck_cast_function(implicit_cost = 100)]
535/// fn dfn_cast_str_to_bigint(s: String) -> i64 { ... }
536/// ```
537///
538/// - `CAST(x AS T)` 出错 -> 整条查询失败(`set_error`);
539/// - `TRY_CAST(x AS T)` 出错 -> 该行输出 NULL 并记录行级错误(`set_row_error`);
540/// - 属性支持 `auto_register = false` / `implicit_cost = N`,生成模块里导出
541/// `cast_function_builder()` 和 `cast_function_register()` 供手动注册。
542///
543/// Registers `fn(source) -> target` as a DuckDB cast function covering `CAST(source AS target)`.
544/// The source type comes from the single argument and the target type from the return type, with
545/// the same return shapes as `duck_scalar_function`. An error fails the whole query for
546/// `CAST(x AS T)` (`set_error`) but writes NULL and records a row-level error for
547/// `TRY_CAST(x AS T)` (`set_row_error`). The attribute accepts `auto_register = false` and
548/// `implicit_cost = N`, and the generated module exports `cast_function_builder()` and
549/// `cast_function_register()` for manual registration.
550#[proc_macro_attribute]
551pub fn duck_cast_function(attr: TokenStream, item: TokenStream) -> TokenStream {
552 cast_function::build(attr, item)
553}
554
555/// 注册一个 SQL 宏:函数返回 SQL 文本(或 builder),扩展初始化时执行/注册。
556///
557/// 支持的返回形式:
558///
559/// - `SqlMacro` / `DuckResult<SqlMacro>`:交给 quack-rs 直接注册;
560/// - `String` / `&'static str` / `DuckResult<...>`:作为 SQL 文本执行,
561/// 一段文本里可以有多条 `CREATE OR REPLACE MACRO` 语句。
562///
563/// Registers a SQL macro: the function returns SQL text (or a builder) that is executed or
564/// registered when the extension initialises. Supported return shapes are `SqlMacro` /
565/// `DuckResult<SqlMacro>` (registered through quack-rs) and `String` / `&'static str` /
566/// `DuckResult<...>` (executed as SQL text, which may contain several
567/// `CREATE OR REPLACE MACRO` statements).
568#[proc_macro_attribute]
569pub fn duck_sql_macro(attr: TokenStream, item: TokenStream) -> TokenStream {
570 sql_macro::build(attr, item)
571}
572
573/// 把 `SELECT * FROM 'data.myformat'` 这类「未知表名/文件路径」重定向到某个表函数。
574///
575/// 函数签名只接受一个「表名(路径)」参数,返回目标表函数的名字:
576///
577/// ```ignore
578/// #[duck_replacement_scan]
579/// fn dfn_scan_points(path: &str) -> DuckOptionResult<String> {
580/// if path.ends_with(".points") {
581/// return Ok(Some("dfn_read_points".to_string()));
582/// }
583/// Ok(None)
584/// }
585/// ```
586///
587/// - `Ok(Some(table_function))`:接管,并把路径作为第一个 VARCHAR 参数传给该表函数;
588/// - `Ok(None)`:不接管,DuckDB 继续尝试其他 replacement scan;
589/// - `Err(..)` / panic:整条查询以该错误结束(仅原生;wasm 上 panic 会变成栈溢出、不是该错误)。
590///
591/// 返回值可以是 `Option<String>` / `Option<&'static str>` /
592/// `DuckOptionResult<String>` / `DuckOptionResult<&'static str>`。
593///
594/// Redirects "unknown table names / file paths" such as `SELECT * FROM 'data.myformat'` to a
595/// table function. The signature takes exactly one table-name (path) argument and returns the
596/// name of the target table function: `Ok(Some(table_function))` takes over and passes the path
597/// as the first VARCHAR argument; `Ok(None)` declines so DuckDB tries the next replacement scan;
598/// `Err(..)` or a panic fails the whole query (on wasm a panic surfaces as a stack overflow, not the
599/// message). The return type may be `Option<String>` /
600/// `Option<&'static str>` / `DuckOptionResult<String>` / `DuckOptionResult<&'static str>`.
601#[proc_macro_attribute]
602pub fn duck_replacement_scan(attr: TokenStream, item: TokenStream) -> TokenStream {
603 replacement_scan::build(attr, item)
604}
605
606/// Generate DuckDB extension entry point.
607///
608/// 生成 DuckDB 扩展入口:`duckfn_entrypoint!("duckfn");`
609/// 扩展名必须全小写、只含字母/数字/下划线。
610///
611/// Generates the DuckDB extension entry point: `duckfn_entrypoint!("duckfn");`. The
612/// extension name must be lowercase and contain only letters, digits and underscores.
613///
614/// Expands to:
615///
616/// ```ignore
617/// quack_rs::entry_point_v2!(
618/// duckfn_init_c_api,
619/// duckfn::register_all_duckfn
620/// );
621/// ```
622#[proc_macro]
623pub fn duckfn_entrypoint(input: TokenStream) -> TokenStream {
624 entrypoint::duckfn_entrypoint(input)
625}
626
627/// 一次注册多个 SQL 脚本文件(快捷方式)。
628///
629/// ```ignore
630/// duck_sql_macro_files!("sql/a.sql", "sql/b.sql", "sql/c.sql");
631/// ```
632///
633/// 参数是可变多个字符串字面量(文件路径),支持尾随逗号,至少一个。
634/// 每个文件在编译期用 `include_str!` 内联(路径相对「调用本宏的 .rs 文件」),
635/// 扩展初始化时按书写顺序依次执行整段脚本 —— 一份脚本里可以有多条
636/// 分号分隔的 `CREATE OR REPLACE MACRO` 语句。
637///
638/// 与 `#[duck_sql_macro]` 的关系:后者作用在函数上,由函数返回 SQL;
639/// 本宏不需要写函数,直接把若干 .sql 文件注册出去。
640///
641/// Registers several SQL script files at once (a shortcut). The arguments are one or more
642/// string literals (file paths) with an optional trailing comma; at least one is required.
643/// Each file is inlined at compile time with `include_str!` (paths are resolved relative to the
644/// `.rs` file that invokes the macro) and the whole script is executed in written order when the
645/// extension initialises — one script may contain several semicolon-separated
646/// `CREATE OR REPLACE MACRO` statements. Unlike `#[duck_sql_macro]`, which annotates a function
647/// returning SQL, this macro needs no function and simply registers the `.sql` files.
648#[proc_macro]
649pub fn duck_sql_macro_files(input: TokenStream) -> TokenStream {
650 sql_macro_files::duck_sql_macro_files(input)
651}
652