diff --git a/src/doc/design/engine.texinfo b/src/doc/design/engine.texinfo index de730516bb..76219790eb 100644 --- a/src/doc/design/engine.texinfo +++ b/src/doc/design/engine.texinfo @@ -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 diff --git a/src/doc/design/gnucash-design.texinfo b/src/doc/design/gnucash-design.texinfo index 372d14b240..9e1568f3a1 100644 --- a/src/doc/design/gnucash-design.texinfo +++ b/src/doc/design/gnucash-design.texinfo @@ -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 diff --git a/src/engine/Makefile.am b/src/engine/Makefile.am index 0d83a078e1..0665c268cf 100644 --- a/src/engine/Makefile.am +++ b/src/engine/Makefile.am @@ -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} diff --git a/src/engine/Makefile.in b/src/engine/Makefile.in index 7708ff5480..d69900d513 100644 --- a/src/engine/Makefile.in +++ b/src/engine/Makefile.in @@ -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} diff --git a/src/engine/kvp_doc.txt b/src/engine/kvp_doc.txt new file mode 100644 index 0000000000..3de6f5e0b7 --- /dev/null +++ b/src/engine/kvp_doc.txt @@ -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. diff --git a/src/register/Makefile.am b/src/register/Makefile.am index 908fd0cdd7..639c231da4 100644 --- a/src/register/Makefile.am +++ b/src/register/Makefile.am @@ -32,7 +32,6 @@ noinst_HEADERS = \ EXTRA_DIST = \ .cvsignore \ - design.txt \ table-html.c \ table-html.h diff --git a/src/register/Makefile.in b/src/register/Makefile.in index 9bcd2f6709..b48bce99ae 100644 --- a/src/register/Makefile.in +++ b/src/register/Makefile.in @@ -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}