Merge pull request #129 from triblespace/codex/implement-delta-macro-as-procedural-macro

Implement procedural delta macro

Author: somethingelseentirely

CHANGELOG.md

@@ -18,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `entity!` now implemented as a procedural macro alongside `pattern!`.
 - `entity!` subsumes the old `entity_inner!` helper; macro invocations can
   optionally provide an existing `TribleSet`.
+- Implemented a procedural `delta!` macro for incremental query support.
 - Expanded documentation for the `pattern` procedural macro to ease maintenance, including detailed comments inside the implementation.
 - `EntityId` variants renamed to `Var` and `Lit` for consistency with field patterns.
 - `Workspace::checkout` now accepts commit ranges for convenient history queries.

INVENTORY.md

@@ -4,18 +4,13 @@
 - None at the moment.
 
 ## Completed Work
-- None yet. This file now tracks development ideas.
+- Implemented a `delta!` macro for incremental queries. The macro
+  computes the difference between two `TribleSet`s and unions per-triple
+  results so callers only see newly inserted data.
 
 ## Desired Functionality
 - Finalize the compressed zero-copy archive format currently mentioned as WIP.
 - Provide additional examples showcasing advanced queries and repository usage.
-- Add incremental query support building on the union constraint so
-  results can update when datasets change without full recomputation.
-  Namespaces will expose a `delta!` operator similar to `pattern!`
-  that receives the previous and current `TribleSet`, calls `union!`
-  internally and matches only the newly added tribles. See the book's
-  [Incremental Queries](book/src/incremental-queries.md) chapter for
-  the planned approach.
 - Explore replacing `CommitSelector` ranges with a set-based API
   built on commit reachability. The goal is to mirror git's revision
   selection semantics (similar to `rev-list` or `rev-parse`).

book/src/incremental-queries.md

@@ -11,7 +11,7 @@ delta while the remaining constraints see the full updated dataset. Each
 case yields the new solutions introduced by those additions and we then
 union all of the per‑constraint results.
 
-To help express these delta queries at the macro level, namespaces will
+To help express these delta queries at the macro level, namespaces now
 offer a `delta!` operator. It behaves like `pattern!` but takes the
 previous and current `TribleSet`. The macro computes their difference
 and then calls `union!` internally to apply the resulting delta

src/namespace.rs

@@ -75,8 +75,15 @@ macro_rules! NS {
                 };
             }
 
-            // TODO: incremental queries will eventually use a dedicated `delta!`
-            // macro that applies semi-naive rewriting on a per-triple basis.
+            #[macro_pub::macro_pub]
+            macro_rules! delta {
+                ($prev:expr, $curr:expr, $pattern: tt) => {
+                    {
+                        ::tribles_macros::delta!{ ::tribles, $mod_name, $prev, $curr, $pattern }
+                    }
+                };
+            }
+
         }
     };
 }
@@ -199,4 +206,56 @@ mod tests {
             r
         );
     }
+
+    #[test]
+    fn ns_delta() {
+        let mut base = TribleSet::new();
+        (0..10).for_each(|_| {
+            let a = ufoid();
+            let b = ufoid();
+            base += literature::entity!(&a, {
+                firstname: Name(EN).fake::<String>(),
+                lastname: Name(EN).fake::<String>()
+            });
+            base += literature::entity!(&b, {
+                title: Name(EN).fake::<String>(),
+                author: &a
+            });
+        });
+
+        let mut updated = base.clone();
+        let shakespeare = ufoid();
+        let hamlet = ufoid();
+        updated += literature::entity!(&shakespeare, {
+            firstname: "William",
+            lastname: "Shakespeare"
+        });
+        updated += literature::entity!(&hamlet, {
+            title: "Hamlet",
+            author: &shakespeare,
+            quote: "To be, or not to be, that is the question.".to_blob().get_handle()
+        });
+
+        let r: Vec<_> = find!(
+            (author, hamlet, title),
+            literature::delta!(&base, &updated, [
+            {author @
+             firstname: ("William"),
+             lastname: ("Shakespeare")},
+            {hamlet @
+                title: title,
+                author: author
+            }])
+        )
+        .collect();
+
+        assert_eq!(
+            vec![(
+                shakespeare.to_value(),
+                hamlet.to_value(),
+                "Hamlet".to_value(),
+            )],
+            r
+        );
+    }
 }

tribles-macros/src/lib.rs

@@ -344,6 +344,48 @@ pub fn entity(input: TokenStream) -> TokenStream {
     }
 }
 
+/// Parsed input for the [`delta`] macro.
+///
+/// The invocation takes the form `crate_path, namespace_path, prev, curr, [..]`.
+/// `prev` and `curr` are expressions evaluating to [`TribleSet`]s. The pattern
+/// syntax matches that of [`pattern!`].
+struct DeltaInput {
+    crate_path: Path,
+    ns: Path,
+    prev: Expr,
+    curr: Expr,
+    pattern: Vec<Entity>,
+}
+
+impl Parse for DeltaInput {
+    fn parse(input: ParseStream<'_>) -> syn::Result<Self> {
+        let crate_path: Path = input.parse()?;
+        input.parse::<Token![,]>()?;
+        let ns: Path = input.parse()?;
+        input.parse::<Token![,]>()?;
+        let prev: Expr = input.parse()?;
+        input.parse::<Token![,]>()?;
+        let curr: Expr = input.parse()?;
+        input.parse::<Token![,]>()?;
+        let content;
+        bracketed!(content in input);
+        let mut pattern = Vec::new();
+        while !content.is_empty() {
+            pattern.push(content.parse()?);
+            if content.peek(Token![,]) {
+                content.parse::<Token![,]>()?;
+            }
+        }
+        Ok(DeltaInput {
+            crate_path,
+            ns,
+            prev,
+            curr,
+            pattern,
+        })
+    }
+}
+
 fn entity_impl(input: TokenStream) -> syn::Result<TokenStream> {
     let EntityInput {
         crate_path,
@@ -406,3 +448,182 @@ fn entity_impl(input: TokenStream) -> syn::Result<TokenStream> {
 
     Ok(output.into())
 }
+
+/// Procedural implementation of the `delta!` macro.
+#[proc_macro]
+pub fn delta(input: TokenStream) -> TokenStream {
+    match delta_impl(input) {
+        Ok(ts) => ts,
+        Err(e) => e.to_compile_error().into(),
+    }
+}
+
+fn delta_impl(input: TokenStream) -> syn::Result<TokenStream> {
+    use std::collections::HashMap;
+
+    let DeltaInput {
+        crate_path,
+        ns,
+        prev,
+        curr,
+        pattern,
+    } = syn::parse(input)?;
+
+    // Identifiers used throughout the expansion
+    let ctx_ident = format_ident!("__ctx", span = Span::call_site());
+    let prev_ident = format_ident!("__prev", span = Span::call_site());
+    let curr_ident = format_ident!("__curr", span = Span::call_site());
+    let delta_ident = format_ident!("__delta", span = Span::call_site());
+
+    // Prepare declarations shared by all union branches
+    let mut attr_decl_tokens = TokenStream2::new();
+    let mut attr_const_tokens = TokenStream2::new();
+
+    let mut entity_decl_tokens = TokenStream2::new();
+    let mut entity_const_tokens = TokenStream2::new();
+
+    let mut value_decl_tokens = TokenStream2::new();
+    let mut value_const_tokens = TokenStream2::new();
+
+    struct TripleInfo {
+        e_ident: Ident,
+        a_ident: Ident,
+        v_ident: Ident,
+    }
+    let mut triples: Vec<TripleInfo> = Vec::new();
+
+    let mut attr_map: HashMap<String, Ident> = HashMap::new();
+    let mut attr_idx = 0usize;
+    let mut entity_idx = 0usize;
+    let mut value_idx = 0usize;
+
+    for entity in pattern {
+        let e_ident = format_ident!("__e{}", entity_idx, span = Span::call_site());
+        entity_idx += 1;
+        match entity.id {
+            Some(EntityId::Var(id)) => {
+                entity_decl_tokens.extend(quote! { let #e_ident = #id; });
+            }
+            Some(EntityId::Lit(expr)) => {
+                entity_decl_tokens.extend(quote! {
+                    let #e_ident: #crate_path::query::Variable<#crate_path::value::schemas::genid::GenId> = #ctx_ident.next_variable();
+                });
+                entity_const_tokens.extend(quote! {
+                    constraints.push({ let e: #crate_path::id::Id = #expr; Box::new(#e_ident.is(#crate_path::value::ToValue::to_value(e)))});
+                });
+            }
+            None => {
+                entity_decl_tokens.extend(quote! {
+                    let #e_ident: #crate_path::query::Variable<#crate_path::value::schemas::genid::GenId> = #ctx_ident.next_variable();
+                });
+            }
+        }
+
+        for Field { name, value } in entity.fields {
+            let field_ident = name;
+            let a_ident = attr_map
+                .entry(field_ident.to_string())
+                .or_insert_with(|| {
+                    let ident = format_ident!("__a{}", attr_idx, span = Span::call_site());
+                    attr_idx += 1;
+                    attr_decl_tokens.extend(quote! {
+                        let #ident: #crate_path::query::Variable<#crate_path::value::schemas::genid::GenId> = #ctx_ident.next_variable();
+                    });
+                    attr_const_tokens.extend(quote! {
+                        constraints.push(Box::new(#ident.is(#crate_path::value::ToValue::to_value(ns::ids::#field_ident))));
+                    });
+                    ident
+                })
+                .clone();
+
+            let v_ident = format_ident!("__v{}", value_idx, span = Span::call_site());
+            value_idx += 1;
+
+            match value {
+                FieldValue::Lit(expr) => {
+                    let val_ident = format_ident!("__c{}", value_idx, span = Span::call_site());
+                    value_idx += 1;
+                    value_decl_tokens.extend(quote! {
+                        let #v_ident: #crate_path::query::Variable<ns::schemas::#field_ident> = #ctx_ident.next_variable();
+                        let #val_ident: #crate_path::value::Value<ns::schemas::#field_ident> = #crate_path::value::ToValue::to_value(#expr);
+                    });
+                    value_const_tokens.extend(quote! {
+                        constraints.push(Box::new(#v_ident.is(#val_ident)));
+                    });
+                }
+                FieldValue::Var(expr) => {
+                    value_decl_tokens.extend(quote! {
+                        let #v_ident: #crate_path::query::Variable<ns::schemas::#field_ident> = #expr;
+                    });
+                }
+            }
+
+            triples.push(TripleInfo {
+                e_ident: e_ident.clone(),
+                a_ident: a_ident.clone(),
+                v_ident,
+            });
+        }
+    }
+
+    let mut case_exprs: Vec<TokenStream2> = Vec::new();
+    for delta_idx in 0..triples.len() {
+        let mut triple_tokens = TokenStream2::new();
+        for (
+            idx,
+            TripleInfo {
+                e_ident,
+                a_ident,
+                v_ident,
+            },
+        ) in triples.iter().enumerate()
+        {
+            let dataset = if idx == delta_idx {
+                &delta_ident
+            } else {
+                &curr_ident
+            };
+            triple_tokens.extend(quote! {
+                constraints.push(Box::new(#dataset.pattern(#e_ident, #a_ident, #v_ident)));
+            });
+        }
+
+        let case = quote! {
+            {
+                let mut constraints: Vec<Box<dyn #crate_path::query::Constraint>> = vec![];
+                use #crate_path::query::TriblePattern;
+                #triple_tokens
+                #crate_path::query::intersectionconstraint::IntersectionConstraint::new(constraints)
+            }
+        };
+        case_exprs.push(case);
+    }
+
+    let union_expr = quote! {
+        #crate_path::query::unionconstraint::UnionConstraint::new(vec![
+            #(Box::new(#case_exprs) as Box<dyn #crate_path::query::Constraint>),*
+        ])
+    };
+
+    let output = quote! {
+        {
+            let #ctx_ident = __local_find_context!();
+            let #prev_ident = #prev;
+            let #curr_ident = #curr;
+            let #delta_ident = #curr_ident.difference(&#prev_ident);
+            use #ns as ns;
+            #attr_decl_tokens
+            #entity_decl_tokens
+            #value_decl_tokens
+            let mut constraints: Vec<Box<dyn #crate_path::query::Constraint>> = vec![];
+            use #crate_path::query::TriblePattern;
+            #attr_const_tokens
+            #entity_const_tokens
+            #value_const_tokens
+            constraints.push(Box::new(#union_expr));
+            #crate_path::query::intersectionconstraint::IntersectionConstraint::new(constraints)
+        }
+    };
+
+    Ok(output.into())
+}