X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;f=doc%2Fusage.html;fp=doc%2Fusage.html;h=cd050df414a0f2e707d0e8b9a71fd0999318046f;hb=6d7fe09b0eab9dd8ea3c209d59589bea6514a48c;hp=786cf1f1694714bb02dfe73eaf6bf5ec7e564767;hpb=00537961a05301e245a002110ed9d3da0e0ee2ca;p=gedcom-parse.git diff --git a/doc/usage.html b/doc/usage.html index 786cf1f..cd050df 100644 --- a/doc/usage.html +++ b/doc/usage.html @@ -1,9 +1,7 @@ Using the GEDCOM parser library - - - +

Using the GEDCOM parser library

@@ -94,8 +92,7 @@ actual callback mechanism, although it also uses a callback...
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 + 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:
@@ -169,7 +166,7 @@ a GEDCOM file. First, have a look at the following piece of code:

void my_header_end_cb (Gedcom_ctxt self)
{
- printf("The header ends, context is %d\n", self); /* context + printf("The header ends, context is %d\n", (int)self); /* context will print as "1" */
}

@@ -207,7 +204,7 @@ need to have the signatures as shown in the example.
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 that will contain the information for the + 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.

@@ -263,11 +260,11 @@ 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. the struct that + 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 the same context, but this can be its own context object +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 will be the same in the example. +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 .
@@ -278,7 +275,7 @@ level number (the initial number of the line in the GEDCOM file), the tag 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.
+ 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 @@ -291,9 +288,8 @@ level number (the initial number of the line in the GEDCOM file), the tag

The Gedcom_val argument of the end callback is currently not used. It is there for future enhancements.
There is also a Gedcom_val argument in -the start callback for records. This argument is currently a string -value giving the pointer in string form.
There are also two Gedcom_val arguments in +the start callback for records. The first one (xref) contains the xref_value corresponding to the cross-reference (or NULL if there isn't one), the second one (parsed_value) contains the value that is parsed from the raw_value. See the interface details.

@@ -361,6 +357,8 @@ 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.