Skip to main content

day_persistence_macros/
lib.rs

1// Copyright © The Daybrite Project
2// SPDX-License-Identifier: MPL-2.0
3
4//! `#[derive(Model)]`: the day-persistence derive (docs/persistence.md).
5//!
6//! `Model` implies `Observable` and adds the schema half: `impl day_persistence::Model` with
7//! the table name, column list, row↔struct mappers and the default row, typed column
8//! references for predicates (`Trip::name()`), and the relation accessors and wiring.
9//! `#[model(id)]` marks the key; field options are `column = "…"`, `unique`, `index`,
10//! `transient` (observable, never stored), `with = Codec`, `json`, `relation(…)` and
11//! `link(…)`; struct options are `table = "…"`, `external = "alias"`, `index("a", "b")` for
12//! composites, `fts(…)` and `spatial(…)`. `#[obs(skip)]` leaves a field out of both halves: a
13//! field the change log cannot name could never mark its row dirty, so persisting it would
14//! silently lose edits.
15//!
16//! The observable half is not generated here. The derive describes the struct to day-macros'
17//! `observable_impls!` (reached as `day_persistence::__observable_impls!`), which emits exactly
18//! what `#[derive(Observable)]` would for the same fields. That one macro is the whole
19//! contract between this derive and the framework's: this crate owns the `#[model(…)]` grammar
20//! and the schema emission, day-macros owns the accessors, and neither reads the other's
21//! attributes.
22//!
23//! Generated paths say `day_persistence::…` and `day_model::…` unqualified. An app that derives
24//! `Model` depends on day-persistence directly, which resolves the first; `use
25//! day::prelude::*` with the facade's `model` feature (or a direct day-model dependency)
26//! resolves the second.
27//!
28//! Same construction as day-macros, with neither syn nor quote. A derive that needs field
29//! names and type tokens never has to understand a type, only re-emit it.
30
31use proc_macro::{Delimiter, TokenStream, TokenTree};
32
33/// A persistable model: everything `#[derive(Observable)]` generates, plus `impl
34/// day_persistence::Model`: table name, column list, row↔struct mappers and the default row.
35/// See day-persistence's crate docs and `docs/persistence.md`.
36///
37/// `#[model(id)]` marks the key (it is `#[obs(key)]` too). Field options: `column = "…"`,
38/// `unique`, `index`, `transient` (observable, never stored), `with = Codec`, `json`. Struct
39/// options: `table = "…"` (snake_cased struct name otherwise), `index("a", "b")` for
40/// composites. `#[obs(skip)]` removes a field from both halves.
41#[proc_macro_derive(Model, attributes(model, obs))]
42pub fn model(input: TokenStream) -> TokenStream {
43    finish(expand_model(input))
44}
45
46fn finish(result: Result<String, String>) -> TokenStream {
47    match result {
48        Ok(out) => out
49            .parse()
50            .unwrap_or_else(|e| panic!("generated code did not parse: {e}")),
51        Err(msg) => format!("compile_error!({msg:?});")
52            .parse()
53            .expect("compile_error! literal always parses"),
54    }
55}
56
57#[derive(Default)]
58struct FieldDef {
59    name: String,
60    ty: String,
61    key: bool,
62    skip: bool,
63    // The #[model(…)] half; inert under a bare Observable.
64    column: Option<String>,
65    unique: bool,
66    indexed: bool,
67    transient: bool,
68    with: Option<String>,
69    json: bool,
70    /// `#[model(relation(…))]`: a `Many<T>` marker field. It gets no column or plain accessor;
71    /// the Model derive emits a `RelationRef` accessor and the wiring instead.
72    relation: Option<RelationAttr>,
73    /// `#[model(link(…))]`: a `Linked<T>` marker field, a relation by value rather than by
74    /// key, across databases (docs/persistence.md). It gets no column or accessor; the Model
75    /// derive emits the predicate builder and the `LinkDef`.
76    link: Option<LinkAttr>,
77}
78
79/// The parsed `link(target = T, local = "column", remote = "column")`.
80struct LinkAttr {
81    target: String,
82    local: String,
83    remote: String,
84}
85
86/// The parsed `relation(target = T, inverse = "…", delete = "…", ordered = "…", join = "…")`.
87struct RelationAttr {
88    target: String,
89    inverse: Option<String>,
90    delete: String,
91    ordered: Option<String>,
92    join: Option<String>,
93}
94
95impl FieldDef {
96    fn column_name(&self) -> &str {
97        self.column.as_deref().unwrap_or(&self.name)
98    }
99    fn persisted(&self) -> bool {
100        !self.skip && !self.transient && self.relation.is_none() && self.link.is_none()
101    }
102    fn nullable(&self) -> bool {
103        self.ty == "Option" || self.ty.starts_with("Option <")
104    }
105}
106
107struct StructDef {
108    name: String,
109    table: Option<String>,
110    /// `external = "alias"`: the table lives in a database ATTACHed under `alias`, managed by
111    /// someone else, so it is read-only and gets neither DDL nor a migration.
112    external: Option<String>,
113    composites: Vec<Vec<String>>,
114    fts: Vec<String>,
115    fts_tokenize: Option<String>,
116    spatial: Option<(String, String)>,
117    fields: Vec<FieldDef>,
118}
119
120fn expand_model(input: TokenStream) -> Result<String, String> {
121    let def = parse_struct(input)?;
122    let keys: Vec<&FieldDef> = def.fields.iter().filter(|f| f.key).collect();
123    let key = match keys.as_slice() {
124        [k] => *k,
125        [] => {
126            return Err(format!(
127                "Model: `{}` needs exactly one field marked #[model(id)]",
128                def.name
129            ));
130        }
131        _ => {
132            return Err(format!(
133                "Model: `{}` marks more than one field as the id",
134                def.name
135            ));
136        }
137    };
138    if key.transient || key.skip {
139        return Err(format!(
140            "Model: `{}`'s id field cannot be transient or skipped",
141            def.name
142        ));
143    }
144    if key.with.is_some() || key.json {
145        // The key's stored form must match its `Key` form: the fold's WHERE parameters and
146        // external-merge decoding both derive it from the key kind, not from a codec.
147        return Err(format!(
148            "Model: `{}`'s id field takes no codec — integer, Uuid and String keys store \
149             in their canonical forms",
150            def.name
151        ));
152    }
153
154    let mut out = observable_impls(&def);
155    out.push_str(&emit_model(&def, key)?);
156    Ok(out)
157}
158
159// ---------------------------------------------------------------------------
160// Emission
161// ---------------------------------------------------------------------------
162
163/// The observable half, handed to day-macros: the struct restated with only what `Observable`
164/// reads. The key carries `#[obs(key)]`; skipped fields are left out, and so are relation and
165/// link markers, which observe through their `RelationRef` accessor (emitted below) rather
166/// than a plain `Field`: a `Many` holds nothing a `Field` could usefully bind.
167fn observable_impls(def: &StructDef) -> String {
168    let mut out = format!(
169        "day_persistence::__observable_impls! {{\n    struct {} {{\n",
170        def.name
171    );
172    for f in def
173        .fields
174        .iter()
175        .filter(|f| !f.skip && f.relation.is_none() && f.link.is_none())
176    {
177        let key = if f.key { "#[obs(key)] " } else { "" };
178        out.push_str(&format!("        {key}{}: {},\n", f.name, f.ty));
179    }
180    out.push_str("    }\n}\n");
181    out
182}
183
184/// The schema half. Every generated expression goes through `day_persistence::` paths and the
185/// field's type: the derive never guesses a SQL type, it asks `ColumnValue::SQL_TYPE` (or
186/// the named codec's) at compile time.
187fn emit_model(def: &StructDef, key: &FieldDef) -> Result<String, String> {
188    let name = &def.name;
189    let bare_table = def.table.clone().unwrap_or_else(|| snake_case(name));
190    // An external table is addressed through its database alias everywhere SQL names it
191    // (the fault SELECT, predicates, the FTS shadow `alias.table_fts`), which is what one
192    // qualified `TABLE` constant gives every existing code path at once.
193    let table = match &def.external {
194        Some(alias) => format!("{alias}.{bare_table}"),
195        None => bare_table,
196    };
197    let persisted: Vec<&FieldDef> = def.fields.iter().filter(|f| f.persisted()).collect();
198    for f in def.fields.iter().filter(|f| f.link.is_some()) {
199        let l = f.link.as_ref().expect("filtered");
200        if !persisted.iter().any(|p| p.column_name() == l.local) {
201            return Err(format!(
202                "Model: link(…) on `{}` names local = {:?}, which is not a persisted column of `{name}`",
203                f.name, l.local
204            ));
205        }
206    }
207
208    let mut columns = String::new();
209    for f in &persisted {
210        let sql = sql_type_expr(f);
211        columns.push_str(&format!(
212            "        day_persistence::ColumnDef {{ name: \"{}\", field: \"{}\", sql: {sql}, \
213             not_null: {}, unique: {}, indexed: {} }},\n",
214            f.column_name(),
215            f.name,
216            !f.nullable(),
217            f.unique,
218            f.indexed,
219        ));
220    }
221
222    // fts()/spatial() name COLUMNS; a typo would silently index nothing, so check now.
223    let column_names: Vec<&str> = persisted.iter().map(|f| f.column_name()).collect();
224    for c in &def.fts {
225        if !column_names.contains(&c.as_str()) {
226            return Err(format!(
227                "Model: fts(…) names `{c}`, which is not a persisted column of `{name}`"
228            ));
229        }
230    }
231    if let Some((lat, lon)) = &def.spatial {
232        for c in [lat, lon] {
233            if !column_names.contains(&c.as_str()) {
234                return Err(format!(
235                    "Model: spatial(…) names `{c}`, which is not a persisted column of `{name}`"
236                ));
237            }
238        }
239    }
240
241    let composites = def
242        .composites
243        .iter()
244        .map(|cols| {
245            format!(
246                "&[{}]",
247                cols.iter()
248                    .map(|c| format!("\"{c}\""))
249                    .collect::<Vec<_>>()
250                    .join(", ")
251            )
252        })
253        .collect::<Vec<_>>()
254        .join(", ");
255
256    let mut to_row = String::new();
257    for f in &persisted {
258        to_row.push_str(&format!("            {},\n", encode_expr(f)));
259    }
260
261    let mut from_row = String::new();
262    for f in &def.fields {
263        if let Some(i) = persisted.iter().position(|p| p.name == f.name) {
264            from_row.push_str(&format!("            {}: {},\n", f.name, decode_expr(f, i)));
265        } else {
266            from_row.push_str(&format!(
267                "            {}: ::core::default::Default::default(),\n",
268                f.name
269            ));
270        }
271    }
272
273    // Typed column refs: `Trip::name()` in a predicate, beside `trip.name()` the binding.
274    // Inherent fns without a receiver never collide with the Fields trait's methods (which
275    // take self): method-call syntax finds the trait, path syntax finds these.
276    let mut cols = String::new();
277    for f in &persisted {
278        let encode = match codec(f) {
279            Some(codec) => format!(
280                "<{codec} as day_persistence::ValueCodec<{}>>::to_sqlite_value",
281                f.ty
282            ),
283            None => format!("day_persistence::encode_column::<{}>", f.ty),
284        };
285        cols.push_str(&format!(
286            "    pub fn {}() -> day_persistence::Col<{}> {{\n\
287             \x20       day_persistence::Col::new(\"{}\", \"{}\", \"{table}\", {encode})\n\
288             \x20   }}\n",
289            f.name,
290            f.ty,
291            f.column_name(),
292            f.name,
293        ));
294    }
295    // The static relation reference, for predicates. The instance accessor of the same name
296    // lives on the Relations trait and takes `self`, so path syntax finds this one and
297    // method-call syntax finds that one, the rule `Trip::name()` already relies on.
298    for f in def.fields.iter().filter(|f| f.relation.is_some()) {
299        let r = f.relation.as_ref().expect("filtered");
300        cols.push_str(&format!(
301            "    pub fn {}() -> day_persistence::RelationCol<{name}, {}> {{\n\
302             \x20       day_persistence::RelationCol::new(\"{}\", \"{table}\", \
303             <{} as day_persistence::Model>::TABLE)\n\
304             \x20   }}\n",
305            f.name, r.target, f.name, r.target,
306        ));
307    }
308    // A link's predicate builder is a plain RelationCol: the container resolves the
309    // (owner, field) pair to the link's join condition at compile time, so `any`/`none`/
310    // `is_empty`/`count_ge` read exactly as they do across a keyed relation.
311    for f in def.fields.iter().filter(|f| f.link.is_some()) {
312        let l = f.link.as_ref().expect("filtered");
313        cols.push_str(&format!(
314            "    pub fn {}() -> day_persistence::RelationCol<{name}, {}> {{\n\
315             \x20       day_persistence::RelationCol::new(\"{}\", \"{table}\", \
316             <{} as day_persistence::Model>::TABLE)\n\
317             \x20   }}\n",
318            f.name, l.target, f.name, l.target,
319        ));
320    }
321    if !def.fts.is_empty() {
322        cols.push_str(&format!(
323            "    pub fn fts() -> day_persistence::FtsRef {{\n\
324             \x20       day_persistence::FtsRef {{ columns: <{name} as day_persistence::Model>::FTS_COLUMNS }}\n\
325             \x20   }}\n"
326        ));
327    }
328    if let Some((lat, lon)) = &def.spatial {
329        cols.push_str(&format!(
330            "    pub fn geo() -> day_persistence::GeoRef {{\n\
331             \x20       day_persistence::GeoRef {{ lat: \"{lat}\", lon: \"{lon}\" }}\n\
332             \x20   }}\n"
333        ));
334    }
335    let col_impl = format!("#[allow(dead_code)]\nimpl {name} {{\n{cols}}}\n");
336
337    // Relations: the const table, the wiring, and the RelationRef accessor trait.
338    let rels: Vec<(&FieldDef, &RelationAttr)> = def
339        .fields
340        .iter()
341        .filter_map(|f| f.relation.as_ref().map(|r| (f, r)))
342        .collect();
343    let delete_expr = |d: &str| match d {
344        "cascade" => "day_persistence::DeleteRule::Cascade",
345        "deny" => "day_persistence::DeleteRule::Deny",
346        _ => "day_persistence::DeleteRule::Nullify",
347    };
348    let opt_str = |o: &Option<String>| match o {
349        Some(s) => format!("Some(\"{s}\")"),
350        None => "None".into(),
351    };
352    let relations_const = if rels.is_empty() {
353        String::new()
354    } else {
355        format!(
356            "    const RELATIONS: &'static [day_persistence::RelationDef] = &[\n{}    ];\n",
357            rels.iter()
358                .map(|(f, r)| format!(
359                    "        day_persistence::RelationDef {{ field: \"{}\", target_table: \
360                     <{} as day_persistence::Model>::TABLE, inverse: \"{}\", delete: {}, \
361                     ordered: {}, join: {} }},\n",
362                    f.name,
363                    r.target,
364                    r.inverse.as_deref().unwrap_or(""),
365                    delete_expr(&r.delete),
366                    opt_str(&r.ordered),
367                    opt_str(&r.join),
368                ))
369                .collect::<String>()
370        )
371    };
372    let wire_fn = if rels.is_empty() {
373        String::new()
374    } else {
375        format!(
376            "    fn wire(reg: &mut day_persistence::Registrar<'_>) {{\n{}    }}\n",
377            rels.iter()
378                .map(|(f, r)| match (&r.join, &r.inverse) {
379                    (Some(join), _) => format!(
380                        "        day_persistence::wire_join::<Self, {}>(reg, \"{}\", \
381                         \"{join}\", {}, {});\n",
382                        r.target,
383                        f.name,
384                        opt_str(&r.ordered),
385                        delete_expr(&r.delete),
386                    ),
387                    (None, Some(inverse)) => format!(
388                        "        day_persistence::wire_to_many::<Self, {}>(reg, \"{}\", \
389                         \"{inverse}\", {}, {});\n",
390                        r.target,
391                        f.name,
392                        delete_expr(&r.delete),
393                        opt_str(&r.ordered),
394                    ),
395                    (None, None) => String::new(), // refused at parse time
396                })
397                .collect::<String>()
398        )
399    };
400    let rel_trait = if rels.is_empty() {
401        String::new()
402    } else {
403        format!(
404            "#[allow(non_camel_case_types)]\n\
405             pub trait {name}Relations: day_model::Source<{name}> + Sized {{\n{}}}\n\
406             impl<S: day_model::Source<{name}>> {name}Relations for S {{}}\n",
407            rels.iter()
408                .map(|(f, r)| format!(
409                    "    fn {}(self) -> day_persistence::RelationRef<Self, {name}, {}> {{\n\
410                     \x20       day_persistence::RelationRef::new(day_model::project(\
411                     self, \"{}\", |s| &s.{}, |s| &mut s.{}))\n\
412                     \x20   }}\n",
413                    f.name, r.target, f.name, f.name, f.name
414                ))
415                .collect::<String>()
416        )
417    };
418
419    let fts_const = if def.fts.is_empty() {
420        String::new()
421    } else {
422        let tokenize = match &def.fts_tokenize {
423            Some(t) => format!(
424                "    const FTS_TOKENIZE: Option<&'static str> = Some(\"{}\");\n",
425                t.replace('\\', "\\\\").replace('"', "\\\"")
426            ),
427            None => String::new(),
428        };
429        format!(
430            "    const FTS_COLUMNS: &'static [&'static str] = &[{}];\n{tokenize}",
431            def.fts
432                .iter()
433                .map(|c| format!("\"{c}\""))
434                .collect::<Vec<_>>()
435                .join(", ")
436        )
437    };
438    let links: Vec<(&FieldDef, &LinkAttr)> = def
439        .fields
440        .iter()
441        .filter_map(|f| f.link.as_ref().map(|l| (f, l)))
442        .collect();
443    let links_const = if links.is_empty() {
444        String::new()
445    } else {
446        format!(
447            "    const LINKS: &'static [day_persistence::LinkDef] = &[\n{}    ];\n",
448            links
449                .iter()
450                .map(|(f, l)| format!(
451                    "        day_persistence::LinkDef {{ field: \"{}\", local: \"{}\", \
452                     target_table: <{} as day_persistence::Model>::TABLE, remote: \"{}\" }},\n",
453                    f.name, l.local, l.target, l.remote
454                ))
455                .collect::<String>()
456        )
457    };
458    let external_const = if def.external.is_some() {
459        "    const EXTERNAL: bool = true;\n".to_string()
460    } else {
461        String::new()
462    };
463    let spatial_const = match &def.spatial {
464        None => String::new(),
465        Some((lat, lon)) => format!(
466            "    const SPATIAL: Option<day_persistence::SpatialCols> = \
467             Some(day_persistence::SpatialCols {{ lat: \"{lat}\", lon: \"{lon}\" }});\n"
468        ),
469    };
470
471    let key_sql = sql_type_expr(key);
472    Ok(col_impl
473        + &rel_trait
474        + &format!(
475            "impl day_persistence::Model for {name} {{\n\
476         \x20   const TABLE: &'static str = \"{table}\";\n\
477         \x20   const KEY: &'static str = \"{key_col}\";\n\
478         \x20   const KEY_SQL: day_persistence::SqlType = {key_sql};\n\
479         \x20   const COLUMNS: &'static [day_persistence::ColumnDef] = &[\n{columns}    ];\n\
480         \x20   const COMPOSITE_INDEXES: &'static [&'static [&'static str]] = &[{composites}];\n\
481         {fts_const}{spatial_const}{relations_const}{links_const}{external_const}\
482         \x20   fn to_row(&self) -> Vec<day_persistence::Value> {{\n\
483         \x20       vec![\n{to_row}        ]\n\
484         \x20   }}\n\
485         \x20   fn from_row(row: &dyn day_persistence::Row) -> \
486         Result<Self, day_persistence::DbError> {{\n\
487         \x20       Ok(Self {{\n{from_row}        }})\n\
488         \x20   }}\n\
489         \x20   fn default_row() -> Vec<day_persistence::Value> {{\n\
490         \x20       day_persistence::Model::to_row(&<Self as ::core::default::Default>::default())\n\
491         \x20   }}\n\
492         {wire_fn}\
493         }}\n",
494            key_col = key.column_name(),
495        ))
496}
497
498fn sql_type_expr(f: &FieldDef) -> String {
499    match codec(f) {
500        Some(codec) => format!(
501            "<{codec} as day_persistence::ValueCodec<{}>>::SQL_TYPE",
502            f.ty
503        ),
504        None => format!("<{} as day_persistence::ColumnValue>::SQL_TYPE", f.ty),
505    }
506}
507
508fn encode_expr(f: &FieldDef) -> String {
509    match codec(f) {
510        Some(codec) => format!(
511            "<{codec} as day_persistence::ValueCodec<{}>>::to_sqlite_value(&self.{})",
512            f.ty, f.name
513        ),
514        None => format!(
515            "day_persistence::ColumnValue::to_sqlite_value(&self.{})",
516            f.name
517        ),
518    }
519}
520
521/// A stored NULL decodes as the field's `Default`, which is what makes an added column's old
522/// rows readable before their backfill, matching the model's deleted-row semantics.
523fn decode_expr(f: &FieldDef, i: usize) -> String {
524    let read = format!("day_persistence::Row::get(row, {i}usize)");
525    match codec(f) {
526        Some(codec) => format!(
527            "match {read} {{\n\
528             \x20               day_persistence::Value::Null => ::core::default::Default::default(),\n\
529             \x20               v => <{codec} as day_persistence::ValueCodec<{}>>::from_sqlite_value(v)?,\n\
530             \x20           }}",
531            f.ty
532        ),
533        None => format!(
534            "match {read} {{\n\
535             \x20               day_persistence::Value::Null => ::core::default::Default::default(),\n\
536             \x20               v => <{} as day_persistence::ColumnValue>::from_sqlite_value(v)?,\n\
537             \x20           }}",
538            f.ty
539        ),
540    }
541}
542
543fn codec(f: &FieldDef) -> Option<String> {
544    if let Some(with) = &f.with {
545        Some(with.clone())
546    } else if f.json {
547        Some("day_persistence::Json".into())
548    } else {
549        None
550    }
551}
552
553fn snake_case(name: &str) -> String {
554    let mut out = String::with_capacity(name.len() + 4);
555    for (i, ch) in name.chars().enumerate() {
556        if ch.is_uppercase() {
557            if i > 0 {
558                out.push('_');
559            }
560            out.extend(ch.to_lowercase());
561        } else {
562            out.push(ch);
563        }
564    }
565    out
566}
567
568// ---------------------------------------------------------------------------
569// Parsing
570// ---------------------------------------------------------------------------
571
572/// The whole derive input: struct-level `#[model(…)]` options, the name, and the fields.
573fn parse_struct(input: TokenStream) -> Result<StructDef, String> {
574    let tokens: Vec<TokenTree> = input.into_iter().collect();
575
576    let mut table = None;
577    let mut external = None;
578    let mut composites = Vec::new();
579    let mut fts = Vec::new();
580    let mut fts_tokenize = None;
581    let mut spatial = None;
582    let mut i = 0;
583    while i < tokens.len() {
584        match &tokens[i] {
585            TokenTree::Ident(id) if id.to_string() == "struct" => break,
586            TokenTree::Punct(p) if p.as_char() == '#' => {
587                if let Some(TokenTree::Group(g)) = tokens.get(i + 1) {
588                    if let Some(items) = attr_items(g, "model") {
589                        parse_struct_options(
590                            items,
591                            &mut table,
592                            &mut external,
593                            &mut composites,
594                            &mut fts,
595                            &mut fts_tokenize,
596                            &mut spatial,
597                        )?;
598                    }
599                    i += 2;
600                    continue;
601                }
602                return Err("malformed attribute on the struct".into());
603            }
604            _ => i += 1,
605        }
606    }
607    if i >= tokens.len() {
608        return Err("the derive expects a struct".into());
609    }
610    let name = match tokens.get(i + 1) {
611        Some(TokenTree::Ident(id)) => id.to_string(),
612        _ => return Err("the derive expects a named struct".into()),
613    };
614    let body = match tokens.get(i + 2) {
615        Some(TokenTree::Group(g)) if g.delimiter() == Delimiter::Brace => g.stream(),
616        Some(TokenTree::Punct(p)) if p.as_char() == '<' => {
617            return Err("the derive does not support generic structs yet".into());
618        }
619        _ => return Err("the derive expects a struct with named fields".into()),
620    };
621
622    Ok(StructDef {
623        name,
624        table,
625        external,
626        composites,
627        fts,
628        fts_tokenize,
629        spatial,
630        fields: parse_fields(body)?,
631    })
632}
633
634/// If the bracket group is `name(…)`, return the paren group's items split on top-level commas.
635fn attr_items(bracket: &proc_macro::Group, name: &str) -> Option<Vec<Vec<TokenTree>>> {
636    let inner: Vec<TokenTree> = bracket.stream().into_iter().collect();
637    match (inner.first(), inner.get(1)) {
638        (Some(TokenTree::Ident(id)), Some(TokenTree::Group(g)))
639            if id.to_string() == name && g.delimiter() == Delimiter::Parenthesis =>
640        {
641            let mut items = vec![Vec::new()];
642            for tt in g.stream() {
643                match &tt {
644                    TokenTree::Punct(p) if p.as_char() == ',' => items.push(Vec::new()),
645                    _ => items.last_mut().expect("never empty").push(tt),
646                }
647            }
648            items.retain(|item| !item.is_empty());
649            Some(items)
650        }
651        _ => None,
652    }
653}
654
655fn parse_struct_options(
656    items: Vec<Vec<TokenTree>>,
657    table: &mut Option<String>,
658    external: &mut Option<String>,
659    composites: &mut Vec<Vec<String>>,
660    fts: &mut Vec<String>,
661    fts_tokenize: &mut Option<String>,
662    spatial: &mut Option<(String, String)>,
663) -> Result<(), String> {
664    for item in items {
665        match item.as_slice() {
666            [TokenTree::Ident(id), TokenTree::Group(g)]
667                if id.to_string() == "fts" && g.delimiter() == Delimiter::Parenthesis =>
668            {
669                // Column literals, plus an optional `tokenize = "…"` naming the FTS5
670                // tokenizer (e.g. "unicode61 remove_diacritics 2").
671                let mut fts_items = vec![Vec::new()];
672                for tt in g.stream() {
673                    match &tt {
674                        TokenTree::Punct(p) if p.as_char() == ',' => fts_items.push(Vec::new()),
675                        _ => fts_items.last_mut().expect("never empty").push(tt.clone()),
676                    }
677                }
678                for item in fts_items.into_iter().filter(|i| !i.is_empty()) {
679                    match item.as_slice() {
680                        [TokenTree::Literal(lit)] => fts.push(string_literal(lit)?),
681                        [
682                            TokenTree::Ident(k),
683                            TokenTree::Punct(eq),
684                            TokenTree::Literal(lit),
685                        ] if k.to_string() == "tokenize" && eq.as_char() == '=' => {
686                            *fts_tokenize = Some(string_literal(lit)?);
687                        }
688                        other => {
689                            return Err(format!(
690                                "fts(…) expects column string literals and an optional \
691                                 tokenize = \"…\", found `{}`",
692                                tokens_text(other)
693                            ));
694                        }
695                    }
696                }
697            }
698            [TokenTree::Ident(id), TokenTree::Group(g)]
699                if id.to_string() == "spatial" && g.delimiter() == Delimiter::Parenthesis =>
700            {
701                let mut lat = None;
702                let mut lon = None;
703                let inner: Vec<TokenTree> = g.stream().into_iter().collect();
704                let mut j = 0;
705                while j + 2 < inner.len() + 1 {
706                    match (&inner.get(j), &inner.get(j + 1), &inner.get(j + 2)) {
707                        (
708                            Some(TokenTree::Ident(k)),
709                            Some(TokenTree::Punct(eq)),
710                            Some(TokenTree::Literal(lit)),
711                        ) if eq.as_char() == '=' => {
712                            match k.to_string().as_str() {
713                                "lat" => lat = Some(string_literal(lit)?),
714                                "lon" => lon = Some(string_literal(lit)?),
715                                other => {
716                                    return Err(format!(
717                                        "spatial(…) takes lat = \"…\" and lon = \"…\", found `{other}`"
718                                    ));
719                                }
720                            }
721                            j += 3;
722                            if matches!(inner.get(j), Some(TokenTree::Punct(p)) if p.as_char() == ',')
723                            {
724                                j += 1;
725                            }
726                        }
727                        _ => return Err("spatial(…) takes lat = \"…\" and lon = \"…\"".into()),
728                    }
729                }
730                match (lat, lon) {
731                    (Some(lat), Some(lon)) => *spatial = Some((lat, lon)),
732                    _ => return Err("spatial(…) needs BOTH lat = \"…\" and lon = \"…\"".into()),
733                }
734            }
735            [
736                TokenTree::Ident(id),
737                TokenTree::Punct(eq),
738                TokenTree::Literal(lit),
739            ] if id.to_string() == "table" && eq.as_char() == '=' => {
740                *table = Some(string_literal(lit)?);
741            }
742            [
743                TokenTree::Ident(id),
744                TokenTree::Punct(eq),
745                TokenTree::Literal(lit),
746            ] if id.to_string() == "external" && eq.as_char() == '=' => {
747                let alias = string_literal(lit)?;
748                if alias.is_empty() || !alias.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
749                {
750                    return Err(format!(
751                        "external = {alias:?} must be a plain SQL schema name (letters, digits, `_`)"
752                    ));
753                }
754                *external = Some(alias);
755            }
756            [TokenTree::Ident(id), TokenTree::Group(g)]
757                if id.to_string() == "index" && g.delimiter() == Delimiter::Parenthesis =>
758            {
759                let mut cols = Vec::new();
760                for tt in g.stream() {
761                    match &tt {
762                        TokenTree::Literal(lit) => cols.push(string_literal(lit)?),
763                        TokenTree::Punct(p) if p.as_char() == ',' => {}
764                        other => {
765                            return Err(format!(
766                                "index(…) expects string literals, found `{other}`"
767                            ));
768                        }
769                    }
770                }
771                composites.push(cols);
772            }
773            other => {
774                return Err(format!(
775                    "unknown #[model] option on the struct: `{}` (supported: table = \"…\", external = \"alias\", index(\"a\", \"b\"), fts(\"a\", \"b\"), spatial(lat = \"…\", lon = \"…\"))",
776                    tokens_text(other)
777                ));
778            }
779        }
780    }
781    Ok(())
782}
783
784fn parse_field_options(items: Vec<Vec<TokenTree>>, f: &mut FieldDef) -> Result<(), String> {
785    for item in items {
786        match item.as_slice() {
787            [TokenTree::Ident(id)] => match id.to_string().as_str() {
788                "id" => f.key = true,
789                "unique" => f.unique = true,
790                "index" => f.indexed = true,
791                "transient" => f.transient = true,
792                "json" => f.json = true,
793                other => {
794                    return Err(format!(
795                        "unknown #[model] option on field `{}`: `{other}` (supported: id, unique, index, transient, json, column = \"…\", with = Codec)",
796                        f.name
797                    ));
798                }
799            },
800            [
801                TokenTree::Ident(id),
802                TokenTree::Punct(eq),
803                TokenTree::Literal(lit),
804            ] if id.to_string() == "column" && eq.as_char() == '=' => {
805                f.column = Some(string_literal(lit)?);
806            }
807            [TokenTree::Ident(id), TokenTree::Punct(eq), rest @ ..]
808                if id.to_string() == "with" && eq.as_char() == '=' && !rest.is_empty() =>
809            {
810                f.with = Some(tokens_text(rest));
811            }
812            [TokenTree::Ident(id), TokenTree::Group(g)]
813                if id.to_string() == "relation" && g.delimiter() == Delimiter::Parenthesis =>
814            {
815                f.relation = Some(parse_relation(g, &f.name)?);
816            }
817            [TokenTree::Ident(id), TokenTree::Group(g)]
818                if id.to_string() == "link" && g.delimiter() == Delimiter::Parenthesis =>
819            {
820                f.link = Some(parse_link(g, &f.name)?);
821            }
822            other => {
823                return Err(format!(
824                    "unknown #[model] option on field `{}`: `{}`",
825                    f.name,
826                    tokens_text(other)
827                ));
828            }
829        }
830    }
831    Ok(())
832}
833
834/// `relation(target = Type, inverse = "field", delete = "…", ordered = "field", join = "table")`.
835fn parse_relation(g: &proc_macro::Group, field: &str) -> Result<RelationAttr, String> {
836    let mut items = vec![Vec::new()];
837    for tt in g.stream() {
838        match &tt {
839            TokenTree::Punct(p) if p.as_char() == ',' => items.push(Vec::new()),
840            _ => items.last_mut().expect("never empty").push(tt),
841        }
842    }
843    items.retain(|i| !i.is_empty());
844
845    let (mut target, mut inverse, mut delete, mut ordered, mut join) =
846        (None, None, None, None, None);
847    for item in items {
848        match item.as_slice() {
849            [TokenTree::Ident(k), TokenTree::Punct(eq), rest @ ..]
850                if eq.as_char() == '=' && !rest.is_empty() =>
851            {
852                match k.to_string().as_str() {
853                    "target" => target = Some(tokens_text(rest)),
854                    "inverse" => inverse = Some(literal_str(rest, field)?),
855                    "delete" => delete = Some(literal_str(rest, field)?),
856                    "ordered" => ordered = Some(literal_str(rest, field)?),
857                    "join" => join = Some(literal_str(rest, field)?),
858                    other => {
859                        return Err(format!(
860                            "relation(…) on `{field}`: unknown option `{other}` (supported: \
861                             target = Type, inverse = \"field\", delete = \"…\", \
862                             ordered = \"field\", join = \"table\")"
863                        ));
864                    }
865                }
866            }
867            // Bare `ordered`, the join form: the position lives on the membership row, so
868            // there is no child field to name (one child can sit at different positions
869            // under different parents).
870            [TokenTree::Ident(k)] if k.to_string() == "ordered" => {
871                ordered = Some("position".into());
872            }
873            other => {
874                return Err(format!(
875                    "relation(…) on `{field}`: expected `name = …`, found `{}`",
876                    tokens_text(other)
877                ));
878            }
879        }
880    }
881    let Some(target) = target else {
882        return Err(format!("relation(…) on `{field}` needs target = Type"));
883    };
884    let delete = delete.unwrap_or_else(|| "nullify".into());
885    if !["nullify", "cascade", "deny"].contains(&delete.as_str()) {
886        return Err(format!(
887            "relation(…) on `{field}`: delete = {delete:?} — nullify, cascade, or deny"
888        ));
889    }
890    if inverse.is_none() && join.is_none() {
891        return Err(format!(
892            "relation(…) on `{field}` needs inverse = \"field\" (the target's One<…> field) \
893             — or join = \"table\" for a many-to-many"
894        ));
895    }
896    Ok(RelationAttr {
897        target,
898        inverse,
899        delete,
900        ordered,
901        join,
902    })
903}
904
905/// `link(target = Type, local = "column", remote = "column")` is a relation matched by value:
906/// rows of `Type` whose `remote` column equals this row's `local` column. No foreign key and
907/// no wiring, which is what lets it cross into an `external` table SQLite cannot constrain.
908fn parse_link(g: &proc_macro::Group, field: &str) -> Result<LinkAttr, String> {
909    let mut items = vec![Vec::new()];
910    for tt in g.stream() {
911        match &tt {
912            TokenTree::Punct(p) if p.as_char() == ',' => items.push(Vec::new()),
913            _ => items.last_mut().expect("never empty").push(tt),
914        }
915    }
916    items.retain(|i| !i.is_empty());
917    let (mut target, mut local, mut remote) = (None, None, None);
918    for item in items {
919        match item.as_slice() {
920            [TokenTree::Ident(k), TokenTree::Punct(eq), rest @ ..]
921                if eq.as_char() == '=' && !rest.is_empty() =>
922            {
923                match k.to_string().as_str() {
924                    "target" => target = Some(tokens_text(rest)),
925                    "local" => local = Some(literal_str(rest, field)?),
926                    "remote" => remote = Some(literal_str(rest, field)?),
927                    other => {
928                        return Err(format!(
929                            "link(…) on `{field}`: unknown option `{other}` (supported: \
930                             target = Type, local = \"column\", remote = \"column\")"
931                        ));
932                    }
933                }
934            }
935            other => {
936                return Err(format!(
937                    "link(…) on `{field}`: expected `name = …`, found `{}`",
938                    tokens_text(other)
939                ));
940            }
941        }
942    }
943    match (target, local, remote) {
944        (Some(target), Some(local), Some(remote)) => Ok(LinkAttr {
945            target,
946            local,
947            remote,
948        }),
949        _ => Err(format!(
950            "link(…) on `{field}` needs target = Type, local = \"column\", and remote = \"column\""
951        )),
952    }
953}
954
955fn literal_str(rest: &[TokenTree], field: &str) -> Result<String, String> {
956    match rest {
957        [TokenTree::Literal(l)] => string_literal(l),
958        other => Err(format!(
959            "relation(…) on `{field}`: expected a string literal, found `{}`",
960            tokens_text(other)
961        )),
962    }
963}
964
965fn string_literal(lit: &proc_macro::Literal) -> Result<String, String> {
966    let s = lit.to_string();
967    if s.len() >= 2 && s.starts_with('"') && s.ends_with('"') {
968        Ok(s[1..s.len() - 1].to_string())
969    } else {
970        Err(format!("expected a string literal, found `{s}`"))
971    }
972}
973
974fn tokens_text(tokens: &[TokenTree]) -> String {
975    tokens.iter().cloned().collect::<TokenStream>().to_string()
976}
977
978/// Split the brace body on top-level commas and read `#[obs|model(...)] vis name : Type` out of
979/// each. "Top-level" means outside `<…>` too, so a `HashMap<u64, usize>` field stays one chunk;
980/// brackets and parens are already single `Group` tokens, but angles arrive as bare puncts.
981fn parse_fields(body: TokenStream) -> Result<Vec<FieldDef>, String> {
982    let mut fields = Vec::new();
983    let mut chunk: Vec<TokenTree> = Vec::new();
984    let mut angle_depth = 0i32;
985    let mut prev_dash = false;
986
987    for tt in body {
988        match &tt {
989            TokenTree::Punct(p) if p.as_char() == '<' => {
990                angle_depth += 1;
991                chunk.push(tt);
992            }
993            // `->` in a fn-pointer type must not close an angle bracket.
994            TokenTree::Punct(p) if p.as_char() == '>' && !prev_dash => {
995                angle_depth = (angle_depth - 1).max(0);
996                chunk.push(tt);
997            }
998            TokenTree::Punct(p) if p.as_char() == ',' && angle_depth == 0 => {
999                if !chunk.is_empty() {
1000                    fields.push(parse_one(&chunk)?);
1001                    chunk.clear();
1002                }
1003            }
1004            _ => chunk.push(tt),
1005        }
1006        prev_dash = matches!(
1007            chunk.last(),
1008            Some(TokenTree::Punct(p)) if p.as_char() == '-'
1009        );
1010    }
1011    if !chunk.is_empty() {
1012        fields.push(parse_one(&chunk)?);
1013    }
1014    Ok(fields)
1015}
1016
1017fn parse_one(chunk: &[TokenTree]) -> Result<FieldDef, String> {
1018    let mut i = 0;
1019    let mut f = FieldDef::default();
1020    let mut deferred: Vec<Vec<Vec<TokenTree>>> = Vec::new();
1021
1022    // Attributes and doc comments. `#[model(…)]` items need the field name for their errors,
1023    // so they are parsed after it is known.
1024    while i < chunk.len() {
1025        match &chunk[i] {
1026            TokenTree::Punct(p) if p.as_char() == '#' => {
1027                if let Some(TokenTree::Group(g)) = chunk.get(i + 1) {
1028                    if let Some(items) = attr_items(g, "obs") {
1029                        for item in items {
1030                            match item.as_slice() {
1031                                [TokenTree::Ident(id)] if id.to_string() == "key" => f.key = true,
1032                                [TokenTree::Ident(id)] if id.to_string() == "skip" => {
1033                                    f.skip = true;
1034                                }
1035                                other => {
1036                                    return Err(format!(
1037                                        "unknown #[obs] option: `{}` (supported: key, skip)",
1038                                        tokens_text(other)
1039                                    ));
1040                                }
1041                            }
1042                        }
1043                    } else if let Some(items) = attr_items(g, "model") {
1044                        deferred.push(items);
1045                    }
1046                    i += 2;
1047                    continue;
1048                }
1049                return Err("malformed attribute on a field".into());
1050            }
1051            _ => break,
1052        }
1053    }
1054
1055    // Visibility.
1056    if let Some(TokenTree::Ident(id)) = chunk.get(i)
1057        && id.to_string() == "pub"
1058    {
1059        i += 1;
1060        if let Some(TokenTree::Group(g)) = chunk.get(i)
1061            && g.delimiter() == Delimiter::Parenthesis
1062        {
1063            i += 1;
1064        }
1065    }
1066
1067    f.name = match chunk.get(i) {
1068        Some(TokenTree::Ident(id)) => id.to_string(),
1069        _ => return Err("expected a field name".into()),
1070    };
1071    i += 1;
1072    match chunk.get(i) {
1073        Some(TokenTree::Punct(p)) if p.as_char() == ':' => i += 1,
1074        _ => return Err(format!("expected `:` after field `{}`", f.name)),
1075    }
1076
1077    // The type is whatever is left, re-emitted verbatim, never interpreted.
1078    f.ty = tokens_text(&chunk[i..]);
1079    if f.ty.is_empty() {
1080        return Err(format!("field `{}` has no type", f.name));
1081    }
1082
1083    for items in deferred {
1084        parse_field_options(items, &mut f)?;
1085    }
1086    Ok(f)
1087}