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