libgedcom.so
), to be linked in the application
programgedcom.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.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.In the above piece of code,void my_message_handler (Gedcom_msg_type type, char *msg)
{
...
}
...
gedcom_set_message_handler(my_message_handler);
...
result = gedcom_parse_file("myfamily.ged");
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: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.Error on line
<lineno>: <actual_message>
printf
is used in the message handler.Using theGedcom_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");
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...).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.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.Gedcom_val
type for the xref
argument
was not discussed, see further for this)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. theGedcom_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");
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.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)
; |
Gedcom_val
argument of the end callback
is currently not used. It is there for future enhancements.Gedcom_val
argument in the start
callback for records. This argument is currently a string value giving
the pointer in string form.