This is gnucash-design.info, produced by makeinfo version 4.1 from
gnucash-design.texinfo.


INFO-DIR-SECTION Programming

START-INFO-DIR-ENTRY
* gnucash: (gnucash-design).       Design of the GnuCash program
END-INFO-DIR-ENTRY


   This file documents the design of the GnuCash program.

   Copyright 2000 Gnumatic Incorporated

   This is Edition 1.8.11, last updated 13 August 2001, of the `GnuCash
Design Document', version 1.8.11.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts
being LIST, and with the Back-Cover Texts being LIST.  A copy of the
license is included in the section entitled "GNU Free Documentation
License".


File: gnucash-design.info,  Node: Top,  Next: GNU Free Documentation License,  Prev: (dir),  Up: (dir)

GnuCash Design Document
***********************

   This is Edition 1.8.11, last updated 13 August 2001, of the `GnuCash
Design Document', version 1.8.11.

* Menu:

* GNU Free Documentation License::
* Introduction::
* Top Level::
* Engine::
* Component Manager::
* Register::
* Reports::
* User Preferences::
* Function Index::
* Data Type Index::
* Concept Index::


 --- The Detailed Node Listing ---

Engine

* Engine Introduction::
* Using and Extending the Engine API::
* Globally Unique Identifiers::
* Numeric Library::
* Key-Value Pair Frames::
* Events::
* Commodities::
* Commodity Tables::
* Prices::
* Price Databases::
* Splits::
* Transactions::
* Accounts::
* Account Groups::
* GNCBooks::
* Scrub::

Globally Unique Identifiers

* When to use GUIDs::
* GUID Types::
* How to use GUIDs::
* GUIDs and GnuCash Entities::
* The GUID Generator::

Numeric Library

* Standard Numeric Arguments::
* Creating Numeric Objects::
* Basic Arithmetic Operations::
* Numeric Comparisons and Predicates::
* Numeric Denominator Conversion::
* Numeric Floating Point Conversion::
* Numeric String Conversion::
* Numeric Error Handling ::
* Numeric Example::

Key-Value Pair Frames

* Key-Value Policy::
* kvp_frame::
* kvp_value::
* kvp_list::

Events

* Event API::

Commodities

* General Commodity API::
* Commodity Getters::
* Commodity Setters::

Commodity Tables

* General Commodity Table API::
* Commodity Table Access API::
* Commodity Table Modification API::

Prices

* Price Implementation Details::
* General Price API::
* Price Getters::
* Price Setters::

Price Databases

* Price Lists::
* General Price Database API::

Splits

* General Split API::
* Split Getters::
* Split Setters::

Transactions

* General Transaction API::
* Transaction Getters::
* Transaction Setters::

Accounts

* Account Types::
* General Account API::
* Account Type API::
* Account Getters::

Account Groups

* General Account Group API::
* Account Group Account API::

GNCBooks

* GNCBook API::

Component Manager

* Component Manager Introduction::

Register

* Cells::
* Cellblocks::
* Table::
* Split Register::

Cells

* BasicCell::

Reports

* Creating a Report::

User Preferences

* Option Databases::
* Option Types::
* Option Creation::
* Option Values::


File: gnucash-design.info,  Node: GNU Free Documentation License,  Next: Introduction,  Prev: Top,  Up: Top

GNU Free Documentation License
******************************

                        Version 1.1, March 2000
     Copyright (C) 2000  Free Software Foundation, Inc.
         59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

Preamble
========

   The purpose of this License is to make a manual, textbook, or other
written document "free" in the sense of freedom: to assure everyone the
effective freedom to copy and redistribute it, with or without
modifying it, either commercially or noncommercially.  Secondarily,
this License preserves for the author and publisher a way to get credit
for their work, while not being considered responsible for
modifications made by others.

   This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.  It
complements the GNU General Public License, which is a copyleft license
designed for free software.

   We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does.  But this License is not limited to software manuals; it
can be used for any textual work, regardless of subject matter or
whether it is published as a printed book.  We recommend this License
principally for works whose purpose is instruction or reference.

APPLICABILITY AND DEFINITIONS
=============================

   This License applies to any manual or other work that contains a
notice placed by the copyright holder saying it can be distributed
under the terms of this License.  The "Document", below, refers to any
such manual or work.  Any member of the public is a licensee, and is
addressed as "you".

   A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.

   A "Secondary Section" is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject.  (For example, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.)  The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding them.

   The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.

   The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.

   A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the general
public, whose contents can be viewed and edited directly and
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input to
text formatters.  A copy made in an otherwise Transparent file format
whose markup has been designed to thwart or discourage subsequent
modification by readers is not Transparent.  A copy that is not
"Transparent" is called "Opaque".

   Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML or
XML using a publicly available DTD, and standard-conforming simple HTML
designed for human modification.  Opaque formats include PostScript,
PDF, proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the machine-generated
HTML produced by some word processors for output purposes only.

   The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page.  For works in
formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.

VERBATIM COPYING
================

   You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License.  You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute.  However, you may accept
compensation in exchange for copies.  If you distribute a large enough
number of copies you must also follow the conditions in section 3.

   You may also lend copies, under the same conditions stated above, and
you may publicly display copies.

COPYING IN QUANTITY
===================

   If you publish printed copies of the Document numbering more than
100, and the Document's license notice requires Cover Texts, you must
enclose the copies in covers that carry, clearly and legibly, all these
Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts
on the back cover.  Both covers must also clearly and legibly identify
you as the publisher of these copies.  The front cover must present the
full title with all words of the title equally prominent and visible.
You may add other material on the covers in addition.  Copying with
changes limited to the covers, as long as they preserve the title of
the Document and satisfy these conditions, can be treated as verbatim
copying in other respects.

   If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.

   If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a publicly-accessible computer-network location containing a complete
Transparent copy of the Document, free of added material, which the
general network-using public has access to download anonymously at no
charge using public-standard network protocols.  If you use the latter
option, you must take reasonably prudent steps, when you begin
distribution of Opaque copies in quantity, to ensure that this
Transparent copy will remain thus accessible at the stated location
until at least one year after the last time you distribute an Opaque
copy (directly or through your agents or retailers) of that edition to
the public.

   It is requested, but not required, that you contact the authors of
the Document well before redistributing any large number of copies, to
give them a chance to provide you with an updated version of the
Document.

MODIFICATIONS
=============

   You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release the
Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy of
it.  In addition, you must do these things in the Modified Version:

  A. Use in the Title Page (and on the covers, if any) a title distinct
     from that of the Document, and from those of previous versions
     (which should, if there were any, be listed in the History section
     of the Document).  You may use the same title as a previous version
     if the original publisher of that version gives permission.

  B.  List on the Title Page, as authors, one or more persons or
     entities responsible for authorship of the modifications in the
     Modified Version, together with at least five of the principal
     authors of the Document (all of its principal authors, if it has
     less than five).

  C. State on the Title page the name of the publisher of the Modified
     Version, as the publisher.

  D.  Preserve all the copyright notices of the Document.

  E. Add an appropriate copyright notice for your modifications
     adjacent to the other copyright notices.

  F. Include, immediately after the copyright notices, a license notice
     giving the public permission to use the Modified Version under the
     terms of this License, in the form shown in the Addendum below.

  G. Preserve in that license notice the full lists of Invariant
     Sections and required Cover Texts given in the Document's license
     notice.

  H. Include an unaltered copy of this License.

  I. Preserve the section entitled "History", and its title, and add to
     it an item stating at least the title, year, new authors, and
     publisher of the Modified Version as given on the Title Page.  If
     there is no section entitled "History" in the Document, create one
     stating the title, year, authors, and publisher of the Document as
     given on its Title Page, then add an item describing the Modified
     Version as stated in the previous sentence.

  J. Preserve the network location, if any, given in the Document for
     public access to a Transparent copy of the Document, and likewise
     the network locations given in the Document for previous versions
     it was based on.  These may be placed in the "History" section.
     You may omit a network location for a work that was published at
     least four years before the Document itself, or if the original
     publisher of the version it refers to gives permission.

  K. In any section entitled "Acknowledgements" or "Dedications",
     preserve the section's title, and preserve in the section all the
     substance and tone of each of the contributor acknowledgements
     and/or dedications given therein.

  L. Preserve all the Invariant Sections of the Document, unaltered in
     their text and in their titles.  Section numbers or the equivalent
     are not considered part of the section titles.

  M. Delete any section entitled "Endorsements".  Such a section may
     not be included in the Modified Version.

  N. Do not retitle any existing section as "Endorsements" or to
     conflict in title with any Invariant Section.

   If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant.  To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.

   You may add a section entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties-for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.

   You may add a passage of up to five words as a Front-Cover Text, and
a passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version.  Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or through
arrangements made by) any one entity.  If the Document already includes
a cover text for the same cover, previously added by you or by
arrangement made by the same entity you are acting on behalf of, you
may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.

   The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.

COMBINING DOCUMENTS
===================

   You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice.

   The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy.  If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of Invariant
Sections in the license notice of the combined work.

   In the combination, you must combine any sections entitled "History"
in the various original documents, forming one section entitled
"History"; likewise combine any sections entitled "Acknowledgements",
and any sections entitled "Dedications".  You must delete all sections
entitled "Endorsements."

COLLECTIONS OF DOCUMENTS
========================

   You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy that
is included in the collection, provided that you follow the rules of
this License for verbatim copying of each of the documents in all other
respects.

   You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert a
copy of this License into the extracted document, and follow this
License in all other respects regarding verbatim copying of that
document.

AGGREGATION WITH INDEPENDENT WORKS
==================================

   A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, does not as a whole count as a Modified Version of
the Document, provided no compilation copyright is claimed for the
compilation.  Such a compilation is called an "aggregate", and this
License does not apply to the other self-contained works thus compiled
with the Document, on account of their being thus compiled, if they are
not themselves derivative works of the Document.

   If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one quarter
of the entire aggregate, the Document's Cover Texts may be placed on
covers that surround only the Document within the aggregate.  Otherwise
they must appear on covers around the whole aggregate.

TRANSLATION
===========

   Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections.  You may include a
translation of this License provided that you also include the original
English version of this License.  In case of a disagreement between the
translation and the original English version of this License, the
original English version will prevail.

TERMINATION
===========

   You may not copy, modify, sublicense, or distribute the Document
except as expressly provided for under this License.  Any other attempt
to copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License.  However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such parties
remain in full compliance.

FUTURE REVISIONS OF THIS LICENSE
================================

   The Free Software Foundation may publish new, revised versions of
the GNU Free Documentation License from time to time.  Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.  See
http://www.gnu.org/copyleft/.

   Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation.  If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents
====================================================

   To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

     Copyright (c)  YEAR  YOUR NAME.
     Permission is granted to copy, distribute and/or modify this document
     under the terms of the GNU Free Documentation License, Version 1.1
     or any later version published by the Free Software Foundation;
     with the Invariant Sections being LIST THEIR TITLES, with the
     Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
     A copy of the license is included in the section entitled "GNU
     Free Documentation License".

   If you have no Invariant Sections, write "with no Invariant Sections"
instead of saying which ones are invariant.  If you have no Front-Cover
Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
LIST"; likewise for Back-Cover Texts.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.


File: gnucash-design.info,  Node: Introduction,  Next: Top Level,  Prev: GNU Free Documentation License,  Up: Top

Introduction
************

   This document defines the design and architecture of the GnuCash
program, an application for tracking finances. GnuCash is composed of
several subsystems or modules. This document describes each module,
specifying its interface and, where appropriate, its implementation, as
well as describing the interactions between each module.

Who Should Read This Document?
==============================

   Anyone who plans on making a significant change or addition to
GnuCash's functionality should read this document. By adhering to the
structure presented here, your contribution will be more likely to work
correctly with existing and future features.

Goals
=====

   GnuCash is intended to be a finance and accounting program for
individuals and small businesses. As such, it should have the following
primary features:

   * A sound underlying model for financial entities such as currencies,
     transactions, and accounts.

   * A user interface which provides an efficient way to accomplish
     common tasks, such as transaction entry, account reconciliation,
     etc.

   * The ability to generate and print standard financial reports such
     as Income Statements, Balance Sheets, etc.

   * The ability to generate and print graphs of financial information.


   A more comprehensive list of current and planned features for GnuCash
is located at `http://cvs.gnucash.org/linux/gnucash/projects.html'.


File: gnucash-design.info,  Node: Top Level,  Next: Engine,  Prev: Introduction,  Up: Top

Architectural Overview
**********************

   GnuCash is written primarily in two languages: C and Scheme. The
engine/server is written in C primarily for speed, portability,
stability and historical purposes. Much of the day-to-day workhorse code
is written in Scheme, primarily for its power, expressiveness and ease
of development.  The user interface is Gtk/Gnome, some of it written in
C, some in scheme, and some with the GUI designer tool Glade
`glade.pn.org'.

   GnuCash is modular, thereby allowing separate individuals to
maintain, develop and enhance certain modules without disturbing the
overall development. (Never mind that modules help avoid spaghetti code
and nasty, ugly hacks).  The interfaces between modules are documented,
and, for the most part, stable and unchanging.

   GnuCash currently consists of the following modules:

The Engine
==========

   The "Engine" (located under the `src/engine' directory in the
GnuCash codebase) provides an interface for creating, manipulating, and
destroying three basic financial entities: Accounts, Transactions (known
as Journal Entries in accounting practice), and Splits (known as Ledger
Entries). These three entities are the central data structures of the
GnuCash financial data model.

   The Engine code contains no GUI code whatsoever.

Query
-----

   The "Query" module (`src/engine/Query.*') provides an interface into
the engine for finding transactions based on a set of criteria, such as
description, date posted, account membership, etc. Simple queries can
be combined using standard boolean operators.

File I/O
--------

   The "File I/O" module (`src/engine/FileIO.*') provides an interface
for reading and writing a set of Accounts, Transactions, and Splits to
a binary file. This module is deprecated.

XML I/O
-------

   The "XML I/O" module (`src/engine/*xml*.*' and
`src/engine/*sixtp*.*') provides an interface for reading and writing
the engine information to an XML format.

Backend
-------

   The "Backend" module (`src/engine/Backend*.*') provides hooks to
allow different modules to be used for storing and retrieving Engine
data. There are two backends currently under development, a Postgresql
backend (`src/engine/sql/*') and an RPC backend (`src/engine/rpc/*').

The Register
============

   The "Register" (`src/register') implements a ledger-like GUI that
allows the user to dynamically enter dates, prices, memos descriptions,
etc. in an intuitive fashion that should be obvious to anyone who's
used a checkbook register. The code is highly configurable, allowing
the ledger columns and rows to be laid out in any way, with no
restrictions on the function, type, and number of columns/rows. For
example, one can define a ledger with three date fields, one price
field, and four memo fields in a straightforward fashion. Cell handling
objects support and automatically validate date entry, memo entry
(w/auto-completion), prices, combo-boxes (pull-down menus), and
multi-state check-boxes. Cells can be marked read-write, or
output-only. Cells can be assigned unique colors. The currently active
ledger row-block can be highlighted with a unique color.

   The register code is completely independent of the engine code, knows
nothing about accounting or any of the other GnuCash subsystems. It can
be used in independent projects that have nothing to do with accounting.

Reports
=======

   The "Reports" module (`src/scm/report.scm', `src/scm/reports') is a
scheme (guile) based system to create balance sheets, profit & loss
statements, etc. by using the engine API to fetch and display data
formatted in HTML.

   For the most part, this module uses the Query API to fetch the engine
information instead of using the raw engine interface. This design uses
Queries to extract the data and assemble it into a view-independent
format. This data is then be converted to HTML reports and/or graphs
such as bar and pie charts.

Graphs
======

   The "Graphs" module implements GUI graphs such as bar and pie
charts. These graphs can be interactive in that the user can, for
example, move pie wedges, and 'live' in that the user can click on graph
subsections to see a detail graph or report of that particular
subsection.

   This module is implemented using the GUPPI library being developed by
Jon Trowbridge (<http://www.gnome.org/guppi>).

Price Quotes
============

   The "Price Quotes" module (`src/quotes') is a Perl system to fetch
stock price data off the Internet and insert it into the GnuCash
Engine. This module requires the functionality of the Finance::Quote
module available at SourceForge. The Finance::Quote module can fetch
price quotes from many different sources including Yahoo, Yahoo Europe,
and some international exchanges.

   The Finance::Quote module also supports fetching currency exchange
rates. GnuCash will be extended to allow the fetching and use of
currency exchange rates.

User Preferences
================

   The "User Preferences" module (`src/scm/options.scm',
`src/scm/prefs.scm') provides an infrastructure for defining both
user-configurable and internal preferences. Preferences are defined in
scheme using several predefined preference types such as boolean,
string, date, etc. Preferences are 'implemented' by providing a GUI
which allows the user to see and change preference values. An API is
provided to query preference values and to register callbacks which
will be invoked when preferences change.

   Preference values which are different from the default values are
stored as scheme forms in a user-specific preferences file
(`~/.gnucash/config.auto'). This file is automatically loaded upon
startup.

QIF Import
==========

   The "QIF Import" module (`src/scm/qif-import') provides
functionality for importing QIF (Quicken Interchange Format) data into
GnuCash.

GnuCash
=======

   The GnuCash module (`src/gnome', `src/register/gnome' and
`src/*.[ch]') is the main GUI application. It consists of a collection
of miscellaneous GUI code to glue together all of the pieces above into
a coherent, point-and-click whole. It is meant to be easy to use and
intuitive to the novice user without sacrificing the power and
flexibility that a professional might expect. When people say that
GnuCash is trying to be a "Quicken or MS Money look/work/act-alike",
this is the piece that they are referring to. It really is meant to be
a personal-finance manager with enough power for the power user and the
ease of use for the beginner.

   Currently, the Gnome interface is the only operational interface.
There is an obsolete Motif interface which is not maintained and which
is removed in current CVS. There is also old Qt code (removed in current
CVS) which won't compile, and most/all functions are missing.


File: gnucash-design.info,  Node: Engine,  Next: Component Manager,  Prev: Top Level,  Up: Top

Engine
******

   The Engine provides an interface to a financial engine with three
basic financial entities: Accounts, Transactions (known as Journal
Entries in accounting practice), and Splits (known as Ledger Entries).
These three entities are the central data structures of the GnuCash
financial data model.

   In addition, the Engine provides the abstraction of Account Groups
(collections of related accounts) and GNCBooks. A GNCBook abstracts both
a set of related GnuCash data (financial entities plus additional
information such as budgets, per-file preferences, etc.) plus a
file-editing session allowing transparent support for locking and
implementation with other backends such as SQL.

   The Engine code contains no GUI code whatsoever and is designed to
be created as a shared library for use by other programs.

* Menu:

* Engine Introduction::
* Using and Extending the Engine API::
* Globally Unique Identifiers::
* Numeric Library::
* Key-Value Pair Frames::
* Events::
* Commodities::
* Commodity Tables::
* Prices::
* Price Databases::
* Splits::
* Transactions::
* Accounts::
* Account Groups::
* GNCBooks::
* Scrub::


File: gnucash-design.info,  Node: Engine Introduction,  Next: Using and Extending the Engine API,  Prev: Engine,  Up: Engine

Introduction
============

   Splits (*note Splits::), or "Ledger Entries" are the fundamental
accounting units. Each Split consists of a quantity (number of dollar
bills, number of shares, etc.), the value of that quantity expressed in
a (possibly) different currency than the quantity, a Memo, a pointer to
the parent Transaction, a pointer to the debited Account, a reconciled
flag and timestamp, an "Action" field, and a key-value frame which can
store arbitrary data (*note Key-Value Pair Frames::).

   Transactions (*note Transactions::) embody the notion of "double
entry" accounting. A Transaction consists of a date, a description, a
number, a list of one or more Splits, and a key-value frame. When
double-entry rules are enforced, the total value of the splits is zero.
Note that if there is just one split, its value must be zero for
double-entry accounting; this used to be used for storing prices, but
with the advent of the Price DB, this is no longer the case. If there
are two splits, then the value of one must be positive, the other
negative: this denotes that one account is debited, and another is
credited by an equal amount. Positive Split values are 'debits' and
negative Split values are 'credits'. Ensuring the Splits to 'add up' to
zero causes a double-entry accounting system to always balance.

   The engine does not enforce double-entry accounting, but provides an
API to enable user-code to find unbalanced transactions and 'repair'
them so that they are in balance. *Note Scrub::.

   Note the sum of the values of Splits in a Transaction is always
computed with respect to a currency; thus splits can be balanced even
when they are in different currencies, as long as they share a common
currency.  This feature allows currency-trading accounts to be
established.

   Every Split must point to its parent Transaction, and that
Transaction must in turn include that Split in the Transaction's list
of Splits. A Split can belong to at most one Transaction. These
relationships are enforced by the engine. The engine user cannnot
accidentally destroy this relationship as long as they stick to using
the API and never access internal structures directly.

   Splits are grouped into Accounts (*note Accounts::) which are also
known as "Ledgers" in accounting practice. Each Account consists of a
list of Splits that debit that Account. To ensure consistency, if a
Split points to an Account, then the Account must point to the Split,
and vice-versa.  A Split can belong to at most one Account. Besides
merely containing a list of Splits, the Account structure also give the
Account a name, a code number, description and notes fields, a
key-value frame, a pointer to the currency that is used for all splits
in this account, and a pointer to the "security" used for all splits in
this account. The "security" can be the name of a stock (e.g. "IBM",
"McDonald's"), or another currency (e.g. "USD", "GBP").  The security
is used during Transaction balancing to enable trading between accounts
denominated in different currencies, or to, for example, move stocks
from one Account to another.

   Accounts can be arranged in a hierarchical tree. The nodes of the
tree are called "Account Groups" (*note Account Groups::). By accounting
convention, the value of an Account is equal to the value of all of its
Splits plus the value of all of its sub-Accounts.


File: gnucash-design.info,  Node: Using and Extending the Engine API,  Next: Globally Unique Identifiers,  Prev: Engine Introduction,  Up: Engine

Using and Extending the Engine API
==================================

   Engine API calls are named using a specific convention. For example,
the function to access the Memo field of a Split is `xaccSplitGetMemo'.
The prefix `xacc' comes first(1), followed by the name of the entity
for which the API call applies (`Split'), followed by the action
performed by the call (`Get'), followed by the name of the field being
accessed (`Memo'). Future API calls should conform to this naming
convention.

   The formal arguments to Engine API calls always begin with the
entity to which the call applies. Thus, the arguments to
`xaccSplitSetMemo' are the `Split' pointer followed by the pointer to a
memo string. Future API calls should also conform to this convention.

   Engine API calls should be implemented to behave as gracefully as
possible with unexpected input. Specifically, public API calls should
gracefully handle `NULL' pointer arguments. User code should be able to
handle `NULL' return values from Engine calls as well.

   ---------- Footnotes ----------

   (1) The `xacc' prefix is a historical artifact. GnuCash was derived
from X-Accountant by Robin Clark.


File: gnucash-design.info,  Node: Globally Unique Identifiers,  Next: Numeric Library,  Prev: Using and Extending the Engine API,  Up: Engine

Globally Unique Identifiers
===========================

   It is common for Engine structures to reference other Engine
structures.  For example, an Account must reference its Splits, its
parent Account Group, and its child Account Group. Furthermore, other
GnuCash modules may need to reference Engine structures. For example, a
GUI implementation may wish to save a list of Accounts which the user
has open when the application exits in order to restore that same state
upon the next invocation.

   One way to uniquely identify an Engine structure, at least while the
program is running, is using the C pointer which points to the
structure. C pointers have the advantage of speed, but also have some
disadvantages:

   * Pointers cannot be used in data files and are not persistant across
     different program invocations.

   * When an entity is destroyed, every other structure which
     references that entity through a direct pointer must be
     immediately updated to prevent illegal accesses.


   The "GUID" (Globally Unique Identifier) provides a way to reference
Engine structures that is more flexible than C pointers. Each Engine
structure has an associated GUID which can be used to reference that
structure. Engine GUIDs have the following features:

   * The GUID is permanent, i.e., it persists between invocations of
     GnuCash.

   * The GUID is guaranteed to be unique with the set of all Splits,
     Transactions, and Accounts in the hierarchy of which the structure
     is a member.

   * With very high probability, the GUID is unique among all GUIDs
     created by any invocation of GnuCash, all over the world.

   * GUIDs can be efficiently encoded in a string representation.


* Menu:

* When to use GUIDs::
* GUID Types::
* How to use GUIDs::
* GUIDs and GnuCash Entities::
* The GUID Generator::


File: gnucash-design.info,  Node: When to use GUIDs,  Next: GUID Types,  Prev: Globally Unique Identifiers,  Up: Globally Unique Identifiers

When to use GUIDs
-----------------

   Although GUIDs are very flexible, the engine structures like Accounts
will probably continue to use C pointers for the forseeable future,
since they are much faster (and in certain respects more convenient)
than using GUIDs. In general, however, it is much safer to use GUIDs.
In particular, you should consider using GUIDs if any of the following
is true:

   * You need to save a reference to an engine structure in a file.

   * You need to save a reference to an engine structure that could be
     deleted in between accesses to the saved reference.



File: gnucash-design.info,  Node: GUID Types,  Next: How to use GUIDs,  Prev: When to use GUIDs,  Up: Globally Unique Identifiers

GUID Types
----------

   The GUIDs in GnuCash are typed using the enum `GNCIdType'.  Possible
values and their meanings for GUID types are:

`GNC_ID_NONE'
     The GUID does not currently refer to a GnuCash entity, though it
     could refer to one in the future.

`GNC_ID_NULL'
     The GUID does not, and never will, refer to a GnuCash entity.

`GNC_ID_ACCOUNT'
     The GUID refers to an Account (*note Accounts::).

`GNC_ID_TRANS'
     The GUID refers to a Transation (*note Transactions::).

`GNC_ID_SPLIT'
     The GUID refers to a Split (*note Splits::).

 - Function: GNCIdType xaccGUIDType (const GUID * GUID)
     Return the type associated with GUID.

 - Function: const GUID * xaccGUIDNull (void)
     Return a GUID which is guaranteed to always have type
     `GNC_ID_NULL'.


File: gnucash-design.info,  Node: How to use GUIDs,  Next: GUIDs and GnuCash Entities,  Prev: GUID Types,  Up: Globally Unique Identifiers

How to use GUIDs
----------------

   The Engine API functions which access the GUID for a specific entity
return a pointer to the GUID. *Note:* Do not store the pointer itself!
Instead, store a copy of the GUID. Storing the pointer itself would
present some of the same problems as using the account pointer
directly. Example:

     {
       GUID saved_guid;
       Account *account;
     
       account = < something to get an Account pointer >
     
       saved_guid = *xaccAccountGetGUID(account);
     
       ...
     
       account = xaccAccountLookup(&saved_guid);
     
       ...
     }

   You can compare two GUIDs with the following functions.

 - Function: gboolean guid_equal (const GUID * GUID_1, const GUID *
          GUID_2)
     Compare two guids and return TRUE if they are both non-NULL and
     equal.

 - Function: gint guid_compare (const GUID * G1, const GUID * G2)
     Return the `memcmp' of the two GUID's.

   You can encode and decode GUIDs and their string representations
using the next two functions.

 - Function: char * guid_to_string (const GUID * GUID)
     Return a null-terminated string encoding of GUID. String encodings
     of identifiers are hex numbers printed only with the characters `0'
     through `9' and `a' through `f'.  The encoding will always be
     `GUID_ENCODING_LENGTH' characters long. The returned string should
     be freed when no longer needed.

 - Function: char * guid_to_string_buff (const GUID * GUID, char * BUFF)
     This routine does the same work as `guid_to_string', except that
     the string is written into the memory pointed at by BUFF. The
     buffer must be at least GUID_ENCODING_LENGTH+1 characters long.
     This routine is handy for avoiding a malloc/free cycle.  It
     returns a pointer to the _end_ of what was written.  (i.e. it can
     be used like `stpcpy' during string concatenation)

 - Function: gboolean string_to_guid (const char * STRING, GUID * GUID)
     Given a string, decode an id into GUID if GUID is non-NULL. The
     function returns TRUE if the string was a valid 32 character
     hexadecimal number. This function accepts both upper and lower
     case hex digits. If the return value is FALSE, the effect on GUID
     is undefined.

   You can allocate and deallocate space for GUIDs using standard
memory routines. However, if your code is allocating and deallocating
lots of GUID objects, then the next two functions should be used.

 - Function: GUID * xaccGUIDMalloc (void)
     Return newly allocated memory for a GUID object. The memory must
     be freed with `xaccGUIDFree'. In general, this function is faster
     than using the standard libc allocators.

 - Function: void xaccGUIDFree (GUID * GUID)
     Free the space for a GUID that was allocated with `xaccGUIDMalloc'.

   You can use the following two functions to aid in using GUIDS in hash
tables.

 - Function: guint guid_hash_to_guint (gconstpointer PTR)
     Return a hash value suitable for use with a `GHashTable'.  PTR
     must point to a GUID.

 - Function: GHashTable * guid_hash_table_new (void)
     Return a new `GHashTable' which uses GUIDs as keys.


File: gnucash-design.info,  Node: GUIDs and GnuCash Entities,  Next: The GUID Generator,  Prev: How to use GUIDs,  Up: Globally Unique Identifiers

GUIDs and GnuCash Entities
--------------------------

   This section documents a low-level API for associating entities with
GUIDs. User code and general engine code should not use this API;
instead use the API documented in the sections for the specific GnuCash
entities such as Accounts and Transactions.

 - Function: void xaccGUIDNew (GUID * GUID)
     Generate a new guid. This function is guaranteed to return a guid
     that is unique within the scope of all GnuCash entities being
     managed by the the current invocation of GnuCash. GnuCash routines
     should always use this function and not `guid_new'!

 - Function: void * xaccLookupEntity (const GUID * GUID, GNCIdType
          ENTITY_TYPE)
     Lookup an entity given an id and a type. If there is no entity
     associated with the id, or if it has a different type, NULL is
     returned.

 - Function: void xaccStoreEntity (void * ENTITY, const GUID * GUID,
          GNCIdType entity_type)
     Store the given entity under the given id with the given type.

 - Function: void xaccRemoveEntity (const GUID * GUID)
     Remove any existing association between an entity and the given
     id. The entity is not changed in any way.


File: gnucash-design.info,  Node: The GUID Generator,  Prev: GUIDs and GnuCash Entities,  Up: Globally Unique Identifiers

The GUID Generator
------------------

   GUIDs are created by the GUID generator. The API for this generator
is low-level and should not be used by user-code.

 - Function: void guid_init (void)
     Initialize the GUID generator with a variety of random sources
     including common system files and /dev/random.

 - Function: void guid_init_with_salt (const void * SALT, size_t
          SALT_LEN)
     Initialize the GUID generator with guid_init() and with the given
     sequence of arbitrary binary data.

 - Function: void guid_init_only_salt (const void * SALT, size_t
          SALT_LEN)
     Initialize the GUID generator using only the given sequence of
     arbitrary binary data. This provides a way to reliably obtain a
     given sequence of GUIDs.

 - Function: void guid_new (GUID * GUID)
     Create a new GUID and store it in GUID. This is a low-level
     function!  GnuCash code should use `xaccGUIDNew'.


File: gnucash-design.info,  Node: Numeric Library,  Next: Key-Value Pair Frames,  Prev: Globally Unique Identifiers,  Up: Engine

Numeric Library
===============

   Financial quantities in GnuCash (Split quantities and values) are
stored as exact quantities measured in the smallest denominational unit
of the appropriate currency. For example, 100.50 US Dollars would be
stored as (10050 / 100) US Dollars. GnuCash uses the `gnc_numeric'
datatype to store financial quantities.

   The `gnc_numeric' API provides data types and functions for
manipulating exact numeric quantities. While the `gnc_numeric' library
was developed to represent and operate on exact financial quantities in
GnuCash, the library is also (hopefully) suitable for use in any
application where exact numeric representation for rational numbers is
needed.

   A `gnc_numeric' value represents a number in rational form, with a
64-bit `long long' integer as numerator and denominator. If more
precision, a higher-precision representation of irrational numbers, or a
wider dynamic range is needed, a floating point format may be
appropriate. There are reasonable rational approximations to common
irrational constants (*note Numeric Example::), but the transcendental
functions have not been implemented for `gnc_numeric' objects.

* Menu:

* Standard Numeric Arguments::
* Creating Numeric Objects::
* Basic Arithmetic Operations::
* Numeric Comparisons and Predicates::
* Numeric Denominator Conversion::
* Numeric Floating Point Conversion::
* Numeric String Conversion::
* Numeric Error Handling ::
* Numeric Example::

