X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;f=doc%2Fusage.html;h=dc2e70ad7d9f03ebde68f0f2b722ca9caf204076;hb=a5bd4c3c89f5cb433a615c436947b8b0f44c3661;hp=f47684feb49bf606a63fc61fa86076dc345a2e44;hpb=7a161f98fa3efba595c96577e3ae7eda15b3dec3;p=gedcom-parse.git diff --git a/doc/usage.html b/doc/usage.html index f47684f..dc2e70a 100644 --- a/doc/usage.html +++ b/doc/usage.html @@ -1,307 +1,731 @@ - - - - Using the GEDCOM parser library - - - - - +Using the GEDCOM parser library + + + +

Using the GEDCOM parser library

-
- +
+

Index

+ -
+ +

Overview
-

- The GEDCOM parser library is built as a callback-based parser (comparable -to the SAX interface of XML).  It comes with:
- + The GEDCOM +parser library provides two interfaces.  At the one hand, it can be +used as a callback-based parser (comparable to the SAX interface of +XML); at the other hand, the parser can be used to convert the GEDCOM file +into an object model (comparable to the DOM interface of XML).  It comes +with:
+ Additionally, if you want to use the GEDCOM C object model, the following should be used (note that libgedcom.so is also needed in this case, because the object model uses the callback parser internally):
+ - Next to these, there is also a data directory in $PREFIX/share/gedcom-parse - that contains some additional stuff, but which is not immediately important -at first.  I'll leave the description of the data directory for later.
-
- The very simplest call of the gedcom parser is simply the following piece -of code (include of the gedcom header is assumed, as everywhere in this manual):
- + + Next to these, there is also a data directory in $PREFIX/share/gedcom-parse + that contains some additional stuff, but which is not immediately + important at first.  I'll leave the description of the data directory + for later.
+
+ The very simplest call of the gedcom callback parser is simply the following + piece of code (include of the gedcom.h header is assumed, as everywhere +in this manual):
+
int result;
- ...
- result = gedcom_parse_file("myfamily.ged");
-
- Although this will not provide much information, one thing it does is parse -the entire file and return the result.  The function returns 0 on success -and 1 on failure.  No other information is available using this function -only.
-
-The next sections will refine this to be able to have meaningful errors and -the actual data that is in the file.
-
-

Error handling

-Since this is a relatively simple topic, it is discussed before the actual -callback mechanism, although it also uses a callback...
-
-The library can be used in several different circumstances, both terminal-based -as GUI-based.  Therefore, it leaves the actual display of the error -message up to the application.  For this, the application needs to register -a callback before parsing the GEDCOM file, which will be called by the library -on errors, warnings and messages.
-
-A typical piece of code would be:
-
void my_message_handler (Gedcom_msg_type type, -char *msg)
-{
-  ...
-}
-...
- gedcom_set_message_handler(my_message_handler);
-...
-result = gedcom_parse_file("myfamily.ged");
-
-In the above piece of code, my_message_handler is the callback -that will be called for errors (type=ERROR), warnings ( -type=WARNING) and messages (type=MESSAGE).  The -callback must have the signature as in the example.  For errors, the - msg passed to the callback will have the format:
-
Error on line <lineno>: <actual_message>
-
-Note that the entire string will be properly internationalized, and encoded -in UTF-8 (see "Why UTF-8?"  LINK TBD).  Also, no newline -is appended, so that the application program can use it in any way it wants. - Warnings are similar, but use "Warning" instead of "Error".  Messages -are plain text, without any prefix.
-
-With this in place, the resulting code will already show errors and warnings -produced by the parser, e.g. on the terminal if a simple printf - is used in the message handler.
-
-

Data callback mechanism

-The most important use of the parser is of course to get the data out of -the GEDCOM file.  As already mentioned, the parser uses a callback mechanism -for that.  In fact, the mechanism involves two levels.
-
-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 "end element" -callback (much like in a SAX interface for XML), i.e. when a line containing -a certain tag is parsed, the "start element" callback 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.
-
-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 development. - Moreover, under GEDCOM it is allowed for an application to define its -own tags, which will typically not  be supported by another application. - Still, in that case, data preservation is important; it would hardly -be accepted that information that is not understood by a certain program -is just removed.
-
-Therefore, the second level of callbacks involves a "default callback".  An -application needs to subscribe to callbacks for tags it does support, and -need to provide a "default callback" which will be called for tags it doesn't -support.  The application can then choose to just store the information -that comes via the default callback in plain textual format.
-
-After this introduction, let's see what the API looks like...
-
-

Start and end callbacks

-

Callbacks for records
-

-As a simple example, we will get some information from the header of a GEDCOM -file.  First, have a look at the following piece of code:
-
Gedcom_ctxt my_header_start_cb (int level, -Gedcom_val xref, char *tag)
-{
-  printf("The header starts\n");
-  return (Gedcom_ctxt)1;
-}
-
-void my_header_end_cb (Gedcom_ctxt self)
-{
-  printf("The header ends, context is %d\n", self);   /* context -will print as "1" */
-}
-
-...
- gedcom_subscribe_to_record(REC_HEAD, my_header_start_cb, my_header_end_cb);
-...
-result = gedcom_parse_file("myfamily.ged");
-
- Using the gedcom_subscribe_to_record function, the application -requests to use the specified callbacks as start and end callback. The end -callback is optional: you can pass NULL if you are not interested -in the end callback.  The identifiers to use as first argument to the -function (here REC_HEAD) are described in TBD (use the header -file for now...).
-
-From the name of the function it becomes clear that this function is specific -to complete records.  For the separate elements in records there is -another function, which we'll see shortly.  Again, the callbacks need -to have the signatures as shown in the example.
-
-The Gedcom_ctxt type that is used as a result of the start callback -and as an argument to the end callback is vital for passing context necessary -for the application.  This type is meant to be opaque; in fact, it's -a void pointer, so you can pass anything via it.  The important thing -to know is that the context that the application returns in the start callback -will be passed in the end callback as an argument, and as we will see shortly, -also to all the directly subordinate elements of the record.
-
-The example passes a simple integer as context, but an application could -e.g. pass a struct that will contain the information for the -header.  In the end callback, the application could then e.g. do some -finalizing operations on the struct to put it in its database.
-
-(Note that the Gedcom_val type for the xref argument -was not discussed, see further for this)
-
-

Callbacks for elements

-We will now retrieve the SOUR field (the name of the program that wrote the -file) from the header:
-
Gedcom_ctxt my_header_source_start_cb(Gedcom_ctxt -parent,
-                      -                int     -    level,
-                      -                char*     -  tag,
-                      -                char*     -  raw_value,
-                      -                Gedcom_val  parsed_value)
-{
-  char *source = GEDCOM_STRING(parsed_value);
-  printf("This file was written by %s\n", source);
-  return parent;
-}
-
-void my_header_source_end_cb(Gedcom_ctxt parent,
-                      -       Gedcom_ctxt self,
-                      -       Gedcom_val  parsed_value)
-{
-  printf("End of the source description\n");
-}
-
-...
- gedcom_subscribe_to_element(ELT_HEAD_SOUR,
-                      -      my_header_source_start_cb,
-                      -      my_header_source_end_cb);
-...
-result = gedcom_parse_file("myfamily.ged");
-
-The subscription mechanism for elements is similar, only the signatures of -the callbacks differ.  The signature for the start callback shows that -the context of the parent line (e.g. the struct that describes -the header) is passed to this start callback.  The callback itself returns -here the same context, but this can be its own context object of course. - The end callback is called with both the context of the parent and -the context of itself, which will be the same in the example.
-
-If we look at the other arguments of the start callback, we see the level -number (the initial number of the line in the GEDCOM file), the tag (e.g. -"SOUR"), and then a raw value and a parsed value.  The raw value is -just the raw string that occurs as value on the line next to the tag (in -UTF-8 encoding).  The parsed value is the meaningful value that is parsed -from that raw string.
-
-The Gedcom_val type is meant to be an opaque type.  The -only thing that needs to be known about it is that it can contain specific -data types, which have to be retrieved from it using pre-defined macros. - Currently, the specific types are (with val of type -Gedcom_val):
-
- - - - - - - - - - - - - - - - - - - - - - - -

- 		type checker
- 		cast operator
-
null value
- 		GEDCOM_IS_NULL(val)
- 		N/A
-
string
- 		GEDCOM_IS_STRING(val)
- 		char* str = GEDCOM_STRING(val);
-
date
- 		GEDCOM_IS_DATE(val)
- 		struct date_value dv = GEDCOM_DATE(val) -;
-
-
-The null value is used for when the GEDCOM spec doesn't allow a value, or -when an optional value is allowed but none is given.
+ ...
+ gedcom_init();
+ ...
+ result = gedcom_parse_file("myfamily.ged");
+ + Although this will not provide much information, one thing it does + is parse the entire file and return the result.  The function returns + 0 on success and 1 on failure.  No other information is available +using this function only.
+
+Alternatively, programs using the C object model should use the following (in this case, the inclusion of both gedcom.h and gom.h is required):
+ +
int result;
+ ...
+ gedcom_init();
+ ...
+ result = gom_parse_file("myfamily.ged");
+
+The call to gom_parse_file will build the C object model, which is then a complete representation of the GEDCOM file.
+
+No matter which of the interfaces you use, the call to gedcom_init() should be one of the first calls +in your program.  The requirement is that it should come before the first +call to iconv_open (part of the generic character set conversion +feature) in the program, either by your program itself, or indirectly by +the library calls it makes.  Practically, it should e.g. come before + any calls to any GTK functions, because GTK uses iconv_open + in its initialization.
 
-The string value is the most general used value currently, for all those -values that don't have a more specific meaning.  In essence, the value -that is returned by GEDCOM_STRING is always the same as the raw_value passed -to the start callback, and is thus in fact redundant.
-
-The date value is used for all elements that return a date.  (Description -of struct date_value TBD: look in the header file for the moment).
+For the same reason it is also advised to put +the -lgedcom option +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: -lgedcom_gom -lgedcom

-The type checker returns a true or a false value according to the type of -the value, but this is in principle only necessary in the rare circumstances -that two types are possible, or where an optional value can be provided. - In most cases, the type is fixed for a specific tag (types per tag -to be described).
+ 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.
+ +
+

Error handling

The library can be used in several different circumstances, both +terminal-based as GUI-based.  Therefore, it leaves the actual display +of the error message up to the application.  For this, the application +needs to register a callback before parsing the GEDCOM file, which will +be called by the library on errors, warnings and messages.

-Some extra notes:
- -

Default callbacks
-

-TO BE COMPLETED
-
$Id$
- $Name$
-
- - - + A typical piece of code would be (gom_parse_file would be called in case the C object model is used):
+ +
void my_message_handler (Gedcom_msg_type type, + char *msg)
+ {
+   ...
+ }
+ ...
+ gedcom_set_message_handler(my_message_handler);
+ ...
+ result = gedcom_parse_file("myfamily.ged");
+
+ In the above piece of code, my_message_handler is the + callback that will be called for errors (type=ERROR), warnings + (type=WARNING) and messages (type=MESSAGE).  The + callback must have the signature as in the example.  For errors, +the msg passed to the callback will have the format:
+ +
Error on line <lineno>: <actual_message>
+
+ Note that the entire string will be properly internationalized, and + encoded in UTF-8 (Why UTF-8?).  Also, +no newline is appended, so that the application program can use it in any +way it wants.  Warnings are similar, but use "Warning" instead of "Error". + Messages are plain text, without any prefix.
+
+ With this in place, the resulting code will already show errors and + warnings produced by the parser, e.g. on the terminal if a simple + printf is used in the message handler.
+ +
+

Data callback mechanism

+ 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 here for the C object model).  In fact, the mechanism involves two levels.
+
+ 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 + "end element" callback (much like in a SAX interface for XML), i.e. when + a line containing a certain tag is parsed, the "start element" callback + 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.
+
+ 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 + development.  Moreover, under GEDCOM it is allowed for an application + to define its own tags, which will typically not  be supported by +another application.  Still, in that case, data preservation is important; + it would hardly be accepted that information that is not understood by + a certain program is just removed.
+
+ Therefore, the second level of callbacks involves a "default callback". +  An application needs to subscribe to callbacks for tags it does support, + and need to provide a "default callback" which will be called for tags +it doesn't support.  The application can then choose to just store +the information that comes via the default callback in plain textual format.
+
+ After this introduction, let's see what the API looks like...
+
+ +

Start and end callbacks

+ +

Callbacks for records
+

+ As a simple example, we will get some information from the header +of a GEDCOM file.  First, have a look at the following piece of code:
+ +
Gedcom_ctxt my_header_start_cb (Gedcom_rec rec,
+                                int level,
+                     +            Gedcom_val xref,
+                     +            char *tag,
+                     +            char *raw_value,
+                     +            int parsed_tag,
+                     +            Gedcom_val parsed_value)
+ {
+   printf("The header starts\n");
+   return (Gedcom_ctxt)1;
+ }
+
+ void my_header_end_cb (Gedcom_rec rec, Gedcom_ctxt self)
+ {
+   printf("The header ends, context is %d\n", (int)self);   + /* context will print as "1" */
+ }
+
+ ...
+ gedcom_subscribe_to_record(REC_HEAD, my_header_start_cb, + my_header_end_cb);
+ ...
+ result = gedcom_parse_file("myfamily.ged");
+
+ Using the gedcom_subscribe_to_record function, the + application requests to use the specified callbacks as start and end +callback. The end callback is optional: you can pass NULL + if you are not interested in the end callback.  The identifiers +to use as first argument to the function (here REC_HEAD) +are described in the interface +details .  These are also passed as first argument in the callbacks (the Gedcom_rec argument).
+
+ From the name of the function it becomes clear that this function +is specific to complete records.  For the separate elements in records + there is another function, which we'll see shortly.  Again, the callbacks + need to have the signatures as shown in the example.
+
+ The Gedcom_ctxt type that is used as a result of the +start callback and as an argument to the end callback is vital for passing +context necessary for the application.  This type is meant to be opaque; +in fact, it's a void pointer, so you can pass anything via it.  The +important thing to know is that the context that the application returns +in the start callback will be passed in the end callback as an argument, +and as we will see shortly, also to all the directly subordinate elements +of the record.
+
+ The tag is the GEDCOM tag in string format, the parsed_tag + is an integer, for which symbolic values are defined as TAG_HEAD, + TAG_SOUR, TAG_DATA, ... and USERTAG + for the application-specific tags.  These values +are defined in the header gedcom-tags.h that is installed, +and included via gedcom.h (so no need to include gedcom-tags.h + yourself).
+
+ The example passes a simple integer as context, but an application + could e.g. pass a struct (or an object in a C++ application) + that will contain the information for the header.  In the end callback, + the application could then e.g. do some finalizing operations on the + struct to put it in its database.
+
+ (Note that the Gedcom_val type for the xref + and parsed_value arguments was not discussed, see further + for this)
+
+ +

Callbacks for elements

+ We will now retrieve the SOUR field (the name of the program that +wrote the file) from the header:
+ +
Gedcom_ctxt my_header_source_start_cb(Gedcom_elt  elt,
+                      +                Gedcom_ctxt + parent,
+                     +                   int   +       level,
+                     +                   char*   +     tag,
+                     +                   char*   +     raw_value,
+                     +                   int   +       parsed_tag,
+                     +                   Gedcom_val +  parsed_value)
+ {
+   char *source = GEDCOM_STRING(parsed_value);
+   printf("This file was written by %s\n", source);
+   return parent;
+ }
+
+ void my_header_source_end_cb(Gedcom_elt  elt,
+                             Gedcom_ctxt parent,
+                     +          Gedcom_ctxt self,
+                     +          Gedcom_val  parsed_value)
+ {
+   printf("End of the source description\n");
+ }
+
+ ...
+ gedcom_subscribe_to_element(ELT_HEAD_SOUR,
+                     +         my_header_source_start_cb,
+                     +         my_header_source_end_cb);
+ ...
+ result = gedcom_parse_file("myfamily.ged");
+
+ The subscription mechanism for elements is similar, only the signatures + of the callbacks differ.  The signature for the start callback shows + that the context of the parent line (here e.g. the struct + that describes the header) is passed to this start callback.  The + callback itself returns here in this example the same context, but this +can be its own context object of course.  The end callback is called +with both the context of the parent and the context of itself, which in this +example will be the same.  Again, the list of identifiers to use as +a first argument for the subscription function are detailed in the interface details .  Again, these are passed as first argument in the callback (the Gedcom_elt argument).
+
+ If we look at the other arguments of the start callback, we see the + level number (the initial number of the line in the GEDCOM file), the tag + (e.g. "SOUR"), and then a raw value, a parsed tag and a parsed value.  The + raw value is just the raw string that occurs as value on the line next +to the tag (in UTF-8 encoding).  The parsed value is the meaningful +value that is parsed from that raw string.  The parsed tag is described +in the section for record callbacks above.
+
+ The Gedcom_val type is meant to be an opaque type.  The + only thing that needs to be known about it is that it can contain specific + data types, which have to be retrieved from it using pre-defined macros. +  These data types are described in the interface details. +
+
+ Some extra notes:
+ + + + + +

Default callbacks
+

+ As described above, an application doesn't always implement the entire + GEDCOM spec, and application-specific tags may have been added by other + applications.  To preserve this extra data anyway, a default callback + can be registered by the application, as in the following example:
+ +
void my_default_cb (Gedcom_elt elt, Gedcom_ctxt parent, int level, + char* tag, char* raw_value, int parsed_tag)
+ {
+   ...
+ }
+
+ ...
+ gedcom_set_default_callback(my_default_cb);
+ ...
+ result = gedcom_parse_file("myfamily.ged");
+
+ This callback has a similar signature as the previous ones, + but it doesn't contain a parsed value.  However, it does contain the + parent context, that was returned by the application for the most specific + containing tag that the application supported.
+
+ Suppose e.g. that this callback is called for some tags in the header + that are specific to some other application, then our application could + make sure that the parent context contains the struct or object that represents + the header, and use the default callback here to add the level, tag and + raw_value as plain text in a member of that struct or object, thus preserving + the information.  The application can then write this out when the +data is saved again in a GEDCOM file.  To make it more specific, consider + the following example:
+ +
struct header {
+   char* source;
+   ...
+   char* extra_text;
+ };
+
+ Gedcom_ctxt my_header_start_cb(Gedcom_rec rec, int level, Gedcom_val xref, char* tag, + char *raw_value,
+                     +           int parsed_tag, Gedcom_val parsed_value)
+ {
+   struct header head = my_make_header_struct();
+   return (Gedcom_ctxt)head;
+ }
+
+ void my_default_cb(Gedcom_elt elt, Gedcom_ctxt parent, int level, char* tag, char* +raw_value, int parsed_tag)
+ {
+   struct header head = (struct header)parent;
+   my_header_add_to_extra_text(head, level, tag, raw_value);
+ }
+
+ gedcom_set_default_callback(my_default_cb);
+ gedcom_subscribe_to_record(REC_HEAD, my_header_start, NULL);
+ ...
+ result = gedcom_parse_file(filename);
+
+ Note that the default callback will be called for any tag that isn't + specifically subscribed upon by the application, and can thus be called + in various contexts.  For simplicity, the example above doesn't take + this into account (the parent could be of different + types, depending on the context).
+
+ Note also that the default callback is not called when the parent context + is NULL.  This is e.g. the case if none + of the "upper" tags has been subscribed upon.
+ + +
+ +

Other API functions
+

+ + Although the above describes the basic interface of the gedcom parser, there + are some other functions that allow to customize the behaviour of the library. +  These will be explained in the current section.
+ + +

Debugging

+ The library can generate various debugging output, not only from itself, + but also the debugging output generated by the yacc parser.  By default, + no debugging output is generated, but this can be customized using the +following function:
+ + +
void gedcom_set_debug_level (int level, FILE* +trace_output)
+
+ The level can be one of the following values:
+ + + + If the trace_output is NULL, debugging information + will be written to stderr, otherwise the given file handle + is used (which must be open).
+
+ + +

Error treatment

+ One of the previous sections already described the callback to be +registered to get error messages.  The library also allows to customize +what happens on an error, using the following function:
+ + +
void gedcom_set_error_handling (Gedcom_err_mech + mechanism)
+
+ The mechanism can be one of:
+ + + + This doesn't influence the generation of error or warning messages, + only the behaviour of the parser and its return code.
+
+ + +

Compatibility mode
+

+ Applications are not necessarily true to the GEDCOM spec (or use a +different version than 5.5).  The intention is that the library is +resilient to this, and goes in compatibility mode for files written by specific +programs (detected via the HEAD.SOUR tag).  This compatibility mode +can be enabled and disabled via the following function:
+ + +
void gedcom_set_compat_handling (int enable_compat)
+
+ The argument can be:
+ + + + Currently, there is a beginning for compatibility for ftree and Lifelines (3.0.2).
+ +
+

Converting character sets

+ All strings passed by the GEDCOM parser to the application are in UTF-8 + encoding.  Typically, an application needs to convert this to something + else to be able to display it.
+
+ The most common case is that the output character set is controlled by +the locale mechanism (i.e. via the LANG, + LC_ALL or LC_CTYPE environment variables), which also +controls the gettext mechanism in the application.  
+
+
+ + The source distribution of +gedcom-parse contains an example implementation (utf8-locale.c + and utf8-locale.h 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).  
+
+ Its interface is:
+ +
+ 
char *convert_utf8_to_locale (char *input, int *conv_failures);
char *convert_locale_to_utf8 (char *input);
+
+ 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 setlocale function (the second step detailed + below).  All other steps given below, including setting up and closing + down the conversion handles, are transparantly handled by the two functions. +  
+
+ If you pass a pointer to an integer to the first function, it will be +set to the number of conversion failures, i.e. characters that couldn't +be converted; you can also just pass NULL if you are not interested +(note that usually, the interesting information is just whether there +were conversion failures or not, which is then given by the integer +being bigger than zero or not).  The second function doesn't need this, +because any locale can be converted to UTF-8.
+
+ You can change the "?" that is output for characters that can't be converted + to any string you want, using the following function before the conversion + calls:
+ +
+ 
void convert_set_unknown (const char *unknown);
+
+
+ If you want to have your own functions for it instead of this example +implementation, the following steps need to be taken by the application +(more detailed info can be found in the info file of the GNU libc library +in the "Generic Charset Conversion" section under "Character Set Handling" +or online + here):
+ + + +
+
+ 
#include <locale.h>    /* for setlocale */
#include <langinfo.h>  /* for nl_langinfo */
#include <iconv.h>     /* for iconv_* functions */
+
+
+ + + +
+
+ 
setlocale(LC_ALL, "");
+
+
+ + + +
+
+ 
iconv_t iconv_handle;
...
iconv_handle = iconv_open(nl_langinfo(CODESET), "UTF-8");
if (iconv_handle == (iconv_t) -1)
  /* signal an error */
+
+
+ + + +
+
+ 
/* char* in_buf is the input buffer,    size_t in_len is its length */
/* char* out_buf is the output buffer,  size_t out_len is its length */

size_t nconv;
char *in_ptr = in_buf;
char *out_ptr = out_buf;
nconv = iconv(iconv_handle, &in_ptr, &in_len, &out_ptr, &out_len);
+
+
+ +
If the output buffer is not big enough, iconv will + return -1 and set errno to E2BIG.  Also, +the in_ptr and out_ptr will point just after +the last successfully converted character in the respective buffers, and +the in_len and out_len will be updated to show +the remaining lengths.  There can be two strategies here:
+ + + Another error case is when the conversion was unsuccessful (if one of +the characters can't be represented in the target character set).  The + iconv function will then also return -1 and set errno + to EILSEQ; the in_ptr will point to the character + that couldn't be converted.  In that case, again two strategies are +possible:
+ + + +
    + +
      +
    1. if the first byte is in +binary 0xxxxxxx, then the character is only one byte long, just skip over +that byte
      +
      +
      2. +
    2. if the first byte is in +binary 11xxxxxx, then skip over that byte and all bytes 10xxxxxx that follow.
      +
      3. + +
    + +
+
+ + + +
+
+ 
iconv_close(iconv_handle);
+
+
+ The example implementation + mentioned above grows the output buffer dynamically and outputs "?" for characters + that can't be converted.
+ + +
+ +

Support for configure.in

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:
+
AM_LIB_GEDCOM_PARSER([major,[minor,[patch]]])
+
+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:
+
AM_LIB_GEDCOM_PARSER(1,34)
+
+To be able to use this macro in the sources of your application, you have three options:
+ +
+There are three preprocessor symbols defined for version checks in the + header (but their direct use is deprecated: please use the macro above):
+ + + The last one is equal to (GEDCOM_PARSE_VERSION_MAJOR * 1000) + GEDCOM_PARSE_VERSION_MINOR.
+ + +
+ +
$Id$
$Name$
+ + +
+ + +
+
+
+
+ \ No newline at end of file