mirror of
https://github.com/Gnucash/gnucash.git
synced 2025-02-25 18:55:30 -06:00
*** empty log message ***
git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@2406 57a11ea4-9604-0410-9ed3-97b8803252fd
This commit is contained in:
parent
6bf7915b89
commit
27806fea12
205
src/engine/README.query-api
Normal file
205
src/engine/README.query-api
Normal file
@ -0,0 +1,205 @@
|
||||
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.
|
||||
|
||||
-----------------------------------------------------------------
|
Loading…
Reference in New Issue
Block a user