is called for that tag, and when all its subordinate lines with their
tags have been processed, the "end element" callback is called for the
original tag. Since GEDCOM is hierarchical, this results in properly
-nested calls to appropriate "start element" and "end element" callbacks.<br>
+nested calls to appropriate "start element" and "end element" callbacks (note: see <a href="#Compatibility_mode">compatibility handling</a>).<br>
<br>
However, it would be typical for a genealogy program to support only
a subset of the GEDCOM standard, certainly a program that is still under
<ul>
<li>The <code>Gedcom_val</code> argument of the end callback
- is currently not used. It is there for future enhancements.</li>
+ is used to pass 'complete' values, e.g. the full text of a note. See
+ the <a href="file:///home/verthezp/src/external/gedcom-parse/doc/interface.html#Record_identifiers">interface details</a>
+ for the exact type of this argument.</li>
<li>There are also two <code>Gedcom_val</code> arguments
in the start callback for records. The first one (<code>xref</code>
) contains the <code>xref_value</code> corresponding to the cross-reference
<br>
<h3><a name="Controlling_some_settings"></a>Controlling some settings<br>
</h3>
-Note that by default the file is written in ASCII encoding (and hence e.g.
-accented characters will cause a conversion failure). You can change
+Note that by default the file is written in the same encoding as the read file was in. You can change
this by calling the following function <i>before</i> calling <code>gedcom_write_open</code>, i.e. it affects all files that are opened after it is being called:<code></code><code><br>
</code>
-<blockquote><code>int <b>gedcom_write_set_encoding</b> (const char* charset, Encoding width, Enc_bom bom);<br></code></blockquote>
+<blockquote><code>int <b>gedcom_write_set_encoding</b> (Enc_from from, const char* charset, Encoding width, Enc_bom bom);<br></code></blockquote>The <code>from</code> parameter indicates how you want the encoding to be set:<br>
+<ul>
+ <li><b><code>ENC_FROM_FILE</code></b>: The same as the read file was in (this is the default).</li>
+ <li><b><code>ENC_FROM_SYS</code></b>: Not a valid value here, see below for <code>gedcom_write_set_terminator</code><br>
+ </li>
+ <li><b><code>ENC_MANUAL</code></b>: From the values given in the following parameters.</li>
+</ul>
+When <code>ENC_FROM_FILE</code><b> </b>is selected, the other parameters in the function are ignored (they can be passed as 0). When <code>ENC_MANUAL</code> is chosen, the meaning of the other parameters is as follows:<br>
+<br>
The valid <code>charset</code> values are given in the first column in the file <code>gedcom.enc</code> in the data directory of gedcom-parse (<code>$PREFIX/share/gedcom-parse</code>).
The character sets UNICODE, ASCII and ANSEL are always supported (these
are standard for GEDCOM), as well as ANSI (not standard), but there may be
<ul>
<li><code><b>WITHOUT_BOM</b></code></li>
<li><code><b>WITH_BOM</b></code></li>
-</ul>
-For both these parameters you can pass 0 for non-UNICODE encodings, since
-that corresponds to the correct values (and is ignored anyway). The
-function returns 0 in case of success, non-zero in case of error.<br>
+</ul> For both these parameters you can pass 0 for non-UNICODE encodings,
+since that corresponds to the correct values (and is ignored anyway). The
+function returns 0 in case of success, non-zero in case of error. Note
+that you still need to pass the correct charset value for the HEAD.CHAR tag,
+otherwise you will get a warning, and the value will be forced to the correct
+value.<br>
<br>
Further, it is possible to control the kind of line terminator that is used, via the following function (also to be used before <code>gedcom_write_open</code>):<br>
-<blockquote><code>int <b>gedcom_write_set_line_terminator</b> (Enc_line_end end);<br></code></blockquote>
+<blockquote><code>int <b>gedcom_write_set_line_terminator</b> (Enc_from from, Enc_line_end end);<br></code></blockquote>The values for the <code>from</code> parameter are given above. The value <b><code>ENC_FROM_SYS</code></b>
+is valid here, and means that the normal terminator for the current system
+is used (the second parameter of the function is then ignored). This
+is the default for this setting.<br>
+<br>
The <code>end</code> parameter takes one of the following values:<br>
<ul>
- <li><b><code>END_CR</code></b>: only carriage return ("/r") (cf. Macintosh)</li>
- <li><b><code>END_LF</code></b>: only line feed ("/n") (cf. Unix, Mac OS X)</li>
- <li><b><code>END_CR_LF</code></b>: first carriage return, then line feed ("/r/n") (cf. DOS, Windows)</li>
+ <li><b><code>END_CR</code></b>: only carriage return ("/r") (system value for Macintosh)</li>
+ <li><b><code>END_LF</code></b>: only line feed ("/n") (system value for Unix, Mac OS X)</li>
+ <li><b><code>END_CR_LF</code></b>: first carriage return, then line feed ("/r/n") (system value for DOS, Windows)</li>
<li><b><code>END_LF_CR</code></b>: first line feed, then carriage return ("/n/r")</li>
</ul>
By default, this is set to the appropriate line terminator on the current
that CONT/CONC lines can be automatically taken care of. Note that
the resulting GEDCOM file should conform to the GEDCOM standard. Several
checks are built in already, and more will follow, to force this. There
-is (currently) no compatibility mode for writing GEDCOM files.<br>
+is no compatibility mode for writing GEDCOM files (and probably never will be).<br>
<br>
In general, each of the following functions expect their input in UTF-8 encoding (see also <a href="#Converting_character_sets">here</a>). If this is not the case, errors will be returned.<br>
<br>
Note that for examples of using these functions you can look at the sources for the Gedcom object model (e.g. the function <code>write_header</code> in <code>gom/header.c</code>).<br>
<h4>Records</h4>
For writing lines corresponding to records (i.e. on level 0), the following function is available:
-<blockquote><code>int <b>gedcom_write_record_str</b> (Gedcom_write_hndl hndl, Gedcom_rec rec, char* xrefstr, char* value);<br></code></blockquote>
+<blockquote><code>int <b>gedcom_write_record_str</b> (Gedcom_write_hndl hndl, Gedcom_rec rec, const char* xrefstr, const char* value);<br></code></blockquote>
The <code>hndl</code> parameter is the write handle that was returned by <code>gedcom_write_open</code>. The <code>rec</code> parameter is one of the identifiers given in the first column in <a href="interface.html#Record_identifiers">this table</a> (except <code>REC_USER</code>: see below). The <code>xrefstr</code> and <code>val</code> parameters are respectively the cross-reference key of the record (something like '<code>@FAM01@</code>'), and the value of the record line, which should be <code>NULL</code> for some record types, according to the same table.<br>
<h4>Elements</h4>
For writing lines corresponding to elements (inside records, i.e. on a level
type:
<blockquote><code>int <b>gedcom_write_element_str</b> (Gedcom_write_hndl hndl, Gedcom_elt elt, int parsed_tag, <br>
- int parent_rec_or_elt, char* value);<br>
+ int parent_rec_or_elt, const char* value);<br>
i</code><code>nt <b>gedcom_write_element_xref</b> (Gedcom_write_hndl hndl, Gedcom_elt elt, int parsed_tag, <br>
- int parent_rec_or_elt, struct xref_value*
+ int parent_rec_or_elt, const struct xref_value*
value);</code><br>
<code>int <b>gedcom_write_element_date</b> (Gedcom_write_hndl hndl, Gedcom_elt elt, int parsed_tag, <br>
- int parent_rec_or_elt, struct date_value*
+ int parent_rec_or_elt, const struct date_value*
value);</code><br>
<code>i</code><code>nt <b>gedcom_write_element_age </b> (Gedcom_write_hndl hndl, Gedcom_elt elt, int parsed_tag, <br>
- int parent_rec_or_elt, struct age_value*
+ int parent_rec_or_elt, const struct age_value*
value);</code><br>
</blockquote>
<blockquote><code></code></blockquote>
done by calling <code>gedcom_normalize_date</code> (see <a href="interface.html#date">here</a>).<br>
<h4>User-defined tags</h4>
For user-defined tags (tags starting with an underscore), there are separate functions, again depending on the data type:<code></code>
-<blockquote><code>int <b>gedcom_write_user_str</b> (Gedcom_write_hndl hndl, int level, char* tag, char* xrefstr,<br>
- char* value);<br>
-i</code><code>nt <b>gedcom_write_user_xref</b> (Gedcom_write_hndl hndl, </code><code>int level, char* tag, char* xrefstr,</code><br>
- <code>
- struct xref_value* value);</code><br>
+<blockquote><code>int <b>gedcom_write_user_str</b> (Gedcom_write_hndl hndl, int level, const char* tag, const char* xrefstr,<br>
+ const char* value);<br>
+i</code><code>nt <b>gedcom_write_user_xref</b> (Gedcom_write_hndl hndl, </code><code>int level, const char* tag, const char* xrefstr,</code><br>
+ <code>
+
+ const struct xref_value* value);</code><br>
<code></code></blockquote>
In the case of user-defined tags, the level and tag string are passed verbatim
(not controlled by the library). This allows to write any extra data
</ul>
- Currently, there is a beginning for compatibility for ftree and Lifelines (3.0.2).<br>
+ Currently, there is (some) compatibility for:<br>
+<ul>
+ <li>ftree</li>
+ <li>Lifelines (3.0.2)</li>
+ <li>Personal Ancestral File (PAF), version 2, 4 and 5</li>
+ <li>Family Origins</li>
+ <li>EasyTree</li>
+</ul>
+The following function allows to set some options for the compatibility handling:<br>
+<blockquote><code>void <b>gedcom_set_compat_options</b> (Gedcom_compat options)</code><br>
+ </blockquote>
+The parameter can be an OR'ed combination of the following options:<br>
+<ul>
+ <li><code>COMPAT_ALLOW_OUT_OF_CONTEXT</code></li>
+</ul>
+<blockquote>
+ <blockquote>In some compatibility cases, tags are coming out-of-order,
+i.e. their start element callback would have to come after the end element
+callback of the parent tag. E.g. instead of the standard GEDCOM<br>
+ <blockquote><code>1 DATE ...<br>
+2 TIME ...</code><br>
+ </blockquote>
+the genealogy program has generated something like:<br>
+ <blockquote><code>1 DATE ...<br>
+1 TIME ...</code><br>
+ </blockquote>
+This can give a problem if your end element callbacks free some resources. <br>
+ <br>
+If your program can handle elements out of context, you can enable this option.
+ By default it is disabled, and so the values of these out-of-context
+tags are lost (the parser generates a warning if this is the case). The Gedcom object model in C has this option enabled.<br>
+ </blockquote>
+</blockquote>
+<br>
+
<hr width="100%" size="2">
<h2><a name="Converting_character_sets"></a>Converting character sets</h2>
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><code>AM_PATH_GEDCOM_PARSER([<i>min_version</i>,[<i>action_if_found</i>,[<i>action_if_not_found,</i>[<i>modules</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>
+version 1.34.2, you would put in configure.in the following statement:<br>
+<blockquote><code>AM_PATH_GEDCOM_PARSER(1.34.2)</code><br>
+</blockquote>Note that version numbers now contains three parts (since version
+0.20.0: this is also the first version in which this macro is available).<br>
+<br>
+The macro also sets the variables <code>GEDCOM_CFLAGS</code> and <code>GEDCOM_LIBS</code> for use in Makefiles. Typically, this would be done as follows in a Makefile.am:<br>
+<blockquote><code>bin_programs = myprg</code><br>
+ <code>myprg_SOURCES = myprg.c foo.c bar.c<br>
+INCLUDES = @GEDCOM_CFLAGS@<br>
+LDADD = @GEDCOM_LIBS@</code></blockquote>
+If your program uses some extra modules, they can be passed as fourth argument
+in the macro, so that the CFLAGS and LIBS are correctly filled in. Currently,
+the only available module is <code>gom</code> (the Gedcom object model). For example:<br>
+<blockquote><code>AM_PATH_GEDCOM_PARSER(0.21.2, , ,gom)</code><br>
</blockquote>
To be able to use this macro in the sources of your application, you have three options:<br>
<ul>
</li>
</ul>
- The last one is equal to <code>(GEDCOM_PARSE_VERSION_MAJOR * 1000) + GEDCOM_PARSE_VERSION_MINOR.</code><br>
+ The last one is equal to <code>(GEDCOM_PARSE_VERSION_MAJOR * 1000) + GEDCOM_PARSE_VERSION_MINOR.</code> As you see, this only checked the major and minor version, not the patch number, so this is obsolete.<br>
<br>
<h3>Compilation and linking flags</h3>
-Similar to other libraries, the GEDCOM parse library installs a script <code>gedcom-config</code> to help with compilation and linking flags.<br>
+Similar to other libraries, the GEDCOM parse library installs a script <code>gedcom-config</code> to help with compilation and linking flags for programs that don't use autoconf/automake.<br>
<br>
To get compilation flags for your program, use (depending on whether you
only use the callback parser, or also the GEDCOM object model):
<br>
<br>
<br>
+<br>
+<br>
+<br>
+<br>
</body></html>
\ No newline at end of file
projects / gedcom-parse.git / blobdiff