X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;f=doc%2Finterface.html;h=5e9d8b23cb980f4eaef7fa1002067c3e40331fc8;hb=a5bd4c3c89f5cb433a615c436947b8b0f44c3661;hp=74d5aadd0886d5fac92f5dcaa297705f68efd05a;hpb=1316fee80103b38bf682f5c626c0abaa525db41c;p=gedcom-parse.git diff --git a/doc/interface.html b/doc/interface.html index 74d5aad..5e9d8b2 100644 --- a/doc/interface.html +++ b/doc/interface.html @@ -1,11 +1,7 @@ - - - - Libgedcom interface details +Libgedcom interface details + - - - +

Libgedcom interface details


@@ -18,9 +14,11 @@
  • Gedcom_val types
  • @@ -827,9 +825,8 @@ element start callback.
    ELT_SUB_INDIV_RESI,
    ELT_SUB_INDIV_BIRT,
    ELT_SUB_INDIV_GEN,
    - ELT_SUB_INDIV_ADOP
    -
    -
    + ELT_SUB_INDIV_ADOP,
    +ELT_SUB_INDIV_EVEN
    STRING
    @@ -917,9 +914,8 @@ element start callback.
    ELT_SUB_INDIV_RESI,
    ELT_SUB_INDIV_BIRT,
    ELT_SUB_INDIV_GEN,
    - ELT_SUB_INDIV_ADOP
    -
    -
    + ELT_SUB_INDIV_ADOP,
    +ELT_SUB_INDIV_EVEN
    STRING
    @@ -931,7 +927,14 @@ element start callback.
    REC_INDI
    - XREF_PTR(INDI)
    + XREF_PTR(FAM),
    +XREF_PTR(INDI),
    +XREF_PTR(NOTE),
    +XREF_PTR(OBJE),
    +XREF_PTR(REPO),
    +XREF_PTR(SOUR),
    +XREF_PTR(SUBM),
    +XREF_PTR(SUBN)

    @@ -1049,8 +1052,8 @@ element start callback.
    ELT_SUB_INDIV_RESI,
    ELT_SUB_INDIV_BIRT,
    ELT_SUB_INDIV_GEN,
    - ELT_SUB_INDIV_ADOP
    -
    + ELT_SUB_INDIV_ADOP,
    +ELT_SUB_INDIV_EVEN
    STRING
    @@ -1066,10 +1069,8 @@ element start callback.
    ELT_SUB_INDIV_RESI,
    ELT_SUB_INDIV_BIRT,
    ELT_SUB_INDIV_GEN,
    - ELT_SUB_INDIV_ADOP
    -
    -
    -
    + ELT_SUB_INDIV_ADOP,
    +ELT_SUB_INDIV_EVEN
    DATE
    @@ -1085,11 +1086,10 @@ element start callback.
    ELT_SUB_INDIV_RESI,
    ELT_SUB_INDIV_BIRT,
    ELT_SUB_INDIV_GEN,
    - ELT_SUB_INDIV_ADOP

    -
    -
    + ELT_SUB_INDIV_ADOP,
    +ELT_SUB_INDIV_EVEN
    - STRING
    + AGE
    @@ -1103,9 +1103,8 @@ element start callback.
    ELT_SUB_INDIV_RESI,
    ELT_SUB_INDIV_BIRT,
    ELT_SUB_INDIV_GEN,
    - ELT_SUB_INDIV_ADOP

    -
    -
    + ELT_SUB_INDIV_ADOP,
    +ELT_SUB_INDIV_EVEN
    STRING
    @@ -1121,9 +1120,8 @@ element start callback.
    ELT_SUB_INDIV_RESI,
    ELT_SUB_INDIV_BIRT,
    ELT_SUB_INDIV_GEN,
    - ELT_SUB_INDIV_ADOP

    -
    -
    + ELT_SUB_INDIV_ADOP,
    +ELT_SUB_INDIV_EVEN
    STRING
    @@ -1172,7 +1170,7 @@ element start callback.
    ELT_SUB_FAM_EVT_HUSB,
    ELT_SUB_FAM_EVT_WIFE
    - STRING
    + AGE
    @@ -1468,6 +1466,7 @@ element start callback.
    ELT_SUB_INDIV_BIRT,
    ELT_SUB_INDIV_GEN,
    ELT_SUB_INDIV_ADOP,
    +ELT_SUB_INDIV_EVEN,
    ELT_SUB_SOUR
    NULL
    @@ -1521,6 +1520,7 @@ element start callback.
    ELT_SUB_INDIV_BIRT,
    ELT_SUB_INDIV_GEN,
    ELT_SUB_INDIV_ADOP,
    +ELT_SUB_INDIV_EVEN,
    ELT_SUB_LIO_BAPL,
    ELT_SUB_LIO_SLGC,
    ELT_SUB_LSS_SLGS,
    @@ -1615,7 +1615,12 @@ element start callback.
    ELT_SUB_FAM_EVT,
    ELT_SUB_FAM_EVT_EVEN,
    ELT_SUB_INDIV_ATTR,
    - ELT_SUB_INDIV_RESI

    + ELT_SUB_INDIV_RESI
    , +
    +ELT_SUB_INDIV_BIRT,
    + ELT_SUB_INDIV_GEN,
    + ELT_SUB_INDIV_ADOP,
    +ELT_SUB_INDIV_EVEN

    STRING
    @@ -1644,6 +1649,7 @@ element start callback.
    ELT_SUB_INDIV_BIRT,
    ELT_SUB_INDIV_GEN,
    ELT_SUB_INDIV_ADOP,
    +ELT_SUB_INDIV_EVEN,
    ELT_SUB_LIO_BAPL,
    ELT_SUB_LIO_SLGC,
    ELT_SUB_LSS_SLGS,
    @@ -1824,6 +1830,14 @@ element start callback.
    struct date_value dv = GEDCOM_DATE(val); + age
    + + GEDCOM_IS_AGE(val)
    + + struct age_value age = GEDCOM_AGE(val);
    + + + xref pointer
    GEDCOM_IS_XREF_PTR(val)
    @@ -1847,17 +1861,17 @@ tag.
     
    The string value is the most general used value currently, for all those values that don't have a more specific meaning.  In essence, -the value that is returned by GEDCOM_STRING is always the same as the -raw_value passed to the start callback, and is thus in fact redundant.
    +the value that is returned by GEDCOM_STRING(val) is always the same as the +raw_value passed to the start callback, and is thus in fact redundant.

    The date value is used for all elements that return a date.  See -here for the definition.
    +here for the definition.

    The xref value is for cross-references between records in the file.  See -here for the definition.
    +here for the definition.

    -

    struct date_value

    +

    struct date_value

    This struct describes a date as given in the GEDCOM file, and has the following definition:
    @@ -1865,7 +1879,7 @@ raw_value passed to the start callback, and is thus in fact redundant.
      Date_value_type  type;
      struct date      date1;
      struct date      date2;
    -   char              phrase[MAX_PHRASE_LEN +   char             phrase[MAX_PHRASE_LEN + 1];
    };
    @@ -1985,7 +1999,7 @@ raw_value passed to the start callback, and is thus in fact redundant.

    -

    struct date
    +

    struct date

    The date1 and date2 also have a strict syntax:
    @@ -2078,18 +2092,100 @@ day number.  Two cases can be distinguished:
    -
    These are represented by 2 serial day numbers ( - sdn1 and sdn2) and a Date_type equal + +
    These are represented by 2 serial day numbers (sdn1 and sdn2) and a Date_type equal to DATE_BOUNDED.
    -
    +
    + For example, the Gregorian date "MAR 1990" is represented by the serial day numbers for "1 MAR 1990" and "31 MAR 1990", and the Gregorian date "1990" is represented by the serial day numbers for "1 JAN 1990" and "31 DEC 1990".  Similarly for the other calendar types.
    +
    + +
    +
    +

    struct age_value

    + + This struct describes an age as given in the GEDCOM file, and has the + following definition:
    + + +
    struct age_value {
    +   Age_type      type;
    +   Age_modifier  mod;
    +   int           years;
    +  int           months;
    +  int           days;
    +   char          phrase[MAX_PHRASE_LEN + + 1];
    + };

    +
    +
    -
    + -

    struct xref_value

    + + It depends on the first member, the type, which members are actually + relevant:
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Age_type
    +
    Meaning
    +
    Relevant members
    +
    AGE_UNRECOGNIZED
    +
    format not recognized, full raw value in phrase
    +
    phrase
    +
    AGE_CHILD
    +
    the indication 'CHILD'
    +
    mod
    +
    AGE_INFANT
    +
    the indication 'INFANT'
    +
    mod
    +
    AGE_STILLBORN
    +
    the indication 'STILLBORN'
    +
    mod
    +
    AGE_NUMERIC
    +
    an indication in years, months and/or days (each can be -1 if not given)
    +
    mod, years, months, days
    +
    +
    +The modifier can be one of the following:
    + +
    +

    struct xref_value

    + This struct represents a cross-reference in the GEDCOM file (but note that the Gedcom_val contains a pointer to such a struct, not the struct itself).  It is defined as:
    @@ -2112,7 +2208,9 @@ be one of:
  • XREF_REPO
  • XREF_SOUR
  • XREF_SUBM
  • -
  • XREF_SUBN
  • +
  • XREF_SUBN
  • XREF_ANY (if the type is not known, see below)
    +
  • +
  • XREF_USER (for application-specific cross-references)
  • @@ -2123,17 +2221,75 @@ can be filled by the application with an object (of any type) that corresponds with the cross-reference, and then later extracted when the cross-reference is used or defined again in the file.  This relieves the application from the burden of maintaining the mapping between cross-references and objects.
    +
    +The value XREF_ANY is used when the type of the object is not +immediately known: it has to come from further information.  This is +the case in an association (ELT_SUB_ASSO): the type is then given by the TYPE subtag.

    - The parser checks whether all cross-references that are used are defined -(if not, an error is produced) and whether all cross-references that are defined -are used (if not, a warning is produced).  It also checks whether the -type of the cross-reference is the same on definition and use (if not, an -error is produced).
    -
    + The parser checks whether all cross-references that are used are defined + (if not, an error is produced) and whether all cross-references that are +defined are used (if not, a warning is produced).  It also checks whether +the type of the cross-reference is the same on definition and use (if not, +an error is produced).  The first two checks are done at the end of +the parsing, because cross-references can be defined after their usage in +GEDCOM.
    +
    +The following functions are available to manipulate xref_value objects:
    +
    struct xref_value* gedcom_get_by_xref (const char *key)
    +
     Retrieve an xref_value by its key.  Returns NULL if the given key isn't a valid cross-reference key (see below) or isn't used.
    +
    + struct xref_value* gedcom_add_xref (Xref_type type, const char* key, Gedcom_ctxt object)
    +
    Add an xref_value of the given type (see list above), with the given key, to the given object, with a use count equal to 0.  Returns the new xref_value if success.  Returns NULL in one of the following cases:
    + +
    + int gedcom_delete_xref (const char* key)
    +
    +
    Delete the xref_value corresponding to the given key.  Returns 0 if success.  Returns 1 in one of the following cases:
    + +
    + struct xref_value* gedcom_link_xref (Xref_type type, const char* key)
    +struct xref_value* gedcom_unlink_xref (Xref_type type, const char* key)

    +
    Declare the xref_value corresponding to the given key as being +used/no longer used (linked to or unlinked) as the given type.  The +use of these functions is not mandatory, but it can aid in spotting places in the code where xref_value objects are deleted while they are still referenced.
    +
    +Returns the xref_value object if success, and its use count is incremented/decremented.  Returns NULL in one of the following cases:
    + +
    +
    +
    +
    + +A cross-reference key must be a string of maximum 22 characters, of the following format:
    + +An example would thus be: "@This is an xref_val@".
    +
    $Id$
    $Name$

    - - +
    +
    +
    +
    +
    + \ No newline at end of file