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 <ul>
  15   <li><a href="#anchor">Overview</a></li>
  16   <li><a href="#Error_handling">Error handling</a></li>
  17   <li><a href="#Data_callback_mechanism">Data callback mechanism</a></li>
  18   <ul>
  19     <li><a href="#Start_and_end_callbacks">Start and end callbacks</a></li>
  20     <li><a href="#Default_callbacks">Default callbacks</a><br>
  21     </li>
  22   </ul>
  23 </ul>
  24 <hr width="100%" size="2">
  25 <h2><a name="Overview"></a>Overview<br>
  26  </h2>
  27  The GEDCOM parser library is built as a callback-based parser (comparable
  28 to the SAX interface of XML). &nbsp;It comes with:<br>
  29
  30 <ul>
  31    <li>a library (<code>libgedcom.so</code>), to be linked in the application
  32 program</li>
  33    <li>a header file (<code>gedcom.h</code>), to be used in the sources of
  34 the application program</li>
  35
  36 </ul>
  37  Next to these, there is also a data directory in <code>$PREFIX/share/gedcom-parse</code>
  38   that contains some additional stuff, but which is not immediately important
  39 at first. &nbsp;I'll leave the description of the data directory for later.<br>
  40  <br>
  41  The very simplest call of the gedcom parser is simply the following piece
  42 of code (include of the gedcom header is assumed, as everywhere in this manual):<br>
  43
  44 <blockquote><code>int result;<br>
  45  ...<br>
  46  result = <b>gedcom_parse_file</b>("myfamily.ged");<br>
  47    </code>   </blockquote>
  48  Although this will not provide much information, one thing it does is parse
  49 the entire file and return the result. &nbsp;The function returns 0 on success
  50 and 1 on failure. &nbsp;No other information is available using this function
  51 only.<br>
  52   <br>
  53 The next sections will refine this to be able to have meaningful errors and
  54 the actual data that is in the file.<br>
  55   <hr width="100%" size="2">
  56   <h2><a name="Error_handling"></a>Error handling</h2>
  57 Since this is a relatively simple topic, it is discussed before the actual
  58 callback mechanism, although it also uses a callback...<br>
  59   <br>
  60 The library can be used in several different circumstances, both terminal-based
  61 as GUI-based. &nbsp;Therefore, it leaves the actual display of the error
  62 message up to the application. &nbsp;For this, the application needs to register
  63 a callback before parsing the GEDCOM file, which will be called by the library
  64 on errors, warnings and messages.<br>
  65   <br>
  66 A typical piece of code would be:<br>
  67   <blockquote><code>void <b>my_message_handler</b> (Gedcom_msg_type type,
  68 char *msg)<br>
  69 {<br>
  70 &nbsp; ...<br>
  71 }<br>
  72 ...<br>
  73     <b>gedcom_set_message_handler</b>(my_message_handler);<br>
  74 ...<br>
  75 result = <b>gedcom_parse_file</b>("myfamily.ged");</code><br>
  76     </blockquote>
  77 In the above piece of code, <code>my_message_handler</code> is the callback
  78 that will be called for errors (<code>type=ERROR</code>), warnings (<code>
  79 type=WARNING</code>) and messages (<code>type=MESSAGE</code>). &nbsp;The
  80 callback must have the signature as in the example. &nbsp;For errors, the
  81     <code>msg</code> passed to the callback will have the format:<br>
  82     <blockquote><code>Error on line</code> <i>&lt;lineno&gt;</i>: <i>&lt;actual_message&gt;</i><br>
  83       </blockquote>
  84 Note that the entire string will be properly internationalized, and encoded
  85 in UTF-8 (see "Why UTF-8?" &nbsp;<i>LINK TBD</i>). &nbsp;Also, no newline
  86 is appended, so that the application program can use it in any way it wants.
  87 &nbsp;Warnings are similar, but use "Warning" instead of "Error". &nbsp;Messages
  88 are plain text, without any prefix.<br>
  89       <br>
  90 With this in place, the resulting code will already show errors and warnings
  91 produced by the parser, e.g. on the terminal if a simple <code>printf</code>
  92  is used in the message handler.<br>
  93       <hr width="100%" size="2">
  94       <h2><a name="Data_callback_mechanism"></a>Data callback mechanism</h2>
  95 The most important use of the parser is of course to get the data out of
  96 the GEDCOM file. &nbsp;As already mentioned, the parser uses a callback mechanism
  97 for that. &nbsp;In fact, the mechanism involves two levels.<br>
  98       <br>
  99 The primary level is that each of the sections in a GEDCOM file is notified
 100 to the application code via a "start element" callback and an "end element"
 101 callback (much like in a SAX interface for XML), i.e. when a line containing
 102 a certain tag is parsed, the "start element" callback is called for that
 103 tag, and when all its subordinate lines with their tags have been processed,
 104 the "end element" callback is called for the original tag. &nbsp;Since GEDCOM
 105 is hierarchical, this results in properly nested calls to appropriate "start
 106 element" and "end element" callbacks.<br>
 107       <br>
 108 However, it would be typical for a genealogy program to support only a subset
 109 of the GEDCOM standard, certainly a program that is still under development.
 110 &nbsp;Moreover, under GEDCOM it is allowed for an application to define its
 111 own tags, which will typically not &nbsp;be supported by another application.
 112 &nbsp;Still, in that case, data preservation is important; it would hardly
 113 be accepted that information that is not understood by a certain program
 114 is just removed.<br>
 115       <br>
 116 Therefore, the second level of callbacks involves a "default callback". &nbsp;An
 117 application needs to subscribe to callbacks for tags it does support, and
 118 need to provide a "default callback" which will be called for tags it doesn't
 119 support. &nbsp;The application can then choose to just store the information
 120 that comes via the default callback in plain textual format.<br>
 121       <br>
 122 After this introduction, let's see what the API looks like...<br>
 123       <br>
 124       <h3><a name="Start_and_end_callbacks"></a>Start and end callbacks</h3>
 125       <h4><i>Callbacks for records</i> <br>
 126       </h4>
 127 As a simple example, we will get some information from the header of a GEDCOM
 128 file. &nbsp;First, have a look at the following piece of code:<br>
 129       <blockquote><code>Gedcom_ctxt <b>my_header_start_cb</b> (int level,
 130 Gedcom_val xref, char *tag)<br>
 131 {<br>
 132 &nbsp; printf("The header starts\n");<br>
 133 &nbsp; return (Gedcom_ctxt)1;<br>
 134 }<br>
 135         <br>
 136 void <b>my_header_end_cb</b> (Gedcom_ctxt self)<br>
 137 {<br>
 138 &nbsp; printf("The header ends, context is %d\n", self); &nbsp; /* context
 139 will print as "1" */<br>
 140 }<br>
 141         <br>
 142 ...<br>
 143         <b>gedcom_subscribe_to_record</b>(REC_HEAD, my_header_start_cb, my_header_end_cb);<br>
 144 ...<br>
 145 result = <b>gedcom_parse_file</b>("myfamily.ged");</code><br>
 146         </blockquote>
 147    Using the <code>gedcom_subscribe_to_record</code> function, the application
 148 requests to use the specified callbacks as start and end callback. The end
 149 callback is optional: you can pass <code>NULL</code> if you are not interested
 150 in the end callback. &nbsp;The identifiers to use as first argument to the
 151 function (here <code>REC_HEAD</code>) are described in <i>TBD (use the header
 152 file for now...)</i>.<br>
 153         <br>
 154 From the name of the function it becomes clear that this function is specific
 155 to complete records. &nbsp;For the separate elements in records there is
 156 another function, which we'll see shortly. &nbsp;Again, the callbacks need
 157 to have the signatures as shown in the example.<br>
 158         <br>
 159 The <code>Gedcom_ctxt</code> type that is used as a result of the start callback
 160 and as an argument to the end callback is vital for passing context necessary
 161 for the application. &nbsp;This type is meant to be opaque; in fact, it's
 162 a void pointer, so you can pass anything via it. &nbsp;The important thing
 163 to know is that the context that the application returns in the start callback
 164 will be passed in the end callback as an argument, and as we will see shortly,
 165 also to all the directly subordinate elements of the record.<br>
 166         <br>
 167 The example passes a simple integer as context, but an application could
 168 e.g. pass a <code>struct</code> that will contain the information for the
 169 header. &nbsp;In the end callback, the application could then e.g. do some
 170 finalizing operations on the <code>struct</code> to put it in its database.<br>
 171         <br>
 172 (Note that the <code>Gedcom_val</code> type for the <code>xref</code> argument
 173 was not discussed, see further for this)<br>
 174         <br>
 175         <h4><i>Callbacks for elements</i></h4>
 176 We will now retrieve the SOUR field (the name of the program that wrote the
 177 file) from the header:<br>
 178         <blockquote><code>Gedcom_ctxt <b>my_header_source_start_cb</b>(Gedcom_ctxt
 179 parent,<br>
 180 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 181 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; int &nbsp; &nbsp;
 182 &nbsp; &nbsp; level,<br>
 183 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 184 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; char* &nbsp; &nbsp;
 185 &nbsp; tag,<br>
 186 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 187 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; char* &nbsp; &nbsp;
 188 &nbsp; raw_value,<br>
 189 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 190 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Gedcom_val &nbsp;parsed_value)<br>
 191 {<br>
 192 &nbsp; char *source = GEDCOM_STRING(parsed_value);<br>
 193 &nbsp; printf("This file was written by %s\n", source);<br>
 194 &nbsp; return parent;<br>
 195 }<br>
 196           <br>
 197 void <b>my_header_source_end_cb</b>(Gedcom_ctxt parent,<br>
 198 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 199 &nbsp; &nbsp; &nbsp; &nbsp;Gedcom_ctxt self,<br>
 200 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 201 &nbsp; &nbsp; &nbsp; &nbsp;Gedcom_val &nbsp;parsed_value)<br>
 202 {<br>
 203 &nbsp; printf("End of the source description\n");<br>
 204 }<br>
 205           <br>
 206 ...<br>
 207           <b>gedcom_subscribe_to_element</b>(ELT_HEAD_SOUR,<br>
 208 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 209 &nbsp; &nbsp; &nbsp; my_header_source_start_cb,<br>
 210 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
 211 &nbsp; &nbsp; &nbsp; my_header_source_end_cb);<br>
 212 ...<br>
 213 result = <b>gedcom_parse_file</b>("myfamily.ged");</code><br>
 214           </blockquote>
 215 The subscription mechanism for elements is similar, only the signatures of
 216 the callbacks differ. &nbsp;The signature for the start callback shows that
 217 the context of the parent line (e.g. the <code>struct</code> that describes
 218 the header) is passed to this start callback. &nbsp;The callback itself returns
 219 here the same context, but this can be its own context object of course.
 220 &nbsp;The end callback is called with both the context of the parent and
 221 the context of itself, which will be the same in the example.<br>
 222           <br>
 223 If we look at the other arguments of the start callback, we see the level
 224 number (the initial number of the line in the GEDCOM file), the tag (e.g.
 225 "SOUR"), and then a raw value and a parsed value. &nbsp;The raw value is
 226 just the raw string that occurs as value on the line next to the tag (in
 227 UTF-8 encoding). &nbsp;The parsed value is the meaningful value that is parsed
 228 from that raw string.<br>
 229           <br>
 230 The <code>Gedcom_val</code> type is meant to be an opaque type. &nbsp;The
 231 only thing that needs to be known about it is that it can contain specific
 232 data types, which have to be retrieved from it using pre-defined macros.
 233 &nbsp;Currently, the specific types are (with <code>val</code> of type <code>
 234 Gedcom_val</code>):<br>
 235           <br>
 236           <table cellpadding="2" cellspacing="2" border="1" width="100%">
 237             <tbody>
 238               <tr>
 239                 <td valign="top"><br>
 240                 </td>
 241                 <td valign="top"><b>type checker</b><br>
 242                 </td>
 243                 <td valign="top"><b>cast operator</b><br>
 244                 </td>
 245               </tr>
 246               <tr>
 247                 <td valign="top">null value<br>
 248                 </td>
 249                 <td valign="top"><code>GEDCOM_IS_NULL(val)</code><br>
 250                 </td>
 251                 <td valign="top">N/A<br>
 252                 </td>
 253               </tr>
 254               <tr>
 255                 <td valign="top">string<br>
 256                 </td>
 257                 <td valign="top"><code>GEDCOM_IS_STRING(val)</code><br>
 258                 </td>
 259                 <td valign="top"><code>char* str = GEDCOM_STRING(val);</code><br>
 260                 </td>
 261               </tr>
 262               <tr>
 263                 <td valign="top">date<br>
 264                 </td>
 265                 <td valign="top"><code>GEDCOM_IS_DATE(val)</code><br>
 266                 </td>
 267                 <td valign="top"><code>struct date_value dv = GEDCOM_DATE(val)
 268 ;</code><br>
 269                 </td>
 270               </tr>
 271             </tbody>
 272           </table>
 273           <br>
 274 The null value is used for when the GEDCOM spec doesn't allow a value, or
 275 when an optional value is allowed but none is given.<br>
 276 &nbsp; <br>
 277 The string value is the most general used value currently, for all those
 278 values that don't have a more specific meaning. &nbsp;In essence, the value
 279 that is returned by GEDCOM_STRING is always the same as the raw_value passed
 280 to the start callback, and is thus in fact redundant.<br>
 281           <br>
 282 The date value is used for all elements that return a date. &nbsp;(<i>Description
 283 of struct date_value TBD: look in the header file for the moment</i>).<br>
 284           <br>
 285 The type checker returns a true or a false value according to the type of
 286 the value, but this is in principle only necessary in the rare circumstances
 287 that two types are possible, or where an optional value can be provided.
 288 &nbsp;In most cases, the type is fixed for a specific tag (<i>types per tag
 289 to be described</i>).<br>
 290           <br>
 291 Some extra notes:<br>
 292           <ul>
 293             <li>The <code>Gedcom_val</code> argument of the end callback
 294 is currently not used. &nbsp;It is there for future enhancements.</li>
 295             <li>There is also a <code>Gedcom_val</code> argument in the start
 296 callback for records. &nbsp;This argument is currently a string value giving
 297 the pointer in string form.</li>
 298           </ul>
 299           <h3><a name="Default_callbacks"></a>Default callbacks<br>
 300           </h3>
 301 TO BE COMPLETED<br>
 302           <hr width="100%" size="2">$Id$<br>
 303        $Name$<br>
 304    <br>
 305
 306           </body>
 307           </html>