Allow elements out of context.
[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 @VERSION_PATCH@
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,
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 typedef enum _ENC {
371   ONE_BYTE      = 0x00,
372   TWO_BYTE_HILO = 0x01,
373   TWO_BYTE_LOHI = 0x02
374 } Encoding;
375
376 typedef enum _ENC_BOM {
377   WITHOUT_BOM = 0x00,
378   WITH_BOM    = 0x10
379 } Enc_bom;
380
381 typedef enum _ENC_LINE_END {
382   END_CR    = 0,
383   END_LF    = 1,
384   END_CR_LF = 2,
385   END_LF_CR = 3
386 } Enc_line_end;
387
388 typedef enum _ENC_FROM {
389   ENC_FROM_FILE = 0,
390   ENC_FROM_SYS  = 1,
391   ENC_MANUAL    = 2
392 } Enc_from;
393
394 struct encoding_state;
395
396 typedef enum _DATE_INPUT {
397   DI_FROM_STRINGS,
398   DI_FROM_NUMBERS,
399   DI_FROM_SDN
400 } Date_input;
401
402 typedef enum _COMPAT_OPTIONS {
403   COMPAT_ALLOW_OUT_OF_CONTEXT = 0x01
404 } Gedcom_compat;
405
406 /**************************************************************************/
407 /***  Things meant to be internal, susceptible to changes               ***/
408 /***  Use the GEDCOM_STRING/GEDCOM_DATE interface instead of relying    ***/
409 /***  on this !!                                                        ***/
410 /**************************************************************************/
411
412 /* Update strings in interface.c if this changes */
413 typedef enum _GEDCOM_VAL_TYPE {
414   GV_NULL       = 0x01,
415   GV_CHAR_PTR   = 0x02,
416   GV_DATE_VALUE = 0x04,
417   GV_AGE_VALUE  = 0x08,
418   GV_XREF_PTR   = 0x10
419 } Gedcom_val_type;
420
421 union _Gedcom_val_union {
422   char* string_val;
423   struct date_value date_val;
424   struct age_value age_val;
425   struct xref_value *xref_val;
426 };
427
428 typedef struct _Gedcom_val_struct {
429   Gedcom_val_type type;
430   union _Gedcom_val_union value;
431 } Gedcom_val_struct;
432
433 void gedcom_cast_error(const char* file, int line,
434                        Gedcom_val_type tried_type,
435                        Gedcom_val_type real_type);
436
437 extern struct date_value def_date_val;
438 extern struct age_value  def_age_val;
439 extern struct xref_value def_xref_val;
440
441 #define GV_CHECK_CAST(VAL, TYPE, MEMBER, DEFVAL)                              \
442    (((VAL)->type == TYPE) ?                                                   \
443     (VAL)->value.MEMBER :                                                     \
444     (gedcom_cast_error(__FILE__,__LINE__, TYPE, (VAL)->type), DEFVAL))
445
446 #define GV_IS_TYPE(VAL, TYPE)                                                 \
447    ((VAL)->type == TYPE)
448
449 /**************************************************************************/
450 /***  Function interface                                                ***/
451 /**************************************************************************/
452
453 /* Type for parsed values, meant to be opaque */
454 typedef Gedcom_val_struct* Gedcom_val;
455
456 /* Type for write handle, meant to be opaque */
457 struct Gedcom_write_struct;
458 typedef struct Gedcom_write_struct* Gedcom_write_hndl;
459
460 /* Check to determine whether there is a parsed value or not */
461 #define GEDCOM_IS_NULL(VAL) \
462    GV_IS_TYPE(VAL, GV_NULL)
463
464 /* This returns the char* from a Gedcom_val, if appropriate */
465 /* It gives a gedcom_warning if the cast is not correct     */
466 #define GEDCOM_STRING(VAL) \
467    GV_CHECK_CAST(VAL, GV_CHAR_PTR, string_val, "<error>")
468 #define GEDCOM_IS_STRING(VAL) \
469    GV_IS_TYPE(VAL, GV_CHAR_PTR)
470
471 /* This returns the struct date_value from a Gedcom_val, if appropriate */
472 /* It gives a gedcom_warning if the cast is not correct                 */
473 #define GEDCOM_DATE(VAL) \
474    GV_CHECK_CAST(VAL, GV_DATE_VALUE, date_val, def_date_val)
475 #define GEDCOM_IS_DATE(VAL) \
476    GV_IS_TYPE(VAL, GV_DATE_VALUE)
477
478 /* This returns the struct age_value from a Gedcom_val, if appropriate  */
479 /* It gives a gedcom_warning if the cast is not correct                 */
480 #define GEDCOM_AGE(VAL) \
481    GV_CHECK_CAST(VAL, GV_AGE_VALUE, age_val, def_age_val)
482 #define GEDCOM_IS_AGE(VAL) \
483    GV_IS_TYPE(VAL, GV_AGE_VALUE)
484
485 /* This returns the (struct xref_value *) from a Gedcom_val, if appropriate */
486 /* It gives a gedcom_warning if the cast is not correct                     */
487 #define GEDCOM_XREF_PTR(VAL) \
488    GV_CHECK_CAST(VAL, GV_XREF_PTR, xref_val, &def_xref_val)
489 #define GEDCOM_IS_XREF_PTR(VAL) \
490    GV_IS_TYPE(VAL, GV_XREF_PTR)
491
492 typedef void
493         (*Gedcom_msg_handler)
494         (Gedcom_msg_type type, char *msg);
495
496 typedef Gedcom_ctxt
497         (*Gedcom_rec_start_cb)
498         (Gedcom_rec rec, int level, Gedcom_val xref, char *tag,
499          char *raw_value, int tag_value, Gedcom_val parsed_value);
500 typedef void
501         (*Gedcom_rec_end_cb)
502         (Gedcom_rec rec, Gedcom_ctxt self, Gedcom_val parsed_value);
503
504 typedef Gedcom_ctxt
505         (*Gedcom_elt_start_cb)
506         (Gedcom_elt elt, Gedcom_ctxt parent,
507          int level, char *tag, char *raw_value,
508          int tag_value, Gedcom_val parsed_value);
509 typedef void
510         (*Gedcom_elt_end_cb)
511         (Gedcom_elt elt, Gedcom_ctxt parent, Gedcom_ctxt self,
512          Gedcom_val parsed_value);
513
514 typedef void
515         (*Gedcom_def_cb)
516         (Gedcom_elt elt, Gedcom_ctxt parent, int level, char *tag,
517          char *raw_value, int tag_value);
518
519 int     gedcom_init();
520 int     gedcom_parse_file(const char* file_name);
521 int     gedcom_new_model();
522 void    gedcom_set_debug_level(int level, FILE* trace_output);
523 void    gedcom_set_error_handling(Gedcom_err_mech mechanism);
524 void    gedcom_set_compat_handling(int enable_compat);
525 void    gedcom_set_compat_options(Gedcom_compat options);
526 void    gedcom_set_message_handler(Gedcom_msg_handler func);
527 void    gedcom_set_default_callback(Gedcom_def_cb func);
528
529 void    gedcom_subscribe_to_record(Gedcom_rec rec,
530                                    Gedcom_rec_start_cb cb_start,
531                                    Gedcom_rec_end_cb cb_end);
532 void    gedcom_subscribe_to_element(Gedcom_elt elt,
533                                     Gedcom_elt_start_cb cb_start,
534                                     Gedcom_elt_end_cb cb_end);
535
536 /* Separate value parsing functions */
537 struct date_value  gedcom_parse_date(const char* line_value);
538 char*              gedcom_date_to_string(const struct date_value* val);
539 struct date_value* gedcom_new_date_value(const struct date_value* copy_from);
540 int   gedcom_normalize_date(Date_input compute_from, struct date_value *val);
541
542 struct age_value  gedcom_parse_age(const char* line_value);
543 struct age_value* gedcom_new_age_value(const struct age_value* copy_from);
544 char*             gedcom_age_to_string(const struct age_value* val);
545
546 /* Handling cross-references */
547 struct xref_value *gedcom_get_by_xref(const char *key);
548 struct xref_value *gedcom_add_xref(Xref_type type, const char* xrefstr,
549                                    Gedcom_ctxt object);
550 struct xref_value *gedcom_link_xref(Xref_type type, const char* xrefstr);
551 struct xref_value *gedcom_unlink_xref(Xref_type type, const char* xrefstr);
552 int                gedcom_delete_xref(const char* xrefstr);
553
554 /* Writing support */
555 Gedcom_write_hndl  gedcom_write_open(const char* filename);
556 int  gedcom_write_close(Gedcom_write_hndl hndl, int *total_conv_fails);
557 int  gedcom_write_set_encoding(Enc_from from,
558                                const char* charset, Encoding width,
559                                Enc_bom bom);
560 int  gedcom_write_set_line_terminator(Enc_from from, Enc_line_end end);
561
562 int  gedcom_write_record_str(Gedcom_write_hndl hndl,
563                              Gedcom_rec rec, const char* xrefstr,
564                              const char* val);
565   
566 int gedcom_write_element_str(Gedcom_write_hndl hndl, Gedcom_elt elt,
567                              int parsed_tag, int parent_rec_or_elt,
568                              const char* val);
569 int gedcom_write_element_xref(Gedcom_write_hndl hndl, Gedcom_elt elt,
570                               int parsed_tag, int parent_rec_or_elt,
571                               const struct xref_value* val);
572
573 int gedcom_write_element_date(Gedcom_write_hndl hndl,
574                               Gedcom_elt elt, int tag, int parent_rec_or_elt,
575                               const struct date_value* val);
576 int gedcom_write_element_age(Gedcom_write_hndl hndl,
577                              Gedcom_elt elt, int tag, int parent_rec_or_elt,
578                              const struct age_value* val);
579
580 int gedcom_write_user_str(Gedcom_write_hndl hndl, int level, const char* tag,
581                           const char* xrefstr, const char* value);
582 int gedcom_write_user_xref(Gedcom_write_hndl hndl, int level, const char* tag,
583                            const char* xrefstr, const struct xref_value* val);
584
585 /* For use in gom */
586 int        gedcom_error(const char* s, ...);
587 int        gedcom_warning(const char* s, ...);
588 int        gedcom_message(const char* s, ...);
589 int        gedcom_debug_print(const char* s, ...);
590
591 #ifdef __cplusplus
592 }
593 #endif
594
595 #endif /* __GEDCOM_H */