2 Copyright (C) 2001,2002,2003 The Genes Development Team
3 This file is part of the Gedcom parser library.
4 Contributed by Peter Verthez <Peter.Verthez@advalvas.be>, 2003.
6 The Gedcom parser library is free software; you can redistribute it
7 and/or modify it under the terms of the GNU Lesser General Public
8 License as published by the Free Software Foundation; either
9 version 2.1 of the License, or (at your option) any later version.
11 The Gedcom parser library is distributed in the hope that it will be
12 useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Lesser General Public License for more details.
16 You should have received a copy of the GNU Lesser General Public
17 License along with the Gedcom parser library; if not, write to the
18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
24 /*! \mainpage The Gedcom Parser Library
26 The Gedcom Parser Library is a C library that provides an API to applications
27 to parse and process arbitrary genealogy files in the standard GEDCOM format.
29 <a href="http://www.gendex.com/gedcom55/55gctoc.htm">release 5.5</a> of the
32 The following links provide a manual to the Gedcom parser library:
37 The Gedcom Parser Library provides two interfaces. On the one hand, it can
38 be used as a callback-based parser (comparable to the SAX interface of XML);
39 on the other hand, the parser can be used to convert the GEDCOM file into an
40 object model (comparable to the DOM interface of XML). It comes with:
42 - a library (\c libgedcom.so), to be linked in the application program,
43 which implements the callback parser
44 - a header file (\c gedcom.h), to be used in the sources of the application
46 - a header file (\c gedcom-tags.h) that is also installed, but that is
47 automatically included via \c gedcom.h
49 Additionally, if you want to use the C object model, the following should be
50 used (note that \c libgedcom.so is also needed in this case, because the
51 object model uses the callback parser internally):
53 - a library (\c libgedcom_gom.so), to be linked in the application program,
54 which implements the C object model
55 - a header file (\c gom.h), to be used in the source of the application
58 There is a separate script and an M4 macro (for autoconf) to help with
59 library and compilation flags, see the development support (TODO: REFERENCE!)
62 /*! \defgroup callback Callback Interface */
64 /*! \defgroup gom Gedcom Object Model in C */
66 /*! \defgroup main Main functions of the parser
69 The very simplest call of the Gedcom callback parser is simply the following
70 piece of code (include of the \c gedcom.h header is assumed, as everywhere
78 result = gedcom_parse_file("myfamily.ged");
81 Although this will not provide much information, one thing it does is parse
82 the entire file and return the result.
84 The next sections will refine this
85 piece of code to be able to have meaningful errors and the actual data that
89 /*! \defgroup error Error handling
92 The library can be used in several different circumstances, both
93 terminal-based as GUI-based. Therefore, it leaves the actual display of the
94 error message up to the application.
96 For this, the application needs to register a callback before parsing the
97 GEDCOM file, which will be called by the library on errors, warnings and
100 A typical piece of code would be:
103 void my_message_handler(Gedcom_msg_type type, char* msg)
108 gedcom_set_message_handler(my_message_handler);
110 result = gedcom_parse_file("myfamily.ged");
113 With this in place, the resulting code will show errors and warnings produced
114 by the parser, e.g. on the terminal if a simple \c printf is used in the
118 /*! \defgroup cb_mech Data callback mechanism
122 /*! \defgroup write Support for writing GEDCOM files
126 /*! \defgroup gommain Main functions of the object model
129 Programs using the Gedcom object model in C should use the following
131 both the \c gedcom.h and \c gom.h headers is required; contrast this with
132 the example given for the \ref main "callback parser"):
139 result = gom_parse_file("myfamily.ged");