1 /********************************************************************\
2  * qofquerycore.h -- API for providing core Query data types        *
3  * Copyright (C) 2002 Derek Atkins <warlord@MIT.EDU>                *
4  * Copyright (C) 2006 Neil Williams <linux@codehelp.co.uk>          *
5  *                                                                  *
6  * This program is free software; you can redistribute it and/or    *
7  * modify it under the terms of the GNU General Public License as   *
8  * published by the Free Software Foundation; either version 2 of   *
9  * the License, or (at your option) any later version.              *
10  *                                                                  *
11  * This program is distributed in the hope that it will be useful,  *
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of   *
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the    *
14  * GNU General Public License for more details.                     *
15  *                                                                  *
16  * You should have received a copy of the GNU General Public License*
17  * along with this program; if not, contact:                        *
18  *                                                                  *
19  * Free Software Foundation           Voice:  +1-617-542-5942       *
20  * 51 Franklin Street, Fifth Floor    Fax:    +1-617-542-2652       *
21  * Boston, MA  02110-1301,  USA       gnu@gnu.org                   *
22  *                                                                  *
23 \********************************************************************/
24 
25 /** @addtogroup Query
26     @{ */
27 
28 /** @file qofquerycore.h
29     @brief API for providing core Query data types
30     @author Copyright (C) 2002 Derek Atkins <warlord@MIT.EDU>
31 */
32 
33 #ifndef QOF_QUERYCORE_H
34 #define QOF_QUERYCORE_H
35 
36 #include "qofnumeric.h"
37 #include "qofdate.h"
38 #include "kvpframe.h"
39 #include "qofclass.h"
40 
41 /**
42  * PREDICATE DATA TYPES: All the predicate data types are rolled up into
43  * the union type PredicateData.  The "type" field specifies which type
44  * the union is.
45  */
46 typedef struct _QofQueryPredData QofQueryPredData;
47 
48 /** Standard Query comparitors, for how to compare objects in a predicate.
49  *  Note that not all core types implement all comparitors
50  */
51 typedef enum
52 {
53 	QOF_COMPARE_LT = 1,
54 	QOF_COMPARE_LTE,
55 	QOF_COMPARE_EQUAL,
56 	QOF_COMPARE_GT,
57 	QOF_COMPARE_GTE,
58 	QOF_COMPARE_NEQ
59 } QofQueryCompare;
60 
61 /** List of known core query data-types...
62  *  Each core query type defines it's set of optional "comparitor qualifiers".
63  */
64 /* Comparisons for QOF_TYPE_STRING */
65 typedef enum
66 {
67 	QOF_STRING_MATCH_NORMAL = 1,
68 	QOF_STRING_MATCH_CASEINSENSITIVE
69 } QofStringMatch;
70 
71 /** Comparisons for QOF_TYPE_DATE
72  * The QOF_DATE_MATCH_DAY comparison rounds the two time
73  *     values to mid-day and then compares these rounded values.
74  * The QOF_DATE_MATCH_NORMAL comparison matches the time values,
75  *     down to the second.
76  */
77 
78 typedef enum
79 {
80 	QOF_DATE_MATCH_NORMAL = 1,
81 	QOF_DATE_MATCH_DAY
82 } QofDateMatch;
83 
84 /** Comparisons for QOF_TYPE_NUMERIC, QOF_TYPE_DEBCRED
85  *
86  * XXX Should be deprecated, or at least wrapped up as a convenience
87  * function,  this is based on the old bill gribble code, which assumed
88  * the amount was always positive, and then specified a funds-flow
89  * direction (credit, debit, or either).
90  *
91  * The point being that 'match credit' is equivalent to the compound
92  * predicate (amount >= 0) && (amount 'op' value) while the  'match
93  * debit' predicate is equivalent to (amount <= 0) && (abs(amount) 'op' value)
94 */
95 
96 typedef enum
97 {
98 	QOF_NUMERIC_MATCH_DEBIT = 1,
99 	QOF_NUMERIC_MATCH_CREDIT,
100 	QOF_NUMERIC_MATCH_ANY
101 } QofNumericMatch;
102 
103 /* Comparisons for QOF_TYPE_GUID */
104 typedef enum
105 {
106   /** These expect a single object and expect the
107    * QofAccessFunc returns GUID* */
108 	QOF_GUID_MATCH_ANY = 1,
109 	QOF_GUID_MATCH_NONE,
110 	QOF_GUID_MATCH_NULL,
111   /** These expect a GList* of objects and calls the QofAccessFunc routine
112    * on each item in the list to obtain a GUID* for each object */
113 	QOF_GUID_MATCH_ALL,
114   /** These expect a single object and expect the QofAccessFunc function
115    * to return a GList* of GUID* (the list is the property of the caller) */
116 	QOF_GUID_MATCH_LIST_ANY,
117 } QofGuidMatch;
118 
119 /** A CHAR type is for a RECNCell, Comparisons for QOF_TYPE_CHAR
120  *  'ANY' will match any charagter in the string.
121  *
122  * Match 'ANY' is a convenience/performance-enhanced predicate
123  * for the compound statement (value==char1) || (value==char2) || etc.
124  * Match 'NONE' is equivalent to
125  * (value != char1) && (value != char2) && etc.
126  */
127 typedef enum
128 {
129 	QOF_CHAR_MATCH_ANY = 1,
130 	QOF_CHAR_MATCH_NONE
131 } QofCharMatch;
132 
133 /** No extended comparisons for QOF_TYPE_INT32, QOF_TYPE_INT64,
134  *  QOF_TYPE_DOUBLE, QOF_TYPE_BOOLEAN, QOF_TYPE_KVP
135  */
136 
137 /** Head of Predicate Data structures.  All PData must start like this. */
138 struct _QofQueryPredData
139 {
140 	QofType type_name;			/* QOF_TYPE_* */
141 	QofQueryCompare how;
142 };
143 
144 
145 /** @name Core Data Type Predicates
146     @{ */
147 QofQueryPredData *
148 qof_query_string_predicate (QofQueryCompare how,
149 						    const gchar * str,
150 						    QofStringMatch options,
151 						    gboolean is_regex);
152 
153 QofQueryPredData *
154 qof_query_time_predicate (QofQueryCompare how,
155 						  QofDateMatch options,
156 						  QofTime *qt);
157 
158 QofQueryPredData *
159 qof_query_numeric_predicate (QofQueryCompare how,
160 							 QofNumericMatch options,
161 							 QofNumeric value);
162 
163 QofQueryPredData *
164 qof_query_guid_predicate (QofGuidMatch options,
165 						  GList * guids);
166 
167 QofQueryPredData *
168 qof_query_int32_predicate (QofQueryCompare how, gint32 val);
169 
170 QofQueryPredData *
171 qof_query_int64_predicate (QofQueryCompare how, gint64 val);
172 
173 QofQueryPredData *
174 qof_query_double_predicate (QofQueryCompare how,
175 							double val);
176 
177 QofQueryPredData *
178 qof_query_boolean_predicate (QofQueryCompare how,
179 							 gboolean val);
180 
181 QofQueryPredData *
182 qof_query_char_predicate (QofCharMatch options,
183 						  const gchar * chars);
184 
185 QofQueryPredData *
186 qof_query_collect_predicate (QofGuidMatch options,
187 							 QofCollection * coll);
188 
189 QofQueryPredData *
190 qof_query_choice_predicate (QofGuidMatch options,
191 							GList * guids);
192 
193 /** The qof_query_kvp_predicate() matches the object that has
194  *  the value 'value' located at the path 'path'.  In a certain
195  *  sense, the 'path' is handled as if it were a parameter.
196  */
197 QofQueryPredData *
198 qof_query_kvp_predicate (QofQueryCompare how,
199 						 GSList * path,
200 						 const KvpValue * value);
201 
202 /** Same predicate as above, except that 'path' is assumed to be
203  * a string containing slash-separated pathname. */
204 QofQueryPredData *
205 qof_query_kvp_predicate_path (QofQueryCompare how,
206 							  const gchar * path,
207 							  const KvpValue * value);
208 
209 /** Copy a predicate. */
210 QofQueryPredData *
211 qof_query_core_predicate_copy (QofQueryPredData * pdata);
212 
213 /** Destroy a predicate. */
214 void qof_query_core_predicate_free (QofQueryPredData * pdata);
215 
216 /** Retrieve a predicate. */
217 gboolean
218 qof_query_time_predicate_get_time (QofQueryPredData * pd,
219 								   QofTime * qt);
220 
221 /** Return a printable string for a core data object.  Caller needs
222  *  to g_free() the returned string.
223  */
224 gchar *
225 qof_query_core_to_string (QofType, gpointer object,
226 						  QofParam * getter);
227 
228 #endif /* QOF_QUERYCORE_H */
229 /* @} */
230 /* @} */
231