</ul>
<li><a href="#Other_functions">Modifying the object model</a></li>
<ul>
- <li><a href="#Manipulating_strings">Manipulating strings</a></li>
+ <li><a href="#Manipulating_strings">Manipulating strings</a></li><li><a href="#Adding_and_removing_records">Adding and removing records</a></li>
+ <li><a href="#Adding_rem_and_moving_xref">Adding, removing and moving cross-references</a><br>
+ </li>
+ <li><a href="#Adding_removing_and_moving">Adding, removing and moving sub-structures</a><br>
+ </li>
+
</ul><li><a href="#Writing_the_object_model_to_file">Writing the object model to file</a><br>
<br>
</li>
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* <b>gom_get_first_XXX</b>();<br>
-struct XXX* <b>gom_get_XXX_by_xref</b>(char* xref);</code><br>
+struct XXX* <b>gom_get_XXX_by_xref</b>(const char* xref);</code><br>
</blockquote>
</li>
</ul>
This way, none of the information in the GEDCOM file is lost, even the non-standard information.<br>
<br>
<hr width="100%" size="2">
-<h2><a name="Other_functions"></a>Modifying the object model</h2>Currently, there are only functions available to modify strings in the model (and the date manipulation functions described <a href="interface.html#date_value">here</a>).
- In principle it is possible to add new records, notes, ... yourself,
-but you have to know what you are doing, because you should keep the model
-consistent. In the next release, functions will be available to add,
-remove and modify anything in the model.<br>
+<h2><a name="Other_functions"></a>Modifying the object model</h2>Note that the date manipulations are described <a href="interface.html#date_value">here</a>.<br>
<h3><a name="Manipulating_strings"></a>Manipulating strings<br>
</h3>
want to know this. You can pass <code>NULL</code> if you're not interested. The function returns <code>NULL</code>
if an error occurred (e.g. if the given string is not a valid string for
the current locale); in that case the target data variable is not modified.<br>
+<br>
+<h3><a name="Adding_and_removing_records"></a>Adding and removing records</h3>
+For each of the record types, there are two functions to add and remove records:
+<blockquote><code>struct XXX* <b>gom_new_XXX</b>(const char* xref);<br>
+int <b>gom_delete_XXX</b>(struct XXX* obj);</code><br>
+ </blockquote>
+
+
+The <code><b>XXX</b></code> stands for one of the following: <code><b>family</b>, </code><code><b>individual</b>, <b>multimedia</b>, <b>note</b>, <b>repository</b>, <b>source</b>, <b>submitter</b>, <b>user_rec</b></code>.<br>
+<br>
+For submission records, the <code><b>gom_delete_submission()</b></code> has no parameters (since there can be only one such object anyway).<br>
+<br>
+When creating new records, the application is responsible for making sure
+that mandatory fields (according to the GEDCOM spec) are filled in afterwards.
+ In a later release, there will be checks in <code>gom_write_file</code> when something is missing.<br>
+<br>
+<h3><a name="Adding_rem_and_moving_xref"></a>Adding, removing and moving cross-references<br>
+</h3>
+For struct members that are of type <code>struct xref_value</code>, the following function is available:<br>
+<blockquote><code>struct xref_value* <b>gom_set_xref</b>(struct xref_value** data, const char* xref);</code><br>
+ </blockquote>
+This function modifies the <code>data</code> variable to point to the given <code>xref</code>, taking care of unreferencing the old value, and referencing the new value. If an error occurs, <code>NULL</code> is returned (and the <code>data</code> variable is not changed). If xref is <code>NULL</code>, the data is set to <code>NULL</code>.<br>
+<br>
+For struct members that are of type <code>struct xref_list</code>, the following functions are available:<br>
+<blockquote><code>struct xref_list* <b>gom_add_xref</b>(struct xref_list** data, const char* xref);<br>
+int <b> gom_remove_xref</b>(struct xref_list** data, const char* xref);<br>
+int <b>gom_move_xref</b>(Gom_direction dir, </code><code>struct xref_list** data, const char* xref);</code><br>
+ </blockquote>
+The first function adds the given <code>xref</code> to the end of the <code>data</code> list. The second function removes the given <code>xref</code> from the <code>data</code> list (if present; if not present an error is generated and 1 is returned).<br>
+<br>
+The third function moves the given <code>xref </code>up or down the <code>data</code> list, depending on the <code>dir</code> parameter, which can be:<br>
+<ul>
+ <li><code>MOVE_UP</code></li>
+ <li><code>MOVE_DOWN</code></li>
+</ul>
+Again, an error is generated and 1 is returned if the given xref is not part
+of the list. If the xref cannot be moved up (because the first in the
+list) or down (because the last in the list), a warning is generated, but
+the function still returns success (0).<br>
+<h3><a name="Adding_removing_and_moving"></a>Adding, removing and moving substructures<br>
+</h3>
+For struct members that are just a single value, the following functions are available:<br>
+<blockquote><code>struct XXX* <b>gom_set_new_XXX</b>(struct XXX** data);<br>
+int <b>gom_delete_XXX</b>(struct XXX** data);</code><br>
+ </blockquote>
+This is the case for <b><code>XXX</code></b> equal to <b><code>address</code></b>, <b><code>change_date</code></b> or <b><code>place</code></b>. The first function creates a new substructure and assigns it to <code>data</code> (<code>NULL</code> is returned if there was already a value). The second function deletes the value from <code>data</code>.<br>
+<br>
+Note: for <code>change_date</code> structs there is also the following short-cut function, which updates the date and time directly:<br>
+<blockquote><code>int <b>gom_update_timestamp</b> (struct change_date** obj, time_t tval);<br></code></blockquote>
+For struct members that are a list (as described <a href="#Object_lists">here</a>), the following functions are available:<br>
+<blockquote><code>struct XXX* <b>gom_add_new_XXX</b>(struct XXX** data);<br>
+int <b>gom_remove_XXX</b>(struct XXX** data, struct XXX* obj);</code><br>
+ <code>int <b>gom_move_XXX</b>(Gom_direction dir, struct XXX** data, struct XXX* obj);</code><br>
+ </blockquote>
+
+This is the case for all <code>XXX</code> structs that have a <code>next</code> and <code>previous</code> member. The first function creates a new substructure and adds it to the end of the <code>data</code> list. The second function deletes the object from the <code>data</code> list (if present; if not present, an error is generated and 1 is returned).<br>
+<br>
+The third function moves the given <code>obj</code> up or down the <code>data</code> list, depending on the <code>dir</code> parameter, similar to the xref functions above.<br>
+<br>
+
<hr width="100%" size="2">
<h2><a name="Writing_the_object_model_to_file"></a>Writing the object model to file<br>
</h2>
<br>
<br>
<br>
+<br>
</body></html>
\ No newline at end of file
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
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). Note:
+currently the Gedcom object model in C has this option disabled too, although
+this will change in the future.<br>
+ </blockquote>
+</blockquote>
+<br>
+
<hr width="100%" size="2">
<h2><a name="Converting_character_sets"></a>Converting character sets</h2>
<br>
<br>
<br>
+<br>
</body></html>
\ No newline at end of file
projects / gedcom-parse.git / commitdiff