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 enum _Gedcom_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 };
  63
  64   /** \brief Record types
  65       \ingroup start_end
  66
  67       See the
  68       <a href="interface.html#Record_identifiers">interface details</a>.
  69   */
  70 typedef enum _Gedcom_rec Gedcom_rec;
  71
  72 enum _Gedcom_elt {
  73   ELT_HEAD_SOUR = NR_OF_RECS,
  74   ELT_HEAD_SOUR_VERS,
  75   ELT_HEAD_SOUR_NAME,
  76   ELT_HEAD_SOUR_CORP,
  77   ELT_HEAD_SOUR_DATA,
  78   ELT_HEAD_SOUR_DATA_DATE,
  79   ELT_HEAD_SOUR_DATA_COPR,
  80   ELT_HEAD_DEST,
  81   ELT_HEAD_DATE,
  82   ELT_HEAD_DATE_TIME,
  83   ELT_HEAD_SUBM,
  84   ELT_HEAD_SUBN,
  85   ELT_HEAD_FILE,
  86   ELT_HEAD_COPR,
  87   ELT_HEAD_GEDC,
  88   ELT_HEAD_GEDC_VERS,
  89   ELT_HEAD_GEDC_FORM,
  90   ELT_HEAD_CHAR,
  91   ELT_HEAD_CHAR_VERS,
  92   ELT_HEAD_LANG,
  93   ELT_HEAD_PLAC,
  94   ELT_HEAD_PLAC_FORM,
  95   ELT_HEAD_NOTE,
  96
  97   ELT_FAM_HUSB,
  98   ELT_FAM_WIFE,
  99   ELT_FAM_CHIL,
 100   ELT_FAM_NCHI,
 101   ELT_FAM_SUBM,
 102
 103   ELT_INDI_RESN,
 104   ELT_INDI_SEX,
 105   ELT_INDI_SUBM,
 106   ELT_INDI_ALIA,
 107   ELT_INDI_ANCI,
 108   ELT_INDI_DESI,
 109   ELT_INDI_RFN,
 110   ELT_INDI_AFN,
 111
 112   ELT_OBJE_FORM,
 113   ELT_OBJE_TITL,
 114   ELT_OBJE_BLOB,
 115   ELT_OBJE_BLOB_CONT,
 116   ELT_OBJE_OBJE,
 117
 118   ELT_REPO_NAME,
 119
 120   ELT_SOUR_DATA,
 121   ELT_SOUR_DATA_EVEN,
 122   ELT_SOUR_DATA_EVEN_DATE,
 123   ELT_SOUR_DATA_EVEN_PLAC,
 124   ELT_SOUR_DATA_AGNC,
 125   ELT_SOUR_AUTH,
 126   ELT_SOUR_TITL,
 127   ELT_SOUR_ABBR,
 128   ELT_SOUR_PUBL,
 129   ELT_SOUR_TEXT,
 130
 131   ELT_SUBN_SUBM,
 132   ELT_SUBN_FAMF,
 133   ELT_SUBN_TEMP,
 134   ELT_SUBN_ANCE,
 135   ELT_SUBN_DESC,
 136   ELT_SUBN_ORDI,
 137   ELT_SUBN_RIN,
 138
 139   ELT_SUBM_NAME,
 140   ELT_SUBM_LANG,
 141   ELT_SUBM_RFN,
 142   ELT_SUBM_RIN,
 143
 144   ELT_SUB_ADDR,
 145   ELT_SUB_ADDR_CONT,
 146   ELT_SUB_ADDR_ADR1,
 147   ELT_SUB_ADDR_ADR2,
 148   ELT_SUB_ADDR_CITY,
 149   ELT_SUB_ADDR_STAE,
 150   ELT_SUB_ADDR_POST,
 151   ELT_SUB_ADDR_CTRY,
 152
 153   ELT_SUB_PHON,
 154
 155   ELT_SUB_ASSO,
 156   ELT_SUB_ASSO_TYPE,
 157   ELT_SUB_ASSO_RELA,
 158
 159   ELT_SUB_CHAN,
 160   ELT_SUB_CHAN_DATE,
 161   ELT_SUB_CHAN_TIME,
 162
 163   ELT_SUB_FAMC,
 164   ELT_SUB_FAMC_PEDI,
 165
 166   ELT_SUB_CONT,
 167   ELT_SUB_CONC,
 168
 169   ELT_SUB_EVT_TYPE,
 170   ELT_SUB_EVT_DATE,
 171   ELT_SUB_EVT_AGE,
 172   ELT_SUB_EVT_AGNC,
 173   ELT_SUB_EVT_CAUS,
 174
 175   ELT_SUB_FAM_EVT,
 176   ELT_SUB_FAM_EVT_HUSB,
 177   ELT_SUB_FAM_EVT_WIFE,
 178   ELT_SUB_FAM_EVT_AGE,
 179   ELT_SUB_FAM_EVT_EVEN,
 180
 181   ELT_SUB_IDENT_REFN,
 182   ELT_SUB_IDENT_REFN_TYPE,
 183   ELT_SUB_IDENT_RIN,
 184
 185   ELT_SUB_INDIV_ATTR,
 186   ELT_SUB_INDIV_RESI,
 187   ELT_SUB_INDIV_BIRT,
 188   ELT_SUB_INDIV_BIRT_FAMC,
 189   ELT_SUB_INDIV_GEN,
 190   ELT_SUB_INDIV_ADOP,
 191   ELT_SUB_INDIV_ADOP_FAMC,
 192   ELT_SUB_INDIV_ADOP_FAMC_ADOP,
 193   ELT_SUB_INDIV_EVEN,
 194
 195   ELT_SUB_LIO_BAPL,
 196   ELT_SUB_LIO_BAPL_STAT,
 197   ELT_SUB_LIO_BAPL_DATE,
 198   ELT_SUB_LIO_BAPL_TEMP,
 199   ELT_SUB_LIO_BAPL_PLAC,
 200   ELT_SUB_LIO_SLGC,
 201   ELT_SUB_LIO_SLGC_FAMC,
 202
 203   ELT_SUB_LSS_SLGS,
 204   ELT_SUB_LSS_SLGS_STAT,
 205   ELT_SUB_LSS_SLGS_DATE,
 206   ELT_SUB_LSS_SLGS_TEMP,
 207   ELT_SUB_LSS_SLGS_PLAC,
 208
 209   ELT_SUB_MULTIM_OBJE,
 210   ELT_SUB_MULTIM_OBJE_FORM,
 211   ELT_SUB_MULTIM_OBJE_TITL,
 212   ELT_SUB_MULTIM_OBJE_FILE,
 213
 214   ELT_SUB_NOTE,
 215
 216   ELT_SUB_PERS_NAME,
 217   ELT_SUB_PERS_NAME_NPFX,
 218   ELT_SUB_PERS_NAME_GIVN,
 219   ELT_SUB_PERS_NAME_NICK,
 220   ELT_SUB_PERS_NAME_SPFX,
 221   ELT_SUB_PERS_NAME_SURN,
 222   ELT_SUB_PERS_NAME_NSFX,
 223
 224   ELT_SUB_PLAC,
 225   ELT_SUB_PLAC_FORM,
 226
 227   ELT_SUB_SOUR,
 228   ELT_SUB_SOUR_PAGE,
 229   ELT_SUB_SOUR_EVEN,
 230   ELT_SUB_SOUR_EVEN_ROLE,
 231   ELT_SUB_SOUR_DATA,
 232   ELT_SUB_SOUR_DATA_DATE,
 233   ELT_SUB_SOUR_TEXT,
 234   ELT_SUB_SOUR_QUAY,
 235
 236   ELT_SUB_REPO,
 237   ELT_SUB_REPO_CALN,
 238   ELT_SUB_REPO_CALN_MEDI,
 239
 240   ELT_SUB_FAMS,
 241
 242   ELT_USER,
 243
 244   NR_OF_ELTS     /* Just a final value to be used in array boundaries */
 245 };
 246
 247   /** \brief Element types
 248       \ingroup start_end
 249
 250       See the
 251       <a href="interface.html#Element_identifiers">interface details</a>.
 252   */
 253 typedef enum _Gedcom_elt Gedcom_elt;
 254
 255 /**************************************************************************/
 256 /***  Definition of some auxiliary types                                ***/
 257 /**************************************************************************/
 258
 259   /** \addtogroup error */
 260   /** @{ */
 261   /** \brief Error handling mechanisms.
 262
 263       These are the possible error handling mechanisms.
 264       \sa gedcom_set_error_handling
 265   */
 266 enum _Gedcom_err_mech {
 267   IMMED_FAIL,    /**< immediately fail the parsing on an error (this is
 268                        the default) */
 269   DEFER_FAIL,    /**< continue parsing after an error, but return a failure
 270                        code eventually */
 271   IGNORE_ERRORS  /**< continue parsing after an error, return success always */
 272 };
 273
 274   /** \brief Error handling mechanisms. */
 275 typedef enum _Gedcom_err_mech Gedcom_err_mech;
 276
 277   /** \brief Message type in message handler callbacks
 278
 279       This will be passed to the message callback to indicate the message type.
 280       \sa gedcom_set_message_handler
 281   */
 282 enum _Gedcom_msg_type {
 283   ERROR,               /**< An error message */
 284   WARNING,             /**< A warning message */
 285   MESSAGE              /**< Just a message */
 286 };
 287
 288   /** \brief Message type in message handler callbacks */
 289 typedef enum _Gedcom_msg_type Gedcom_msg_type;
 290   /** @} */
 291
 292 /* All Unicode characters between U+0000 and U+FFFF can be encoded in
 293    UTF-8 with 3 or less bytes */
 294 #define UTF_FACTOR 3
 295
 296 #define MAX_DAY_LEN    2
 297 #define MAX_MONTH_LEN  4
 298 #define MAX_YEAR_LEN   7
 299 #define MAX_PHRASE_LEN 35 * UTF_FACTOR
 300
 301   /** \addtogroup parsed_date */
 302   /** @{ */
 303   /** \brief Date type
 304
 305       This determines which one of the serial day numbers (Julian days) are
 306       relevant in the struct date.
 307    */
 308 enum _Date_type {
 309   DATE_UNRECOGNIZED,   /**< Neither date#sdn1 as date#sdn2 are significant */
 310   DATE_EXACT,          /**< Only date#sdn1 is significant */
 311   DATE_BOUNDED         /**< Both date#sdn1 and date#sdn2 are significant */
 312 };
 313
 314   /** \brief Date type */
 315 typedef enum _Date_type Date_type;
 316
 317   /** \brief Calendar type
 318
 319       This determines the calendary type (see calendar overview LINK TBD).
 320    */
 321 enum _Calendar_type {
 322   CAL_GREGORIAN,  /**< The Gregorian calendar */
 323   CAL_JULIAN,     /**< The Julian calendar */
 324   CAL_HEBREW,     /**< The Hebrew (Jewish) calendar */
 325   CAL_FRENCH_REV, /**< The calendar used after the French Revolution */
 326   CAL_UNKNOWN     /**< An unknown calendar type */
 327 };
 328
 329   /** \brief Calendar type */
 330 typedef enum _Calendar_type Calendar_type;
 331
 332   /** \brief Year type
 333
 334       This determines whether the year has one value (e.g. 1677) or two values
 335       (e.g. 1677/78, the first value is in annunciation style, the second in
 336       circumcision style).
 337    */
 338 enum _Year_type {
 339   YEAR_SINGLE,  /**< There is only one value for the year */
 340   YEAR_DOUBLE   /**< The date#year_str contains two values.  Note that the
 341                    date#year
 342                    will then contain the circumcision style year, i.e. the
 343                    highest one */
 344 };
 345
 346   /** \brief Year type */
 347 typedef enum _Year_type Year_type;
 348
 349   /** \brief Date value type
 350
 351       This determines which members in the struct date_value are relevant, as
 352       given in the description below.
 353    */
 354 enum _Date_value_type {
 355   /* Simple date */
 356   DV_NO_MODIFIER, /**< Just a simple date: date1 */
 357   /* Range values */
 358   DV_BEFORE,      /**< A range (BEFORE date1) */
 359   DV_AFTER,       /**< A range (AFTER date1) */
 360   DV_BETWEEN,     /**< A range (BETWEEN date1 AND date2) */
 361   /* Period values */
 362   DV_FROM,        /**< A period (FROM date1) */
 363   DV_TO,          /**< A period (TO date1) */
 364   DV_FROM_TO,     /**< A period (FROM date1 TO date2) */
 365   /* Approx values */
 366   DV_ABOUT,       /**< An approximation (ABOUT date1) */
 367   DV_CALCULATED,  /**< An approximation (CALCULATED date1) */
 368   DV_ESTIMATED,   /**< An approximation (ESTIMATED date1) */
 369   /* Other */
 370   DV_INTERPRETED, /**< INTERPRETED date1 FROM phrase */
 371   DV_PHRASE       /**< phrase */
 372 };
 373
 374   /** \brief Date value type */
 375 typedef enum _Date_value_type Date_value_type;
 376
 377   /** \brief Date input type for gedcom_normalize_date
 378
 379       See explanation for gedcom_normalize_date().
 380    */
 381 enum _Date_input {
 382   DI_FROM_STRINGS,
 383     /**< compute from date#day_str, date#month_str and date#year_str */
 384   DI_FROM_NUMBERS,
 385     /**< compute from date#day, date#month, date#year and date#year_type */
 386   DI_FROM_SDN
 387     /**< compute from date#type, date#sdn1 and date#sdn2 */
 388 };
 389
 390   /** \brief Date input type for gedcom_normalize_date */
 391 typedef enum _Date_input Date_input;
 392
 393   /** \brief Parsed date
 394
 395       This struct describes exactly one date.  It contains the string
 396       representation, the numeric representation and the representation using
 397       serial day numbers (aka Julian days).
 398
 399       It is possible that the #year_str is given as e.g. "1677/78".  This is
 400       coming from a date in a so called "annunciation style", where the year
 401       began on 25 March: "20 March 1677/78" is 20 March 1677 in "annunciation
 402       style" and 20 March 1678 in "circumcision style" (the current style).
 403       See calendar overview (LINK TBD).
 404
 405       In this case, the #year will contain the "circumcision style" year (1678
 406       in the example), and #year_type will be YEAR_DOUBLE.  Normal dates will
 407       have a #year_type equal to YEAR_SINGLE.
 408
 409       Finally, the last three fields (#type, #sdn1 and #sdn2) are probably
 410       the most interesting values
 411       for applications that want to process dates.  Basically, the date is
 412       converted to a serial day number (aka Julian day), which is the unique
 413       day number since November 25, 4714 BC in the Gregorian calendar.  The
 414       advantage of these day numbers is that they are unique and independent
 415       of the calendar system.  Furthermore, date differences can just be
 416       computed by subtracting the serial day numbers.
 417
 418       However, since dates in GEDCOM are not necessarily exact (e.g. "MAR
 419       1990"), it is not possible to represent all GEDCOM dates with 1 serial
 420       day number.  Two cases can be distinguished:
 421
 422          - <b>Exact dates</b> (e.g. "25 MAR 1990"):\n\n
 423            These are represented by a serial day number in #sdn1 and a
 424            #type equal to DATE_EXACT.
 425
 426          - <b>Incomplete dates</b> (e.g. "MAR 1990"):\n\n
 427            These are represented by 2 serial day numbers (#sdn1 and #sdn2)
 428            and a #type equal to DATE_BOUNDED.\n\n
 429            For example, the Gregorian date "MAR 1990" is represented by the
 430            serial day numbers for "1 MAR 1990" and "31 MAR 1990", and the
 431            Gregorian date "1990" is represented by the serial day numbers
 432            for "1 JAN 1990" and "31 DEC 1990".  Similarly for the other
 433            calendar types.
 434    */
 435 struct date {
 436   Calendar_type cal;   /**< The calendar type */
 437   char day_str[MAX_DAY_LEN + 1];
 438                        /**< The literal string part of the date, as parsed from
 439                           the value in the GEDCOM file, that denotes
 440                           the day (can be an empty string) */
 441   char month_str[MAX_MONTH_LEN + 1];
 442                        /**< The literal string part of the date, as parsed from
 443                           the value in the GEDCOM file, that denotes the month
 444                           (can be an empty string) */
 445   char year_str[MAX_YEAR_LEN + 1];
 446                        /**< The literal string part of the date, as parsed from
 447                           the value in the GEDCOM file, that denotes the year
 448                        */
 449   int day;    /**< The numeric representation of the #day_str (starting from
 450                  1), or -1 if the #day_str is empty */
 451   int month;  /**< The month number of #month_str in the given calendar type
 452                  #cal (starting from 1), or -1 if the #month_str is empty */
 453   int year;   /**< The numeric representation of the #year_str */
 454   Year_type year_type;
 455               /**< The year type (see detailed description of \ref date)*/
 456   Date_type type;
 457               /**< The date type (see detailed description of \ref date) */
 458   long int sdn1; /**< The first serial day number */
 459   long int sdn2; /**< The second serial day number */
 460 };
 461
 462   /** \brief Date value
 463
 464       The main struct describing a date value.  It depends on the first member,
 465       the type, which members are actually relevant.
 466    */
 467 struct date_value {
 468   Date_value_type type;  /**< The type of date, which determines which of the
 469                             following members are relevant */
 470   struct date date1;                /**< First parsed date */
 471   struct date date2;                /**< Second parsed date */
 472   char phrase[MAX_PHRASE_LEN + 1];  /**< Free-format date phrase */
 473 };
 474   /** @} */
 475
 476
 477   /** \brief Type for context handling, meant to be opaque
 478       \ingroup start_end
 479   */
 480 typedef void* Gedcom_ctxt;
 481
 482   /** \addtogroup parsed_xref */
 483   /** @{ */
 484
 485   /** \brief Cross-reference type
 486
 487       This determines what kind of object the cross-reference points to.
 488    */
 489 enum _Xref_type {
 490   XREF_NONE,   /**< Used as a default value */
 491   XREF_FAM,    /**< Points to a family */
 492   XREF_INDI,   /**< Points to an individual */
 493   XREF_NOTE,   /**< Points to a note */
 494   XREF_OBJE,   /**< Points to a multimedia object */
 495   XREF_REPO,   /**< Points to a source repository */
 496   XREF_SOUR,   /**< Points to a source */
 497   XREF_SUBM,   /**< Points to a submitter */
 498   XREF_SUBN,   /**< Points to a submission record */
 499   XREF_USER,   /**< For application-specific cross-references */
 500   XREF_ANY     /**< If the type is not known: it has to come from further
 501                   information.  This is the case in an association
 502                   (\c ELT_SUB_ASSO): the type is then given by the \c TYPE
 503                   subtag.
 504                */
 505 };
 506
 507   /** \brief Cross-reference type */
 508 typedef enum _Xref_type Xref_type;
 509
 510   /** \brief Cross-reference value
 511
 512       The struct describing a cross-reference value.
 513    */
 514 struct xref_value {
 515   Xref_type type;  /**< Determines what the cross-reference points to */
 516   char *string;    /**< The actual cross-reference string from the GEDCOM
 517                       file. */
 518   Gedcom_ctxt object;
 519                    /**< The referenced object.  This is initially \c NULL, but
 520                       can be filled by the application with an object (of any
 521                       type) that corresponds with the cross-reference, and then
 522                       later extracted when the cross-reference is used or
 523                       defined again in the file.  This relieves the application
 524                       from the burden of maintaining the mapping between
 525                       cross-references and objects. */
 526 };
 527   /** @} */
 528
 529   /** \addtogroup parsed_age */
 530   /** @{ */
 531
 532   /** \brief Age value type
 533
 534       This determines which members in the struct age_value are relevant, as
 535       given in the description below.
 536    */
 537 enum _Age_type {
 538   AGE_UNRECOGNIZED,  /**< Format not recognized, full raw value in phrase */
 539   AGE_CHILD,         /**< CHILD, with given modifier */
 540   AGE_INFANT,        /**< INFANT, with given modifier */
 541   AGE_STILLBORN,     /**< STILLBORN, with given modifier */
 542   AGE_NUMERIC        /**< An indication in years, months and/or days (each can
 543                         be -1 if not given), with given modifier */
 544 };
 545
 546   /** \brief Age value type */
 547 typedef enum _Age_type Age_type;
 548
 549   /** \brief Age modifier
 550
 551       This gives a modifier on the given date (less than or greater than).
 552    */
 553 enum _Age_modifier {
 554   AGE_NO_MODIFIER,   /**< No modifier */
 555   AGE_LESS_THAN,     /**< The modifier '<' is added */
 556   AGE_GREATER_THAN   /**< The modifier '>' is added */
 557 };
 558
 559   /** \brief Age modifier */
 560 typedef enum _Age_modifier Age_modifier;
 561
 562   /** \brief Age value
 563
 564       The struct describing an age value.  It depends on the first member,
 565       the type, which members are actually relevant.
 566    */
 567 struct age_value {
 568   Age_type type;       /**< The type of age, which determines which of the
 569                             following members are relevant */
 570   Age_modifier mod;    /**< A modifier (less than or greater than) */
 571   int years;           /**< The number of years */
 572   int months;          /**< The number of months */
 573   int days;            /**< The number of days */
 574   char phrase[MAX_PHRASE_LEN + 1];  /**< Free-format age phrase */
 575 };
 576   /** @} */
 577
 578   /** \addtogroup write */
 579   /** @{ */
 580
 581   /** \brief The encoding width and endianness
 582       \sa gedcom_write_set_encoding */
 583 enum _Encoding {
 584   ONE_BYTE      = 0x00, /**< This should be used for all character sets except
 585                             UNICODE */
 586   TWO_BYTE_HILO = 0x01, /**< High-low encoding for UNICODE (i.e. big-endian) */
 587   TWO_BYTE_LOHI = 0x02  /**< Low-high encoding for UNICODE (i.e. little-endian)
 588                          */
 589 };
 590
 591   /** \brief The encoding width and endianness */
 592 typedef enum _Encoding Encoding;
 593
 594   /** \brief The use of a byte-order-mark in the encoding
 595       \sa gedcom_write_set_encoding */
 596 enum _Enc_bom {
 597   WITHOUT_BOM = 0x00,  /**< Without byte-order-mark */
 598   WITH_BOM    = 0x10   /**< With byte-order-mark */
 599 };
 600
 601   /** \brief The use of a byte-order-mark in the encoding */
 602 typedef enum _Enc_bom Enc_bom;
 603
 604   /** \brief The line terminator in the encoding
 605       \sa gedcom_write_set_line_terminator */
 606 enum _Enc_line_end {
 607   END_CR    = 0, /**< Only carriage return ('\\r') (system value for Mac) */
 608   END_LF    = 1, /**< Only line feed ('\\n') (system value for Unix, Mac OSX)
 609                   */
 610   END_CR_LF = 2, /**< First carriage return, then line feed ('\\r\\n')
 611                     (system value for DOS, Windows) */
 612   END_LF_CR = 3  /**< First line feed, then carriage return ('\\n\\r') */
 613 };
 614
 615   /** \brief The line terminator in the encoding */
 616 typedef enum _Enc_line_end Enc_line_end;
 617
 618   /** \brief Source of the encoding settings
 619       \sa gedcom_write_set_encoding and gedcom_write_set_line_terminator */
 620 enum _Enc_from {
 621   ENC_FROM_FILE = 0, /**< The same as the read file was in */
 622   ENC_FROM_SYS  = 1, /**< The system value */
 623   ENC_MANUAL    = 2  /**< From the parameters given in the function */
 624 };
 625
 626   /** \brief Source of the encoding settings */
 627 typedef enum _Enc_from Enc_from;
 628   /** @} */
 629
 630 struct encoding_state;
 631
 632   /** \addtogroup compat */
 633   /** @{ */
 634   /** \brief Compatibility mode options */
 635 enum _Gedcom_compat {
 636   COMPAT_ALLOW_OUT_OF_CONTEXT = 0x01
 637     /**< In some compatibility cases, tags are coming out-of-order, i.e. their
 638        start element callback would have to come after the end element callback
 639        of the parent tag.  E.g. instead of the standard GEDCOM
 640        \code
 641          1 DATE ...
 642          2 TIME ...
 643        \endcode
 644        the genealogy program has generated something like:
 645        \code
 646          1 DATE ...
 647          1 TIME ...
 648        \endcode
 649        This can give a problem if your end element callbacks free some
 650        resources.
 651
 652        If your program can handle elements out of context, you can enable this
 653        option.  By default it is disabled, and so the values of these
 654        out-of-context tags are lost (the parser generates a warning if this is
 655        the case).
 656     */
 657 };
 658
 659   /** \brief Compatibility mode options */
 660 typedef enum _Gedcom_compat Gedcom_compat;
 661   /** @} */
 662
 663 /**************************************************************************/
 664 /***  Things meant to be internal, susceptible to changes               ***/
 665 /***  Use the GEDCOM_STRING/GEDCOM_DATE interface instead of relying    ***/
 666 /***  on this !!                                                        ***/
 667 /**************************************************************************/
 668
 669 /* Update strings in interface.c if this changes */
 670 typedef enum _GEDCOM_VAL_TYPE {
 671   GV_NULL       = 0x01,
 672   GV_CHAR_PTR   = 0x02,
 673   GV_DATE_VALUE = 0x04,
 674   GV_AGE_VALUE  = 0x08,
 675   GV_XREF_PTR   = 0x10
 676 } Gedcom_val_type;
 677
 678 union _Gedcom_val_union {
 679   char* string_val;
 680   struct date_value date_val;
 681   struct age_value age_val;
 682   struct xref_value *xref_val;
 683 };
 684
 685 typedef struct _Gedcom_val_struct {
 686   Gedcom_val_type type;
 687   union _Gedcom_val_union value;
 688 } Gedcom_val_struct;
 689
 690 void gedcom_cast_error(const char* file, int line,
 691                        Gedcom_val_type tried_type,
 692                        Gedcom_val_type real_type);
 693
 694 extern struct date_value def_date_val;
 695 extern struct age_value  def_age_val;
 696 extern struct xref_value def_xref_val;
 697
 698 #define GV_CHECK_CAST(VAL, TYPE, MEMBER, DEFVAL)                              \
 699    (((VAL)->type == TYPE) ?                                                   \
 700     (VAL)->value.MEMBER :                                                     \
 701     (gedcom_cast_error(__FILE__,__LINE__, TYPE, (VAL)->type), DEFVAL))
 702
 703 #define GV_IS_TYPE(VAL, TYPE)                                                 \
 704    ((VAL)->type == TYPE)
 705
 706 /**************************************************************************/
 707 /***  Function interface                                                ***/
 708 /**************************************************************************/
 709
 710   /** \brief Parsed value
 711       \ingroup parsed
 712
 713       Type for the parsed value.  The struct type Gedcom_val_struct should
 714       be seen as internal: the Gedcom_val should be handled using the macros
 715       given above.
 716   */
 717 typedef Gedcom_val_struct* Gedcom_val;
 718
 719 struct Gedcom_write_struct;
 720   /** \brief Write handle
 721       \ingroup write
 722
 723       Handle for writing Gedcom files.  The struct type Gedcom_write_struct
 724       should be seen as internal: only the handle should be used.
 725    */
 726 typedef struct Gedcom_write_struct* Gedcom_write_hndl;
 727
 728 /* Check to determine whether there is a parsed value or not */
 729 #define GEDCOM_IS_NULL(VAL) \
 730    GV_IS_TYPE(VAL, GV_NULL)
 731
 732 /* This returns the char* from a Gedcom_val, if appropriate */
 733 /* It gives a gedcom_warning if the cast is not correct     */
 734 #define GEDCOM_STRING(VAL) \
 735    GV_CHECK_CAST(VAL, GV_CHAR_PTR, string_val, "<error>")
 736 #define GEDCOM_IS_STRING(VAL) \
 737    GV_IS_TYPE(VAL, GV_CHAR_PTR)
 738
 739 /* This returns the struct date_value from a Gedcom_val, if appropriate */
 740 /* It gives a gedcom_warning if the cast is not correct                 */
 741 #define GEDCOM_DATE(VAL) \
 742    GV_CHECK_CAST(VAL, GV_DATE_VALUE, date_val, def_date_val)
 743 #define GEDCOM_IS_DATE(VAL) \
 744    GV_IS_TYPE(VAL, GV_DATE_VALUE)
 745
 746 /* This returns the struct age_value from a Gedcom_val, if appropriate  */
 747 /* It gives a gedcom_warning if the cast is not correct                 */
 748 #define GEDCOM_AGE(VAL) \
 749    GV_CHECK_CAST(VAL, GV_AGE_VALUE, age_val, def_age_val)
 750 #define GEDCOM_IS_AGE(VAL) \
 751    GV_IS_TYPE(VAL, GV_AGE_VALUE)
 752
 753 /* This returns the (struct xref_value *) from a Gedcom_val, if appropriate */
 754 /* It gives a gedcom_warning if the cast is not correct                     */
 755 #define GEDCOM_XREF_PTR(VAL) \
 756    GV_CHECK_CAST(VAL, GV_XREF_PTR, xref_val, &def_xref_val)
 757 #define GEDCOM_IS_XREF_PTR(VAL) \
 758    GV_IS_TYPE(VAL, GV_XREF_PTR)
 759
 760   /** \brief Message handler callback
 761       \ingroup error
 762     A callback for errors, warnings and messages.
 763     \sa gedcom_set_message_handler
 764
 765     \param type The message type
 766     \param msg  For errors, this will have the format
 767       \code
 768         Error on line <lineno>: <actual_message>
 769       \endcode
 770       Note that the entire string will be properly internationalized, and
 771       encoded in UTF-8 (<a href=encoding.html>Why UTF-8?</a>).
 772       Also, no newline is appended, so that
 773       the application program can use it in any way it wants.  Warnings are
 774       similar, but use "Warning" instead of "Error".  Messages are plain
 775       text, without any prefix.
 776   */
 777 typedef void
 778         (*Gedcom_msg_handler)
 779         (Gedcom_msg_type type, char *msg);
 780
 781   /** \brief Record start callback
 782       \ingroup start_end
 783     A callback to handle the start of records.  A record entry in a GEDCOM
 784     file is always of the form <tt>"<level> <xref> <tag> <value>"</tt>, e.g.
 785     \code
 786       0 @REC003@ NOTE This is a note
 787     \endcode
 788     The different parameters of the callback return different parts of this
 789     entry.
 790     \sa gedcom_subscribe_to_record
 791
 792     \param rec An enum identifying the record type (see the
 793     <a href="interface.html#Record_identifiers">interface details</a>)
 794     \param level The GEDCOM level (always 0 for records)
 795     \param xref The cross-reference key that identifies the record ("@REC003@"
 796     in the example above).
 797     \param tag The GEDCOM tag, in string format ("NOTE" in the example above).
 798     \param raw_value The value of the record, in string format, encoded as
 799     UTF-8 ("This is a note" in the example above)
 800     \param tag_value The GEDCOM tag, as symbolic value (e.g. \c TAG_NOTE in the
 801     example).  These values are defined in the header \c gedcom-tags.h that is
 802     installed, and included via \c gedcom.h (so no need to include
 803     \c gedcom-tags.h yourself).
 804     \param parsed_value The value of the record, in parsed format.
 805
 806     \return A context to be used for this record (equivalent to a void
 807     pointer).  This context will be passed
 808     in all callbacks for direct child elements, and in the end callback for the
 809     record.
 810   */
 811 typedef Gedcom_ctxt
 812         (*Gedcom_rec_start_cb)
 813         (Gedcom_rec rec, int level, Gedcom_val xref, char *tag,
 814          char *raw_value, int tag_value, Gedcom_val parsed_value);
 815   /** \brief Record end callback
 816       \ingroup start_end
 817     A callback to handle the end of records, i.e. this callback is called when
 818     all sub-elements of a record have been processed.
 819     \sa gedcom_subscribe_to_record
 820
 821     \param rec An enum identifying the record type (see the
 822     <a href="interface.html#Record_identifiers">interface details</a>)
 823     \param self The context as was given via the start callback.
 824     \param parsed_value The value of the record, in parsed format.  Here it is
 825     used to pass 'complete' values, e.g. the full text of a note including
 826     concatenated lines.
 827   */
 828 typedef void
 829         (*Gedcom_rec_end_cb)
 830         (Gedcom_rec rec, Gedcom_ctxt self, Gedcom_val parsed_value);
 831
 832   /** \brief Element start callback
 833       \ingroup start_end
 834     A callback to handle the start of elements.  An element in a GEDCOM
 835     file is part of a record, and is always of the form
 836     <tt>"<level> <tag> <value>"</tt>, e.g.
 837     \code
 838       1 DATE 1 JAN 1998
 839     \endcode
 840     The different parameters of the callback return different parts of this
 841     entry.
 842     \sa gedcom_subscribe_to_element
 843
 844     \param elt An enum identifying the element type (see the
 845     <a href="interface.html#Element_identifiers">interface details</a>)
 846     \param parent The context of the parent element or record
 847     \param level The GEDCOM level (always bigger than 0 for elements)
 848     \param tag The GEDCOM tag, in string format ("DATE" in the example above).
 849     \param raw_value The value of the record, in string format, encoded as
 850     UTF-8 ("1 JAN 1998" in the example above)
 851     \param tag_value The GEDCOM tag, as symbolic value (e.g. \c TAG_DATE in the
 852     example).  These values are defined in the header \c gedcom-tags.h that is
 853     installed, and included via \c gedcom.h (so no need to include
 854     \c gedcom-tags.h yourself).
 855     \param parsed_value The value of the record, in parsed format.
 856
 857     \return A context to be used for this element (equivalent to a void
 858     pointer).  This context will be passed
 859     in all callbacks for direct child elements, and in the end callback for the
 860     element.
 861   */
 862 typedef Gedcom_ctxt
 863         (*Gedcom_elt_start_cb)
 864         (Gedcom_elt elt, Gedcom_ctxt parent,
 865          int level, char *tag, char *raw_value,
 866          int tag_value, Gedcom_val parsed_value);
 867   /** \brief Element end callback
 868       \ingroup start_end
 869     A callback to handle the end of element, i.e. this callback is called when
 870     all sub-elements of an element have been processed.
 871     \sa gedcom_subscribe_to_element
 872
 873     \param elt An enum identifying the element type (see the
 874     <a href="interface.html#Element_identifiers">interface details</a>)
 875     \param parent The context of the parent element or record.
 876     \param self The context as was given via the start callback of the element.
 877     \param parsed_value The value of the element, in parsed format.  Here it is
 878     used to pass 'complete' values, e.g. the full text of a note including
 879     concatenated lines.
 880   */
 881 typedef void
 882         (*Gedcom_elt_end_cb)
 883         (Gedcom_elt elt, Gedcom_ctxt parent, Gedcom_ctxt self,
 884          Gedcom_val parsed_value);
 885
 886   /** \brief Default callback
 887       \ingroup defcb
 888     The default callback, i.e. this callback is called when no specific
 889     callback has been registered.
 890     \sa gedcom_set_default_callback
 891
 892     \param elt An enum identifying the element type (see the
 893     <a href="interface.html#Element_identifiers">interface details</a>)
 894     \param parent The context of the parent element or record.
 895     \param level The GEDCOM level (always bigger than 0 for elements)
 896     \param tag The GEDCOM tag, in string format.
 897     \param raw_value The value of the record, in string format, encoded as
 898     UTF-8
 899     \param tag_value The GEDCOM tag, as symbolic value.  These values are
 900     defined in the header \c gedcom-tags.h that is
 901     installed, and included via \c gedcom.h (so no need to include
 902     \c gedcom-tags.h yourself).
 903   */
 904 typedef void
 905         (*Gedcom_def_cb)
 906         (Gedcom_elt elt, Gedcom_ctxt parent, int level, char *tag,
 907          char *raw_value, int tag_value);
 908
 909   /** \addtogroup main */
 910   /** @{ */
 911   /** \brief Initializes the Gedcom parser library */
 912 int     gedcom_init();
 913   /** \brief Parses an existing Gedcom file */
 914 int     gedcom_parse_file(const char* file_name);
 915   /** \brief Starts a new Gedcom model */
 916 int     gedcom_new_model();
 917   /** @} */
 918
 919   /** \addtogroup error */
 920   /** @{ */
 921   /** \brief Sets the error handler callback */
 922 void    gedcom_set_message_handler(Gedcom_msg_handler func);
 923   /** \brief Determine what happens on an error */
 924 void    gedcom_set_error_handling(Gedcom_err_mech mechanism);
 925   /** @} */
 926
 927   /** \addtogroup debug */
 928   /** @{ */
 929   /** \brief Set the debugging level */
 930 void    gedcom_set_debug_level(int level, FILE* trace_output);
 931   /** @} */
 932
 933   /** \addtogroup compat */
 934   /** @{ */
 935   /** \brief Enable or disable compatibility mode */
 936 void    gedcom_set_compat_handling(int enable_compat);
 937   /** \brief Set some options for the compatibility mode */
 938 void    gedcom_set_compat_options(Gedcom_compat options);
 939   /** @} */
 940
 941   /** \addtogroup defcb */
 942   /** @{ */
 943   /** \brief Set the default callback */
 944 void    gedcom_set_default_callback(Gedcom_def_cb func);
 945   /** @} */
 946
 947   /** \addtogroup start_end */
 948   /** @{ */
 949   /** \brief Subscribe to records, with given start and end callback */
 950 void    gedcom_subscribe_to_record(Gedcom_rec rec,
 951                                    Gedcom_rec_start_cb cb_start,
 952                                    Gedcom_rec_end_cb cb_end);
 953   /** \brief Subscribe to elements, with given start and end callback */
 954 void    gedcom_subscribe_to_element(Gedcom_elt elt,
 955                                     Gedcom_elt_start_cb cb_start,
 956                                     Gedcom_elt_end_cb cb_end);
 957   /** @} */
 958
 959 /* Separate value parsing functions */
 960   /** \addtogroup parsed_date */
 961   /** @{ */
 962   /** \brief Parse the given string into a date value */
 963 struct date_value  gedcom_parse_date(const char* line_value);
 964   /** \brief Convert the given date value into a string */
 965 char*              gedcom_date_to_string(const struct date_value* val);
 966   /** \brief Create a new date value */
 967 struct date_value* gedcom_new_date_value(const struct date_value* copy_from);
 968   /** \brief Normalize the given date value */
 969 int   gedcom_normalize_date(Date_input compute_from, struct date_value *val);
 970   /** @} */
 971
 972   /** \addtogroup parsed_age */
 973   /** @{ */
 974   /** \brief Parse the given string into an age value */
 975 struct age_value  gedcom_parse_age(const char* line_value);
 976   /** \brief Convert the given age value into a string */
 977 char*             gedcom_age_to_string(const struct age_value* val);
 978   /** \brief Create a new age value */
 979 struct age_value* gedcom_new_age_value(const struct age_value* copy_from);
 980   /** @} */
 981
 982   /** \addtogroup parsed_xref */
 983   /** @{ */
 984   /** \brief Retrieve an xref_value using the cross-reference key */
 985 struct xref_value *gedcom_get_by_xref(const char *key);
 986   /** \brief Add a cross-reference  */
 987 struct xref_value *gedcom_add_xref(Xref_type type, const char* xrefstr,
 988                                    Gedcom_ctxt object);
 989   /** \brief Link via a cross-reference  */
 990 struct xref_value *gedcom_link_xref(Xref_type type, const char* xrefstr);
 991   /** \brief Remove a link via a cross-reference  */
 992 struct xref_value *gedcom_unlink_xref(Xref_type type, const char* xrefstr);
 993   /** \brief Delete a cross-reference  */
 994 int                gedcom_delete_xref(const char* xrefstr);
 995   /** @} */
 996
 997   /** \addtogroup write */
 998   /** @{ */
 999   /** \brief Open a file for writing GEDCOM */
1000 Gedcom_write_hndl  gedcom_write_open(const char* filename);
1001   /** \brief Close the file */
1002 int  gedcom_write_close(Gedcom_write_hndl hndl, int *total_conv_fails);
1003   /** \brief Set the encoding for writing GEDCOM files */
1004 int  gedcom_write_set_encoding(Enc_from from,
1005                                const char* charset, Encoding width,
1006                                Enc_bom bom);
1007   /** \brief Set the line terminator for writing GEDCOM files */
1008 int  gedcom_write_set_line_terminator(Enc_from from, Enc_line_end end);
1009
1010   /** \brief Write a record line */
1011 int  gedcom_write_record_str(Gedcom_write_hndl hndl,
1012                              Gedcom_rec rec, const char* xrefstr,
1013                              const char* val);
1014
1015   /** \brief Write an element line, with string value */
1016 int gedcom_write_element_str(Gedcom_write_hndl hndl, Gedcom_elt elt,
1017                              int parsed_tag, int parent_rec_or_elt,
1018                              const char* val);
1019   /** \brief Write an element line, with cross-reference value */
1020 int gedcom_write_element_xref(Gedcom_write_hndl hndl, Gedcom_elt elt,
1021                               int parsed_tag, int parent_rec_or_elt,
1022                               const struct xref_value* val);
1023
1024   /** \brief Write an element line, with date value */
1025 int gedcom_write_element_date(Gedcom_write_hndl hndl,
1026                               Gedcom_elt elt, int tag, int parent_rec_or_elt,
1027                               const struct date_value* val);
1028   /** \brief Write an element line, with age value */
1029 int gedcom_write_element_age(Gedcom_write_hndl hndl,
1030                              Gedcom_elt elt, int tag, int parent_rec_or_elt,
1031                              const struct age_value* val);
1032
1033   /** \brief Write an user defined element line, with string value */
1034 int gedcom_write_user_str(Gedcom_write_hndl hndl, int level, const char* tag,
1035                           const char* xrefstr, const char* value);
1036   /** \brief Write an user defined element line, with cross-reference value */
1037 int gedcom_write_user_xref(Gedcom_write_hndl hndl, int level, const char* tag,
1038                            const char* xrefstr, const struct xref_value* val);
1039   /** @} */
1040
1041 /* For use in gom */
1042 int        gedcom_error(const char* s, ...);
1043 int        gedcom_warning(const char* s, ...);
1044 int        gedcom_message(const char* s, ...);
1045 int        gedcom_debug_print(const char* s, ...);
1046
1047 #ifdef __cplusplus
1048 }
1049 #endif
1050
1051 #endif /* __GEDCOM_H */