X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fusage.html;h=3d13ab0d8f93eedabbd68c4f3fdb7deb04af6e8c;hb=a6f453d612fe285d2585b689e3e4d675de455510;hp=f47684feb49bf606a63fc61fa86076dc345a2e44;hpb=7a161f98fa3efba595c96577e3ae7eda15b3dec3;p=gedcom-parse.git diff --git a/doc/usage.html b/doc/usage.html index f47684f..3d13ab0 100644 --- a/doc/usage.html +++ b/doc/usage.html @@ -2,306 +2,398 @@
libgedcom.so
), to be linked in the application
-programgedcom.h
), to be used in the sources of
-the application programlibgedcom.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.$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
+ ...+ In the above piece of code,void my_message_handler (Gedcom_msg_type type, +
+ A typical piece of code would be:
+ +-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 + {
+ ...
+ }
+ ...
+ 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: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 + + 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, + +
- 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 + {
+ 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 passNULL
if you are not interested -in the end callback. The identifiers to use as first argument to the -function (hereREC_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.
-
-TheGedcom_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 astruct
that will contain the information for the -header. In the end callback, the application could then e.g. do some + }
+
+ ...
+ 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 the
+interface details.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
+ 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 + We will now retrieve the SOUR field (the name of the program that wrote +the file) from the header:
+ +-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 + + int level,
- - char* + + char* tag,
- - char* + + 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,
- + {
+ 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,
- + {
+ 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.
-
-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.
-
-TheGedcom_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 (withval
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.
-
-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).
-
-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).
+ ...
+ 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. Again, the list of
+identifiers to use as a first argument for the subscription function are
+detailed in the interface details
+.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. Gedcom_val
argument of the end callback
+ 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.Gedcom_val
argument in the
+start callback for records. This argument is currently a string value
+giving the pointer in string form.+ 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.void my_default_cb (Gedcom_ctxt parent, +int level, char* tag, char* raw_value)
+{
+ ...
+}
+
+...
+ gedcom_set_default_callback(my_default_cb);
+...
+result = gedcom_parse_file("myfamily.ged");
+
+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 +struct header {
+ char* source;
+ ...
+ char* extra_text;
+};
+
+Gedcom_ctxt my_header_start_cb(int level, Gedcom_val xref, char* tag)
+{
+ struct header head = my_make_header_struct();
+ return (Gedcom_ctxt)head;
+}
+
+void my_default_cb(Gedcom_ctxt parent, int level, char* tag, char* raw_value)
+{
+ 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);
+
parent
could be of different types, depending
+on the context).+Thevoid gedcom_set_debug_level (int level, +FILE* trace_output)
+
level
can be one of the following values:trace_output
is NULL
, debugging information
+will be written to stderr
, otherwise the given file handle is
+used (which must be open).+Thevoid gedcom_set_error_handling (Gedcom_err_mech +mechanism)
+
mechanism
can be one of:IMMED_FAIL
: immediately fail the parsing
+on an error (this is the default)DEFER_FAIL
: continue parsing after an
+error, but return a failure code eventuallyIGNORE_ERRORS
: continue parsing after
+an error, return success always+The argument can be:void gedcom_set_compat_handling + (int enable_compat)
+