mirror of
https://github.com/Gnucash/gnucash.git
synced 2024-11-22 08:57:17 -06:00
More work on architecture docs.
git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@2756 57a11ea4-9604-0410-9ed3-97b8803252fd
This commit is contained in:
Dave Peticolas
parent
dfedfd76ab
commit
441938d811
@ -95,8 +95,69 @@ Splits plus the value of all of its sub-Accounts.
|
||||
|
||||
@node Globally Unique Identifiers, Key-Value Pair Frames, Engine Introduction, Engine
|
||||
@section Globally Unique Identifiers
|
||||
@cindex Globally Unique Identifier
|
||||
@tindex GUID
|
||||
|
||||
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:
|
||||
|
||||
@itemize
|
||||
|
||||
@item
|
||||
Pointers cannot be used in data files and are not persistant across
|
||||
different program invocations.
|
||||
|
||||
@item
|
||||
When an entity is destroyed, every other structure which references that
|
||||
entity through a direct pointer must be immediately updated to prevent
|
||||
illegal accesses.
|
||||
|
||||
@end itemize
|
||||
|
||||
The @dfn{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:
|
||||
|
||||
@itemize
|
||||
|
||||
@item
|
||||
The GUID is permanent, i.e., it persists between invocations of GnuCash.
|
||||
|
||||
@item
|
||||
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.
|
||||
|
||||
@item
|
||||
With very high probability, the GUID is unique among all GUIDs
|
||||
created by any invocation of GnuCash, all over the world.
|
||||
|
||||
@item
|
||||
GUIDs can be efficiently encoded in a string representation.
|
||||
|
||||
@end itemize
|
||||
|
||||
|
||||
@menu
|
||||
* When to use GUIDs::
|
||||
@end menu
|
||||
|
||||
@node When to use GUIDs, , Globally Unique Identifiers, Globally Unique Identifiers
|
||||
@subsection When to use GUIDs
|
||||
@cindex When to use GUIDs
|
||||
|
||||
|
||||
|
||||
@node Key-Value Pair Frames, Splits, Globally Unique Identifiers, Engine
|
||||
@section Key-Value Pair Frames
|
||||
@ -120,14 +181,64 @@ between character strings (keys) and @code{kvp_value} structures. A
|
||||
@code{kvp_value} object.
|
||||
|
||||
@menu
|
||||
* Key-Value Policy::
|
||||
* kvp_frame::
|
||||
* kvp_value::
|
||||
* kvp_list::
|
||||
* Key-Value Policy::
|
||||
@end menu
|
||||
|
||||
|
||||
@node kvp_frame, kvp_value, Key-Value Pair Frames, Key-Value Pair Frames
|
||||
@node Key-Value Policy, kvp_frame, Key-Value Pair Frames, Key-Value Pair Frames
|
||||
@subsection Key-Value Policy
|
||||
@cindex Key-Value Policy
|
||||
|
||||
This section defines the policy that programmers should follow
|
||||
when using key-value pairs to store information. Because of the
|
||||
large amount of information which can potentially be stored using
|
||||
this mechanism, it is important to follow these guidelines so
|
||||
that order will be maintained.
|
||||
|
||||
The following rules should be followed for using key-value pairs:
|
||||
|
||||
@itemize
|
||||
|
||||
@item
|
||||
The document @file{src/engine/kvp_doc.txt} should be used to document the
|
||||
use of keys and values. Please consult this document before planning any
|
||||
use of new keys.
|
||||
|
||||
@item
|
||||
Key strings should be in all lower case with the '-' character
|
||||
separating words. If possible, use only alphanumeric characters and
|
||||
'-'. Example: @code{bank-info}. Because the '/' character is useful for
|
||||
describing keys in sub-frames (@code{bank-info/routing-number}), do not
|
||||
use the '/' character in key names.
|
||||
|
||||
@item
|
||||
Favor longer, descriptive key strings over short ones. Example:
|
||||
@code{online-banking-info} is better than @code{onln-bnk}.
|
||||
|
||||
@item
|
||||
Make use of the fact that frames can be stored in frames. If a group
|
||||
of keys are used for a related purpose, consider storing them together
|
||||
in a sub-frame.
|
||||
|
||||
@item
|
||||
Values should generally not be accessed directly through keys, but
|
||||
should rather be accessed through specific API calls. The API calls
|
||||
do not necessarily need to part a part of the Engine API. For example,
|
||||
the GUI would probably define keys that the Engine does not need to
|
||||
know about.
|
||||
|
||||
@item
|
||||
The same key should not be used for different engine structures (Accounts,
|
||||
Transactions, Splits), unless the key's value has the same type and the
|
||||
same basic purpose.
|
||||
|
||||
@end itemize
|
||||
|
||||
|
||||
@node kvp_frame, kvp_value, Key-Value Policy, Key-Value Pair Frames
|
||||
@subsection kvp_frame
|
||||
@tindex kvp_frame
|
||||
|
||||
@ -253,7 +364,7 @@ as appropriate.
|
||||
@end deftypefun
|
||||
|
||||
|
||||
@node kvp_list, Key-Value Policy, kvp_value, Key-Value Pair Frames
|
||||
@node kvp_list, , kvp_value, Key-Value Pair Frames
|
||||
@subsection kvp_list
|
||||
@tindex kvp_list
|
||||
|
||||
@ -296,46 +407,6 @@ the caller and should not be accessed after the function returns.
|
||||
@end deftypefun
|
||||
|
||||
|
||||
@node Key-Value Policy, , kvp_list, Key-Value Pair Frames
|
||||
@subsection Key-Value Policy
|
||||
@cindex Key-Value Policy
|
||||
|
||||
This section defines the policy that programmers should follow
|
||||
when using key-value pairs to store information. Because of the
|
||||
large amount of information which can potentially be stored using
|
||||
this mechanism, it is important to follow these guidelines so
|
||||
that order will be maintained.
|
||||
|
||||
The following rules should be followed for using key-value pairs:
|
||||
|
||||
@itemize
|
||||
|
||||
@item
|
||||
The document @file{src/engine/kvp_doc.txt} should be used to document
|
||||
the use of keys and values. Please consult this document before planning
|
||||
any use of new keys.
|
||||
|
||||
@item
|
||||
Key strings should be in all lower case with the '_' character
|
||||
separating words. If possible, use only alphanumeric characters
|
||||
and '_'. Example: @code{"bank_info"}
|
||||
|
||||
@item
|
||||
Favor longer, descriptive key strings over short ones. Example:
|
||||
@code{"online_banking_info"} is better than @code{"onln_bnk"}.
|
||||
|
||||
@item
|
||||
Make use of the fact that frames can be stored in frames. If a group
|
||||
of keys are used for a related purpose, consider storing them together
|
||||
in a sub-frame.
|
||||
|
||||
@item
|
||||
Values should generally not be accessed directly through keys, but
|
||||
should rather be accessed through specific API calls.
|
||||
|
||||
@end itemize
|
||||
|
||||
|
||||
@node Splits, Transactions, Key-Value Pair Frames, Engine
|
||||
@section Splits
|
||||
@tindex Split
|
||||
|
||||
@ -85,12 +85,16 @@ Engine
|
||||
* Account Groups::
|
||||
* Sessions::
|
||||
|
||||
Globally Unique Identifiers
|
||||
|
||||
* When to use GUIDs::
|
||||
|
||||
Key-Value Pair Frames
|
||||
|
||||
* Key-Value Policy::
|
||||
* kvp_frame::
|
||||
* kvp_value::
|
||||
* kvp_list::
|
||||
* Key-Value Policy::
|
||||
|
||||
Register
|
||||
|
||||
|
||||
@ -59,7 +59,8 @@ EXTRA_DIST = \
|
||||
.cvsignore \
|
||||
README.query-api \
|
||||
design.txt \
|
||||
extensions.txt
|
||||
extensions.txt \
|
||||
kvp_doc.txt
|
||||
|
||||
CFLAGS = @CFLAGS@ ${GLIB_CFLAGS} ${GUILE_COMPILE_ARGS}
|
||||
|
||||
|
||||
@ -131,7 +131,7 @@ libgncengine_la_LDFLAGS = -version-info 1:1:1
|
||||
noinst_HEADERS = AccInfo.h AccInfoP.h Account.h AccountP.h BackendP.h DateUtils.h FileIO.h FileIOP.h GNCId.h GNCIdP.h Group.h GroupP.h Query.h Queue.h Scrub.h Session.h TransLog.h Transaction.h TransactionP.h date.h gnc-common.h guid.h md5.h util.h kvp_frame.h
|
||||
|
||||
|
||||
EXTRA_DIST = .cvsignore README.query-api design.txt extensions.txt
|
||||
EXTRA_DIST = .cvsignore README.query-api design.txt extensions.txt kvp_doc.txt
|
||||
|
||||
|
||||
CFLAGS = @CFLAGS@ ${GLIB_CFLAGS} ${GUILE_COMPILE_ARGS}
|
||||
|
||||
58
src/engine/kvp_doc.txt
Normal file
58
src/engine/kvp_doc.txt
Normal file
@ -0,0 +1,58 @@
|
||||
This file documents the use of keys in the key-value pair system
|
||||
used by the Engine. Before assigning keys for use, please read
|
||||
the Key-Value Policy in the GnuCash Design Document located
|
||||
under src/doc/design.
|
||||
|
||||
The format of the data below is:
|
||||
|
||||
Name: The name of the key, including key names of parent frames
|
||||
with the parent frames listed first, as in a fully-qualified
|
||||
filename. Use the '/' character to separate keys.
|
||||
|
||||
Type: The type of value stored in the key. The types are listed in
|
||||
'kvp_frame.h'.
|
||||
|
||||
Entities: Which engine entities (Accounts, Transactions, Splits)
|
||||
can use this key. Use 'All' if every entity could have
|
||||
the key.
|
||||
|
||||
Use: The use to which the key will be put. Include any requirements
|
||||
for using the key here. Also include any API calls which use
|
||||
the key. If more than one entity can use the key,
|
||||
|
||||
|
||||
Example:
|
||||
|
||||
Name: my-favorite-thing
|
||||
Type: string
|
||||
Entities: Accounts
|
||||
Use: xaccGetMyFavoriteThing(), xaccSetMyFavoriteThing()
|
||||
This key stores a text description of the user's
|
||||
favorite thing. Do not use this key to store things
|
||||
which the user merely likes!
|
||||
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
|
||||
Name: user-keys
|
||||
Type: frame
|
||||
Entities: All
|
||||
Use: This frame is used to store keys which are editable directly by
|
||||
the user. The program should not attach any semantics to keys
|
||||
under this frame.
|
||||
|
||||
Name: old-price-source
|
||||
Type: string
|
||||
Entities: Account
|
||||
Use: This string holds the old Price Source code used by earlier versions
|
||||
of GnuCash and stored in the obsolete AccInfo structure. The use of
|
||||
this value will be deprecated when the new version of Finance::Quote
|
||||
is fully supported. The new version of Finance::Quote uses a different
|
||||
scheme to identify sources for price quotes.
|
||||
|
||||
Name: old-docref
|
||||
Type: string
|
||||
Entities: Transactions, Splits
|
||||
Use: This string holds the old Docref value which was supported in earlier
|
||||
versions of GnuCash but which was never used for any purpose. The
|
||||
value is retained in case any users were making use of it.
|
||||
@ -32,7 +32,6 @@ noinst_HEADERS = \
|
||||
|
||||
EXTRA_DIST = \
|
||||
.cvsignore \
|
||||
design.txt \
|
||||
table-html.c \
|
||||
table-html.h
|
||||
|
||||
|
||||
@ -123,7 +123,7 @@ libgncregister_a_SOURCES = QuickFill.c basiccell.c cellblock.c datecell
|
||||
noinst_HEADERS = QuickFill.h basiccell.h cellblock.h combocell.h datecell.h numcell.h pricecell.h quickfillcell.h recncell.h register-common.h splitreg.h table-allgui.h textcell.h
|
||||
|
||||
|
||||
EXTRA_DIST = .cvsignore design.txt table-html.c table-html.h
|
||||
EXTRA_DIST = .cvsignore table-html.c table-html.h
|
||||
|
||||
|
||||
CFLAGS = @CFLAGS@ ${GNOME_CFLAGS} ${GUILE_COMPILE_ARGS}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user