Change return type of gedcom_init to int.
[gedcom-parse.git] / include / gedcom.h.in
1 /* External header for the Gedcom parser library.
2    Copyright (C) 2001,2002 The Genes Development Team
3    This file is part of the Gedcom parser library.
4    Contributed by Peter Verthez <Peter.Verthez@advalvas.be>, 2001.
5
6    The Gedcom parser library is free software; you can redistribute it
7    and/or modify it under the terms of the GNU Lesser General Public
8    License as published by the Free Software Foundation; either
9    version 2.1 of the License, or (at your option) any later version.
10
11    The Gedcom parser library is distributed in the hope that it will be
12    useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14    Lesser General Public License for more details.
15
16    You should have received a copy of the GNU Lesser General Public
17    License along with the Gedcom parser library; if not, write to the
18    Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
19    02111-1307 USA.  */
20
21 /* $Id$ */
22 /* $Name$ */
23
24 #ifndef __GEDCOM_H
25 #define __GEDCOM_H
26
27 #include <stdio.h>
28 #include <stdarg.h>
29
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33
34 #ifndef GEDCOM_INTERNAL
35 #include <gedcom-tags.h>
36 #endif
37
38 #define GEDCOM_PARSE_VERSION_MAJOR @VERSION_MAJOR@
39 #define GEDCOM_PARSE_VERSION_MINOR @VERSION_MINOR@
40 #define GEDCOM_PARSE_VERSION_PATCH 0
41 #define GEDCOM_PARSE_VERSION \
42   (GEDCOM_PARSE_VERSION_MAJOR * 1000 + GEDCOM_PARSE_VERSION_MINOR)
43
44 int gedcom_check_version(int major, int minor, int patch);
45
46 /**************************************************************************/
47 /***  First the records and elements to subscribe upon                  ***/
48 /**************************************************************************/
49                                                                            
50 typedef enum _REC {
51   REC_HEAD,
52   REC_FAM,
53   REC_INDI,
54   REC_OBJE,
55   REC_NOTE,
56   REC_REPO,
57   REC_SOUR,
58   REC_SUBN,
59   REC_SUBM,
60   REC_USER,
61   NR_OF_RECS     /* Just a final value to be used in array boundaries */
62 } Gedcom_rec;
63
64 typedef enum _ELT {
65   ELT_HEAD_SOUR = NR_OF_RECS + 1,
66   ELT_HEAD_SOUR_VERS,
67   ELT_HEAD_SOUR_NAME,
68   ELT_HEAD_SOUR_CORP,
69   ELT_HEAD_SOUR_DATA,
70   ELT_HEAD_SOUR_DATA_DATE,
71   ELT_HEAD_SOUR_DATA_COPR,
72   ELT_HEAD_DEST,
73   ELT_HEAD_DATE,
74   ELT_HEAD_DATE_TIME,
75   ELT_HEAD_SUBM,
76   ELT_HEAD_SUBN,
77   ELT_HEAD_FILE,
78   ELT_HEAD_COPR,
79   ELT_HEAD_GEDC,
80   ELT_HEAD_GEDC_VERS,
81   ELT_HEAD_GEDC_FORM,
82   ELT_HEAD_CHAR,
83   ELT_HEAD_CHAR_VERS,
84   ELT_HEAD_LANG,
85   ELT_HEAD_PLAC,
86   ELT_HEAD_PLAC_FORM,
87   ELT_HEAD_NOTE,
88   
89   ELT_FAM_HUSB,
90   ELT_FAM_WIFE,
91   ELT_FAM_CHIL,
92   ELT_FAM_NCHI,
93   ELT_FAM_SUBM,
94   
95   ELT_INDI_RESN,
96   ELT_INDI_SEX,
97   ELT_INDI_SUBM,
98   ELT_INDI_ALIA,
99   ELT_INDI_ANCI,
100   ELT_INDI_DESI,
101   ELT_INDI_RFN,
102   ELT_INDI_AFN,
103   
104   ELT_OBJE_FORM,
105   ELT_OBJE_TITL,
106   ELT_OBJE_BLOB,
107   ELT_OBJE_BLOB_CONT,
108   ELT_OBJE_OBJE,
109   
110   ELT_REPO_NAME,
111
112   ELT_SOUR_DATA,
113   ELT_SOUR_DATA_EVEN,
114   ELT_SOUR_DATA_EVEN_DATE,
115   ELT_SOUR_DATA_EVEN_PLAC,
116   ELT_SOUR_DATA_AGNC,
117   ELT_SOUR_AUTH,
118   ELT_SOUR_TITL,
119   ELT_SOUR_ABBR,
120   ELT_SOUR_PUBL,
121   ELT_SOUR_TEXT,
122
123   ELT_SUBN_SUBM,
124   ELT_SUBN_FAMF,
125   ELT_SUBN_TEMP,
126   ELT_SUBN_ANCE,
127   ELT_SUBN_DESC,
128   ELT_SUBN_ORDI,
129   ELT_SUBN_RIN,
130
131   ELT_SUBM_NAME,
132   ELT_SUBM_LANG,
133   ELT_SUBM_RFN,
134   ELT_SUBM_RIN,
135
136   ELT_SUB_ADDR,
137   ELT_SUB_ADDR_CONT,
138   ELT_SUB_ADDR_ADR1,
139   ELT_SUB_ADDR_ADR2,
140   ELT_SUB_ADDR_CITY,
141   ELT_SUB_ADDR_STAE,
142   ELT_SUB_ADDR_POST,
143   ELT_SUB_ADDR_CTRY,
144   
145   ELT_SUB_PHON,
146
147   ELT_SUB_ASSO,
148   ELT_SUB_ASSO_TYPE,
149   ELT_SUB_ASSO_RELA,
150
151   ELT_SUB_CHAN,
152   ELT_SUB_CHAN_DATE,
153   ELT_SUB_CHAN_TIME,
154
155   ELT_SUB_FAMC,
156   ELT_SUB_FAMC_PEDI,
157
158   ELT_SUB_CONT,
159   ELT_SUB_CONC,
160
161   ELT_SUB_EVT_TYPE,
162   ELT_SUB_EVT_DATE,
163   ELT_SUB_EVT_AGE,
164   ELT_SUB_EVT_AGNC,
165   ELT_SUB_EVT_CAUS,
166
167   ELT_SUB_FAM_EVT,
168   ELT_SUB_FAM_EVT_HUSB,
169   ELT_SUB_FAM_EVT_WIFE,
170   ELT_SUB_FAM_EVT_AGE,
171   ELT_SUB_FAM_EVT_EVEN,
172
173   ELT_SUB_IDENT_REFN,
174   ELT_SUB_IDENT_REFN_TYPE,
175   ELT_SUB_IDENT_RIN,
176
177   ELT_SUB_INDIV_ATTR,
178   ELT_SUB_INDIV_RESI,
179   ELT_SUB_INDIV_BIRT,
180   ELT_SUB_INDIV_BIRT_FAMC,
181   ELT_SUB_INDIV_GEN,
182   ELT_SUB_INDIV_ADOP,
183   ELT_SUB_INDIV_ADOP_FAMC,
184   ELT_SUB_INDIV_ADOP_FAMC_ADOP,
185   ELT_SUB_INDIV_EVEN,
186
187   ELT_SUB_LIO_BAPL,
188   ELT_SUB_LIO_BAPL_STAT,
189   ELT_SUB_LIO_BAPL_DATE,
190   ELT_SUB_LIO_BAPL_TEMP,
191   ELT_SUB_LIO_BAPL_PLAC,
192   ELT_SUB_LIO_SLGC,
193   ELT_SUB_LIO_SLGC_FAMC,
194
195   ELT_SUB_LSS_SLGS,
196   ELT_SUB_LSS_SLGS_STAT,
197   ELT_SUB_LSS_SLGS_DATE,
198   ELT_SUB_LSS_SLGS_TEMP,
199   ELT_SUB_LSS_SLGS_PLAC,
200
201   ELT_SUB_MULTIM_OBJE,
202   ELT_SUB_MULTIM_OBJE_FORM,
203   ELT_SUB_MULTIM_OBJE_TITL,
204   ELT_SUB_MULTIM_OBJE_FILE,
205
206   ELT_SUB_NOTE,
207
208   ELT_SUB_PERS_NAME,
209   ELT_SUB_PERS_NAME_NPFX,
210   ELT_SUB_PERS_NAME_GIVN,
211   ELT_SUB_PERS_NAME_NICK,
212   ELT_SUB_PERS_NAME_SPFX,
213   ELT_SUB_PERS_NAME_SURN,
214   ELT_SUB_PERS_NAME_NSFX,
215
216   ELT_SUB_PLAC,
217   ELT_SUB_PLAC_FORM,
218
219   ELT_SUB_SOUR,
220   ELT_SUB_SOUR_PAGE,
221   ELT_SUB_SOUR_EVEN,
222   ELT_SUB_SOUR_EVEN_ROLE,
223   ELT_SUB_SOUR_DATA,
224   ELT_SUB_SOUR_DATA_DATE,
225   ELT_SUB_SOUR_TEXT,
226   ELT_SUB_SOUR_QUAY,
227
228   ELT_SUB_REPO,
229   ELT_SUB_REPO_CALN,
230   ELT_SUB_REPO_CALN_MEDI,
231
232   ELT_SUB_FAMS,
233   
234   ELT_USER,
235   
236   NR_OF_ELTS     /* Just a final value to be used in array boundaries */
237 } Gedcom_elt;
238
239 /**************************************************************************/
240 /***  Definition of some auxiliary types                                ***/
241 /**************************************************************************/
242                                                                            
243 typedef enum _MECH {
244   IMMED_FAIL,
245   DEFER_FAIL,
246   IGNORE_ERRORS
247 } Gedcom_err_mech;
248
249 typedef enum _MSG {
250   ERROR,
251   WARNING,
252   MESSAGE
253 } Gedcom_msg_type;
254
255 typedef enum _DATE_TYPE {
256   DATE_UNRECOGNIZED,   /* Neither jday1 as jday2 are significant */
257   DATE_EXACT,          /* Only jday1 is significant */
258   DATE_BOUNDED         /* Both jday1 and jday2 are significant */
259 } Date_type;
260
261 typedef enum _CALENDAR_TYPE {
262   CAL_GREGORIAN,
263   CAL_JULIAN,
264   CAL_HEBREW,
265   CAL_FRENCH_REV,
266   CAL_UNKNOWN
267 } Calendar_type;
268
269 typedef enum _YEAR_TYPE {
270   YEAR_SINGLE,
271   YEAR_DOUBLE     /* In this case, the 'year' indicates the last value */
272 } Year_type;
273
274 typedef enum _DATE_VAL_MOD {
275   /* Simple date */
276   DV_NO_MODIFIER,
277   /* Range values */
278   DV_BEFORE,
279   DV_AFTER,
280   DV_BETWEEN,       /* Two dates are given */
281   /* Period values */
282   DV_FROM,
283   DV_TO,
284   DV_FROM_TO,       /* Two dates are given */
285   /* Approx values */
286   DV_ABOUT,
287   DV_CALCULATED,
288   DV_ESTIMATED,
289   /* Other */
290   DV_INTERPRETED,   /* One date and a phrase is given */
291   DV_PHRASE         /* Only phrase is given */
292 } Date_value_type;
293
294 /* All Unicode characters between U+0000 and U+FFFF can be encoded in
295    UTF-8 with 3 or less bytes */
296 #define UTF_FACTOR 3
297
298 #define MAX_DAY_LEN    2
299 #define MAX_MONTH_LEN  4
300 #define MAX_YEAR_LEN   7
301 #define MAX_PHRASE_LEN 35 * UTF_FACTOR
302
303 struct date {
304   Calendar_type cal;
305   char day_str[MAX_DAY_LEN + 1];
306   char month_str[MAX_MONTH_LEN + 1];
307   char year_str[MAX_YEAR_LEN + 1];
308   int day;    /* starts at 1 */
309   int month;  /* starts at 1 */
310   int year;   /* the highest value for double years */
311   Year_type year_type;
312   Date_type type;
313   long int sdn1;
314   long int sdn2;
315 };
316
317 struct date_value {
318   Date_value_type type;
319   struct date date1;
320   struct date date2;
321   char phrase[MAX_PHRASE_LEN + 1];
322 };
323
324 /* Type for context handling, meant to be opaque */
325 typedef void* Gedcom_ctxt;
326
327 typedef enum _XREF_TYPE {
328   XREF_NONE,
329   XREF_FAM,
330   XREF_INDI,
331   XREF_NOTE,
332   XREF_OBJE,
333   XREF_REPO,
334   XREF_SOUR,
335   XREF_SUBM,
336   XREF_SUBN,
337   XREF_USER,
338   XREF_ANY
339 } Xref_type;
340
341 struct xref_value {
342   Xref_type type;
343   char *string;
344   Gedcom_ctxt object;
345 };
346
347 typedef enum _AGE_TYPE {
348   AGE_UNRECOGNIZED,
349   AGE_CHILD,
350   AGE_INFANT,
351   AGE_STILLBORN,
352   AGE_NUMERIC
353 } Age_type;
354
355 typedef enum _AGE_MODIFIER {
356   AGE_NO_MODIFIER,
357   AGE_LESS_THAN,
358   AGE_GREATER_THAN
359 } Age_modifier;
360
361 struct age_value {
362   Age_type type;
363   Age_modifier mod;
364   int years;
365   int months;
366   int days;
367   char phrase[MAX_PHRASE_LEN + 1];
368 };
369
370 /**************************************************************************/
371 /***  Things meant to be internal, susceptible to changes               ***/
372 /***  Use the GEDCOM_STRING/GEDCOM_DATE interface instead of relying    ***/
373 /***  on this !!                                                        ***/
374 /**************************************************************************/
375                                                                            
376 typedef enum _GEDCOM_VAL_TYPE {
377   GV_NULL,
378   GV_CHAR_PTR,
379   GV_DATE_VALUE,
380   GV_AGE_VALUE,
381   GV_XREF_PTR
382 } Gedcom_val_type;
383
384 union _Gedcom_val_union {
385   char* string_val;
386   struct date_value date_val;
387   struct age_value age_val;
388   struct xref_value *xref_val;
389 };
390
391 typedef struct _Gedcom_val_struct {
392   Gedcom_val_type type;
393   union _Gedcom_val_union value;
394 } Gedcom_val_struct;
395
396 void gedcom_cast_error(const char* file, int line,
397                        Gedcom_val_type tried_type,
398                        Gedcom_val_type real_type);
399
400 extern struct date_value def_date_val;
401 extern struct age_value  def_age_val;
402 extern struct xref_value def_xref_val;
403
404 #define GV_CHECK_CAST(VAL, TYPE, MEMBER, DEFVAL)                              \
405    ((VAL->type == TYPE) ?                                                     \
406     VAL->value.MEMBER :                                                       \
407     (gedcom_cast_error(__FILE__,__LINE__, TYPE, VAL->type), DEFVAL))
408
409 #define GV_IS_TYPE(VAL, TYPE)                                                 \
410    (VAL->type == TYPE)
411
412 /**************************************************************************/
413 /***  Function interface                                                ***/
414 /**************************************************************************/
415
416 /* Type for parsed values, meant to be opaque */
417 typedef Gedcom_val_struct* Gedcom_val;
418
419 /* Check to determine whether there is a parsed value or not */
420 #define GEDCOM_IS_NULL(VAL) \
421    GV_IS_TYPE(VAL, GV_NULL)
422
423 /* This returns the char* from a Gedcom_val, if appropriate */
424 /* It gives a gedcom_warning if the cast is not correct     */
425 #define GEDCOM_STRING(VAL) \
426    GV_CHECK_CAST(VAL, GV_CHAR_PTR, string_val, "<error>")
427 #define GEDCOM_IS_STRING(VAL) \
428    GV_IS_TYPE(VAL, GV_CHAR_PTR)
429
430 /* This returns the struct date_value from a Gedcom_val, if appropriate */
431 /* It gives a gedcom_warning if the cast is not correct                 */
432 #define GEDCOM_DATE(VAL) \
433    GV_CHECK_CAST(VAL, GV_DATE_VALUE, date_val, def_date_val)
434 #define GEDCOM_IS_DATE(VAL) \
435    GV_IS_TYPE(VAL, GV_DATE_VALUE)
436
437 /* This returns the struct age_value from a Gedcom_val, if appropriate  */
438 /* It gives a gedcom_warning if the cast is not correct                 */
439 #define GEDCOM_AGE(VAL) \
440    GV_CHECK_CAST(VAL, GV_AGE_VALUE, age_val, def_age_val)
441 #define GEDCOM_IS_AGE(VAL) \
442    GV_IS_TYPE(VAL, GV_AGE_VALUE)
443
444 /* This returns the (struct xref_value *) from a Gedcom_val, if appropriate */
445 /* It gives a gedcom_warning if the cast is not correct                     */
446 #define GEDCOM_XREF_PTR(VAL) \
447    GV_CHECK_CAST(VAL, GV_XREF_PTR, xref_val, &def_xref_val)
448 #define GEDCOM_IS_XREF_PTR(VAL) \
449    GV_IS_TYPE(VAL, GV_XREF_PTR)
450
451 typedef void
452         (*Gedcom_msg_handler)
453         (Gedcom_msg_type type, char *msg);
454
455 typedef Gedcom_ctxt
456         (*Gedcom_rec_start_cb)
457         (Gedcom_rec rec, int level, Gedcom_val xref, char *tag,
458          char *raw_value, int tag_value, Gedcom_val parsed_value);
459 typedef void
460         (*Gedcom_rec_end_cb)
461         (Gedcom_rec rec, Gedcom_ctxt self);
462
463 typedef Gedcom_ctxt
464         (*Gedcom_elt_start_cb)
465         (Gedcom_elt elt, Gedcom_ctxt parent,
466          int level, char *tag, char *raw_value,
467          int tag_value, Gedcom_val parsed_value);
468 typedef void
469         (*Gedcom_elt_end_cb)
470         (Gedcom_elt elt, Gedcom_ctxt parent, Gedcom_ctxt self,
471          Gedcom_val parsed_value);
472
473 typedef void
474         (*Gedcom_def_cb)
475         (Gedcom_elt elt, Gedcom_ctxt parent, int level, char *tag,
476          char *raw_value, int tag_value);
477
478 int     gedcom_init();
479 int     gedcom_parse_file(const char* file_name);
480 int     gedcom_new_model();
481 void    gedcom_set_debug_level(int level, FILE* trace_output);
482 void    gedcom_set_error_handling(Gedcom_err_mech mechanism);
483 void    gedcom_set_compat_handling(int enable_compat);
484 void    gedcom_set_message_handler(Gedcom_msg_handler func);
485 void    gedcom_set_default_callback(Gedcom_def_cb func);
486
487 void    gedcom_subscribe_to_record(Gedcom_rec rec,
488                                    Gedcom_rec_start_cb cb_start,
489                                    Gedcom_rec_end_cb cb_end);
490 void    gedcom_subscribe_to_element(Gedcom_elt elt,
491                                     Gedcom_elt_start_cb cb_start,
492                                     Gedcom_elt_end_cb cb_end);
493
494 /* Separate value parsing functions */
495 struct date_value gedcom_parse_date(const char* line_value);
496 struct age_value  gedcom_parse_age(const char* line_value);
497
498 /* Handling cross-references */
499 struct xref_value *gedcom_get_by_xref(const char *key);
500 struct xref_value *gedcom_add_xref(Xref_type type, const char* xrefstr,
501                                    Gedcom_ctxt object);
502 struct xref_value *gedcom_link_xref(Xref_type type, const char* xrefstr);
503 struct xref_value *gedcom_unlink_xref(Xref_type type, const char* xrefstr);
504 int                gedcom_delete_xref(const char* xrefstr);
505
506 /* For use in gom */
507 int        gedcom_error(const char* s, ...);
508 int        gedcom_warning(const char* s, ...);
509 int        gedcom_message(const char* s, ...);
510 int        gedcom_debug_print(const char* s, ...);
511
512 #ifdef __cplusplus
513 }
514 #endif
515
516 #endif /* __GEDCOM_H */