Account.c

/********************************************************************\
 * Account.c -- Account data structure implementation               *
 * Copyright (C) 1997 Robin D. Clark                                *
 * Copyright (C) 1997-2003 Linas Vepstas <linas@linas.org>          *
 * Copyright (C) 2007 David Hampton <hampton@employees.org>         *
 *                                                                  *
 * 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 General Public License for more details.                     *
 *                                                                  *
 * You should have received a copy of the GNU General Public License*
 * along with this program; if not, contact:                        *
 *                                                                  *
 * Free Software Foundation           Voice:  +1-617-542-5942       *
 * 51 Franklin Street, Fifth Floor    Fax:    +1-617-542-2652       *
 * Boston, MA  02110-1301,  USA       gnu@gnu.org                   *
 *                                                                  *
\********************************************************************/

#include "config.h"

#include <glib.h>
#include <glib/gi18n.h>
#include <stdlib.h>
#include <string.h>

#include "AccountP.h"
#include "Split.h"
#include "Transaction.h"
#include "TransactionP.h"
#include "gnc-event.h"
#include "gnc-glib-utils.h"
#include "gnc-lot.h"
#include "gnc-lot-p.h"
#include "gnc-pricedb.h"

#define GNC_ID_ROOT_ACCOUNT        "RootAccount"

static QofLogModule log_module = GNC_MOD_ACCOUNT;

/* The Canonical Account Separator.  Pre-Initialized. */
static gchar account_separator[8] = ".";
gunichar account_uc_separator = ':';

enum {
    LAST_SIGNAL
};

enum {
  PROP_0,
  PROP_NAME,
  PROP_FULL_NAME,
  PROP_CODE,
  PROP_DESCRIPTION,
  PROP_NOTES,
  PROP_TYPE,

  PROP_COMMODITY,
  PROP_COMMODITY_SCU,
  PROP_NON_STD_SCU,
  PROP_SORT_DIRTY,
  PROP_BALANCE_DIRTY,
  PROP_START_BALANCE,
  PROP_START_CLEARED_BALANCE,
  PROP_START_RECONCILED_BALANCE,
  PROP_END_BALANCE,
  PROP_END_CLEARED_BALANCE,
  PROP_END_RECONCILED_BALANCE,

  PROP_POLICY,
  PROP_MARK,
  PROP_TAX_RELATED,
  PROP_TAX_CODE,
  PROP_TAX_SOURCE,
};

typedef struct AccountPrivate
{
    /* The accountName is an arbitrary string assigned by the user. 
     * It is intended to a short, 5 to 30 character long string that
     * is displayed by the GUI as the account mnemonic. 
     */
    char *accountName;

    /* The accountCode is an arbitrary string assigned by the user.
     * It is intended to be reporting code that is a synonym for the 
     * accountName. Typically, it will be a numeric value that follows 
     * the numbering assignments commonly used by accountants, such 
     * as 100, 200 or 600 for top-level accounts, and 101, 102..  etc.
     * for detail accounts.
     */
    char *accountCode;

    /* The description is an arbitrary string assigned by the user. 
     * It is intended to be a longer, 1-5 sentence description of what
     * this account is all about.
     */
    char *description;

    /* The type field is the account type, picked from the enumerated
     * list that includes ACCT_TYPE_BANK, ACCT_TYPE_STOCK,
     * ACCT_TYPE_CREDIT, ACCT_TYPE_INCOME, etc.  Its intended use is to
     * be a hint to the GUI as to how to display and format the
     * transaction data.
     */
    GNCAccountType type;

    /* 
     * The commodity field denotes the kind of 'stuff' stored 
     * in this account.  The 'amount' field of a split indicates
     * how much of the 'stuff' there is.
     */
    gnc_commodity * commodity;
    int commodity_scu;
    gboolean non_standard_scu;

    /* The parent and children pointers are used to implement an account
     * hierarchy, of accounts that have sub-accounts ("detail accounts").
     */
    Account *parent;    /* back-pointer to parent */
    GList *children;    /* list of sub-accounts */

    /* protected data - should only be set by backends */
    gnc_numeric starting_balance;
    gnc_numeric starting_cleared_balance;
    gnc_numeric starting_reconciled_balance;

    /* cached parameters */
    gnc_numeric balance;
    gnc_numeric cleared_balance;
    gnc_numeric reconciled_balance;

    gboolean balance_dirty;     /* balances in splits incorrect */

    GList *splits;              /* list of split pointers */
    gboolean sort_dirty;        /* sort order of splits is bad */

    LotList   *lots;            /* list of lot pointers */
    GNCPolicy *policy;          /* Cached pointer to policy method */

    /* The "mark" flag can be used by the user to mark this account
     * in any way desired.  Handy for specialty traversals of the 
     * account tree. */
    short mark;
} AccountPrivate;

#define GET_PRIVATE(o)  \
   (G_TYPE_INSTANCE_GET_PRIVATE ((o), GNC_TYPE_ACCOUNT, AccountPrivate))

/********************************************************************\
 * Because I can't use C++ for this project, doesn't mean that I    *
 * can't pretend to!  These functions perform actions on the        *
 * account data structure, in order to encapsulate the knowledge    *
 * of the internals of the Account in one file.                     *
\********************************************************************/

static void xaccAccountBringUpToDate (Account *acc);


/********************************************************************\
 * gnc_get_account_separator                                        *
 *   returns the current account separator character                *
 *                                                                  *
 * Args: none                                                       *
 * Returns: account separator character                             *
 \*******************************************************************/
const gchar *
gnc_get_account_separator_string (void)
{
  return account_separator;
}

gunichar
gnc_get_account_separator (void)
{
  return account_uc_separator;
}

void
gnc_set_account_separator (const gchar *separator)
{
  gunichar uc;
  gint count;

  uc = g_utf8_get_char_validated(separator, -1);
  if ((uc == (gunichar)-2) || (uc == (gunichar)-1) || g_unichar_isalnum(uc)) {
    account_uc_separator = ':';
    strcpy(account_separator, ":");
    return;
  }

  account_uc_separator = uc;
  count = g_unichar_to_utf8(uc, account_separator);
  account_separator[count] = '\0';
}

/********************************************************************\
\********************************************************************/

G_INLINE_FUNC void mark_account (Account *acc);
void
mark_account (Account *acc)
{
  qof_instance_set_dirty(&acc->inst);
}

/********************************************************************\
\********************************************************************/

/* GObject Initialization */
G_DEFINE_TYPE(Account, gnc_account, QOF_TYPE_INSTANCE)

static void
gnc_account_init(Account* acc)
{
    AccountPrivate *priv;

    priv = GET_PRIVATE(acc);
    priv->parent   = NULL;
    priv->children = NULL;

    priv->accountName = CACHE_INSERT("");
    priv->accountCode = CACHE_INSERT("");
    priv->description = CACHE_INSERT("");

    priv->type = ACCT_TYPE_NONE;

    priv->mark = 0;

    priv->policy = xaccGetFIFOPolicy();
    priv->lots = NULL;

    priv->commodity = NULL;
    priv->commodity_scu = 0;
    priv->non_standard_scu = FALSE;

    priv->balance = gnc_numeric_zero();
    priv->cleared_balance = gnc_numeric_zero();
    priv->reconciled_balance = gnc_numeric_zero();
    priv->starting_balance = gnc_numeric_zero();
    priv->starting_cleared_balance = gnc_numeric_zero();
    priv->starting_reconciled_balance = gnc_numeric_zero();
    priv->balance_dirty = FALSE;

    priv->splits = NULL;
    priv->sort_dirty = FALSE;
 }

static void
gnc_account_dispose (GObject *acctp)
{
    G_OBJECT_CLASS(gnc_account_parent_class)->dispose(acctp);
}

static void
gnc_account_finalize(GObject* acctp)
{
    G_OBJECT_CLASS(gnc_account_parent_class)->finalize(acctp);
}

static void
gnc_account_get_property (GObject         *object,
                          guint            prop_id,
                          GValue          *value,
                          GParamSpec      *pspec)
{
    Account *account;
    AccountPrivate *priv;

    g_return_if_fail(GNC_IS_ACCOUNT(object));

    account = GNC_ACCOUNT(object);
    priv = GET_PRIVATE(account);
    switch (prop_id) {
        case PROP_NAME:
            g_value_set_string(value, priv->accountName);
            break;
        case PROP_FULL_NAME:
            g_value_take_string(value, xaccAccountGetFullName(account));
            break;
        case PROP_CODE:
            g_value_set_string(value, priv->accountCode);
            break;
        case PROP_DESCRIPTION:
            g_value_set_string(value, priv->description);
            break;
        case PROP_NOTES:
            g_value_set_string(value, xaccAccountGetNotes(account));
            break;
        case PROP_TYPE:
            // NEED TO BE CONVERTED TO A G_TYPE_ENUM
            g_value_set_int(value, priv->type);
            break;
        case PROP_COMMODITY:
            g_value_set_object(value, priv->commodity);
            break;
        case PROP_COMMODITY_SCU:
            g_value_set_int(value, priv->commodity_scu);
            break;
        case PROP_NON_STD_SCU:
            g_value_set_boolean(value, priv->non_standard_scu);
            break;
        case PROP_SORT_DIRTY:
            g_value_set_boolean(value, priv->sort_dirty);
            break;
        case PROP_BALANCE_DIRTY:
            g_value_set_boolean(value, priv->balance_dirty);
            break;
        case PROP_START_BALANCE:
            g_value_set_boxed(value, &priv->starting_balance);
            break;
        case PROP_START_CLEARED_BALANCE:
            g_value_set_boxed(value, &priv->starting_cleared_balance);
            break;
        case PROP_START_RECONCILED_BALANCE:
            g_value_set_boxed(value, &priv->starting_reconciled_balance);
            break;
        case PROP_END_BALANCE:
            g_value_set_boxed(value, &priv->balance);
            break;
        case PROP_END_CLEARED_BALANCE:
            g_value_set_boxed(value, &priv->cleared_balance);
            break;
        case PROP_END_RECONCILED_BALANCE:
            g_value_set_boxed(value, &priv->reconciled_balance);
            break;
        case PROP_POLICY:
            /* MAKE THIS A BOXED VALUE */
            g_value_set_pointer(value, priv->policy);
            break;
        case PROP_MARK:
            g_value_set_int(value, priv->mark);
            break;
        case PROP_TAX_RELATED:
            g_value_set_boolean(value, xaccAccountGetTaxRelated(account));
            break;
        case PROP_TAX_CODE:
            g_value_set_string(value, xaccAccountGetTaxUSCode(account));
            break;
        case PROP_TAX_SOURCE:
            g_value_set_string(value,
                               xaccAccountGetTaxUSPayerNameSource(account));
            break;
        default:
            G_OBJECT_WARN_INVALID_PROPERTY_ID(object, prop_id, pspec);
            break;
    }
}

static void
gnc_account_set_property (GObject         *object,
                          guint            prop_id,
                          const GValue    *value,
                          GParamSpec      *pspec)
{
    Account *account;
    gnc_numeric *number;

    g_return_if_fail(GNC_IS_ACCOUNT(object));

    account = GNC_ACCOUNT(object);

    switch (prop_id) {
        case PROP_NAME:
            xaccAccountSetName(account, g_value_get_string(value));
            break;
        case PROP_CODE:
            xaccAccountSetCode(account, g_value_get_string(value));
            break;
        case PROP_DESCRIPTION:
            xaccAccountSetDescription(account, g_value_get_string(value));
            break;
        case PROP_NOTES:
            xaccAccountSetNotes(account, g_value_get_string(value));
            break;
        case PROP_TYPE:
            // NEED TO BE CONVERTED TO A G_TYPE_ENUM
            xaccAccountSetType(account, g_value_get_int(value));
            break;
        case PROP_COMMODITY:
            xaccAccountSetCommodity(account, g_value_get_object(value));
            break;
        case PROP_COMMODITY_SCU:
            xaccAccountSetCommoditySCU(account, g_value_get_int(value));
            break;
        case PROP_SORT_DIRTY:
            gnc_account_set_sort_dirty(account);
            break;
        case PROP_BALANCE_DIRTY:
            gnc_account_set_balance_dirty(account);
            break;
        case PROP_START_BALANCE:
            number = g_value_get_boxed(value);
            gnc_account_set_start_balance(account, *number);
            break;
        case PROP_START_CLEARED_BALANCE:
            number = g_value_get_boxed(value);
            gnc_account_set_start_cleared_balance(account, *number);
            break;
        case PROP_START_RECONCILED_BALANCE:
            number = g_value_get_boxed(value);
            gnc_account_set_start_reconciled_balance(account, *number);
            break;
        case PROP_POLICY:
            gnc_account_set_policy(account, g_value_get_pointer(value));
            break;
        case PROP_MARK:
            xaccAccountSetMark(account, g_value_get_int(value));
            break;
        case PROP_TAX_RELATED:
            xaccAccountSetTaxRelated(account, g_value_get_boolean(value));
            break;
        case PROP_TAX_CODE:
            xaccAccountSetTaxUSCode(account, g_value_get_string(value));
            break;
        case PROP_TAX_SOURCE:
            xaccAccountSetTaxUSPayerNameSource(account,
                                               g_value_get_string(value));
        default:
            G_OBJECT_WARN_INVALID_PROPERTY_ID(object, prop_id, pspec);
            break;
    }    
}



static void
gnc_account_class_init (AccountClass *klass)
{
    GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
        
    gobject_class->dispose = gnc_account_dispose;
    gobject_class->finalize = gnc_account_finalize;
    gobject_class->set_property = gnc_account_set_property;
    gobject_class->get_property = gnc_account_get_property;

    g_type_class_add_private(klass, sizeof(AccountPrivate));

    g_object_class_install_property
        (gobject_class,
         PROP_NAME,
         g_param_spec_string ("name",
                              "Account Name",
                              "The accountName is an arbitrary string "
                              "assigned by the user.  It is intended to "
                              "a short, 5 to 30 character long string "
                              "that is displayed by the GUI as the "
                              "account mnemonic.  Account names may be "
                              "repeasted. but no two accounts that share "
                              "a parent may have the same name.",
                              NULL,
                              G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_FULL_NAME,
         g_param_spec_string ("fullname",
                              "Full Account Name",
                              "The name of the account concatenated with "
                              "all its parent account names to indicate "
                              "a unique account.",
                              NULL,
                              G_PARAM_READABLE));

    g_object_class_install_property
        (gobject_class,
         PROP_CODE,
         g_param_spec_string ("code",
                              "Account Code",
                              "The account code is an arbitrary string "
                              "assigned by the user. It is intended to "
                              "be reporting code that is a synonym for "
                              "the accountName.",
                              NULL,
                              G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_DESCRIPTION,
         g_param_spec_string ("description",
                              "Account Description",
                              "The account description is an arbitrary "
                              "string assigned by the user. It is intended "
                              "to be a longer, 1-5 sentence description of "
                              "what this account is all about.",
                              NULL,
                              G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_NOTES,
         g_param_spec_string ("notes",
                              "Account Notes",
                              "The account notes is an arbitrary provided "
                              "for the user to attach any orther text that "
                              "they would like to associate with the account.",
                              NULL,
                              G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_TYPE,
         g_param_spec_int ("type",
                           "Account Type",
                           "The account type, picked from the enumerated list "
                           "that includes ACCT_TYPE_BANK, ACCT_TYPE_STOCK, "
                           "ACCT_TYPE_CREDIT, ACCT_TYPE_INCOME, etc.",
                           ACCT_TYPE_NONE,
                           NUM_ACCOUNT_TYPES - 1,
                           ACCT_TYPE_BANK,
                           G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_COMMODITY,
         g_param_spec_object ("commodity",
                              "Commodity",
                              "The commodity field denotes the kind of "
                              "'stuff' stored  in this account, whether "
                              "it is USD, gold, stock, etc.",
                              GNC_TYPE_COMMODITY,
                              G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_COMMODITY_SCU,
         g_param_spec_int ("commodity-scu",
                           "Commodity SCU",
                           "The smallest fraction of the commodity that is "
                           "tracked.  This number is used as the denominator "
                           "value in 1/x, so a value of 100 says that the "
                           "commodity can be divided into hundreths.  E.G."
                           "1 USD can be divided into 100 cents.",
                           0,
                           G_MAXINT32,
                           1000000,
                           G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_NON_STD_SCU,
         g_param_spec_boolean ("non-std-scu",
                               "Non-std SCU",
                               "TRUE id the account SCU doesn't match "
                               "the commodity SCU.  This indicates a case "
                               "where the two were accidentally set to "
                               "mismatched values in older versions of "
                               "GnuCash.",
                               FALSE,
                               G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_SORT_DIRTY,
         g_param_spec_boolean("sort-dirty",
                              "Sort Dirty",
                              "TRUE if the splits in the account needs to be "
                              "resorted.  This flag is set by the accounts "
                              "code for certain internal modifications, or "
                              "when external code calls the engine to say a "
                              "split has been modified in a way that may "
                              "affect the sort order of the account. Note: "
                              "This value can only be set to TRUE.",
                              FALSE,
                              G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_BALANCE_DIRTY,
         g_param_spec_boolean("balance-dirty",
                              "Balance Dirty",
                              "TRUE if the running balances in the account "
                              "needs to be recalculated.  This flag is set "
                              "by the accounts code for certain internal "
                              "modifications, or when external code calls "
                              "the engine to say a split has been modified. "
                              "Note: This value can only be set to TRUE.",
                              FALSE,
                              G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_START_BALANCE,
         g_param_spec_boxed("start-balance",
                            "Starting Balance",
                            "The starting balance for the account.  This "
                            "parameter is intended for use with backends that "
                            "do not return the complete list of splits for an "
                            "account, but rather return a partial list.  In "
                            "such a case, the backend will typically return "
                            "all of the splits after some certain date, and "
                            "the 'starting balance' will represent the "
                            "summation of the splits up to that date.",
                            GNC_TYPE_NUMERIC,
                            G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_START_CLEARED_BALANCE,
         g_param_spec_boxed("start-cleared-balance",
                            "Starting Cleared Balance",
                            "The starting cleared balance for the account.  "
                            "This parameter is intended for use with backends "
                            "that do not return the complete list of splits "
                            "for an account, but rather return a partial "
                            "list.  In such a case, the backend will "
                            "typically return all of the splits after "
                            "some certain date, and the 'starting cleared "
                            "balance' will represent the summation of the "
                            "splits up to that date.",
                            GNC_TYPE_NUMERIC,
                            G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_START_RECONCILED_BALANCE,
         g_param_spec_boxed("start-reconciled-balance",
                            "Starting Reconciled Balance",
                            "The starting reconciled balance for the "
                            "account.  This parameter is intended for use "
                            "with backends that do not return the complete "
                            "list of splits for an account, but rather return "
                            "a partial list.  In such a case, the backend "
                            "will typically return all of the splits after "
                            "some certain date, and the 'starting recontiled "
                            "balance' will represent the summation of the "
                            "splits up to that date.",
                             GNC_TYPE_NUMERIC,
                             G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_END_BALANCE,
         g_param_spec_boxed("end-balance",
                            "Ending Account Balance",
                            "This is the current ending balance for the "
                            "account.  It is computed from the sum of the "
                            "starting balance and all splits in the account.",
                            GNC_TYPE_NUMERIC,
                            G_PARAM_READABLE));

    g_object_class_install_property
        (gobject_class,
         PROP_END_CLEARED_BALANCE,
         g_param_spec_boxed("end-cleared-balance",
                            "Ending Account Cleared Balance",
                            "This is the current ending cleared balance for "
                            "the account.  It is computed from the sum of the "
                            "starting balance and all cleared splits in the "
                            "account.",
                            GNC_TYPE_NUMERIC,
                            G_PARAM_READABLE));

    g_object_class_install_property
        (gobject_class,
         PROP_END_RECONCILED_BALANCE,
         g_param_spec_boxed("end-reconciled-balance",
                            "Ending Account Reconciled Balance",
                            "This is the current ending reconciled balance "
                            "for the account.  It is computed from the sum of "
                            "the starting balance and all reconciled splits "
                            "in the account.",
                            GNC_TYPE_NUMERIC,
                            G_PARAM_READABLE));

    g_object_class_install_property
        (gobject_class,
         PROP_POLICY,
         g_param_spec_pointer ("policy",
                               "Policy",
                               "The account lots policy.",
                               G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_MARK,
         g_param_spec_int ("acct-mark",
                           "Account Mark",
                           "Ipsum Lorem",
                           0,
                           G_MAXINT16,
                           0,
                           G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_TAX_RELATED,
         g_param_spec_boolean ("tax-related",
                               "Tax Related",
                               "Whether the account maps to an entry on an "
                               "income tax document.",
                               FALSE,
                               G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_TAX_CODE,
         g_param_spec_string ("tax-code",
                              "Tax Code",
                              "This is the code for mapping an account to a "
                              "specific entry on a taxable document.  In the "
                              "United States it is used to transfer totals "
                              "into tax preparation software.",
                              NULL,
                              G_PARAM_READWRITE));

    g_object_class_install_property
        (gobject_class,
         PROP_TAX_SOURCE,
         g_param_spec_string ("tax-source",
                              "Tax Source",
                              "This is an unknown tax related field.",
                              NULL,
                              G_PARAM_READWRITE));
}

static void
xaccInitAccount (Account * acc, QofBook *book)
{
  ENTER ("book=%p\n", book);
  qof_instance_init_data (&acc->inst, GNC_ID_ACCOUNT, book);

  LEAVE ("account=%p\n", acc);
}

/********************************************************************\
\********************************************************************/

QofBook *
gnc_account_get_book(const Account *account)
{
  return qof_instance_get_book(QOF_INSTANCE(account));
}

/********************************************************************\
\********************************************************************/

static Account * 
gnc_coll_get_root_account (QofCollection *col)
{
  if (!col) return NULL;
  return qof_collection_get_data (col);
}

static void
gnc_coll_set_root_account (QofCollection *col, Account *root)
{
  AccountPrivate *rpriv;
  Account *old_root;
  if (!col) return;

  old_root = gnc_coll_get_root_account (col);
  if (old_root == root) return;

  /* If the new root is already linked into the tree somewhere, then
   * remove it from its current position before adding it at the
   * top. */
  rpriv = GET_PRIVATE(root);
  if (rpriv->parent) {
    xaccAccountBeginEdit(root);
    gnc_account_remove_child(rpriv->parent, root);
    xaccAccountCommitEdit(root);
  }
    
  qof_collection_set_data (col, root);

  if (old_root) {
    xaccAccountBeginEdit (old_root);
    xaccAccountDestroy (old_root);
  }
}

Account *
gnc_book_get_root_account (QofBook *book)
{
  QofCollection *col;
  Account *root;

  if (!book) return NULL;
  col = qof_book_get_collection (book, GNC_ID_ROOT_ACCOUNT);
  root = gnc_coll_get_root_account (col);
  if (root == NULL)
    root = gnc_account_create_root(book);
  return root;
}

void
gnc_book_set_root_account (QofBook *book, Account *root)
{
  QofCollection *col;
  if (!book) return;

  if (root && gnc_account_get_book(root) != book)
  {
     PERR ("cannot mix and match books freely!");
     return;
  }

  col = qof_book_get_collection (book, GNC_ID_ROOT_ACCOUNT);
  gnc_coll_set_root_account (col, root);
}

/********************************************************************\
\********************************************************************/

Account *
xaccMallocAccount (QofBook *book)
{
  Account *acc;

  g_return_val_if_fail (book, NULL);

  acc = g_object_new (GNC_TYPE_ACCOUNT, NULL);
  xaccInitAccount (acc, book);
  qof_event_gen (&acc->inst, QOF_EVENT_CREATE, NULL);

  return acc;
}

Account *
gnc_account_create_root (QofBook *book)
{
  Account *root;
  AccountPrivate *rpriv;

  root = xaccMallocAccount(book);
  rpriv = GET_PRIVATE(root);
  xaccAccountBeginEdit(root);
  rpriv->type = ACCT_TYPE_ROOT;
  CACHE_REPLACE(rpriv->accountName, "Root Account");
  xaccAccountCommitEdit(root);
  gnc_book_set_root_account(book, root);
  return root;
}

static Account *
xaccCloneAccountCommon(const Account *from, QofBook *book)
{
    Account *ret;
    AccountPrivate *from_priv, *priv;

    g_return_val_if_fail(GNC_IS_ACCOUNT(from), NULL);
    g_return_val_if_fail(QOF_IS_BOOK(book), NULL);

    ENTER (" ");
    ret = g_object_new (GNC_TYPE_ACCOUNT, NULL);
    g_return_val_if_fail (ret, NULL);

    from_priv = GET_PRIVATE(from);
    priv = GET_PRIVATE(ret);
    xaccInitAccount (ret, book);

    /* Do not Begin/CommitEdit() here; give the caller 
     * a chance to fix things up, and let them do it.
     * Also let caller issue the generate_event (EVENT_CREATE) */
    priv->type = from_priv->type;

    priv->accountName = CACHE_INSERT(from_priv->accountName);
    priv->accountCode = CACHE_INSERT(from_priv->accountCode);
    priv->description = CACHE_INSERT(from_priv->description);

    kvp_frame_delete(ret->inst.kvp_data);
    ret->inst.kvp_data = kvp_frame_copy(from->inst.kvp_data);

    /* The new book should contain a commodity that matches
     * the one in the old book. Find it, use it. */
    priv->commodity = gnc_commodity_obtain_twin(from_priv->commodity, book);
    gnc_commodity_increment_usage_count(priv->commodity);

    priv->commodity_scu = from_priv->commodity_scu;
    priv->non_standard_scu = from_priv->non_standard_scu;

    LEAVE (" ");
    return ret;
}

Account *
xaccCloneAccount (const Account *from, QofBook *book)
{
    Account *ret = xaccCloneAccountCommon(from, book);
    qof_instance_gemini (&ret->inst, (QofInstance *) &from->inst);
    g_assert (ret ==
              (Account*) qof_instance_lookup_twin (QOF_INSTANCE(from), book));
    return ret;
}

Account *
xaccCloneAccountSimple (const Account *from, QofBook *book)
{
    Account *ret = xaccCloneAccountCommon(from, book);    
    qof_instance_set_dirty(&ret->inst);
    return ret;
}

/********************************************************************\
\********************************************************************/

static void
xaccFreeOneChildAccount (Account *acc, gpointer dummy)
{
    /* FIXME: this code is kind of hacky.  actually, all this code
     * seems to assume that the account edit levels are all 1. */
    if (qof_instance_get_editlevel(acc) == 0)
      xaccAccountBeginEdit(acc);
    xaccAccountDestroy(acc);
}

static void
xaccFreeAccountChildren (Account *acc)
{
  AccountPrivate *priv;
  GList *children;

  /* Copy the list since it will be modified */
  priv = GET_PRIVATE(acc);
  children = g_list_copy(priv->children);
  g_list_foreach(children, (GFunc)xaccFreeOneChildAccount, NULL);
  g_list_free(children);

  /* The foreach should have removed all the children already. */
  if (priv->children)
    g_list_free(priv->children);
  priv->children = NULL;
}

/* The xaccFreeAccount() routine releases memory associated with the
 * account.  It should never be called directly from user code;
 * instead, the xaccAccountDestroy() routine should be used (because
 * xaccAccountDestroy() has the correct commit semantics). */
static void
xaccFreeAccount (Account *acc)
{
  AccountPrivate *priv;
  GList *lp;

  g_return_if_fail(GNC_IS_ACCOUNT(acc));

  priv = GET_PRIVATE(acc);
  qof_event_gen (&acc->inst, QOF_EVENT_DESTROY, NULL);

  if (priv->children) 
  {
    PERR (" instead of calling xaccFreeAccount(), please call \n"
          " xaccAccountBeginEdit(); xaccAccountDestroy(); \n");

    /* First, recursively free children */
    xaccFreeAccountChildren(acc);
  }

  /* remove lots -- although these should be gone by now. */
  if (priv->lots)
  {
    PERR (" instead of calling xaccFreeAccount(), please call \n"
          " xaccAccountBeginEdit(); xaccAccountDestroy(); \n");
  
    for (lp=priv->lots; lp; lp=lp->next)
    {
      GNCLot *lot = lp->data;
      gnc_lot_destroy (lot);
    }
    g_list_free (priv->lots);
    priv->lots = NULL;
  }

  /* Next, clean up the splits */
  /* NB there shouldn't be any splits by now ... they should 
   * have been all been freed by CommitEdit().  We can remove this
   * check once we know the warning isn't occurring any more. */
  if (priv->splits) 
  {
    GList *slist;
    PERR (" instead of calling xaccFreeAccount(), please call \n"
          " xaccAccountBeginEdit(); xaccAccountDestroy(); \n");
  
    qof_instance_reset_editlevel(acc);

    slist = g_list_copy(priv->splits);
    for (lp = slist; lp; lp = lp->next) {
      Split *s = (Split *) lp->data;
      g_assert(xaccSplitGetAccount(s) == acc);
      xaccSplitDestroy (s);
    }
    g_list_free(slist);
    g_assert(priv->splits == NULL);
  }

  CACHE_REPLACE(priv->accountName, NULL);
  CACHE_REPLACE(priv->accountCode, NULL);
  CACHE_REPLACE(priv->description, NULL);

  /* zero out values, just in case stray 
   * pointers are pointing here. */

  priv->parent = NULL;
  priv->children = NULL;

  priv->balance  = gnc_numeric_zero();
  priv->cleared_balance = gnc_numeric_zero();
  priv->reconciled_balance = gnc_numeric_zero();

  priv->type = ACCT_TYPE_NONE;
  gnc_commodity_decrement_usage_count(priv->commodity);
  priv->commodity = NULL;

  priv->balance_dirty = FALSE;
  priv->sort_dirty = FALSE;

  /* qof_instance_release (&acc->inst); */
  g_object_unref(acc);
}

/********************************************************************\
 * transactional routines
\********************************************************************/

void 
xaccAccountBeginEdit (Account *acc) 
{
        g_return_if_fail(acc);
        qof_begin_edit(&acc->inst);
}

static void on_done(QofInstance *inst) 
{
    /* old event style */
    qof_event_gen (inst, QOF_EVENT_MODIFY, NULL);
}

static void on_err (QofInstance *inst, QofBackendError errcode)
{
  PERR("commit error: %d", errcode);
}

static void acc_free (QofInstance *inst)
{
  AccountPrivate *priv;
  Account *acc = (Account *) inst;

  priv = GET_PRIVATE(acc);
  if (priv->parent)
    gnc_account_remove_child(priv->parent, acc);
  xaccFreeAccount(acc);
}

static void
destroy_pending_splits_for_account(QofInstance *ent, gpointer acc)
{
    Transaction *trans = (Transaction *) ent;
    Split *split;

    if (xaccTransIsOpen(trans))
        while ((split = xaccTransFindSplitByAccount(trans, acc)))
            xaccSplitDestroy(split);
}

void 
xaccAccountCommitEdit (Account *acc) 
{
  AccountPrivate *priv;
  QofBook *book;

  g_return_if_fail(acc);
  if (!qof_commit_edit(&acc->inst)) return;

  /* If marked for deletion, get rid of subaccounts first,
   * and then the splits ... */
  priv = GET_PRIVATE(acc);
  if (qof_instance_get_destroying(acc))
  {
    GList *lp, *slist;
    QofCollection *col;
 
    qof_instance_increase_editlevel(acc);

    /* First, recursively free children */
    xaccFreeAccountChildren(acc);

    PINFO ("freeing splits for account %p (%s)",
           acc, priv->accountName ? priv->accountName : "(null)");

    slist = g_list_copy(priv->splits);
    for (lp = slist; lp; lp = lp->next)
    {
      Split *s = lp->data;
      xaccSplitDestroy (s);
    }
    g_list_free(slist); 
    /* It turns out there's a case where this assertion does not hold:
       When the user tries to delete an Imbalance account, while also
       deleting all the splits in it.  The splits will just get
       recreated and put right back into the same account!

       g_assert(priv->splits == NULL || qof_book_shutting_down(acc->inst.book));
    */

    book = qof_instance_get_book(acc);
    if (!qof_book_shutting_down(book)) {
      col = qof_book_get_collection(book, GNC_ID_TRANS);
      qof_collection_foreach(col, destroy_pending_splits_for_account, acc);
    }

    /* the lots should be empty by now */
    for (lp = priv->lots; lp; lp = lp->next)
    {
      GNCLot *lot = lp->data;
      gnc_lot_destroy (lot);
    }
    g_list_free(priv->lots);
    priv->lots = NULL;

    qof_instance_set_dirty(&acc->inst);
    qof_instance_decrease_editlevel(acc);
  }
  else 
  {
    xaccAccountBringUpToDate(acc);
  }

  qof_commit_edit_part2(&acc->inst, on_err, on_done, acc_free);
}

void 
xaccAccountDestroy (Account *acc) 
{
  g_return_if_fail(GNC_IS_ACCOUNT(acc));

  qof_instance_set_destroying(acc, TRUE);

  xaccAccountCommitEdit (acc);
}

/********************************************************************\
\********************************************************************/

static gboolean
xaccAcctChildrenEqual(const GList *na,
                      const GList *nb,
                      gboolean check_guids)
{
  if ((!na && nb) || (na && !nb))
  {
    PWARN ("only one has accounts");
    return(FALSE);
  }

  while (na && nb)
  {
    Account *aa = na->data;
    Account *ab = nb->data;

    if (!xaccAccountEqual(aa, ab, check_guids))
    {
      char sa[GUID_ENCODING_LENGTH + 1];
      char sb[GUID_ENCODING_LENGTH + 1];

      guid_to_string_buff (xaccAccountGetGUID (aa), sa);
      guid_to_string_buff (xaccAccountGetGUID (ab), sb);

      PWARN ("accounts %s and %s differ", sa, sb);

      return(FALSE);
    }

    na = na->next;
    nb = nb->next;
  }

  if (na || nb)
  {
    PWARN ("different numbers of accounts");
    return(FALSE);
  }

  return(TRUE);
}

gboolean
xaccAccountEqual(const Account *aa, const Account *ab, gboolean check_guids)
{
  AccountPrivate *priv_aa, *priv_ab;

  if(!aa && !ab) return TRUE;

  g_return_val_if_fail(GNC_IS_ACCOUNT(aa), FALSE);
  g_return_val_if_fail(GNC_IS_ACCOUNT(ab), FALSE);

  priv_aa = GET_PRIVATE(aa);
  priv_ab = GET_PRIVATE(ab);
  if (priv_aa->type != priv_ab->type)
  {
    PWARN ("types differ: %d vs %d", priv_aa->type, priv_ab->type);
    return FALSE;
  }

  if (safe_strcmp(priv_aa->accountName, priv_ab->accountName) != 0)
  {
    PWARN ("names differ: %s vs %s", priv_aa->accountName, priv_ab->accountName);
    return FALSE;
  }

  if (safe_strcmp(priv_aa->accountCode, priv_ab->accountCode) != 0)
  {
    PWARN ("codes differ: %s vs %s", priv_aa->accountCode, priv_ab->accountCode);
    return FALSE;
  }

  if (safe_strcmp(priv_aa->description, priv_ab->description) != 0)
  {
    PWARN ("descriptions differ: %s vs %s", priv_aa->description, priv_ab->description);
    return FALSE;
  }

  if (!gnc_commodity_equal(priv_aa->commodity, priv_ab->commodity))
  {
    PWARN ("commodities differ");
    return FALSE;
  }

  if(check_guids) {
    if(qof_instance_guid_compare(aa, ab) != 0)
    {
      PWARN ("GUIDs differ");
      return FALSE;
    }
  }

  if (kvp_frame_compare(aa->inst.kvp_data, ab->inst.kvp_data) != 0)
  {
    char *frame_a;
    char *frame_b;

    frame_a = kvp_frame_to_string (aa->inst.kvp_data);
    frame_b = kvp_frame_to_string (ab->inst.kvp_data);