From 9e3cdef1e953ad7d2ef5a6d7bb17b815c1b420fd Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 13 Feb 2019 15:51:39 -0800 Subject: [PATCH] lib: balance assertion docs (#290) [ci skip] --- hledger-lib/Hledger/Data/Types.hs | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/hledger-lib/Hledger/Data/Types.hs b/hledger-lib/Hledger/Data/Types.hs index 44680d1cd3a..5ea7fd5a4e9 100644 --- a/hledger-lib/Hledger/Data/Types.hs +++ b/hledger-lib/Hledger/Data/Types.hs @@ -239,9 +239,29 @@ instance Show Status where -- custom show.. bad idea.. don't do it.. -- | The amount to compare an account's balance to, to verify that the history -- leading to a given point is correct or to set the account to a known value. +-- +-- Different kinds of balance assertion (from #290): +-- +-- * simple assertions: single-commodity, non-total, subaccount-exclusive +-- assertions, as in Ledger (syntax: `=`). See definitions below. +-- +-- * subaccount-inclusive assertions: asserting the balance of an account +-- including all its subaccounts' balances. Not implemented, proposed by #290. +-- +-- * multicommodity assertions: writing multiple amounts separated by + to +-- assert a multicommodity balance, in a single assertion. Not implemented, +-- proposed by #934. In current hledger you can assert a multicommodity +-- balance by using multiple postings/assertions. But in either case, the +-- balance might contain additional unasserted commodities. To disallow that +-- you need... +-- +-- * total assertions: asserting that the balance is as written, with no extra +-- commodities in the account. Added by #902, with syntax `==`. I sometimes +-- wish this was the default behaviour, of `=`. +-- data BalanceAssertion = BalanceAssertion { - baamount :: Amount, -- ^ the expected value of a particular commodity - baexact :: Bool, -- ^ whether the assertion is exclusive, and doesn't allow other commodities alongside 'baamount' + baamount :: Amount, -- ^ the expected balance of a single commodity + baexact :: Bool, -- ^ whether the assertion is total, ie disallowing amounts in other commodities baposition :: GenericSourcePos } deriving (Eq,Typeable,Data,Generic,Show) @@ -256,7 +276,8 @@ data Posting = Posting { pcomment :: Text, -- ^ this posting's comment lines, as a single non-indented multi-line string ptype :: PostingType, ptags :: [Tag], -- ^ tag names and values, extracted from the comment - pbalanceassertion :: Maybe BalanceAssertion, -- ^ optional: the expected balance in this commodity in the account after this posting + pbalanceassertion :: Maybe BalanceAssertion, -- ^ an expected balance in the account after this posting, + -- in a single commodity, excluding subaccounts. ptransaction :: Maybe Transaction, -- ^ this posting's parent transaction (co-recursive types). -- Tying this knot gets tedious, Maybe makes it easier/optional. porigin :: Maybe Posting -- ^ When this posting has been transformed in some way