1 /* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3  *  Copyright (C) 2009-2010  Kouhei Sutou <kou@clear-code.com>
4  *
5  *  This library is free software: you can redistribute it and/or modify
6  *  it under the terms of the GNU Lesser General Public License as published by
7  *  the Free Software Foundation, either version 3 of the License, or
8  *  (at your option) any later version.
9  *
10  *  This library is distributed in the hope that it will be useful,
11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  *  GNU Lesser General Public License for more details.
14  *
15  *  You should have received a copy of the GNU Lesser General Public License
16  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
17  *
18  */
19 
20 #ifndef __GCUT_DATA_H__
21 #define __GCUT_DATA_H__
22 
23 #include <gcutter/gcut-data-helper.h>
24 
25 G_BEGIN_DECLS
26 
27 /**
28  * SECTION: gcut-data
29  * @title: Convenience test data API
30  * @short_description: API to create test data without
31  * structure definition.
32  *
33  * cut_add_data() requires custom data type for complex test
34  * data. But it's not easy to write. gcut_add_datum()
35  * provides API to use complex test data without custom data
36  * type. It uses #GType for providing complex data.
37  */
38 
39 
40 /**
41  * gcut_add_datum:
42  * @name: the name of the data.
43  * @first_field_name: the first field name.
44  * @...: the type and value pair of the first field,
45  *       followed optionally by the next field name, type
46  *       and value triples. %NULL-terminated. See
47  *       description for more details.
48  *
49  * Adds a datum to be used in data driven test. It's
50  * convenient rather than cut_add_data() because you doesn't
51  * need to define a new structure for a complex test data.
52  *
53  * e.g.:
54  * |[
55  * #include <gcutter.h>
56  *
57  * void data_translate (void);
58  * void test_translate (gconstpointer data);
59  *
60  * static const gchar*
61  * translate (gint input)
62  * {
63  *    switch(input) {
64  *    case 1:
65  *        return "first";
66  *    case 111:
67  *        return "a hundred eleven";
68  *    default:
69  *        return "unsupported";
70  *    }
71  * }
72  *
73  * void
74  * data_translate(void)
75  * {
76  *     gcut_add_datum("simple data",
77  *                    "translated", G_TYPE_STRING, "first",
78  *                    "input", G_TYPE_INT, 1,
79  *                    NULL);
80  *     gcut_add_datum("complex data",
81  *                    "translated", G_TYPE_STRING, "a hundred eleven",
82  *                    "input", G_TYPE_INT, 111,
83  *                    NULL);
84  * }
85  *
86  * void
87  * test_translate(gconstpointer data)
88  * {
89  *     cut_assert_equal_string(gcut_data_get_string(data, "translated"),
90  *                             translate(gcut_data_get_int(data, "input")));
91  * }
92  * ]|
93  *
94  * Available types and their values are the followings:
95  *
96  * <variablelist>
97  *   <varlistentry>
98  *     <term>#G_TYPE_CHAR</term>
99  *     <listitem>
100  *       <para>#gchar value</para>
101  *       <para>e.g.:
102  * |[
103  * gcut_add_datum("data name",
104  *                "field-name", G_TYPE_CHAR, 'X',
105  *                NULL);
106  * ]|
107  *       </para>
108  *     </listitem>
109  *   </varlistentry>
110  *   <varlistentry>
111  *     <term>#G_TYPE_STRING</term>
112  *     <listitem>
113  *       <para>const #gchar *value</para>
114  *       <para>e.g.:
115  * |[
116  * gcut_add_datum("data name",
117  *                "field-name", G_TYPE_STRING, "string value",
118  *                NULL);
119  * ]|
120  *       </para>
121  *     </listitem>
122  *   </varlistentry>
123  *   <varlistentry>
124  *     <term>#G_TYPE_INT</term>
125  *     <listitem>
126  *       <para>#gint value</para>
127  *       <para>e.g.:
128  * |[
129  * gcut_add_datum("data name",
130  *                "field-name", G_TYPE_INT, 100,
131  *                NULL);
132  * ]|
133  *       </para>
134  *     </listitem>
135  *   </varlistentry>
136  *   <varlistentry>
137  *     <term>#G_TYPE_UINT</term>
138  *     <listitem>
139  *       <para>#guint value</para>
140  *       <para>e.g.:
141  * |[
142  * gcut_add_datum("data name",
143  *                "field-name", G_TYPE_UINT, 100,
144  *                NULL);
145  * ]|
146  *       </para>
147  *     </listitem>
148  *   </varlistentry>
149  *   <varlistentry>
150  *     <term>#G_TYPE_INT64</term>
151  *     <listitem>
152  *       <para>#gint64 value</para>
153  *       <para>e.g.:
154  * |[
155  * gcut_add_datum("data name",
156  *                "field-name", G_TYPE_INT64, G_GINT64_CONSTANT(100),
157  *                NULL);
158  * ]|
159  *       </para>
160  *     </listitem>
161  *   </varlistentry>
162  *   <varlistentry>
163  *     <term>#G_TYPE_UINT64</term>
164  *     <listitem>
165  *       <para>#guint64 value</para>
166  *       <para>e.g.:
167  * |[
168  * gcut_add_datum("data name",
169  *                "field-name", G_TYPE_UINT64, G_GUINT64_CONSTANT(100),
170  *                NULL);
171  * ]|
172  *       </para>
173  *     </listitem>
174  *   </varlistentry>
175  *   <varlistentry>
176  *     <term>#G_TYPE_GTYPE</term>
177  *     <listitem>
178  *       <para>#GType value</para>
179  *       <para>e.g.:
180  * |[
181  * gcut_add_datum("data name",
182  *                "field-name", G_TYPE_GTYPE, G_TYPE_OBJECT,
183  *                NULL);
184  * ]|
185  *       </para>
186  *     </listitem>
187  *   </varlistentry>
188  *   <varlistentry>
189  *     <term>GFlags types</term>
190  *     <listitem>
191  *       <para>its type value.</para>
192  *       <para>e.g.:
193  * |[
194  * gcut_add_datum("data name",
195  *                "field-name", GTK_TYPE_WIDGET_FLAGS, GTK_TOPLEVEL | GTK_MAPPED,
196  *                NULL);
197  * ]|
198  *       </para>
199  *     </listitem>
200  *   </varlistentry>
201  *   <varlistentry>
202  *     <term>GEnum types</term>
203  *     <listitem>
204  *       <para>its type value.</para>
205  *       <para>e.g.:
206  * |[
207  * gcut_add_datum("data name",
208  *                "field-name", GTK_TYPE_WRAP_MODE, GTK_WRAP_NONE,
209  *                NULL);
210  * ]|
211  *       </para>
212  *     </listitem>
213  *   </varlistentry>
214  *   <varlistentry>
215  *     <term>#G_TYPE_POINTER</term>
216  *     <listitem>
217  *       <para>#gconstpointer value, #GDestroyNotify notify</para>
218  *       <para>notify is called when value is destroyed.</para>
219  *       <para>e.g.:
220  * |[
221  * gcut_add_datum("data name",
222  *                "field-name", G_TYPE_POINTER, my_structure_new(...), my_structure_free,
223  *                NULL);
224  * ]|
225  *       </para>
226  *       <para>NOTE: value's ownership is passed to Cutter. Don't free it.</para>
227  *     </listitem>
228  *   </varlistentry>
229  *   <varlistentry>
230  *     <term>GBoxed types</term>
231  *     <listitem>
232  *       <para>its type value.</para>
233  *       <para>e.g.:
234  * |[
235  * gcut_add_datum("data name",
236  *                "field-name", G_TYPE_HASH_TABLE,
237  *                gcut_hash_table_string_string_new("name1", "value1",
238  *                                                  "name2", "value2",
239  *                                                  NULL),
240  *                NULL);
241  * ]|
242  *       </para>
243  *       <para>NOTE: value's ownership is passed to Cutter. Don't free it.</para>
244  *     </listitem>
245  *   </varlistentry>
246  *   <varlistentry>
247  *     <term>#G_TYPE_BOOLEAN</term>
248  *     <listitem>
249  *       <para>#gboolean value</para>
250  *       <para>e.g.:
251  * |[
252  * gcut_add_datum("data name",
253  *                "field-name", G_TYPE_BOOLEAN, TRUE,
254  *                NULL);
255  * ]|
256  *       </para>
257  *     </listitem>
258  *   </varlistentry>
259  *   <varlistentry>
260  *     <term>#G_TYPE_DOUBLE</term>
261  *     <listitem>
262  *       <para>#gdouble value</para>
263  *       <para>e.g.:
264  * |[
265  * gcut_add_datum("data name",
266  *                "field-name", G_TYPE_DOUBLE, 2.9,
267  *                NULL);
268  * ]|
269  *       </para>
270  *     </listitem>
271  *   </varlistentry>
272  * </variablelist>
273  *
274  * Since: 1.0.6
275  */
276 #define gcut_add_datum(name, first_field_name, ...)             \
277     cut_test_context_add_data(                                  \
278         cut_get_current_test_context(),                         \
279         name,                                                   \
280         gcut_dynamic_data_new(first_field_name, __VA_ARGS__),   \
281         g_object_unref,                                         \
282         NULL)
283 
284 /**
285  * gcut_data_has_field:
286  * @data: the data added by gcut_add_datum().
287  * @field_name: the field name.
288  *
289  * Returns: %TRUE if @data has a @field_name field is
290  *          available, %FALSE otherwise.
291  *
292  * Since: 1.1.5
293  */
294 #define gcut_data_has_field(data, field_name)                          \
295     gcut_dynamic_data_has_field(data, field_name)
296 
297 /**
298  * gcut_data_get_char:
299  * @data: the data added by gcut_add_datum().
300  * @field_name: the field name.
301  *
302  * Gets a field value identified by @field_name as char.
303  *
304  * Returns: a field value corresponded to @field_name.
305  *
306  * Since: 1.1.3
307  */
308 #define gcut_data_get_char(data, field_name)                          \
309     gcut_data_get_char_helper(                                        \
310         data, field_name,                                             \
311         (cut_push_backtrace(gcut_data_get_char(data, field_name)),    \
312          cut_pop_backtrace))
313 
314 /**
315  * gcut_data_get_string:
316  * @data: the data added by gcut_add_datum().
317  * @field_name: the field name.
318  *
319  * Gets a field value identified by @field_name as string.
320  *
321  * Returns: a field value corresponded to @field_name.
322  *
323  * Since: 1.0.6
324  */
325 #define gcut_data_get_string(data, field_name)                          \
326     gcut_data_get_string_helper(                                        \
327         data, field_name,                                               \
328         (cut_push_backtrace(gcut_data_get_string(data, field_name)),    \
329          cut_pop_backtrace))
330 
331 /**
332  * gcut_data_get_int:
333  * @data: the data added by gcut_add_datum().
334  * @field_name: the field name.
335  *
336  * Gets a field value identified by @field_name as integer.
337  *
338  * Returns: a field value corresponded to @field_name.
339  *
340  * Since: 1.0.6
341  */
342 #define gcut_data_get_int(data, field_name)                             \
343     gcut_data_get_int_helper(                                           \
344         data, field_name,                                               \
345         (cut_push_backtrace(gcut_data_get_int(data, field_name)),       \
346          cut_pop_backtrace))
347 
348 /**
349  * gcut_data_get_uint:
350  * @data: the data added by gcut_add_datum().
351  * @field_name: the field name.
352  *
353  * Gets a field value identified by @field_name as
354  * unsigned integer.
355  *
356  * Returns: a field value corresponded to @field_name.
357  *
358  * Since: 1.0.6
359  */
360 #define gcut_data_get_uint(data, field_name)                            \
361     gcut_data_get_uint_helper(                                          \
362         data, field_name,                                               \
363         (cut_push_backtrace(gcut_data_get_uint(data, field_name)),      \
364          cut_pop_backtrace))
365 
366 /**
367  * gcut_data_get_int64:
368  * @data: the data added by gcut_add_datum().
369  * @field_name: the field name.
370  *
371  * Gets a field value identified by @field_name as 64-bit
372  * integer.
373  *
374  * Returns: a field value corresponded to @field_name.
375  *
376  * Since: 1.1.3
377  */
378 #define gcut_data_get_int64(data, field_name)                           \
379     gcut_data_get_int64_helper(                                         \
380         data, field_name,                                               \
381         (cut_push_backtrace(gcut_data_get_int64(data, field_name)),     \
382          cut_pop_backtrace))
383 
384 /**
385  * gcut_data_get_uint64:
386  * @data: the data added by gcut_add_datum().
387  * @field_name: the field name.
388  *
389  * Gets a field value identified by @field_name as
390  * 64-bit unsigned integer.
391  *
392  * Returns: a field value corresponded to @field_name.
393  *
394  * Since: 1.1.3
395  */
396 #define gcut_data_get_uint64(data, field_name)                          \
397     gcut_data_get_uint64_helper(                                        \
398         data, field_name,                                               \
399         (cut_push_backtrace(gcut_data_get_uint64(data, field_name)),    \
400          cut_pop_backtrace))
401 
402 /**
403  * gcut_data_get_size:
404  * @data: the data added by gcut_add_datum().
405  * @field_name: the field name.
406  *
407  * Gets a field value identified by @field_name as size_t.
408  *
409  * Returns: a field value corresponded to @field_name.
410  *
411  * Since: 1.1.3
412  */
413 #define gcut_data_get_size(data, field_name)                            \
414     gcut_data_get_size_helper(                                          \
415         data, field_name,                                               \
416         (cut_push_backtrace(gcut_data_get_size(data, field_name)),      \
417          cut_pop_backtrace))
418 
419 /**
420  * gcut_data_get_type:
421  * @data: the data added by gcut_add_datum().
422  * @field_name: the field name.
423  *
424  * Gets a field value identified by @field_name as #GType.
425  *
426  * Returns: a field value corresponded to @field_name.
427  *
428  * Since: 1.0.6
429  */
430 #define gcut_data_get_type(data, field_name)                            \
431     gcut_data_get_type_helper(                                          \
432         data, field_name,                                               \
433         (cut_push_backtrace(gcut_data_get_type(data, field_name)),      \
434          cut_pop_backtrace))
435 
436 /**
437  * gcut_data_get_flags:
438  * @data: the data added by gcut_add_datum().
439  * @field_name: the field name.
440  *
441  * Gets a field value identified by @field_name as
442  * unsigned integer of GFlags.
443  *
444  * Returns: a field value corresponded to @field_name.
445  *
446  * Since: 1.0.6
447  */
448 #define gcut_data_get_flags(data, field_name)                           \
449     gcut_data_get_flags_helper(                                         \
450         data, field_name,                                               \
451         (cut_push_backtrace(gcut_data_get_flags(data, field_name)),     \
452          cut_pop_backtrace))
453 
454 /**
455  * gcut_data_get_enum:
456  * @data: the data added by gcut_add_datum().
457  * @field_name: the field name.
458  *
459  * Gets a field value identified by @field_name as
460  * integer of GEnum type.
461  *
462  * Returns: a field value corresponded to @field_name.
463  *
464  * Since: 1.0.6
465  */
466 #define gcut_data_get_enum(data, field_name)                            \
467     gcut_data_get_enum_helper(                                          \
468         data, field_name,                                               \
469         (cut_push_backtrace(gcut_data_get_enum(data, field_name)),      \
470          cut_pop_backtrace))
471 
472 /**
473  * gcut_data_get_pointer:
474  * @data: the data added by gcut_add_datum().
475  * @field_name: the field name.
476  *
477  * Gets a field value identified by @field_name as
478  * pointer.
479  *
480  * Returns: a field value corresponded to @field_name.
481  *
482  * Since: 1.0.6
483  */
484 #define gcut_data_get_pointer(data, field_name)                         \
485     gcut_data_get_pointer_helper(                                       \
486         data, field_name,                                               \
487         (cut_push_backtrace(gcut_data_get_pointer(data, field_name)),   \
488          cut_pop_backtrace))
489 
490 /**
491  * gcut_data_get_boxed:
492  * @data: the data added by gcut_add_datum().
493  * @field_name: the field name.
494  *
495  * Gets a field value identified by @field_name as
496  * GBoxed type value.
497  *
498  * Returns: a field value corresponded to @field_name.
499  *
500  * Since: 1.0.7
501  */
502 #define gcut_data_get_boxed(data, field_name)                           \
503     gcut_data_get_boxed_helper(                                         \
504         data, field_name,                                               \
505         (cut_push_backtrace(gcut_data_get_boxed(data, field_name)),     \
506          cut_pop_backtrace))
507 
508 /**
509  * gcut_data_get_object:
510  * @data: the data added by gcut_add_datum().
511  * @field_name: the field name.
512  *
513  * Gets a field value identified by @field_name as
514  * #GObject type value.
515  *
516  * Returns: a field value corresponded to @field_name.
517  *
518  * Since: 1.1.1
519  */
520 #define gcut_data_get_object(data, field_name)                          \
521     gcut_data_get_object_helper(                                        \
522         data, field_name,                                               \
523         (cut_push_backtrace(gcut_data_get_object(data, field_name)),    \
524          cut_pop_backtrace))
525 
526 /**
527  * gcut_data_get_boolean:
528  * @data: the data added by gcut_add_datum().
529  * @field_name: the field name.
530  *
531  * Gets a field value identified by @field_name as boolean.
532  *
533  * Returns: a field value corresponded to @field_name.
534  *
535  * Since: 1.1.3
536  */
537 #define gcut_data_get_boolean(data, field_name)                         \
538     gcut_data_get_boolean_helper(                                       \
539         data, field_name,                                               \
540         (cut_push_backtrace(gcut_data_get_boolean(data, field_name)),   \
541          cut_pop_backtrace))
542 
543 /**
544  * gcut_data_get_double:
545  * @data: the data added by gcut_add_datum().
546  * @field_name: the field name.
547  *
548  * Gets a field value identified by @field_name as double
549  * floating point number.
550  *
551  * Returns: a field value corresponded to @field_name.
552  *
553  * Since: 1.1.3
554  */
555 #define gcut_data_get_double(data, field_name)                         \
556     gcut_data_get_double_helper(                                       \
557         data, field_name,                                              \
558         (cut_push_backtrace(gcut_data_get_double(data, field_name)),   \
559          cut_pop_backtrace))
560 
561 G_END_DECLS
562 
563 #endif /* __GCUT_DATA_H__ */
564 
565 /*
566 vi:nowrap:ai:expandtab:sw=4:ts=4
567 */
568