mirror of
https://github.com/Gnucash/gnucash.git
synced 2024-11-22 08:57:17 -06:00
39aa5f9c09
It's extremely out of date and we no longer use it to keep track of our design decisions and suggestions. Only a section on KVP policy has been move into kvp_doc.txt as it may make sense there.
664 lines
17 KiB
Plaintext
664 lines
17 KiB
Plaintext
/** \page kvpvalues KVP Values used By GnuCash
|
|
|
|
Date Last Revised: August 2003
|
|
|
|
API: \ref KVP
|
|
|
|
This file documents the use of keys in the key-value pair system
|
|
used by the GnuCash Application (both the engine, and non-engine, GUI
|
|
pieces).
|
|
|
|
\section kvppolicy KVP 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:
|
|
|
|
- This should be used to document the use of keys and values.
|
|
Please consult it before planning any use of new keys.
|
|
|
|
- Key strings should be in all lower case with the '-' character
|
|
separating words. If possible, use only alphanumeric characters and
|
|
'-'. Example: `bank-info`. Because the '/' character is useful for
|
|
describing keys in sub-frames (`bank-info/routing-number`), do not
|
|
use the '/' character in key names.
|
|
|
|
- Favor longer, descriptive key strings over short ones. Example:
|
|
`online-banking-info` is better than `onln-bnk`.
|
|
|
|
- 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.
|
|
|
|
- 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.
|
|
|
|
- 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.
|
|
|
|
\section kvpdocformat KVP Documentation format
|
|
|
|
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-value.hpp'.
|
|
|
|
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:
|
|
|
|
\verbatim
|
|
Name: /my-favorite-thing
|
|
Type: string
|
|
Entities: Account
|
|
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!
|
|
\endverbatim
|
|
|
|
Please put the keys in alphabetical order.
|
|
|
|
\section kvpvaluelist List of existing values
|
|
|
|
[ \ref kvpA ] [ \ref kvpB ] [ \ref kvpC ] [ \ref kvpD ] [ \ref kvpE ]
|
|
[ \ref kvpF ] [ \ref kvpG ] [ \ref kvpH ] [ \ref kvpJ ] [ \ref kvpK ] [ \ref kvpL ]\n
|
|
[ \ref kvpM ] [ \ref kvpN ] [ \ref kvpO ] [ \ref kvpP ] [ \ref kvpQ ]
|
|
[ \ref kvpR ] [ \ref kvpS ] [ \ref kvpT ] [ \ref kvpU ] [ \ref kvpV ] [ \ref kvpW ]
|
|
|
|
\subsection kvpA A
|
|
|
|
\subsection kvpB B
|
|
|
|
\verbatim
|
|
Name: /book/
|
|
Type: kvp_frame
|
|
Entities: Account, Book, Transaction
|
|
Use: kvp subdirectory holding info relating to accounting periods, including
|
|
the 'twin' of an open/closed account, pointers to the open-balance
|
|
transactions, the closing dates, etc.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/accounting-period
|
|
Type: string, enum {none, week, month, quarter, trimester, year}
|
|
XXX not used, should be UIFreqSpec stuff ..
|
|
Entities: Book
|
|
Use: An enumerated identifier indicating how often books are supposed
|
|
to be closed. This key will typically be present only in an
|
|
open book, as it seems meaningless in a closed book.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/close-date
|
|
Type: Time64
|
|
Entities: Book
|
|
Use: The posted closing date of this book. This book only contains
|
|
transactions whose posted date is earlier than this closing date.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/closed-acct
|
|
Type: GUID
|
|
Entities: Transaction
|
|
Use: The GUID of the account for which this transaction represents the
|
|
opening balance. This value will occur *only* in transactions that
|
|
are opening balances.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/closed-book
|
|
Type: GUID
|
|
Entities: Transaction
|
|
Use: The GUID of the book for which this transaction represents the
|
|
opening balance. This value will occur *only* in transactions that
|
|
are opening balances.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/log-date
|
|
Type: Time64
|
|
Entities: Book
|
|
Use: A log of the date which the user performed the closing of the book.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/next-acct
|
|
Type: GUID
|
|
Entities: Account
|
|
Use: The GUID of the account that follows this one, chronologically.
|
|
Note that the open-date of the next book should equal the close-date
|
|
of the book that this account belongs to.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/next-book
|
|
Type: GUID
|
|
Entities: Account, Book
|
|
Use: The GUID of the book that follows this one, chronologically.
|
|
Note that the open-date of the next book should equal the close-date
|
|
of this book.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/notes
|
|
Type: string
|
|
Entities: Book
|
|
Use: User-suplied notes for the book. The user can set this to any value
|
|
and change it at any time for any reason.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/open-date
|
|
Type: Time64
|
|
Entities: Book
|
|
Use: The posted opening date of this book. This book only contains transactions
|
|
whose posted date is later than this closing date.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/prev-acct
|
|
Type: GUID
|
|
Entities: Account
|
|
Use: The GUID of the account that precedes this one, chronologically.
|
|
Note that the close-date of the previous book should equal the open-date
|
|
of the book that this account belongs to.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/prev-book
|
|
Type: GUID
|
|
Entities: Account, Book
|
|
Use: The GUID of the book that precedes this one, chronologically.
|
|
Note that the close-date of the previous book should equal the open-date
|
|
of this book.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/title
|
|
Type: string
|
|
Entities: Book
|
|
Use: A user-suplied title for the book. The user can set this to any value
|
|
and change it at any time for any reason.
|
|
|
|
\endverbatim
|
|
|
|
\subsection kvpC C
|
|
|
|
\verbatim
|
|
Name: /counters/...
|
|
Type: int64
|
|
Entities: Book
|
|
Use: Holders for a bunch of counters for various types. Used specifically
|
|
in the business objects for ID counters. The counter name is the path
|
|
that follows /counters/, e.g. "/counters/GncCustomer"
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /counter_formats/...
|
|
Type: string
|
|
Entities: Book
|
|
Use: Holders for a bunch of counter formats for various types. Used
|
|
specifically in the business objects, to format a counter value
|
|
into a (string) ID. The counter name is the path that follows
|
|
/counter_formats/, e.g. "/counter_formats/GncCustomer"
|
|
|
|
These formats are printf-style format strings that contain exactly
|
|
one format specifier for an int64 (optionally preceded or followed
|
|
by arbitrary other strings).
|
|
\endverbatim
|
|
|
|
\subsection kvpD D
|
|
|
|
\subsection kvpE E
|
|
|
|
\subsection kvpF F
|
|
|
|
\verbatim
|
|
Name: /from-sched-xaction
|
|
Type: GUID
|
|
Entities: Transaction
|
|
Use: Identifies that the Transaction was created from a ScheduledTransaction,
|
|
and stores the GUID of that SX.
|
|
\endverbatim
|
|
|
|
\subsection kvpG G
|
|
|
|
\verbatim
|
|
Name: /gains-source
|
|
Type: guid
|
|
Entities: Split
|
|
Use: GUID of the split that is at the source of the cap gains recorded
|
|
in this split.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /gains-split
|
|
Type: guid
|
|
Entities: Split
|
|
Use: GUID of the split that records the capital gains for this split.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /gemini/
|
|
Type: kvp_glist
|
|
Entities: Account, Book
|
|
Use: kvp bag holding frames that identify accounts or books
|
|
that are copies of this account.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /gemini/.*
|
|
Type: kvp_frame
|
|
Entities: Account, Book
|
|
Use: bag value holds a frame that identifies a single copied account.
|
|
Other copies would appear in other bag values.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /gemini/<type>/acct_guid
|
|
Type: guid
|
|
Entities: Account
|
|
Use: guid of another account that is a copy of this one.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /gemini/<type>/book_guid
|
|
Type: guid
|
|
Entities: Account, Book
|
|
Use: When this appears in an account, then it contains the guid of
|
|
the book that the other account belongs to. When this appears
|
|
in a book, then this is the guid of the other book.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /gemini/<type>/date
|
|
Type: time64
|
|
Entities: Account, Book
|
|
Use: date that the copy was created.
|
|
\endverbatim
|
|
|
|
\subsection kvpH H
|
|
|
|
\verbatim
|
|
Name: /hbci/
|
|
Type: frame
|
|
Entities: Account, Book
|
|
Use: subdirectory for information related to the German online banking
|
|
protocol HBCI
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /hbci/account-id
|
|
Type: string
|
|
Entities: Account
|
|
Use: HBCI Account code of the HBCI counterpart of this gnucash account
|
|
in the real world
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /hbci/bank-code
|
|
Type: string
|
|
Entities: Account
|
|
Use: Bank code of HBCI account
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /hbci/country-code
|
|
Type: gint64
|
|
Entities: Account
|
|
Use: Country code of the bank of HBCI account
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /hbci/trans-retrieval
|
|
Type: Time64
|
|
Entities: Account
|
|
Use: Time of the last statement retrieval through HBCI for this
|
|
specific account
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /hbci/config-filename
|
|
Type: string
|
|
Entitied: Book
|
|
Use: OpenHBCI configuration file name, where the real HBCI
|
|
configuration for the OpenHBCI library can be found
|
|
\endverbatim
|
|
|
|
\subsection kvpJ J
|
|
|
|
\subsection kvpK K
|
|
|
|
\subsection kvpL L
|
|
|
|
\verbatim
|
|
Name: last-num
|
|
Type: string
|
|
Entities: Account
|
|
Use: xaccAccountGetLastNum, xaccAccountSetLastNum
|
|
Store the last number used in an account's transactions.
|
|
Used in auto-filling the Num field.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /lot-mgmt/
|
|
Type: kvp_frame
|
|
Entities: Account
|
|
Use: Frame holding info regarding how lots should be managed in this
|
|
account, including what accounting policy to use, where realized
|
|
gains should be reported, and etc.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /lot-mgmt/gains-acct/
|
|
Type: frame
|
|
Entities: Account
|
|
Use: When a lot in this account is double-balanced, this frame
|
|
holds per-currency accounts to which realized gains are to
|
|
be posted.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /lot-mgmt/gains-acct/xxxxx
|
|
Type: guid
|
|
Entities: Account
|
|
Use: When a lot in this account is double-balanced, this key specifies
|
|
the account to which realized gains are to be posted.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /lot-mgmt/next-id
|
|
Type: int64
|
|
Entities: Account
|
|
Use: The next unused lot id number, used to autogenerate
|
|
a lot title.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /lot-split/
|
|
Type: kvp_glist
|
|
Entities: Split
|
|
Use: A bag of kvp frames holding identification of splits
|
|
that were split off of this split. Same style as the
|
|
/gemini/, look there for additional doco's.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /lot-split/<type>/peer_guid
|
|
Type: GUID
|
|
Entities: Split
|
|
Use: The GUID of the peer split which was split from this split.
|
|
\endverbatim
|
|
|
|
\subsection kvpM M
|
|
|
|
\subsection kvpN N
|
|
|
|
\verbatim
|
|
Name: /notes
|
|
Type: string
|
|
Entities: Account, Lot, Transaction
|
|
Use: A user-suplied 'Notes' text field. The user can set this to
|
|
any value and change it at any time for any reason.
|
|
Accessors: xaccAccountGetNotes(), xaccAccountSetNotes(),
|
|
xaccTransGetNotes(), xaccTransSetNotes()
|
|
\endverbatim
|
|
|
|
\subsection kvpO O
|
|
|
|
\verbatim
|
|
Name: old-currency
|
|
Type: string
|
|
Entities: Account
|
|
Use: This string holds the canonical name of the old Account
|
|
currency. This may be deleted at some point in the future.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: old-currency-scu
|
|
Type: gint64
|
|
Entities: Account
|
|
Use: This holds the old currency scu. This may be deleted at
|
|
some point in the future.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
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.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
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.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: old-security
|
|
Type: string
|
|
Entities: Account
|
|
Use: This string holds the canonical name of the old Account
|
|
security. This may be deleted at some point in the future.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: old-security-scu
|
|
Type: gint64
|
|
Entities: Account
|
|
Use: This holds the old security scu. This may be deleted at
|
|
some point in the future.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: online-id
|
|
Type: string
|
|
Entities: All
|
|
Use: This holds a unique identifier for accounts, transactions and splits
|
|
created by the generic import layer. This allows imports of
|
|
successive statements to automatically match accounts and transactions
|
|
which have already been imported.
|
|
|
|
This used to be set on transactions but not splits. It is now set on
|
|
splits but not transactions. It is still checked on transactions, but
|
|
this may change at some point in the future.
|
|
|
|
\subsection kvpP P
|
|
|
|
\subsection kvpQ Q
|
|
|
|
\subsection kvpR R
|
|
|
|
\verbatim
|
|
Name: /reconcile-info/
|
|
Type: frame
|
|
Entities: Account
|
|
Use: store reconcile information about accounts
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /reconcile-info/include-children
|
|
Type: gint64
|
|
Entities: Account
|
|
Use: A boolean flag indicating whether transactions in sub-accounts should be
|
|
included during reconcilition.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /reconcile-info/last-date
|
|
Type: frame
|
|
Entities: Account
|
|
Use: store the statement date of the last reconciliation
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /reconcile-info/postpone/date
|
|
Type: gint64
|
|
Entities: Account
|
|
Use: store the ending statement date of a postponed reconciliation
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /reconcile-info/postpone/balance
|
|
Type: numeric
|
|
Entities: Account
|
|
Use: store the ending balance of a postponed reconciliation
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /reconcile-info/auto-interest-transfer
|
|
Type: string
|
|
Entities: Account
|
|
Use: allows the user to override the global reconcile option
|
|
"Automatic interest transfer" on a per-account basis.
|
|
Acceptable values are "true" and "false".
|
|
(This really could use a KVP_TYPE_BOOLEAN.)
|
|
\endverbatim
|
|
|
|
\subsection kvpS S
|
|
|
|
\verbatim
|
|
Name: /sched-xaction/
|
|
Type: frame
|
|
Entities: Split in a SchedXaction
|
|
Use: Storage for the various fields of a scheduled transaction's
|
|
template Splits.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /sched-xaction/account
|
|
Type: GUID
|
|
Entities: Split associated with a SchedXaction
|
|
Use: The GUID of this Split's xfrm account.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /sched-xaction/credit-formula
|
|
Type: string
|
|
Entities: Split associated with a SchedXaction
|
|
Use: Store the formula for the credit side of the split
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /sched-xaction/debit-formula
|
|
Type: string
|
|
Entities: Split associated with a SchedXaction
|
|
Use: Formula for the debit. Either the credit or the
|
|
debit formula must be empty.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: split-type
|
|
Entities: Split
|
|
Use: xaccSplitGetType, xaccSplitMakeStockSplit
|
|
Store a string representing the type of split, if not normal.
|
|
\endverbatim
|
|
|
|
\subsection kvpT T
|
|
|
|
\verbatim
|
|
Name: /tax-US/code
|
|
Type: string
|
|
Entities: Account
|
|
Use: see src/scm/report/[tax,txf]*.scm
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /tax-US/payer-name-source
|
|
Type: string
|
|
Entities: Account
|
|
Use: see src/scm/report/[tax,txf]*.scm
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: tax-related
|
|
Type: gint64
|
|
Entities: Account
|
|
Use: A boolean flag indicated whether the Account is tax-related.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /title
|
|
Type: string
|
|
Entities: Lot
|
|
Use: A user-supplied title for the lot. The user can set this to
|
|
any value and change it at any time for any reason.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: trans-date-due
|
|
Type: Time64
|
|
Entities: Transaction
|
|
Use: Accounts/Receivable, Accounts/Payable Due Date.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: trans-txn-type
|
|
Type: string
|
|
Entities: Transaction
|
|
Use: A/R, A/P Transaction Type (Invoice or Payment)
|
|
\endverbatim
|
|
|
|
\subsection kvpU U
|
|
|
|
\verbatim
|
|
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.
|
|
\endverbatim
|
|
|
|
\subsection kvpV V
|
|
|
|
\verbatim
|
|
Name: void-reason
|
|
Type: string
|
|
Entities: Transaction
|
|
Use: This string is used to store the reason why a transaction has been
|
|
voided. Note that it should only exist if the transaction has been voided.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: void-former-amount
|
|
Type: gnc_numeric
|
|
Entities: Split
|
|
Use: To store the amount of the this split before it was voided. Note
|
|
that it should only exist if the parent transaction has been voided (but
|
|
checking the reconcile status of the split is a more direct way of finding
|
|
out a split has been voided).
|
|
\endverbatim
|
|
|
|
\subsection kvpW W
|
|
*/
|
|
|
|
--------------------------- end of document ------------------------
|