1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><title>Using the GEDCOM parser library</title>
4 <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1"></head><body text="#000000" bgcolor="#ffffff" link="#000099" vlink="#990099" alink="#000099">
6 <h1 align="center">Using the GEDCOM parser library</h1>
12 <li><a href="#anchor">Overview</a></li>
13 <li><a href="#Error_handling">Error handling</a></li>
14 <li><a href="#Data_callback_mechanism">Data callback mechanism</a></li>
17 <li><a href="#Start_and_end_callbacks">Start and end callbacks</a></li>
18 <li><a href="#Default_callbacks">Default callbacks</a></li>
20 </ul><li><a href="#Other_API_functions">Other API functions</a></li>
23 <li><a href="#Debugging">Debugging</a></li>
24 <li><a href="#Error_treatment">Error treatment</a></li>
25 <li><a href="#Compatibility_mode">Compatibility mode</a></li>
28 <li><a href="#Converting_character_sets">Converting character sets</a></li>
29 <li><a href="#Support_for_configure.in">Support for configure.in</a><br>
32 <li><a href="interface.html">Interface details of the callback parser</a></li><li><a href="gom.html">C object model</a><br>
38 <hr width="100%" size="2">
39 <h2><a name="Overview"></a>Overview<br>
41 parser library provides two interfaces. At the one hand, it can be
42 used as a callback-based parser (comparable to the SAX interface of
43 XML); at the other hand, the parser can be used to convert the GEDCOM file
44 into an object model (comparable to the DOM interface of XML). It comes
48 <li>a library (<code>libgedcom.so</code>), to be linked in the
49 application program, which implements the callback parser</li>
50 <li>a header file (<code>gedcom.h</code>), to be used in the sources
51 of the application program</li>
52 <li>a header file (<code>gedcom-tags.h</code>) that is also installed,
53 but that is automatically included via <code>gedcom.h</code></li></ul>Additionally, if you want to use the GEDCOM C object model, the following should be used (note that <code>libgedcom.so</code> is also needed in this case, because the object model uses the callback parser internally):<br>
55 <li>a library (<code>libgedcom_gom.so</code>), to be linked in the application program, which implements the C object model</li>
56 <li>a header file (<code>gom.h</code>), to be used in the sources of the application program<br>
62 Next to these, there is also a data directory in <code>$PREFIX/share/gedcom-parse</code>
63 that contains some additional stuff, but which is not immediately
64 important at first. I'll leave the description of the data directory
67 The very simplest call of the gedcom callback parser is simply the following
68 piece of code (include of the <code>gedcom.h</code> header is assumed, as everywhere
71 <blockquote><code>int result;<br>
73 <b>gedcom_init</b>();<br>
75 result = <b>gedcom_parse_file</b>("myfamily.ged");<br>
77 Although this will not provide much information, one thing it does
78 is parse the entire file and return the result. The function returns
79 0 on success and 1 on failure. No other information is available
80 using this function only.<br>
82 Alternatively, programs using the C object model should use the following (in this case, the inclusion of both <code>gedcom.h</code> and <code>gom.h</code> is required):<br>
84 <blockquote><code>int result;<br>
86 <b>gedcom_init</b>();<br>
88 result = <b>gom_parse_file</b>("myfamily.ged");<br>
90 The call to <code>gom_parse_file</code> will build the C object model, which is then a complete representation of the GEDCOM file.<br>
92 No matter which of the interfaces you use, the call to <code>gedcom_init</code>() should be one of the first calls
93 in your program. The requirement is that it should come before the first
94 call to <code>iconv_open</code> (part of the generic character set conversion
95 feature) in the program, either by your program itself, or indirectly by
96 the library calls it makes. Practically, it should e.g. come before
97 any calls to any GTK functions, because GTK uses <code>iconv_open</code>
98 in its initialization.<br>
100 For the same reason it is also advised to put
101 the <code>-lgedcom</code> option
102 on the linking of the program as the last option, so that its initialization
103 code is run first. In the case of using the C object model, the linking
104 options should be: <code>-lgedcom_gom -lgedcom</code><br>
105 <br>The function <code>gedcom_init()</code> also initializes locale handling by calling <code>setlocale(LC_ALL, "")</code>, in case the application would not do this (it doesn't hurt for the application to do the same).<br>
107 The next sections will refine this piece of code to be able to have
108 meaningful errors and the actual data that is in the file.<br>
110 <hr width="100%" size="2">
111 <h2><a name="Error_handling"></a>Error handling</h2>The library can be used in several different circumstances, both
112 terminal-based as GUI-based. Therefore, it leaves the actual display
113 of the error message up to the application. For this, the application
114 needs to register a callback before parsing the GEDCOM file, which will
115 be called by the library on errors, warnings and messages.<br>
117 A typical piece of code would be (<code>gom_parse_file</code> would be called in case the C object model is used):<br>
119 <blockquote><code>void <b>my_message_handler</b> (Gedcom_msg_type type,
125 <b>gedcom_set_message_handler</b>(my_message_handler);<br>
127 result = <b>gedcom_parse_file</b>("myfamily.ged");</code><br>
129 In the above piece of code, <code>my_message_handler</code> is the
130 callback that will be called for errors (<code>type=ERROR</code>), warnings
131 (<code>type=WARNING</code>) and messages (<code>type=MESSAGE</code>). The
132 callback must have the signature as in the example. For errors,
133 the <code> msg</code> passed to the callback will have the format:<br>
135 <blockquote><code>Error on line</code> <i><lineno></i>: <i><actual_message></i><br>
137 Note that the entire string will be properly internationalized, and
138 encoded in UTF-8 (<a href="encoding.html">Why UTF-8?</a>). Also,
139 no newline is appended, so that the application program can use it in any
140 way it wants. Warnings are similar, but use "Warning" instead of "Error".
141 Messages are plain text, without any prefix.<br>
143 With this in place, the resulting code will already show errors and
144 warnings produced by the parser, e.g. on the terminal if a simple <code>
145 printf</code> is used in the message handler.<br>
147 <hr width="100%" size="2">
148 <h2><a name="Data_callback_mechanism"></a>Data callback mechanism</h2>
149 The most important use of the parser is of course to get the data
150 out of the GEDCOM file. This section focuses on the callback mechanism (see <a href="gom.html">here</a> for the C object model). In fact, the mechanism involves two levels.<br>
152 The primary level is that each of the sections in a GEDCOM file is
153 notified to the application code via a "start element" callback and an
154 "end element" callback (much like in a SAX interface for XML), i.e. when
155 a line containing a certain tag is parsed, the "start element" callback
156 is called for that tag, and when all its subordinate lines with their
157 tags have been processed, the "end element" callback is called for the
158 original tag. Since GEDCOM is hierarchical, this results in properly
159 nested calls to appropriate "start element" and "end element" callbacks.<br>
161 However, it would be typical for a genealogy program to support only
162 a subset of the GEDCOM standard, certainly a program that is still under
163 development. Moreover, under GEDCOM it is allowed for an application
164 to define its own tags, which will typically not be supported by
165 another application. Still, in that case, data preservation is important;
166 it would hardly be accepted that information that is not understood by
167 a certain program is just removed.<br>
169 Therefore, the second level of callbacks involves a "default callback".
170 An application needs to subscribe to callbacks for tags it does support,
171 and need to provide a "default callback" which will be called for tags
172 it doesn't support. The application can then choose to just store
173 the information that comes via the default callback in plain textual format.<br>
175 After this introduction, let's see what the API looks like...<br>
178 <h3><a name="Start_and_end_callbacks"></a>Start and end callbacks</h3>
180 <h4><i>Callbacks for records</i> <br>
182 As a simple example, we will get some information from the header
183 of a GEDCOM file. First, have a look at the following piece of code:<br>
185 <blockquote><code>Gedcom_ctxt <b>my_header_start_cb</b> (Gedcom_rec rec,<br>
186 int level, <br>
187
188 Gedcom_val xref, <br>
189
190 char *tag, <br>
191
192 char *raw_value,<br>
193
194 int parsed_tag, <br>
195
196 Gedcom_val parsed_value)<br>
198 printf("The header starts\n");<br>
199 return (Gedcom_ctxt)1;<br>
202 void <b>my_header_end_cb</b> (Gedcom_rec rec, Gedcom_ctxt self)<br>
204 printf("The header ends, context is %d\n", (int)self);
205 /* context will print as "1" */<br>
209 <b>gedcom_subscribe_to_record</b>(REC_HEAD, my_header_start_cb,
210 my_header_end_cb);<br>
212 result = <b>gedcom_parse_file</b>("myfamily.ged");</code><br>
214 Using the <code>gedcom_subscribe_to_record</code> function, the
215 application requests to use the specified callbacks as start and end
216 callback. The end callback is optional: you can pass <code>NULL</code>
217 if you are not interested in the end callback. The identifiers
218 to use as first argument to the function (here <code>REC_HEAD</code>)
219 are described in the <a href="interface.html#Record_identifiers"> interface
220 details</a> . These are also passed as first argument in the callbacks (the <code>Gedcom_rec</code> argument).<br>
222 From the name of the function it becomes clear that this function
223 is specific to complete records. For the separate elements in records
224 there is another function, which we'll see shortly. Again, the callbacks
225 need to have the signatures as shown in the example.<br>
227 The <code>Gedcom_ctxt</code> type that is used as a result of the
228 start callback and as an argument to the end callback is vital for passing
229 context necessary for the application. This type is meant to be opaque;
230 in fact, it's a void pointer, so you can pass anything via it. The
231 important thing to know is that the context that the application returns
232 in the start callback will be passed in the end callback as an argument,
233 and as we will see shortly, also to all the directly subordinate elements
236 The <code>tag</code> is the GEDCOM tag in string format, the <code>parsed_tag</code>
237 is an integer, for which symbolic values are defined as <code>TAG_HEAD,</code>
238 <code>TAG_SOUR,</code> <code>TAG_DATA,</code> ... and <code>USERTAG
239 </code><code></code> for the application-specific tags. These values
240 are defined in the header <code>gedcom-tags.h</code> that is installed,
241 and included via <code> gedcom.h</code> (so no need to include <code>gedcom-tags.h</code>
244 The example passes a simple integer as context, but an application
245 could e.g. pass a <code>struct</code> (or an object in a C++ application)
246 that will contain the information for the header. In the end callback,
247 the application could then e.g. do some finalizing operations on the
248 <code> struct</code> to put it in its database.<br>
250 (Note that the <code>Gedcom_val</code> type for the <code>xref</code>
251 and <code>parsed_value</code> arguments was not discussed, see further
255 <h4><i>Callbacks for elements</i></h4>
256 We will now retrieve the SOUR field (the name of the program that
257 wrote the file) from the header:<br>
259 <blockquote><code>Gedcom_ctxt <b>my_header_source_start_cb</b>(Gedcom_elt elt,<br>
260
261 Gedcom_ctxt
263
264 int
265 level,<br>
266
267 char*
268 tag,<br>
269
270 char*
271 raw_value,<br>
272
273 int
274 parsed_tag,<br>
275
276 Gedcom_val
277 parsed_value)<br>
279 char *source = GEDCOM_STRING(parsed_value);<br>
280 printf("This file was written by %s\n", source);<br>
281 return parent;<br>
284 void <b>my_header_source_end_cb</b>(Gedcom_elt elt,<br>
285 Gedcom_ctxt parent,<br>
286
287 Gedcom_ctxt self,<br>
288
289 Gedcom_val parsed_value)<br>
291 printf("End of the source description\n");<br>
295 <b>gedcom_subscribe_to_element</b>(ELT_HEAD_SOUR,<br>
296
297 my_header_source_start_cb,<br>
298
299 my_header_source_end_cb);<br>
301 result = <b>gedcom_parse_file</b>("myfamily.ged");</code><br>
303 The subscription mechanism for elements is similar, only the signatures
304 of the callbacks differ. The signature for the start callback shows
305 that the context of the parent line (here e.g. the <code>struct</code>
306 that describes the header) is passed to this start callback. The
307 callback itself returns here in this example the same context, but this
308 can be its own context object of course. The end callback is called
309 with both the context of the parent and the context of itself, which in this
310 example will be the same. Again, the list of identifiers to use as
311 a first argument for the subscription function are detailed in the <a href="interface.html#Element_identifiers"> interface details</a> . Again, these are passed as first argument in the callback (the <code>Gedcom_elt</code> argument).<br>
313 If we look at the other arguments of the start callback, we see the
314 level number (the initial number of the line in the GEDCOM file), the tag
315 (e.g. "SOUR"), and then a raw value, a parsed tag and a parsed value. The
316 raw value is just the raw string that occurs as value on the line next
317 to the tag (in UTF-8 encoding). The parsed value is the meaningful
318 value that is parsed from that raw string. The parsed tag is described
319 in the section for record callbacks above.<br>
321 The <code>Gedcom_val</code> type is meant to be an opaque type. The
322 only thing that needs to be known about it is that it can contain specific
323 data types, which have to be retrieved from it using pre-defined macros.
324 These data types are described in the <a href="interface.html#Gedcom_val_types"> interface details</a>.
327 Some extra notes:<br>
331 <li>The <code>Gedcom_val</code> argument of the end callback
332 is currently not used. It is there for future enhancements.</li>
333 <li>There are also two <code>Gedcom_val</code> arguments
334 in the start callback for records. The first one (<code>xref</code>
335 ) contains the <code>xref_value</code> corresponding to the cross-reference
336 (or <code>NULL</code> if there isn't one), the second one (<code>parsed_value</code>
337 ) contains the value that is parsed from the <code>raw_value</code>. See
338 the <a href="interface.html#Record_identifiers">interface details</a>
345 <h3><a name="Default_callbacks"></a>Default callbacks<br>
347 As described above, an application doesn't always implement the entire
348 GEDCOM spec, and application-specific tags may have been added by other
349 applications. To preserve this extra data anyway, a default callback
350 can be registered by the application, as in the following example:<br>
352 <blockquote><code>void <b>my_default_cb</b> (Gedcom_elt elt, Gedcom_ctxt parent, int level,
353 char* tag, char* raw_value, int parsed_tag)<br>
359 <b>gedcom_set_default_callback</b>(my_default_cb);<br>
361 result = <b>gedcom_parse_file</b>("myfamily.ged");</code><br>
363 This callback has a similar signature as the previous ones,
364 but it doesn't contain a parsed value. However, it does contain the
365 parent context, that was returned by the application for the most specific
366 containing tag that the application supported.<br>
368 Suppose e.g. that this callback is called for some tags in the header
369 that are specific to some other application, then our application could
370 make sure that the parent context contains the struct or object that represents
371 the header, and use the default callback here to add the level, tag and
372 raw_value as plain text in a member of that struct or object, thus preserving
373 the information. The application can then write this out when the
374 data is saved again in a GEDCOM file. To make it more specific, consider
375 the following example:<br>
377 <blockquote><code>struct header {<br>
378 char* source;<br>
380 char* extra_text;<br>
383 Gedcom_ctxt my_header_start_cb(Gedcom_rec rec, int level, Gedcom_val xref, char* tag,
385
386 int parsed_tag, Gedcom_val parsed_value)<br>
388 struct header head = my_make_header_struct();<br>
389 return (Gedcom_ctxt)head;<br>
392 void my_default_cb(Gedcom_elt elt, Gedcom_ctxt parent, int level, char* tag, char*
393 raw_value, int parsed_tag)<br>
395 struct header head = (struct header)parent;<br>
396 my_header_add_to_extra_text(head, level, tag, raw_value);<br>
399 gedcom_set_default_callback(my_default_cb);<br>
400 gedcom_subscribe_to_record(REC_HEAD, my_header_start, NULL);<br>
402 result = gedcom_parse_file(filename);</code><br>
404 Note that the default callback will be called for any tag that isn't
405 specifically subscribed upon by the application, and can thus be called
406 in various contexts. For simplicity, the example above doesn't take
407 this into account (the <code>parent</code> could be of different
408 types, depending on the context).<br>
410 Note also that the default callback is not called when the parent context
411 is <code>NULL</code><code></code>. This is e.g. the case if none
412 of the "upper" tags has been subscribed upon.<br>
415 <hr width="100%" size="2">
417 <h2><a name="Other_API_functions"></a>Other API functions<br>
420 Although the above describes the basic interface of the gedcom parser, there
421 are some other functions that allow to customize the behaviour of the library.
422 These will be explained in the current section.<br>
425 <h3><a name="Debugging"></a>Debugging</h3>
426 The library can generate various debugging output, not only from itself,
427 but also the debugging output generated by the yacc parser. By default,
428 no debugging output is generated, but this can be customized using the
429 following function:<br>
432 <blockquote><code>void <b>gedcom_set_debug_level</b> (int level, FILE*
433 trace_output)</code><br>
435 The <code>level</code> can be one of the following values:<br>
439 <li>0: no debugging information (this is the
441 <li>1: only debugging information from libgedcom
443 <li>2: debugging information from libgedcom
448 If the <code>trace_output</code> is <code>NULL</code>, debugging information
449 will be written to <code>stderr</code>, otherwise the given file handle
450 is used (which must be open).<br>
454 <h3><a name="Error_treatment"></a>Error treatment</h3>
455 One of the previous sections already described the callback to be
456 registered to get error messages. The library also allows to customize
457 what happens on an error, using the following function:<br>
460 <blockquote><code>void <b>gedcom_set_error_handling</b> (Gedcom_err_mech
461 mechanism)</code><br>
463 The <code>mechanism</code> can be one of:<br>
467 <li><code>IMMED_FAIL</code>: immediately fail
468 the parsing on an error (this is the default)</li>
469 <li><code>DEFER_FAIL</code>: continue parsing
470 after an error, but return a failure code eventually</li>
471 <li><code>IGNORE_ERRORS</code>: continue parsing
472 after an error, return success always</li>
476 This doesn't influence the generation of error or warning messages,
477 only the behaviour of the parser and its return code.<br>
481 <h3><a name="Compatibility_mode"></a>Compatibility mode<br>
483 Applications are not necessarily true to the GEDCOM spec (or use a
484 different version than 5.5). The intention is that the library is
485 resilient to this, and goes in compatibility mode for files written by specific
486 programs (detected via the HEAD.SOUR tag). This compatibility mode
487 can be enabled and disabled via the following function:<br>
490 <blockquote><code>void <b>gedcom_set_compat_handling</b> (int enable_compat)</code><br>
492 The argument can be:<br>
496 <li>0: disable compatibility mode</li>
497 <li>1: allow compatibility mode (this is the
503 Currently, there is a beginning for compatibility for ftree and Lifelines (3.0.2).<br>
505 <hr width="100%" size="2">
506 <h2><a name="Converting_character_sets"></a>Converting character sets</h2>
507 All strings passed by the GEDCOM parser to the application are in UTF-8
508 encoding. Typically, an application needs to convert this to something
509 else to be able to display it.<br>
511 The most common case is that the output character set is controlled by
512 the <code>locale</code> mechanism (i.e. via the <code>LANG</code>, <code>
513 LC_ALL</code> or <code>LC_CTYPE</code> environment variables), which also
514 controls the <code>gettext</code> mechanism in the application. <br>
518 The source distribution of <code>
519 gedcom-parse</code> contains an a library implementing help functions for UTF-8 encoding (<code></code>see
520 the "utf8" subdirectory of the top directory). Feel free to use
521 it in your source code. It isn't installed anywhere, so you need
522 to take over the source and header files in your application. Note that on
523 some systems it uses libcharset, which is also included in this subdirectory.
526 Its interface contains first of all the following two help functions:<br>
529 <pre><code>int <b>is_utf8_string</b> (char *input);<br>int <b>utf8_strlen</b> (char *input);<br></code></pre></blockquote>The
530 first one returns 1 if the given input is a valid UTF-8 string, it returns
531 0 otherwise, the second gives the number of UTF-8 characters in the given
532 input. Note that the second function assumes that the input is valid
533 UTF-8, and gives unpredictable results if it isn't.<br>
535 For conversion, the following functions are available:<br>
537 <pre><code></code><code>char *<b>convert_utf8_to_locale</b> (char *input, int *conv_failures);<br>char *<b>convert_locale_to_utf8</b> (char *input);<br></code></pre>
542 Both functions return a pointer to a static buffer that is overwritten
543 on each call. To function properly, the application must first set
544 the locale using the <code>setlocale</code> function (the second step detailed
545 below). All other steps given below, including setting up and closing
546 down the conversion handles, are transparantly handled by the two functions.
549 If you pass a pointer to an integer to the first function, it will be
550 set to the number of conversion failures, i.e. characters that couldn't
551 be converted; you can also just pass <code>NULL</code> if you are not interested
552 (note that usually, the interesting information is just whether there <i>
553 were</i> conversion failures or not, which is then given by the integer
554 being bigger than zero or not). The second function doesn't need this,
555 because any locale can be converted to UTF-8.<br>
557 You can change the "?" that is output for characters that can't be converted
558 to any string you want, using the following function before the conversion
562 <pre><code>void <b>convert_set_unknown</b> (const char *unknown);</code></pre>
565 If you want to have your own functions for it instead of this example
566 implementation, the following steps need to be taken by the application
567 (more detailed info can be found in the info file of the GNU libc library
568 in the "Generic Charset Conversion" section under "Character Set Handling"
569 or online <a href="http://www.gnu.org/manual/glibc-2.2.3/html_chapter/libc_6.html#SEC99">
573 <li>inclusion of some headers:</li>
579 <pre><code>#include <locale.h> /* for setlocale */<br>#include <langinfo.h> /* for nl_langinfo */<br>#include <iconv.h> /* for iconv_* functions */<br></code></pre>
584 <li>set the program's current locale to what
585 the user configured in the environment:</li>
591 <pre><code>setlocale(LC_ALL, "");</code><br></pre>
596 <li>open a conversion handle for conversion
597 from UTF-8 to the character set of the current locale (once for the entire
604 <pre><code>iconv_t iconv_handle;<br>...<br>iconv_handle = iconv_open(nl_langinfo(CODESET), "UTF-8");</code><br>if (iconv_handle == (iconv_t) -1)<br> /* signal an error */<br></pre>
609 <li>then, every string can be converted
610 using the following:</li>
616 <pre><code>/* char* in_buf is the input buffer, size_t in_len is its length */<br>/* char* out_buf is the output buffer, size_t out_len is its length */<br><br>size_t nconv;<br>char *in_ptr = in_buf;<br>char *out_ptr = out_buf;<br>nconv = iconv(iconv_handle, &in_ptr, &in_len, &out_ptr, &out_len);</code></pre>
620 <blockquote>If the output buffer is not big enough, <code>iconv</code> will
621 return -1 and set <code>errno</code> to <code>E2BIG</code>. Also,
622 the <code>in_ptr</code> and <code>out_ptr</code> will point just after
623 the last successfully converted character in the respective buffers, and
624 the <code> in_len</code> and <code>out_len</code> will be updated to show
625 the remaining lengths. There can be two strategies here:<br>
628 <li>Make sure from the beginning
629 that the output buffer is big enough. However, it's difficult to find
630 an absolute maximum length in advance, even given the length of the input
634 <li>Do the conversion in several
635 steps, growing the output buffer each time to make more space, and calling
636 <code>iconv</code> consecutively until the conversion is complete.
637 This is the preferred way (a function could be written to encapsulate
641 Another error case is when the conversion was unsuccessful (if one of
642 the characters can't be represented in the target character set). The
643 <code> iconv</code> function will then also return -1 and set <code>errno</code>
644 to <code>EILSEQ</code>; the <code>in_ptr</code> will point to the character
645 that couldn't be converted. In that case, again two strategies are
649 <li>Just fail the conversion,
650 and show an error. This is not very user friendly, of course.<br>
653 <li>Skip over the character that
654 can't be converted and append a "?" to the output buffer, then call <code>
655 iconv</code> again. Skipping over a UTF-8 character is fairly simple,
656 as follows from the <a href="http://www.cl.cam.ac.uk/%7Emgk25/unicode.html#utf-8">encoding rules</a>
664 <li>if the first byte is in
665 binary 0xxxxxxx, then the character is only one byte long, just skip over
669 <li>if the first byte is in
670 binary 11xxxxxx, then skip over that byte and all bytes 10xxxxxx that follow.<br>
679 <li>eventually, the conversion
680 handle needs to be closed (when the program exits):<br>
687 <pre><code>iconv_close(iconv_handle);<br></code></pre>
690 The example implementation
691 mentioned above grows the output buffer dynamically and outputs "?" for characters
692 that can't be converted.<br>
695 <hr width="100%" size="2">
697 <h2><a name="Support_for_configure.in"></a>Support for configure.in</h2>There
698 is a macro available for use in configure.in for applications that are using
699 autoconf to configure their sources. The following macro checks whether
700 the Gedcom parser library is available and whether its version is high enough:<br>
701 <blockquote><code>AM_LIB_GEDCOM_PARSER([<i>major</i>,[<i>minor</i>,[<i>patch</i>]]])</code><br>
703 All the arguments are optional and default to 0. E.g. to check for
704 version 1.34, you would put in configure.in the following statement:<br>
705 <blockquote><code>AM_LIB_GEDCOM_PARSER(1,34)</code><br>
707 To be able to use this macro in the sources of your application, you have three options:<br>
709 <li>Put the file <code>m4/gedcom.m4</code> in your autoconf data directory (i.e. the path given by '<code>aclocal --print-ac-dir</code>', usually <code>/usr/share/aclocal</code>). You can do this automatically by going into the m4 subdirectory and typing '<code>make install-m4</code>'.<br>
712 <li>If you're using autoconf, but not automake, copy the contents of <code>m4/gedcom.m4</code> in the <code>aclocal.m4</code> file in your sources.<br>
715 <li>If you're using automake, copy the contents of <code>m4/gedcom.m4</code> in the <code>acinclude.m4</code> file in your sources.<br>
719 There are three preprocessor symbols defined for version checks in the
720 header (but their direct use is deprecated: please use the macro above):<br>
723 <li><code>GEDCOM_PARSE_VERSION_MAJOR</code></li>
724 <li><code>GEDCOM_PARSE_VERSION_MINOR</code></li>
725 <li><code>GEDCOM_PARSE_VERSION</code><br>
729 The last one is equal to <code>(GEDCOM_PARSE_VERSION_MAJOR * 1000) + GEDCOM_PARSE_VERSION_MINOR.</code><br>
732 <hr width="100%" size="2">
734 <pre><font size="-1">$Id$<br>$Name$</font><br></pre>
projects / gedcom-parse.git / blob