X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;ds=inline;f=doc%2Fusage.html;h=ee3d2d4b1133ea50d60f301feb1ef40107719a84;hb=7cbefaec45b82eb0449465da19d38a89f2ff2cf3;hp=6880dc8f65ab3f3025d679ab4d488f676d8d17cf;hpb=70dd8d0091ad90636d0957346830ca564db969f6;p=gedcom-parse.git diff --git a/doc/usage.html b/doc/usage.html index 6880dc8..ee3d2d4 100644 --- a/doc/usage.html +++ b/doc/usage.html @@ -1,9 +1,7 @@
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.h
gedcom.h
libgedcom.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,42 @@ 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.
+ 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 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 +146,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 +415,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.
@@ -713,5 +730,7 @@ handle needs to be closed (when the program exits):
+
+
\ No newline at end of file