From 1104f989b6affe5d5c31de77c6731e2bf32219e3 Mon Sep 17 00:00:00 2001 From: Dave Peticolas Date: Thu, 24 Aug 2000 04:34:03 +0000 Subject: [PATCH] More work on the architecture docs. git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@2700 57a11ea4-9604-0410-9ed3-97b8803252fd --- src/doc/design/engine.texinfo | 131 ++++++++++++++++++++++++++ src/doc/design/gnucash-design.texinfo | 10 ++ src/doc/design/top-level.texinfo | 3 +- 3 files changed, 142 insertions(+), 2 deletions(-) diff --git a/src/doc/design/engine.texinfo b/src/doc/design/engine.texinfo index 1efa0b762f..d47e392e25 100644 --- a/src/doc/design/engine.texinfo +++ b/src/doc/design/engine.texinfo @@ -1,2 +1,133 @@ @node Engine, Register, Top Level, Top @chapter Engine + +The Enging 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 releated accounts) and Sessions. A Session abstracts +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 +* Globally Unique Identifiers:: +* Key-Value Pair Frames:: +* Sessions:: +* Account Group:: +* Account:: +* Transaction:: +* Split:: +@end menu + + +@node Globally Unique Identifiers, Key-Value Pair Frames, Engine, Engine +@section Globally Unique Identifiers +@tindex GUID + + +@node Key-Value Pair Frames, Sessions, Globally Unique Identifiers, Engine +@section Key-Value Pair Frames +@tindex kvp_frame +@tindex kvp_value +@tindex kvp_value_t +@tindex kvp_list + +The number and types of data items which are associated with the +financial abstractions (Accounts, Transactions, and Splits) can vary +widely. For example, an Account which represents a user's checking +account might need to store the bank name, a telephone number, and a +username for online banking purposes. Another Account representing the +user's ownership of a stock might need to store information about +retrieving price quotes online such as the ticker symbol and the +exchange. + +The GnuCash accounting entities use Key-Value Pair Frames (hereafter +referred to as the datatype @code{kvp_frame}). A @code{kvp_frame} is +a set of associations between character strings (keys) and +@code{kvp_value} structures. A @code{kvp_value} is a union with +possible types enumerated in the @code{kvp_value_t} enum which +indicates the type of data stored in a @code{kvp_value} object. +Possible @code{kvp_value_t} values and their meanings are: + +@table @code + +@item KVP_TYPE_NONE +Indicates the abscence of a value in a kvp_frame. + +@item KVP_TYPE_INT64 +A @code{gint64} value. + +@item KVP_TYPE_FLOAT64 +A @code{double} value. + +@item KVP_TYPE_STRING +A @code{char *} value of arbitrary length. + +@item KVP_TYPE_GUID +A @code{GUID} value. @xref{Globally Unique Identifiers}. + +@item KVP_TYPE_BINARY +Arbitrary binary data. + +@item KVP_TYPE_LIST +A @code{kvp_list} item which contains a list of @code{kvp_value} items. + +@item KVP_TYPE_FRAME +A @code{kvp_frame} object. Thus, frames may contain other frames in a +recursive manner. + +@end table + + +@node Sessions, Account Group, Key-Value Pair Frames, Engine +@section Sessions +@tindex Session + +The @dfn{Session} interface provides wrappers for initiating/concluding +a file-editing session. This class provides several important services: + +@itemize + +@item +Prevents multiple users from editing the same file at the same time, +thus avoiding lost data due to race conditions. Thus an open session +implies that the associated file is locked. + +@item +Provides a search path for the file to be edited. This should simplify +install & maintenance problems for naive users who may not have a good +grasp on what a file ssytem is, or where they want to keep their data +files. + +@end itemize + +The current implementation assumes the use of files and file locks; +however, the API was designed to be general enough to allow the use +of generic URL's, and/or implementation on top of SQL or other +database/persistant object technology. + + +@node Account Groups, Account, Sessions, Engine +@section Account Groups +@tindex AccountGroup + + +@node Accounts, Transaction, Account Group, Engine +@section Accounts +@tindex Account + + +@node Transactions, Split, Account, Engine +@section Transactions +@tindex Transaction + + +@node Splits, , Transaction, Engine +@section Splits +@tindex Split diff --git a/src/doc/design/gnucash-design.texinfo b/src/doc/design/gnucash-design.texinfo index ddf2dd37ed..a4bbe51d28 100644 --- a/src/doc/design/gnucash-design.texinfo +++ b/src/doc/design/gnucash-design.texinfo @@ -93,6 +93,16 @@ of the @cite{GnuCash Design Document}, version @value{VERSION}. @detailmenu --- The Detailed Node Listing --- +Engine + +* Globally Unique Identifiers:: +* Key-Value Pair Frames:: +* Sessions:: +* Account Group:: +* Account:: +* Transaction:: +* Split:: + Register * Cells:: diff --git a/src/doc/design/top-level.texinfo b/src/doc/design/top-level.texinfo index 1d1a54bc76..b075de3b50 100644 --- a/src/doc/design/top-level.texinfo +++ b/src/doc/design/top-level.texinfo @@ -12,8 +12,7 @@ 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, and is essentially -OS-neutral. +The Engine code contains no GUI code whatsoever. @subsection Query