libgedcom.so), to be linked in the
-application programgedcom.h), to be used in the sources
of the application programgedcom-tags.h) that is also installed,
- but that is automatically included via gedcom.hgedcom.hlibgedcom.so is also needed in this case, because the object model uses the callback parser internally):libgedcom_gom.so), to be linked in the application program, which implements the C object modelgom.h), to be used in the sources of the application program$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.gedcom.h header is assumed, as everywhere
in this manual):int result;
@@ -71,32 +78,43 @@ in this manual):
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 call to gedcom_init() should be one of the first calls
+
+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. 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.
-
- The next sections will refine this piece of code to be able to have
+ in its initialization.
+
+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 function gedcom_init() also initializes locale handling by calling setlocale(LC_ALL, ""), in case the application would not do this (it doesn't hurt for the application to do the same).
+
+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
- 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
+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.
- A typical piece of code would be:
+ 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)
@@ -129,8 +147,7 @@ way it wants. Warnings are similar, but use "Warning" instead of "Error"
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.
+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
@@ -399,7 +416,8 @@ raw_value, int parsed_tag)
Other API functions
- Although the above describes the basic interface of libgedcom, there
+
+ 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.
@@ -498,17 +516,29 @@ 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).
+gedcom-parse contains an a library implementing help functions for UTF-8 encoding (
- Its interface is:
+ Its interface contains first of all the following two help functions:
- char *convert_utf8_to_locale (char *input, int *conv_failures);
char *convert_locale_to_utf8 (char *input);
+ int is_utf8_string (char *input);
int utf8_strlen (char *input);
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.
+
+For conversion, the following functions are available:
+
+ 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
@@ -656,45 +686,38 @@ handle needs to be closed (when the program exits):
iconv_close(iconv_handle);
-
- The example implementation
- mentioned above grows the output buffer dynamically and outputs "?" for characters
+ - There are three preprocessor symbols defined for version checks in the - header:AC_CHECK_LIB(gedcom, gedcom_parse_file,,
- AC_MSG_ERROR(Cannot - find libgedcom: Please install gedcom-parse))
- AC_MSG_CHECKING(for libgedcom version)
- AC_TRY_RUN([
- #include <stdio.h>
- #include <stdlib.h>
- #include <gedcom.h>
- int
- main()
- {
- if (GEDCOM_PARSE_VERSION >= 1034) exit(0);
- exit(1);
- }],
- ac_gedcom_version_ok='yes',
- ac_gedcom_version_ok='no',
- ac_gedcom_version_ok='no')
- if test "$ac_gedcom_version_ok" = 'yes' ; then
- AC_MSG_RESULT(ok)
- else
- AC_MSG_RESULT(not ok)
- AC_MSG_ERROR(You need at least version 1.34 of gedcom-parse)
- fi
-
+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([major,[minor,[patch]]])
+
+To be able to use this macro in the sources of your application, you have three options:AM_LIB_GEDCOM_PARSER(1,34)
+
m4/gedcom.m4 in your autoconf data directory (i.e. the path given by 'aclocal --print-ac-dir', usually /usr/share/aclocal). You can do this automatically by going into the m4 subdirectory and typing 'make install-m4'.m4/gedcom.m4 in the aclocal.m4 file in your sources.m4/gedcom.m4 in the acinclude.m4 file in your sources.GEDCOM_PARSE_VERSION_MAJOR(GEDCOM_PARSE_VERSION_MAJOR * 1000) + GEDCOM_PARSE_VERSION_MINOR.+