Cleanup Tuple to allow self-typing.

[rrq/rrqmisc.git] / vector / Query.h

diff --git a/vector/Query.h b/vector/Query.h
index 17bbe384295c048362b51ddbaf7320efd6424941..f13083d6df426c4ecf72f677ae1b46ca4e14fcf8 100644 (file)
--- a/vector/Query.h
+++ b/vector/Query.h
@@ -1,24 +1,25 @@
-#ifndef query_H
-#define query_H
+#ifndef Query_H
+#define Query_H
 
 #include <TupleSchema.h>
 #include <Relation.h>
+#include <BindingTable.h>
 
-struct query_callbacks;
+struct QueryCallbacks;
 
 /**
- * A query is an implementation of a generic ABI over relations. It's
+ * A Query is an implementation of a generic ABI over relations. It's
  * more or less a "virtual Relation" representing a logical composite
  * access of actual relations, and as such its active part is held in
- * a separate \ref querytype record similar to how \ref ItemKeyFun
+ * a separate \ref Querytype record similar to how \ref ItemKeyFun
  * records define valye types.
  */
 typedef struct {
-    struct query_callbacks *def;
-} query;
+    struct QueryCallbacks *def;
+} Query;
 
 /**
- * \brief Creates an assignment query.
+ * \brief Creates an assignment Query.
  *
  * \param arity is the assignment tuple arity.
  *
@@ -27,27 +28,85 @@ typedef struct {
  * \param values is the (void*) values to asign.
  *
  * The two tuples must have the same arity for assigning names[i] to
- * values[i]. This query makes the given names have the given values,
+ * values[i]. This Query makes the given names have the given values,
  * once for each (*next) call following a (*reset) call.
  *
- * \related query
+ * \related Query
  */
-extern query *query_assign(int arity,tuple *names,tuple *values);
+extern Query *Query_assign(int arity,Tuple *names,Tuple *values);
 
-
-
-typedef struct {
-    query base;
-    Relation *r;
-    tuple *names;
-    tuple *query;
-} lookup_query;
+/**
+ * \brief Create a Query record for lookup data in a Relation.
+ *
+ * \param r is the relation being queried.
+ *
+ * \param names is a same-arity tuple of binding names for the
+ * columns, using \b 0 for unnamed columns.
+ *
+ * \param values is a same--arity tuple of query values, using \b 0 for
+ * columns to enumerate.
+ *
+ * The names and values tuples identify bindings and values to use for
+ * the search query, and which bindings to set up from the successive
+ * results. Names that are bound beforhand identify constraining
+ * values, and the names that are unbound gain successive values from
+ * the matching tuples.
+ *
+ * \related Query
+ */
+extern Query *Query_Relation(Relation *r,Tuple *names,Tuple *values);
 
 /**
- * \brief Create a lookup_query record for lookup data in a Relation.
+ * \brief Create a Query record for a conjunction of queries.
+ *
+ * \param n is the number of sub queries.
+ *
+ * \param ... are the sub queries.
+ *
+ * The conjunction query processes the sub queries in order resulting
+ * in the sequence of their combined bindings.
+ *
+ * \related Query
  */
-extern query *query_lookup(Relation *r,...);
+extern Query *Query_and(int n,...);
 
+/**
+ * \brief Create a Query record for a disjunction of queries.
+ *
+ * \param n is the number of sub queries.
+ *
+ * \param ... are the sub queries.
+ *
+ * The disjunction query processed the sub queries in order to find
+ * all their individual "true" binding combinations. It processes one
+ * sub query at a time to exhaustion and provide their individudal
+ * binding sequences separately.
+ *
+ * \related Query
+ */
+extern Query *Query_or(int n,...);
 
+/**
+ * \brief Invoke a consequent callback function for each successful
+ * binding of a query.
+ *
+ * \param q is the antecedent query to process.
+ *
+ * \param bt is the binding table to use.
+ *
+ * \param consequent is the callback function to invoke for each
+ * binding.
+ * \param data is the caller's context data.
+ *
+ * This function prrocesses the Query for establishing its binding
+ * sequence and inokes the consequent callback function for each
+ * binding as it is provided.
+ * 
+ * \related Query
+ */
+extern void Query_rule(
+    Query *q,BindingTable *bt,
+    int (*consequent)(BindingTable *bt,void *data),
+    void *data );
 
 #endif