Added some initial documentation.
[gedcom-parse.git] / 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>