[Gnucash-changes] QSF backend API resolved
Neil Williams
codehelp at cvs.gnucash.org
Sun Jun 19 16:36:40 EDT 2005
Log Message:
-----------
QSF backend API resolved
Tags:
----
gnucash-gnome2-dev
Modified Files:
--------------
gnucash:
ChangeLog
gnucash/src/backend/qsf:
qsf-backend.c
qsf-object.xsd.xml
qsf-xml.h
Added Files:
-----------
gnucash/src/backend/qsf:
qof-backend-qsf.h
Revision Data
-------------
Index: ChangeLog
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/ChangeLog,v
retrieving revision 1.1487.2.230
retrieving revision 1.1487.2.231
diff -LChangeLog -LChangeLog -u -r1.1487.2.230 -r1.1487.2.231
--- ChangeLog
+++ ChangeLog
@@ -1,4 +1,10 @@
2005-06-19 Neil Williams <linux at codehelp.co.uk>
+ * src/backend/qsf/qsf-backend.c: API
+ * src/backend/qsf/qsf-object.xsd.xml: QOF_TYPE_COLLECT
+ * src/backend/qsf/qsf-xml.h: Make into a private header.
+ * src/backend/qsf/qof-backend-qsf.h: Public API for the library.
+
+2005-06-19 Neil Williams <linux at codehelp.co.uk>
* src/doc/backend-api.txt
* src/doc/backend-errors.txt
* src/doc/backup.txt
Index: qsf-object.xsd.xml
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/backend/qsf/Attic/qsf-object.xsd.xml,v
retrieving revision 1.1.2.4
retrieving revision 1.1.2.5
diff -Lsrc/backend/qsf/qsf-object.xsd.xml -Lsrc/backend/qsf/qsf-object.xsd.xml -u -r1.1.2.4 -r1.1.2.5
--- src/backend/qsf/qsf-object.xsd.xml
+++ src/backend/qsf/qsf-object.xsd.xml
@@ -128,6 +128,15 @@
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
+ <xsd:element name="collect" minOccurs="0" maxOccurs="unbounded">
+ <xsd:complexType>
+ <xsd:simpleContent>
+ <xsd:extension base="xsd:hexBinary">
+ <xsd:attribute name="type" type="xsd:string" use="required"/>
+ </xsd:extension>
+ </xsd:simpleContent>
+ </xsd:complexType>
+ </xsd:element>
</xsd:sequence>
<xsd:attribute name="type" type="xsd:string" use="required"/>
<xsd:attribute name="count" type="xsd:positiveInteger" use="optional"/>
Index: qsf-xml.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/backend/qsf/Attic/qsf-xml.h,v
retrieving revision 1.1.2.4
retrieving revision 1.1.2.5
diff -Lsrc/backend/qsf/qsf-xml.h -Lsrc/backend/qsf/qsf-xml.h -u -r1.1.2.4 -r1.1.2.5
--- src/backend/qsf/qsf-xml.h
+++ src/backend/qsf/qsf-xml.h
@@ -24,100 +24,8 @@
#ifndef QSF_XML_H
#define QSF_XML_H
-/** @addtogroup Backend
- @{ */
-/** @addtogroup QSF QOF Serialisation Format
-
-QSF - QOF Serialization Format is an XML serialization format
-i.e. it lays out a QOF object in a series of XML tags. The format will
-consist of two component formats:
-
-qof-qsf for the QSF object data and
-
-qsf-map to map sets of QSF objects between QOF applications.
-
-Maps exist to allow complex conversions between objects where object parameters
-need to be calculated, combined or processed using conditionals. Some QSF objects
-can be converted using XSL or other standard tools. For more information on maps,
-see http://code.neil.williamsleesmill.me.uk/map.html
-
-QSF object files will contain user data and are to be exported from QOF applications
-under user control or they can be hand-edited. QSF maps contain application data and
-can be created by application developers from application source code. Tools may be
-created later to generate maps interactively but maps require application support as
-well as an understanding of QOF objects in the import and output applications and are
-intended to remain within the scope of application developers rather than users.
-
-A QSF file written by one QOF application will need an appropriate QSF map before the
-data can be accessed by a different application using QOF. Any QSF objects that are
-not defined in the map will be ignored. QSF files written and accessed by the same
-application can use maps if necessary or can simply import the QSF data as a whole.
-
-Unless specifically mentioned otherwise, all defined strings are case-sensitive.
-
-Full documentation of this format is at:
-
-http://code.neil.williamsleesmill.me.uk/qsf.html
-
-QSF itself is now being built into the QOF library for use with pilot-link to allow
-Palm objects to be described in QOF, written to XML as QSF and imported directly into
-GnuCash and other QOF-compliant applications. As a generic format, it does not depend
-on any pre-defined objects - as the current GnuCash XML format depends on AccountGroup.
-Instead, QSF is a simple container for all QOF objects.
-
-QSF grew from the qof_book_merge code base and uses the qof_book_merge code that is now
-part of QOF. Any QofBook generated by QSF still needs to be merged into the existing
-application data using qof_book_merge. See ::BookMerge.
-
-QSF can be used as an export or offline storage format for QOF applications (although
-long term storage may be best performed using separate (non-XML) methods, depending
-on the application).
-
-QSF is designed to cope with partial QofBooks at the QofObject level. There is no
-requirement for specific objects to always be defined, as long as each QOF object
-specified is fully defined, no orphan or missing parameters are allowed. Part of the
-handling for partial books requires a storage mechanism for references to entities
-that are not within reach of the current book. This requires a little extra coding
-in the QSF QofBackend to contain the reference data so that when the book is
-written out, the reference can be included. When the file is imported back in, a
-little extra code then rebuilds those references during the merge.
-
-Copying entites from an existing QofBook using the qof_entity_copy routines will
-automatically create the reference table. If your QOF objects use references to other
-entities, books that are created manually also need to create a reference table.
-
-Work is continuing on supporting QSF in GnuCash and QOF. QSF is a very open format -
-the majority of the work will be in standardising object types and creating maps that
-convert between objects. Applications that read QSF should ignore any objects that do
-not match the available maps and warn the user about missing data.
-
-Anyone is free to create their own QSF objects, subject to the GNU GPL. It is intended
-that QSF can be used as the flexible, open and free format for QOF data - providing
-all that is lacking from a typical CSV export with all the validation benefits of XML
-and the complex data handling of QOF. The QSF object and map formats remain under the
-GNU GPL licence and QSF is free software.
-
-\todo
- - Adding more map support, some parts of the map are still not coded. equals,
- variables and the conditional logic may not be up to the task of the
- datebook repetition calculations.
- - Rationalise the API - remove functions that shouldn't be public.
-
-\todo QOF contains numerous g_string_sprintf and g_string_sprintfa calls.
- These are deprecated and should be renamed to g_string_printf and g_string_append_printf
- respectively.
-
-QSF is in three sections:
- - QSF Backend : a QofBackend for file:/ QSF objects and maps.
- qsf-backend.c
- - QSF Object : Input, export and validation of QSF object files.
- qsf-xml.c
- - QSF Map : Validation, processing and conversion routines.
- qsf-xml-map.c
-
- @{ */
/** @file qsf-xml.h
- @brief QSF API - Backend, maps and objects.
+ @brief Private QSF header
@author Copyright (C) 2004-2005 Neil Williams <linux at codehelp.co.uk>
*/
@@ -147,7 +55,7 @@
HAVE_QSF_MAP, /**< A QSF object with the map it needs. */
OUR_QSF_OBJ, /**< A QSF object that can be loaded without a map. */
}qsf_type;
-
+
/** \brief Holds a description of the QofObject.
Used when converting QOF objects from another application. The incoming,
@@ -197,14 +105,14 @@
A pilot_addr_kvp type KVP parameter located at /user/name containing a guid value.
@{ */
-#define QSF_OBJECT_KVP "path" /**< The path to this KVP value in the entity frame. */
+#define QSF_OBJECT_KVP "path" /**< The path to this KVP value in the entity frame. */
#define QSF_OBJECT_VALUE "value" /**< The KVP Value. */
/** @} */
/** @name QSF Map XML
@{ */
-#define MAP_ROOT_TAG "qsf-map" /**< Top level root tag for QSF Maps */
-#define MAP_DEFINITION_TAG "definition" /**< Second level container for defined objects
+#define MAP_ROOT_TAG "qsf-map" /**< Top level root tag for QSF Maps */
+#define MAP_DEFINITION_TAG "definition" /**< Second level container for defined objects
Attributes: qof_version - Taken from the QOF_OBJECT_VERSION macro in QOF,
At the time of QSF development, QOF_OBJECT_VERSION is defined as 3. All
@@ -241,7 +149,7 @@
\a value Text representation of the required value. For numeric, use the format
[0-9]?/[0-9]?
-\attention Using boolean defaults
+\attention Using boolean defaults
A boolean default is not output in the QSF directly, instead the value is
used in the calculations to modify certain values. If the boolean default
@@ -420,26 +328,26 @@
*/
typedef struct qsf_metadata
{
- qsf_type file_type; /**< what type of file is being handled */
- qsf_objects *object_set; /**< current object set for qsf_object_list. */
- int count; /**< sequential counter for each object in the book */
- GList *qsf_object_list; /**< list of qsf_objects */
- GSList *qsf_sequence; /**< Parameter list sorted into QSF order */
+ qsf_type file_type; /**< what type of file is being handled */
+ qsf_objects *object_set; /**< current object set for qsf_object_list. */
+ int count; /**< sequential counter for each object in the book */
+ GList *qsf_object_list; /**< list of qsf_objects */
+ GSList *qsf_sequence; /**< Parameter list sorted into QSF order */
GList *referenceList; /**< Table of references, ::QofEntityReference. */
GHashTable *qsf_parameter_hash; /**< Hashtable of parameters for each object */
GHashTable *qsf_calculate_hash, *qsf_default_hash, *qsf_define_hash;
- GSList *supported_types; /**< The partial list of QOF types currently supported, in QSF order. */
+ GSList *supported_types; /**< The partial list of QOF types currently supported, in QSF order. */
xmlDocPtr input_doc, output_doc; /**< Pointers to the input and output xml document(s). */
/** \todo Review the list of xml nodes in qsf_param and rationalise. */
xmlNodePtr child_node, cur_node, param_node, output_node, output_root, book_node, lister;
xmlNsPtr qsf_ns, map_ns; /**< Separate namespaces for QSF objects and QSF maps. */
- const char *qof_type; /**< Holds details of the QOF_TYPE */
- QofIdType qof_obj_type; /**< current QofObject type (e_type) for the parameters. */
- QofEntity *qsf_ent; /**< Current entity in the book. */
- QofBackend *be; /**< the current QofBackend for this operation. */
+ const char *qof_type; /**< Holds details of the QOF_TYPE */
+ QofIdType qof_obj_type; /**< current QofObject type (e_type) for the parameters. */
+ QofEntity *qsf_ent; /**< Current entity in the book. */
+ QofBackend *be; /**< the current QofBackend for this operation. */
gboolean knowntype; /**< detect references by comparing with known QOF types. */
QofParam *qof_param; /**< used by kvp to handle the frame hash table */
- QofBook *book; /**< the current QofBook.
+ QofBook *book; /**< the current QofBook.
Theoretically, QSF can handle multiple QofBooks - currently limited to 1.
*/
@@ -739,7 +647,7 @@
context will be available. When just determining the type of file, qsf_param is
not necessary. Use the *_be functions from within the QofBackend and the
corresponding function in other code.
-
+
The file is validated against the QSF object schema, qsf-object.xsd.xml and
each object described in the file is checked to find out if a suitable QSF
map exists. Map files are accepted if all objects described in the QSF object
@@ -808,14 +716,6 @@
void
qsf_file_type (QofBackend *be, QofBook *book);
-/** \brief Describe this backend to the application.
-
-Sets QSF Backend Version 0.1, access method = file:
-
-This is the QOF backend interface, not the GnuCash module.
-*/
-void qsf_provider_init(void);
-
void
qsf_valid_foreach(xmlNodePtr parent, qsf_validCB cb,
struct qsf_node_iterate *iter, qsf_validator *valid);
@@ -825,20 +725,20 @@
struct qsf_node_iterate *iter, qsf_param *params);
/** \brief Loads the QSF into a QofSession, ready to merge.
-
+
Loads a QSF object file containing only GnuCash objects
into a second QofSession.
-
+
@param first_session A QofSession pointer to the original session. This
will become the target of the subsequent qof_book_merge.
@param path Absolute or relative path to the file to be loaded
-
+
@return ERR_BACKEND_NO_ERR == 0 on success, otherwise the QofBackendError
set by the QSFBackend.
-
+
\todo Build the qof_book_merge code onto this function if session loads
- properly.
+ properly.
*/
QofBackendError
qof_session_load_our_qsf_object(QofSession *first_session, const char *path);
@@ -846,13 +746,11 @@
/** \brief Placeholder so far.
\todo Determine the map to use and convert the QOF objects
-
+
Much of the map code is written but there is still work to do.
*/
QofBackendError
qof_session_load_qsf_object(QofSession *first_session, const char *path);
-
-void qsf_destroy_backend (QofBackend *be);
/** \brief Backend routine to write a file or stdout.
@@ -889,7 +787,7 @@
/** \brief Create a new QSF backend.
*/
QofBackend* qsf_backend_new(void);
-
+
/** @} */
/** @} */
Index: qsf-backend.c
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/backend/qsf/Attic/qsf-backend.c,v
retrieving revision 1.1.2.12
retrieving revision 1.1.2.13
diff -Lsrc/backend/qsf/qsf-backend.c -Lsrc/backend/qsf/qsf-backend.c -u -r1.1.2.12 -r1.1.2.13
--- src/backend/qsf/qsf-backend.c
+++ src/backend/qsf/qsf-backend.c
@@ -26,6 +26,7 @@
#include "qsf-xml.h"
#include "qsf-dir.h"
+#include "qof-backend-qsf.h"
#include <errno.h>
#define QSF_TYPE_BINARY "binary"
@@ -103,7 +104,7 @@
{
QSFBackend *qsf_be;
char *p, *path;
-
+
g_return_if_fail(be != NULL);
qsf_be = (QSFBackend*)be;
g_return_if_fail(qsf_be->params != NULL);
@@ -133,7 +134,7 @@
qsf_session_end( QofBackend *be)
{
QSFBackend *qsf_be;
-
+
qsf_be = (QSFBackend*)be;
g_return_if_fail(qsf_be != NULL);
qsf_free_params(qsf_be->params);
@@ -142,7 +143,8 @@
xmlCleanupParser();
}
-void qsf_destroy_backend (QofBackend *be)
+static void
+qsf_destroy_backend (QofBackend *be)
{
g_free(be);
}
@@ -470,10 +472,10 @@
return;
}
ref_name = g_strdup(reference->param->param_name);
- node = xmlAddChild(object_node, xmlNewNode(ns, QOF_TYPE_GUID));
+ node = xmlAddChild(object_node, xmlNewNode(ns, QOF_TYPE_GUID));
guid_to_string_buff(reference->ref_guid, qsf_guid);
- xmlNodeAddContent(node, qsf_guid);
- xmlNewProp(node, QSF_OBJECT_TYPE ,ref_name);
+ xmlNodeAddContent(node, qsf_guid);
+ xmlNewProp(node, QSF_OBJECT_TYPE ,ref_name);
g_free(ref_name);
}
}
@@ -543,10 +545,10 @@
if(0 == safe_strcmp(qof_param->param_type, QOF_TYPE_KVP))
{
qsf_kvp = kvp_frame_copy(qof_param->param_getfcn(ent,qof_param));
- params->qof_param = qof_param;
- params->output_node = object_node;
- kvp_frame_for_each_slot(qsf_kvp, qsf_from_kvp_helper, params);
- }
+ params->qof_param = qof_param;
+ params->output_node = object_node;
+ kvp_frame_for_each_slot(qsf_kvp, qsf_from_kvp_helper, params);
+ }
if((qof_param->param_setfcn != NULL) && (qof_param->param_getfcn != NULL))
{
supported = g_slist_copy(params->supported_types);
@@ -647,7 +649,7 @@
write_qsf_to_stdout(QofBook *book)
{
xmlDocPtr qsf_doc;
-
+
qsf_doc = qofbook_to_qsf(book);
g_return_if_fail(qsf_is_valid(QSF_SCHEMA_DIR, QSF_OBJECT_SCHEMA, qsf_doc) == TRUE);
xmlDocFormatDump(stdout, qsf_doc, 1);
@@ -906,15 +908,15 @@
boolean_setter = (void(*)(QofEntity*, gboolean))cm_setter;
if(boolean_setter != NULL) { boolean_setter(qsf_ent, cm_boolean); }
}
- if(safe_strcmp(qof_type, QOF_TYPE_KVP) == 0) {
- cm_type = qsf_to_kvp_helper(xmlGetProp(node, QSF_OBJECT_VALUE));
- if(!cm_type) { return; }
- cm_value = string_to_kvp_value(xmlNodeGetContent(node), cm_type);
- cm_kvp = kvp_frame_copy(cm_param->param_getfcn(qsf_ent, cm_param));
- cm_kvp = kvp_frame_set_value(cm_kvp, xmlGetProp(node, QSF_OBJECT_KVP), cm_value);
- kvp_frame_setter = (void(*)(QofEntity*, KvpFrame*))cm_setter;
- if(kvp_frame_setter != NULL) { kvp_frame_setter(qsf_ent, cm_kvp); }
- }
+ if(safe_strcmp(qof_type, QOF_TYPE_KVP) == 0) {
+ cm_type = qsf_to_kvp_helper(xmlGetProp(node, QSF_OBJECT_VALUE));
+ if(!cm_type) { return; }
+ cm_value = string_to_kvp_value(xmlNodeGetContent(node), cm_type);
+ cm_kvp = kvp_frame_copy(cm_param->param_getfcn(qsf_ent, cm_param));
+ cm_kvp = kvp_frame_set_value(cm_kvp, xmlGetProp(node, QSF_OBJECT_KVP), cm_value);
+ kvp_frame_setter = (void(*)(QofEntity*, KvpFrame*))cm_setter;
+ if(kvp_frame_setter != NULL) { kvp_frame_setter(qsf_ent, cm_kvp); }
+ }
if(safe_strcmp(qof_type, QOF_TYPE_COLLECT) == 0) {
QofCollection *qsf_coll;
QofIdType type;
--- /dev/null
+++ src/backend/qsf/qof-backend-qsf.h
@@ -0,0 +1,155 @@
+/***************************************************************************
+ * qof-backend-qsf.h
+ *
+ * Sat Jun 11 19:34:36 2005
+ * Copyright 2005 Neil Williams
+ * linux at codehelp.co.uk
+ ****************************************************************************/
+/*
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ */
+
+/** @addtogroup Backend
+ @{ */
+/** @addtogroup QSF QOF Serialisation Format
+
+This is the public interface of the qof-backend-qsf library.
+
+QSF - QOF Serialization Format is an XML serialization format
+i.e. it lays out a QOF object in a series of XML tags. The format will
+consist of two component formats:
+
+qof-qsf for the QSF object data and
+
+qsf-map to map sets of QSF objects between QOF applications.
+
+Maps exist to allow complex conversions between objects where object parameters
+need to be calculated, combined or processed using conditionals. Some QSF objects
+can be converted using XSL or other standard tools. For more information on maps,
+see http://code.neil.williamsleesmill.me.uk/map.html
+
+QSF object files will contain user data and are to be exported from QOF applications
+under user control or they can be hand-edited. QSF maps contain application data and
+can be created by application developers from application source code. Tools may be
+created later to generate maps interactively but maps require application support as
+well as an understanding of QOF objects in the import and output applications and are
+intended to remain within the scope of application developers rather than users.
+
+A QSF file written by one QOF application will need an appropriate QSF map before the
+data can be accessed by a different application using QOF. Any QSF objects that are
+not defined in the map will be ignored. QSF files written and accessed by the same
+application can use maps if necessary or can simply import the QSF data as a whole.
+
+Unless specifically mentioned otherwise, all defined strings are case-sensitive.
+
+Full documentation of this format is at:
+
+http://code.neil.williamsleesmill.me.uk/qsf.html
+
+QSF itself is now being built into the QOF library for use with pilot-link to allow
+Palm objects to be described in QOF, written to XML as QSF and imported directly into
+GnuCash and other QOF-compliant applications. As a generic format, it does not depend
+on any pre-defined objects - as the current GnuCash XML format depends on AccountGroup.
+Instead, QSF is a simple container for all QOF objects.
+
+QSF grew from the qof_book_merge code base and uses the qof_book_merge code that is now
+part of QOF. Any QofBook generated by QSF still needs to be merged into the existing
+application data using qof_book_merge. See ::BookMerge.
+
+QSF can be used as an export or offline storage format for QOF applications (although
+long term storage may be best performed using separate (non-XML) methods, depending
+on the application).
+
+QSF is designed to cope with partial QofBooks at the QofObject level. There is no
+requirement for specific objects to always be defined, as long as each QOF object
+specified is fully defined, no orphan or missing parameters are allowed. Part of the
+handling for partial books requires a storage mechanism for references to entities
+that are not within reach of the current book. This requires a little extra coding
+in the QSF QofBackend to contain the reference data so that when the book is
+written out, the reference can be included. When the file is imported back in, a
+little extra code then rebuilds those references during the merge.
+
+Copying entites from an existing QofBook using the qof_entity_copy routines will
+automatically create the reference table. If your QOF objects use references to other
+entities, books that are created manually also need to create a reference table.
+
+Work is continuing on supporting QSF in GnuCash and QOF. QSF is a very open format -
+the majority of the work will be in standardising object types and creating maps that
+convert between objects. Applications that read QSF should ignore any objects that do
+not match the available maps and warn the user about missing data.
+
+Anyone is free to create their own QSF objects, subject to the GNU GPL. It is intended
+that QSF can be used as the flexible, open and free format for QOF data - providing
+all that is lacking from a typical CSV export with all the validation benefits of XML
+and the complex data handling of QOF. The QSF object and map formats remain under the
+GNU GPL licence and QSF is free software.
+
+\todo
+ - Adding more map support, some parts of the map are still not coded. equals,
+ variables and the conditional logic may not be up to the task of the
+ datebook repetition calculations.
+ - Rationalise the API - remove functions that shouldn't be public.
+
+\todo QOF contains numerous g_string_sprintf and g_string_sprintfa calls.
+ These are deprecated and should be renamed to g_string_printf and g_string_append_printf
+ respectively.
+
+QSF is in three sections:
+ - QSF Backend : a QofBackend for file:/ QSF objects and maps.
+ qsf-backend.c
+ - QSF Object : Input, export and validation of QSF object files.
+ qsf-xml.c
+ - QSF Map : Validation, processing and conversion routines.
+ qsf-xml-map.c
+
+ @{ */
+/** @file qof-backend-qsf.h
+ @brief QSF API - Backend, maps and objects.
+ @author Copyright (C) 2004-2005 Neil Williams <linux at codehelp.co.uk>
+*/
+
+#ifndef _QOF_BACKEND_QSF_H
+#define _QOF_BACKEND_QSF_H
+
+#include "qofbackend.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+/** \brief Describe this backend to the application.
+
+Sets QSF Backend Version 0.1, access method = file:
+
+This is the QOF backend interface, not a GnuCash module.
+*/
+void qsf_provider_init(void);
+
+/** \brief Create a new QSF backend.
+
+ Initialises the backend and provides access to the
+ functions that will load and save the data.
+*/
+QofBackend* qsf_backend_new(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */
+/** @} */
+
+#endif /* _QOF_BACKEND_QSF_H */
More information about the gnucash-changes
mailing list