[Gnucash-changes] The contents of this document have now been
merged into the QOF header
Linas Vepstas
linas at cvs.gnucash.org
Wed May 5 10:43:50 EDT 2004
Log Message:
-----------
The contents of this document have now been merged into the
QOF header files (which should show up in src/engine in the enxt update).
This file is now dead
Removed Files:
-------------
gnucash/src/doc:
query-api.txt
Revision Data
-------------
--- src/doc/query-api.txt
+++ /dev/null
@@ -1,205 +0,0 @@
-Gnucash Query API
-
-
-BASIC QUERY API: With this API you can create arbitrary logical
-queries to find sets of splits in an account group. To make simple
-queries (1 term, such as an account query), create the appropriate
-QueryTerm structure and stick it in a Query object using
-xaccInitQuery. The QueryTerm should be malloced but the Query object
-will handle freeing it. To make compound queries, make multiple
-simple queries and combine them using xaccMergeQuery and the logical
-operations of your choice.
-
------------------------------------------------------------------
-Query * xaccMallocQuery()
-
-Allocates and initializes a Query structure which must be freed by the
-user with xaccFreeQuery. A newly-allocated Query object matches
-nothing (xaccQueryGetSplits will return NULL).
-
------------------------------------------------------------------
-void xaccInitQuery(Query * q, QueryTerm * qt)
-
-Initializes an allocated Query object with initial term qt (possibly
-NULL). Any previous query terms are freed.
-
------------------------------------------------------------------
-void xaccFreeQuery(Query * q)
-
-Frees the resources associate with a Query object.
-
------------------------------------------------------------------
-void xaccQuerySetGroup(Query * q, AccountGroup * group)
-
-Set the Gnucash account group that the query applies to.
-xaccQuerySetGroup must be called before a Query object created with
-xaccMallocQuery can be used. Queries created with xaccQueryInvert and
-xaccQueryMerge inherit the account group of the arguments to those
-functions.
-
------------------------------------------------------------------
-Query * xaccQueryInvert(Query * q)
-
-Logically invert the query. xaccInvertQuery returns a newly allocated
-Query object such that the union of the splits matched by query q and
-query (p = xaccQueryInvert(q)) is the entire account group that q
-applies to.
-
------------------------------------------------------------------
-Query * xaccQueryMerge(Query * q1, Query * q2, QueryOp how)
-
-Combine queries q1 and q2 using logical operator 'how'. 'how' must be
-one of QUERY_AND, QUERY_OR, QUERY_NAND, QUERY_NOR, QUERY_XOR. The
-account groups of q1 and q2 must be the same. xaccQueryMerge returns
-a newly-allocated Query object or NULL on error.
-
------------------------------------------------------------------
-void xaccQueryClear(Query * q)
-
-Remove all query terms from q. q matches nothing after xaccQueryClear.
-
------------------------------------------------------------------
-void xaccQueryPurgeTerms(Query * q, pd_type_t type);
-
-Remove query terms of a particular type from q. The "type" of a term
-is determined by the type of data that gets passed to the predicate
-function. The currently-supported values of 'type' are PD_DATE,
-PD_AMOUNT, PD_ACCOUNT, PD_STRING, PD_CLEARED, PD_MISC. This function
-is really only used in one place: in window-register.c, to modify
-in-place a query to remove any date tests prior to adding new ones.
-This should probably be removed from the API in favor of an extra
-argument to xaccQueryMerge specifying what to do with existing terms
-of that type.
-
-
------------------------------------------------------------------
-int xaccQueryHasTerms(Query * q)
-
-Returns the number of terms in the canonical form of the query. Can
-be used as a predicate to see if the query has been initialized
-(return value > 0) or is "blank" (return value == 0).
-
-
------------------------------------------------------------------
-
-CONVENIENCE API: The remainder of the API (in particular, any function
-called xaccQueryAdd***Match) is a set of convenience functions for
-creating and modifying specific types of queries. All of these
-functions can be duplicated using the Basic API specified above,
-directly manipulating QueryTerm objects and creating and merging
-queries as needed. One slight advantage of the convenience API is
-that it uses a standard set of predicates that are more-or-less
-opaque. This may be important later.
-
-It's probably more useful to describe the various types of
-PredicateData than the convenience functions, which are pretty
-self-explanatory once you understand what the underlying process is.
-For example, AddMemoMatch and AddDescriptionMatch are essentially the
-same function because they both use PD_STRING predicate data; they
-just use a different predicate (one compares data.string.matchstring
-with the split's Memo, one compares with the parent transaction's
-Description).
-
-Each function in the convenience API takes a Query *, some arguments
-which fill in the fields of the appropriate PredicateData type, and a
-QueryOp. The Query object is modified in place, using the logical
-operation specified by the QueryOp to combine a single new QueryTerm
-with the existing Query. This works by making a new Query of one term
-and combining with the existing Query using xaccQueryMerge and the
-specified QueryOp. If you have an existing Query (a + b + c) and
-combine using QueryOp QUERY_AND in a convenience function representing
-predicate d, you will get (ad + bd + cd).
-
-
-STRUCTURE OF A QUERY: A Query is a logical function of any number of
-QueryTerms. A QueryTerm consists of a C function pointer (the
-Predicate) and a PredicateData structure containing data passed to the
-predicate funtion. The PredicateData structure is a constant
-associated with the Term and is identical for every Split that is
-tested.
-
-The terms of the Query may represent any logical function and are
-stored in canonical form, i.e. the function is expressed as a logical
-sum of logical products. So if you have QueryTerms a, b, c, d, e and
-you have the logical function a(b+c) + !(c(d+e)), it gets stored as
-ab + ac + !c + !c!e +!d!c + !d!e. This may not be optimal for evaluation
-of some functions but it's easy to store, easy to manipulate, and it
-doesn't require a complete algebra system to deal with.
-
-The representation is of a GList of GLists of QueryTerms. The
-"backbone" GList q->terms represents the OR-chain, and every item on
-the backbone is a GList of QueryTerms representing an AND-chain
-corresponding to a single product-term in the canonical
-representation. QueryTerms are duplicated when necessary to fill out
-the canonical form, and the same predicate may be evaluated multiple
-times per split for complex queries. This is a place where we could
-probably optimize.
-
-Evaluation of a Query (see xaccQueryGetSplits) is optimized as much as
-possible by short-circuited evaluation. The predicates in each
-AND-chain are sorted by predicate type, with Account queries sorted
-first to allow the evaluator to completely eliminate accounts from the
-search if there's no chance of them having splits that match.
-
-
-PREDICATE DATA TYPES: All the predicate data types are rolled up into
-the union type PredicateData. The "type" field specifies which type
-the union is. The values of type are:
-
------------------------------------------------------------------
-PD_DATE : match a date range. Specify a start date and an end date.
-
-Used in: xaccQueryAddDateMatch
- xaccQueryAddDateMatchTS
- xaccQueryAddDateMatchTT
-
------------------------------------------------------------------
-PD_AMOUNT : match a numeric amount. Specify an amount (always
-positive), a funds-flow direction (credit, debit, or either), and
-"how", specifying the type of amount comparison to be used :
-
- AMT_MATCH_ATLEAST : split >= pd amount
- AMT_MATCH_ATMOST : split >= pd amount
- AMT_MATCH_EXACTLY : split == pd amount
-
-Used in: xaccQueryAddAmountMatch
- xaccQueryAddSharePriceMatch
- xaccQueryAddSharesMatch
-
------------------------------------------------------------------
-PD_ACCOUNT : match an account or set of accounts. Specify a set
-of accounts and "how":
-
- ACCT_MATCH_ALL : a transaction must have at least one split
- affecting each account in pd.acct.accounts.
- ACCT_MATCH_ANY : a transaction must have at least one split
- affecting any account in the set
- ACCT_MATCH_NONE : a transaction may not affect any account in
- the set.
-
-Used in: xaccQueryAddAccountMatch
- xaccQueryAddSingleAccountMatch
-
------------------------------------------------------------------
-PD_STRING : match a string. Specify a string, bool signifying
-case sensitivity, bool signifying regexp or simple string.
-
-Used in: xaccQueryAddDescriptionMatch
- xaccQueryAddNumberMatch
- xaccQueryAddActionMatch
- xaccQueryAddMemoMatch
-
------------------------------------------------------------------
-PD_CLEARED : match the Cleared state of the transaction. Specify
-a bit-mask that is an OR combination of one or more of the
-following:
- CLEARED_NO (state == 'n')
- CLEARED_CLEARED (state == 'c')
- CLEARED_RECONCILED (state == 'y')
-
-Used in: xaccQueryAddClearedMatch
-
------------------------------------------------------------------
-PD_MISC : match some "other" user predicate. Not used at the moment.
-
------------------------------------------------------------------
More information about the Gnucash-changes
mailing list