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.clone(),
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    // Names reach SQL quoted, so any string is a table or column name here; the two things
209    // SQLite cannot take are an empty name and a NUL (which ends the statement text early).
210    check_name("table", &bare_table)?;
211    for f in &persisted {
212        check_name(&format!("column of field `{}`", f.name), f.column_name())?;
213    }
214    for (i, f) in persisted.iter().enumerate() {
215        let twin = persisted[..i]
216            .iter()
217            .find(|p| p.column_name().eq_ignore_ascii_case(f.column_name()));
218        if let Some(twin) = twin {
219            return Err(format!(
220                "Model: fields `{}` and `{}` of `{name}` both store in column {:?} (SQLite \
221                 compares column names without case)",
222                twin.name,
223                f.name,
224                f.column_name()
225            ));
226        }
227    }
228
229    let mut columns = String::new();
230    for f in &persisted {
231        let sql = sql_type_expr(f);
232        columns.push_str(&format!(
233            "        day_persistence::ColumnDef {{ name: {:?}, field: \"{}\", sql: {sql}, \
234             not_null: {}, unique: {}, indexed: {} }},\n",
235            f.column_name(),
236            f.name,
237            !f.nullable(),
238            f.unique,
239            f.indexed,
240        ));
241    }
242
243    // fts()/spatial() name COLUMNS; a typo would silently index nothing, so check now.
244    let column_names: Vec<&str> = persisted.iter().map(|f| f.column_name()).collect();
245    for c in &def.fts {
246        if !column_names.contains(&c.as_str()) {
247            return Err(format!(
248                "Model: fts(…) names `{c}`, which is not a persisted column of `{name}`"
249            ));
250        }
251    }
252    if let Some((lat, lon)) = &def.spatial {
253        for c in [lat, lon] {
254            if !column_names.contains(&c.as_str()) {
255                return Err(format!(
256                    "Model: spatial(…) names `{c}`, which is not a persisted column of `{name}`"
257                ));
258            }
259        }
260    }
261
262    let composites = def
263        .composites
264        .iter()
265        .map(|cols| {
266            format!(
267                "&[{}]",
268                cols.iter()
269                    .map(|c| format!("{c:?}"))
270                    .collect::<Vec<_>>()
271                    .join(", ")
272            )
273        })
274        .collect::<Vec<_>>()
275        .join(", ");
276
277    let mut to_row = String::new();
278    for f in &persisted {
279        to_row.push_str(&format!("            {},\n", encode_expr(f)));
280    }
281
282    let mut from_row = String::new();
283    for f in &def.fields {
284        if let Some(i) = persisted.iter().position(|p| p.name == f.name) {
285            from_row.push_str(&format!("            {}: {},\n", f.name, decode_expr(f, i)));
286        } else {
287            from_row.push_str(&format!(
288                "            {}: ::core::default::Default::default(),\n",
289                f.name
290            ));
291        }
292    }
293
294    // Typed column refs: `Trip::name()` in a predicate, beside `trip.name()` the binding.
295    // Inherent fns without a receiver never collide with the Fields trait's methods (which
296    // take self): method-call syntax finds the trait, path syntax finds these.
297    let mut cols = String::new();
298    for f in &persisted {
299        let encode = match codec(f) {
300            Some(codec) => format!(
301                "<{codec} as day_persistence::ValueCodec<{}>>::to_sqlite_value",
302                f.ty
303            ),
304            None => format!("day_persistence::encode_column::<{}>", f.ty),
305        };
306        cols.push_str(&format!(
307            "    pub fn {}() -> day_persistence::Col<{}> {{\n\
308             \x20       day_persistence::Col::new({:?}, \"{}\", {table:?}, {encode})\n\
309             \x20   }}\n",
310            f.name,
311            f.ty,
312            f.column_name(),
313            f.name,
314        ));
315    }
316    // The static relation reference, for predicates. The instance accessor of the same name
317    // lives on the Relations trait and takes `self`, so path syntax finds this one and
318    // method-call syntax finds that one, the rule `Trip::name()` already relies on.
319    for f in def.fields.iter().filter(|f| f.relation.is_some()) {
320        let r = f.relation.as_ref().expect("filtered");
321        cols.push_str(&format!(
322            "    pub fn {}() -> day_persistence::RelationCol<{name}, {}> {{\n\
323             \x20       day_persistence::RelationCol::new(\"{}\", {table:?}, \
324             <{} as day_persistence::Model>::TABLE)\n\
325             \x20   }}\n",
326            f.name, r.target, f.name, r.target,
327        ));
328    }
329    // A link's predicate builder is a plain RelationCol: the container resolves the
330    // (owner, field) pair to the link's join condition at compile time, so `any`/`none`/
331    // `is_empty`/`count_ge` read exactly as they do across a keyed relation.
332    for f in def.fields.iter().filter(|f| f.link.is_some()) {
333        let l = f.link.as_ref().expect("filtered");
334        cols.push_str(&format!(
335            "    pub fn {}() -> day_persistence::RelationCol<{name}, {}> {{\n\
336             \x20       day_persistence::RelationCol::new(\"{}\", {table:?}, \
337             <{} as day_persistence::Model>::TABLE)\n\
338             \x20   }}\n",
339            f.name, l.target, f.name, l.target,
340        ));
341    }
342    if !def.fts.is_empty() {
343        cols.push_str(&format!(
344            "    pub fn fts() -> day_persistence::FtsRef {{\n\
345             \x20       day_persistence::FtsRef {{ columns: <{name} as day_persistence::Model>::FTS_COLUMNS }}\n\
346             \x20   }}\n"
347        ));
348    }
349    if let Some((lat, lon)) = &def.spatial {
350        cols.push_str(&format!(
351            "    pub fn geo() -> day_persistence::GeoRef {{\n\
352             \x20       day_persistence::GeoRef {{ lat: {lat:?}, lon: {lon:?} }}\n\
353             \x20   }}\n"
354        ));
355    }
356    let col_impl = format!("#[allow(dead_code)]\nimpl {name} {{\n{cols}}}\n");
357
358    // Relations: the const table, the wiring, and the RelationRef accessor trait.
359    let rels: Vec<(&FieldDef, &RelationAttr)> = def
360        .fields
361        .iter()
362        .filter_map(|f| f.relation.as_ref().map(|r| (f, r)))
363        .collect();
364    let delete_expr = |d: &str| match d {
365        "cascade" => "day_persistence::DeleteRule::Cascade",
366        "deny" => "day_persistence::DeleteRule::Deny",
367        _ => "day_persistence::DeleteRule::Nullify",
368    };
369    let opt_str = |o: &Option<String>| match o {
370        Some(s) => format!("Some({s:?})"),
371        None => "None".into(),
372    };
373    let relations_const = if rels.is_empty() {
374        String::new()
375    } else {
376        format!(
377            "    const RELATIONS: &'static [day_persistence::RelationDef] = &[\n{}    ];\n",
378            rels.iter()
379                .map(|(f, r)| format!(
380                    "        day_persistence::RelationDef {{ field: \"{}\", target_table: \
381                     <{} as day_persistence::Model>::TABLE, inverse: {:?}, delete: {}, \
382                     ordered: {}, join: {} }},\n",
383                    f.name,
384                    r.target,
385                    r.inverse.as_deref().unwrap_or(""),
386                    delete_expr(&r.delete),
387                    opt_str(&r.ordered),
388                    opt_str(&r.join),
389                ))
390                .collect::<String>()
391        )
392    };
393    let wire_fn = if rels.is_empty() {
394        String::new()
395    } else {
396        format!(
397            "    fn wire(reg: &mut day_persistence::Registrar<'_>) {{\n{}    }}\n",
398            rels.iter()
399                .map(|(f, r)| match (&r.join, &r.inverse) {
400                    (Some(join), _) => format!(
401                        "        day_persistence::wire_join::<Self, {}>(reg, \"{}\", \
402                         {join:?}, {}, {});\n",
403                        r.target,
404                        f.name,
405                        opt_str(&r.ordered),
406                        delete_expr(&r.delete),
407                    ),
408                    (None, Some(inverse)) => format!(
409                        "        day_persistence::wire_to_many::<Self, {}>(reg, \"{}\", \
410                         {inverse:?}, {}, {});\n",
411                        r.target,
412                        f.name,
413                        delete_expr(&r.delete),
414                        opt_str(&r.ordered),
415                    ),
416                    (None, None) => String::new(), // refused at parse time
417                })
418                .collect::<String>()
419        )
420    };
421    let rel_trait = if rels.is_empty() {
422        String::new()
423    } else {
424        format!(
425            "#[allow(non_camel_case_types)]\n\
426             pub trait {name}Relations: day_model::Source<{name}> + Sized {{\n{}}}\n\
427             impl<S: day_model::Source<{name}>> {name}Relations for S {{}}\n",
428            rels.iter()
429                .map(|(f, r)| format!(
430                    "    fn {}(self) -> day_persistence::RelationRef<Self, {name}, {}> {{\n\
431                     \x20       day_persistence::RelationRef::new(day_model::project(\
432                     self, \"{}\", |s| &s.{}, |s| &mut s.{}))\n\
433                     \x20   }}\n",
434                    f.name, r.target, f.name, f.name, f.name
435                ))
436                .collect::<String>()
437        )
438    };
439
440    let fts_const = if def.fts.is_empty() {
441        String::new()
442    } else {
443        let tokenize = match &def.fts_tokenize {
444            Some(t) => format!("    const FTS_TOKENIZE: Option<&'static str> = Some({t:?});\n"),
445            None => String::new(),
446        };
447        format!(
448            "    const FTS_COLUMNS: &'static [&'static str] = &[{}];\n{tokenize}",
449            def.fts
450                .iter()
451                .map(|c| format!("{c:?}"))
452                .collect::<Vec<_>>()
453                .join(", ")
454        )
455    };
456    let links: Vec<(&FieldDef, &LinkAttr)> = def
457        .fields
458        .iter()
459        .filter_map(|f| f.link.as_ref().map(|l| (f, l)))
460        .collect();
461    let links_const = if links.is_empty() {
462        String::new()
463    } else {
464        format!(
465            "    const LINKS: &'static [day_persistence::LinkDef] = &[\n{}    ];\n",
466            links
467                .iter()
468                .map(|(f, l)| format!(
469                    "        day_persistence::LinkDef {{ field: \"{}\", local: {:?}, \
470                     target_table: <{} as day_persistence::Model>::TABLE, remote: {:?} }},\n",
471                    f.name, l.local, l.target, l.remote
472                ))
473                .collect::<String>()
474        )
475    };
476    let external_const = match &def.external {
477        Some(alias) => format!(
478            "    const EXTERNAL: bool = true;\n    const SCHEMA: Option<&'static str> = Some({alias:?});\n"
479        ),
480        None => String::new(),
481    };
482    let spatial_const = match &def.spatial {
483        None => String::new(),
484        Some((lat, lon)) => format!(
485            "    const SPATIAL: Option<day_persistence::SpatialCols> = \
486             Some(day_persistence::SpatialCols {{ lat: {lat:?}, lon: {lon:?} }});\n"
487        ),
488    };
489
490    let key_sql = sql_type_expr(key);
491    Ok(col_impl
492        + &rel_trait
493        + &format!(
494            "impl day_persistence::Model for {name} {{\n\
495         \x20   const TABLE: &'static str = {table:?};\n\
496         \x20   const KEY: &'static str = {key_col:?};\n\
497         \x20   const KEY_SQL: day_persistence::SqlType = {key_sql};\n\
498         \x20   const COLUMNS: &'static [day_persistence::ColumnDef] = &[\n{columns}    ];\n\
499         \x20   const COMPOSITE_INDEXES: &'static [&'static [&'static str]] = &[{composites}];\n\
500         {fts_const}{spatial_const}{relations_const}{links_const}{external_const}\
501         \x20   fn to_row(&self) -> Vec<day_persistence::Value> {{\n\
502         \x20       vec![\n{to_row}        ]\n\
503         \x20   }}\n\
504         \x20   fn from_row(row: &dyn day_persistence::Row) -> \
505         Result<Self, day_persistence::DbError> {{\n\
506         \x20       Ok(Self {{\n{from_row}        }})\n\
507         \x20   }}\n\
508         \x20   fn default_row() -> Vec<day_persistence::Value> {{\n\
509         \x20       day_persistence::Model::to_row(&<Self as ::core::default::Default>::default())\n\
510         \x20   }}\n\
511         {wire_fn}\
512         }}\n",
513            key_col = key.column_name(),
514        ))
515}
516
517fn sql_type_expr(f: &FieldDef) -> String {
518    match codec(f) {
519        Some(codec) => format!(
520            "<{codec} as day_persistence::ValueCodec<{}>>::SQL_TYPE",
521            f.ty
522        ),
523        None => format!("<{} as day_persistence::ColumnValue>::SQL_TYPE", f.ty),
524    }
525}
526
527fn encode_expr(f: &FieldDef) -> String {
528    match codec(f) {
529        Some(codec) => format!(
530            "<{codec} as day_persistence::ValueCodec<{}>>::to_sqlite_value(&self.{})",
531            f.ty, f.name
532        ),
533        None => format!(
534            "day_persistence::ColumnValue::to_sqlite_value(&self.{})",
535            f.name
536        ),
537    }
538}
539
540/// A stored NULL decodes as the field's `Default`, which is what makes an added column's old
541/// rows readable before their backfill, matching the model's deleted-row semantics.
542fn decode_expr(f: &FieldDef, i: usize) -> String {
543    let read = format!("day_persistence::Row::get(row, {i}usize)");
544    match codec(f) {
545        Some(codec) => format!(
546            "match {read} {{\n\
547             \x20               day_persistence::Value::Null => ::core::default::Default::default(),\n\
548             \x20               v => <{codec} as day_persistence::ValueCodec<{}>>::from_sqlite_value(v)?,\n\
549             \x20           }}",
550            f.ty
551        ),
552        None => format!(
553            "match {read} {{\n\
554             \x20               day_persistence::Value::Null => ::core::default::Default::default(),\n\
555             \x20               v => <{} as day_persistence::ColumnValue>::from_sqlite_value(v)?,\n\
556             \x20           }}",
557            f.ty
558        ),
559    }
560}
561
562fn codec(f: &FieldDef) -> Option<String> {
563    if let Some(with) = &f.with {
564        Some(with.clone())
565    } else if f.json {
566        Some("day_persistence::Json".into())
567    } else {
568        None
569    }
570}
571
572fn snake_case(name: &str) -> String {
573    let mut out = String::with_capacity(name.len() + 4);
574    for (i, ch) in name.chars().enumerate() {
575        if ch.is_uppercase() {
576            if i > 0 {
577                out.push('_');
578            }
579            out.extend(ch.to_lowercase());
580        } else {
581            out.push(ch);
582        }
583    }
584    out
585}
586
587// ---------------------------------------------------------------------------
588// Parsing
589// ---------------------------------------------------------------------------
590
591/// The whole derive input: struct-level `#[model(…)]` options, the name, and the fields.
592fn parse_struct(input: TokenStream) -> Result<StructDef, String> {
593    let tokens: Vec<TokenTree> = input.into_iter().collect();
594
595    let mut table = None;
596    let mut external = None;
597    let mut composites = Vec::new();
598    let mut fts = Vec::new();
599    let mut fts_tokenize = None;
600    let mut spatial = None;
601    let mut i = 0;
602    while i < tokens.len() {
603        match &tokens[i] {
604            TokenTree::Ident(id) if id.to_string() == "struct" => break,
605            TokenTree::Punct(p) if p.as_char() == '#' => {
606                if let Some(TokenTree::Group(g)) = tokens.get(i + 1) {
607                    if let Some(items) = attr_items(g, "model") {
608                        parse_struct_options(
609                            items,
610                            &mut table,
611                            &mut external,
612                            &mut composites,
613                            &mut fts,
614                            &mut fts_tokenize,
615                            &mut spatial,
616                        )?;
617                    }
618                    i += 2;
619                    continue;
620                }
621                return Err("malformed attribute on the struct".into());
622            }
623            _ => i += 1,
624        }
625    }
626    if i >= tokens.len() {
627        return Err("the derive expects a struct".into());
628    }
629    let name = match tokens.get(i + 1) {
630        Some(TokenTree::Ident(id)) => id.to_string(),
631        _ => return Err("the derive expects a named struct".into()),
632    };
633    let body = match tokens.get(i + 2) {
634        Some(TokenTree::Group(g)) if g.delimiter() == Delimiter::Brace => g.stream(),
635        Some(TokenTree::Punct(p)) if p.as_char() == '<' => {
636            return Err("the derive does not support generic structs yet".into());
637        }
638        _ => return Err("the derive expects a struct with named fields".into()),
639    };
640
641    Ok(StructDef {
642        name,
643        table,
644        external,
645        composites,
646        fts,
647        fts_tokenize,
648        spatial,
649        fields: parse_fields(body)?,
650    })
651}
652
653/// If the bracket group is `name(…)`, return the paren group's items split on top-level commas.
654fn attr_items(bracket: &proc_macro::Group, name: &str) -> Option<Vec<Vec<TokenTree>>> {
655    let inner: Vec<TokenTree> = bracket.stream().into_iter().collect();
656    match (inner.first(), inner.get(1)) {
657        (Some(TokenTree::Ident(id)), Some(TokenTree::Group(g)))
658            if id.to_string() == name && g.delimiter() == Delimiter::Parenthesis =>
659        {
660            let mut items = vec![Vec::new()];
661            for tt in g.stream() {
662                match &tt {
663                    TokenTree::Punct(p) if p.as_char() == ',' => items.push(Vec::new()),
664                    _ => items.last_mut().expect("never empty").push(tt),
665                }
666            }
667            items.retain(|item| !item.is_empty());
668            Some(items)
669        }
670        _ => None,
671    }
672}
673
674fn parse_struct_options(
675    items: Vec<Vec<TokenTree>>,
676    table: &mut Option<String>,
677    external: &mut Option<String>,
678    composites: &mut Vec<Vec<String>>,
679    fts: &mut Vec<String>,
680    fts_tokenize: &mut Option<String>,
681    spatial: &mut Option<(String, String)>,
682) -> Result<(), String> {
683    for item in items {
684        match item.as_slice() {
685            [TokenTree::Ident(id), TokenTree::Group(g)]
686                if id.to_string() == "fts" && g.delimiter() == Delimiter::Parenthesis =>
687            {
688                // Column literals, plus an optional `tokenize = "…"` naming the FTS5
689                // tokenizer (e.g. "unicode61 remove_diacritics 2").
690                let mut fts_items = vec![Vec::new()];
691                for tt in g.stream() {
692                    match &tt {
693                        TokenTree::Punct(p) if p.as_char() == ',' => fts_items.push(Vec::new()),
694                        _ => fts_items.last_mut().expect("never empty").push(tt.clone()),
695                    }
696                }
697                for item in fts_items.into_iter().filter(|i| !i.is_empty()) {
698                    match item.as_slice() {
699                        [TokenTree::Literal(lit)] => fts.push(string_literal(lit)?),
700                        [
701                            TokenTree::Ident(k),
702                            TokenTree::Punct(eq),
703                            TokenTree::Literal(lit),
704                        ] if k.to_string() == "tokenize" && eq.as_char() == '=' => {
705                            *fts_tokenize = Some(string_literal(lit)?);
706                        }
707                        other => {
708                            return Err(format!(
709                                "fts(…) expects column string literals and an optional \
710                                 tokenize = \"…\", found `{}`",
711                                tokens_text(other)
712                            ));
713                        }
714                    }
715                }
716            }
717            [TokenTree::Ident(id), TokenTree::Group(g)]
718                if id.to_string() == "spatial" && g.delimiter() == Delimiter::Parenthesis =>
719            {
720                let mut lat = None;
721                let mut lon = None;
722                let inner: Vec<TokenTree> = g.stream().into_iter().collect();
723                let mut j = 0;
724                while j + 2 < inner.len() + 1 {
725                    match (&inner.get(j), &inner.get(j + 1), &inner.get(j + 2)) {
726                        (
727                            Some(TokenTree::Ident(k)),
728                            Some(TokenTree::Punct(eq)),
729                            Some(TokenTree::Literal(lit)),
730                        ) if eq.as_char() == '=' => {
731                            match k.to_string().as_str() {
732                                "lat" => lat = Some(string_literal(lit)?),
733                                "lon" => lon = Some(string_literal(lit)?),
734                                other => {
735                                    return Err(format!(
736                                        "spatial(…) takes lat = \"…\" and lon = \"…\", found `{other}`"
737                                    ));
738                                }
739                            }
740                            j += 3;
741                            if matches!(inner.get(j), Some(TokenTree::Punct(p)) if p.as_char() == ',')
742                            {
743                                j += 1;
744                            }
745                        }
746                        _ => return Err("spatial(…) takes lat = \"…\" and lon = \"…\"".into()),
747                    }
748                }
749                match (lat, lon) {
750                    (Some(lat), Some(lon)) => *spatial = Some((lat, lon)),
751                    _ => return Err("spatial(…) needs BOTH lat = \"…\" and lon = \"…\"".into()),
752                }
753            }
754            [
755                TokenTree::Ident(id),
756                TokenTree::Punct(eq),
757                TokenTree::Literal(lit),
758            ] if id.to_string() == "table" && eq.as_char() == '=' => {
759                *table = Some(string_literal(lit)?);
760            }
761            [
762                TokenTree::Ident(id),
763                TokenTree::Punct(eq),
764                TokenTree::Literal(lit),
765            ] if id.to_string() == "external" && eq.as_char() == '=' => {
766                let alias = string_literal(lit)?;
767                if alias.is_empty() || !alias.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
768                {
769                    return Err(format!(
770                        "external = {alias:?} must be a plain SQL schema name (letters, digits, `_`)"
771                    ));
772                }
773                *external = Some(alias);
774            }
775            [TokenTree::Ident(id), TokenTree::Group(g)]
776                if id.to_string() == "index" && g.delimiter() == Delimiter::Parenthesis =>
777            {
778                let mut cols = Vec::new();
779                for tt in g.stream() {
780                    match &tt {
781                        TokenTree::Literal(lit) => cols.push(string_literal(lit)?),
782                        TokenTree::Punct(p) if p.as_char() == ',' => {}
783                        other => {
784                            return Err(format!(
785                                "index(…) expects string literals, found `{other}`"
786                            ));
787                        }
788                    }
789                }
790                composites.push(cols);
791            }
792            other => {
793                return Err(format!(
794                    "unknown #[model] option on the struct: `{}` (supported: table = \"…\", external = \"alias\", index(\"a\", \"b\"), fts(\"a\", \"b\"), spatial(lat = \"…\", lon = \"…\"))",
795                    tokens_text(other)
796                ));
797            }
798        }
799    }
800    Ok(())
801}
802
803fn parse_field_options(items: Vec<Vec<TokenTree>>, f: &mut FieldDef) -> Result<(), String> {
804    for item in items {
805        match item.as_slice() {
806            [TokenTree::Ident(id)] => match id.to_string().as_str() {
807                "id" => f.key = true,
808                "unique" => f.unique = true,
809                "index" => f.indexed = true,
810                "transient" => f.transient = true,
811                "json" => f.json = true,
812                other => {
813                    return Err(format!(
814                        "unknown #[model] option on field `{}`: `{other}` (supported: id, unique, index, transient, json, column = \"…\", with = Codec)",
815                        f.name
816                    ));
817                }
818            },
819            [
820                TokenTree::Ident(id),
821                TokenTree::Punct(eq),
822                TokenTree::Literal(lit),
823            ] if id.to_string() == "column" && eq.as_char() == '=' => {
824                f.column = Some(string_literal(lit)?);
825            }
826            [TokenTree::Ident(id), TokenTree::Punct(eq), rest @ ..]
827                if id.to_string() == "with" && eq.as_char() == '=' && !rest.is_empty() =>
828            {
829                f.with = Some(tokens_text(rest));
830            }
831            [TokenTree::Ident(id), TokenTree::Group(g)]
832                if id.to_string() == "relation" && g.delimiter() == Delimiter::Parenthesis =>
833            {
834                f.relation = Some(parse_relation(g, &f.name)?);
835            }
836            [TokenTree::Ident(id), TokenTree::Group(g)]
837                if id.to_string() == "link" && g.delimiter() == Delimiter::Parenthesis =>
838            {
839                f.link = Some(parse_link(g, &f.name)?);
840            }
841            other => {
842                return Err(format!(
843                    "unknown #[model] option on field `{}`: `{}`",
844                    f.name,
845                    tokens_text(other)
846                ));
847            }
848        }
849    }
850    Ok(())
851}
852
853/// `relation(target = Type, inverse = "field", delete = "…", ordered = "field", join = "table")`.
854fn parse_relation(g: &proc_macro::Group, field: &str) -> Result<RelationAttr, String> {
855    let mut items = vec![Vec::new()];
856    for tt in g.stream() {
857        match &tt {
858            TokenTree::Punct(p) if p.as_char() == ',' => items.push(Vec::new()),
859            _ => items.last_mut().expect("never empty").push(tt),
860        }
861    }
862    items.retain(|i| !i.is_empty());
863
864    let (mut target, mut inverse, mut delete, mut ordered, mut join) =
865        (None, None, None, None, None);
866    for item in items {
867        match item.as_slice() {
868            [TokenTree::Ident(k), TokenTree::Punct(eq), rest @ ..]
869                if eq.as_char() == '=' && !rest.is_empty() =>
870            {
871                match k.to_string().as_str() {
872                    "target" => target = Some(tokens_text(rest)),
873                    "inverse" => inverse = Some(literal_str(rest, field)?),
874                    "delete" => delete = Some(literal_str(rest, field)?),
875                    "ordered" => ordered = Some(literal_str(rest, field)?),
876                    "join" => join = Some(literal_str(rest, field)?),
877                    other => {
878                        return Err(format!(
879                            "relation(…) on `{field}`: unknown option `{other}` (supported: \
880                             target = Type, inverse = \"field\", delete = \"…\", \
881                             ordered = \"field\", join = \"table\")"
882                        ));
883                    }
884                }
885            }
886            // Bare `ordered`, the join form: the position lives on the membership row, so
887            // there is no child field to name (one child can sit at different positions
888            // under different parents).
889            [TokenTree::Ident(k)] if k.to_string() == "ordered" => {
890                ordered = Some("position".into());
891            }
892            other => {
893                return Err(format!(
894                    "relation(…) on `{field}`: expected `name = …`, found `{}`",
895                    tokens_text(other)
896                ));
897            }
898        }
899    }
900    let Some(target) = target else {
901        return Err(format!("relation(…) on `{field}` needs target = Type"));
902    };
903    let delete = delete.unwrap_or_else(|| "nullify".into());
904    if !["nullify", "cascade", "deny"].contains(&delete.as_str()) {
905        return Err(format!(
906            "relation(…) on `{field}`: delete = {delete:?} — nullify, cascade, or deny"
907        ));
908    }
909    if inverse.is_none() && join.is_none() {
910        return Err(format!(
911            "relation(…) on `{field}` needs inverse = \"field\" (the target's One<…> field) \
912             — or join = \"table\" for a many-to-many"
913        ));
914    }
915    Ok(RelationAttr {
916        target,
917        inverse,
918        delete,
919        ordered,
920        join,
921    })
922}
923
924/// `link(target = Type, local = "column", remote = "column")` is a relation matched by value:
925/// rows of `Type` whose `remote` column equals this row's `local` column. No foreign key and
926/// no wiring, which is what lets it cross into an `external` table SQLite cannot constrain.
927fn parse_link(g: &proc_macro::Group, field: &str) -> Result<LinkAttr, String> {
928    let mut items = vec![Vec::new()];
929    for tt in g.stream() {
930        match &tt {
931            TokenTree::Punct(p) if p.as_char() == ',' => items.push(Vec::new()),
932            _ => items.last_mut().expect("never empty").push(tt),
933        }
934    }
935    items.retain(|i| !i.is_empty());
936    let (mut target, mut local, mut remote) = (None, None, None);
937    for item in items {
938        match item.as_slice() {
939            [TokenTree::Ident(k), TokenTree::Punct(eq), rest @ ..]
940                if eq.as_char() == '=' && !rest.is_empty() =>
941            {
942                match k.to_string().as_str() {
943                    "target" => target = Some(tokens_text(rest)),
944                    "local" => local = Some(literal_str(rest, field)?),
945                    "remote" => remote = Some(literal_str(rest, field)?),
946                    other => {
947                        return Err(format!(
948                            "link(…) on `{field}`: unknown option `{other}` (supported: \
949                             target = Type, local = \"column\", remote = \"column\")"
950                        ));
951                    }
952                }
953            }
954            other => {
955                return Err(format!(
956                    "link(…) on `{field}`: expected `name = …`, found `{}`",
957                    tokens_text(other)
958                ));
959            }
960        }
961    }
962    match (target, local, remote) {
963        (Some(target), Some(local), Some(remote)) => Ok(LinkAttr {
964            target,
965            local,
966            remote,
967        }),
968        _ => Err(format!(
969            "link(…) on `{field}` needs target = Type, local = \"column\", and remote = \"column\""
970        )),
971    }
972}
973
974fn literal_str(rest: &[TokenTree], field: &str) -> Result<String, String> {
975    match rest {
976        [TokenTree::Literal(l)] => string_literal(l),
977        other => Err(format!(
978            "relation(…) on `{field}`: expected a string literal, found `{}`",
979            tokens_text(other)
980        )),
981    }
982}
983
984/// The string a literal token spells: `"…"` with its escapes resolved, or `r"…"`/`r#"…"#`
985/// as written. The token's text is source text, so `"say \"hi\""` has to become `say "hi"`
986/// here, not stay three characters longer.
987fn string_literal(lit: &proc_macro::Literal) -> Result<String, String> {
988    let s = lit.to_string();
989    if let Some(raw) = s.strip_prefix('r') {
990        let hashes = raw.len() - raw.trim_start_matches('#').len();
991        let body = &raw[hashes..raw.len() - hashes];
992        if hashes * 2 + 2 <= raw.len() && body.starts_with('"') && body.ends_with('"') {
993            return Ok(body[1..body.len() - 1].to_string());
994        }
995        return Err(format!("expected a string literal, found `{s}`"));
996    }
997    if s.len() < 2 || !s.starts_with('"') || !s.ends_with('"') {
998        return Err(format!("expected a string literal, found `{s}`"));
999    }
1000    let mut out = String::with_capacity(s.len());
1001    let mut chars = s[1..s.len() - 1].chars();
1002    while let Some(ch) = chars.next() {
1003        if ch != '\\' {
1004            out.push(ch);
1005            continue;
1006        }
1007        match chars.next() {
1008            Some('"') => out.push('"'),
1009            Some('\\') => out.push('\\'),
1010            Some('\'') => out.push('\''),
1011            Some('n') => out.push('\n'),
1012            Some('r') => out.push('\r'),
1013            Some('t') => out.push('\t'),
1014            Some('0') => out.push('\0'),
1015            Some('x') => {
1016                let hex: String = chars.by_ref().take(2).collect();
1017                let code = u8::from_str_radix(&hex, 16)
1018                    .map_err(|_| format!("bad escape `\\x{hex}` in {s}"))?;
1019                out.push(code as char);
1020            }
1021            Some('u') => {
1022                if chars.next() != Some('{') {
1023                    return Err(format!("bad escape `\\u` in {s}"));
1024                }
1025                let hex: String = chars.by_ref().take_while(|c| *c != '}').collect();
1026                let code = u32::from_str_radix(&hex, 16)
1027                    .ok()
1028                    .and_then(char::from_u32)
1029                    .ok_or_else(|| format!("bad escape `\\u{{{hex}}}` in {s}"))?;
1030                out.push(code);
1031            }
1032            // A backslash before a newline joins the lines, eating the leading whitespace.
1033            Some('\n') => {
1034                let rest = chars.as_str();
1035                let trimmed = rest.trim_start();
1036                chars = trimmed.chars();
1037                let _ = rest;
1038            }
1039            other => {
1040                return Err(format!(
1041                    "unsupported escape `\\{}` in {s}",
1042                    other.map(String::from).unwrap_or_default()
1043                ));
1044            }
1045        }
1046    }
1047    Ok(out)
1048}
1049
1050/// Whether `name` can be a SQL identifier at all: SQLite quotes anything, but an empty name
1051/// is refused and a NUL ends the statement text before the quote does.
1052fn check_name(what: &str, name: &str) -> Result<(), String> {
1053    if name.is_empty() {
1054        return Err(format!("Model: the {what} name is empty"));
1055    }
1056    if name.contains('\0') {
1057        return Err(format!(
1058            "Model: the {what} name {name:?} contains a NUL, which SQL cannot carry"
1059        ));
1060    }
1061    Ok(())
1062}
1063
1064fn tokens_text(tokens: &[TokenTree]) -> String {
1065    tokens.iter().cloned().collect::<TokenStream>().to_string()
1066}
1067
1068/// Split the brace body on top-level commas and read `#[obs|model(...)] vis name : Type` out of
1069/// each. "Top-level" means outside `<…>` too, so a `HashMap<u64, usize>` field stays one chunk;
1070/// brackets and parens are already single `Group` tokens, but angles arrive as bare puncts.
1071fn parse_fields(body: TokenStream) -> Result<Vec<FieldDef>, String> {
1072    let mut fields = Vec::new();
1073    let mut chunk: Vec<TokenTree> = Vec::new();
1074    let mut angle_depth = 0i32;
1075    let mut prev_dash = false;
1076
1077    for tt in body {
1078        match &tt {
1079            TokenTree::Punct(p) if p.as_char() == '<' => {
1080                angle_depth += 1;
1081                chunk.push(tt);
1082            }
1083            // `->` in a fn-pointer type must not close an angle bracket.
1084            TokenTree::Punct(p) if p.as_char() == '>' && !prev_dash => {
1085                angle_depth = (angle_depth - 1).max(0);
1086                chunk.push(tt);
1087            }
1088            TokenTree::Punct(p) if p.as_char() == ',' && angle_depth == 0 => {
1089                if !chunk.is_empty() {
1090                    fields.push(parse_one(&chunk)?);
1091                    chunk.clear();
1092                }
1093            }
1094            _ => chunk.push(tt),
1095        }
1096        prev_dash = matches!(
1097            chunk.last(),
1098            Some(TokenTree::Punct(p)) if p.as_char() == '-'
1099        );
1100    }
1101    if !chunk.is_empty() {
1102        fields.push(parse_one(&chunk)?);
1103    }
1104    Ok(fields)
1105}
1106
1107fn parse_one(chunk: &[TokenTree]) -> Result<FieldDef, String> {
1108    let mut i = 0;
1109    let mut f = FieldDef::default();
1110    let mut deferred: Vec<Vec<Vec<TokenTree>>> = Vec::new();
1111
1112    // Attributes and doc comments. `#[model(…)]` items need the field name for their errors,
1113    // so they are parsed after it is known.
1114    while i < chunk.len() {
1115        match &chunk[i] {
1116            TokenTree::Punct(p) if p.as_char() == '#' => {
1117                if let Some(TokenTree::Group(g)) = chunk.get(i + 1) {
1118                    if let Some(items) = attr_items(g, "obs") {
1119                        for item in items {
1120                            match item.as_slice() {
1121                                [TokenTree::Ident(id)] if id.to_string() == "key" => f.key = true,
1122                                [TokenTree::Ident(id)] if id.to_string() == "skip" => {
1123                                    f.skip = true;
1124                                }
1125                                other => {
1126                                    return Err(format!(
1127                                        "unknown #[obs] option: `{}` (supported: key, skip)",
1128                                        tokens_text(other)
1129                                    ));
1130                                }
1131                            }
1132                        }
1133                    } else if let Some(items) = attr_items(g, "model") {
1134                        deferred.push(items);
1135                    }
1136                    i += 2;
1137                    continue;
1138                }
1139                return Err("malformed attribute on a field".into());
1140            }
1141            _ => break,
1142        }
1143    }
1144
1145    // Visibility.
1146    if let Some(TokenTree::Ident(id)) = chunk.get(i)
1147        && id.to_string() == "pub"
1148    {
1149        i += 1;
1150        if let Some(TokenTree::Group(g)) = chunk.get(i)
1151            && g.delimiter() == Delimiter::Parenthesis
1152        {
1153            i += 1;
1154        }
1155    }
1156
1157    f.name = match chunk.get(i) {
1158        Some(TokenTree::Ident(id)) => id.to_string(),
1159        _ => return Err("expected a field name".into()),
1160    };
1161    i += 1;
1162    match chunk.get(i) {
1163        Some(TokenTree::Punct(p)) if p.as_char() == ':' => i += 1,
1164        _ => return Err(format!("expected `:` after field `{}`", f.name)),
1165    }
1166
1167    // The type is whatever is left, re-emitted verbatim, never interpreted.
1168    f.ty = tokens_text(&chunk[i..]);
1169    if f.ty.is_empty() {
1170        return Err(format!("field `{}` has no type", f.name));
1171    }
1172
1173    for items in deferred {
1174        parse_field_options(items, &mut f)?;
1175    }
1176    Ok(f)
1177}