[Gnucash-changes] add documentation
Linas Vepstas
linas at cvs.gnucash.org
Mon Apr 12 01:24:32 EDT 2004
Log Message:
-----------
add documentation
Modified Files:
--------------
gnucash/src/engine:
qofquery.h
qofquerycore.h
qofsql.h
Revision Data
-------------
Index: qofsql.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofsql.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -Lsrc/engine/qofsql.h -Lsrc/engine/qofsql.h -u -r1.1 -r1.2
--- src/engine/qofsql.h
+++ src/engine/qofsql.h
@@ -30,7 +30,8 @@
#define QOF_SQL_QUERY_H
#include <glib.h>
-#include "qofbook.h"
+#include <qof/kvp_frame.h>
+#include <qof/qofbook.h>
typedef struct _QofSqlQuery QofSqlQuery;
@@ -47,16 +48,66 @@
/** Perform the query, return the results.
*
- * The returned list is a list of the 'search-for' type that was
- * previously set with the qof_query_search_for() or the
- * XXX fixme this doc is wrong.
- * qof_query_create_for() routines. The returned list will have
- * been sorted using the indicated sort order, and trimed to the
+ * The returned list is a list of ... See below ...
+ * The returned list will have been sorted using the indicated sort
+ * order, (by default ascending order) and trimed to the
* max_results length.
* Do NOT free the resulting list. This list is managed internally
* by QofSqlQuery.
+ *
+ * The types of SQL queries that are allowed at this point are very
+ * limited. In general, only the following types of queries are
+ * supported:
+ * SELECT * FROM SomeObj WHERE (param_a < 10.0) AND (param_b = "asdf")
+ * SORT BY param_c DESC;
+ * The returned list is a list of all of the instances of 'SomeObj' that
+ * mathc the query. The 'SORT' term is optional. The 'WHERE' term is
+ * optional; but if you don't include 'WHERE', you will get a list of
+ * all of the object instances. The Boolean operations 'AND' and 'OR'
+ * together with parenthesis can be used to construct arbitrarily
+ * nested predicates.
+ *
+ * The following are types of queries are NOT supported:
+ * SELECT a,b,c FROM ...
+ * I am thinking of implementing the above as a list of KVP's
+ * whose keys would be a,b,c and values would be the results of the
+ * search.
+ *
+ * Also unsupported are joins:
+ * SELECT * FROM ObjA,ObjB WHERE (ObjA.thingy = ObjB.Stuff);
+ * The problem with the above is that the search requires a nested
+ * search loop, aka a 'join', which is not currently supported in the
+ * underlying QofQuery code.
+ *
+ * Also unsupported: UPDATE and INSERT.
*/
GList * qof_sql_query_run (QofSqlQuery *query, const char * str);
+
+/**
+ * Set the kvp frame to be used for formulating 'indirect' predicates.
+ *
+ * Although joins are not supported (see above), there is one special
+ * hack that one can use to pass data indirectly into the predicates.
+ * This is by using a KVP key name to reference the value to be used
+ * for a predicate. Thus, for example,
+ * SELECT * FROM SomeObj WHERE (param_a = KVP:/some/key/path);
+ * will look up the value stored at '/some/key/path', and use that
+ * value to form the actual predicate. So, for example, if
+ * the value stored at '/some/key/path' was 2, then the actual
+ * query run will be
+ * SELECT * FROM SomeObj WHERE (param_a = 2);
+ * The lookup occurs at the time that the query is formulated.
+ *
+ * The query does *not* take over ownership of the kvp frame,
+ * nor does it copy it. Thus, the kvp frame must exist when the
+ * query is formulated, and it is the responsibility of the
+ * caller to free it when no longer needed.
+ *
+ * Note that because this feature is a kind of a hack put in place
+ * due to the lack of support for joins, it will probably go away
+ * (be deprecated) if/when joins are implemented.
+ */
+void qof_sql_query_set_kvp (QofSqlQuery *, KvpFrame *);
#endif /* QOF_SQL_QUERY_H */
Index: qofquery.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofquery.h,v
retrieving revision 1.7
retrieving revision 1.8
diff -Lsrc/engine/qofquery.h -Lsrc/engine/qofquery.h -u -r1.7 -r1.8
--- src/engine/qofquery.h
+++ src/engine/qofquery.h
@@ -55,11 +55,16 @@
/** "Known" Object Parameters -- all objects must support these */
#define QOF_QUERY_PARAM_BOOK "book"
#define QOF_QUERY_PARAM_GUID "guid"
-#define QOF_QUERY_PARAM_ACTIVE "active" /* it's ok if an object does
- * not support this */
+
+/** "Known" Object Parameters -- some objects might support these */
+#define QOF_QUERY_PARAM_ACTIVE "active"
/* --------------------------------------------------------- */
-/** Startup and Shutdown */
+/** Subsystem initialization and shutdown. Call init() once
+ * to initalize the query subsytem; call shutdown() to free
+ * up any resources associated with the query subsystem.
+ * Typically called during application startup, shutdown.
+ */
void qof_query_init (void);
void qof_query_shutdown (void);
@@ -106,17 +111,28 @@
* param_list = make_list (SPLIT_ACCOUNT, ACCOUNT_NAME, NULL);
* qof_query_add_term (query, param_list, QOF_COMPARE_EQUAL,
* acct_name_pred_data, QOF_QUERY_AND);
+ *
+ * Please note that QofQuery does not, at this time, support joins.
+ * That is, one cannot specify a predicate that is a parameter list.
+ * Put another way, one cannot search for objects where
+ * obja->thingy == objb->stuff
*/
void qof_query_add_term (QofQuery *query, GSList *param_list,
QofQueryPredData *pred_data, QofQueryOp op);
+/** DOCUMENT ME !! */
void qof_query_add_guid_match (QofQuery *q, GSList *param_list,
const GUID *guid, QofQueryOp op);
+/** DOCUMENT ME !! */
void qof_query_add_guid_list_match (QofQuery *q, GSList *param_list,
GList *guid_list, QofGuidMatch options,
QofQueryOp op);
+/** Handy-dandy convenience routines, avoids having to create
+ * a separate predicate for boolean matches. We might want to
+ * create handy-dandy sugar routines for the other predicate types
+ * as well. */
void qof_query_add_boolean_match (QofQuery *q,
GSList *param_list,
gboolean value,
@@ -151,9 +167,17 @@
/** Return the number of terms in thq query. */
int qof_query_num_terms (QofQuery *q);
+/** DOCUMENT ME !! */
gboolean qof_query_has_term_type (QofQuery *q, GSList *term_param);
+/** Make a copy of the indicated query */
QofQuery * qof_query_copy (QofQuery *q);
+
+/** Make a copy of the indicated query, inverting the sense
+ * of the search. In other words, if the original query search
+ * for all objects with a certain condition, the inverted query
+ * will search for all object with NOT that condition.
+ */
QofQuery * qof_query_invert(QofQuery *q);
/** Merges two queries together. Both queries must be compatible
@@ -232,15 +256,15 @@
*/
gboolean qof_query_equal (QofQuery *q1, QofQuery *q2);
-/* Print the Query in human-readable format.
+/** Print the Query in human-readable format.
* Useful for debugging and development.
*/
void qof_query_print (QofQuery *query);
-/* Return the type of data we're querying for */
+/** Return the type of data we're querying for */
QofIdType qof_query_get_search_for (QofQuery *q);
-/* Return the list of books we're using */
+/** Return the list of books we're using */
GList * qof_query_get_books (QofQuery *q);
#endif /* QOF_QUERYNEW_H */
Index: qofquerycore.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofquerycore.h,v
retrieving revision 1.8
retrieving revision 1.9
diff -Lsrc/engine/qofquerycore.h -Lsrc/engine/qofquerycore.h -u -r1.8 -r1.9
--- src/engine/qofquerycore.h
+++ src/engine/qofquerycore.h
@@ -129,6 +129,11 @@
QofQueryPredData *qof_query_boolean_predicate (QofQueryCompare how, gboolean val);
QofQueryPredData *qof_query_char_predicate (QofCharMatch options,
const char *chars);
+
+/** The qof_query_kvp_predicate() matches the object that has
+ * the value 'value' located at the path 'path'. In a certain
+ * sense, the 'path' is handled as if it were a paramter.
+ */
QofQueryPredData *qof_query_kvp_predicate (QofQueryCompare how,
GSList *path, const KvpValue *value);
More information about the Gnucash-changes
mailing list