<li><a href="#Start_and_end_callbacks">Start and end callbacks</a></li>
<li><a href="#Default_callbacks">Default callbacks</a></li>
- </ul><li><a href="#C_object_model">C object model</a></li>
- <ul>
- <li><a href="#Main_functions">Main functions</a></li>
- <li><a href="#Object_model_structure">Object model structure</a></li>
- <li><a href="#User_data">User data</a><br>
- </li>
- </ul>
-
- <li><a href="#Other_API_functions">Other API functions</a></li>
+ </ul><li><a href="#Other_API_functions">Other API functions</a></li>
<ul>
<li><a href="#Debugging">Debugging</a></li>
<li><a href="#Support_for_configure.in">Support for configure.in</a><br>
<br>
</li>
- <li><a href="interface.html">Interface details of the callback parser</a></li><li><a href="gomxref.html">C object model details</a><br>
+ <li><a href="interface.html">Interface details of the callback parser</a></li><li><a href="gom.html">C object model</a><br>
</li>
on the linking of the program as the last option, so that its initialization
code is run first. In the case of using the C object model, the linking
options should be: <code>-lgedcom_gom -lgedcom</code><br>
- <br>
- The next sections will refine this piece of code to be able to have
+ <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>
+ <br>
+The next sections will refine this piece of code to be able to have
meaningful errors and the actual data that is in the file.<br>
<hr width="100%" size="2">
<hr width="100%" size="2">
<h2><a name="Data_callback_mechanism"></a>Data callback mechanism</h2>
The most important use of the parser is of course to get the data
-out of the GEDCOM file. This section focuses on the callback mechanism (see the <a href="#C_object_model">next section</a> for the C object model). In fact, the mechanism involves two levels.<br>
+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>
<br>
The primary level is that each of the sections in a GEDCOM file is
notified to the application code via a "start element" callback and an
of the "upper" tags has been subscribed upon.<br>
-<hr width="100%" size="2"><br>
-<h2><a name="C_object_model"></a>C object model</h2>
-In the GEDCOM object model, all the data is immediately available after calling <code>gom_parse_file()</code>. For this, an entire model based on C structs is used. These structs are documented <a href="gomxref.html">here</a>,
-and follow the GEDCOM syntax quite closely. Each of the records in
-a GEDCOM file are modelled by a separate struct, and some common sub-structures
-have their own struct definition.<br>
-<br>
-<h3><a name="Main_functions"></a>Main functions<br>
-</h3>
-The following functions are available to get at these structs:<br>
-<ul>
- <li>First, there are two functions to get the header record and the submission
-record (there can be only one of them in a GEDCOM file):<br>
- <blockquote><code>struct header* gom_get_header();<br>
-struct submission* gom_get_submission();<br>
- </code></blockquote>
- </li>
- <li>Further, for each of the other records, there are two functions, one
-to get the first of such records, and one to get a record via its cross-reference
-tag in the GEDCOM file:<br>
- <blockquote><code>struct XXX* gom_get_first_XXX();<br>
-struct XXX* gom_get_XXX_by_xref(char* xref);</code><br>
- </blockquote>
- </li>
-</ul>
-<blockquote>The XXX stands for one of the following: <code>family, </code><code>individual, multimedia, note, repository, source, submitter, user_rec</code>.<br>
-</blockquote>
-<h3><a name="Object_model_structure"></a>Object model structure<br>
-</h3>
-All records of a certain type are linked together in a linked list. The
-above functions only give access to the first record of each linked list.
- The others can be accessed by traversing the linked list via the <code>next</code> member of the structs. This means that e.g. the following piece of code will traverse the linked list of family records:<br>
-<blockquote><code>struct family* fam;<br>
- <br>
-for (fam = gom_get_first_family() ; fam ; fam = fam->next) {<br>
- ...<br>
-}</code><br>
-</blockquote>
-The <code>next</code> member of the last element in the list is guaranteed to have the <code>NULL</code> value.<br>
-<br>
-Actually, the linked list is a doubly-linked list: each record also has a <code>previous</code> member. But for implementation reasons the behaviour of this <code>previous</code> member on the edges of the linked list will not be guaranteed, i.e. it can be circular or terminated with <code>NULL</code>, no assumptions can be made in the application code.<br>
-<br>
-This linked-list model applies also to all sub-structures of the main record structs, i.e. each struct that has a <code>next </code>and <code>previous</code>
-member following the above conventions. This means that the following
-piece of code traverses all children of a family (see the details of the
-different structs <a href="gomxref.html">here</a>):<br>
-<blockquote><code>struct family* fam = ...;<br>
- <br>
-struct xref_list* xrl;<br>
-for (xrl = fam->children ; xrl ; xrl = xrl->next) {<br>
- ...<br>
-}</code> <br>
-</blockquote>
-Note that all character strings in the object model are encoded in UTF-8 (<a href="file:///home/verthezp/src/external/gedcom-parse/doc/encoding.html">Why UTF-8?</a>).<br>
-<h3><a name="User_data"></a>User data</h3>
-Each of the structs has an extra member called <code>extra</code> (of type <code>struct user_data*</code>).
- This gathers all non-standard GEDCOM tags within the scope of the struct
-in a flat linked list, no matter what the internal structure of the non-standard
-tags is. Each element of the linked list has:<br>
-<ul>
- <li>a level: the level number in the GEDCOM file</li>
- <li>a tag: the tag given in the GEDCOM file</li>
- <li>a value: the value, which can be a string value or a cross-reference value (one of the two will be non-NULL)<br>
- </li>
-</ul>
-This way, none of the information in the GEDCOM file is lost, even the non-standard information.<br>
<hr width="100%" size="2">
<h2><a name="Other_API_functions"></a>Other API functions<br>
<br>
The source distribution of <code>
-gedcom-parse</code> contains an example implementation (<code>utf8-locale.c</code>
- and <code> utf8-locale.h</code> in the "t" subdirectory of the top directory).
- Feel free to use it in your source code (it is not part of the library,
-and it isn't installed anywhere, so you need to take over the source and
-header file in your application). <br>
+gedcom-parse</code> contains an a library implementing help functions for UTF-8 encoding (<code></code>see
+the "utf8" subdirectory of the top directory). Feel free to use
+ it in your source code. It isn't installed anywhere, so you need
+to take over the source and header files in your application. Note that on
+some systems it uses libcharset, which is also included in this subdirectory.
+ <br>
<br>
- Its interface is:<br>
+ Its interface contains first of all the following two help functions:<br>
<blockquote>
- <pre><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>
+ <pre><code>int <b>is_utf8_string</b> (char *input);<br>int <b>utf8_strlen</b> (char *input);<br></code></pre></blockquote>The
+first one returns 1 if the given input is a valid UTF-8 string, it returns
+0 otherwise, the second gives the number of UTF-8 characters in the given
+input. Note that the second function assumes that the input is valid
+UTF-8, and gives unpredictable results if it isn't.<br>
+<br>
+For conversion, the following functions are available:<br>
+<blockquote>
+ <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>
+</blockquote>
+<blockquote>
</blockquote>
+
Both functions return a pointer to a static buffer that is overwritten
on each call. To function properly, the application must first set
the locale using the <code>setlocale</code> function (the second step detailed
<blockquote>
<pre><code>iconv_close(iconv_handle);<br></code></pre>
</blockquote>
- </blockquote>
- The example implementation
- mentioned above grows the output buffer dynamically and outputs "?" for characters
+ </blockquote>
+ The example implementation
+mentioned above grows the output buffer dynamically and outputs "?" for characters
that can't be converted.<br>
<hr width="100%" size="2">
-<h2><a name="Support_for_configure.in"></a>Support for configure.in</h2>
- Programs using the GEDCOM parser library and using autoconf to configure
- their sources can use the following statements in configure.in (the example
- is checking for gedcom-parse, version 1.34):<br>
-
-<blockquote><code>AC_CHECK_LIB(gedcom, gedcom_parse_file,,<br>
- AC_MSG_ERROR(Cannot
- find libgedcom: Please install gedcom-parse))<br>
- AC_MSG_CHECKING(for libgedcom version)<br>
- AC_TRY_RUN([<br>
- #include <stdio.h><br>
- #include <stdlib.h><br>
- #include <gedcom.h><br>
- int<br>
- main()<br>
- {<br>
- if (GEDCOM_PARSE_VERSION >= 1034) exit(0);<br>
- exit(1);<br>
- }],<br>
- ac_gedcom_version_ok='yes',<br>
- ac_gedcom_version_ok='no',<br>
- ac_gedcom_version_ok='no')<br>
- if test "$ac_gedcom_version_ok" = 'yes' ; then<br>
- AC_MSG_RESULT(ok)<br>
- else<br>
- AC_MSG_RESULT(not ok)<br>
- AC_MSG_ERROR(You need at least version 1.34 of gedcom-parse)<br>
- fi</code><br>
- </blockquote>
- There are three preprocessor symbols defined for version checks in the
- header:<br>
+<h2><a name="Support_for_configure.in"></a>Support for configure.in</h2>There
+is a macro available for use in configure.in for applications that are using
+autoconf to configure their sources. The following macro checks whether
+the Gedcom parser library is available and whether its version is high enough:<br>
+<blockquote><code>AM_LIB_GEDCOM_PARSER([<i>major</i>,[<i>minor</i>,[<i>patch</i>]]])</code><br>
+</blockquote>
+All the arguments are optional and default to 0. E.g. to check for
+version 1.34, you would put in configure.in the following statement:<br>
+<blockquote><code>AM_LIB_GEDCOM_PARSER(1,34)</code><br>
+</blockquote>
+To be able to use this macro in the sources of your application, you have three options:<br>
+<ul>
+ <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>
+ <br>
+ </li>
+ <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>
+ <br>
+ </li>
+ <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>
+ </li>
+</ul>
+<br>
+There are three preprocessor symbols defined for version checks in the
+ header (but their direct use is deprecated: please use the macro above):<br>
<ul>
<li><code>GEDCOM_PARSE_VERSION_MAJOR</code></li>
</ul>
The last one is equal to <code>(GEDCOM_PARSE_VERSION_MAJOR * 1000) + GEDCOM_PARSE_VERSION_MINOR.</code><br>
+
<hr width="100%" size="2">
<pre> </pre>
+<br>
+<br>
+<br>
+<br>
<br>
<br>
</body></html>
\ No newline at end of file
projects / gedcom-parse.git / blobdiff