redesign gemini API to be more generically useful

git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@9037 57a11ea4-9604-0410-9ed3-97b8803252fd

src/engine/Account.c

@@ -215,9 +215,13 @@ xaccCloneAccount (const Account *from, QofBook *book)
     ret->non_standard_scu = from->non_standard_scu;
     ret->core_dirty   = TRUE;
 
-    /* make a note of where the copy came from */
-    gnc_kvp_gemini (ret->kvp_data, &from->guid, &from->book->guid, now);
-    gnc_kvp_gemini (from->kvp_data, &ret->guid, &book->guid, now);
+    /* Make a note of where the copy came from */
+    gnc_kvp_gemini (ret->kvp_data, now, "acct_guid", &from->guid, 
+                                        "book_guid", &from->book->guid,
+                                        NULL);
+    gnc_kvp_gemini (from->kvp_data, now, "acct_guid", &ret->guid, 
+                                         "book_guid", &book->guid, 
+                                         NULL);
 
     LEAVE (" ");
     return ret;

src/engine/Period.c

@@ -363,8 +363,8 @@ gnc_book_partition (QofBook *dest_book, QofBook *src_book, QofQuery *query)
 
    /* Make note of the sibling books */
    now = time(0);
-   gnc_kvp_gemini (src_book->kvp_data, NULL, &dest_book->guid, now);
-   gnc_kvp_gemini (dest_book->kvp_data, NULL, &src_book->guid, now);
+   gnc_kvp_gemini (src_book->kvp_data, now, "book_guid", &dest_book->guid, NULL);
+   gnc_kvp_gemini (dest_book->kvp_data, now, "book_guid", &src_book->guid, NULL);
 
    if (be && be->commit)
    {

src/engine/Scrub2.c

@@ -44,6 +44,7 @@
 #include "gnc-engine-util.h"
 #include "gnc-lot.h"
 #include "gnc-lot-p.h"
+#include "kvp-util-p.h"
 #include "messages.h"
 
 static short module = MOD_LOT;
@@ -127,6 +128,7 @@ void
 xaccAccountScrubLots (Account *acc)
 {
    SplitList *node;
+   time_t now = time(0);
 
    if (!acc) return;
 
@@ -210,24 +212,29 @@ xaccAccountScrubLots (Account *acc)
                * because the new balance should be precisely zero. */
               gnc_lot_add_split (lot, split);
 
-              /* put the remainder of the balance into a new split, which is
-               * in other respects just a clone of this one */
-              /* XXX FIXME: we should add some kvp markup to indicate that these
-               * two splits used to be one before being 'split' */
+              /* Put the remainder of the balance into a new split,
+               * which is in other respects just a clone of this one */
               new_split = xaccMallocSplit (acc->book);
 
-              /* Copy most of teh split attributes */
+              /* Copy most of the split attributes */
               xaccSplitSetMemo (new_split, xaccSplitGetMemo (split));
               xaccSplitSetAction (new_split, xaccSplitGetAction (split));
               xaccSplitSetReconcile (new_split, xaccSplitGetReconcile (split));
               ts = xaccSplitRetDateReconciledTS (split);
               xaccSplitSetDateReconciledTS (new_split, &ts);
 
               /* Copying the KVP tree seems like the right thing to do, 
-               * this is potentially dangerous, depending on how other 
-               * users use it.*/
+               * but this is potentially dangerous, depending on how other 
+               * users use it. XXX this needs some thinking ... */
               xaccSplitSetSlots_nc (new_split, kvp_frame_copy(xaccSplitGetSlots (split)));  
 
+              /* Make a pair of pointers, to show that these two splits
+               * used to be one ... */
+              gnc_kvp_gemini (xaccSplitGetSlots (split), now,
+                          "split_guid", xaccSplitGetGUID (new_split), NULL);
+              gnc_kvp_gemini (xaccSplitGetSlots (new_split), now,
+                          "split_guid", xaccSplitGetGUID (split), NULL);
+
               xaccSplitSetAmount (new_split, amt_b);
               xaccSplitSetValue (new_split, val_b);
 

src/engine/kvp-util-p.h

@@ -1,6 +1,5 @@
 /********************************************************************\
  * kvp_util.h -- misc odd-job kvp utils                             *
- * Copyright (C) 2001 Linas Vepstas <linas@linas.org>               *
  *                                                                  *
  * This program is free software; you can redistribute it and/or    *
  * modify it under the terms of the GNU General Public License as   *
@@ -29,18 +28,36 @@
 #include "guid.h"
 #include "kvp_frame.h"
 
-/* PRIVATE FILE 
+/* @file kvp_util.h
+ * @breif misc odd-job kvp utils engine-private routines
+ * @author Copyright (C) 2001, 2003 Linas Vepstas <linas@linas.org>               *
+ * @note PRIVATE FILE 
  * -- these routines are private to the engine. The should not be used 
  *    outside of the engine.
  */
 
-/* 
- * The gnc_kvp_gemini() routine:
- * mark the guid and date of the copy, using kvp.  The info will be
- * placed in /gemini/ncopies, /gemini/<n>/acct_guid, /gemini/<n>/book_guid,
- * /gemini/<n>/date, where <n> = ncopies-1.
+/** This routine is used to create a 'pointer' to an object in a kvp tree.
+ *  The thing being pointed at is uniquely identified by its GUID. 
+ *  This routine is typically used to create a linked list, and/or
+ *  a collection of pointers to objects that are 'related' to each 
+ *  other in some way.
+ *
+ *  The var-args should be pairs of strings (const char *) followed by
+ *  the corresponding GUID pointer (const GUID *).  Terminate the varargs
+ *  with a NULL as the last string argument.
+ *
+ *  The actual 'pointer' is stored in an array in the subdirectory
+ *  '/gemini'.  The size of the array is in /gemini/ncopies.  The
+ *  pointer is stored in /gemini/<n>/<name> where <n> = ncopies -1, 
+ *  <name> was passed as an argument.  In addition, the date is 
+ *  logged.  Thus, for example:
+ *  gnc_kvp_gemini (kvp, secs, "acct_guid", aguid, "book_guid", bguid, NULL);
+ *  will increment /gemini/ncopies, and will store aguid in 
+ *  /gemini/<n>/acct_guid and bguid in /gemini/<n>/book_guid, where
+ *  <n> = ncopies-1
  */
 
-void gnc_kvp_gemini (KvpFrame *, const GUID *, const GUID *, time_t);
+void gnc_kvp_gemini (KvpFrame *kvp_root, time_t secs, 
+                     const char *first_name, ...);
 
 #endif /* XACC_KVP_UTIL_P_H */

src/engine/kvp-util.c

@@ -32,60 +32,61 @@
 #include "kvp-util-p.h"
 
 /* ================================================================ */
-/* mark the guid and date of the copy, using kvp.  The info will be
- * places in /gemini/ncopies, /gemini/<n>/acct_guid, /gemini/<n>/book_guid,
- * /gemini/<n>/date, where <n> = ncopies-1.
- */
-
+
 void 
-gnc_kvp_gemini (KvpFrame *kvp_root, const GUID *acct_guid, 
-        const GUID *book_guid, time_t secs)
+gnc_kvp_gemini (KvpFrame *kvp_root, time_t secs, const char *first_name, ...)
 {
+   va_list ap;
    char buff[80];
    KvpFrame *cwd, *pwd;
-   KvpValue *v_ncopies, *vvv;
+   KvpValue *v_ncopies;
    gint64 ncopies = 0;
    Timespec ts;
+   const char *name;
 
    if (!kvp_root) return;
+   if (!first_name) return;
 
    /* cwd == 'current working directory' */
    pwd = kvp_frame_get_frame (kvp_root, "gemini", NULL);
    if (!pwd) return;  /* error: can't ever happen */
 
-   /* find, increment, store number of copies */
+   /* Find, increment, store number of copies */
    v_ncopies = kvp_frame_get_slot (pwd, "ncopies");
    if (v_ncopies)
    { 
       ncopies = kvp_value_get_gint64 (v_ncopies);
    }
 
    ncopies ++;
-   v_ncopies = kvp_value_new_gint64 (ncopies);
-   kvp_frame_set_slot_nc (pwd, "ncopies", v_ncopies);
+   kvp_frame_set_gint64 (pwd, "ncopies", ncopies);
 
    /* OK, now create subdirectory and put the actual data */
    --ncopies;
    sprintf (buff, GNC_SCANF_LLD, (long long int) ncopies);
    cwd = kvp_frame_new();
    kvp_frame_set_slot_nc(pwd, buff, kvp_value_new_frame_nc(cwd));
 
-   if (acct_guid)
-   {
-      vvv = kvp_value_new_guid (acct_guid);
-      kvp_frame_set_slot_nc (cwd, "acct_guid", vvv);
-   }
+   /* Record the time */
+   ts.tv_sec = secs;
+   ts.tv_nsec = 0;
+   kvp_frame_set_timespec (cwd, "date", ts);
 
-   if (book_guid)
+   /* Loop over the args */
+   va_start (ap, first_name);
+   name = first_name;
+
+   while (name)
    {
-      vvv = kvp_value_new_guid (book_guid);
-      kvp_frame_set_slot_nc (cwd, "book_guid", vvv);
+      const GUID *guid;
+      guid = va_arg (ap, const GUID *);
+
+      kvp_frame_set_guid (cwd, name, guid);
+
+      name = va_arg (ap, const char *);
    }
 
-   ts.tv_sec = secs;
-   ts.tv_nsec = 0;
-   vvv = kvp_value_new_timespec (ts);
-   kvp_frame_set_slot_nc (cwd, "date", vvv);
+   va_end (ap);
 }
 
 /* ================================================================ */