doc/usage.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4   <title>Using the GEDCOM parser library</title>
   5
   6   <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
   7 </head>
   8   <body>
   9
  10 <h1 align="center">Using the GEDCOM parser library</h1>
  11     <br>
  12
  13 <h2>Index</h2>
  14
  15 <ul>
  16      <li><a href="#anchor">Overview</a></li>
  17      <li><a href="#Error_handling">Error handling</a></li>
  18      <li><a href="#Data_callback_mechanism">Data callback mechanism</a></li>
  19
  20   <ul>
  21        <li><a href="#Start_and_end_callbacks">Start and end callbacks</a></li>
  22        <li><a href="#Default_callbacks">Default callbacks</a></li>
  23
  24   </ul>
  25     <li><a href="#Other_API_functions">Other API functions</a></li>
  26
  27   <ul>
  28       <li><a href="#Debugging">Debugging</a></li>
  29       <li><a href="#Error_treatment">Error treatment</a></li>
  30       <li><a href="#Compatibility_mode">Compatibility mode</a></li>
  31
  32   </ul>
  33     <li><a href="interface.html">Interface details</a><br>
  34        </li>
  35
  36 </ul>
  37
  38 <hr width="100%" size="2">
  39 <h2><a name="Overview"></a>Overview<br>
  40     </h2>
  41     The GEDCOM parser library is built as a callback-based parser (comparable
  42   to the SAX interface of XML). &nbsp;It comes with:<br>
  43
  44 <ul>
  45       <li>a library (<code>libgedcom.so</code>), to be linked in the application
  46   program</li>
  47       <li>a header file (<code>gedcom.h</code>), to be used in the sources
  48  of  the application program</li>
  49   <li>a header file (<code>gedcom-tags.h</code>) that is also installed,
  50 but that is automatically included via <code>gedcom.h</code><br>
  51   </li>
  52
  53 </ul>
  54     Next to these, there is also a data directory in <code>$PREFIX/share/gedcom-parse</code>
  55      that contains some additional stuff, but which is not immediately important
  56   at first. &nbsp;I'll leave the description of the data directory for later.<br>
  57     <br>
  58     The very simplest call of the gedcom parser is simply the following piece
  59   of code (include of the gedcom header is assumed, as everywhere in this
  60 manual):<br>
  61
  62 <blockquote><code>int result;<br>
  63     ...<br>
  64     result = <b>gedcom_parse_file</b>("myfamily.ged");<br>
  65       </code>   </blockquote>
  66     Although this will not provide much information, one thing it does is
  67 parse  the entire file and return the result. &nbsp;The function returns 0
  68 on success  and 1 on failure. &nbsp;No other information is available using
  69 this function  only.<br>
  70      <br>
  71    The next sections will refine this to be able to have meaningful errors
  72  and the actual data that is in the file.<br>
  73
  74   <hr width="100%" size="2">
  75   <h2><a name="Error_handling"></a>Error handling</h2>
  76    Since this is a relatively simple topic, it is discussed before the actual
  77  callback mechanism, although it also uses a callback...<br>
  78      <br>
  79    The library can be used in several different circumstances, both terminal-based
  80  as GUI-based. &nbsp;Therefore, it leaves the actual display of the error
  81 message up to the application. &nbsp;For this, the application needs to register
  82 a callback before parsing the GEDCOM file, which will be called by the library
  83  on errors, warnings and messages.<br>
  84      <br>
  85    A typical piece of code would be:<br>
  86
  87   <blockquote><code>void <b>my_message_handler</b> (Gedcom_msg_type type,
  88  char *msg)<br>
  89    {<br>
  90    &nbsp; ...<br>
  91    }<br>
  92    ...<br>
  93        <b>gedcom_set_message_handler</b>(my_message_handler);<br>
  94    ...<br>
  95    result = <b>gedcom_parse_file</b>("myfamily.ged");</code><br>
  96        </blockquote>
  97    In the above piece of code, <code>my_message_handler</code> is the callback
  98  that will be called for errors (<code>type=ERROR</code>), warnings (<code>
  99   type=WARNING</code>) and messages (<code>type=MESSAGE</code>). &nbsp;The
 100 callback must have the signature as in the example. &nbsp;For errors, the
 101     <code> msg</code> passed to the callback will have the format:<br>
 102
 103     <blockquote><code>Error on line</code> <i>&lt;lineno&gt;</i>: <i>&lt;actual_message&gt;</i><br>
 104          </blockquote>
 105    Note that the entire string will be properly internationalized, and encoded
 106  in UTF-8 (see "Why UTF-8?" &nbsp;<i>LINK TBD</i>). &nbsp;Also, no newline
 107  is appended, so that the application program can use it in any way it wants.
 108  &nbsp;Warnings are similar, but use "Warning" instead of "Error". &nbsp;Messages
 109  are plain text, without any prefix.<br>
 110          <br>
 111    With this in place, the resulting code will already show errors and warnings
 112  produced by the parser, e.g. on the terminal if a simple <code>printf</code>
 113     is used in the message handler.<br>
 114
 115       <hr width="100%" size="2">
 116       <h2><a name="Data_callback_mechanism"></a>Data callback mechanism</h2>
 117    The most important use of the parser is of course to get the data out
 118 of  the GEDCOM file. &nbsp;As already mentioned, the parser uses a callback
 119 mechanism  for that. &nbsp;In fact, the mechanism involves two levels.<br>
 120          <br>
 121    The primary level is that each of the sections in a GEDCOM file is notified
 122  to the application code via a "start element" callback and an "end element"
 123  callback (much like in a SAX interface for XML), i.e. when a line containing
 124  a certain tag is parsed, the "start element" callback is called for that
 125 tag, and when all its subordinate lines with their tags have been processed,
 126 the "end element" callback is called for the original tag. &nbsp;Since GEDCOM
 127  is hierarchical, this results in properly nested calls to appropriate "start
 128  element" and "end element" callbacks.<br>
 129          <br>
 130    However, it would be typical for a genealogy program to support only a
 131 subset  of the GEDCOM standard, certainly a program that is still under development.
 132  &nbsp;Moreover, under GEDCOM it is allowed for an application to define its
 133  own tags, which will typically not &nbsp;be supported by another application.
 134  &nbsp;Still, in that case, data preservation is important; it would hardly
 135  be accepted that information that is not understood by a certain program
 136 is just removed.<br>
 137          <br>
 138    Therefore, the second level of callbacks involves a "default callback".
 139  &nbsp;An application needs to subscribe to callbacks for tags it does support,
 140  and need to provide a "default callback" which will be called for tags it
 141  doesn't support. &nbsp;The application can then choose to just store the
 142 information that comes via the default callback in plain textual format.<br>
 143          <br>
 144    After this introduction, let's see what the API looks like...<br>
 145          <br>
 146
 147       <h3><a name="Start_and_end_callbacks"></a>Start and end callbacks</h3>
 148
 149       <h4><i>Callbacks for records</i> <br>
 150          </h4>
 151    As a simple example, we will get some information from the header of a
 152 GEDCOM  file. &nbsp;First, have a look at the following piece of code:<br>
 153
 154       <blockquote><code>Gedcom_ctxt <b>my_header_start_cb</b> (int level,
 155  Gedcom_val xref, char *tag, int parsed_tag)<br>
 156    {<br>
 157    &nbsp; printf("The header starts\n");<br>
 158    &nbsp; return (Gedcom_ctxt)1;<br>
 159    }<br>
 160            <br>
 161    void <b>my_header_end_cb</b> (Gedcom_ctxt self)<br>
 162    {<br>
 163    &nbsp; printf("The header ends, context is %d\n", self); &nbsp; /* context
 164  will print as "1" */<br>
 165    }<br>
 166            <br>
 167    ...<br>
 168            <b>gedcom_subscribe_to_record</b>(REC_HEAD, my_header_start_cb,
 169  my_header_end_cb);<br>
 170    ...<br>
 171    result = <b>gedcom_parse_file</b>("myfamily.ged");</code><br>
 172            </blockquote>
 173       Using the <code>gedcom_subscribe_to_record</code> function, the application
 174  requests to use the specified callbacks as start and end callback. The end
 175  callback is optional: you can pass <code>NULL</code> if you are not interested
 176  in the end callback. &nbsp;The identifiers to use as first argument to the
 177  function (here <code>REC_HEAD</code>) are described in the <a href="interface.html#Record_identifiers">
 178   interface details</a>.<br>
 179            <br>
 180    From the name of the function it becomes clear that this function is specific
 181  to complete records. &nbsp;For the separate elements in records there is
 182 another function, which we'll see shortly. &nbsp;Again, the callbacks need
 183 to have the signatures as shown in the example.<br>
 184            <br>
 185    The <code>Gedcom_ctxt</code> type that is used as a result of the start
 186  callback and as an argument to the end callback is vital for passing context
 187  necessary for the application. &nbsp;This type is meant to be opaque; in
 188 fact, it's a void pointer, so you can pass anything via it. &nbsp;The important
 189  thing to know is that the context that the application returns in the start
 190  callback will be passed in the end callback as an argument, and as we will
 191  see shortly, also to all the directly subordinate elements of the record.<br>
 192         <br>
 193 The <code>tag</code> is the GEDCOM tag in string format, the <code>parsed_tag</code>
 194  is an integer, for which symbolic values are defined as <code>TAG_HEAD,</code>
 195  <code>TAG_SOUR,</code> <code>TAG_DATA,</code> ... and <code>USERTAG </code><code></code>
 196 for the application-specific tags. &nbsp;These values are defined in the
 197 header <code>gedcom-tags.h</code> that is installed, and included via <code>
 198 gedcom.h</code> (so no need to include <code>gedcom-tags.h</code> yourself).<br>
 199            <br>
 200    The example passes a simple integer as context, but an application could
 201  e.g. pass a <code>struct</code> that will contain the information for the
 202  header. &nbsp;In the end callback, the application could then e.g. do some
 203  finalizing operations on the <code>struct</code> to put it in its database.<br>
 204            <br>
 205    (Note that the <code>Gedcom_val</code> type for the <code>xref</code>
 206 argument  was not discussed, see further for this)<br>
 207            <br>
 208
 209         <h4><i>Callbacks for elements</i></h4>
 210    We will now retrieve the SOUR field (the name of the program that wrote
 211  the file) from the header:<br>
 212
 213         <blockquote><code>Gedcom_ctxt <b>my_header_source_start_cb</b>(Gedcom_ctxt
 214  parent,<br>
 215    &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 216 &nbsp;  &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; int &nbsp;
 217 &nbsp;  &nbsp; &nbsp; level,<br>
 218    &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 219 &nbsp;  &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; char* &nbsp;
 220 &nbsp;  &nbsp; tag,<br>
 221    &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 222 &nbsp;  &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; char* &nbsp;
 223 &nbsp;  &nbsp; raw_value,<br>
 224 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 225 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; int &nbsp; &nbsp;
 226 &nbsp; &nbsp; parsed_tag,<br>
 227    &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 228 &nbsp;  &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Gedcom_val
 229 &nbsp;parsed_value)<br>
 230    {<br>
 231    &nbsp; char *source = GEDCOM_STRING(parsed_value);<br>
 232    &nbsp; printf("This file was written by %s\n", source);<br>
 233    &nbsp; return parent;<br>
 234    }<br>
 235              <br>
 236    void <b>my_header_source_end_cb</b>(Gedcom_ctxt parent,<br>
 237    &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 238 &nbsp;  &nbsp; &nbsp; &nbsp; &nbsp;Gedcom_ctxt self,<br>
 239    &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 240 &nbsp;  &nbsp; &nbsp; &nbsp; &nbsp;Gedcom_val &nbsp;parsed_value)<br>
 241    {<br>
 242    &nbsp; printf("End of the source description\n");<br>
 243    }<br>
 244              <br>
 245    ...<br>
 246              <b>gedcom_subscribe_to_element</b>(ELT_HEAD_SOUR,<br>
 247    &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 248 &nbsp;  &nbsp; &nbsp; &nbsp; my_header_source_start_cb,<br>
 249    &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 250 &nbsp;  &nbsp; &nbsp; &nbsp; my_header_source_end_cb);<br>
 251    ...<br>
 252    result = <b>gedcom_parse_file</b>("myfamily.ged");</code><br>
 253              </blockquote>
 254    The subscription mechanism for elements is similar, only the signatures
 255  of the callbacks differ. &nbsp;The signature for the start callback shows
 256  that the context of the parent line (e.g. the <code>struct</code> that describes
 257  the header) is passed to this start callback. &nbsp;The callback itself returns
 258  here the same context, but this can be its own context object of course.
 259 &nbsp;The end callback is called with both the context of the parent and
 260 the context of itself, which will be the same in the example. &nbsp;Again,
 261 the list of identifiers to use as a first argument for the subscription function
 262 are detailed in the <a href="interface.html#Element_identifiers">interface
 263 details</a> .<br>
 264              <br>
 265    If we look at the other arguments of the start callback, we see the level
 266  number (the initial number of the line in the GEDCOM file), the tag (e.g.
 267  "SOUR"), and then a raw value, a parsed tag and a parsed value. &nbsp;The
 268 raw value is just the raw string that occurs as value on the line next to
 269 the tag (in UTF-8 encoding). &nbsp;The parsed value is the meaningful value
 270 that is parsed from that raw string. &nbsp;The parsed tag is described in
 271 the section for record callbacks.<br>
 272              <br>
 273    The <code>Gedcom_val</code> type is meant to be an opaque type. &nbsp;The
 274  only thing that needs to be known about it is that it can contain specific
 275  data types, which have to be retrieved from it using pre-defined macros.
 276 &nbsp;These data types are described in the <a href="interface.html#Gedcom_val_types">
 277   interface details</a>.           <br>
 278             <br>
 279    Some extra notes:<br>
 280
 281           <ul>
 282                <li>The <code>Gedcom_val</code> argument of the end callback
 283  is currently not used. &nbsp;It is there for future enhancements.</li>
 284                <li>There is also a <code>Gedcom_val</code> argument in the
 285  start callback for records. &nbsp;This argument is currently a string value
 286  giving the pointer in string form.</li>
 287
 288           </ul>
 289
 290           <h3><a name="Default_callbacks"></a>Default callbacks<br>
 291              </h3>
 292    As described above, an application doesn't always implement the entire
 293 GEDCOM spec, and application-specific tags may have been added by other applications.
 294  &nbsp;To preserve this extra data anyway, a default callback can be registered
 295  by the application, as in the following example:<br>
 296
 297           <blockquote><code>void <b>my_default_cb</b> (Gedcom_ctxt parent,
 298  int level, char* tag, char* raw_value, int parsed_tag)<br>
 299   {<br>
 300   &nbsp; ...<br>
 301   }<br>
 302               <br>
 303   ...<br>
 304               <b>gedcom_set_default_callback</b>(my_default_cb);<br>
 305   ...<br>
 306   result = <b>gedcom_parse_file</b>("myfamily.ged");</code><br>
 307               </blockquote>
 308              This callback has a similar signature as the previous ones,
 309 but  it doesn't contain a parsed value. &nbsp;However, it does contain the
 310 parent  context, that was returned by the application for the most specific
 311 containing  tag that the application supported.<br>
 312               <br>
 313   Suppose e.g. that this callback is called for some tags in the header that
 314  are specific to some other application, then our application could make
 315 sure  that the parent context contains the struct or object that represents
 316 the  header, and use the default callback here to add the level, tag and
 317 raw_value  as plain text in a member of that struct or object, thus preserving
 318 the information.  &nbsp;The application can then write this out when the
 319 data is saved again  in a GEDCOM file. &nbsp;To make it more specific, consider
 320 the following example:<br>
 321
 322             <blockquote><code>struct header {<br>
 323   &nbsp; char* source;<br>
 324   &nbsp; ...<br>
 325   &nbsp; char* extra_text;<br>
 326   };<br>
 327                 <br>
 328   Gedcom_ctxt my_header_start_cb(int level, Gedcom_val xref, char* tag, int
 329 parsed_tag)<br>
 330   {<br>
 331   &nbsp; struct header head = my_make_header_struct();<br>
 332   &nbsp; return (Gedcom_ctxt)head;<br>
 333   }<br>
 334                 <br>
 335   void my_default_cb(Gedcom_ctxt parent, int level, char* tag, char* raw_value,
 336 int parsed_tag)<br>
 337   {<br>
 338   &nbsp; struct header head = (struct header)parent;<br>
 339   &nbsp; my_header_add_to_extra_text(head, level, tag, raw_value);<br>
 340   }<br>
 341                 <br>
 342   gedcom_set_default_callback(my_default_cb);<br>
 343   gedcom_subscribe_to_record(REC_HEAD, my_header_start, NULL);<br>
 344   ...<br>
 345   result = gedcom_parse_file(filename);</code><br>
 346                 </blockquote>
 347   Note that the default callback will be called for any tag that isn't specifically
 348  subscribed upon by the application, and can thus be called in various contexts.
 349  &nbsp;For simplicity, the example above doesn't take this into account (the
 350                <code>parent</code> could be of different types, depending
 351 on the context).<br>
 352
 353               <hr width="100%" size="2">
 354               <h2><a name="Other_API_functions"></a>Other API functions<br>
 355                 </h2>
 356   Although the above describes the basic interface of libgedcom, there are
 357  some other functions that allow to customize the behaviour of the library.
 358  &nbsp;These will be explained in the current section.<br>
 359
 360               <h3><a name="Debugging"></a>Debugging</h3>
 361   The library can generate various debugging output, not only from itself,
 362  but also the debugging output generated by the yacc parser. &nbsp;By default,
 363  no debugging output is generated, but this can be customized using the following
 364  function:<br>
 365
 366               <blockquote><code>void <b>gedcom_set_debug_level</b> (int level,
 367  FILE* trace_output)</code><br>
 368                   </blockquote>
 369   The <code>level</code> can be one of the following values:<br>
 370
 371                 <ul>
 372                     <li>0: &nbsp;no debugging information (this is the default)</li>
 373                     <li>1: &nbsp;only debugging information from libgedcom
 374  itself</li>
 375                     <li>2: &nbsp;debugging information from libgedcom and
 376 yacc</li>
 377
 378                 </ul>
 379   If the <code>trace_output</code> is <code>NULL</code>, debugging information
 380  will be written to <code>stderr</code>, otherwise the given file handle
 381 is  used (which must be open).<br>
 382                   <br>
 383
 384                 <h3><a name="Error_treatment"></a>Error treatment</h3>
 385   One of the previous sections already described the callback to be registered
 386  to get error messages. &nbsp;The library also allows to customize what happens
 387  on an error, using the following function:<br>
 388
 389                 <blockquote><code>void <b>gedcom_set_error_handling</b> (Gedcom_err_mech
 390  mechanism)</code><br>
 391                     </blockquote>
 392   The <code>mechanism</code> can be one of:<br>
 393
 394                   <ul>
 395                       <li><code>IMMED_FAIL</code>: immediately fail the parsing
 396  on an error (this is the default)</li>
 397                       <li><code>DEFER_FAIL</code>: continue parsing after
 398 an error, but return a failure code eventually</li>
 399                       <li><code>IGNORE_ERRORS</code>: continue parsing after
 400  an error, return success always</li>
 401
 402                   </ul>
 403   This doesn't influence the generation of error or warning messages, only
 404  the behaviour of the parser and its return code.<br>
 405                     <br>
 406
 407                   <h3><a name="Compatibility_mode"></a>Compatibility mode<br>
 408                     </h3>
 409   Applications are not necessarily true to the GEDCOM spec (or use a different
 410  version than 5.5). &nbsp;The intention is that the library is resilient
 411 to  this, and goes in compatibility mode for files written by specific programs
 412  (detected via the HEAD.SOUR tag). &nbsp;This compatibility mode can be enabled
 413  and disabled via the following function:<br>
 414
 415                   <blockquote><code>void <b>gedcom_set_compat_handling</b>
 416    (int enable_compat)</code><br>
 417                       </blockquote>
 418   The argument can be:<br>
 419
 420                     <ul>
 421                         <li>0: disable compatibility mode</li>
 422                         <li>1: allow compatibility mode (this is the default)<br>
 423                         </li>
 424
 425                     </ul>
 426   Note that, currently, no actual compatibility code is present, but this
 427 is on the to-do list.<br>
 428
 429                     <hr width="100%" size="2">
 430                     <pre>$Id$<br>$Name$<br></pre>
 431
 432                     <pre>                    </pre>
 433
 434                     </body>
 435                     </html>