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